QNX Momentics - photon.qnx.comphoton.qnx.com/download/download/9367/ddk_usb.pdfQNX Momentics DDK...

QNX Momentics DDK

Universal Serial Bus (USB) Devices

For QNX Neutrino 6.3.0 or QNX 4

2004, QNX Software Systems Ltd.

QNX Software Systems Ltd.175 Terence Matthews CrescentKanata, OntarioK2M 1W8CanadaVoice: +1 613 591-0931Fax: +1 613 591-3579Email: [email protected]: http://www.qnx.com/

2000 – 2004, 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(www.qnx.com). 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.

Contents

About the USB DDK viiAssumptions ix

Building DDKs x

Before You Begin 11System requirements 3

For QNX Neutrino 6.3 3

For QNX 4 3

USB devices supported 3

Known limitations 4

EHCI 4

Photon and text mode 4

DDK source code 5

Overview 72The 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 133

USB Library Reference 174Functions arranged by category 19

May 31, 2004 Contents iii


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


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

About the USB DDK

May 31, 2004 About the USB DDK vii

2004, QNX Software Systems Ltd. Assumptions

Our USB API is designed to work with either QNX Neutrino orQNX 4. Exceptions will be noted where appropriate.

�

This guide is organized into these main parts:

� a read-this-first page indicating your system requirements andother 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 underthe /ddk working dir/usb/src/hardware/devu/class directoryon your system.

�

AssumptionsWe assume you’re familiar with the Universal Serial Bus (USB)Specification revision 2.0, especially the chapters on:

� 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 inorder to write USB client device drivers.

May 31, 2004 About the USB DDK ix

Building DDKs 2004, QNX Software Systems Ltd.

For up-to-date information on USB developments, visitwww.usb.org.

�

Building DDKsYou can compile the DDK from the IDE or the command line.

� 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 forinformation on the location of the DDK archives.

DDKs are simple zipped archives, with no special requirements.You must manually expand their directory structure from thearchive. 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-6.2.1. This method is no longerrequired, as each DDK archive is completely self-contained.

The following example indicates how you create a directory andunzip 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

2004, QNX Software Systems Ltd. Building DDKs

prebuilt install

include

usr

src

ddk_install_dir

platforms

lib

mouse

printer

devu

hardware

includeclass

Directory structure for a DDK.

Each DDK is rooted in whatever directory you copy it to. If youtype make within this directory, you’ll generate all of the buildableentities 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 scratcharea within the DDK directory that mimics the layout of a targetsystem.

May 31, 2004 About the USB DDK xi

Building DDKs 2004, QNX Software Systems Ltd.

When you build a DDK, everything it needs, aside from standardsystem headers, is pulled in from within its own directory. Nothingthat’s built is installed outside of the DDK’s directory. Themakefiles shipped with the DDKs copy the contents of theprebuilt directory into the install directory. The binaries arebuilt from the source using include files and link libraries in theinstall directory.

xii About the USB DDK May 31, 2004

Chapter 1

Before You Begin

In this chapter. . .System requirements 3USB devices supported 3Known limitations 4DDK source code 5

May 31, 2004 Chapter 1 � Before You Begin 1

2004, QNX Software Systems Ltd. System requirements

System requirementsThis USB SDK is designed to work with both QNX Neutrino 6 andwith QNX 4.

For QNX Neutrino 6.3You’ll need the following:

� QNX Neutrino 6.3

� GNU GCC 2.952

� USB EHCI, OHCI or UHCI controller, version 1.1 and 2.0compliant

For QNX 4You’ll need the following:

� QNX 4.25, patch D or later

� Watcom 10.6, patch B or later

� USB EHCI, OHCI or UHCI controller, version 1.1 and 2.0compliant

USB devices supported

Type of device Manufacturer Model

Keyboard Belkin MediaBoard F8E211-USB

″ Micro Innovations –

Mouse Logitech USB Wheel MouseM-BB48

″ ″ WingMan Gaming MouseM-BC38

continued. . .


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 limitationsEHCI

Isochronous and split isochronous transfers are unsupported at thistime.

Retrieving ’Other Speed Descriptor’ has not been implemented.

Photon and text modeIf you’re using Photon as well as text mode, you won’t be able toswitch between them and use a USB keyboard once the USB stackhas been started.

From a cold boot, you’ll be able to use a USB keyboard in text modebefore the USB stack has been started. As soon as you start the USBstack, you can’t use a USB keyboard in text mode.

4 Chapter 1 � Before You Begin May 31, 2004

2004, QNX Software Systems Ltd. DDK source code

CAUTION: Make sure that the command line for devi-hirun (orInput) includes the option to not reset the keyboard controller. Forexample:

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 bereset whenever you switch between Photon and text mode, and themachine may hang.

!

DDK source codeCurrently, the directory structure for the USB DDK looks like this:


DDK source code 2004, QNX Software Systems Ltd.

prebuilt install

include

usr

src

ddk_install_dir

platforms

lib

mouse

printer

devu

hardware

includeclass

Directory structure for the USB DDK.

6 Chapter 1 � Before You Begin May 31, 2004

Chapter 2

Overview

In this chapter. . .The USB stack and library 9How a class driver works 10

May 31, 2004 Chapter 2 � Overview 7

2004, QNX Software Systems Ltd. The USB stack and library

The USB stack and libraryUSB (Universal Serial Bus) is a hardware and protocol specificationfor interconnecting various devices to a host controller. We supply aUSB stack that implements the USB protocol and allows user-writtenclass drivers to communicate with USB devices.

We also supply a USB driver library (usbd *()) for class drivers to usein order to communicate with the USB stack. Note that a class drivercan be considered a “client” of the USB stack.

The stack is implemented as a standalone process that registers thepathname of /dev/io-usb/io-usb (by default). Currently, thestack contains the hub class driver within it.

Host Controller Interface (HCI) typesThe stack supports the three industry-standard HCI types:

� Open Host Controller Interface (OHCI)

� Universal Host Controller Interface (UHCI)

� Enhanced Host Controller Interface (EHCI).

We provide separate servers for each type (devu-ohci.so,devu-uhci.so), and devu-ehci.so. Note that USB devices don’tcare whether a computer has an OHCI, UHCI, or an EHCI controller.

Data buffersThe client library provides functions to allocate data buffers in sharedmemory; the stack manages these data buffers and gives the clientlibrary access to them. This means that all data transfers must use theprovided buffers.

As a result, a class driver must reside on the same physical node as theUSB stack. The clients of the class driver, however, can benetwork-distributed. The advantage of this approach is that noadditional memory copy occurs between the time that the data isreceived by the USB stack and the time that it’s delivered to the classdriver (and vice versa).


How a class driver works 2004, QNX Software Systems Ltd.

USB enumeratorWith the QNX Neutrino OS, the USB enumerator attaches to the USBstack and waits for device insertions. When a device insertion isdetected, the enumerator looks in the configuration manager’sdatabase to see which class driver it should start. It then starts theappropriate driver, which provides for that class of device. Forexample, 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 fortheir particular devices to be detected by the stack. At that point,they’ll provide the appropriate services for that class of device, just asif they’d been started by the enumerator. When a device is removed,the enumerator will shut down the class driver.

How a class driver worksA class driver typically performs the following operations:

1 Connect to the USB stack (usbd connect()) and provide twocallbacks: one for insertion and one for removal.

2 In the insertion callback:

2a Connect to the USB device (usbd attach()).

2b Get descriptors (usbd descriptor()).

2c Select the configuration (usbd select config()) andinterface (usbd select interface()).

2d 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 theusbd setup *() functions (usbd setup bulk(),usbd setup interrupt(), etc.).

10 Chapter 2 � Overview May 31, 2004

2004, QNX Software Systems Ltd. How a class driver works

5 Initiate data transfer using the usbd io() function (withcompletion callbacks if required).

In this context, the term “pipe” is a USB-specific term that has nothingto do with standard POSIX “pipes” (as used, for example, in thecommand line ls | more). In USB terminology, a “pipe” is simplya handle; something that identifies a connection to an endpoint.

�


Chapter 3

USB Utilities

May 31, 2004 Chapter 3 � USB Utilities 13


The USB Software Development Kit contains the followingcommand-line utilities:

The utilities used in this DDK are the same ones that exist in the QNXNeutrino Utilities Reference.

�

devu-ehci.so

USB manager for Enhanced Host Controller Interfacestandard controllers. (USB 2.0)

devu-ohci.so

USB manager for Open Host Controller Interfacestandard controllers. (USB 2.0)

devu-prn Class Driver for USB printers.

devu-uhci.so

USB manager for Universal Host Controller Interfacestandard controllers. (USB 2.0)

io-usb USB server.

usb Display USB device configuration.

May 31, 2004 Chapter 3 � USB Utilities 15

Chapter 4

USB Library Reference

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

May 31, 2004 Chapter 4 � USB Library Reference 17


usbd pipe endpoint() 75usbd reset device() 76usbd reset pipe() 77usbd select config() 78usbd select interface() 80usbd setup bulk() 82usbd setup control() 84usbd setup interrupt() 86usbd setup isochronous() 88usbd setup vendor() 90usbd status() 92usbd string() 94usbd topology() 96usbd urb status() 98

18 Chapter 4 � USB Library Reference May 31, 2004

2004, QNX Software Systems Ltd. Functions arranged by category

Functions arranged by categoryThe USB functions may be grouped into these categories:

� Connection functions

� Memory-management functions

� I/O functions

� Pipe-management functions

� Configuration/interface functions

� Miscellaneous functions

Connection functionsusbd connect() Connect a client driver to the USB stack.

usbd disconnect()

Disconnect a client driver from the USB stack.

usbd attach() Attach to a USB device.

usbd detach() Detach from a USB device.

Memory-management functionsusbd alloc() Allocate memory area to use for data transfers.

usbd free() Free memory allocated by usbd alloc().

usbd mphys() Get the physical address of memory allocated byusbd alloc().

usbd alloc urb()

Allocate a USB Request Block for subsequentURB-based operations.

usbd free urb() Free the URB allocated by usbd alloc urb().


Functions arranged by category 2004, QNX Software Systems Ltd.

I/O functionsusbd 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() Submit a previously set up URB to the USB stack.

usbd feature() Control a feature for a USB device.

usbd descriptor()

Get USB descriptors.

usbd status() Get specific device status.

Pipe-management functionsusbd open pipe()

Initialize the pipe described by the device or endpointdescriptor.

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 pipehandle.


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 functionsusbd select config()

Select the configuration for a USB device.

usbd select interface()

Select the interface for a USB device.

Miscellaneous/ convenience functionsusbd args lookup()

Look up a driver’s command-line arguments.

usbd configuration descriptor()

Get the configuration descriptor for a specificconfiguration setting.

usbd device lookup()

Map the device instance identifier to an opaquedevice handle (from usbd attach()).

usbd device extra()

Retrieve a pointer to the device-specific extramemory allocated by usbd attach().

usbd device descriptor()

Get the device descriptor for a specific device.


Functions arranged by category 2004, QNX Software Systems Ltd.

usbd endpoint descriptor()

Get the endpoint descriptor for a specific endpointsetting.

usbd get frame()

Get the current frame number and frame length for adevice.

usbd hcd info() Get information on the USB host controller andSDK library.

usbd hub descriptor()

Get the hub descriptor for a specific (hub) device.

usbd interface descriptor()

Get the interface descriptor for a specific interfacesetting.

usbd languages descriptor()

Get the table of supported LANGIDs for the givendevice.

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.


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. Thisfunction can be used during an error condition (e.g. to abort a pendingoperation) or during normal operation (e.g. to halt an isochronoustransfer).

pipe An opaque handle returned by usbd open pipe().

Returns:EOK Success.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

Signal handler No

Thread Yes

See also:usbd open pipe(), usbd close pipe(), usbd pipe endpoint(),usbd reset pipe()


usbd alloc() 2004, QNX Software Systems Ltd.

Allocate memory area to use for data transfers


void *usbd alloc( size t size );

Description:The usbd alloc() function allocates a memory area that can then beused for data transfers. You should use the memory area allocated bythis function, because it’s allocated efficiently and because itsphysical 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 notenough memory.

Errors:ENOMEM Insufficient memory available.


Safety

Cancellation point No


continued. . .


2004, QNX Software Systems Ltd. usbd alloc()

Safety

Signal handler No

Thread Yes

See also:usbd alloc urb(), usbd free(), usbd free urb(), usbd mphys()


usbd alloc urb() 2004, QNX Software Systems Ltd.

Allocate a USB Request Block for subsequent URB-based operations


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. (Not yetimplemented.)

To free the block, use usbd free urb().

Returns:A pointer to the start of the allocated block, or NULL if there’s notenough memory.

Errors:ENOMEM Insufficient memory available.


Safety



Signal handler No

Thread Yes


2004, QNX Software Systems Ltd. usbd alloc urb()

See also:usbd alloc(), usbd free(), usbd free urb(), usbd mphys()


usbd args lookup() 2004, QNX Software Systems Ltd.

Look up a driver’s command-line arguments


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’scommand-line arguments at insertion/attach time.

The command-line arguments are held in argc and argv within theusbd connect parm data structure. See usbd connect() for details.

connection Identifies the USB stack (from usbd connect()).


Safety



Signal handler No

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()


2004, QNX Software Systems Ltd. usbd attach()Attach to a USB device


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 thedevice matched your filter), which will give you the connection andinstance parameters involved. The insertion callback is prototyped asfollows:

void (*insertion)(struct usbd connection *, usbd device instance t *instance)

Here are the parameters:

connection An opaque handle that identifies the USB stack (fromusbd connect()).

instance Describes which device you wish to attach to.

extra The size of additional memory you’d like allocatedwith the device. You can use usbd device extra() laterto get a pointer to this additional memory. Typically,the class driver would store variousstatus/config/device-specific details in here (ifneeded).

device An opaque handle used to identify the device in latercalls.

The usbd device instance t structure looks like this:


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 whichcase 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 youspecified insertion/removal callback functions, then you’ll getexclusive 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, youget shared access, so you can only read device configuration.


ENODEV Specified device doesn’t exist. If in a loop, then there’snothing at that devno. If from a callback, then thedevice has since been removed.

EBUSY A shared/exclusive conflict.

ENOMEM No memory for internal device structures.


2004, QNX Software Systems Ltd. usbd attach()


Safety



Signal handler No

Thread Yes

See also:usbd connect(), usbd detach(), usbd device extra(),usbd disconnect()


usbd close pipe() 2004, QNX Software Systems Ltd.

Close a pipe previously opened by usbd open pipe()


int usbd close pipe( struct usbd pipe *pipe );

Description:You use the usbd close pipe() function to close a pipe that waspreviously opened via usbd open pipe().



EBUSY Active or pending I/O.


Safety



Signal handler No

Thread Yes

See also:usbd abort pipe(), usbd open pipe(), usbd pipe endpoint(),usbd reset pipe()


2004, QNX Software Systems Ltd. usbd configuration descriptor()Get the configuration descriptor for a specific configuration setting


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 theconfiguration descriptor for a specific configuration setting.

device An opaque handle used to identify the USB device.

cfg The device’s configuration identifier(bConfigurationValue).

node Indicates the descriptor’s location for rooting futurerequests (e.g. interfaces of this configuration).

The usbd configuration descriptor t structure looks likethis:

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;


usbd configuration descriptor() 2004, QNX Software Systems Ltd.

Returns:A pointer to usbd configuration descriptor t on success, orNULL on error.


Safety



Signal handler No

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()


2004, QNX Software Systems Ltd. usbd connect()Connect a client driver to the USB stack


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 andto provide insertion/removal callbacks (in theusbd connect parm t data structure).

parm Connection parameters describing how to connect tothe USB stack and how you intend to operate with it.

connection An opaque handle returned on a successfulconnection; it’s used to pass into other routines toidentify the connection.

Data structurestypedef struct usbd connect parm {

const char *path;uint16 vusb;uint16 vusbd;uint32 flags;

int argc;char **argv;uint32 evtbufsz;

usbd device ident t *ident;usbd funcs t *funcs;uint16 connect wait

} usbd connect parm t;

path Name of the stack (NULL means/dev/io-usb/io-usb, the default name).

vusb and vusbd Versions of the USB stack (USB VERSION) andSDK (USBD VERSION).


usbd connect() 2004, QNX Software Systems Ltd.

flags Currently none defined. Pass 0.

argc and argv Command-line arguments to the device driver thatcan be made available via usbd args lookup() atinsertion/attach time.

evtbufsz Size of the event buffer used by the handler threadto buffer events from the USB stack. For thedefault size, pass 0.

ident Identifies the devices you’re interested in receivinginsertion/removal callbacks for (a filter); fields canbe set to USBD CONNECT WILDCARD or to anexplicit value.

funcs The insertion/removal callbacks.

connect wait 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 afilter 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 Called when a device that matches defined filter isdetected.

removal Called when a device is removed.


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 notinterested in receiving dynamic insertion/removal notifications, whichmeans that you won’t be a fully operational class driver. Noasynchronous I/O will be allowed, no event thread, etc. This approachis taken, for example, by the usb display utility.

�


EPROGRAMISMATCH

Versionitis.

ENOMEM No memory for internal connect structures.

ESRCH USB server not running.

EACCESS Permission denied to USB server.

EAGAIN Can’t create async/callback thread.

Examples:A class driver (in its main(), probably) for a 3COM Ethernet cardmight 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 = {


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);


Safety



Signal handler No

Thread Yes

Caveats:The usbd connect() function creates a thread on your behalf that’sused by the library to monitor the USB stack for device insertion orremoval. Since your insertion and removal callback functions arecalled by this new thread, you must ensure that any common


2004, QNX Software Systems Ltd. usbd connect()

resources used between that thread and any other thread(s) in yourclass driver are properly protected (e.g. via a mutex).

See also:usbd args lookup(), usbd attach(), usbd detach(), usbd disconnect()


usbd descriptor() 2004, QNX Software Systems Ltd.

Get USB descriptors.


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.


set A flag that says to either get or set a descriptor.

type Type of descriptor (e.g. USB DESC DEVICE,USB DESC CONFIGURATION, USB DESC STRING,USB DESC HUB).

rtype 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).

index This varies, depending on the request. It’s used for passinga parameter to the device.

langid Identifies the language supported in strings (according tothe LANGID table).

desc Pointer at buffer to put descriptors.

len The length of the data transfer in bytes.


2004, QNX Software Systems Ltd. usbd descriptor()

Returns:EMSGSIZE Buffer too small for descriptor.

ENOMEM No memory for URB.

ENODEV Device was removed.

EIO I/O error on USB device.


Safety



Signal handler No

Thread Yes

See also:usbd feature() usbd io(), usbd setup bulk(), usbd setup control(),usbd setup interrupt(), usbd setup isochronous(),usbd setup vendor(), usbd status()


usbd detach() 2004, QNX Software Systems Ltd.

Detach from the USB device


int usbd detach( struct usbd device *device );

Description:You use the usbd detach() function to disconnect from a USB devicethat you previously had attached to via usbd attach().

The usbd detach() function automatically closes any pipes previouslyopened via usbd open pipe().

device An opaque handle from usbd attach().


EBUSY I/O pending on the device.


Safety



Signal handler No

Thread Yes


2004, QNX Software Systems Ltd. usbd detach()

Caveats:Don’t try to detach if there’s I/O pending on the device. If there is,usbd detach() will fail.

See also:usbd attach(), usbd close pipe(), usbd connect(), usbd disconnect(),usbd open pipe()


usbd device descriptor() 2004, QNX Software Systems Ltd.

Get the device descriptor for a specific device


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 devicedescriptor for a specific device (a handle from usbd attach()).

The node parameter tells you where a descriptor was found to rootfuture 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 NULLon error.


2004, QNX Software Systems Ltd. usbd device descriptor()


Safety



Signal handler No

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()


usbd device extra() 2004, QNX Software Systems Ltd.

Get a pointer to the memory allocated by the extra parameter


void *usbd device extra( struct usbd device *device );

Description:You use the usbd device extra() function to get a pointer to theadditional memory allocated via the extra parameter in usbd attach().

Returns:NULL if no device-specific memory was allocated by usbd attach().


Safety



Signal handler No

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()


2004, QNX Software Systems Ltd. usbd device lookup()Map the device instance identifier to an opaque device handle (from usbd attach())


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 instanceidentifier to an opaque device handle from usbd attach(). This wouldtypically be required in the removal callback.

Returns:An opaque device handle or NULL.


Safety



Signal handler No

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()


usbd disconnect() 2004, QNX Software Systems Ltd.

Disconnect a client driver from the USB stack


int usbd disconnect( struct usbd connection *connection );

Description:You use the usbd disconnect() to disconnect a client driver that hadbeen previously connected to the USB stack via the usbd connect()function.

The usbd disconnect() function automatically closes any pipespreviously opened via usbd attach().




Safety



Signal handler No

Thread Yes


2004, QNX Software Systems Ltd. usbd disconnect()

See also:usbd attach(), usbd connect(), usbd detach()


usbd endpoint descriptor() 2004, QNX Software Systems Ltd.

Get the endpoint descriptor for a specific endpoint setting


usbd endpoint descriptor t*usbd endpoint descriptor(

struct usbd device *device,uint8 config,uint8 iface,uint8 alt,uint8 endpoint,


Description:The usbd endpoint descriptor() function lets you obtain the endpointdescriptor for a specific endpoint on a configuration/interface.


config Configuration identifier (bConfigurationValue).

ifc Interface identifier (bInterfaceNumber).

alt Alternate identifier (bAlternateSetting).

endpoint Endpoint identifier (bEndpointAddress).

node Indicates the descriptor’s location for rooting futurerequests.

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;


2004, QNX Software Systems Ltd. usbd endpoint descriptor()

Returns:A pointer to usbd endpoint descriptor t on success, or NULLon error.


Safety



Signal handler No

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()


usbd feature() 2004, QNX Software Systems Ltd.

Control a feature for a USB device.


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 aUSB device.


set Set or clear a feature on the USB device.

feature A specific feature on the device.


index This varies, depending on the request. It’s used forpassing a parameter to the device.




EIO I/O error on USB device.


2004, QNX Software Systems Ltd. usbd feature()


Safety



Signal handler No

Thread Yes

See also:usbd descriptor(), usbd io(), usbd setup bulk(), usbd setup control(),usbd setup interrupt(), usbd setup isochronous(),usbd setup vendor(), usbd status()


usbd free() 2004, QNX Software Systems Ltd.

Free the memory area allocated by usbd alloc()


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 waspreviously returned by a call to usbd mphys().

It’s safe to call usbd free() with a NULL ptr.



Safety



Signal handler No

Thread Yes

See also:usbd alloc(), usbd alloc urb(), usbd free urb(), usbd mphys()


2004, QNX Software Systems Ltd. usbd free urb()Free the USB Request Block allocated by usbd alloc urb()


struct usbd urb *usbd free urb( struct usbd urb *urb );

Description:The usbd free urb() function frees the memory allocated byusbd alloc urb().



Safety



Signal handler No

Thread Yes

See also:usbd alloc(), usbd alloc urb(), usbd free(), usbd mphys()


usbd get frame() 2004, QNX Software Systems Ltd.

Get the current frame number and frame length for a device

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 aspecific device (a handle from usbd attach()).

fnum If non-NULL, this is set to the frame number.

flen If non-NULL, this is set to the frame length.


ENODEV The device has been removed.


Safety



Signal handler No

Thread Yes


2004, QNX Software Systems Ltd. usbd get frame()

See also:usbd attach()


usbd hcd info() 2004, QNX Software Systems Ltd.

Get information on the USB host controller and SDK library


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 theUSB host controller and SDK library.


cindex Gets information about a specific host controller.

info A pointer to the usbd hcd info t data structure,which is filled in by usbd hcd info(). The structurecontains 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 theUSB stack, the SDK, and the HCD; controller andcapabilities hold the name and capabilities of the USB hostcontroller; ndev contains the number of devices currently connected.


2004, QNX Software Systems Ltd. usbd hcd info()



Safety



Signal handler No

Thread 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()


usbd hub descriptor() 2004, QNX Software Systems Ltd.

Get the hub descriptor for a specific (hub) device


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.



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 onerror.



2004, QNX Software Systems Ltd. usbd hub descriptor()

Safety



Signal handler No

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()


usbd interface descriptor() 2004, QNX Software Systems Ltd.

Get the interface descriptor for a specific interface setting


usbd interface descriptor t*usbd interface descriptor(

struct usbd device *device,uint8 cfg,uint8 ifc,uint8 alt,


Description:The usbd interface descriptor() function lets you obtain the interfacedescriptor for a specific interface setting.





node Indicates the descriptor’s location for rooting futurerequests (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;


2004, QNX Software Systems Ltd. usbd interface descriptor()

Returns:A pointer to usbd interface descriptor t on success, orNULL on error.


Safety



Signal handler No

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()


usbd io() 2004, QNX Software Systems Ltd.

Submit a previously set up URB to the USB stack


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. TheURB would have been set up from one of these functions:

� 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 synchronousonly. Therefore, the func parameter in usbd io() must be NULL.

�

The usbd io() function is the one that actually makes the data transferhappen; the setup functions simply set up the URB for the datatransfer.


func Callback at I/O completion, given URB, pipe, plushandle.

handle User data.

timeout A value (in milliseconds) or USBD TIME DEFAULT orUSBD TIME INFINITY.


2004, QNX Software Systems Ltd. usbd io()

Returns:EBADF Improper usbd connect() call.

EINVAL Improper usbd connect() call.



Safety



Signal handler No

Thread Yes

See also:usbd descriptor(), usbd feature(), usbd setup control(),usbd setup bulk(), usbd setup interrupt(), usbd setup isochronous(),usbd setup vendor(), usbd status()


usbd languages descriptor() 2004, QNX Software Systems Ltd.

Get the table of supported LANGIDs for the given device


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 ofsupported language IDs for the device.



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 onerror.



2004, QNX Software Systems Ltd. usbd languages descriptor()

Safety



Signal handler No

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()


usbd mphys() 2004, QNX Software Systems Ltd.

Get the physical address of memory allocated by usbd alloc()


paddr t usbd mphys( const void *ptr );

Description:The usbd mphys() function obtains the physical address used byusbd alloc() to allocate memory for a data transfer.

Returns:Physical address.


Safety



Signal handler No

Thread Yes

See also:usbd alloc(), usbd alloc urb(), usbd free(), usbd free urb(),usbd mphys()


2004, QNX Software Systems Ltd. usbd open pipe()Initialize the pipe described by the device or endpoint descriptor


int usbd open pipe( struct usbd device *device,usbd descriptors t *desc,struct usbd pipe **pipe );

Description:You use the usbd open pipe() function to initialize the pipe describedby the endpoint descriptor.


desc A pointer to the device or endpoint descriptor that wasreturned from usbd parse descriptors().


Returns:EINVAL Descriptor isn’t device or endpoint.

ENOMEM No memory for internal pipe structures.


Safety



Signal handler No

Thread Yes


usbd open pipe() 2004, QNX Software Systems Ltd.

See also:usbd abort pipe(), usbd close pipe(), usbd pipe endpoint(),usbd reset pipe()


2004, QNX Software Systems Ltd. usbd parse descriptors()Parse device descriptors looking for a specific entry


usbd descriptors t *usbd parse descriptors(struct usbd device *device,struct usbd desc node *root,uint8 type, int index,struct usbd desc node **node );

Description:When called the first time, the usbd parse descriptors() functionloads all the descriptors from the USB device:

� device

� configuration

� interface

� endpoint

� hub

� string

The function uses usdb descriptor() to get each raw USB descriptor.The data is then endian-ized, made alignment-safe, and built into anin-memory tree structure to facilitate future parsing requests.

Each node in this tree is a struct usbd desc node. The root parameterlets you say where in the tree to begin parsing (NULL is base). Thenode parameter tells you where a descriptor was found to root futurerequests from.

The tree looks like this:

(ROOT)|(DEVICE) - (HUB) - (LANGUAGE TABLE)

|(CONFIG) - ..... (CONFIG)


usbd parse descriptors() 2004, QNX Software Systems Ltd.

|(INTERFACE) - ..... (INTERFACE)

|(ENDPOINT) - ..... (ENDPOINT)

Any vendor-specific or class-specific descriptors that are embeddedinto the standard descriptor output are also inserted into this tree at theappropriate point.

Although a descriptor for endpoint 0 (control) isn’t present on thewire, one is constructed and placed in the tree (to simplifyenumeration within the class driver).

You use type for specifying the type of descriptor to find; index is thenth occurrence. Note that type 0 will match any descriptor type; youcan use it to retrieve any embedded class or vendor-specificdescriptors if you don’t know their type.

Here’s an example that will walk all endpoints for an interface:

for (eix = 0; (desc = usbd parse descriptors(device, ifc, USB DESC ENDPOINT,

eix, &ept)) != NULL; ++eix);

where ifc is the appropriate (INTERFACE) node (found by a previouscall to usbd parse descriptors() or usbd interface descriptor().

Returns:A pointer to the descriptor on success, NULL on error.


Safety



Signal handler No

continued. . .


2004, QNX Software Systems Ltd. usbd parse descriptors()

Safety

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 languages descriptor(),usbd string(), usbd urb status()


usbd pipe device() 2004, QNX Software Systems Ltd.

Retrieve the device associated with the pipe


struct usbd device*usbd pipe device( struct usbd pipe *pipe );

Description:You use the usbd pipe device() to retrieve the device associated withpipe (an opaque handle returned by usbd open pipe()).

Returns:A pointer to a usbd device that describes the device.


Safety



Signal handler No

Thread Yes

See also:usbd abort pipe(), usbd open pipe(), usbd close pipe(),usbd reset pipe()


2004, QNX Software Systems Ltd. usbd pipe endpoint()Retrieve the endpoint number associated with the pipe


uint32 usbd pipe endpoint( struct usbd pipe *pipe );

Description:You use the usbd pipe endpoint() to retrieve the endpoint numberassociated with pipe (an opaque handle returned byusbd open pipe()).

Returns:A pipe/endpoint number.


Safety



Signal handler No

Thread Yes

See also:usbd abort pipe(), usbd open pipe(), usbd close pipe(),usbd reset pipe()


usbd reset device() 2004, QNX Software Systems Ltd.

Reset a USB device


int usbd reset device( struct usbd device *device );

Description:You use the usbd reset device() function to reset the specified device.




Safety



Signal handler No

Thread Yes

See also:usbd attach(), usbd connect()


2004, QNX Software Systems Ltd. usbd reset pipe()Clear a stall condition on an endpoint identified by the pipe handle


int usbd reset pipe( struct usbd pipe *pipe );

Description:You use the usbd reset pipe() function to clear a stall condition on anendpoint identified by the pipe handle.





Safety



Signal handler No

Thread Yes

See also:usbd abort pipe() usbd open pipe(), usbd close pipe(),usbd pipe endpoint(),


usbd select config() 2004, QNX Software Systems Ltd.

Select the configuration for a USB device


int usbd select config( struct usbd device *device,uint8 cfg );

Description:You use the usbd select config() function to select the configurationfor a USB device.







Safety



Signal handler No

Thread Yes


2004, QNX Software Systems Ltd. usbd select config()

See also:usbd select interface()


usbd select interface() 2004, QNX Software Systems Ltd.

Select the interface for a USB device


int usbd select interface( struct usbd device *device,uint8 ifc, uint8 alt );

Description:You use the usbd select interface() function to select the interface fora USB device.








Safety



Signal handler No

Thread Yes


2004, QNX Software Systems Ltd. usbd select interface()

See also:usbd select config()


usbd setup bulk() 2004, QNX Software Systems Ltd.

Set up a URB for a bulk data transfer


int usbd setup bulk( struct usbd urb *urb,uint32 flags, void *addr,uint32 len );

Description:This routine sets up a URB for a bulk data transfer.

urb An opaque handle (from usbd alloc urb()).

flags One of the following:

� URB DIR IN — Specify incoming (device-to-PC)transfer.

� URB DIR OUT — Specify outgoing (PC-to-device)transfer.

� URB DIR NONE — Don’t specify direction.

� URB SHORT XFER OK — Allow short transfers.

addr Address for start of transfer — you must use the bufferallocated by usbd alloc().

len The length (in bytes) of the data transfer.




2004, QNX Software Systems Ltd. usbd setup bulk()

Safety



Signal handler No

Thread Yes

Caveats:To ensure that the correct physical address will be used, you must usethe buffer allocated by usbd alloc() for the addr parameter.

See also:usbd descriptor(), usbd feature(), usbd io(), usbd setup control(),usbd setup interrupt(), usbd setup isochronous(),usbd setup vendor(), usbd status()


usbd setup control() 2004, QNX Software Systems Ltd.

Set up a URB for a control transfer

Synopsis:CAUTION: This function is still under development --- its synopsisand other details shown here may change significantly!!

#include <sys/usbdi.h>

usbd setup control( struct usbd urb *urb, uint32 flags, uint16request, uint16 rtype, uint16 value, uint16 index, void *addr,

uint32 len );

Description:This routine sets up a URB for a control transfer.







request A device-specific request.


value This varies, depending on the request. It’s used forpassing a parameter to the device.



2004, QNX Software Systems Ltd. usbd setup control()





Safety



Signal handler No

Thread Yes


See also:usbd descriptor(), usbd feature(), usbd io(), usbd setup bulk(),usbd setup interrupt(), usbd setup isochronous(),usbd setup vendor(), usbd status()


usbd setup interrupt() 2004, QNX Software Systems Ltd.

Set up a URB for an interrupt transfer


int usbd setup interrupt( struct usbd urb *urb,uint32 flags,

void *addr,uint32 len );

Description:This routine sets up a URB for an interrupt transfer.












2004, QNX Software Systems Ltd. usbd setup interrupt()

Safety



Signal handler No

Thread Yes

See also:usbd setup bulk(), usbd setup control(), usbd setup isochronous(),usbd setup vendor()


usbd setup isochronous() 2004, QNX Software Systems Ltd.

Set up a URB for an isochronous transfer

Synopsis:CAUTION: This function is still under development - its synopsisand other details shown here may change significantly!!

#include <sys/usbdi.h>

int usbd setup isochronous( struct usbd urb *urb,uint32 flags,int32 frame,void *addr,uint32 len );

Description:This routine sets up a URB for an isochronous transfer.






� URB ISOCH ASAP — Allow transfer as soon as possible(overrides frame).


frame The device frame number. This is ignored ifURB ISOCH ASAP is set.




2004, QNX Software Systems Ltd. usbd setup isochronous()



Safety



Signal handler No

Thread Yes

See also:usbd descriptor(), usbd feature(), usbd io(), usbd setup bulk(),usbd setup control(), usbd setup interrupt(), usbd setup vendor(),usbd status()


usbd setup vendor() 2004, QNX Software Systems Ltd.

Set up a URB for a vendor-specific transfer


int usbd setup vendor( struct usbd urb *urb,uint32 flags, uint16 request,uint16 rtype, uint16 value,uint16 index, void *addr,uint32 len );

Description:This routine sets up a URB for a vendor-specific transfer.

For this release of the USB SDK, vendor requests are synchronousonly. Therefore, the func parameter in usbd io() must be NULL.

�







request A device-specific request.


value This varies, depending on the request. It’s used forpassing a parameter to the device.


2004, QNX Software Systems Ltd. usbd setup vendor()






Safety



Signal handler No

Thread Yes


See also:usbd descriptor(), usbd feature(), usbd io(), usbd setup bulk(),usbd setup control(), usbd setup interrupt(),usbd setup isochronous(), usbd status()


usbd status() 2004, QNX Software Systems Ltd.

Get specific device status


int usbd status( struct usbd device *device,uint16 rtype, uint16 index,void *addr, uint32 len )

Description:You use the usbd status() function to get specific device status.



index This varies, depending on the request. It’s used for passinga parameter to the device.




EMSGSIZE Buffer too small for descriptor.




2004, QNX Software Systems Ltd. usbd status()


Safety



Signal handler No

Thread Yes

See also:usbd descriptor(), usbd feature(), usbd io(), usbd setup bulk(),usbd setup control(), usbd setup interrupt(),usbd setup isochronous(), usbd setup vendor()


usbd string() 2004, QNX Software Systems Ltd.

Get a string descriptor


char *usbd string( struct usbd device *device,uint8 index,

int langid );

Description:The usbd string() function lets you obtain a string from the USBdevice’s table of strings.

Typically, the string table may contain the names of the vendor, theproduct, etc. The string table is optional.


index Index into the device’s (optional) string table.

langid Language ID. The usbd languages descriptor() functionprovides the supported langids for the device. If youspecify 0, the usbd string() function will select thefirst/only supported language.

Note that the strings are actually in Unicode/wide characters, sousb string() also conveniently converts them to UTF-8 (byte stream)for you.

Note that usbd string() places the result string in a static buffer that’sreused every time the function is called.

Returns:A pointer to the string in an internal static buffer, or NULL on error.


2004, QNX Software Systems Ltd. usbd string()


Safety



Signal handler No

Thread No

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 languages descriptor(),usbd parse descriptors(), usbd urb status()


usbd topology() 2004, QNX Software Systems Ltd.

Get the USB bus physical topology


int usbd topology( struct usbd connection *connection,usbd bus topology t *tp )

Description:You use the usbd topology() function to get the USB bus physicaltopology.

For more information on USB bus topology, see sections 4.1.1 and5.2.3 in the USB Specification v1.1.

�

Here are the parameters:

connection An opaque handle that identifies the USB stack (fromusbd connect()).

tp A pointer to the usbd bus topology t datastructure, which is filled in by usbd topology().

The usbd bus topology t structure contains at least thefollowing:

typedef struct usbd port attachment {uint8 upstream devno;uint8 upstream port;uint8 upstream port speed;

} usbd port attachment t;

typedef struct usbd bus topology {usbd port attachment t ports[64];

} usbd bus topology t;

The structure contains an array of usb port attachments, one perdevice. Note that the upstream devno field will contain a value otherthan 0xff to indicate a valid attachment.


2004, QNX Software Systems Ltd. usbd topology()




Safety



Signal handler No

Thread Yes

See also:usbd connect()


usbd urb status() 2004, QNX Software Systems Ltd.

Return status information on a URB


int usbd urb status( struct usbd urb *urb,uint32 *status,uint32 *len )

Description:You use the usbd urb status() function to extract completion statusand data-transfer length from a URB.


status Completion status (see below).

len The actual length (in bytes) of the data transfer.

Completion status

The status field contains the completion status information, whichincludes the following flags:

USBD STATUS INPROG

The operation is in progress.

USBD STATUS CMP

The operation is complete.

USBD STATUS CMP ERR

The operation is complete, but an error occurred.

USBD STATUS TIMEOUT

The operation timed out.

USBD STATUS ABORTED

The operation aborted.


2004, QNX Software Systems Ltd. usbd urb status()

USBD STATUS CRC ERR

The last packet from the endpoint contained a CRC error.

USBD STATUS BITSTUFFING

The last packet from the endpoint contained a bit-stuffingviolation.

USBD STATUS TOGGLE MISMATCH

The last packet from the endpoint had the wrong data-togglePID.

USBD STATUS STALL

The endpoint returned a STALL PID.

USBD STATUS DEV NOANSWER

Device didn’t respond to token (IN) or didn’t provide ahandshake (OUT).

USBD STATUS PID FAILURE

Check bits on PID from endpoint failed on data PID (IN) orhandshake (OUT).

USBD STATUS BAD PID

Receive PID was invalid or undefined.

USBD STATUS DATA OVERRUN

The endpoint returned more data than the allowable maximum.

USBD STATUS DATA UNDERRUN

The endpoint didn’t return enough data to fill the specifiedbuffer.

USBD STATUS BUFFER OVERRUN

During an IN, the host controller received data from theendpoint faster than it could be written to system memory.

USBD STATUS BUFFER UNDERRUN

During an OUT, the host controller couldn’t retrieve data fastenough.


usbd urb status() 2004, QNX Software Systems Ltd.

USBD STATUS NOT ACCESSED

Controller didn’t execute request.


EBUSY URB I/O still active.

ETIMEDOUT Timeout occurred.

EINTR Operation aborted/interrupted.

ENODEV Device removed.

EIO I/O error.


Safety



Signal handler No

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 languages descriptor(),usbd parse descriptors(), usbd string()


Index

A

assumptions ix

C

callbacks 10, 30, 36class driver

typical operations 10

D

data buffers 9

I

insertion/removal 10, 30, 36, 37

L

looping, as alternate method ofattaching 30

P

pipenot a UNIX term in this doc 11

S

shared memory 9

U

USBlink to www.usb.org xSpecification revision 2.0 ix

usbd abort pipe() 23usbd alloc() 24

May 31, 2004 Index 101

Index 2004, QNX Software Systems Ltd.

usbd alloc urb() 26usbd args lookup() 28usbd attach() 29usbd close pipe() 32usbd configuration descriptor() 33usbd connect() 35

data structures 35usbd descriptor() 40usbd detach() 42usbd device descriptor() 44usbd device extra() 46usbd device lookup() 47usbd disconnect() 48usbd endpoint descriptor() 50usbd feature() 52usbd free() 54usbd free urb() 55usbd get frame() 56usbd hcd info() 58usbd hub descriptor() 60usbd interface descriptor() 62usbd io() 64usbd languages descriptor() 66usbd mphys() 68usbd open pipe() 69usbd parse descriptors() 71usbd pipe device() 74usbd pipe endpoint() 75usbd reset device() 76usbd reset pipe() 77usbd select config() 78usbd select interface() 80usbd setup bulk() 82usbd setup control() 84usbd setup interrupt() 86usbd setup isochronous() 88usbd setup vendor() 90

usbd status() 92usbd string() 94usbd topology() 96usbd urb status() 98

102 Index May 31, 2004

QNX Momentics - photon.qnx.comphoton.qnx.com/download/download/9367/ddk_usb.pdfQNX Momentics DDK...

Documents

Transcript of QNX Momentics - photon.qnx.comphoton.qnx.com/download/download/9367/ddk_usb.pdfQNX Momentics DDK...