|
Linux Kernel
3.7.1
|
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
|
Linux Kernel
3.7.1
|
#include <linux/pci.h>#include <linux/usb.h>#include <linux/module.h>#include <linux/slab.h>#include <linux/init.h>#include <linux/mm.h>#include <linux/timer.h>#include <linux/ctype.h>#include <linux/nls.h>#include <linux/device.h>#include <linux/scatterlist.h>#include <linux/usb/quirks.h>#include <linux/usb/hcd.h>#include <asm/byteorder.h>#include "usb.h"Go to the source code of this file.
Data Structures | |
| struct | api_context |
| struct | set_config_request |
Macros | |
| #define | MAX_USB_STRING_SIZE (127 * 3 + 1) |
Variables | |
| struct device_type | usb_if_device_type |
| EXPORT_SYMBOL_GPL | ( | usb_control_msg | ) |
| EXPORT_SYMBOL_GPL | ( | usb_interrupt_msg | ) |
| EXPORT_SYMBOL_GPL | ( | usb_bulk_msg | ) |
| EXPORT_SYMBOL_GPL | ( | usb_sg_init | ) |
| EXPORT_SYMBOL_GPL | ( | usb_sg_wait | ) |
| EXPORT_SYMBOL_GPL | ( | usb_sg_cancel | ) |
| EXPORT_SYMBOL_GPL | ( | usb_get_descriptor | ) |
| EXPORT_SYMBOL_GPL | ( | usb_string | ) |
| EXPORT_SYMBOL_GPL | ( | usb_get_status | ) |
| EXPORT_SYMBOL_GPL | ( | usb_clear_halt | ) |
| EXPORT_SYMBOL_GPL | ( | usb_reset_endpoint | ) |
| EXPORT_SYMBOL_GPL | ( | usb_set_interface | ) |
| EXPORT_SYMBOL_GPL | ( | usb_reset_configuration | ) |
| EXPORT_SYMBOL_GPL | ( | usb_driver_set_configuration | ) |
| int usb_bulk_msg | ( | struct usb_device * | usb_dev, |
| unsigned int | pipe, | ||
| void * | data, | ||
| int | len, | ||
| int * | actual_length, | ||
| int | timeout | ||
| ) |
usb_bulk_msg - Builds a bulk urb, sends it off and waits for completion : pointer to the usb device to send the message to : endpoint "pipe" to send the message to : pointer to the data to send : length in bytes of the data to send : pointer to a location to put the actual length transferred in bytes : time in msecs to wait for the message to complete before timing out (if 0 the wait is forever)
Context: !in_interrupt ()
This function sends a simple bulk message to a specified endpoint and waits for the message to complete, or timeout.
If successful, it returns 0, otherwise a negative error number. The number of actual bytes transferred will be stored in the actual_length paramater.
Don't use this function from within an interrupt context, like a bottom half handler. If you need an asynchronous message, or need to send a message from within interrupt context, use usb_submit_urb() If a thread in your driver uses this call, make sure your disconnect() method can wait for it to complete. Since you don't have a handle on the URB used, you can't cancel the request.
Because there is no usb_interrupt_msg() and no USBDEVFS_INTERRUPT ioctl, users are forced to abuse this routine by using it to submit URBs for interrupt endpoints. We will take the liberty of creating an interrupt URB (with the default interval) if the target is an interrupt endpoint.
usb_clear_halt - tells device to clear endpoint halt/stall condition : device whose endpoint is halted : endpoint "pipe" being cleared Context: !in_interrupt ()
This is used to clear halt conditions for bulk and interrupt endpoints, as reported by URB completion status. Endpoints that are halted are sometimes referred to as being "stalled". Such endpoints are unable to transmit or receive data until the halt status is cleared. Any URBs queued for such an endpoint should normally be unlinked by the driver before clearing the halt condition, as described in sections 5.7.5 and 5.8.5 of the USB 2.0 spec.
Note that control and isochronous endpoints don't halt, although control endpoints report "protocol stall" (for unsupported requests) using the same status code used to report a true stall.
This call is synchronous, and may not be used in an interrupt context.
Returns zero on success, or else the status code returned by the underlying usb_control_msg() call.
| 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 | ||
| ) |
usb_control_msg - Builds a control urb, sends it off and waits for completion : pointer to the usb device to send the message to : endpoint "pipe" to send the message to : USB message request value : USB message request type value : USB message value : USB message index value : pointer to the data to send : length in bytes of the data to send : time in msecs to wait for the message to complete before timing out (if 0 the wait is forever)
Context: !in_interrupt ()
This function sends a simple control message to a specified endpoint and waits for the message to complete, or timeout.
If successful, it returns the number of bytes transferred, otherwise a negative error number.
Don't use this function from within an interrupt context, like a bottom half handler. If you need an asynchronous message, or need to send a message from within interrupt context, use usb_submit_urb(). If a thread in your driver uses this call, make sure your disconnect() method can wait for it to complete. Since you don't have a handle on the URB used, you can't cancel the request.
usb_disable_device - Disable all the endpoints for a USB device : the device whose endpoints are being disabled : 0 to disable endpoint 0, 1 to skip it.
Disables all the device's endpoints, potentially including endpoint 0. Deallocates hcd/hardware state for the endpoints (nuking all or most pending urbs) and usbcore state for the interfaces, so that usbcore must usb_set_configuration() before any interfaces could be used.
usb_disable_endpoint – Disable an endpoint by address : the device whose endpoint is being disabled : the endpoint's address. Endpoint number for output, endpoint number + USB_DIR_IN for input : flag to erase any endpoint state stored in the controller hardware
Disables the endpoint for URB submission and nukes all pending URBs. If is set then also deallocates hcd/hardware state for the endpoint.
| void usb_disable_interface | ( | struct usb_device * | dev, |
| struct usb_interface * | intf, | ||
| bool | reset_hardware | ||
| ) |
usb_driver_set_configuration - Provide a way for drivers to change device configurations : the device whose configuration is being updated : the configuration being chosen. Context: In process context, must be able to sleep
Device interface drivers are not allowed to change device configurations. This is because changing configurations will destroy the interface the driver is bound to and create new ones; it would be like a floppy-disk driver telling the computer to replace the floppy-disk drive with a tape drive!
Still, in certain specialized circumstances the need may arise. This routine gets around the normal restrictions by using a work thread to submit the change-config request.
Returns 0 if the request was successfully queued, error code otherwise. The caller has no way to know whether the queued request will eventually succeed.
| void usb_enable_interface | ( | struct usb_device * | dev, |
| struct usb_interface * | intf, | ||
| bool | reset_eps | ||
| ) |
| int usb_get_descriptor | ( | struct usb_device * | dev, |
| unsigned char | type, | ||
| unsigned char | index, | ||
| void * | buf, | ||
| int | size | ||
| ) |
usb_get_descriptor - issues a generic GET_DESCRIPTOR request : the device whose descriptor is being retrieved : the descriptor type (USB_DT_*) : the number of the descriptor : where to put the descriptor : how big is "buf"? Context: !in_interrupt ()
Gets a USB descriptor. Convenience functions exist to simplify getting some types of descriptors. Use usb_get_string() or usb_string() for USB_DT_STRING. Device (USB_DT_DEVICE) and configuration descriptors (USB_DT_CONFIG) are part of the device structure. In addition to a number of USB-standard descriptors, some devices also use class-specific or vendor-specific descriptors.
This call is synchronous, and may not be used in an interrupt context.
Returns the number of bytes received on success, or else the status code returned by the underlying usb_control_msg() call.
usb_get_status - issues a GET_STATUS call : the device whose status is being checked : USB_RECIP_*; for device, interface, or endpoint : zero (for device), else interface or endpoint number : pointer to two bytes of bitmap data Context: !in_interrupt ()
Returns device, interface, or endpoint status. Normally only of interest to see if the device is self powered, or has enabled the remote wakeup facility; or whether a bulk or interrupt endpoint is halted ("stalled").
Bits in these status bitmaps are set using the SET_FEATURE request, and cleared using the CLEAR_FEATURE request. The usb_clear_halt() function should be used to clear halt ("stall") status.
This call is synchronous, and may not be used in an interrupt context.
Returns the number of bytes received on success, or else the status code returned by the underlying usb_control_msg() call.
| int usb_interrupt_msg | ( | struct usb_device * | usb_dev, |
| unsigned int | pipe, | ||
| void * | data, | ||
| int | len, | ||
| int * | actual_length, | ||
| int | timeout | ||
| ) |
usb_interrupt_msg - Builds an interrupt urb, sends it off and waits for completion : pointer to the usb device to send the message to : endpoint "pipe" to send the message to : pointer to the data to send : length in bytes of the data to send : pointer to a location to put the actual length transferred in bytes : time in msecs to wait for the message to complete before timing out (if 0 the wait is forever)
Context: !in_interrupt ()
This function sends a simple interrupt message to a specified endpoint and waits for the message to complete, or timeout.
If successful, it returns 0, otherwise a negative error number. The number of actual bytes transferred will be stored in the actual_length paramater.
Don't use this function from within an interrupt context, like a bottom half handler. If you need an asynchronous message, or need to send a message from within interrupt context, use usb_submit_urb() If a thread in your driver uses this call, make sure your disconnect() method can wait for it to complete. Since you don't have a handle on the URB used, you can't cancel the request.
usb_reset_configuration - lightweight device reset : the device whose configuration is being reset
This issues a standard SET_CONFIGURATION request to the device using the current configuration. The effect is to reset most USB-related state in the device, including interface altsettings (reset to zero), endpoint halts (cleared), and endpoint state (only for bulk and interrupt endpoints). Other usbcore state is unchanged, including bindings of usb device drivers to interfaces.
Because this affects multiple interfaces, avoid using this with composite (multi-interface) devices. Instead, the driver for each interface may use usb_set_interface() on the interfaces it claims. Be careful though; some devices don't support the SET_INTERFACE request, and others won't reset all the interface state (notably endpoint state). Resetting the whole configuration would affect other drivers' interfaces.
The caller must own the device lock.
Returns zero on success, else a negative error code.
usb_sg_cancel - stop scatter/gather i/o issued by usb_sg_wait() : request block, initialized with usb_sg_init()
This stops a request after it has been started by usb_sg_wait(). It can also prevents one initialized by usb_sg_init() from starting, so that call just frees resources allocated to the request.
| int usb_sg_init | ( | struct usb_sg_request * | io, |
| struct usb_device * | dev, | ||
| unsigned | pipe, | ||
| unsigned | period, | ||
| struct scatterlist * | sg, | ||
| int | nents, | ||
| size_t | length, | ||
| gfp_t | mem_flags | ||
| ) |
usb_sg_init - initializes scatterlist-based bulk/interrupt I/O request : request block being initialized. until usb_sg_wait() returns, treat this as a pointer to an opaque block of memory, : the usb device that will send or receive the data : endpoint "pipe" used to transfer the data : polling rate for interrupt endpoints, in frames or (for high speed endpoints) microframes; ignored for bulk : scatterlist entries : how many entries in the scatterlist : how many bytes to send from the scatterlist, or zero to send every byte identified in the list. : SLAB_* flags affecting memory allocations in this call
Returns zero for success, else a negative errno value. This initializes a scatter/gather request, allocating resources such as I/O mappings and urb memory (except maybe memory used by USB controller drivers).
The request must be issued using usb_sg_wait(), which waits for the I/O to complete (or to be canceled) and then cleans up all resources allocated by usb_sg_init().
The request may be canceled with usb_sg_cancel(), either before or after usb_sg_wait() is called.
usb_sg_wait - synchronously execute scatter/gather request : request block handle, as initialized with usb_sg_init(). some fields become accessible when this call returns. Context: !in_interrupt ()
This function blocks until the specified I/O operation completes. It leverages the grouping of the related I/O requests to get good transfer rates, by queueing the requests. At higher speeds, such queuing can significantly improve USB throughput.
There are three kinds of completion for this function. (1) success, where io->status is zero. The number of io->bytes transferred is as requested. (2) error, where io->status is a negative errno value. The number of io->bytes transferred before the error is usually less than requested, and can be nonzero. (3) cancellation, a type of error with status -ECONNRESET that is initiated by usb_sg_cancel().
When this function returns, all memory allocated through usb_sg_init() or this call will have been freed. The request block parameter may still be passed to usb_sg_cancel(), or it may be freed. It could also be reinitialized and then reused.
Data Transfer Rates:
Bulk transfers are valid for full or high speed endpoints. The best full speed data rate is 19 packets of 64 bytes each per frame, or 1216 bytes per millisecond. The best high speed data rate is 13 packets of 512 bytes each per microframe, or 52 KBytes per millisecond.
The reason to use interrupt transfers through this API would most likely be to reserve high speed bandwidth, where up to 24 KBytes per millisecond could be transferred. That capability is less useful for low or full speed interrupt endpoints, which allow at most one packet per millisecond, of at most 8 or 64 bytes (respectively).
It is not necessary to call this function to reserve bandwidth for devices under an xHCI host controller, as the bandwidth is reserved when the configuration or interface alt setting is selected.
usb_string - returns UTF-8 version of a string descriptor : the device whose string descriptor is being retrieved : the number of the descriptor : where to put the string : how big is "buf"? Context: !in_interrupt ()
This converts the UTF-16LE encoded strings returned by devices, from usb_get_string_descriptor(), to null-terminated UTF-8 encoded ones that are more usable in most kernel contexts. Note that this function chooses strings in the first language supported by the device.
This call is synchronous, and may not be used in an interrupt context.
Returns length of the string (>= 0) or usb_control_msg status (< 0).
| struct device_type usb_if_device_type |
1.8.2