libusb prototypes in Linux (usb.h)

Note: These routines extensively use data descriptor structures that contain a series of bytes with a header identifying the length and type of the data. See descriptors.c for the code dealing with these.

usb_dev_handle *usb_open(struct usb_device *dev);

• Allocates a usb_dev_handle that points to dev and the bus that dev is on.
• Sets the fd, config, interface, and altsetting pointers to -1 (undefined).
• Calls usb_os_open which gets a file descriptor from device_open.

int usb_close(usb_dev_handle *dev);

• Calls usb_os_close to try and close the file descriptor.
• Deallocates dev.

int usb_get_string(usb_dev_handle *dev, int index, int langid, char *buf, size_t buflen);

• Uses usb_control_msg to send request_type 0x80, request 0x06, with value=0x03 in high byte and index in lower byte, index=langid, buf, buflen, and size=1000.

int usb_get_string_simple(usb_dev_handle *dev, int index, char *buf, size_t buflen);

• Uses usb_control_msg to send request_type 0x00, request 0x00, to get list of language IDs.
• Uses usb_get_string with index, the first language ID, and a temporary buffer to get and parse a string descriptor.

int usb_get_descriptor_by_endpoint(usb_dev_handle *udev, int ep, unsigned char type, unsigned char index, void *buf, int size);

• Uses usb_control_msg to send request_type=ep OR'ed with 0x80, request 0x06, with value=type in its upper byte and index in its lower byte.
• buf is cleared and filled with up to 1000 bytes of descriptor.

int usb_get_descriptor(usb_dev_handle *udev, unsigned char type, unsigned char index, void *buf, int size);

• Identical to usb_get_descriptor_by_endpoint, but does not OR in the endpoint.

int usb_bulk_write(usb_dev_handle *dev, int ep, char *bytes, int size, int timeout);

int usb_bulk_read(usb_dev_handle *dev, int ep, char *bytes, int size, int timeout);

• Uses usb_urb_transfer (urb=usb request block) of type 3 (bulk) to transfer bytes in 16kB blocks within timeout milliseconds. The endpoint ep determines whether the transfer is a write or a read.
• A read ioctl system call is used with arguments file descriptor, 0x55, and 10 with the submission in a struct usb_urb.
• A write ioctl is then used with arguments file descriptor and 13 retrieve any completed blocks.
• If the transfer does not complete in success or error, then it is canceled with an ioctl with arguments of file descriptor and 11 followed by a final write ioctl with arguments file descriptor and 12.
• The total bytes transferred are returned or a timeout error message.

int usb_interrupt_write(usb_dev_handle *dev, int ep, char *bytes, int size, int timeout);

• Just like the bulk read/write functions except that the urb is of type 1 (interrupt).

int usb_interrupt_read(usb_dev_handle *dev, int ep, char *bytes, int size, int timeout);

• Just like the bulk read/write functions except that the urb is of type 1 (interrupt) and the endpoint is ORed with 0x80.

int usb_control_msg(usb_dev_handle *dev, int requesttype, int request, int value, int index, char *bytes, int size, int timeout);

• Sends a read/write ioctl system call with arguments file descriptor, 0x55, 0, and a struct usb_ctrltransfer holding requesttype, request, etc.

int usb_set_configuration(usb_dev_handle *dev, int configuration);

• Sends a read ioctl system call with arguments file descriptor, 0x55, 5, and the configuration integer.

int usb_claim_interface(usb_dev_handle *dev, int interface);

• Sends a read ioctl system call with arguments file descriptor, 0x55, 15, and the interface integer.

int usb_release_interface(usb_dev_handle *dev, int interface);

• Sends a read ioctl system call with arguments file descriptor, 0x55, 16, and the interface integer.

int usb_set_altinterface(usb_dev_handle *dev, int alternate);

• Sends a read ioctl system call with arguments file descriptor, 0x55, 4, and a struct usb_setinterface holding interface and specifying alternate.

int usb_resetep(usb_dev_handle *dev, unsigned int ep);

• Sends a read ioctl system call with arguments file descriptor, 0x55, 3, and the ep integer.

int usb_clear_halt(usb_dev_handle *dev, unsigned int ep);

• Sends a read ioctl system call with arguments file descriptor, 0x55, 21, and the ep integer.

int usb_reset(usb_dev_handle *dev);

• Sends an ioctl system call with arguments file descriptor, 0x55, 20.

int usb_get_driver_np(usb_dev_handle *dev, int interface, char *name, unsigned int namelen);

• Sends a control ioctl system call with arguments file descriptor, 0x55, 0, and a struct usb_ctrltransfer holding requesttype, request, etc.

int usb_detach_kernel_driver_np(usb_dev_handle *dev, int interface);

• Sends a control ioctl system call with arguments file descriptor, 0x55, 0, and a struct usb_ctrltransfer holding requesttype, request, etc.

char *usb_strerror(void);

• Returns an error message depending on usb_error_type: "no error", usb_error_str, system string corresponding to usb_error_errno, or "Unknown error". Errors are reported using the macros USB_ERROR(x) and USB_ERROR_STR(x, format, args). See error.h for details and usb.c for examples.

void usb_init(void);

• If the environment variable USB_DEBUG exists, sets usb_debug to its value.
• Uses usb_os_init which tries to set usb_path.
  • If USB_DEVFS_PATH, a usb filesystem environmental variable is defined it is used.
  • Otherwise, it checks for entries in /dev/bus/usb, and if it finds any, sets usb_path=/dev/bus/usb with a zero byte termination.
  • Finally, if both of those fail, it checks for non-hidden entries in /proc/bus/usb, and if it finds any, sets usb_path=/proc/bus/usb.

void usb_set_debug(int level);

• Sets usb_debug=level and prints message on stderr. Debug levels of 0 up to 2 are used in libusb.

int usb_find_busses(void);

• Does a usb_os_find_busses to get a list of current busses and allocate their structures. usb_os_find_busses does this by noting the directories in usb_path that have entirely numeric names.
• usb_find_busses then updates its usb_busses linked list accordingly and deallocates busses that are no longer present.
• The return integer reports the number of changes.

int usb_find_devices(void);

• For each bus it does usb_os_find_devices to get a list of current devices on that bus. usb_os_find_devices does this by:
  • Looking for non-zero, non-hidden files in each bus directory
  • Opening them
  • Uses a write ioctl with the file descriptor, 0x55, and 17 to obtain struct usb_connectinfo.
  • Parses the usb_connectinfo using usb_parse_descriptor
  • Adds it to the linked list, struct usb_device *devices.
• usb_os_find_devices then parses all reported configuration descriptors and closes the file descriptor.
• usb_find_devices then updates the struct usb_dev in struct usb_bus usb_busses.
• Finally, it does usb_os_determine_children which ...

struct usb_device *usb_device(usb_dev_handle *dev);

• Returns the struct usb_device corresponding to the usb_dev_handle* dev.

struct usb_bus *usb_get_busses(void);

• Returns the struct usb_bus busses.

Last updated: December 28, 2006