iPXE
uhci.h
Go to the documentation of this file.
1 #ifndef _IPXE_UHCI_H
2 #define _IPXE_UHCI_H
3 
4 /** @file
5  *
6  * USB Universal Host Controller Interface (UHCI) driver
7  *
8  */
9 
10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
11 
12 #include <assert.h>
13 #include <ipxe/pci.h>
14 #include <ipxe/usb.h>
15 
16 /** Minimum alignment required for data structures
17  *
18  * With the exception of the frame list (which is page-aligned), data
19  * structures used by UHCI generally require 16-byte alignment.
20  */
21 #define UHCI_ALIGN 16
22 
23 /** Number of ports */
24 #define UHCI_PORTS 2
25 
26 /** Maximum transfer size */
27 #define UHCI_MTU 1280
28 
29 /** I/O BAR size */
30 #define UHCI_BAR_SIZE 0x14
31 
32 /** USB command register */
33 #define UHCI_USBCMD 0x00
34 
35 /** Max packet is 64 bytes */
36 #define UHCI_USBCMD_MAX64 0x0080
37 
38 /** Host controller reset */
39 #define UHCI_USBCMD_HCRESET 0x0002
40 
41 /** Run/stop */
42 #define UHCI_USBCMD_RUN 0x0001
43 
44 /** USB status register */
45 #define UHCI_USBSTS 0x02
46 
47 /** Host controller halted */
48 #define UHCI_USBSTS_HCHALTED 0x0020
49 
50 /** USB interrupt */
51 #define UHCI_USBSTS_USBINT 0x0001
52 
53 /** Frame list base address register */
54 #define UHCI_FLBASEADD 0x08
55 
56 /** Port status and control register */
57 #define UHCI_PORTSC(port) ( 0x0e + ( (port) << 1 ) )
58 
59 /** Port reset */
60 #define UHCI_PORTSC_PR 0x0200
61 
62 /** Low-speed device attached */
63 #define UHCI_PORTSC_LS 0x0100
64 
65 /** Port enabled/disabled change */
66 #define UHCI_PORTSC_PEC 0x0008
67 
68 /** Port enabled */
69 #define UHCI_PORTSC_PED 0x0004
70 
71 /** Connect status change */
72 #define UHCI_PORTSC_CSC 0x0002
73 
74 /** Current connect status */
75 #define UHCI_PORTSC_CCS 0x0001
76 
77 /** Port status change mask */
78 #define UHCI_PORTSC_CHANGE ( UHCI_PORTSC_CSC | UHCI_PORTSC_PEC )
79 
80 /** Depth-first processing */
81 #define UHCI_LINK_DEPTH_FIRST 0x00000004UL
82 
83 /** Queue head type */
84 #define UHCI_LINK_TYPE_QH 0x00000002UL
85 
86 /** List terminator */
87 #define UHCI_LINK_TERMINATE 0x00000001UL
88 
89 /** Number of frames in frame list */
90 #define UHCI_FRAMES 1024
91 
92 /** A frame list */
94  /** Link pointer */
96 } __attribute__ (( packed ));
97 
98 /** A transfer descriptor */
100  /** Link pointer */
102  /** Actual length */
104  /** Status */
106  /** Flags */
108  /** Control */
110  /** Buffer pointer */
112 } __attribute__ (( packed ));
113 
114 /** Length mask */
115 #define UHCI_LEN_MASK 0x7ff
116 
117 /** Actual length */
118 #define UHCI_ACTUAL_LEN( actual ) ( ( (actual) + 1 ) & UHCI_LEN_MASK )
119 
120 /** Active */
121 #define UHCI_STATUS_ACTIVE 0x80
122 
123 /** Stalled */
124 #define UHCI_STATUS_STALLED 0x40
125 
126 /** Data buffer error */
127 #define UHCI_STATUS_BUFFER 0x20
128 
129 /** Babble detected */
130 #define UHCI_STATUS_BABBLE 0x10
131 
132 /** NAK received */
133 #define UHCI_STATUS_NAK 0x08
134 
135 /** CRC/timeout error */
136 #define UHCI_STATUS_CRC_TIMEOUT 0x04
137 
138 /** Bitstuff error */
139 #define UHCI_STATUS_BITSTUFF 0x02
140 
141 /** Short packet detect */
142 #define UHCI_FL_SPD 0x20
143 
144 /** Error counter */
145 #define UHCI_FL_CERR( count ) ( (count) << 3 )
146 
147 /** Error counter maximum value */
148 #define UHCI_FL_CERR_MAX UHCI_FL_CERR ( 3 )
149 
150 /** Low speed device */
151 #define UHCI_FL_LS 0x04
152 
153 /** Interrupt on completion */
154 #define UHCI_FL_IOC 0x01
155 
156 /** Packet ID */
157 #define UHCI_CONTROL_PID( pid ) ( (pid) << 0 )
158 
159 /** Packet ID mask */
160 #define UHCI_CONTROL_PID_MASK UHCI_CONTROL_PID ( 0xff )
161 
162 /** Device address */
163 #define UHCI_CONTROL_DEVICE( address ) ( (address) << 8 )
164 
165 /** Endpoint address */
166 #define UHCI_CONTROL_ENDPOINT( address ) ( (address) << 15 )
167 
168 /** Data toggle */
169 #define UHCI_CONTROL_TOGGLE ( 1 << 19 )
170 
171 /** Data length */
172 #define UHCI_CONTROL_LEN( len ) ( ( ( (len) - 1 ) & UHCI_LEN_MASK ) << 21 )
173 
174 /** Check for data packet
175  *
176  * This check is based on the fact that only USB_PID_SETUP has bit 2
177  * set.
178  */
179 #define UHCI_DATA_PACKET( control ) ( ! ( control & 0x04 ) )
180 
181 /** Check for short packet */
182 #define UHCI_SHORT_PACKET( control, actual ) \
183  ( ( ( (control) >> 21 ) ^ (actual) ) & UHCI_LEN_MASK )
184 
185 /** USB legacy support register (in PCI configuration space) */
186 #define UHCI_USBLEGSUP 0xc0
187 
188 /** USB legacy support default value */
189 #define UHCI_USBLEGSUP_DEFAULT 0x2000
190 
191 /** A queue head */
193  /** Horizontal link pointer */
195  /** Current transfer descriptor */
197 } __attribute__ (( packed ));
198 
199 /** A single UHCI transfer
200  *
201  * UHCI hardware is extremely simple, and requires software to build
202  * the entire packet schedule (including manually handling all of the
203  * data toggles). The hardware requires at least 16 bytes of transfer
204  * descriptors per 64 bytes of transmitted/received data. We allocate
205  * the transfer descriptors at the time that the transfer is enqueued,
206  * to avoid the need to allocate unreasonably large blocks when the
207  * endpoint is opened.
208  */
210  /** Producer counter */
211  unsigned int prod;
212  /** Consumer counter */
213  unsigned int cons;
214  /** Completed data length */
215  size_t len;
216 
217  /** Transfer descriptors */
219 
220  /** I/O buffer */
221  struct io_buffer *iobuf;
222 };
223 
224 /** Number of transfer descriptors in a ring
225  *
226  * This is a policy decision.
227  */
228 #define UHCI_RING_COUNT 16
229 
230 /** A transfer ring */
231 struct uhci_ring {
232  /** Producer counter */
233  unsigned int prod;
234  /** Consumer counter */
235  unsigned int cons;
236 
237  /** Maximum packet length */
238  size_t mtu;
239  /** Base flags
240  *
241  * This incorporates the CERR and LS bits
242  */
244  /** Base control word
245  *
246  * This incorporates the device address, the endpoint address,
247  * and the data toggle for the next descriptor to be enqueued.
248  */
250 
251  /** Transfers */
253  /** End of transfer ring (if non-empty) */
255 
256  /** Queue head */
258 };
259 
260 /**
261  * Calculate space used in transfer ring
262  *
263  * @v ring Transfer ring
264  * @ret fill Number of entries used
265  */
266 static inline __attribute__ (( always_inline )) unsigned int
267 uhci_ring_fill ( struct uhci_ring *ring ) {
268  unsigned int fill;
269 
270  fill = ( ring->prod - ring->cons );
271  assert ( fill <= UHCI_RING_COUNT );
272  return fill;
273 }
274 
275 /**
276  * Calculate space remaining in transfer ring
277  *
278  * @v ring Transfer ring
279  * @ret remaining Number of entries remaining
280  */
281 static inline __attribute__ (( always_inline )) unsigned int
282 uhci_ring_remaining ( struct uhci_ring *ring ) {
283  unsigned int fill = uhci_ring_fill ( ring );
284 
285  return ( UHCI_RING_COUNT - fill );
286 }
287 
288 /** Maximum time to wait for host controller to stop
289  *
290  * This is a policy decision.
291  */
292 #define UHCI_STOP_MAX_WAIT_MS 100
293 
294 /** Maximum time to wait for reset to complete
295  *
296  * This is a policy decision.
297  */
298 #define UHCI_RESET_MAX_WAIT_MS 500
299 
300 /** Maximum time to wait for a port to be enabled
301  *
302  * This is a policy decision.
303  */
304 #define UHCI_PORT_ENABLE_MAX_WAIT_MS 500
305 
306 /** A UHCI device */
307 struct uhci_device {
308  /** Registers */
309  unsigned long regs;
310  /** Name */
311  const char *name;
312 
313  /** EHCI companion controller bus:dev.fn address (if any) */
314  unsigned int companion;
315 
316  /** Asynchronous queue head */
318  /** Frame list */
320 
321  /** List of all endpoints */
323  /** Asynchronous schedule */
324  struct list_head async;
325  /** Periodic schedule
326  *
327  * Listed in decreasing order of endpoint interval.
328  */
330 
331  /** USB bus */
332  struct usb_bus *bus;
333 };
334 
335 /** A UHCI endpoint */
337  /** UHCI device */
338  struct uhci_device *uhci;
339  /** USB endpoint */
340  struct usb_endpoint *ep;
341  /** List of all endpoints */
342  struct list_head list;
343  /** Endpoint schedule */
345 
346  /** Transfer ring */
347  struct uhci_ring ring;
348 };
349 
350 #endif /* _IPXE_UHCI_H */
unsigned int cons
Consumer counter.
Definition: uhci.h:235
#define __attribute__(x)
Definition: compiler.h:10
unsigned int prod
Producer counter.
Definition: uhci.h:211
unsigned short uint16_t
Definition: stdint.h:11
A queue head.
Definition: uhci.h:192
struct uhci_frame_list * frame
Frame list.
Definition: uhci.h:319
struct uhci_queue_head * head
Asynchronous queue head.
Definition: uhci.h:317
uint32_t link
Link pointer.
Definition: uhci.h:101
struct list_head async
Asynchronous schedule.
Definition: uhci.h:324
static unsigned int uhci_ring_fill(struct uhci_ring *ring)
Calculate space used in transfer ring.
Definition: uhci.h:267
#define UHCI_RING_COUNT
Number of transfer descriptors in a ring.
Definition: uhci.h:228
struct uhci_device * uhci
UHCI device.
Definition: uhci.h:338
A UHCI endpoint.
Definition: uhci.h:336
static unsigned int uhci_ring_remaining(struct uhci_ring *ring)
Calculate space remaining in transfer ring.
Definition: uhci.h:282
uint32_t control
Control.
Definition: uhci.h:109
uint8_t flags
Flags.
Definition: uhci.h:107
uint32_t current
Current transfer descriptor.
Definition: uhci.h:196
unsigned int prod
Producer counter.
Definition: uhci.h:233
const char * name
Name.
Definition: uhci.h:311
uint32_t link[UHCI_FRAMES]
Link pointer.
Definition: uhci.h:95
A single UHCI transfer.
Definition: uhci.h:209
A doubly-linked list entry (or list head)
Definition: list.h:18
struct list_head periodic
Periodic schedule.
Definition: uhci.h:329
uint8_t flags
Base flags.
Definition: uhci.h:243
A USB endpoint.
Definition: usb.h:389
Assertions.
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
struct uhci_queue_head * head
Queue head.
Definition: uhci.h:257
struct uhci_ring ring
Transfer ring.
Definition: uhci.h:347
unsigned int companion
EHCI companion controller bus:dev.fn address (if any)
Definition: uhci.h:314
uint16_t actual
Actual length.
Definition: uhci.h:103
unsigned long regs
Registers.
Definition: uhci.h:309
A transfer ring.
Definition: uhci.h:231
struct list_head endpoints
List of all endpoints.
Definition: uhci.h:322
PCI bus.
#define UHCI_FRAMES
Number of frames in frame list.
Definition: uhci.h:90
uint8_t status
Status.
Definition: uhci.h:105
struct io_buffer * iobuf
I/O buffer.
Definition: uhci.h:221
size_t len
Completed data length.
Definition: uhci.h:215
unsigned char uint8_t
Definition: stdint.h:10
struct uhci_transfer * xfer[UHCI_RING_COUNT]
Transfers.
Definition: uhci.h:252
struct list_head schedule
Endpoint schedule.
Definition: uhci.h:344
unsigned int uint32_t
Definition: stdint.h:12
struct usb_endpoint * ep
USB endpoint.
Definition: uhci.h:340
uint32_t control
Base control word.
Definition: uhci.h:249
struct uhci_transfer * end
End of transfer ring (if non-empty)
Definition: uhci.h:254
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
Universal Serial Bus (USB)
A UHCI device.
Definition: uhci.h:307
uint32_t data
Buffer pointer.
Definition: uhci.h:111
uint8_t fill
Length pair.
Definition: deflate.h:12
A transfer descriptor.
Definition: uhci.h:99
uint32_t link
Horizontal link pointer.
Definition: uhci.h:194
struct list_head list
List of all endpoints.
Definition: uhci.h:342
unsigned int cons
Consumer counter.
Definition: uhci.h:213
struct uhci_transfer_descriptor * desc
Transfer descriptors.
Definition: uhci.h:218
size_t mtu
Maximum packet length.
Definition: uhci.h:238
A USB bus.
Definition: usb.h:949
A frame list.
Definition: uhci.h:93
struct usb_bus * bus
USB bus.
Definition: uhci.h:332
A persistent I/O buffer.
Definition: iobuf.h:32