QNX Momentics DDK. Universal Serial Bus (USB) Devices. For QNX Neutrino or QNX , QNX Software Systems Ltd.

Transcription

1 QNX Momentics DDK Universal Serial Bus (USB) Devices For QNX Neutrino or QNX , QNX Software Systems Ltd.

2 QNX Software Systems Ltd. 175 Terence Matthews Crescent Kanata, Ontario K2M 1W8 Canada Voice: Fax: Web: , QNX Software Systems Ltd. All rights reserved. Publishing history Technical support options To obtain technical support for any QNX product, visit the Technical Support section in the Services area on our website ( You ll find a wide range of support options, including our free web-based Developer Support Center. QNX, Momentics, Neutrino, and Photon are registered trademarks of QNX Software Systems Ltd. All other trademarks and registered trademarks belong to their respective owners.

3 Contents About the USB DDK Assumptions ix Building DDKs x vii Before You Begin 1 System requirements 3 For QNX Neutrino For QNX 4 3 USB devices supported 3 Known limitations 4 EHCI 4 Photon and text mode 4 DDK source code 5 Overview 7 The USB stack and library 9 Host Controller Interface (HCI) types 9 Data buffers 9 USB enumerator 10 How a class driver works 10 USB Utilities 13 USB Library Reference 17 Functions arranged by category 19 May 31, 2004 Contents iii

4 2004, QNX Software Systems Ltd. Connection functions 19 Memory-management functions 19 I/O functions 20 Pipe-management functions 20 Configuration/ interface functions 21 Miscellaneous/ convenience functions 21 usbd abort pipe() 23 usbd alloc() 24 usbd alloc urb() 26 usbd args lookup() 28 usbd attach() 29 usbd close pipe() 32 usbd configuration descriptor() 33 usbd connect() 35 usbd descriptor() 40 usbd detach() 42 usbd device descriptor() 44 usbd device extra() 46 usbd device lookup() 47 usbd disconnect() 48 usbd endpoint descriptor() 50 usbd feature() 52 usbd free() 54 usbd free urb() 55 usbd get frame() 56 usbd hcd info() 58 usbd hub descriptor() 60 usbd interface descriptor() 62 usbd io() 64 usbd languages descriptor() 66 usbd mphys() 68 usbd open pipe() 69 iv Contents May 31, 2004

5 2004, QNX Software Systems Ltd. usbd parse descriptors() 71 usbd pipe device() 74 usbd pipe endpoint() 75 usbd reset device() 76 usbd reset pipe() 77 usbd select config() 78 usbd select interface() 80 usbd setup bulk() 82 usbd setup control() 84 usbd setup interrupt() 86 usbd setup isochronous() 88 usbd setup vendor() 90 usbd status() 92 usbd string() 94 usbd topology() 96 usbd urb status() 98 Index 101 May 31, 2004 Contents v

6

7 About the USB DDK May 31, 2004 About the USB DDK vii

8

9 2004, QNX Software Systems Ltd. Assumptions Our USB API is designed to work with either QNX Neutrino or QNX 4. Exceptions will be noted where appropriate. This guide is organized into these main parts: ffl ffl ffl ffl a read-this-first page indicating your system requirements and other vital information you should know before you begin an overview describing how the OS supports USB command-line utilities a set of function pages describing the USB driver interface calls The USB SDK includes source code for several USB class drivers. Each class driver is contained in its own separate archive. Look under the /ddk working dir/usb/src/hardware/devu/class directory on your system. Assumptions We assume you re familiar with the Universal Serial Bus (USB) Specification revision 2.0, especially the chapters on: ffl ffl ffl ffl Architectural Overview USB Data Flow Model USB Device Framework USB Host: Hardware and Software. You ll need a good understanding of the concepts in those chapters in order to write USB client device drivers. May 31, 2004 About the USB DDK ix

10 Building DDKs 2004, QNX Software Systems Ltd. For up-to-date information on USB developments, visit Building DDKs You can compile the DDK from the IDE or the command line. ffl ffl To compile the DDK from the IDE: Please refer to Managing Source Code in the IDE User s Guide. To compile the DDK from the command line: Please refer to the release notes or the installation notes for information on the location of the DDK archives. DDKs are simple zipped archives, with no special requirements. You must manually expand their directory structure from the archive. You can install them into whichever directory you choose, assuming you have write permissions for the chosen directory. Historically, DDKs were placed in /usr/src/ddk VERSION directory, e.g. /usr/src/ddk This method is no longer required, as each DDK archive is completely self-contained. The following example indicates how you create a directory and unzip the archive file: # cd # mkdir my DDK # cd my DDK # unzip /path to ddks/ddk-device type.zip The top-level directory structure for each DDK looks like this: x About the USB DDK May 31, 2004

11 2004, QNX Software Systems Ltd. Building DDKs ddk_install_dir prebuilt install src platforms usr hardware lib include devu class include mouse printer Directory structure for a DDK. Each DDK is rooted in whatever directory you copy it to. If you type make within this directory, you ll generate all of the buildable entities within that DDK no matter where you move the directory. DDKs are structured so that typing make or make install doesn t affect the host system. All binaries are placed in a scratch area within the DDK directory that mimics the layout of a target system. May 31, 2004 About the USB DDK xi

12 Building DDKs 2004, QNX Software Systems Ltd. When you build a DDK, everything it needs, aside from standard system headers, is pulled in from within its own directory. thing that s built is installed outside of the DDK s directory. The makefiles shipped with the DDKs copy the contents of the prebuilt directory into the install directory. The binaries are built from the source using include files and link libraries in the install directory. xii About the USB DDK May 31, 2004

13 Chapter 1 Before You Begin In this chapter... System requirements 3 USB devices supported 3 Known limitations 4 DDK source code 5 May 31, 2004 Chapter 1 ffl Before You Begin 1

14

15 2004, QNX Software Systems Ltd. System requirements System requirements This USB SDK is designed to work with both QNX Neutrino 6 and with QNX 4. For QNX Neutrino 6.3 For QNX 4 You ll need the following: ffl QNX Neutrino 6.3 ffl GNU GCC ffl USB EHCI, OHCI or UHCI controller, version 1.1 and 2.0 compliant You ll need the following: ffl ffl QNX 4.25, patch D or later Watcom 10.6, patch B or later ffl USB EHCI, OHCI or UHCI controller, version 1.1 and 2.0 compliant USB devices supported Type of device Manufacturer Model Keyboard Belkin MediaBoard F8E211-USB Micro Innovations Mouse Logitech USB Wheel Mouse M-BB48 WingMan Gaming Mouse M-BC38 continued... May 31, 2004 Chapter 1 ffl Before You Begin 3

16 Known limitations 2004, QNX Software Systems Ltd. Type of device Manufacturer Model Microsoft IntelliMouse Hub ADS Technologies 4-port Belkin 4-port Printer Canon BJC-85 Epson Stylus Color 740 HP DeskJet 895Cse Known limitations EHCI Isochronous and split isochronous transfers are unsupported at this time. Retrieving Other Speed Descriptor has not been implemented. Photon and text mode If you re using Photon as well as text mode, you won t be able to switch between them and use a USB keyboard once the USB stack has been started. From a cold boot, you ll be able to use a USB keyboard in text mode before the USB stack has been started. As soon as you start the USB stack, you can t use a USB keyboard in text mode. 4 Chapter 1 ffl Before You Begin May 31, 2004

17 2004, QNX Software Systems Ltd. DDK source code! CAUTION: Make sure that the command line for devi-hirun (or Input) includes the option to not reset the keyboard controller. For example: devi-hirun kbd -R fd -d/dev/usbkbd0 & Or with QNX 4: Input kbd -R fd -d/dev/usbkbd0 & If you don t use the -R option, then the keyboard controller will be reset whenever you switch between Photon and text mode, and the machine may hang. DDK source code Currently, the directory structure for the USB DDK looks like this: May 31, 2004 Chapter 1 ffl Before You Begin 5

18 DDK source code 2004, QNX Software Systems Ltd. ddk_install_dir prebuilt install src platforms usr hardware lib include devu class include mouse printer Directory structure for the USB DDK. 6 Chapter 1 ffl Before You Begin May 31, 2004

19 Chapter 2 Overview In this chapter... The USB stack and library 9 How a class driver works 10 May 31, 2004 Chapter 2 ffl Overview 7

20

21 2004, QNX Software Systems Ltd. The USB stack and library The USB stack and library USB (Universal Serial Bus) is a hardware and protocol specification for interconnecting various devices to a host controller. We supply a USB stack that implements the USB protocol and allows user-written class drivers to communicate with USB devices. We also supply a USB driver library (usbd *()) for class drivers to use in order to communicate with the USB stack. te that a class driver can be considered a client of the USB stack. The stack is implemented as a standalone process that registers the pathname of /dev/io-usb/io-usb (by default). Currently, the stack contains the hub class driver within it. Host Controller Interface (HCI) types The stack supports the three industry-standard HCI types: ffl ffl ffl Open Host Controller Interface (OHCI) Universal Host Controller Interface (UHCI) Enhanced Host Controller Interface (EHCI). Data buffers We provide separate servers for each type (devu-ohci.so, devu-uhci.so), and devu-ehci.so. te that USB devices don t care whether a computer has an OHCI, UHCI, or an EHCI controller. The client library provides functions to allocate data buffers in shared memory; the stack manages these data buffers and gives the client library access to them. This means that all data transfers must use the provided buffers. As a result, a class driver must reside on the same physical node as the USB stack. The clients of the class driver, however, can be network-distributed. The advantage of this approach is that no additional memory copy occurs between the time that the data is received by the USB stack and the time that it s delivered to the class driver (and vice versa). May 31, 2004 Chapter 2 ffl Overview 9

22 How a class driver works 2004, QNX Software Systems Ltd. USB enumerator With the QNX Neutrino OS, the USB enumerator attaches to the USB stack and waits for device insertions. When a device insertion is detected, the enumerator looks in the configuration manager s database to see which class driver it should start. It then starts the appropriate driver, which provides for that class of device. For example, a USB Ethernet class driver would register with io-net and bring the interface up. For small, deeply embedded systems, the enumerator isn t required. The class drivers can be started individually they ll wait around for their particular devices to be detected by the stack. At that point, they ll provide the appropriate services for that class of device, just as if they d been started by the enumerator. When a device is removed, the enumerator will shut down the class driver. How a class driver works A class driver typically performs the following operations: 1 Connect to the USB stack (usbd connect()) and provide two callbacks: one for insertion and one for removal. 2 In the insertion callback: 2a 2b 2c 2d Connect to the USB device (usbd attach()). Get descriptors (usbd descriptor()). Select the configuration (usbd select config()) and interface (usbd select interface()). Set up communications pipes to the appropriate endpoint (usbd open pipe()). 3 In the removal callback, detach from the USB device (usbd detach()). 4 Set up all data communications (e.g. reading and writing data, sending and receiving control information, etc.) via the usbd setup *() functions (usbd setup bulk(), usbd setup interrupt(), etc.). 10 Chapter 2 ffl Overview May 31, 2004

23 2004, QNX Software Systems Ltd. How a class driver works 5 Initiate data transfer using the usbd io() function (with completion callbacks if required). In this context, the term pipe is a USB-specific term that has nothing to do with standard POSIX pipes (as used, for example, in the command line ls more). In USB terminology, a pipe is simply a handle; something that identifies a connection to an endpoint. May 31, 2004 Chapter 2 ffl Overview 11

24

25 Chapter 3 USB Utilities May 31, 2004 Chapter 3 ffl USB Utilities 13

26

27 2004, QNX Software Systems Ltd. The USB Software Development Kit contains the following command-line utilities: The utilities used in this DDK are the same ones that exist in the QNX Neutrino Utilities Reference. devu-ehci.so USB manager for Enhanced Host Controller Interface standard controllers. (USB 2.0) devu-ohci.so USB manager for Open Host Controller Interface standard controllers. (USB 2.0) devu-prn Class Driver for USB printers. devu-uhci.so USB manager for Universal Host Controller Interface standard controllers. (USB 2.0) io-usb usb USB server. Display USB device configuration. May 31, 2004 Chapter 3 ffl USB Utilities 15

28

29 Chapter 4 USB Library Reference In this chapter... Functions arranged by category 19 usbd abort pipe() 23 usbd alloc() 24 usbd alloc urb() 26 usbd args lookup() 28 usbd attach() 29 usbd close pipe() 32 usbd configuration descriptor() 33 usbd connect() 35 usbd descriptor() 40 usbd detach() 42 usbd device descriptor() 44 usbd device extra() 46 usbd device lookup() 47 usbd disconnect() 48 usbd endpoint descriptor() 50 usbd feature() 52 usbd free() 54 usbd free urb() 55 usbd get frame() 56 usbd hcd info() 58 usbd hub descriptor() 60 usbd interface descriptor() 62 usbd io() 64 usbd languages descriptor() 66 usbd mphys() 68 usbd open pipe() 69 usbd parse descriptors() 71 usbd pipe device() 74 May 31, 2004 Chapter 4 ffl USB Library Reference 17

30 2004, QNX Software Systems Ltd. usbd pipe endpoint() 75 usbd reset device() 76 usbd reset pipe() 77 usbd select config() 78 usbd select interface() 80 usbd setup bulk() 82 usbd setup control() 84 usbd setup interrupt() 86 usbd setup isochronous() 88 usbd setup vendor() 90 usbd status() 92 usbd string() 94 usbd topology() 96 usbd urb status() Chapter 4 ffl USB Library Reference May 31, 2004

31 2004, QNX Software Systems Ltd. Functions arranged by category Functions arranged by category The USB functions may be grouped into these categories: ffl ffl ffl ffl ffl ffl Connection functions Memory-management functions I/O functions Pipe-management functions Configuration/interface functions Miscellaneous functions Connection functions usbd connect() Connect a client driver to the USB stack. usbd disconnect() Disconnect a client driver from the USB stack. usbd attach() usbd detach() Attach to a USB device. Detach from a USB device. Memory-management functions usbd alloc() Allocate memory area to use for data transfers. usbd free() usbd mphys() usbd alloc urb() usbd free urb() Free memory allocated by usbd alloc(). Get the physical address of memory allocated by usbd alloc(). Allocate a USB Request Block for subsequent URB-based operations. Free the URB allocated by usbd alloc urb(). May 31, 2004 Chapter 4 ffl USB Library Reference 19

32 Functions arranged by category 2004, QNX Software Systems Ltd. I/O functions usbd setup bulk() Set up a URB for a bulk data transfer. usbd setup interrupt() Set up a URB for an interrupt transfer. usbd setup isochronous() Set up a URB for an isochronous transfer. usbd setup vendor() Set up a URB for a vendor-specific transfer. usbd setup control() Set up a URB for a control transfer. usbd io() usbd feature() usbd descriptor() usbd status() Submit a previously set up URB to the USB stack. Control a feature for a USB device. Get USB descriptors. Get specific device status. Pipe-management functions usbd open pipe() Initialize the pipe described by the device or endpoint descriptor. usbd close pipe() Close a pipe previously opened by the usbd open pipe() function. usbd reset pipe() Clear a stall condition on an endpoint identified by the pipe handle. 20 Chapter 4 ffl USB Library Reference May 31, 2004

33 2004, QNX Software Systems Ltd. Functions arranged by category usbd abort pipe() Abort all requests on a pipe. usbd pipe device() Retrieve the device associated with the pipe. usbd pipe endpoint() Retrieve the endpoint number associated with the pipe. Configuration/ interface functions usbd select config() Select the configuration for a USB device. usbd select interface() Select the interface for a USB device. Miscellaneous/ convenience functions usbd args lookup() Look up a driver s command-line arguments. usbd configuration descriptor() Get the configuration descriptor for a specific configuration setting. usbd device lookup() Map the device instance identifier to an opaque device handle (from usbd attach()). usbd device extra() Retrieve a pointer to the device-specific extra memory allocated by usbd attach(). usbd device descriptor() Get the device descriptor for a specific device. May 31, 2004 Chapter 4 ffl USB Library Reference 21

34 Functions arranged by category 2004, QNX Software Systems Ltd. usbd endpoint descriptor() Get the endpoint descriptor for a specific endpoint setting. usbd get frame() Get the current frame number and frame length for a device. usbd hcd info() Get information on the USB host controller and SDK library. usbd hub descriptor() Get the hub descriptor for a specific (hub) device. usbd interface descriptor() Get the interface descriptor for a specific interface setting. usbd languages descriptor() Get the table of supported LANGIDs for the given device. usbd parse descriptors() Parse device descriptors looking for a specific entry. usbd reset device() Reset a USB device. usbd string() Get a string descriptor. usbd urb status() Return status information on a URB. usbd topology() Get the USB bus physical topology. 22 Chapter 4 ffl USB Library Reference May 31, 2004

35 2004, QNX Software Systems Ltd. usbd abort pipe() Abort all requests on a pipe Synopsis: #include <sys/usbdi.h> int usbd abort pipe( struct usbd pipe *pipe ); Description: The usbd abort pipe() function aborts all requests on a pipe. This function can be used during an error condition (e.g. to abort a pending operation) or during normal operation (e.g. to halt an isochronous transfer). pipe An opaque handle returned by usbd open pipe(). Returns: EOK Success. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes Yes See also: usbd open pipe(), usbd close pipe(), usbd pipe endpoint(), usbd reset pipe() May 31, 2004 Chapter 4 ffl USB Library Reference 23

36 usbd alloc() Allocate memory area to use for data transfers 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> void *usbd alloc( size t size ); Description: The usbd alloc() function allocates a memory area that can then be used for data transfers. You should use the memory area allocated by this function, because it s allocated efficiently and because its physical address is quickly obtained via usbd mphys(). The usbd setup *() functions require usbd alloc() d data buffers. size Size (in bytes) of the area to be allocated. To free the memory, use usbd free(). Returns: A pointer to the start of the allocated memory, or NULL if there s not enough memory. Errors: ENOMEM Insufficient memory available. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler continued Chapter 4 ffl USB Library Reference May 31, 2004

37 2004, QNX Software Systems Ltd. usbd alloc() Safety Signal handler Thread Yes See also: usbd alloc urb(), usbd free(), usbd free urb(), usbd mphys() May 31, 2004 Chapter 4 ffl USB Library Reference 25

38 usbd alloc urb() Allocate a USB Request Block for subsequent URB-based operations 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> struct usbd urb *usbd alloc urb( struct usbd urb *link ); Description: The usbd alloc urb() function allocates a USB Request Block (URB) to be used for subsequent URB-based I/O transfers. link Specifies multiple URBs linked together. (t yet implemented.) To free the block, use usbd free urb(). Returns: A pointer to the start of the allocated block, or NULL if there s not enough memory. Errors: ENOMEM Insufficient memory available. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes 26 Chapter 4 ffl USB Library Reference May 31, 2004

39 2004, QNX Software Systems Ltd. usbd alloc urb() See also: usbd alloc(), usbd free(), usbd free urb(), usbd mphys() May 31, 2004 Chapter 4 ffl USB Library Reference 27

40 usbd args lookup() Look up a driver s command-line arguments 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> void usbd args lookup(struct usbd connection *connection, int *argc, char ***argv ); Description: The usbd args lookup() function lets you look up a device driver s command-line arguments at insertion/attach time. The command-line arguments are held in argc and argv within the usbd connect parm data structure. See usbd connect() for details. connection Identifies the USB stack (from usbd connect()). Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes See also: usbd configuration descriptor(), usbd connect(), usbd device lookup(), usbd device extra(), usbd device descriptor(), usbd endpoint descriptor(), usbd hcd info(), usbd hub descriptor(), usbd interface descriptor(), usbd languages descriptor(), usbd parse descriptors(), usbd string(), usbd urb status() 28 Chapter 4 ffl USB Library Reference May 31, 2004

41 2004, QNX Software Systems Ltd. usbd attach() Attach to a USB device Synopsis: #include <sys/usbdi.h> int usbd attach( struct usbd connection *connection, usbd device instance t *instance, size t extra, struct usbd device **device ); Description: You use the usbd attach() function to attach to a USB device. Typically, you do this out of the insertion callback (made when the device matched your filter), which will give you the connection and instance parameters involved. The insertion callback is prototyped as follows: void (*insertion)(struct usbd connection *, usbd device instance t *instance) Here are the parameters: connection instance extra device An opaque handle that identifies the USB stack (from usbd connect()). Describes which device you wish to attach to. The size of additional memory you d like allocated with the device. You can use usbd device extra() later to get a pointer to this additional memory. Typically, the class driver would store various status/config/device-specific details in here (if needed). An opaque handle used to identify the device in later calls. The usbd device instance t structure looks like this: May 31, 2004 Chapter 4 ffl USB Library Reference 29

42 usbd attach() 2004, QNX Software Systems Ltd. typedef struct usbd device instance { uint8 path; uint8 devno; uint16 generation; usbd device ident t ident; uint32 config; uint32 iface; uint32 alternate; } usbd device instance t; Looping Another way to attach is to loop and attach to all devices (in which case you build the instance yourself). For example: for (devno = 0; devno < 64; ++devno) { memset(&instance, USBD CONNECT WILDCARD, sizeof(usbd device instance t)); instance.path = 0, instance.devno = devno; if (usbd attach(connection, &instance, 0, &device) == EOK) {... } } The degree of attachedness depends on how you connected. If you specified insertion/removal callback functions, then you ll get exclusive access to the device and can make I/O to it. If you didn t use callbacks and you attached as in the loop above, you get shared access, so you can only read device configuration. Returns: EOK ENODEV EBUSY ENOMEM Success. Specified device doesn t exist. If in a loop, then there s nothing at that devno. If from a callback, then the device has since been removed. A shared/exclusive conflict. memory for internal device structures. 30 Chapter 4 ffl USB Library Reference May 31, 2004

43 2004, QNX Software Systems Ltd. usbd attach() Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes Yes See also: usbd connect(), usbd detach(), usbd device extra(), usbd disconnect() May 31, 2004 Chapter 4 ffl USB Library Reference 31

44 usbd close pipe() Close a pipe previously opened by usbd open pipe() 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> int usbd close pipe( struct usbd pipe *pipe ); Description: You use the usbd close pipe() function to close a pipe that was previously opened via usbd open pipe(). pipe An opaque handle returned by usbd open pipe(). Returns: EOK EBUSY Success. Active or pending I/O. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes See also: usbd abort pipe(), usbd open pipe(), usbd pipe endpoint(), usbd reset pipe() 32 Chapter 4 ffl USB Library Reference May 31, 2004

45 2004, QNX Software Systems Ltd. usbd configuration descriptor() Get the configuration descriptor for a specific configuration setting Synopsis: #include <sys/usbdi.h> usbd configuration descriptor t *usbd configuration descriptor( struct usbd device *device, uint8 cfg, struct usbd desc node **node ); Description: The usbd configuration descriptor() function lets you obtain the configuration descriptor for a specific configuration setting. device cfg node An opaque handle used to identify the USB device. The device s configuration identifier (bconfigurationvalue). Indicates the descriptor s location for rooting future requests (e.g. interfaces of this configuration). The usbd configuration descriptor t structure looks like this: typedef struct usbd configuration descriptor { uint8 blength; uint8 bdescriptortype; uint16 wtotallength; uint8 bnuminterfaces; uint8 bconfigurationvalue; uint8 iconfiguration; uint8 bmattributes; uint8 MaxPower; } usbd configuration descriptor t; May 31, 2004 Chapter 4 ffl USB Library Reference 33

46 usbd configuration descriptor() 2004, QNX Software Systems Ltd. Returns: A pointer to usbd configuration descriptor t on success, or NULL on error. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes See also: usbd args lookup(), usbd device lookup(), usbd device extra(), usbd device descriptor(), usbd endpoint descriptor(), usbd hcd info(), usbd hub descriptor(), usbd interface descriptor(), usbd languages descriptor(), usbd parse descriptors(), usbd string(), usbd urb status() 34 Chapter 4 ffl USB Library Reference May 31, 2004

47 2004, QNX Software Systems Ltd. usbd connect() Connect a client driver to the USB stack Synopsis: #include <sys/usbdi.h> int usbd connect( usbd connect parm t *parm, struct usbd connection **connection ); Description: You use the usbd connect() function to connect to a USB device and to provide insertion/removal callbacks (in the usbd connect parm t data structure). parm connection Connection parameters describing how to connect to the USB stack and how you intend to operate with it. An opaque handle returned on a successful connection; it s used to pass into other routines to identify the connection. Data structures typedef struct usbd connect parm { const char uint16 uint16 uint32 int char uint32 usbd device ident t usbd funcs t uint16 } usbd connect parm t; *path; vusb; vusbd; flags; argc; **argv; evtbufsz; *ident; *funcs; connect wait path vusb and vusbd Name of the stack (NULL means /dev/io-usb/io-usb, the default name). Versions of the USB stack (USB VERSION) and SDK (USBD VERSION). May 31, 2004 Chapter 4 ffl USB Library Reference 35

48 usbd connect() 2004, QNX Software Systems Ltd. flags Currently none defined. Pass 0. argc and argv evtbufsz ident funcs connect wait Command-line arguments to the device driver that can be made available via usbd args lookup() at insertion/attach time. Size of the event buffer used by the handler thread to buffer events from the USB stack. For the default size, pass 0. Identifies the devices you re interested in receiving insertion/removal callbacks for (a filter); fields can be set to USBD CONNECT WILDCARD or to an explicit value. The insertion/removal callbacks. A value (in seconds) or USBD CONNECT WAIT. typedef struct usbd device ident { uint32 vendor; uint32 device; uint32 class; uint32 subclass; uint32 protocol; } usbd device ident t; You would typically make the usbd device ident structure be a filter for devices you support from this specific class driver. typedef struct usbd funcs { uint32 nentries; void (*insertion)(struct usbd connection *, usbd device instance t *instance); void (*removal)(struct usbd connection *, usbd device instance t *instance); void (*event)(struct usbd connection *, usbd device instance t *instance, uint16 type); } usbd funcs t; The callback functions are contained here. insertion removal Called when a device that matches defined filter is detected. Called when a device is removed. 36 Chapter 4 ffl USB Library Reference May 31, 2004

49 2004, QNX Software Systems Ltd. usbd connect() event A future extension for various other event notifications (e.g. bandwidth problems). USBDI NFUNCS A constant that goes into nentries. By passing NULL as the usbd funcs, you re saying that you re not interested in receiving dynamic insertion/removal notifications, which means that you won t be a fully operational class driver. asynchronous I/O will be allowed, no event thread, etc. This approach is taken, for example, by the usb display utility. Returns: EOK Success. EPROGRAMISMATCH Versionitis. ENOMEM ESRCH EACCESS EAGAIN memory for internal connect structures. USB server not running. Permission denied to USB server. Can t create async/callback thread. Examples: A class driver (in its main(), probably) for a 3COM Ethernet card might connect like this: usbd device ident t interest = { USB VENDOR 3COM, USB PRODUCT 3COM 3C19250, USBD CONNECT WILDCARD, USBD CONNECT WILDCARD, USBD CONNECT WILDCARD, }; usbd funcs t funcs = { May 31, 2004 Chapter 4 ffl USB Library Reference 37

50 usbd connect() 2004, QNX Software Systems Ltd. USBDI NFUNCS, insertion, removal, NULL }; usbd connect parm t cparms = { NULL, USB VERSION, USBD VERSION, 0, argc, argv, 0, &interest, &funcs }; struct usbd connection *connection; int error; error = usbd connect(&cparms, &connection); Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes Yes Caveats: The usbd connect() function creates a thread on your behalf that s used by the library to monitor the USB stack for device insertion or removal. Since your insertion and removal callback functions are called by this new thread, you must ensure that any common 38 Chapter 4 ffl USB Library Reference May 31, 2004

51 2004, QNX Software Systems Ltd. usbd connect() resources used between that thread and any other thread(s) in your class driver are properly protected (e.g. via a mutex). See also: usbd args lookup(), usbd attach(), usbd detach(), usbd disconnect() May 31, 2004 Chapter 4 ffl USB Library Reference 39

52 usbd descriptor() Get USB descriptors. 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> int usbd descriptor( struct usbd device *device, int set, uint8 type, uint16 rtype, uint8 index, uint16 langid, uint8 *desc, size t len ); Description: The usbd descriptor() function lets you obtain the USB descriptors. device set type rtype index langid desc len An opaque handle used to identify the USB device. A flag that says to either get or set a descriptor. Type of descriptor (e.g. USB DESC DEVICE, USB DESC CONFIGURATION, USB DESC STRING, USB DESC HUB). Type of request (e.g. USB RECIPIENT DEVICE, USB RECIPIENT INTERFACE, USB RECIPIENT ENDPOINT, USB RECIPIENT OTHER, USB TYPE STANDARD, USB TYPE CLASS, USB TYPE VENDOR). This varies, depending on the request. It s used for passing a parameter to the device. Identifies the language supported in strings (according to the LANGID table). Pointer at buffer to put descriptors. The length of the data transfer in bytes. 40 Chapter 4 ffl USB Library Reference May 31, 2004

53 2004, QNX Software Systems Ltd. usbd descriptor() Returns: EMSGSIZE ENOMEM ENODEV EIO Buffer too small for descriptor. memory for URB. Device was removed. I/O error on USB device. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes Yes See also: usbd feature() usbd io(), usbd setup bulk(), usbd setup control(), usbd setup interrupt(), usbd setup isochronous(), usbd setup vendor(), usbd status() May 31, 2004 Chapter 4 ffl USB Library Reference 41

54 usbd detach() Detach from the USB device 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> int usbd detach( struct usbd device *device ); Description: You use the usbd detach() function to disconnect from a USB device that you previously had attached to via usbd attach(). The usbd detach() function automatically closes any pipes previously opened via usbd open pipe(). device An opaque handle from usbd attach(). Returns: EOK EBUSY Success. I/O pending on the device. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes Yes 42 Chapter 4 ffl USB Library Reference May 31, 2004

55 2004, QNX Software Systems Ltd. usbd detach() Caveats: See also: Don t try to detach if there s I/O pending on the device. If there is, usbd detach() will fail. usbd attach(), usbd close pipe(), usbd connect(), usbd disconnect(), usbd open pipe() May 31, 2004 Chapter 4 ffl USB Library Reference 43

56 usbd device descriptor() Get the device descriptor for a specific device 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> usbd device descriptor t *usbd device descriptor( struct usbd device *device, struct usbd desc node **node ); Description: The usbd device descriptor() function lets you obtain the device descriptor for a specific device (a handle from usbd attach()). The node parameter tells you where a descriptor was found to root future requests from (e.g. configurations of the device). The usbd device descriptor t structure looks like this: typedef struct usbd device descriptor { uint8 blength; uint8 bdescriptortype; uint16 bcdusb; uint8 bdeviceclass; uint8 bdevicesubclass; uint8 bdeviceprotocol; uint8 bmaxpacketsize0; uint16 idvendor; uint16 idproduct; uint16 bcddevice; uint8 imanufacturer; uint8 iproduct; uint8 iserialnumber; uint8 bnumconfigurations; } usbd device descriptor t; Returns: A pointer to usbd device descriptor t on success, or NULL on error. 44 Chapter 4 ffl USB Library Reference May 31, 2004

57 2004, QNX Software Systems Ltd. usbd device descriptor() Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes See also: usbd args lookup(), usbd configuration descriptor(), usbd device lookup(), usbd device extra(), usbd endpoint descriptor(), usbd hcd info(), usbd hub descriptor(), usbd interface descriptor(), usbd languages descriptor(), usbd parse descriptors(), usbd string(), usbd urb status() May 31, 2004 Chapter 4 ffl USB Library Reference 45

58 usbd device extra() Get a pointer to the memory allocated by the extra parameter 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> void *usbd device extra( struct usbd device *device ); Description: You use the usbd device extra() function to get a pointer to the additional memory allocated via the extra parameter in usbd attach(). Returns: NULL if no device-specific memory was allocated by usbd attach(). Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes See also: usbd args lookup(), usbd attach() usbd configuration descriptor(), usbd device lookup(), usbd device descriptor(), usbd endpoint descriptor(), usbd hcd info(), usbd hub descriptor(), usbd interface descriptor(), usbd languages descriptor(), usbd parse descriptors(), usbd string(), usbd urb status() 46 Chapter 4 ffl USB Library Reference May 31, 2004

59 2004, QNX Software Systems Ltd. usbd device lookup() Map the device instance identifier to an opaque device handle (from usbd attach()) Synopsis: #include <sys/usbdi.h> struct usbd device *usbd device lookup( struct usbd connection *connection, usbd device instance t *instance ); Description: You use the usbd device lookup() function to map the device instance identifier to an opaque device handle from usbd attach(). This would typically be required in the removal callback. Returns: An opaque device handle or NULL. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes See also: usbd args lookup(), usbd attach(), usbd configuration descriptor(), usbd device extra(), usbd device descriptor(), usbd endpoint descriptor(), usbd hcd info(), usbd hub descriptor(), usbd interface descriptor(), usbd languages descriptor(), usbd parse descriptors(), usbd string(), usbd urb status() May 31, 2004 Chapter 4 ffl USB Library Reference 47

60 usbd disconnect() Disconnect a client driver from the USB stack 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> int usbd disconnect( struct usbd connection *connection ); Description: You use the usbd disconnect() to disconnect a client driver that had been previously connected to the USB stack via the usbd connect() function. The usbd disconnect() function automatically closes any pipes previously opened via usbd attach(). connection Identifies the USB stack (from usbd connect()). Returns: EOK Success. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes Yes 48 Chapter 4 ffl USB Library Reference May 31, 2004

61 2004, QNX Software Systems Ltd. usbd disconnect() See also: usbd attach(), usbd connect(), usbd detach() May 31, 2004 Chapter 4 ffl USB Library Reference 49

62 usbd endpoint descriptor() Get the endpoint descriptor for a specific endpoint setting 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> usbd endpoint descriptor t *usbd endpoint descriptor( struct usbd device *device, uint8 config, uint8 iface, uint8 alt, uint8 endpoint, struct usbd desc node **node ); Description: The usbd endpoint descriptor() function lets you obtain the endpoint descriptor for a specific endpoint on a configuration/interface. device config ifc alt endpoint node An opaque handle used to identify the USB device. Configuration identifier (bconfigurationvalue). Interface identifier (binterfacenumber). Alternate identifier (balternatesetting). Endpoint identifier (bendpointaddress). Indicates the descriptor s location for rooting future requests. The endpoint descriptor t structure looks like this: typedef struct usbd endpoint descriptor { uint8 blength; uint8 bdescriptortype; uint8 bendpointaddress; uint8 bmattributes; uint16 wmaxpacketsize; uint8 binterval; } usbd endpoint descriptor t; 50 Chapter 4 ffl USB Library Reference May 31, 2004

63 2004, QNX Software Systems Ltd. usbd endpoint descriptor() Returns: A pointer to usbd endpoint descriptor t on success, or NULL on error. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes See also: usbd args lookup(), usbd configuration descriptor(), usbd device lookup(), usbd device extra(), usbd device descriptor(), usbd hcd info(), usbd hub descriptor(), usbd interface descriptor(), usbd languages descriptor(), usbd parse descriptors(), usbd string(), usbd urb status() May 31, 2004 Chapter 4 ffl USB Library Reference 51

64 usbd feature() Control a feature for a USB device. 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> int usbd feature( struct usbd device *device, int set, uint16 feature, uint16 rtype, uint16 index ); Description: The usbd feature() function lets you control a specific feature on a USB device. device set feature rtype index An opaque handle used to identify the USB device. Set or clear a feature on the USB device. A specific feature on the device. Type of request (e.g. USB RECIPIENT DEVICE, USB RECIPIENT INTERFACE, USB RECIPIENT ENDPOINT, USB RECIPIENT OTHER, USB TYPE STANDARD, USB TYPE CLASS, USB TYPE VENDOR). This varies, depending on the request. It s used for passing a parameter to the device. Returns: EOK ENOMEM ENODEV EIO Success. memory for URB. Device was removed. I/O error on USB device. 52 Chapter 4 ffl USB Library Reference May 31, 2004

65 2004, QNX Software Systems Ltd. usbd feature() Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes Yes See also: usbd descriptor(), usbd io(), usbd setup bulk(), usbd setup control(), usbd setup interrupt(), usbd setup isochronous(), usbd setup vendor(), usbd status() May 31, 2004 Chapter 4 ffl USB Library Reference 53

66 usbd free() Free the memory area allocated by usbd alloc() 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> void usbd free( void* ptr ); Description: The usbd free() function frees the memory allocated by usbd alloc(). The function deallocates the memory area specified by ptr, which was previously returned by a call to usbd mphys(). It s safe to call usbd free() with a NULL ptr. Returns: EOK Success. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes See also: usbd alloc(), usbd alloc urb(), usbd free urb(), usbd mphys() 54 Chapter 4 ffl USB Library Reference May 31, 2004

67 2004, QNX Software Systems Ltd. usbd free urb() Free the USB Request Block allocated by usbd alloc urb() Synopsis: #include <sys/usbdi.h> struct usbd urb *usbd free urb( struct usbd urb *urb ); Description: The usbd free urb() function frees the memory allocated by usbd alloc urb(). Returns: EOK Success. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes See also: usbd alloc(), usbd alloc urb(), usbd free(), usbd mphys() May 31, 2004 Chapter 4 ffl USB Library Reference 55

68 usbd get frame() Get the current frame number and frame length for a device 2004, QNX Software Systems Ltd. Synopsis: int usbd get frame( struct usdb device *device, int32 *fnum, int32 *flen ); Description: This function gets the current frame number and frame length for a specific device (a handle from usbd attach()). fnum flen If non-null, this is set to the frame number. If non-null, this is set to the frame length. Returns: EOK ENODEV Success. The device has been removed. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes Yes 56 Chapter 4 ffl USB Library Reference May 31, 2004

69 2004, QNX Software Systems Ltd. usbd get frame() See also: usbd attach() May 31, 2004 Chapter 4 ffl USB Library Reference 57

70 usbd hcd info() Get information on the USB host controller and SDK library 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> int usbd hcd info( struct usbd connection *connection, uint32 cindex, usbd hcd info t *info ); Description: You use the usbd hcd info() function to obtain information from the USB host controller and SDK library. connection cindex info Identifies the USB stack (from usbd connect()). Gets information about a specific host controller. A pointer to the usbd hcd info t data structure, which is filled in by usbd hcd info(). The structure contains at least the following: typedef struct usbd hcd info { uint16 vusb; uint16 vusbd; char controller[8]; uint32 capabilities; uint8 ndev; uint8 reserved[1]; uint16 vhcd; uint8 reserved[12]; } usbd hcd info t; The vusb, vusbd, and vhcd fields hold the version numbers of the USB stack, the SDK, and the HCD; controller and capabilities hold the name and capabilities of the USB host controller; ndev contains the number of devices currently connected. 58 Chapter 4 ffl USB Library Reference May 31, 2004

71 2004, QNX Software Systems Ltd. usbd hcd info() Returns: EOK Success. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes Yes See also: usbd args lookup(), usbd configuration descriptor(), usbd device lookup(), usbd device extra(), usbd device descriptor(), usbd endpoint descriptor(), usbd hub descriptor(), usbd interface descriptor(), usbd languages descriptor(), usbd parse descriptors(), usbd string(), usbd urb status() May 31, 2004 Chapter 4 ffl USB Library Reference 59

72 usbd hub descriptor() Get the hub descriptor for a specific (hub) device 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> usbd hub descriptor t *usbd hub descriptor( struct usbd device *device, struct usbd desc node **node ); Description: The usbd hub descriptor() function lets you obtain a hub descriptor. device node An opaque handle used to identify the USB device. Indicates the descriptor s location for rooting future requests. The usbd hub descriptor t data structure looks like this: typedef struct usbd hub descriptor { uint8 blength; uint8 bdescriptortype; uint8 bnbrports; uint16 whubcharacteristics; uint8 bpwron2pwrgood; uint8 bhubcontrcurrent; uint8 DeviceRemovable[1]; uint8 PortPwrCtrlMask[1]; } usbd hub descriptor t; Returns: A pointer to usbd hub descriptor t on success, or NULL on error. Classification: QNX Neutrino, QNX 4 60 Chapter 4 ffl USB Library Reference May 31, 2004

73 2004, QNX Software Systems Ltd. usbd hub descriptor() Safety Cancellation point Interrupt handler Signal handler Thread Yes See also: usbd args lookup(), usbd configuration descriptor(), usbd device lookup(), usbd device extra(), usbd device descriptor(), usbd endpoint descriptor(), usbd hcd info(), usbd interface descriptor(), usbd languages descriptor(), usbd parse descriptors(), usbd string(), usbd urb status() May 31, 2004 Chapter 4 ffl USB Library Reference 61

74 usbd interface descriptor() Get the interface descriptor for a specific interface setting 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> usbd interface descriptor t *usbd interface descriptor( struct usbd device *device, uint8 cfg, uint8 ifc, uint8 alt, struct usbd desc node **node ); Description: The usbd interface descriptor() function lets you obtain the interface descriptor for a specific interface setting. device cfg ifc alt node An opaque handle used to identify the USB device. The device s configuration identifier (bconfigurationvalue). Interface identifier (binterfacenumber). Alternate identifier (balternatesetting). Indicates the descriptor s location for rooting future requests (e.g. endpoints of this interface). The usbd interface descriptor t structure looks like this: typedef struct usbd interface descriptor { uint8 blength; uint8 bdescriptortype; uint8 binterfacenumber; uint8 balternatesetting; uint8 bnumendpoints; uint8 binterfaceclass; uint8 binterfacesubclass; uint8 binterfaceprotocol; uint8 iinterface; } usbd interface descriptor t; 62 Chapter 4 ffl USB Library Reference May 31, 2004

75 2004, QNX Software Systems Ltd. usbd interface descriptor() Returns: A pointer to usbd interface descriptor t on success, or NULL on error. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes See also: usbd args lookup(), usbd configuration descriptor(), usbd device lookup(), usbd device extra(), usbd device descriptor(), usbd endpoint descriptor(), usbd hcd info(), usbd hub descriptor(), usbd languages descriptor(), usbd parse descriptors(), usbd string(), usbd urb status() May 31, 2004 Chapter 4 ffl USB Library Reference 63

76 usbd io() Submit a previously set up URB to the USB stack 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> int usbd io( struct usbd urb *urb, struct usbd pipe *pipe, void (*func)(struct usbd urb *, struct usbd pipe *, void *), void *handle, uint32 timeout ); Description: This routine submits a previously set up URB to the USB stack. The URB would have been set up from one of these functions: ffl ffl ffl ffl ffl usbd setup bulk() usbd setup control() usbd setup interrupt() usbd setup isochronous() usbd setup vendor() For this release of the USB SDK, vendor requests are synchronous only. Therefore, the func parameter in usbd io() must be NULL. The usbd io() function is the one that actually makes the data transfer happen; the setup functions simply set up the URB for the data transfer. pipe func handle timeout An opaque handle returned by usbd open pipe(). Callback at I/O completion, given URB, pipe, plus handle. User data. A value (in milliseconds) or USBD TIME DEFAULT or USBD TIME INFINITY. 64 Chapter 4 ffl USB Library Reference May 31, 2004

77 2004, QNX Software Systems Ltd. usbd io() Returns: EBADF EINVAL ENODEV Improper usbd connect() call. Improper usbd connect() call. Device was removed. Classification: QNX Neutrino, QNX 4 Safety Cancellation point Interrupt handler Signal handler Thread Yes Yes See also: usbd descriptor(), usbd feature(), usbd setup control(), usbd setup bulk(), usbd setup interrupt(), usbd setup isochronous(), usbd setup vendor(), usbd status() May 31, 2004 Chapter 4 ffl USB Library Reference 65

78 usbd languages descriptor() Get the table of supported LANGIDs for the given device 2004, QNX Software Systems Ltd. Synopsis: #include <sys/usbdi.h> usbd string descriptor t *usbd languages descriptor( struct usbd device *device, struct usbd desc node **node ); Description: The usbd languages descriptor() function lets you obtain the table of supported language IDs for the device. device node An opaque handle used to identify the USB device. Indicates the descriptor s location for rooting future requests. The usbd string descriptor t structure looks like this: typedef struct usbd string descriptor { uint8 blength; uint8 bdescriptortype; uint16 bstring[1]; } usbd string descriptor t; Returns: A pointer usbd string descriptor t on success, NULL on error. Classification: QNX Neutrino, QNX 4 66 Chapter 4 ffl USB Library Reference May 31, 2004

79 2004, QNX Software Systems Ltd. usbd languages descriptor() Safety Cancellation point Interrupt handler Signal handler Thread Yes See also: usbd args lookup(), usbd configuration descriptor(), usbd device lookup(), usbd device extra(), usbd device descriptor(), usbd endpoint descriptor(), usbd hcd info(), usbd hub descriptor(), usbd interface descriptor(), usbd parse descriptors(), usbd string(), usbd urb status() May 31, 2004 Chapter 4 ffl USB Library Reference 67