⇦ prev | ⇱ home | next ⇨ |
13.5. USB Transfers Without UrbsSometimes a USB driver does not want to go through all of the hassle of creating a struct 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_msgusb_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:
If the function is successful, the return value is 0; otherwise, a negative error number is returned. This error number matches up with the error numbers previously described for urbs in Section 13.3.1. 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(dev->udev, dev->bulk_in_endpointAddr), dev->bulk_in_buffer, min(dev->bulk_in_size, count), &count, HZ*10); /* if the read was successful, copy the data to user space */ if (!retval) { if (copy_to_user(buffer, dev->bulk_in_buffer, count)) retval = -EFAULT; else retval = count; } This example shows a simple bulk read from an IN endpoint. If the read is successful, the data is then copied to user space. This is typically done in a read function for a USB driver. The usb_bulk_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.5.2. usb_control_msgThe 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, _ _u16 size, int timeout); The parameters of this function are almost the same as usb_bulk_msg, with a few important differences:
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. The parameters request, requesttype, value, 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_control_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 disconnect function knows enough to wait for the call to complete before allowing itself to be unloaded from memory. 13.5.3. Other USB Data FunctionsA number of helper 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_descriptor(struct usb_device *dev, unsigned char type, unsigned char index, void *buf, int size); This function can be used by a USB driver to retrieve from the struct usb_device structure any of the device descriptors that are not already present in the existing struct usb_device and struct usb_interface structures, such as audio descriptors or other class specific information. The parameters of the function are:
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_DT_CS_INTERFACE USB_DT_CS_ENDPOINT
If this function is successful, it returns the number of bytes read from the device. Otherwise, it returns a negative error number returned by the underlying call to usb_control_msg that this function makes. One of the more common uses for the usb_get_descriptor call is to retrieve a string from the USB device. Because 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 returns a string encoded in the UTF-16LE format (Unicode, 16 bits per character, in little-endian byte order) in the buffer pointed to by the buf parameter. As this format is usually not very useful, there is another function, called usb_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 instead of the usb_get_string function. |
⇦ prev | ⇱ home | next ⇨ |