This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

usbd_connect()

Connect a client driver to the USB stack

Synopsis:

#include <sys/usbdi.h>

int usbd_connect( usbd_connect_parm_t *parm, 
                  struct usbd_connection **connection );

Description:

You use the usbd_connect() function to connect to a USB device and to provide insertion/removal callbacks (in the usbd_connect_parm_t data structure).

parm: Connection parameters describing how to connect to the USB stack and how you intend to operate with it.
connection: An opaque handle returned on a successful connection; it's used to pass into other routines to identify the connection.

Data structures

typedef struct usbd_connect_parm {
    const char                        *path;
    _uint16                            vusb;
    _uint16                            vusbd;
    _uint32                            flags;
    int                                argc;
    char                             **argv;
    _uint32                            evtbufsz;
    usbd_device_ident_t               *ident;
    usbd_funcs_t                      *funcs;
    _uint16                            connect_wait
} usbd_connect_parm_t;

path: Name of the stack (NULL means /dev/io-usb/io-usb, the default name).
vusb and vusbd: Versions of the USB stack (USB_VERSION) and SDK (USBD_VERSION).
flags: Currently none defined. Pass 0.
argc and argv: Command-line arguments to the device driver that can be made available via usbd_args_lookup() at insertion/attach time.
evtbufsz: Size of the event buffer used by the handler thread to buffer events from the USB stack. For the default size, pass 0.
ident: Identifies the devices you're interested in receiving insertion/removal callbacks for (a filter); fields can be set to USBD_CONNECT_WILDCARD or to an explicit value.
funcs: The insertion/removal callbacks.
connect_wait: A value (in seconds) or USBD_CONNECT_WAIT.

typedef struct usbd_device_ident {
    _uint32                    vendor;
    _uint32                    device;
    _uint32                    dclass;
    _uint32                    subclass;
    _uint32                    protocol;
} usbd_device_ident_t;

You would typically make the usbd_device_ident structure be a filter for devices you support from this specific class driver.

typedef struct usbd_funcs {
   _uint32   nentries;
   void      (*insertion)(struct usbd_connection *, usbd_device_instance_t *instance);
   void      (*removal)(struct usbd_connection *, usbd_device_instance_t *instance);
   void      (*event)(struct usbd_connection *, usbd_device_instance_t *instance, 
                      _uint16 type);
} usbd_funcs_t;

The callback functions are contained here.

insertion: Called when a device that matches defined filter is detected.
removal: Called when a device is removed.
event: A future extension for various other event notifications (e.g. bandwidth problems).
_USBDI_NFUNCS: A constant that goes into nentries.

By passing NULL as the usbd_funcs, you're saying that you're not interested in receiving dynamic insertion/removal notifications, which means that you won't be a fully operational class driver. No asynchronous I/O will be allowed, no event thread, etc. This approach is taken, for example, by the usb display utility.

Returns:

EOK: Success.
EPROGRAMISMATCH: Versionitis.
ENOMEM: No memory for internal connect structures.
ESRCH: USB server not running.
EACCESS: Permission denied to USB server.
EAGAIN: Can't create async/callback thread.

Examples:

A class driver (in its main(), probably) for a 3COM Ethernet card might connect like this:

usbd_device_ident_t        interest = {
                            USB_VENDOR_3COM,
                            USB_PRODUCT_3COM_3C19250,
                            USBD_CONNECT_WILDCARD,
                            USBD_CONNECT_WILDCARD,
                            USBD_CONNECT_WILDCARD,
                        };
usbd_funcs_t            funcs = {
                            _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:

The usbd_connect() function creates a thread on your behalf that's used by the library to monitor the USB stack for device insertion or removal. Since your insertion and removal callback functions are called by this new thread, you must ensure that any common resources used between that thread and any other thread(s) in your class driver are properly protected (e.g. via a mutex).