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

Arguments:

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.

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

Data structures

typedef struct usbd_connect_parm {
    const char                        *path;
    uint16_t                            vusb;
    uint16_t                            vusbd;
    uint32_t                            flags;
    int                                argc;
    char                             **argv;
    uint32_t                            evtbufsz;
    usbd_device_ident_t               *ident;
    usbd_funcs_t                      *funcs;
    uint16_t                            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 DDK (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

A pointer to a usbd_device_ident_t structure that identifies the devices you're interested in receiving insertion/removal callbacks for (a filter):

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

You can set the fields to USBD_CONNECT_WILDCARD or to an explicit value. You would typically make the usbd_device_ident_t structure be a filter for devices you support from this specific class driver.

funcs

A pointer to a usbd_funcs_t structure that specifies the insertion/removal callbacks:

typedef struct usbd_funcs {
   uint32_t   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_t type);
} usbd_funcs_t;

The usbd_funcs_t structure includes the following members:

nentries: The number of entries in the structure. Set this to _USBDI_NFUNCS.
insertion: The function to call when a device that matches the defined filter is detected.
removal: The function to call when a device is removed.
event: A future extension for various other event notifications (e.g. bandwidth problems).

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.

connect_wait

A value (in seconds) or USBD_CONNECT_WAIT.

Returns:

EOK: Success.
EPROGMISMATCH: 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).