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. 28It may 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. 34While a given USB device may be a composite device, a USB device that implements 35two or more classes, there will still only be a single device structure. 36A USB device is always plugged into a port on some hub, excepting the root hub, 37and has an address on the USB fabric. 38.Pp 39Many of the USB HCD driver operations pass a 40.Sy usba_device_t 41to the HCD driver. 42The 43.Sy usba_device_t 44should be used by an HCD driver in a 45.Em read-only 46fashion. 47A subset of the structure's fields that are useful for HCD drivers to read are 48listed below. 49.Pp 50In addition, there are two optional HCD entry points that interact with 51this structure and give the change for a driver to store per-device 52state. 53If the driver implements the 54.Xr usba_hcdi_device_init 9E 55and 56.Xr usba_hcdi_device_fini 9E 57functions, then the private data stored from 58.Xr usba_hcdi_device_init 9E 59can be retrieved with 60.Xr usba_hcdi_get_device_private 9F . 61.Sh STRUCTURE MEMBERS 62The 63.Sy usba_device_t 64structure includes the following members: 65.Bd -literal -offset indent 66dev_info_t *usb_dip 67usba_hubdi_t *usb_hubdi; 68usb_addr_t usb_addr; 69usb_dev_descr_t *usb_dev_descr; 70char *usb_mfg_str; 71char *usb_product_str; 72char *usb_serialno_str; 73usb_port_status_t usb_port_status; 74usb_port_t usb_port; 75usba_device_t *usb_hs_hub_usba_dev; 76usba_device_t *usb_parent_hub; 77.Ed 78.Pp 79The 80.Sy usb_dip 81member is a pointer to the device's 82.Sy dev_info_t 83structure. 84This generally is used if the HCD driver wants to get naming information for 85diagnostic purposes. 86When duplicating requests for isochronous and interrupt requests, HCD drivers 87should use the 88.Sy dev_info_t 89from the 90.Xr usba_pipe_handle_data_t 9S . 91.Pp 92The 93.Sy usb_hubdi 94member can be used to determine whether or not the 95.Sy usba_device_t 96in question is a hub or not. 97HCD drivers should compare this member to 98.Dv NULL . 99If the member is not 100.Dv NULL , 101then this USB device corresponds to a hub. 102.Pp 103the 104.Sy usb_addr 105member indicates the address of the USB device on the broader USB bus. 106Note, that the actual address assigned to the device may be different, 107especially if the HCD driver implements the optional 108.Xr usba_hcdi_device_address 9E 109entry point. 110See the section 111.Sy USB addressing 112in 113.Xr usba_hcdi 9E 114for more information. 115.Pp 116The 117.Sy usb_dev_descr 118member points to the device descriptor for a given device. 119This structure is documented in 120.Xr usb_dev_descr 9S . 121This member may be 122.Dv NULL 123as it may not have been populated during device 124attachment. 125This member may be 126.Dv NULL . 127HCD drivers should always check for 128.Dv NULL 129before dereferencing it. 130.Pp 131The 132.Sy usb_mfg_str 133member may contain a pointer to a character string with the name of the 134manufacturer as retrieved from the device. 135This member may be 136.Dv NULL . 137HCD drivers should always check for 138.Dv NULL 139before dereferencing it. 140.Pp 141The 142.Sy usb_product_str 143member may contain a pointer to a character string with the name of the 144product as retrieved from the device. 145This member may be 146.Dv NULL . 147HCD drivers should always check for 148.Dv NULL 149before dereferencing it. 150.Pp 151The 152.Sy usb_serialno_str 153member may contain a pointer to a character string with the serial 154number of the device as retrieved from the device. 155This member may be 156.Dv NULL . 157HCD drivers should always check for 158.Dv NULL 159before dereferencing it. 160.Pp 161The 162.Sy usb_port_status 163contains a 164.Sy usb_port_status_t 165entry, which describes the current negotiated speed of the device. 166See 167.Xr usba_hcdi 9E 168for more information on the values and types. 169.Pp 170The 171.Sy usb_port 172member contains the port on a hub that the device is plugged into. 173Ports are always numbered starting at 1. 174.Pp 175The 176.Sy usb_hs_hub_usba_dev 177member is set when there is a parent high-speed hub. 178This is most notable for low- and full- speed devices which require split 179transaction support. 180This points to the 181.Sy usb_device_t 182structure that is the closest high-speed parent hub. 183This member should 184always be set to 185.Dv NULL 186for super-speed devices. 187A device operating a super-speed can never be plugged into a high-speed hub. 188.Pp 189The 190.Sy usb_parent_hub 191member points to the 192.Sy usba_device_t 193structure that the device in question is plugged into. 194If the device represents the root hub, then this field will be 195.Dv NULL . 196.Sh SEE ALSO 197.Xr usba_hcdi 9E , 198.Xr usba_hcdi_device_address 9E , 199.Xr usba_hcdi_device_fini 9E , 200.Xr usba_hcdi_device_init 9E , 201.Xr usba_pipe_handle_data_t 9S 202