The Linux-USB Host Side API
   Next

The Linux-USB Host Side API

This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

For more details see the file COPYING in the source distribution of Linux.

Table of Contents

1. Introduction to USB on Linux
2. USB Host-Side API Model
3. USB-Standard Types
struct usb_ctrlrequest - SETUP data for a USB device control request
4. Host-Side Data Types and Macros
struct usb_host_endpoint - host-side endpoint descriptor and queue
struct usb_interface - what usb device drivers talk to
struct usb_interface_cache - long-term representation of a device interface
struct usb_host_config - representation of a device's configuration
usb_interface_claimed - returns true iff an interface is claimed
usb_make_path - returns stable device path in the usb tree
USB_DEVICE - macro used to describe a specific usb device
USB_DEVICE_VER - macro used to describe a specific usb device with a
USB_DEVICE_INFO - macro used to describe a class of usb devices
USB_INTERFACE_INFO - macro used to describe a class of usb interfaces
struct usb_driver - identifies USB driver to usbcore
struct usb_class_driver - identifies a USB driver that wants to use the USB major number
struct urb - USB Request Block
usb_fill_control_urb - initializes a control urb
usb_fill_bulk_urb - macro to help initialize a bulk urb
usb_fill_int_urb - macro to help initialize a interrupt urb
struct usb_sg_request - support for scatter/gather I/O
5. USB Core APIs
usb_init_urb - initializes a urb so that it can be used by a USB driver
usb_alloc_urb - creates a new urb for a USB driver to use
usb_free_urb - frees the memory used by a urb when all users of it are finished
usb_get_urb - increments the reference count of the urb
usb_submit_urb - issue an asynchronous transfer request for an endpoint
usb_unlink_urb - abort/cancel a transfer request for an endpoint
usb_kill_urb - cancel a transfer request and wait for it to finish
usb_control_msg - Builds a control urb, sends it off and waits for completion
usb_bulk_msg - Builds a bulk urb, sends it off and waits for completion
usb_sg_init - initializes scatterlist-based bulk/interrupt I/O request
usb_sg_wait - synchronously execute scatter/gather request
usb_sg_cancel - stop scatter/gather i/o issued by usb_sg_wait
usb_get_descriptor - issues a generic GET_DESCRIPTOR request
usb_string - returns ISO 8859-1 version of a string descriptor
usb_get_status - issues a GET_STATUS call
usb_clear_halt - tells device to clear endpoint halt/stall condition
usb_set_interface - Makes a particular alternate setting be current
usb_reset_configuration - lightweight device reset
usb_register_dev - register a USB device, and ask for a minor number
usb_deregister_dev - deregister a USB device's dynamic minor.
usb_match_id - find first usb_device_id matching device or interface
usb_register_driver - register a USB driver
usb_deregister - unregister a USB driver
usb_ifnum_to_if - get the interface object with a given interface number
usb_altnum_to_altsetting - get the altsetting structure with a given
usb_driver_claim_interface - bind a driver to an interface
usb_driver_release_interface - unbind a driver from an interface
usb_find_interface - find usb_interface pointer for driver and device
usb_alloc_dev - usb device constructor (usbcore-internal)
usb_get_dev - increments the reference count of the usb device structure
usb_put_dev - release a use of the usb device structure
usb_get_intf - increments the reference count of the usb interface structure
usb_put_intf - release a use of the usb interface structure
usb_lock_device_for_reset - cautiously acquire the lock for a
usb_find_device - find a specific usb device in the system
usb_get_current_frame_number - return current bus frame number
usb_buffer_alloc - allocate dma-consistent buffer for URB_NO_xxx_DMA_MAP
usb_buffer_free - free memory allocated with usb_buffer_alloc
usb_buffer_map - create DMA mapping(s) for an urb
usb_buffer_dmasync - synchronize DMA and CPU view of buffer(s)
usb_buffer_unmap - free DMA mapping(s) for an urb
usb_buffer_map_sg - create scatterlist DMA mapping(s) for an endpoint
usb_buffer_dmasync_sg - synchronize DMA and CPU view of scatterlist buffer(s)
usb_buffer_unmap_sg - free DMA mapping(s) for a scatterlist
usb_hub_tt_clear_buffer - clear control/bulk TT state in high speed hub
usb_set_device_state - change a device's current state (usbcore, hcds)
usb_root_hub_lost_power - called by HCD if the root hub lost Vbus power
usb_disconnect - disconnect a device (usbcore-internal)
usb_reset_device - perform a USB port reset to reinitialize a device
6. Host Controller APIs
usb_calc_bus_time - approximate periodic transaction time in nanoseconds
usb_claim_bandwidth - records bandwidth for a periodic transfer
usb_release_bandwidth - reverses effect of usb_claim_bandwidth
usb_hcd_resume_root_hub - called by HCD to resume its root hub
usb_bus_start_enum - start immediate enumeration (for OTG)
usb_hcd_giveback_urb - return URB from HCD to device driver
usb_hc_died - report abnormal shutdown of a host controller (bus glue)
usb_create_hcd - create and initialize an HCD structure
usb_add_hcd - finish generic HCD structure initialization and register
usb_remove_hcd - shutdown processing for generic HCDs
usb_hcd_pci_probe - initialize PCI-based HCDs
usb_hcd_pci_remove - shutdown processing for PCI-based HCDs
usb_hcd_pci_suspend - power management suspend of a PCI-based HCD
usb_hcd_pci_resume - power management resume of a PCI-based HCD
hcd_buffer_create - initialize buffer pools
hcd_buffer_destroy - deallocate buffer pools
7. The USB Filesystem (usbfs)
What files are in "usbfs"?
Mounting and Access Control
/proc/bus/usb/devices
/proc/bus/usb/BBB/DDD
Life Cycle of User Mode Drivers
The ioctl() Requests
Management/Status Requests
Synchronous I/O Support
Asynchronous I/O Support
   Next
   Chapter 1. Introduction to USB on Linux