rom/usb/docs/usbclass.doc

   1 TABLE OF CONTENTS
   2
   3 usbclass/--background--
   4 usbclass/usbAttemptDeviceBinding
   5 usbclass/usbAttemptInterfaceBinding
   6 usbclass/usbDoMethod
   7 usbclass/usbForceDeviceBinding
   8 usbclass/usbForceInterfaceBinding
   9 usbclass/usbGetAttrs
  10 usbclass/usbReleaseDeviceBinding
  11 usbclass/usbReleaseInterfaceBinding
  12 usbclass/usbSetAttrs
  13
  14
  15 \fusbclass/--background--                               usbclass/--background--
  16
  17    PURPOSE
  18         USB classes in the sense of the Poseidon stack environment, are
  19         libraries that provide functionality for USB devices. They interface
  20         to the poseidon.library via its function vectors and are called
  21         whenever a new device is found.
  22
  23         This document is dated to 11-May-03 19:24:05.
  24
  25    OVERVIEW
  26         Each class will be offered the interface or device descriptor of every
  27         device not yet having a binding. If the class 'knows' the type of the
  28         device and is able to communicate with it, it tells back the Poseidon
  29         stack that it wants to use it. There are two types of bindings: device
  30         bindings, that take over control of the whole device, and interface
  31         bindings, that only use the endpoints of a particular interface,
  32         sharing the (compound) device with other classes that bind to other
  33         interfaces.
  34
  35         Bindings are exclusive. No class can bind to an interface already
  36         claimed by someone else. Also, no device binding will be allowed, if
  37         there are interface bindings to that device and vice versa. A class
  38         normally only needs to implement either interface or device bindings.
  39
  40         A class may only claim bindings it is SURE to understand. Otherwise
  41         another class will not be able to add its functionality.
  42
  43         There is an option for the user to force a binding to a device or
  44         interface. This makes sense, if it is a vendor specific driver and
  45         likely to by supported by some yet unknown device which a similar
  46         chipset. Support for forced bindings is optional -- a class driver
  47         may still refuse to bind to the device or interface, if it is not
  48         compatible.
  49
  50         The device or interface structure, as well as any other structures of
  51         the Poseidon stack are private, except for they all contain a Node
  52         structure for linking. Do NOT assume any data layout as it might
  53         change. To get or set attributes, use the psdGetAttrs() and
  54         psdSetAttrs() function of the poseidon.library.
  55
  56         A class driver should spawn a subtask for each instance of the
  57         functionality added. For example, as there can be as many mice on the
  58         USB as the users connects, there will be multiple instances of the
  59         bootmouse.class tasks running.
  60
  61         Whenever the device gets removed, the poseidon.library will ask you
  62         to remove your binding to it and you will properly behave and release
  63         the binding. Note that your library does not need to free all your
  64         resources on this operation. This allows you suspend your
  65         functionality and return it, when the device gets plugged in again.
  66         For example, the printer.class keeps the information about every
  67         printer connected and maps it back to the same unit number whenever it
  68         is reconnected. The data is only freed on the expunge of the class.
  69
  70         Classes communicate with the USB devices via pipes. Have a look at the
  71         poseidon.library AutoDocs.
  72
  73         It is a preferred method only to open the poseidon.library when
  74         required (i.e. inside the attempt/release binding vectors, or inside
  75         the subtask). This allows the stack to expunge itself when it is no
  76         longer needed, taking down the class libraries aswell.
  77
  78         With some newer releases of Poseidon, some functionality has been
  79         added. This includes the usbSetAttrs() and usbGetAttrs() function,
  80         aswell as the usbDoMethod() call. These allow some querying of classes
  81         and their state as well as easier extension without breaking
  82         compatibility with newer versions of the main library.
  83
  84         All class drivers can have their own global configuration and/or
  85         interface or device preferences. It is recommended that if such prefs
  86         exist, a nice GUI should be available to the end user. If interface
  87         or device prefs exist, the ability to change default prefs for these
  88         should be available through the global configuration. Common prefs
  89         handling is supported by the poseidon.library.
  90
  91         Class drivers should be stored in SYS:Classes/USB.
  92
  93    WARNING
  94         The class library interface is PRELIMINARY! It WILL be expanded and
  95         more features WILL be added. If you write your class libraries, be
  96         sure to use version 1. Newer versions of poseidon then will probably
  97         ask for version 2 or higher class library versions, if the interface
  98         is not compatible anymore (or more functions are required).
  99
 100         If you have good ideas on expanding the API, please let me know.
 101
 102
 103 \fusbclass/usbAttemptDeviceBinding             usbclass/usbAttemptDeviceBinding
 104
 105    NAME
 106         usbAttemptDeviceBinding -- establish device binding if possible
 107
 108    SYNOPSIS
 109         udb = usbAttemptDeviceBinding(pd);
 110         D0                            A0
 111
 112         APTR usbAttemptDeviceBinding(APTR);
 113
 114    FUNCTION
 115         The class gets a device structure from the Poseidon stack. It may
 116         then examine it further (using psdGetAttrs()) to decide, if it wants
 117         to use it. In this case, this function returns the pointer to a
 118         private context structure which will not be touched by Poseidon, but
 119         used for the usbReleaseDeviceBinding() call whenever the stack
 120         wants go get rid of the instance.
 121
 122         You can go down the device, traverse its configurations, interfaces
 123         and endpoints by hand. Just read out the structure data using
 124         psdGetAttrs().
 125
 126    NOTE
 127         When establishing a device binding, you are allowed to do anything
 128         you like with the device, including switching configurations and
 129         changing to alternative settings on the interfaces.
 130
 131         However, if it is possible for that kind of device to have multiple
 132         interfaces of which you will not use, but some other class could,
 133         do not use device bindings, but interface bindings.
 134
 135    INPUTS
 136         pd - pointer to a Poseidon device structure (private).
 137
 138    RESULT
 139         udb - private pointer of the binding context or NULL, if no binding
 140               could be established.
 141
 142    SEE ALSO
 143         usbReleaseDeviceBinding(), usbForceDeviceBinding()
 144
 145
 146 \fusbclass/usbAttemptInterfaceBinding       usbclass/usbAttemptInterfaceBinding
 147
 148    NAME
 149         usbAttemptInterfaceBinding -- establish interface binding if possible
 150
 151    SYNOPSIS
 152         uifb = usbAttemptInterfaceBinding(pif);
 153         D0                                A0
 154
 155         APTR usbAttemptInterfaceBinding(APTR);
 156
 157    FUNCTION
 158         The class gets an interface structure from the Poseidon stack. It may
 159         then examine it further (using psdGetAttrs()) to decide, if it wants
 160         to use it. In this case, this function returns the pointer to a
 161         private context structure which will not be touched by Poseidon, but
 162         used for the usbReleaseInterfaceBinding() call whenever the stack
 163         wants go get rid of the instance.
 164
 165         Note that all structures have uplinking data, i.e. you can climb up
 166         to the device structure via the interface IFA_Config and then
 167         CA_Device tag to get the ProductID and other information available.
 168
 169    NOTE
 170         When establishing an interface binding, you are allowed to check for
 171         alternate settings. If you decide to use some other setting, use
 172         the psdSetAltInterface() call.
 173
 174         You may not change the configuration number using
 175         psdSetDeviceConfig() as you only own the given interface and not the
 176         whole device.
 177
 178    INPUTS
 179         pif - pointer to a Poseidon interface structure (private).
 180
 181    RESULT
 182         uifb - private pointer of the binding context or NULL, if no binding
 183                could be established.
 184
 185    SEE ALSO
 186         usbReleaseInterfaceBinding(), usbForceInterfaceBinding()
 187
 188
 189 \fusbclass/usbDoMethod                                     usbclass/usbDoMethod
 190
 191    NAME
 192         usbDoMethodA -- perform a class function
 193         usbDoMethod -- varargs stub for usbDoMethodA
 194
 195    SYNOPSIS
 196         result = usbDoMethodA(methodid, methodddata);
 197         D0                    D0        A1
 198
 199         LONG usbDoMethodA(ULONG, APTR);
 200
 201         result = usbDoMethod(methodid, ...);
 202
 203         LONG usbDoMethod(ULONG, ...);
 204
 205    FUNCTION
 206         Similar to the DoMethod() function of amiga.lib. Performs a class
 207         function and returns its results.
 208
 209    METHODS
 210         UCM_AttemptInterfaceBinding
 211
 212             APTR uifb = usbDoMethod(UCM_AttemptInterfaceBinding, APTR pif);
 213
 214             Does the same as the old vector usbAttemptInterfaceBinding().
 215             For compatibility, both should be implemented. The first and only
 216             parameter contains the interface pointer. The result is the
 217             private binding pointer or NULL, if no binding could be
 218             established.
 219
 220         UCM_ForceInterfaceBinding
 221
 222             APTR uifb = usbDoMethod(UCM_ForceInterfaceBinding, APTR pif);
 223
 224             Does the same as the old vector usbForceInterfaceBinding().
 225             For compatibility, both should be implemented. The first and only
 226             parameter contains the interface pointer. The result is the
 227             private binding pointer or NULL, if no binding could be
 228             established.
 229
 230         UCM_ReleaseInterfaceBinding
 231
 232             void usbDoMethod(UCM_ReleaseInterfaceBinding, APTR uifb);
 233
 234             Does the same as the old vector usbReleaseInterfaceBinding().
 235             For compatibility, both should be implemented. The first and only
 236             parameter contains the private binding pointer returned by
 237             UCM_AttemptInterfaceBinding or UCM_ForceInterfaceBinding.
 238
 239         UCM_AttemptDeviceBinding
 240
 241             APTR udb = usbDoMethod(UCM_AttemptDeviceBinding, APTR pd);
 242
 243             Does the same as the old vector usbAttemptDeviceBinding().
 244             For compatibility, both should be implemented. The first and only
 245             parameter contains the device pointer. The result is the class
 246             private pointer to the device binding or NULL, if no binding could
 247             be established.
 248
 249         UCM_ForceDeviceBinding
 250
 251             APTR udb = usbDoMethod(UCM_ForceDeviceBinding, APTR pd);
 252
 253             Does the same as the old vector usbForceDeviceBinding().
 254             For compatibility, both should be implemented. The first and only
 255             parameter contains the device pointer. The result is the class
 256             private pointer to the device binding or NULL, if no binding could
 257             be established.
 258
 259         UCM_ReleaseDeviceBinding
 260
 261             void usbDoMethod(UCM_ReleaseDeviceBinding, APTR udb);
 262
 263             Does the same as the old vector usbReleaseDeviceBinding().
 264             For compatibility, both should be implemented. The first and only
 265             parameter contains the private binding pointer returned by
 266             UCM_AttemptDeviceBinding or UCM_ForceDeviceBinding.
 267
 268         UCM_OpenCfgWindow
 269
 270             BOOL good = usbDoMethod(UCM_OpenCfgWindow);
 271
 272             If the class has a global configuration GUI, it should be opened
 273             by a call to UCM_OpenCfgWindow. There are no parameters.
 274
 275             If your class does not provide a global GUI, return FALSE.
 276             Otherwise, return TRUE.
 277
 278             Take care that the GUI window has to be started asynchroneously
 279             and may not block. Also, ensure that your window does not get
 280             opened twice, if it is already open. Please be so nice and allow
 281             the window to be closed at any time -- either by the user or
 282             by UCM_CloseCfgWindow. If your global prefs relies on existing
 283             bindings, make sure that it copes with them going away at any
 284             time (through the known release calls).
 285
 286             It is recommended that you inject the prefs to the main Poseidon
 287             prefs structure at the closure of the window.
 288
 289         UCM_CloseCfgWindow
 290
 291             void usbDoMethod(UCM_CloseCfgWindow);
 292
 293             This method requests the GUI to be closed. The class may or may
 294             not obey to this.
 295
 296         UCM_OpenBindingCfgWindow
 297
 298             BOOL good = usbDoMethod(UCM_OpenBindingCfgWindow, APTR ub);
 299
 300             If the class has a binding configuration GUI, it should be opened
 301             by a call to UCM_OpenBindingCfgWindow. The parameter specifies,
 302             which binding should be used and is a the private pointer to the
 303             binding structure the class uses itself. This may either be a
 304             device or interface binding structure.
 305
 306             If your class does not provide a binding configuration GUI,
 307             return FALSE. Otherwise, return TRUE.
 308
 309             Take care that the GUI window has to be started asynchroneously
 310             and may not block. Also, ensure that your window does not get
 311             opened twice, if it is already open. Please be so nice and allow
 312             the window to be closed at any time -- either by the user or
 313             by UCM_CloseBindingCfgWindow. If there are default settings and
 314             no binding config has been generated yet, it should initially use
 315             the default settings for the binding prefs. Make sure that the
 316             prefs task copes the binding going away at any time (through the
 317             known release calls).
 318
 319             Please remember that multiple windows for seperate binding prefs
 320             should be supported.
 321
 322         UCM_CloseBindingCfgWindow
 323
 324             void usbDoMethod(UCM_CloseBindingCfgWindow);
 325
 326             This method requests the GUI window for the binding settings to
 327             be closed. The class may or may not obey to this.
 328
 329    NOTE
 330         The list of methods may grow in future.
 331
 332    INPUTS
 333         methodid - numeric method id a specific in libraries/usbclass.h
 334         methoddata - the message packet to send according to the method id
 335
 336    RESULT
 337         result - result of the method called.
 338
 339    SEE ALSO
 340         usbGetAttrs(), usbSetAttrs()
 341
 342
 343 \fusbclass/usbForceDeviceBinding                 usbclass/usbForceDeviceBinding
 344
 345    NAME
 346         usbForceDeviceBinding -- force device binding if possible
 347
 348    SYNOPSIS
 349         udb = usbForceDeviceBinding(pd);
 350         D0                          A0
 351
 352         APTR usbForceDeviceBinding(APTR);
 353
 354    FUNCTION
 355         This call is very similar to usbAttemptDeviceBinding(), except that it
 356         should do a best attempt to build up a binding, even if it does not
 357         know, if the device is compatible or supported. This allows expert
 358         users to try to get devices to work that normally would not bind
 359         automatically, because the class does not know about it.
 360
 361         Still, even usbForceDeviceBinding() may fail, e.g. if the device does
 362         not meet the requirements (interfaces, endpoints) or does not respond
 363         properly to the expected protocol.
 364
 365         See usbAttemptDeviceBinding() for details.
 366
 367    NOTE
 368         It is recommended that usbAttemptDeviceBinding() only does some
 369         pre-checking and then calls usbForceDeviceBinding() internally.
 370
 371    INPUTS
 372         pd - pointer to a Poseidon device structure (private).
 373
 374    RESULT
 375         udb - private pointer of the binding context or NULL, if no binding
 376               could be established.
 377
 378    SEE ALSO
 379         usbAttemptDeviceBinding(), usbReleaseDeviceBinding()
 380
 381
 382 \fusbclass/usbForceInterfaceBinding           usbclass/usbForceInterfaceBinding
 383
 384    NAME
 385         usbForceInterfaceBinding -- force interface binding if possible
 386
 387    SYNOPSIS
 388         uifb = usbForceInterfaceBinding(pif);
 389         D0                              A0
 390
 391         APTR usbForceInterfaceBinding(APTR);
 392
 393    FUNCTION
 394         This call is very similar to usbAttemptInterfaceBinding(), except that
 395         it should do a best attempt to build up a binding, even if it does not
 396         know, if the device is compatible or supported. This allows expert
 397         users to try to get interfaces to work that normally would not bind
 398         automatically, because the class does not know about it.
 399
 400         Still, even usbForceInterfaceBinding() may fail, e.g. if the device
 401         does not meet the requirements (e.g. endpoints) or does not respond
 402         properly to the expected protocol.
 403
 404         See usbAttemptInterfaceBinding() for details.
 405
 406    NOTE
 407         It is recommended that usbAttemptInterfaceBinding() only does some
 408         pre-checking and then calls usbForceInterfaceBinding() internally.
 409
 410    INPUTS
 411         pif - pointer to a Poseidon interface structure (private).
 412
 413    RESULT
 414         uifb - private pointer of the binding context or NULL, if no binding
 415                could be established.
 416
 417    SEE ALSO
 418         usbAttemptInterfaceBinding(), usbReleaseInterfaceBinding()
 419
 420
 421 \fusbclass/usbGetAttrs                                     usbclass/usbGetAttrs
 422
 423    NAME
 424         usbGetAttrsA -- get information from an internal class structure
 425         usbGetAttrs -- varargs stub for usbGetAttrsA()
 426
 427    SYNOPSIS
 428         num = usbGetAttrsA(type, usbstruct, taglist);
 429         D0                 D0    A0         A1
 430
 431         LONG usbGetAttrsA(ULONG, APTR, struct TagList *);
 432
 433         num = usbGetAttrs(type, usbstruct, tag1, ...);
 434
 435         LONG usbGetAttrs(ULONG, APTR, Tag, ...);
 436
 437    FUNCTION
 438         Acquires attribute information from an internal class structure,
 439         according to the attributes chosen in the tag list. For each entry in
 440         the tag list, ti_Tag identifies the attribute and ti_Data is a pointer
 441         to the long variable where you wish the result to be stored.
 442
 443         There are currently a number of thee different system structures which
 444         can be accessed in this way. To avoid adding multiple functions with
 445         the same semantics, usbGetAttrs() requires the type of the structure
 446         passed.
 447
 448    INPUTS
 449         type - describes the type of the structure passed.
 450                See libraries/usbclass.h for details.
 451         usbstruct - pointer to the system structure on which information
 452                     should be gathered. Can be NULL only for UGA_CLASS.
 453         taglist - pointer to TagItem list, terminated by TAG_END.
 454
 455    TAGS
 456         All tags are read-only, except stated otherwise.
 457
 458         UGA_CLASS: (read-only)
 459         UCCA_Priority (LONG) - Priority for the class scan. Valid inputs are
 460             between -128 and 127. The higher the priority, the earlier the
 461             class gets to attempt a binding. This is important if different
 462             classes lock to the same interfaces or devices, but have varying
 463             degree of functionality and availability (e.g. hid.class versus
 464             bootmouse.class or bootkeyboard.class).
 465         UCCA_Description (STRPTR) - String to display in Trident, describing
 466             the basic features and intention of the class.
 467         UCCA_HasClassCfgGUI (BOOL) - Returns TRUE, if the class has a global
 468             prefs window, or FALSE otherwise.
 469         UCCA_HasBindingCfgGUI (BOOL) - Returns TRUE, if the class implements
 470             a GUI for seperate bindings. If it does not have this feature,
 471             it retuns FALSE.
 472         UCCA_AfterDOSRestart (BOOL) - Returns TRUE, if the class needs to
 473             be restarted (i.e. all bindings closed and reopened), after DOS
 474             has been available. This only applies to classes that are
 475             available while booting and don't need the dos.library, but would
 476             benefit from its existance later on.
 477
 478         UCBA_BINDING:
 479         no tags yet defined
 480
 481         UCFA_CONFIG:
 482         no tags yet defined
 483
 484    RESULT
 485         num - number of tags actually read or -1, if the request was not
 486               supported somehow.
 487
 488    SEE ALSO
 489         psdSetAttrs(), psdNumToStr()
 490
 491
 492 \fusbclass/usbReleaseDeviceBinding   usbclass/usbReleaseDeviceBinding
 493
 494    NAME
 495         usbReleaseDeviceBinding -- release a previously bound device
 496
 497    SYNOPSIS
 498         usbReleaseDeviceBinding(udb);
 499                                 A0
 500
 501         void usbReleaseDeviceBinding(APTR);
 502
 503    FUNCTION
 504         If this function is called, Poseidon wants to release an established
 505         device binding. The class MUST release the device and stop all further
 506         transactions to it. After you've returned from this call, the whole
 507         device you were talking to might be gone.
 508
 509    WARNING
 510         Read the last sentence: Everything you ever owned of the device, is
 511         not available anymore after you have returned from that call. Do NOT
 512         attempt to read out structures you might have got before. Do NOT
 513         try to send pipe transfers anymore.
 514
 515         Normally, this call terminates the subtask created and frees the
 516         context allocated for the instance. This call should not take too
 517         long to terminate, especially, it MAY NOT WAIT for certain
 518         application level action (like closing of a device in use).
 519
 520    INPUTS
 521         udb - private pointer of the binding context.
 522
 523    SEE ALSO
 524         usbAttemptDeviceBinding()
 525
 526
 527 \fusbclass/usbReleaseInterfaceBinding       usbclass/usbReleaseInterfaceBinding
 528
 529    NAME
 530         usbReleaseInterfaceBinding -- release a previously bound interface
 531
 532    SYNOPSIS
 533         usbReleaseInterfaceBinding(uifb);
 534                                    A0
 535
 536         void usbReleaseInterfaceBinding(APTR);
 537
 538    FUNCTION
 539         If this function is called, Poseidon wants to release an established
 540         binding. The class MUST release the interface and stop all further
 541         transactions to it. After you've returned from this call, the
 542         interface and possibly the whole device you were talking to might be
 543         gone.
 544
 545    WARNING
 546         Read the last sentence: Everything you ever owned of the device, is
 547         not available anymore after you have returned from that call. Do NOT
 548         attempt to read out structures you might have got before. Do NOT
 549         try to send pipe transfers anymore.
 550
 551         Normally, this call terminates the subtask created and frees the
 552         context allocated for the instance. This call should not take too
 553         long to terminate, especially, it MAY NOT WAIT for certain
 554         application level action (like closing of a device in use).
 555
 556    INPUTS
 557         uifb - private pointer of the binding context.
 558
 559    SEE ALSO
 560         usbAttemptInterfaceBinding()
 561
 562
 563 \fusbclass/usbSetAttrs                                     usbclass/usbSetAttrs
 564
 565    NAME
 566         usbSetAttrsA -- change fields of an internal class structure
 567         usbSetAttrs -- varargs stub for usbSetAttrsA()
 568
 569    SYNOPSIS
 570         num = usbSetAttrsA(type, usbstruct, taglist);
 571         D0                 D0    A0         A1
 572
 573         LONG usbSetAttrsA(ULONG, APTR, struct TagList *);
 574
 575         num = usbSetAttrs(type, usbstruct, tag1, ...);
 576
 577         LONG usbSetAttrs(ULONG, APTR, Tag, ...);
 578
 579    FUNCTION
 580         Changes the fields allowed to be written of an internal class
 581         structure according to the attributes chosen in the tag list. For
 582         each entry in the tag list, ti_Tag identifies the attribute and
 583         ti_Data is the long data you wish to change the value to.
 584
 585         There are currently a number of three different system structures
 586         which can be accessed in this way. To avoid adding multiple functions
 587         with the same semantics, usbSetAttrs() requires the type of the
 588         structure passed.
 589
 590    INPUTS
 591         type - describes the type of the structure passed.
 592                See libraries/usbclass.h for details.
 593         usbstruct - pointer to the system structure on which information
 594                     should be changed. Can be NULL only for UGA_CLASS.
 595         taglist - pointer to TagItem list, terminated by TAG_END.
 596
 597    TAGS
 598         See usbGetAttrs() for the tags which can be changed.
 599
 600    RESULT
 601         num - number of tags actually read or -1, if the request was not
 602               supported somehow.
 603
 604    SEE ALSO
 605         usbGetAttrs()
 606
 607