Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
USB(4)		       FreeBSD Kernel Interfaces Manual			USB(4)

NAME
     usb, uhub -- introduction to Universal Serial Bus support

SYNOPSIS
     # octeon specific
     dwctwo0 at	iobus? irq 56
     # all architectures
     ehci*   at	cardbus?
     ohci*   at	cardbus?
     uhci*   at	cardbus?
     ehci*   at	pci?
     ohci*   at	pci?
     uhci*   at	pci?
     xhci*   at	pci?
     usb*    at	dwctwo?
     usb*    at	ehci? flags 0x00
     usb*    at	ohci? flags 0x00
     usb*    at	uhci? flags 0x00
     usb*    at	xhci? flags 0x00
     uhub*   at	usb?
     uhub*   at	uhub?

     option    USBVERBOSE

     #include <dev/usb/usb.h>
     #include <dev/usb/usbhid.h>

DESCRIPTION
     OpenBSD provides machine-independent bus support and drivers for Univer-
     sal Serial	Bus (USB) devices.

     The OpenBSD usb driver has	three layers (like scsi(4) and pcmcia(4)): the
     controller, the bus, and the device layer.	 The controller	attaches to a
     physical bus (like	pci(4) or cardbus(4)).	The USB	bus attaches to	the
     controller	and the	root hub attaches to the USB bus.  Devices, which may
     include further hubs, attach to the root hub.  The	attachment forms the
     same tree structure as the	physical USB device tree.  For each USB	device
     there may be additional drivers attached to it.

     The uhub driver controls USB hubs and must	always be present since	there
     is	at least one root hub in any USB system.

     The flags are used	to specify if the devices on the USB bus should	be
     probed early in the boot process.	If the flags are specified with	a
     value of 1, the USB bus will be probed when the USB host device is	at-
     tached instead of waiting until kernel processes start running.

     OpenBSD provides support for the following	devices.  Note that not	all
     architectures support all devices.

   Storage devices
	umass(4)      USB Mass Storage Devices,	e.g., external disk drives

   Wired network interfaces
	aue(4)	      ADMtek AN986/ADM8511 Pegasus family 10/100 USB Ethernet
		      device
	axe(4)	      ASIX Electronics AX88172/AX88178/AX88772 10/100/Gigabit
		      USB Ethernet device
	axen(4)	      ASIX Electronics AX88179 10/100/Gigabit USB Ethernet de-
		      vice
	cdce(4)	      USB Communication	Device Class Ethernet device
	cue(4)	      CATC USB-EL1201A USB Ethernet device
	kue(4)	      Kawasaki LSI KL5KUSB101B USB Ethernet device
	mos(4)	      MosChip MCS7730/7830/7832	10/100 USB Ethernet device
	mue(4)	      Microchip	LAN75xx/LAN78xx	10/100/Gigabit USB Ethernet
		      device
	smsc(4)	      SMSC LAN95xx 10/100 USB Ethernet device
	udav(4)	      Davicom DM9601 10/100 USB	Ethernet device
	ure(4)	      RealTek RTL8152/RTL8153/RTL8153B/RTL8156 10/100/Giga-
		      bit/2.5Gb	USB Ethernet device
	url(4)	      Realtek RTL8150L 10/100 USB Ethernet device
	urndis(4)     USB Remote NDIS Ethernet device

   Wireless network interfaces
	athn(4)	      Atheros IEEE 802.11a/b/g/n wireless network device
	atu(4)	      Atmel AT76C50x IEEE 802.11b wireless network device
	bwfm(4)	      Broadcom and Cypress IEEE	802.11a/ac/b/g/n wireless net-
		      work device
	otus(4)	      Atheros USB IEEE 802.11a/b/g/n wireless network device
	rsu(4)	      Realtek RTL8188SU/RTL8192SU USB IEEE 802.11b/g/n wire-
		      less network device
	rum(4)	      Ralink Technology/MediaTek USB IEEE 802.11a/b/g wireless
		      network device
	run(4)	      Ralink Technology/MediaTek USB IEEE 802.11a/b/g/n	wire-
		      less network device
	uath(4)	      Atheros USB IEEE 802.11a/b/g wireless network device
	upgt(4)	      Conexant/Intersil	PrismGT	SoftMAC	USB IEEE 802.11b/g
		      wireless network device
	ural(4)	      Ralink Technology/MediaTek USB IEEE 802.11b/g wireless
		      network device
	urtw(4)	      Realtek RTL8187L/RTL8187B	USB IEEE 802.11b/g wireless
		      network device
	urtwn(4)      Realtek RTL8188CU/RTL8188EU/RTL8192CU/RTL8192EU USB IEEE
		      802.11b/g/n wireless network device
	wi(4)	      Intersil PRISM 2-3 IEEE 802.11b wireless network device
	zyd(4)	      ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network
		      device

   Serial and parallel interfaces
	moscom(4)     MosChip Semiconductor MCS7703 based USB serial adapter
	uark(4)	      Arkmicro Technologies ARK3116 based USB serial adapter
	ubsa(4)	      Belkin USB serial	adapter
	uchcom(4)     WinChipHead CH341/340 based USB serial adapter
	ucom(4)	      USB tty support
	ucrcom(4)     Chromebook USB serial console
	ucycom(4)     Cypress microcontroller based USB	serial adapter
	uftdi(4)      FTDI USB serial adapter
	uipaq(4)      iPAQ USB units
	ukspan(4)     Keyspan USB serial adapter
	ulpt(4)	      USB printer support
	umcs(4)	      MosChip Semiconductor based USB multiport	serial adapter
	umct(4)	      MCT USB-RS232 USB	serial adapter
	umodem(4)     USB modem	support
	umsm(4)	      Qualcomm MSM modem device
	uplcom(4)     Prolific PL-2303 USB serial adapter
	uscom(4)      simple USB serial	adapters
	uslcom(4)     Silicon Laboratories CP210x based	USB serial adapter
	uslhcom(4)    Silicon Laboratories CP2110 based	USB serial adapter
	uticom(4)     Texas Instruments	TUSB3410 USB serial adapter
	uvisor(4)     USB Handspring Visor
	uvscom(4)     SUNTAC Slipper U VS-10U USB serial adapter
	uxrcom(4)     Exar XR21V1410 USB serial	adapter

   Audio devices
	uaudio(4)     USB audio	devices
	umidi(4)      USB MIDI devices

   Video devices
	udl(4)	      DisplayLink DL-120 / DL-160 USB display devices
	utvfu(4)      USB Fushicai USBTV007 audio/video	capture	device
	uvideo(4)     USB video	devices

   Time	receiver devices
	udcf(4)	      Gude ADS Expert mouseCLOCK USB timedelta sensor
	umbg(4)	      Meinberg Funkuhren USB5131 timedelta sensor

   Radio receiver devices
	udsbr(4)      D-Link DSB-R100 USB radio	device

   Human Interface Devices
	fido(4)	      FIDO/U2F security	keys
	ubcmtp(4)     Broadcom trackpad	mouse
	ugold(4)      TEMPer gold HID thermometer and hygrometer
	uhid(4)	      Generic driver for Human Interface Devices
	uhidev(4)     Base driver for all Human	Interface Devices
	uhidpp(4)     Logitech HID++ devices
	ujoy(4)	      USB joysticks/gamecontrollers
	ukbd(4)	      USB keyboards that follow	the boot protocol
	ums(4)	      USB HID mouse, touchscreen and digitiser devices
	umstc(4)      Microsoft	Surface	Type Cover keyboard
	umt(4)	      USB HID multitouch touchpad devices
	uoaklux(4)    Toradex OAK USB illuminance sensor
	uoakrh(4)     Toradex OAK USB temperature and relative humidity	sensor
	uoakv(4)      Toradex OAK USB +/-10V 8channel ADC interface
	upd(4)	      USB Power	Devices	sensor
	uthum(4)      TEMPer HID thermometer and hygrometer
	utpms(4)      Apple touchpad mouse
	utrh(4)	      USBRH temperature	and humidity sensor
	utwitch(4)    YUREX USB	twitch/jiggle of knee sensor
	uwacom(4)     Wacom USB	tablets

   WAN network devices
	umb(4)	      USB Mobile Broadband Interface Model (MBIM)

   Miscellaneous devices
	uberry(4)     Research In Motion BlackBerry
	ugen(4)	      USB generic device support
	ugl(4)	      Genesys Logic based host-to-host adapters
	uonerng(4)    Moonbase Otago OneRNG TRNG
	uow(4)	      Maxim/Dallas DS2490 USB 1-Wire adapter
	upl(4)	      Prolific based host-to-host adapters
	urng(4)	      USB Random Number	Generator devices
	usps(4)	      USPS composite AC	power and temperature sensor
	uts(4)	      USB touchscreen support

INTRODUCTION TO	USB
     There are different versions of the USB which provide different speeds.
     USB 3 can operate up to 5.0Gb/s.  USB 2 operates at 480Mb/s, while	USB
     versions 1	and 1.1	operate	at 12 Mb/s and 1.5 Mb/s	for low	speed devices.
     Each USB has a host controller that is the	master of the bus; all other
     devices on	the bus	only speak when	spoken to.

     There can be up to	127 devices (apart from	the host controller) on	a bus,
     each with its own address.	 The addresses are assigned dynamically	by the
     host when each device is attached to the bus.

     Within each device	there can be up	to 16 endpoints.  Each endpoint	is in-
     dividually	addressed and the addresses are	static.	 Each of these end-
     points will communicate in	one of four different modes: control,
     isochronous, bulk,	or interrupt.  A device	always has at least one	end-
     point.  This is a control endpoint	at address 0 and is used to give com-
     mands to the device and extract basic data, such as descriptors, from the
     device.  Each endpoint, except the	control	endpoint, is unidirectional.

     The endpoints in a	device are grouped into	interfaces.  An	interface is a
     logical unit within a device; e.g., a compound device with	both a key-
     board and a trackball would present one interface for each.  An interface
     can sometimes be set into different modes,	called alternate settings,
     which affects how it operates.  Different alternate settings can have
     different endpoints within	it.

     A device may operate in different configurations.	Depending on the con-
     figuration	the device may present different sets of endpoints and inter-
     faces.

     Each device located on a hub has several config(8)	locators:

     port	    Number of the port on closest upstream hub.
     configuration  Configuration the device must be in	for this driver	to at-
		    tach.  This	locator	does not set the configuration;	it is
		    iterated by	the bus	enumeration.
     interface	    Interface number within a device that an interface driver
		    attaches to.
     vendor	    16-bit vendor ID of	the device.
     product	    16-bit product ID of the device.
     release	    16-bit release (revision) number of	the device.

     The first locator can be used to pin down a particular device according
     to	its physical position in the device tree.  The last three locators can
     be	used to	pin down a particular device according to what device it actu-
     ally is.

     The bus enumeration of the	USB bus	proceeds in several steps:

     1.	  Any device-specific driver can attach	to the device.

     2.	  If none is found, any	device class specific driver can attach.

     3.	  If none is found, all	configurations are iterated over.  For each
	  configuration	all the	interfaces are iterated	over and interface
	  drivers can attach.  If any interface	driver attached	in a certain
	  configuration, the iteration over configurations is stopped.

     4.	  If still no drivers have been	found, the generic USB driver can at-
	  tach.

USB CONTROLLER INTERFACE
     Use the following to get access to	the USB	specific structures and	de-
     fines:

	   #include <dev/usb/usb.h>

     The /dev/usbN device can be opened	and a few operations can be performed
     on	it.  The following ioctl(2) commands are supported on the controller
     device:

     USB_DEVICEINFO struct usb_device_info
	     This command can be used to retrieve some information about a de-
	     vice on the bus.  The udi_addr field should be filled before the
	     call and the other	fields will be filled by information about the
	     device on that address.  Should no	such device exist, an error is
	     reported.

	     #define USB_MAX_DEVNAMES 4
	     #define USB_MAX_DEVNAMELEN	16
	     struct usb_device_info {
		     u_int8_t	     udi_bus;
		     u_int8_t	     udi_addr;	     /*	device address */
		     char	     udi_product[USB_MAX_STRING_LEN];
		     char	     udi_vendor[USB_MAX_STRING_LEN];
		     char	     udi_release[8];
		     u_int16_t	     udi_productNo;
		     u_int16_t	     udi_vendorNo;
		     u_int16_t	     udi_releaseNo;
		     u_int8_t	     udi_class;
		     u_int8_t	     udi_subclass;
		     u_int8_t	     udi_protocol;
		     u_int8_t	     udi_config;
		     u_int8_t	     udi_speed;
	     #define USB_SPEED_LOW   1
	     #define USB_SPEED_FULL  2
	     #define USB_SPEED_HIGH  3
	     #define USB_SPEED_SUPER 4
		     u_int8_t	     udi_port;
		     int	     udi_power;	     /*	power consumption */
		     int	     udi_nports;
		     char	     udi_devnames[USB_MAX_DEVNAMES]
					 [USB_MAX_DEVNAMELEN];
		     u_int32_t	     udi_ports[16];  /*	hub only */
		     char	     udi_serial[USB_MAX_STRING_LEN];
	     };

	     The udi_bus field contains	the device unit	number of the device.

	     The udi_product, udi_vendor, and udi_release fields contain self-
	     explanatory descriptions of the device.  The udi_productNo,
	     udi_vendorNo, and udi_releaseNo fields contain numeric identi-
	     fiers for the device.

	     The udi_class and udi_subclass fields contain the device class
	     and subclass.

	     The udi_config field shows	the current configuration of the de-
	     vice.

	     The udi_protocol field contains the device	protocol as given from
	     the device.

	     The udi_speed field contains the speed of the device.

	     The udi_power field shows the power consumption in	milli-amps
	     drawn at 5	volts or is zero if the	device is self powered.

	     The udi_devnames field contains the names and instance numbers of
	     the device	drivers	for the	devices	attached to this device.

	     If	the device is a	hub, the udi_nports field is non-zero and the
	     udi_ports field contains the addresses of the connected devices.
	     If	no device is connected to a port, one of the USB_PORT_*	values
	     indicates its status.

     USB_DEVICESTATS struct usb_device_stats
	     This command retrieves statistics about the controller.

	     struct usb_device_stats {
		     u_long  uds_requests[4];
	     };

	     The uds_requests field is indexed by the transfer kind, i.e.
	     UE_*, and indicates how many transfers of each kind have been
	     completed by the controller.

     USB_DEVICE_GET_DDESC struct usb_device_ddesc
	     This command can be used to retrieve the device descriptor	of a
	     device on the bus.	 The udd_addr field needs to be	filled with
	     the bus device address:

	     struct usb_device_ddesc {
		     u_int8_t	     udd_bus;
		     u_int8_t	     udd_addr;	     /*	device address */
		     usb_device_descriptor_t udd_desc;
	     };

	     The udd_bus field contains	the device unit	number.

	     The udd_desc field	contains the device descriptor structure.

     USB_DEVICE_GET_CDESC struct usb_device_cdesc
	     This command can be used to retrieve the configuration descriptor
	     for the given configuration of a device on	the bus.  The udc_addr
	     field needs to be filled with the bus device address.  The
	     udc_config_index field needs to be	filled with the	configuration
	     index for the relevant configuration descriptor.  For convenience
	     the current configuration can be specified	by
	     USB_CURRENT_CONFIG_INDEX:

	     struct usb_device_cdesc {
		     u_int8_t	     udc_bus;
		     u_int8_t	     udc_addr;	     /*	device address */
		     int	     udc_config_index;
		     usb_config_descriptor_t udc_desc;
	     };

	     The udc_bus field contains	the device unit	number.

	     The udc_desc field	contains the configuration descriptor struc-
	     ture.

     USB_DEVICE_GET_FDESC struct usb_device_fdesc
	     This command can be used to retrieve all descriptors for the
	     given configuration of a device on	the bus.  The udf_addr field
	     needs to be filled	with the bus device address.  The
	     udf_config_index field needs to be	filled with the	configuration
	     index for the relevant configuration descriptor.  For convenience
	     the current configuration can be specified	by
	     USB_CURRENT_CONFIG_INDEX.	The udf_data field needs to point to a
	     memory area of the	size given in the udf_size field.  The proper
	     size can be determined by first issuing a USB_DEVICE_GET_CDESC
	     command and inspecting the	wTotalLength field:

	     struct usb_device_fdesc {
		     u_int8_t	      udf_bus;
		     u_int8_t	      udf_addr;	     /*	device address */
		     int	      udf_config_index;
		     u_int	      udf_size;
		     u_char	     *udf_data;
	     };

	     The udf_bus field contains	the device unit	number.

	     The udf_data field	contains all descriptors.

     USB_REQUEST struct	usb_ctl_request
	     This command can be used to execute arbitrary requests on the
	     control pipe.  This is DANGEROUS and should be used with great
	     care since	it can destroy the bus integrity.

	     The usb_ctl_request structure has the following definition:

	     typedef struct {
		     uByte	     bmRequestType;
		     uByte	     bRequest;
		     uWord	     wValue;
		     uWord	     wIndex;
		     uWord	     wLength;
	     } __packed	usb_device_request_t;

	     struct usb_ctl_request {
		     int     ucr_addr;
		     usb_device_request_t ucr_request;
		     void    *ucr_data;
		     int     ucr_flags;
	     #define USBD_SHORT_XFER_OK	0x04 /*	allow short reads */
		     int     ucr_actlen;     /*	actual length transferred */
	     };

	     The ucr_addr field	identifies the device on which to perform the
	     request.  The ucr_request field identifies	parameters of the re-
	     quest, such as length and type.  The ucr_data field contains the
	     location where data will be read from or written to.  The
	     ucr_flags field specifies options for the request,	and the
	     ucr_actlen	field contains the actual length transferred as	the
	     result of the request.

     The include file <dev/usb/usb.h> contains definitions for the types used
     by	the various ioctl(2) calls.  The naming	convention of the fields for
     the various USB descriptors exactly follows the naming in the USB speci-
     fication.	Byte sized fields can be accessed directly, but	word (16-bit)
     sized fields must be accessed by the UGETW(field) and USETW(field,	value)
     macros and	double word (32-bit) sized fields must be accessed by the
     UGETDW(field) and USETDW(field, value) macros to handle byte order	and
     alignment properly.

     The include file <dev/usb/usbhid.h> similarly contains the	definitions
     for Human Interface Devices (HID).

SEE ALSO
     usbhidaction(1), usbhidctl(1), ioctl(2), dwctwo(4), ehci(4), ohci(4),
     uhci(4), xhci(4), config(8), usbdevs(8)

     The USB specifications can	be found at: https://www.usb.org/documents

HISTORY
     The usb driver appeared in	OpenBSD	2.6.

FreeBSD	13.0			March 13, 2021			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | INTRODUCTION TO USB | USB CONTROLLER INTERFACE | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=usb&sektion=4&manpath=OpenBSD+6.9>

home | help