iPXE
usbhub.h
Go to the documentation of this file.
1 #ifndef _USBHUB_H
2 #define _USBHUB_H
3 
4 /** @file
5  *
6  * USB hubs
7  *
8  */
9 
10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
11 
12 #include <ipxe/usb.h>
13 #include <ipxe/list.h>
14 #include <ipxe/process.h>
15 
16 /** Request recipient is a port */
17 #define USB_HUB_RECIP_PORT ( 3 << 0 )
18 
19 /** A basic USB hub descriptor */
21  /** Descriptor header */
23  /** Number of ports */
25  /** Characteristics */
27  /** Power-on delay (in 2ms intervals */
29  /** Controller current (in mA) */
31 } __attribute__ (( packed ));
32 
33 /** A basic USB hub descriptor */
34 #define USB_HUB_DESCRIPTOR 41
35 
36 /** An enhanced USB hub descriptor */
38  /** Basic USB hub descriptor */
40  /** Header decode latency */
42  /** Maximum delay */
44  /** Removable device bitmask */
46 } __attribute__ (( packed ));
47 
48 /** An enhanced USB hub descriptor */
49 #define USB_HUB_DESCRIPTOR_ENHANCED 42
50 
51 /** A USB hub descriptor */
53  /** Descriptor header */
55  /** Basic hub descriptor */
57  /** Enhanced hub descriptor */
59 } __attribute__ (( packed ));
60 
61 /** Port status */
63  /** Current status */
65  /** Changed status */
67 } __attribute__ (( packed ));
68 
69 /** Current connect status feature */
70 #define USB_HUB_PORT_CONNECTION 0
71 
72 /** Port enabled/disabled feature */
73 #define USB_HUB_PORT_ENABLE 1
74 
75 /** Port reset feature */
76 #define USB_HUB_PORT_RESET 4
77 
78 /** Port power feature */
79 #define USB_HUB_PORT_POWER 8
80 
81 /** Low-speed device attached */
82 #define USB_HUB_PORT_LOW_SPEED 9
83 
84 /** High-speed device attached */
85 #define USB_HUB_PORT_HIGH_SPEED 10
86 
87 /** Connect status changed */
88 #define USB_HUB_C_PORT_CONNECTION 16
89 
90 /** Port enable/disable changed */
91 #define USB_HUB_C_PORT_ENABLE 17
92 
93 /** Suspend changed */
94 #define USB_HUB_C_PORT_SUSPEND 18
95 
96 /** Over-current indicator changed */
97 #define USB_HUB_C_PORT_OVER_CURRENT 19
98 
99 /** Reset changed */
100 #define USB_HUB_C_PORT_RESET 20
101 
102 /** Link state changed */
103 #define USB_HUB_C_PORT_LINK_STATE 25
104 
105 /** Configuration error */
106 #define USB_HUB_C_PORT_CONFIG_ERROR 26
107 
108 /** Calculate feature from change bit number */
109 #define USB_HUB_C_FEATURE( bit ) ( 16 + (bit) )
110 
111 /** USB features */
112 #define USB_HUB_FEATURES \
113  ( ( 1 << USB_HUB_C_PORT_CONNECTION ) | \
114  ( 1 << USB_HUB_C_PORT_ENABLE ) | \
115  ( 1 << USB_HUB_C_PORT_SUSPEND ) | \
116  ( 1 << USB_HUB_C_PORT_OVER_CURRENT ) | \
117  ( 1 << USB_HUB_C_PORT_RESET ) )
118 
119 /** USB features for enhanced hubs */
120 #define USB_HUB_FEATURES_ENHANCED \
121  ( ( 1 << USB_HUB_C_PORT_CONNECTION ) | \
122  ( 1 << USB_HUB_C_PORT_OVER_CURRENT ) | \
123  ( 1 << USB_HUB_C_PORT_RESET ) | \
124  ( 1 << USB_HUB_C_PORT_LINK_STATE ) | \
125  ( 1 << USB_HUB_C_PORT_CONFIG_ERROR ) )
126 
127 /** Set hub depth */
128 #define USB_HUB_SET_HUB_DEPTH \
129  ( USB_DIR_OUT | USB_TYPE_CLASS | USB_RECIP_DEVICE | \
130  USB_REQUEST_TYPE ( 12 ) )
131 
132 /** Clear transaction translator buffer */
133 #define USB_HUB_CLEAR_TT_BUFFER \
134  ( USB_DIR_OUT | USB_TYPE_CLASS | USB_HUB_RECIP_PORT | \
135  USB_REQUEST_TYPE ( 8 ) )
136 
137 /**
138  * Get hub descriptor
139  *
140  * @v usb USB device
141  * @v enhanced Hub is an enhanced hub
142  * @v data Hub descriptor to fill in
143  * @ret rc Return status code
144  */
145 static inline __attribute__ (( always_inline )) int
146 usb_hub_get_descriptor ( struct usb_device *usb, int enhanced,
147  union usb_hub_descriptor *data ) {
148  unsigned int desc;
149  size_t len;
150 
151  /* Determine descriptor type and length */
153  len = ( enhanced ? sizeof ( data->enhanced ) : sizeof ( data->basic ) );
154 
155  return usb_get_descriptor ( usb, USB_TYPE_CLASS, desc, 0, 0,
156  &data->header, len );
157 }
158 
159 /**
160  * Get port status
161  *
162  * @v usb USB device
163  * @v port Port address
164  * @v status Port status descriptor to fill in
165  * @ret rc Return status code
166  */
167 static inline __attribute__ (( always_inline )) int
168 usb_hub_get_port_status ( struct usb_device *usb, unsigned int port,
169  struct usb_hub_port_status *status ) {
170 
172  port, status, sizeof ( *status ) );
173 }
174 
175 /**
176  * Clear port feature
177  *
178  * @v usb USB device
179  * @v port Port address
180  * @v feature Feature to clear
181  * @v index Index (when clearing a port indicator)
182  * @ret rc Return status code
183  */
184 static inline __attribute__ (( always_inline )) int
185 usb_hub_clear_port_feature ( struct usb_device *usb, unsigned int port,
186  unsigned int feature, unsigned int index ) {
187 
189  feature, ( ( index << 8 ) | port ) );
190 }
191 
192 /**
193  * Set port feature
194  *
195  * @v usb USB device
196  * @v port Port address
197  * @v feature Feature to clear
198  * @v index Index (when clearing a port indicator)
199  * @ret rc Return status code
200  */
201 static inline __attribute__ (( always_inline )) int
202 usb_hub_set_port_feature ( struct usb_device *usb, unsigned int port,
203  unsigned int feature, unsigned int index ) {
204 
206  feature, ( ( index << 8 ) | port ) );
207 }
208 
209 /**
210  * Set hub depth
211  *
212  * @v usb USB device
213  * @v depth Hub depth
214  * @ret rc Return status code
215  */
216 static inline __attribute__ (( always_inline )) int
217 usb_hub_set_hub_depth ( struct usb_device *usb, unsigned int depth ) {
218 
219  return usb_control ( usb, USB_HUB_SET_HUB_DEPTH, depth, 0, NULL, 0 );
220 }
221 
222 /**
223  * Clear transaction translator buffer
224  *
225  * @v usb USB device
226  * @v device Device address
227  * @v endpoint Endpoint address
228  * @v attributes Endpoint attributes
229  * @v tt_port Transaction translator port (or 1 for single-TT hubs)
230  * @ret rc Return status code
231  */
232 static inline __attribute__ (( always_inline )) int
233 usb_hub_clear_tt_buffer ( struct usb_device *usb, unsigned int device,
234  unsigned int endpoint, unsigned int attributes,
235  unsigned int tt_port ) {
236  unsigned int value;
237 
238  /* Calculate value */
239  value = ( ( ( endpoint & USB_ENDPOINT_MAX ) << 0 ) | ( device << 4 ) |
240  ( ( attributes & USB_ENDPOINT_ATTR_TYPE_MASK ) << 11 ) |
241  ( ( endpoint & USB_ENDPOINT_IN ) << 8 ) );
242 
244  tt_port, NULL, 0 );
245 }
246 
247 /** Transaction translator port value for single-TT hubs */
248 #define USB_HUB_TT_SINGLE 1
249 
250 /** A USB hub device */
252  /** Name */
253  const char *name;
254  /** USB device */
255  struct usb_device *usb;
256  /** USB hub */
257  struct usb_hub *hub;
258  /** Features */
259  unsigned int features;
260  /** Flags */
261  unsigned int flags;
262 
263  /** Interrupt endpoint */
265  /** Interrupt endpoint refill process */
266  struct process refill;
267 };
268 
269 /** Hub requires additional settling delay */
270 #define USB_HUB_SLOW_START 0x0001
271 
272 /** Additional setting delay for out-of-spec hubs */
273 #define USB_HUB_SLOW_START_DELAY_MS 500
274 
275 /** Interrupt ring fill level
276  *
277  * This is a policy decision.
278  */
279 #define USB_HUB_INTR_FILL 4
280 
281 /** Maximum time to wait for port to become enabled
282  *
283  * This is a policy decision.
284  */
285 #define USB_HUB_ENABLE_MAX_WAIT_MS 100
286 
287 #endif /* _USBHUB_H */
A process.
Definition: process.h:17
#define __attribute__(x)
Definition: compiler.h:10
unsigned short uint16_t
Definition: stdint.h:11
struct usb_hub_descriptor_basic basic
Basic USB hub descriptor.
Definition: usbhub.h:39
#define USB_HUB_SET_HUB_DEPTH
Set hub depth.
Definition: usbhub.h:128
An enhanced USB hub descriptor.
Definition: usbhub.h:37
A USB hub.
Definition: usb.h:826
static int usb_hub_get_descriptor(struct usb_device *usb, int enhanced, union usb_hub_descriptor *data)
Get hub descriptor.
Definition: usbhub.h:146
struct usb_descriptor_header header
Descriptor header.
Definition: usbhub.h:54
unsigned int features
Features.
Definition: usbhub.h:259
#define USB_ENDPOINT_ATTR_TYPE_MASK
Endpoint attribute transfer type mask.
Definition: usb.h:266
#define USB_HUB_DESCRIPTOR
A basic USB hub descriptor.
Definition: usbhub.h:34
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
struct usb_endpoint intr
Interrupt endpoint.
Definition: usbhub.h:264
uint64_t desc
Microcode descriptor list physical address.
Definition: ucode.h:12
#define USB_ENDPOINT_MAX
Maximum endpoint number.
Definition: usb.h:507
static int usb_hub_clear_tt_buffer(struct usb_device *usb, unsigned int device, unsigned int endpoint, unsigned int attributes, unsigned int tt_port)
Clear transaction translator buffer.
Definition: usbhub.h:233
struct usb_hub_descriptor_enhanced enhanced
Enhanced hub descriptor.
Definition: usbhub.h:58
uint8_t ports
Number of ports.
Definition: usbhub.h:24
static int usb_hub_get_port_status(struct usb_device *usb, unsigned int port, struct usb_hub_port_status *status)
Get port status.
Definition: usbhub.h:168
uint8_t delay
Power-on delay (in 2ms intervals.
Definition: usbhub.h:28
struct usb_device * usb
USB device.
Definition: usbhub.h:255
struct process refill
Interrupt endpoint refill process.
Definition: usbhub.h:266
int usb_control(struct usb_device *usb, unsigned int request, unsigned int value, unsigned int index, void *data, size_t len)
Issue USB control transaction.
Definition: usb.c:783
uint8_t current
Controller current (in mA)
Definition: usbhub.h:30
static int usb_hub_set_hub_depth(struct usb_device *usb, unsigned int depth)
Set hub depth.
Definition: usbhub.h:217
uint8_t status
Status.
Definition: ena.h:16
uint16_t characteristics
Characteristics.
Definition: usbhub.h:26
A basic USB hub descriptor.
Definition: usbhub.h:20
A hardware device.
Definition: device.h:73
A USB endpoint.
Definition: usb.h:389
u8 port
Port number.
Definition: CIB_PRM.h:31
static int usb_clear_feature(struct usb_device *usb, unsigned int type, unsigned int feature, unsigned int index)
Clear feature.
Definition: usb.h:1106
#define USB_HUB_DESCRIPTOR_ENHANCED
An enhanced USB hub descriptor.
Definition: usbhub.h:49
#define USB_HUB_RECIP_PORT
Request recipient is a port.
Definition: usbhub.h:17
#define USB_TYPE_CLASS
Class-specific request type.
Definition: usb.h:89
A USB hub device.
Definition: usbhub.h:251
struct usb_hub * hub
USB hub.
Definition: usbhub.h:257
A USB hub descriptor.
Definition: usbhub.h:52
static int usb_hub_clear_port_feature(struct usb_device *usb, unsigned int port, unsigned int feature, unsigned int index)
Clear port feature.
Definition: usbhub.h:185
uint8_t latency
Header decode latency.
Definition: usbhub.h:41
A USB device.
Definition: usb.h:708
pseudo_bit_t value[0x00020]
Definition: arbel.h:13
Linked lists.
static int usb_set_feature(struct usb_device *usb, unsigned int type, unsigned int feature, unsigned int index)
Set feature.
Definition: usb.h:1123
unsigned int flags
Flags.
Definition: usbhub.h:261
#define USB_ENDPOINT_IN
Endpoint direction is in.
Definition: usb.h:510
uint16_t removable
Removable device bitmask.
Definition: usbhub.h:45
Processes.
unsigned char uint8_t
Definition: stdint.h:10
uint16_t delay
Maximum delay.
Definition: usbhub.h:43
Port status.
Definition: usbhub.h:62
A USB descriptor header.
Definition: usb.h:158
#define USB_HUB_CLEAR_TT_BUFFER
Clear transaction translator buffer.
Definition: usbhub.h:133
uint16_t changed
Changed status.
Definition: usbhub.h:66
A named feature.
Definition: features.h:78
uint32_t len
Length.
Definition: ena.h:14
Universal Serial Bus (USB)
static int usb_get_status(struct usb_device *usb, unsigned int type, unsigned int index, void *data, size_t len)
Get status.
Definition: usb.h:1089
uint8_t data[48]
Additional event data.
Definition: ena.h:22
static int usb_hub_set_port_feature(struct usb_device *usb, unsigned int port, unsigned int feature, unsigned int index)
Set port feature.
Definition: usbhub.h:202
static int usb_get_descriptor(struct usb_device *usb, unsigned int type, unsigned int desc, unsigned int index, unsigned int language, struct usb_descriptor_header *data, size_t len)
Get USB descriptor.
Definition: usb.h:1156
uint64_t index
Index of the first segment within the content.
Definition: pccrc.h:21
struct usb_hub_descriptor_basic basic
Basic hub descriptor.
Definition: usbhub.h:56
uint16_t current
Current status.
Definition: usbhub.h:64
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
const char * name
Name.
Definition: usbhub.h:253
struct usb_descriptor_header header
Descriptor header.
Definition: usbhub.h:22