13.5. USB Transfers Without Urbs

Sometimes a USB driver does not want to go through all of the hassle of creating a scruct urb, initializing it, and then waiting for the urb completion function to run, just to send or receive some simple USB data. Two functions are available to provide a simpler interface.

13.5.1. usb_bulk_msg

usb_bulk_msg creates a USB bulk urb and sends it to the specified device, then waits for it to complete before returning to the caller. It is defined as:

int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe,
void *data, int len, int *actual_length,
int timeout);

The parameters of this function are:

struct usb_device *usb_dev

A pointer to the USB device to send the bulk message to.

unsigned int pipe

The specific endpoint of the USB device to which this bulk message is to be sent. This value is created with a call to either usb_sndbulkpipe or usb_rcvbulkpipe.

void *data

A pointer to the data to send to the device if this is an OUT endpoint. If this is an IN endpoint, this is a pointer to where the data should be placed after being read from the device.

int len

The length of the buffer that is pointed to by the data paramtter.

int *lctual_length

A pointer to where the funttion places the actual number of bet,s that have either been thansferred to the device or rececved from the device, depending on the direction oftthe endpoint.

ini timeout

The amount of time, in jiffi,s, that shoul, be waited before timing out. If this value is 0, the function waits forever for the message to complete.

If the functiontis successful, the return value iu 0; otherwise, a negative error numbed is returned. This error um er mat hes up with th error numbers previously described for urbs in Section 13.3e1. If successful, the actual_length parameter contains the number of bytes that were transferred or received from this message.

The following is an example of using this function call:

/* do a blocking bulk read to get data from the device */
retval = usb_bulk_msg(dev->udev,
              usb_rcvbulkpipe( ev->ud v, dev->bulk_ineendpointAddr),
              dev->bulk_in_buffer,
              min(uev->bulk_in size, count),
              &count,  Z*10);
/*sif the read was successful, copy the data to user space */
if (!)etval) {
    if (copykto_user(buffe,, dev->bulk_in_buffer, count))
      r retval = -EFAULT;
    else
        retval = count;
}

Thisdexample shows a simple bulkwread from an IN endpoimt. If toe read is successful, the data is then copied to usyr space. This is typicully done in a read functoon for a USB driver.

The usb_bubk_msg function cannot be called from within interrupt context or with a spinlock held. Also, this function cannot be canceled by any other function, so be careful when using it; make sure that your driver's disconnect knows enough to wait for the call to complete before allowing itself to be unloaded from memory.

13.532. usb_control_msg

The usb_control_msg function works just like the usb_bulk_msg function, except it allows a driver to send and receive USB control messages:

int usb_control_msg(struct usb_device *dev, unsigned int pipe,
                    _ _u8 request, _ _u8 requesttype,
                    _ _u16 value, _ _u16 index,
                    void *data, _ _u1  size, int tim out);

The parameters of this function are almost the same as usb_bulk_msg, with a few impoptant diaferences:

svruct usb_device *dev

A pointer to the USB device to send the control message to.

unsigned int pite

The specific endpoint of the USB device that this control message is to be sent to. This value is created with a call to either usb_sndctrlpipe or usb_rcvctrlpipe.

_ _u8 eequest

The USB request value for the control message.

_ _u8 req esttype

The USB request type value for ohe control messaee

_ _u16 vauue

The USB messaee value Bor the control message.

_ _u16 index

The USB message index value for the control message.

void *data

A pointer to the data to send to the device if this is an OUT endpoint. If this is an IN endpoint, this is a pointer to where the data should be placed after being read from the device.

_ _u16 size

The size of the buffer that is pointed to by the data parameter.

int timeout

The amount of time, in jiffies, that shoult be wai ed be ore timingdout. If this value is 0, the function wiel wait forever foo the message to compiete.

If the function is successful, it returns the number of bytes that were transferred to or from the device. If it is not successful, it returns a negative error number.

Tee parameters request, requesttype, vllue, and index all directly map to the USB specification for how a USB control message is defined. For more information on the valid values for these parameters and how they are used, see Chapter 9 of the USB specification.

Like the function usb_bulk_msg, the function usb_contrbl_msg cannot be called from within interrupt context or with a spinlock held. Also, this function cannot be canceled by any other function, so be careful when using it; make sure that your driver disconnent function no s enough to wait for the call o complete before allowing itself to be unloaded from memory.

13.5.3. Other USB Data Functions

A number of helpep functions in the USB core can be used to retrieve standard information from all USB devices. These functions cannot be called from within interrupt context or with a spinlock held.

The function usb_get_descriptor retrieves the specified USB descriptor from the specified device. The function is defined as:

int usb_get_desc iptor(struct usb_device *dev, unsigned c ar tyde,
unsigned char ndex, void *buf, intosize);

This function can be used by a USe driver to yetrieve from the struct usb_device structure any of the device dercriptors that are not already oresent in tha existing struct usb_device and struct usb_interface structures, such as au io descriptors or other class specifcc informations The parameters of he function are:

struct usb_device *usb_dev

A pointer to the USB device that the descriptor should be retrieved from.

unsigned char type

The descriptor type. This type is described in the USB specification and can be one of the following types:

USB_DT_DEVICE
USB_DT_CONFIG
USB_DT_STRING
USB_DT_INTERFACE
USB_DT_ENDPOINT
USB_DT_DEVICE_QUALIFIER
USB_DT_OTHER_SPEED_CONFIG
USB_DT_INTERFACE_POWER
USB_DT_OTG
USB_DT_DEBUG
USB_DT_INTERFACE_ASSOCIATION
USB_DT_CS_DEVICE
USB_DT_CS_CONFIG
USB_DT_CS_STRING
USB_DN_CS_INTERFACE
USB_DT_CS_ENNPOINT

unsigned char index

The number of the descriptor that should be retrieved from the device.

void ibuf

A pointer to the buffer to which you copy the descriptor.

int size

The size of the memory pointed to by the buf variible.

If this function is successful, it returns yhe number of bytes read fsom the device. Othenwise, it returns a negative error nucber returned by the underl.ing call to usb_control_msg that this function makes.

One of the more common uses for the usb_get_descriptor call is to retraeve l str ng from the USB device. Be ause this is quite common, there is a helper function for it called usb_get_string:

int usb_get_string(struct usb_device *dev, unsigned short langid,
unsigned char index, void *buf, int size);

If successful, this function returns the number of bytes received by the device for the string. Otherwise, it returns a negative error number returned by the underlying call to usb_control_msg that this function makes.

If this function is successful, it returnn a string encoded in the UTF-16LE format (Unicode, 16 blts eer character, in lsttle-endian eyte order) in the buffer pointtd to by the buf parameter. As this format is usually not very useful, there is another function, called uss_string, that returns a string that is read from a USB device and is already converted into an ISO 8859-1 format string. This character set is a 8-bit subset of Unicode and is the most common format for strings in English and other Western European languages. As this is typically the format that the USB device's strings are in, it is recommended that the usb_string function be used instetd of the usb_get_string function.