URB Functions

There are four functions of the USB core that handle URBs.

• purb_t usb_alloc_urb(int iso_packets);

  Whenever a URB structure is needed this function has to be called. The argument iso_packets is used to specify the number of iso_frame_desc structures at the end of the URB structure when setting up isochronous transfers. If successful the return value is a pointer to a URB structure preset to zero otherwise a NULL pointer is returned.

• void usb_free_urb (purb_t purb);

  To free memory allocated by usb_alloc_urb simply call this function.

• int usb_submit_urb(purb_t purb);

  This function sends a transfer request asynchronously to the USB core. The argument purb is a pointer to a previously allocated and initialized URB structure. If successful the return value is 0 otherwise an appropriate error code is returned (see section 3.1). The function returns always non-blocking and it is possible to schedule several URBs for different endpoints without waiting. On isochronous endpoints it is even possible to schedule more URBs for one endpoint. This limitation is caused due to error handling and retry mechanisms of the USB protocol (see [4] section 8.5)

• int usb_unlink_urb(purb_t purb);

  This function cancels a scheduled request before it is completed. The argument purb is a pointer to a previously submitted URB structure. The function can be called synchronously or asynchronously depending on the transfer_flag USB_ASYNC_UNLINK (see 2.3.1). Synchronously called the function waits for 1ms and must not be called from an interrupt or completion handler. The return value is 0 if the function succeeds. Asynchronously called the function returns immediately. The return value is -EINPROGRESS if the function was successfully started. When calling usb_unlink_urb the completion handler is called after the function completed. The URB status is marked with -ENOENT (synchronously called) or -ECONNRESET (asynchronously called).

  usb_unlink_urb is also used to stop an interrupt transfer URB. As documented in sections 1.2.2, 2.3.1 interrupt transfers are automatically rescheduled. Call usb_unlink_urb even for ``one shot interrupts''.