Linux Driver Verification » Linux Kernel Safety RuleDB

Initialization of USB request block¶

DESCRIPTION¶

All data which is sent to subsystem controlling USB peripherals (system bus controllers, such as OHCI/UHCI/EHCI) should be properly initialized. Uninitialized data or not properly initialized data can cause failures in both the device controlled by driver and the whole system.
The communication with devices connected to USB interface is performed by USB Request Blocks (URB). Which has the following life circle:

• usb_alloc_urb (...); - allocating memory for URB
• initialization
• usb_submit_urb (...); - sending data to Core USB
• calling callback function of a driver or waiting for "usb_complete_t" notification about successful receive or failure.
• usb_free_urb (...); - free URB

This rule requires that each URB request before submitting it using usb_submit_urb should be properly initialized initialized either by one of initialization functions depending on URB type or by manually filling all required fields.

USB subsystem defines 4 types of URB:

• Interrupt URB
• Bulk URB
• Control URB
• Isochronous URB

Each type has own predefined characteristics (e.g. reserved traffic, data integrity requirements and other QoS characteristics).
Each type of URB should be initialized by the proper function exported by USB Core. Such function is absent only for Isochronous URB because of rare use.

• Interrupt URB
  void usb_fill_int_urb (struct urb*, struct usb_device*, unsigned int pipe, \
  void *buf, int buffer_length, ...)

• Bulk URB
  void usb_fill_bulk_urb (struct urb*, struct usb_device*, unsigned int pipe, \
  void *buf, int buffer_length, ...)

• Control URB
  void usb_fill_control_urb (struct urb*, struct usb_device*, unsigned int pipe, \
  void *buf, int buffer_length, ...)

• Isochronous URB
  There is no standard initialization function. Manual initialization is required

EXAMPLE¶

void some_data_send_func ()
{
urb = usb_alloc_urb(0, GFP_KERNEL);
if (!urb)
{
retval = -ENOMEM;
goto error
}
/* INITIALIZATION */
usb_fill_bulk_urb(urb, dev->udev,
usb_sndbulkpipe(dev->udev, dev->bulk_out_endpointAddr),
buf, count, skel_write_bulk_callback, dev);

/* SENDING URB */
retval = usb_submit_urb(urb, GFP_KERNEL);
if (retval)
{
err("%s - failed submitting write urb, error %d", __FUNCTION__, retval);
goto error;
}
}