1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2016 Joyent, Inc. 13.\" 14.Dd Dec 20, 2016 15.Dt USBA_DEVICE 9S 16.Os 17.Sh NAME 18.Nm usba_device , 19.Nm usba_device_t 20.Nd USBA Device Data Structure 21.Sh SYNOPSIS 22.In sys/usb/usba/hcdi.h 23.Sh INTERFACE LEVEL 24.Sy Volatile - 25illumos USB HCD private 26.Pp 27This is a private data structure that is not part of the stable DDI. It 28may be removed or changed at any time. 29.Sh DESCRIPTION 30The 31.Sy usba_device_t 32structure is used by the illumos USB Architecture (USBA) to represent a 33physical USB device. While a given USB device may be a composite device, 34a USB device that implements two or more classes, there will still only 35be a single device structure. A USB device is always plugged into a 36port on some hub, excepting the root hub, and has an address on the USB 37fabric. 38.Pp 39Many of the USB HCD driver operations pass a 40.Sy usba_device_t 41to the HCD driver. The 42.Sy usba_device_t 43should be used by an HCD driver in a 44.Em read-only 45fashion. A subset of the structure's fields that are useful for HCD 46drivers to read are listed below. 47.Pp 48In addition, there are two optional HCD entry points that interact with 49this structure and give the change for a driver to store per-device 50state. If the driver implements the 51.Xr usba_hcdi_device_init 9E 52and 53.Xr usba_hcdi_device_fini 9E 54functions, then the private data stored from 55.Xr usba_hcdi_device_init 9E 56can be retrieved with 57.Xr usba_hcdi_get_device_private 9F . 58.Sh STRUCTURE MEMBERS 59The 60.Sy usba_device_t 61structure includes the following members: 62.Bd -literal -offset indent 63dev_info_t *usb_dip 64usba_hubdi_t *usb_hubdi; 65usb_addr_t usb_addr; 66usb_dev_descr_t *usb_dev_descr; 67char *usb_mfg_str; 68char *usb_product_str; 69char *usb_serialno_str; 70usb_port_status_t usb_port_status; 71usb_port_t usb_port; 72usba_device_t *usb_hs_hub_usba_dev; 73usba_device_t *usb_parent_hub; 74.Ed 75.Pp 76The 77.Sy usb_dip 78member is a pointer to the device's 79.Sy dev_info_t 80structure. This generally is used if the HCD driver wants to get naming 81information for diagnostic purposes. When duplicating requests for 82isochronous and interrupt requests, HCD drivers should use the 83.Sy dev_info_t 84from the 85.Xr usba_pipe_handle_data_t 9S . 86.Pp 87The 88.Sy usb_hubdi 89member can be used to determine whether or not the 90.Sy usba_device_t 91in question is a hub or not. HCD drivers should compare this member to 92.Dv NULL . 93If the member is not 94.Dv NULL , 95then this USB device corresponds to a hub. 96.Pp 97the 98.Sy usb_addr 99member indicates the address of the USB device on the broader USB bus. 100Note, that the actual address assigned to the device may be different, 101especially if the HCD driver implements the optional 102.Xr usba_hcdi_device_address 9E 103entry point. See the section 104.Sy USB addressing 105in 106.Xr usba_hcdi 9E 107for more information. 108.Pp 109The 110.Sy usb_dev_descr 111member points to the device descriptor for a given device. This 112structure is documented in 113.Xr usb_dev_descr 9S . 114This member may be 115.Dv NULL 116as it may not have been populated during device 117attachment. This member may be 118.Dv NULL . 119HCD drivers should always check for 120.Dv NULL 121before dereferencing it. 122.Pp 123The 124.Sy usb_mfg_str 125member may contain a pointer to a character string with the name of the 126manufacturer as retrieved from the device. This member may be 127.Dv NULL . 128HCD drivers should always check for 129.Dv NULL 130before dereferencing it. 131.Pp 132The 133.Sy usb_product_str 134member may contain a pointer to a character string with the name of the 135product as retrieved from the device. This member may be 136.Dv NULL . 137HCD drivers should always check for 138.Dv NULL 139before dereferencing it. 140.Pp 141The 142.Sy usb_serialno_str 143member may contain a pointer to a character string with the serial 144number of the device as retrieved from the device. This member may be 145.Dv NULL . 146HCD drivers should always check for 147.Dv NULL 148before dereferencing it. 149.Pp 150The 151.Sy usb_port_status_t 152contains a 153.Xr usb_port_status_t 154entry, which describes the current negotiated speed of the device. See 155.Xr usb_port_status_t 9T 156for more information on the values and types. 157.Pp 158The 159.Sy usb_port 160member contains the port on a hub that the device is plugged into. Ports 161are always numbered starting at 1. 162.Pp 163The 164.Sy usb_hs_hub_usba_dev 165member is set when there is a parent high-speed hub. This is most 166notable for low- and full- speed devices which require split 167transaction support. This points to the 168.Sy usb_device_t 169structure that is the closest high-speed parent hub. This member should 170always be set to 171.Dv NULL 172for super-speed devices. A device operating a super-speed can never be 173plugged into a high-speed hub. 174.Pp 175The 176.Sy usb_parent_hub 177member points to the 178.Sy usba_device_t 179structure that the device in question is plugged into. If the device 180represents the root hub, then this field will be 181.Dv NULL . 182.Sh SEE ALSO 183.Xr usba_hcdi 9E , 184.Xr usba_hcdi_device_address 9E , 185.Xr usba_hcdi_device_fini 9E , 186.Xr usba_hcdi_device_init 9E , 187.Xr usba_pipe_handle_data_t 9S , 188.Xr usb_port_status_t 9T 189