USBDI(9)               NetBSD Kernel Developer's Manual               USBDI(9)

NAME
     usbdi -- USB device drivers interface

SYNOPSIS
     #include <dev/usb/usb.h>
     #include <dev/usb/usbdi.h>
     #include <dev/usb/usbdi_util.h>

   Functions offered by usbdi.h
     usbd_status
     usbd_open_pipe(usbd_interface_handle iface, uint8_t address,
         uint8_t flags, usbd_pipe_handle *pipe);

     usbd_status
     usbd_close_pipe(usbd_pipe_handle pipe);

     usbd_status
     usbd_transfer(usbd_xfer_handle xfer);

     usbd_xfer_handle
     usbd_alloc_xfer(usbd_device_handle dev);

     usbd_status
     usbd_free_xfer(usbd_xfer_handle xfer);

     void
     usbd_setup_xfer(usbd_xfer_handle xfer, usbd_pipe_handle pipe,
         usbd_private_handle priv, void *buffer, uint32_t length,
         uint16_t flags, uint32_t timeout, usbd_callback);

     void
     usbd_setup_default_xfer(usbd_xfer_handle xfer, usbd_device_handle dev,
         usbd_private_handle priv, uint32_t timeout,
         usb_device_request_t *req, void *buffer, uint32_t length,
         uint16_t flags, usbd_callback);

     void
     usbd_setup_isoc_xfer(usbd_xfer_handle xfer, usbd_pipe_handle pipe,
         usbd_private_handle priv, uint16_t *frlengths, uint32_t nframes,
         uint16_t flags, usbd_callback);

     void
     usbd_get_xfer_status(usbd_xfer_handle xfer, usbd_private_handle *priv,
         void **buffer, uint32_t *count, usbd_status *status);

     usb_endpoint_descriptor_t *
     usbd_interface2endpoint_descriptor(usbd_interface_handle iface,
         uint8_t address);

     usbd_status
     usbd_abort_pipe(usbd_pipe_handle pipe);

     usbd_status
     usbd_abort_default_pipe(usbd_device_handle dev);

     usbd_status
     usbd_clear_endpoint_stall(usbd_pipe_handle pipe);

     usbd_status
     usbd_clear_endpoint_stall_async(usbd_pipe_handle pipe);

     void
     usbd_clear_endpoint_toggle(usbd_pipe_handle pipe);

     usbd_status
     usbd_endpoint_count(usbd_interface_handle dev, uint8_t *count);

     usbd_status
     usbd_interface_count(usbd_device_handle dev, uint8_t *count);

     usbd_status
     usbd_interface2device_handle(usbd_interface_handle iface,
         usbd_device_handle *dev);

     usbd_status
     usbd_device2interface_handle(usbd_device_handle dev, uint8_t ifaceno,
         usbd_interface_handle *iface);

     usbd_device_handle
     usbd_pipe2device_handle(usbd_pipe_handle pipe);

     void *
     usbd_alloc_buffer(usbd_xfer_handle req, uint32_t size);

     void
     usbd_free_buffer(usbd_xfer_handle req);

     void *
     usbd_get_buffer(usbd_xfer_handle xfer);

     usbd_status
     usbd_sync_transfer(usbd_xfer_handle req);

     usbd_status
     usbd_sync_transfer_sig(usbd_xfer_handle req);

     usbd_status
     usbd_open_pipe_intr(usbd_interface_handle iface, uint8_t address,
         uint8_t flags, usbd_pipe_handle *pipe, usbd_private_handle priv,
         void *buffer, uint32_t length, usbd_callback callback, int interval);

     usbd_status
     usbd_do_request(usbd_device_handle dev, usb_device_request_t *req,
         void *data);

     usbd_status
     usbd_do_request_flags(usbd_device_handle dev, usb_device_request_t *req,
         void *data, uint16_t flags, int *actlen, u_int32_t timo);

     usb_interface_descriptor_t *
     usbd_get_interface_descriptor(usbd_interface_handle iface);

     usb_config_descriptor_t *
     usbd_get_config_descriptor(usbd_device_handle dev);

     usb_device_descriptor_t *
     usbd_get_device_descriptor(usbd_device_handle dev);

     usbd_status
     usbd_set_interface(usbd_interface_handle iface, int altidx);

     int
     usbd_get_no_alts(usb_config_descriptor_t *iface, int ifaceno);

     usbd_status
     usbd_fill_deviceinfo(usbd_device_handle dev, struct usb_device_info *di);

     int
     usbd_get_interface_altindex(usbd_interface_handle iface);

     usb_endpoint_descriptor_t *
     usbd_get_endpoint_descriptor(usbd_interface_handle dev,
         u_int8_t address);

     usb_interface_descriptor_t *
     usbd_find_idesc(usb_config_descriptor_t *cd, int iindex, int ano);

     usb_endpoint_descriptor_t *
     usbd_find_edesc(usb_config_descriptor_t *cd, int ifaceidx, int altidx,
         int endptidx);

     void
     usbd_dopoll(usbd_interface_handle iface);

     void
     usbd_set_polling(usbd_device_handle iface, int val);

     const char *
     usbd_errstr(usbd_status err);

     void
     usbd_add_dev_event(int type, usbd_device_handle iface);

     void
     usbd_add_drv_event(int type, usbd_device_handle iface, device_t dv);

     char *
     usbd_devinfo_alloc(usbd_device_handle iface, int showclass);

     void
     usbd_devinfo_free(char *str);

     const struct usbd_quirks *
     usbd_get_quirks(usbd_device_handle iface);

     usbd_status
     usbd_reload_device_desc(usbd_device_handle iface);

     int
     usbd_ratecheck(struct timeval *tv);

     usbd_status
     usbd_get_string(usbd_device_handle iface, int si, char *buf);

     usbd_status
     usbd_get_string0(usbd_device_handle iface, int, si, char *buf,
         int unicode);

     void
     usb_desc_iter_init(usbd_device_handle iface, usbd_desc_iter_t *iter);

     const usb_descriptor_t *
     usb_desc_iter_next(usbd_desc_iter_t *iter);

     void
     usb_add_task(usbd_device_handle iface, struct usb_task *task, int queue);

     void
     usb_rem_task(usbd_device_handle iface, struct usb_task *task);

     void
     usb_init_task(struct usb_task *task, void (*func)(void *), void *arg,
         uint8_t, flags);

     const struct usb_devno *
     usb_lookup(const struct usb_devno *tbl, u_int16_t vendor,
         u_int16_t product);

   Utilities from usbdi_util.h
     Based on the routines in usbdi.h a number of utility functions have been
     defined that are accessible through usbdi_util.h.

     usbd_status
     usbd_get_desc(usbd_device_handle dev, int type, int index, int len,
         void *desc);

     usbd_status
     usbd_get_config_desc(usbd_device_handle dev, int confidx,
         usb_config_descriptor_t *d);

     usbd_status
     usbd_get_config_desc_full(usbd_device_handle, int dev, void *d,
         int size);

     usbd_status
     usbd_get_device_desc(usbd_device_handle dev, usb_device_descriptor_t *d);

     usbd_status
     usbd_set_address(usbd_device_handle dev, int addr);

     usbd_status
     usbd_get_port_status(usbd_device_handle dev, intp ort,
         usb_port_status_t *ps);

     usbd_status
     usbd_set_hub_feature(usbd_device_handle dev, int sel);

     usbd_status
     usbd_clear_hub_feature(usbd_device_handle dev, int sel);

     usbd_status
     usbd_set_port_feature(usbd_device_handle dev, int port, int sel);

     usbd_status
     usbd_clear_port_feature(usbd_device_handle dev, int port, int sel);

     usbd_status
     usbd_get_device_status(usbd_device_handle dev, usb_status_t *st);

     usbd_status
     usbd_get_hub_status(usbd_device_handle dev, usb_hub_status_t *st);

     usbd_status
     usbd_set_protocol(usbd_interface_handle dev, int report);

     usbd_status
     usbd_get_report_descriptor(usbd_device_handle dev, int ifcno, int repid,
         int size, void *d);

     struct usb_hid_descriptor *
     usbd_get_hid_descriptor(usbd_interface_handle ifc);

     usbd_status
     usbd_set_report(usbd_interface_handle iface, nt type, int id, void *data,
         int len);

     usbd_status
     usbd_set_report_async(usbd_interface_handle iface, int type, int id,
         void *data, int len);

     usbd_status
     usbd_get_report(usbd_interface_handle iface, int type, int id,
         void *data, int len);

     usbd_status
     usbd_set_idle(usbd_interface_handle iface, int duration, int id);

     usbd_status
     usbd_alloc_report_desc(usbd_interface_handle ifc, void **descp,
         int *sizep, int mem);

     usbd_status
     usbd_get_string_desc(usbd_device_handle dev, int sindex, int langid,
         usb_string_descriptor_t *sdesc);

     void
     usbd_delay_ms(usbd_device_handle dev, u_int ms);

     usbd_status
     usbd_set_config_no(usbd_device_handle dev, int no, int msg);

     usbd_status
     usbd_set_config_index(usbd_device_handle dev, int index, int msg);

     usbd_status
     usbd_bulk_transfer(usbd_xfer_handle xfer, usbd_pipe_handle pipe,
         uint16_t flags, uint32_t timeout, void *buf, uint32_t *size,
         char *lbl);

     usbd_status
     usbd_intr_transfer(usbd_xfer_handle xfer, usbd_pipe_handle pipe,
         uint16_t flags, uint32_t timeout, void *buf, uint32_t *size,
         char *lbl);

     void
     usb_detach_waitold(device_t dv);

     void
     usb_detach_wakeupold(device_t dv);

     void
     usb_detach_wait(device_t dv, kcondvar_t *cv, kmutex_t *lk);

     void
     usb_detach_broadcast(device_t dv, kcondvar_t *cv);

DESCRIPTION
     Device driver access to the USB bus centers around transfers.  A transfer
     describes a communication with a USB device.  A transfer is an abstract
     concept that can result in several physical packets being transferred to
     or from a device.  A transfer is described by the usbd_xfer_handle
     cookie.  A pipe is a logical connection to a USB device.  It is described
     by the usbd_pipe_handle cookie.  See the TRANSFERS and PIPES sections for
     more details.

     There are a number of functions to obtain a handle, descriptor of
     resource count:

     usbd_device2interface_handle(dev, ifaceno, iface)
                 Fills in iface with the usbd_interface_handle for the USB
                 device dev on interface number ifaceno.

     usbd_interface2device_handle(iface, dev)
                 Fills in dev with the usbd_device_handle pointer for inter-
                 face iface.

     usbd_pipe2device_handle(pipe)
                 Returns the usbd_device_handle associated with pipe.

     usbd_interface2endpoint_descriptor(iface, address)
                 Returns the usb_endpoint_descriptor_t * for the particular
                 interface iface at address address.

     usbd_endpoint_count(dev, count)

     usbd_interface_count(dev, count)
                 Fills in count with the number of endpoint or interfaces the
                 USB device dev has.

     Error handling and other return values are described in usbd_status(9).

     Additional comments on particular functions:

     usbd_errstr(err)
                 Returns the string associated with err.

     usbd_add_dev_event(type, iface)
                 The type must be one of USB_EVENT_CTRLR_ATTACH,
                 USB_EVENT_CTRLR_DETACH, USB_EVENT_DEVICE_ATTACH and
                 USB_EVENT_DEVICE_DETACH.

     usbd_add_drv_event(type, iface, dv)
                 The type must be one of USB_EVENT_DRIVER_ATTACH and
                 USB_EVENT_DRIVER_DETACH.  The dv corresponds with the
                 device_t associated with the device attached or detached.

     usb_lookup(tbl, vendor, product)
                 Lookup a USB device.  The returned struct usb_devno pointer
                 has these members:
                       u_int16_t ud_vendor;
                       u_int16_t ud_product;
                 The USB_PRODUCT_ANY macro can be used to match any USB prod-
                 uct by a particular vendor.

PIPES
     Pipes are created and destroyed by using the usbd_open_pipe(),
     usbd_open_pipe_intr() and usbd_close_pipe() functions.  The open func-
     tions take the interface handle iface, the address of this pipe and flags
     for this pipe which currently may be 0, or a combination of
     USBD_EXCLUSIVE_USE, to enable exclusive access to this interface and
     address, and USBD_MPSAFE, to allow running transfer callbacks on this
     pipe without first acquiring kernel_lock.  The usbd_open_pipe_intr()
     takes additional arguments priv to set the default private handle.
     buffer and len to describe the buffer to be used, callback for the func-
     tion to call at interrupt time, and finally the interval for interrupts
     to be delivered in milliseconds.  The interval may be set to
     USBD_DEFAULT_INTERVAL use the default interval, specified by the ep.
     description.  It is common to have more than one pipe per device.

TRANSFERS
     Transfers are allocated and deallocated with usbd_alloc_xfer() and
     usbd_free_xfer(), respectively, and are associated with a pipe at their
     creation time.

     The data describing the transfer is filled by either
     usbd_setup_default_xfer() for control pipe transfers, by
     usbd_setup_xfer() for bulk and interrupt transfers, and by
     usbd_setup_isoc_xfer() for isochronous transfers.  Private data may be
     passed between setup and completion or status calls using the
     usbd_private_handle priv argument, which must be an integral type.

     Arguments to the setup functions include the newly allocated xfer, the
     pipe to associate this transfer with, the private data priv, the timeout
     in milliseconds, for control, bulk and interrupt transfers buffer the
     data to transfer and its length and for isochronous transfers the frame
     length frlengths and number of frames nframes, and for default transfers
     a USB request structure req must be presented.  See the INITIALISING USB
     REQUESTS section for more details on USB requests.

     The transfer specific flags that can be set are:

     USBD_NO_COPY
                 Do not copy data to DMA buffer

     USBD_SYNCHRONOUS
                 Wait for completion

     USBD_SYNCHRONOUS_SIG
                 When waiting for completion, allow signals to trigger wake
                 up.

     USBD_SHORT_XFER_OK
                 Short reads are not an error

     USBD_FORCE_SHORT_XFER
                 Force last short packet on write

     To allocate buffers suitable for USB tranfers (i.e., DMA capable), the
     usbd_alloc_buffer() function should be used on the specified xfer for
     size bytes of space.  The usbd_free_buffer() function can be used to free
     the buffer after use.  The usbd_get_buffer() function returns the current
     kernel address for the DMA-capable buffer in xfer.

     Upon completion the callback function is called, which takes the com-
     pleted xfer, the private data priv originally assocated with this trans-
     fer, and status the status of this transfer.

     Transfers are initiated by calling usbd_transfer(), and their results
     made be later obtained by calling usbd_get_xfer_status, which fills in
     the private data priv, original buffer location buffer, the length
     length, and the status of this request.

     The usbd_bulk_transfer() and usbd_intr_transfer() functions are used to
     transfer data in either an interrupt or bulk fashion, and are front-ends
     to the usbd_setup_xfer(), usbd_transfer() and usbd_get_xfer_status(), as
     well as associated error handling.  The lbl option is deprecated and will
     be removed.  The usbd_sync_transfer() is identical to usbd_transfer()
     with the USBD_SYNCHRONOUS flag set.  The usbd_sync_transfer_sig() is
     identical to usbd_transfer() with the USBD_SYNCHRONOUS and
     USBD_SYNCHRONOUS_SIG flags set.

     Transfers are aborted via this pipe with usbd_abort_pipe() and
     usbd_abort_default_pipe().

     The usbd_clear_endpoint_stall() and usbd_clear_endpoint_stall_async()
     functions are used to clear endpoint halt in either a synchronous or
     asynchronous fashion.  To clear the toggle state of an endpoint the
     usbd_clear_endpoint_toggle() function should be used.

     A request is described by a usb_device_request_t which must be ini-
     tialised as necessary before calling either usbd_do_request() or
     usbd_do_request_flags() to submit the request.  For both these functions
     dev is the handle of the USB device the request is for, req is the USB
     request, as described in the INITIALISING USB REQUESTS section, and then
     data is a buffer containing the data for the request.  For the
     usbd_do_request_flags() function there are additional flags passed to the
     usbd_setup function, actlen a pointer to fill in with the actual length
     of this request, and timo, the number of milliseconds to wait before tim-
     ing out this request.

INITIALISING USB REQUESTS
     There are 5 members of a usb_device_request_t that must be initialised:

           uByte bmRequestType;
           uByte bRequest;
           uWord wValue;
           uWord wIndex;
           uWord wLength;

     The first two are normal byte values that may be simply assigned, but the
     last three must be initialised with the USETW() macro.

     The bmRequestType holds the request type of this USB request, which
     describes the indended recipient of the request.

     This may be one of:
           UT_WRITE
           UT_READ

     with one of:
           UT_STANDARD
           UT_CLASS
           UT_VENDOR

     and with one of:
           UT_DEVICE
           UT_INTERFACE
           UT_ENDPOINT
           UT_OTHER

     These are also in combinations as:
           UT_READ_DEVICE
           UT_READ_INTERFACE
           UT_READ_ENDPOINT
           UT_WRITE_DEVICE
           UT_WRITE_INTERFACE
           UT_WRITE_ENDPOINT
           UT_READ_CLASS_DEVICE
           UT_READ_CLASS_INTERFACE
           UT_READ_CLASS_OTHER
           UT_READ_CLASS_ENDPOINT
           UT_WRITE_CLASS_DEVICE
           UT_WRITE_CLASS_INTERFACE
           UT_WRITE_CLASS_OTHER
           UT_WRITE_CLASS_ENDPOINT
           UT_READ_VENDOR_DEVICE
           UT_READ_VENDOR_INTERFACE
           UT_READ_VENDOR_OTHER
           UT_READ_VENDOR_ENDPOINT
           UT_WRITE_VENDOR_DEVICE
           UT_WRITE_VENDOR_INTERFACE
           UT_WRITE_VENDOR_OTHER
           UT_WRITE_VENDOR_ENDPOINT

     The bRequest describes which request is being made.  The available values
     are:
           UR_GET_STATUS
           UR_CLEAR_FEATURE
           UR_SET_FEATURE
           UR_SET_ADDRESS
           UR_GET_DESCRIPTOR
           UR_SET_DESCRIPTOR

     The wValue, wIndex and wLength are device-specific values and must be
     initialised with the USETW() macro.

USB REQUEST TYPES AND STRUCTURES
     The UR_GET_STATUS request operates on a usb_status_t structure, which has
     this member:
           uWord wStatus;

     For device status requests the wStatus member may have either of these
     bit flags set:
           UDS_SELF_POWERED
           UDS_REMOTE_WAKEUP

     For endpoint status requests the wStatus member may have this bit flag
     set:
           UES_HALT

     The UR_CLEAR_FEATURE and UR_SET_FEATURE requests clear or set special
     features on USB devices.  The values for wValue, wIndex and wLength
     depend upon the device and device type.

     The UR_SET_ADDRESS request sets the virtual USB address of a port using
     the wValue.

     The UR_GET_DESCRIPTOR and UR_SET_DESCRIPTOR requests operate on a
     usb_descriptor_t structure, which has these members:
           uByte bLength;
           uByte bDescriptorType;

     The bDescriptorType member may be one of the following values:
           UDESC_DEVICE
           UDESC_CONFIG
           UDESC_STRING
           UDESC_INTERFACE
           UDESC_ENDPOINT
           UDESC_DEVICE_QUALIFIER
           UDESC_OTHER_SPEED_CONFIGURATION
           UDESC_INTERFACE_POWER
           UDESC_OTG
           UDESC_DEBUG
           UDESC_INTERFACE_ASSOC
           UDESC_CS_DEVICE
           UDESC_CS_CONFIG
           UDESC_CS_STRING
           UDESC_CS_INTERFACE
           UDESC_CS_ENDPOINT
           UDESC_HUB

     The usbd_set_interface() function can be used to change the index used
     for transfers on this interface as obtained via
     usbd_device2interface_handle().

USB DEVICE DETACHMENT
     There are two functions available to ease the detach of active devices.
     Typically a reference count is maintained on syscall activity.  When a
     USB device is to be detached, the reference count should be decremented
     and if it is greater or equal to zero, usb_detach_wait() should be called
     on the dv associated with this USB device and, typically, a device-spe-
     cific condition variable cv.  and mutex lk protecting this reference
     count state.  At the end of each syscall function, if the reference count
     is decremented to less than zero, then usb_detach_broadcast() must be
     called on the dv and cv that is being waited on with usb_detach_wait().

     The are another pair of functions with similar functionality that do not
     use a condition variable or mutex and should be avoided in new code.  The
     usb_detach_waitold() function works like usb_detach_wait(), and the
     usb_detach_wakeupold() function works like usb_detach_broadcast().

USB TASK MANAGEMENT
     The USB stack provides a task management framework to execute tasks in a
     thread context at the soonest opportunity.  Typically this is used by
     network drivers to handle periodic updates or status change requests, or
     other operations that need to run in a normal context.

     The usb_init_task() function takes a pointer to a struct usb_task that
     will be initalised, a function to call for this task func, the argument
     to pass to func, arg, and the task flags flags.  If the flags argument is
     USB_TASKQ_MPSAFE, the func function will be called without first acquir-
     ing kernel_lock.

     To invoke the task callback the usb_add_task() function should be called
     with the iface associated with this device, the task structure task, and
     the queue to run against, either USB_TASKQ_HC for operations initiated by
     host controllers or USB_TASKQ_DRIVER for operations initiated by USB
     drivers.

     To deschedule a potentially running task the usb_rem_task() function
     should be called.

     The driver using these facilities is expected to provide the necessary
     serialisation between usb_init_task(), usb_add_task() and usb_rem_task()
     for each specific struct usb_task.

SEE ALSO
     usb(4), usbd_status(9)

HISTORY
     This usbdi interface first appeared in NetBSD 1.4.  The interface is
     based on an early definition from the OpenUSBDI group within the USB
     organisation.  Right after this definition the OpenUSBDI development got
     closed for open source developers, so this interface has not followed the
     further changes.  The OpenUSBDI specification is now available again, but
     looks different.

BUGS
     This manual is under development, so its biggest shortcoming is incom-
     pleteness.

NetBSD 6.0                    September 26, 2013                    NetBSD 6.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen