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.

Library:

libusbdi

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                            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 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                    vendor;
    _uint32                    device;
    _uint32                    dclass;
    _uint32                    subclass;
    _uint32                    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   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 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

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

See also:

usbd_args_lookup(), usbd_attach(), usbd_detach(), usbd_disconnect()