QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ......

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

Transcript of QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ......

Page 1: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

QNX Momentics DDK

Universal Serial Bus (USB) Devices

For QNX Neutrino 6.3.0 or QNX 4

2005, QNX Software Systems Ltd.

Page 2: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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 – 2005, QNX Software Systems Ltd. All rights reserved.

Publishing history

Electronic edition published February 2005.

Technical support options

To obtain technical support for any QNX product, visit theTechnical Support section in theServices 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.

Page 3: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

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

Connection functions 19

February 1, 2005 Contents iii

Page 4: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd.

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

usbd parse descriptors() 71

iv Contents February 1, 2005

Page 5: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd.

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

February 1, 2005 Contents v

Page 6: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This
Page 7: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

About the USB DDK

February 1, 2005 About the USB DDK vii

Page 8: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This
Page 9: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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.

February 1, 2005 About the USB DDK ix

Page 10: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

Building DDKs 2005, 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 theIDE 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 the DDK looks like this:

x About the USB DDK February 1, 2005

Page 11: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd. Building DDKs

prebuilt install src

ddk_install_dir

platforms

mouse

printer

keyboard

devu

hardware

includeclass

Directory structure for this DDK.

February 1, 2005 About the USB DDK xi

Page 12: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

Building DDKs 2005, QNX Software Systems Ltd.

You must run:. ./setenv.sh

before runningmake, ormake install.

You’ll need to run this script once each time you start a new shellsession because the shell needs to be initialized before you cancompile the archive.

The script will be located in the same directory where youunzipped the archive file. It must be run in such a way that itmodifies the current shell’s environment, not a sub-shellenvironment.

In ksh andbash shells, all shell scripts are executed in a sub-shellby default. Therefore, it’s important that you use the syntax. <script>

which will prevent a sub-shell from being used.

Each DDK is rooted in whatever directory you copy it to. If youtypemake within this directory, you’ll generate all of the buildableentities within that DDK no matter where you move the directory.

All binaries are placed in a scratch area within the DDK directorythat mimics the layout of a target system.

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 theinstall directory. The binaries arebuilt from the source using include files and link libraries in theinstall directory.

xii About the USB DDK February 1, 2005

Page 13: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

Chapter 1

Before You Begin

In this chapter. . .System requirements 3USB devices supported 3Known limitations 4

February 1, 2005 Chapter 1 � Before You Begin 1

Page 14: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This
Page 15: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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. . .

February 1, 2005 Chapter 1 � Before You Begin 3

Page 16: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

Known limitations 2005, 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 February 1, 2005

Page 17: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd. Known limitations

CAUTION: Make sure that the command line fordevi-hirun (orInput) includes the option tonot 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.

!

February 1, 2005 Chapter 1 � Before You Begin 5

Page 18: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This
Page 19: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

Chapter 2

Overview

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

February 1, 2005 Chapter 2 � Overview 7

Page 20: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This
Page 21: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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), anddevu-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 drivermust reside on the same physical node as theUSB stack. Theclients 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).

February 1, 2005 Chapter 2 � Overview 9

Page 22: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

How a class driver works 2005, 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 withio-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 February 1, 2005

Page 23: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

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

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

February 1, 2005 Chapter 2 � Overview 11

Page 24: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This
Page 25: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

Chapter 3

USB Utilities

February 1, 2005 Chapter 3 � USB Utilities 13

Page 26: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This
Page 27: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd.

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.

February 1, 2005 Chapter 3 � USB Utilities 15

Page 28: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This
Page 29: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

February 1, 2005 Chapter 4 � USB Library Reference 17

Page 30: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd.

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 February 1, 2005

Page 31: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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 byusbd 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 byusbd alloc urb().

February 1, 2005 Chapter 4 � USB Library Reference 19

Page 32: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

Functions arranged by category 2005, 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 theusbd open pipe()function.

usbd reset pipe()

Clear a stall condition on an endpoint identified by thepipehandle.

20 Chapter 4 � USB Library Reference February 1, 2005

Page 33: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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 (fromusbd attach()).

usbd device extra()

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

usbd device descriptor()

Get the device descriptor for a specific device.

February 1, 2005 Chapter 4 � USB Library Reference 21

Page 34: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

Functions arranged by category 2005, 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.

22 Chapter 4 � USB Library Reference February 1, 2005

Page 35: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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:Theusbd 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 byusbd 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()

February 1, 2005 Chapter 4 � USB Library Reference 23

Page 36: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd alloc() 2005, QNX Software Systems Ltd.

Allocate memory area to use for data transfers

Synopsis:#include <sys/usbdi.h>

void *usbd alloc( size t size );

Description:Theusbd 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 viausbd mphys().

Theusbd setup *() functions requireusbd alloc()’d data buffers.☞

size Size (in bytes) of the area to be allocated.

To free the memory, useusbd free().

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

Errors:ENOMEM Insufficient memory available.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

continued. . .

24 Chapter 4 � USB Library Reference February 1, 2005

Page 37: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd. usbd alloc()

Safety

Signal handler No

Thread Yes

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

February 1, 2005 Chapter 4 � USB Library Reference 25

Page 38: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Allocate a USB Request Block for subsequent URB-based operations

Synopsis:#include <sys/usbdi.h>

struct usbd urb *usbd alloc urb( struct usbd urb *link );

Description:Theusbd 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, useusbd free urb().

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

Errors:ENOMEM Insufficient memory available.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

Signal handler No

Thread Yes

26 Chapter 4 � USB Library Reference February 1, 2005

Page 39: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

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

February 1, 2005 Chapter 4 � USB Library Reference 27

Page 40: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Look up a driver’s command-line arguments

Synopsis:#include <sys/usbdi.h>

void usbd args lookup(struct usbd connection *connection,int *argc,char ***argv );

Description:Theusbd args lookup() function lets you look up a device driver’scommand-line arguments at insertion/attach time.

The command-line arguments are held inargc andargv within theusbd connect parm data structure. Seeusbd connect() for details.

connection Identifies the USB stack (fromusbd connect()).

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

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

28 Chapter 4 � USB Library Reference February 1, 2005

Page 41: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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 theusbd 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 theconnection 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 useusbd 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.

Theusbd device instance t structure looks like this:

February 1, 2005 Chapter 4 � USB Library Reference 29

Page 42: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd attach() 2005, 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 toall devices (in whichcase you build theinstance 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, yougetshared access, so you can only read device configuration.

Returns:EOK Success.

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

EBUSY A shared/exclusive conflict.

ENOMEM No memory for internal device structures.

30 Chapter 4 � USB Library Reference February 1, 2005

Page 43: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd. usbd attach()

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

Signal handler No

Thread Yes

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

February 1, 2005 Chapter 4 � USB Library Reference 31

Page 44: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Close a pipe previously opened by usbd open pipe()

Synopsis:#include <sys/usbdi.h>

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

Description:You use theusbd close pipe() function to close a pipe that waspreviously opened viausbd open pipe().

pipe An opaque handle returned byusbd open pipe().

Returns:EOK Success.

EBUSY Active or pending I/O.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

Signal handler No

Thread Yes

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

32 Chapter 4 � USB Library Reference February 1, 2005

Page 45: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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:Theusbd 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).

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

February 1, 2005 Chapter 4 � USB Library Reference 33

Page 46: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

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

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

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

34 Chapter 4 � USB Library Reference February 1, 2005

Page 47: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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 theusbd 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 andvusbd Versions of the USB stack (USB VERSION) andSDK (USBD VERSION).

February 1, 2005 Chapter 4 � USB Library Reference 35

Page 48: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd connect() 2005, QNX Software Systems Ltd.

flags Currently none defined. Pass 0.

argc andargv Command-line arguments to the device driver thatcan be made available viausbd 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 toUSBD CONNECT WILDCARD or to anexplicit value.

funcs The insertion/removal callbacks.

connect wait A value (in seconds) orUSBD 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 theusbd 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.

36 Chapter 4 � USB Library Reference February 1, 2005

Page 49: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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 intonentries.

By passing NULL as theusbd 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 theusb display utility.

Returns:EOK Success.

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 itsmain(), 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 = {

February 1, 2005 Chapter 4 � USB Library Reference 37

Page 50: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd connect() 2005, 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 Yes

Interrupt handler No

Signal handler No

Thread Yes

Caveats:Theusbd 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, youmust ensure that any common

38 Chapter 4 � USB Library Reference February 1, 2005

Page 51: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

February 1, 2005 Chapter 4 � USB Library Reference 39

Page 52: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd descriptor() 2005, QNX Software Systems Ltd.

Get USB descriptors.

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:Theusbd descriptor() function lets you obtain the USB descriptors.

device An opaque handle used to identify the USB device.

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.

40 Chapter 4 � USB Library Reference February 1, 2005

Page 53: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 41

Page 54: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd detach() 2005, QNX Software Systems Ltd.

Detach from the USB device

Synopsis:#include <sys/usbdi.h>

int usbd detach( struct usbd device *device );

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

Theusbd detach() function automatically closes any pipes previouslyopened viausbd open pipe().

device An opaque handle fromusbd attach().

Returns:EOK Success.

EBUSY I/O pending on the device.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

Signal handler No

Thread Yes

42 Chapter 4 � USB Library Reference February 1, 2005

Page 55: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

February 1, 2005 Chapter 4 � USB Library Reference 43

Page 56: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Get the device descriptor for a specific device

Synopsis:#include <sys/usbdi.h>

usbd device descriptor t*usbd device descriptor(

struct usbd device *device,struct usbd desc node **node );

Description:Theusbd device descriptor() function lets you obtain the devicedescriptor for a specificdevice (a handle fromusbd attach()).

Thenode parameter tells you where a descriptor was found to rootfuture requests from (e.g. configurations of the device).

Theusbd 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 tousbd device descriptor t on success, or NULLon error.

44 Chapter 4 � USB Library Reference February 1, 2005

Page 57: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 45

Page 58: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Get a pointer to the memory allocated by the extra parameter

Synopsis:#include <sys/usbdi.h>

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

Description:You use theusbd device extra() function to get a pointer to theadditional memory allocated via theextra parameter inusbd attach().

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

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

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

46 Chapter 4 � USB Library Reference February 1, 2005

Page 59: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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 theusbd device lookup() function to map the device instanceidentifier to an opaque device handle fromusbd attach(). This wouldtypically be required in the removal callback.

Returns:An opaque device handle or NULL.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 47

Page 60: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd disconnect() 2005, QNX Software Systems Ltd.

Disconnect a client driver from the USB stack

Synopsis:#include <sys/usbdi.h>

int usbd disconnect( struct usbd connection *connection );

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

Theusbd disconnect() function automatically closes any pipespreviously opened viausbd attach().

connection Identifies the USB stack (fromusbd connect()).

Returns:EOK Success.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

Signal handler No

Thread Yes

48 Chapter 4 � USB Library Reference February 1, 2005

Page 61: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd. usbd disconnect()

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

February 1, 2005 Chapter 4 � USB Library Reference 49

Page 62: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Get the endpoint descriptor for a specific endpoint setting

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:Theusbd endpoint descriptor() function lets you obtain the endpointdescriptor for a specific endpoint on a configuration/interface.

device An opaque handle used to identify the USB device.

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.

Theendpoint 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 � USB Library Reference February 1, 2005

Page 63: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

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

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 51

Page 64: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd feature() 2005, QNX Software Systems Ltd.

Control a feature for a USB device.

Synopsis:#include <sys/usbdi.h>

int usbd feature( struct usbd device *device,int set, uint16 feature,uint16 rtype, uint16 index );

Description:Theusbd feature() function lets you control a specific feature on aUSB device.

device An opaque handle used to identify the USB device.

set Set or clear a feature on the USB device.

feature A specific feature on the device.

rtype Type of request (e.g.USB RECIPIENTDEVICE,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 forpassing a parameter to the device.

Returns:EOK Success.

ENOMEM No memory for URB.

ENODEV Device was removed.

EIO I/O error on USB device.

52 Chapter 4 � USB Library Reference February 1, 2005

Page 65: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd. usbd feature()

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 53

Page 66: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd free() 2005, QNX Software Systems Ltd.

Free the memory area allocated by usbd alloc()

Synopsis:#include <sys/usbdi.h>

void usbd free( void* ptr );

Description:Theusbd free() function frees the memory allocated byusbd alloc().The function deallocates the memory area specified byptr, which waspreviously returned by a call tousbd mphys().

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

Returns:EOK Success.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

Signal handler No

Thread Yes

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

54 Chapter 4 � USB Library Reference February 1, 2005

Page 67: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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:Theusbd free urb() function frees the memory allocated byusbd alloc urb().

Returns:EOK Success.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

Signal handler No

Thread Yes

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

February 1, 2005 Chapter 4 � USB Library Reference 55

Page 68: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd get frame() 2005, 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 aspecificdevice (a handle fromusbd attach()).

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

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

Returns:EOK Success.

ENODEV The device has been removed.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

Signal handler No

Thread Yes

56 Chapter 4 � USB Library Reference February 1, 2005

Page 69: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

See also:usbd attach()

February 1, 2005 Chapter 4 � USB Library Reference 57

Page 70: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Get information on the USB host controller and SDK library

Synopsis:#include <sys/usbdi.h>

int usbd hcd info( struct usbd connection *connection,uint32 cindex, usbd hcd info t *info );

Description:You use theusbd hcd info() function to obtain information from theUSB host controller and SDK library.

connection Identifies the USB stack (fromusbd connect()).

cindex Gets information about a specific host controller.

info A pointer to theusbd hcd info t data structure,which is filled in byusbd 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;

Thevusb, vusbd, andvhcd 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.

58 Chapter 4 � USB Library Reference February 1, 2005

Page 71: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Returns:EOK Success.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 59

Page 72: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Get the hub descriptor for a specific (hub) device

Synopsis:#include <sys/usbdi.h>

usbd hub descriptor t *usbd hub descriptor(struct usbd device *device,struct usbd desc node **node );

Description:Theusbd hub descriptor() function lets you obtain a hub descriptor.

device An opaque handle used to identify the USB device.

node Indicates the descriptor’s location for rooting futurerequests.

Theusbd 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 tousbd hub descriptor t on success, or NULL onerror.

Classification:QNX Neutrino, QNX 4

60 Chapter 4 � USB Library Reference February 1, 2005

Page 73: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Safety

Cancellation point No

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 61

Page 74: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Get the interface descriptor for a specific interface setting

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:Theusbd interface descriptor() function lets you obtain the interfacedescriptor for a specific interface setting.

device An opaque handle used to identify the USB device.

cfg The device’s configuration identifier(bConfigurationValue).

ifc Interface identifier (bInterfaceNumber).

alt Alternate identifier (bAlternateSetting).

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

Theusbd 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 � USB Library Reference February 1, 2005

Page 75: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

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

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 63

Page 76: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd io() 2005, QNX Software Systems Ltd.

Submit a previously set up URB to the USB stack

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. 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 aresynchronousonly. Therefore, thefunc parameter inusbd io() must be NULL.

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

pipe An opaque handle returned byusbd open pipe().

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

handle User data.

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

64 Chapter 4 � USB Library Reference February 1, 2005

Page 77: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd. usbd io()

Returns:EBADF Improperusbd connect() call.

EINVAL Improperusbd connect() call.

ENODEV Device was removed.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 65

Page 78: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Get the table of supported LANGIDs for the given device

Synopsis:#include <sys/usbdi.h>

usbd string descriptor t*usbd languages descriptor(struct usbd device *device,struct usbd desc node **node );

Description:Theusbd languages descriptor() function lets you obtain the table ofsupported language IDs for the device.

device An opaque handle used to identify the USB device.

node Indicates the descriptor’s location for rooting futurerequests.

Theusbd 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 pointerusbd string descriptor t on success, NULL onerror.

Classification:QNX Neutrino, QNX 4

66 Chapter 4 � USB Library Reference February 1, 2005

Page 79: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Safety

Cancellation point No

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 67

Page 80: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd mphys() 2005, QNX Software Systems Ltd.

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

Synopsis:#include <sys/usbdi.h>

paddr t usbd mphys( const void *ptr );

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

Returns:Physical address.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

Signal handler No

Thread Yes

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

68 Chapter 4 � USB Library Reference February 1, 2005

Page 81: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Synopsis:#include <sys/usbdi.h>

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

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

device An opaque handle used to identify the USB device.

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

pipe An opaque handle returned byusbd open pipe().

Returns:EINVAL Descriptor isn’t device or endpoint.

ENOMEM No memory for internal pipe structures.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

Signal handler No

Thread Yes

February 1, 2005 Chapter 4 � USB Library Reference 69

Page 82: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

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

70 Chapter 4 � USB Library Reference February 1, 2005

Page 83: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Synopsis:#include <sys/usbdi.h>

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, theusbd parse descriptors() functionloads all the descriptors from the USB device:

� device

� configuration

� interface

� endpoint

� hub

� string

The function usesusdb 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 astruct usbddescnode. Theroot 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)

February 1, 2005 Chapter 4 � USB Library Reference 71

Page 84: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd parse descriptors() 2005, 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 usetype 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 retrieveany 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);

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

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

Signal handler No

continued. . .

72 Chapter 4 � USB Library Reference February 1, 2005

Page 85: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

February 1, 2005 Chapter 4 � USB Library Reference 73

Page 86: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Retrieve the device associated with the pipe

Synopsis:#include <sys/usbdi.h>

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

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

Returns:A pointer to ausbd device that describes the device.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

Signal handler No

Thread Yes

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

74 Chapter 4 � USB Library Reference February 1, 2005

Page 87: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Synopsis:#include <sys/usbdi.h>

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

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

Returns:A pipe/endpoint number.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

Signal handler No

Thread Yes

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

February 1, 2005 Chapter 4 � USB Library Reference 75

Page 88: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Reset a USB device

Synopsis:#include <sys/usbdi.h>

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

Description:You use theusbd reset device() function to reset the specifieddevice.

Returns:EOK Success.

ENODEV Device was removed.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

Signal handler No

Thread Yes

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

76 Chapter 4 � USB Library Reference February 1, 2005

Page 89: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Synopsis:#include <sys/usbdi.h>

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

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

Returns:EOK Success.

ENOMEM No memory for URB.

ENODEV Device was removed.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

Signal handler No

Thread Yes

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

February 1, 2005 Chapter 4 � USB Library Reference 77

Page 90: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Select the configuration for a USB device

Synopsis:#include <sys/usbdi.h>

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

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

device An opaque handle used to identify the USB device.

cfg The device’s configuration identifier(bConfigurationValue).

Returns:EOK Success.

ENOMEM No memory for URB.

ENODEV Device was removed.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

Signal handler No

Thread Yes

78 Chapter 4 � USB Library Reference February 1, 2005

Page 91: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

See also:usbd select interface()

February 1, 2005 Chapter 4 � USB Library Reference 79

Page 92: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Select the interface for a USB device

Synopsis:#include <sys/usbdi.h>

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

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

device An opaque handle used to identify the USB device.

ifc Interface identifier (bInterfaceNumber).

alt Alternate identifier (bAlternateSetting).

Returns:EOK Success.

ENOMEM No memory for URB.

ENODEV Device was removed.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

Signal handler No

Thread Yes

80 Chapter 4 � USB Library Reference February 1, 2005

Page 93: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

See also:usbd select config()

February 1, 2005 Chapter 4 � USB Library Reference 81

Page 94: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Set up a URB for a bulk data transfer

Synopsis:#include <sys/usbdi.h>

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 (fromusbd 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 — youmust use the bufferallocated byusbd alloc().

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

Returns:EOK Success.

Classification:QNX Neutrino, QNX 4

82 Chapter 4 � USB Library Reference February 1, 2005

Page 95: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Safety

Cancellation point No

Interrupt handler No

Signal handler No

Thread Yes

Caveats:To ensure that the correct physical address will be used, youmust usethe buffer allocated byusbd alloc() for theaddr parameter.

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

February 1, 2005 Chapter 4 � USB Library Reference 83

Page 96: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd setup control() 2005, 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 usbdurb *urb, uint32flags, uint16request, uint16rtype, uint16value, uint16index, void *addr,uint32len );

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

urb An opaque handle (fromusbd 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.

request A device-specific request.

rtype Type of request (e.g.USB RECIPIENT DEVICE,USB RECIPIENTINTERFACE,USB RECIPIENTENDPOINT, USB RECIPIENT OTHER,USB TYPE STANDARD, USB TYPE CLASS,USB TYPE VENDOR).

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

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

84 Chapter 4 � USB Library Reference February 1, 2005

Page 97: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

addr Address for start of transfer — youmust use the bufferallocated byusbd alloc().

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

Returns:EOK Success.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

Signal handler No

Thread Yes

Caveats:To ensure that the correct physical address will be used, youmust usethe buffer allocated byusbd alloc() for theaddr parameter.

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

February 1, 2005 Chapter 4 � USB Library Reference 85

Page 98: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Set up a URB for an interrupt transfer

Synopsis:#include <sys/usbdi.h>

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.

urb An opaque handle (fromusbd 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 — youmust use the bufferallocated byusbd alloc().

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

Returns:EOK Success.

Classification:QNX Neutrino, QNX 4

86 Chapter 4 � USB Library Reference February 1, 2005

Page 99: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Safety

Cancellation point No

Interrupt handler No

Signal handler No

Thread Yes

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

February 1, 2005 Chapter 4 � USB Library Reference 87

Page 100: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd setup isochronous() 2005, 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 An opaque handle (fromusbd 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 ISOCH ASAP — Allow transfer as soon as possible(overridesframe).

� URB SHORT XFER OK — Allow short transfers.

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

addr Address for start of transfer — youmust use the bufferallocated byusbd alloc().

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

88 Chapter 4 � USB Library Reference February 1, 2005

Page 101: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Returns:EOK Success.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 89

Page 102: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Set up a URB for a vendor-specific transfer

Synopsis:#include <sys/usbdi.h>

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 aresynchronousonly. Therefore, thefunc parameter inusbd io() must be NULL.

urb An opaque handle (fromusbd 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.

request A device-specific request.

rtype Type of request (e.g.USB RECIPIENT DEVICE,USB RECIPIENTINTERFACE,USB RECIPIENTENDPOINT, USB RECIPIENT OTHER,USB TYPE STANDARD, USB TYPE CLASS,USB TYPE VENDOR).

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

90 Chapter 4 � USB Library Reference February 1, 2005

Page 103: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

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

addr Address for start of transfer — youmust use the bufferallocated byusbd alloc().

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

Returns:EOK Success.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

Signal handler No

Thread Yes

Caveats:To ensure that the correct physical address will be used, youmust usethe buffer allocated byusbd alloc() for theaddr parameter.

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

February 1, 2005 Chapter 4 � USB Library Reference 91

Page 104: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd status() 2005, QNX Software Systems Ltd.

Get specific device status

Synopsis:#include <sys/usbdi.h>

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

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

device An opaque handle used to identify the USB device.

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.

addr Address for start of transfer — youmust use the bufferallocated byusbd alloc().

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

Returns:EOK Success.

EMSGSIZE Buffer too small for descriptor.

ENOMEM No memory for URB.

ENODEV Device was removed.

92 Chapter 4 � USB Library Reference February 1, 2005

Page 105: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd. usbd status()

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 93

Page 106: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd string() 2005, QNX Software Systems Ltd.

Get a string descriptor

Synopsis:#include <sys/usbdi.h>

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

int langid );

Description:Theusbd 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.

device An opaque handle used to identify the USB device.

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

langid Language ID. Theusbd languages descriptor() functionprovides the supportedlangids for the device. If youspecify 0, theusbd 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 thatusbd 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.

94 Chapter 4 � USB Library Reference February 1, 2005

Page 107: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd. usbd string()

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

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

February 1, 2005 Chapter 4 � USB Library Reference 95

Page 108: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

usbd topology() 2005, QNX Software Systems Ltd.

Get the USB bus physical topology

Synopsis:#include <sys/usbdi.h>

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

Description:You use theusbd 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 theusbd bus topology t datastructure, which is filled in byusbd topology().

Theusbd 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 ofusb port attachments, one perdevice. Note that theupstream devno field will contain a value otherthan0xff to indicate a valid attachment.

96 Chapter 4 � USB Library Reference February 1, 2005

Page 109: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, QNX Software Systems Ltd. usbd topology()

Returns:EOK Success.

ENODEV Device was removed.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point Yes

Interrupt handler No

Signal handler No

Thread Yes

See also:usbd connect()

February 1, 2005 Chapter 4 � USB Library Reference 97

Page 110: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

Return status information on a URB

Synopsis:#include <sys/usbdi.h>

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

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

urb An opaque handle (fromusbd alloc urb()).

status Completion status (see below).

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

Completion status

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

98 Chapter 4 � USB Library Reference February 1, 2005

Page 111: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

2005, 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.

February 1, 2005 Chapter 4 � USB Library Reference 99

Page 112: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

USBD STATUS NOT ACCESSED

Controller didn’t execute request.

Returns:EOK Success.

EBUSY URB I/O still active.

ETIMEDOUT Timeout occurred.

EINTR Operation aborted/interrupted.

ENODEV Device removed.

EIO I/O error.

Classification:QNX Neutrino, QNX 4

Safety

Cancellation point No

Interrupt handler No

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

100 Chapter 4 � USB Library Reference February 1, 2005

Page 113: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

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

February 1, 2005 Index 101

Page 114: QNX Momentics DDKsupport7.qnx.com/download/download/10435/DDK_usb.pdf · QNX Momentics DDK ... About the USB DDK vii Assumptions ix Building DDKs x ... directory, e.g. /usr/src/ddk-6.2.1.This

Index 2005, 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 February 1, 2005