xref: /illumos-gate/usr/src/uts/common/sys/usb/hcd/xhci/xhci.h (revision 0ae0ab6f)
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 /*
13  * Copyright (c) 2018, Joyent, Inc.
14  * Copyright (c) 2019 by Western Digital Corporation
15  * Copyright 2022 Oxide Computer Company
16  */
17 
18 #ifndef _SYS_USB_XHCI_XHCI_H
19 #define	_SYS_USB_XHCI_XHCI_H
20 
21 /*
22  * Extensible Host Controller Interface (xHCI) USB Driver
23  */
24 
25 #include <sys/conf.h>
26 #include <sys/ddi.h>
27 #include <sys/sunddi.h>
28 #include <sys/taskq_impl.h>
29 #include <sys/sysmacros.h>
30 #include <sys/usb/hcd/xhci/xhcireg.h>
31 
32 #include <sys/usb/usba.h>
33 #include <sys/usb/usba/hcdi.h>
34 #include <sys/usb/hubd/hub.h>
35 #include <sys/usb/usba/hubdi.h>
36 #include <sys/usb/hubd/hubdvar.h>
37 
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 /*
44  * The base segment for DMA attributes was determined to be 4k based on xHCI 1.1
45  * / table 54: Data Structure Max Size, Boundary, and Alignment Requirement
46  * Summary.  This indicates that the required alignment for most things is
47  * PAGESIZE, which in our current implementation is required to be 4K. We
48  * provide the ring segment value below for the things which need 64K alignment
49  *
50  * Similarly, in the same table, the maximum required alignment is 64 bytes,
51  * hence we use that for everything.
52  *
53  * Next is the scatter/gather lengths. For most of the data structures, we only
54  * want to have a single SGL entry, e.g. just a simple flat mapping. For many of
55  * our transfers, we use the same logic to simplify the implementation of the
56  * driver. However, for bulk transfers, which are the largest by far, we want to
57  * be able to leverage SGLs to give us more DMA flexibility.
58  *
59  * We can transfer up to 64K in one transfer request block (TRB) which
60  * corresponds to a single SGL entry. Each ring we create is a single page in
61  * size and will support at most 256 TRBs. To try and give the operating system
62  * flexibility when allocating DMA transfers, we've opted to allow up to 63
63  * SGLs. Because there isn't a good way to support DMA windows with the xHCI
64  * controller design, if this number is too small then DMA allocations and
65  * binding might fail. If the DMA binding fails, the transfer will fail.
66  *
67  * The reason that we use 63 SGLs and not the expected 64 is that we always need
68  * to allocate an additional TRB for the event data. This leaves us with a
69  * nicely divisible number of entries.
70  *
71  * The final piece of this is the maximum sized transfer that the driver
72  * advertises to the broader framework. This is currently sized at 512 KiB. For
73  * reference the ehci driver sized this value at 640 KiB. It's important to
74  * understand that this isn't reflected in the DMA attribute limitation, because
75  * it's not an attribute of the hardware. Experimentally, this has proven to be
76  * sufficient for most of the drivers that we support today. When considering
77  * increasing this number, please note the impact that might have on the
78  * required number of DMA SGL entries required to satisfy the allocation.
79  *
80  * The value of 512 KiB was originally based on the number of SGLs we supported
81  * multiplied by the maximum transfer size. The original number of
82  * XHCI_TRANSFER_DMA_SGL was 8. The 512 KiB value was based upon taking the
83  * number of SGLs and assuming that each TRB used its maximum transfer size of
84  * 64 KiB.
85  */
86 #define	XHCI_TRB_MAX_TRANSFER	65536	/* 64 KiB */
87 #define	XHCI_DMA_ALIGN		64
88 #define	XHCI_DEF_DMA_SGL	1
89 #define	XHCI_TRANSFER_DMA_SGL	63
90 #define	XHCI_MAX_TRANSFER	524288	/* 512 KiB */
91 
92 /*
93  * Properties and values for rerouting ehci ports to xhci.
94  */
95 #define	XHCI_PROP_REROUTE_DISABLE	0
96 #define	XHCI_PROP_REROUTE_DEFAULT	1
97 
98 /*
99  * This number is a bit made up. Truthfully, the API here isn't the most useful
100  * for what we need to define as it should really be based on the endpoint that
101  * we're interested in rather than the device as a whole.
102  *
103  * We're basically being asked how many TRBs we're willing to schedule in one
104  * go. There's no great way to come up with this number, so we basically are
105  * making up something such that we use up a good portion of a ring, but not too
106  * much of it.
107  */
108 #define	XHCI_ISOC_MAX_TRB	64
109 
110 #ifdef	DEBUG
111 #define	XHCI_DMA_SYNC(dma, flag)	VERIFY0(ddi_dma_sync( \
112 					    (dma).xdb_dma_handle, 0, 0, \
113 					    (flag)))
114 #else
115 #define	XHCI_DMA_SYNC(dma, flag)	((void) ddi_dma_sync( \
116 					    (dma).xdb_dma_handle, 0, 0, \
117 					    (flag)))
118 #endif
119 
120 /*
121  * TRBs need to indicate the number of remaining USB packets in the overall
122  * transfer. This is a 5-bit value, which means that the maximum value we can
123  * store in that TRD field is 31.
124  */
125 #define	XHCI_MAX_TDSIZE		31
126 
127 /*
128  * This defines a time in 2-ms ticks that is required to wait for the controller
129  * to be ready to go. Section 5.4.8 of the XHCI specification in the description
130  * of the PORTSC register indicates that the upper bound is 20 ms. Therefore the
131  * number of ticks is 10.
132  */
133 #define	XHCI_POWER_GOOD	10
134 
135 /*
136  * Definitions to determine the default number of interrupts. Note that we only
137  * bother with a single interrupt at this time, though we've arranged the driver
138  * to make it possible to request more if, for some unlikely reason, it becomes
139  * necessary.
140  */
141 #define	XHCI_NINTR	1
142 
143 /*
144  * Default interrupt modulation value. This enables us to have 4000 interrupts /
145  * second. This is supposed to be the default value of the controller. See xHCI
146  * 1.1 / 4.17.2 for more information.
147  */
148 #define	XHCI_IMOD_DEFAULT	0x000003F8U
149 
150 /*
151  * Definitions that surround the default values used in various contexts. These
152  * come from various parts of the xHCI specification. In general, see xHCI 1.1 /
153  * 4.8.2. Note that the MPS_MASK is used for ISOCH and INTR endpoints which have
154  * different sizes.
155  *
156  * The burst member is a bit more complicated. By default for USB 2 devices, it
157  * only matters for ISOCH and INTR endpoints and so we use the macros below to
158  * pull it out of the endpoint description's max packet field. For USB 3, it
159  * matters for non-control endpoints. However, it comes out of a companion
160  * description.
161  *
162  * By default the mult member is zero for all cases except for super speed
163  * ISOCH endpoints, where it comes from the companion descriptor.
164  */
165 #define	XHCI_CONTEXT_DEF_CERR		3
166 #define	XHCI_CONTEXT_ISOCH_CERR		0
167 #define	XHCI_CONTEXT_MPS_MASK		0x07ff
168 #define	XHCI_CONTEXT_BURST_MASK		0x1800
169 #define	XHCI_CONTEXT_BURST_SHIFT	11
170 #define	XHCI_CONTEXT_DEF_MULT		0
171 #define	XHCI_CONTEXT_DEF_MAX_ESIT	0
172 #define	XHCI_CONTEXT_DEF_CTRL_ATL	8
173 
174 /*
175  * This number represents the number of transfers that we'll set up for a given
176  * interrupt transfer. Note that the idea here is that we'll want to allocate a
177  * certain number of transfers to basically ensure that we'll always be able to
178  * have a transfer available, even if the system is a bit caught up in trying to
179  * process it and for some reason we can't fire the interrupt. As such, we
180  * basically want to have enough available that at the fastest interval (125 us)
181  * that we have enough. So in this case we choose 8, with the assumption that we
182  * should be able to process at least one in a given millisecond. Note that this
183  * is not based in fact and is really just as much a guess and a hope.
184  *
185  * While we could then use less resources for other interrupt transfers that are
186  * slower, starting with uniform resource usage will make things a bit easier.
187  */
188 #define	XHCI_INTR_IN_NTRANSFERS	8
189 
190 /*
191  * This number represents the number of xhci_transfer_t structures that we'll
192  * set up for a given isochronous transfer polling request. A given isochronous
193  * transfer may actually have multiple units of time associated with it. As
194  * such, we basically want to treat this like a case of classic double
195  * buffering. We have one ready to go while the other is being filled up. This
196  * will compensate for additional latency in the system. This is smaller than
197  * the Interrupt IN transfer case above as many callers may ask for multiple
198  * intervals in a single request.
199  */
200 #define	XHCI_ISOC_IN_NTRANSFERS	2
201 
202 #define	XHCI_PERIODIC_IN_NTRANSFERS					\
203 	MAX(XHCI_ISOC_IN_NTRANSFERS, XHCI_INTR_IN_NTRANSFERS)
204 
205 /*
206  * Mask for a route string which is a 20-bit value.
207  */
208 #define	XHCI_ROUTE_MASK(x)	((x) & 0xfffff)
209 
210 /*
211  * This is the default tick that we use for timeouts while endpoints have
212  * outstanding, active, non-periodic transfers. We choose one second as the USBA
213  * specifies timeouts in units of seconds. Note that this is in microseconds, so
214  * it can be fed into drv_usectohz().
215  */
216 #define	XHCI_TICK_TIMEOUT_US	(MICROSEC)
217 
218 /*
219  * Set of bits that we need one of to indicate that this port has something
220  * interesting on it.
221  */
222 #define	XHCI_HUB_INTR_CHANGE_MASK	(XHCI_PS_CSC | XHCI_PS_PEC | \
223     XHCI_PS_WRC | XHCI_PS_OCC | XHCI_PS_PRC | XHCI_PS_PLC | XHCI_PS_CEC)
224 
225 /*
226  * These represent known issues with various xHCI controllers.
227  *
228  *	XHCI_QUIRK_NO_MSI	MSI support on this controller is known to be
229  *				broken.
230  *
231  *	XHCI_QUIRK_32_ONLY	Only use 32-bit DMA addreses with this
232  *				controller.
233  *
234  *	XHCI_QUIRK_INTC_EHCI	This is an Intel platform which supports
235  *				rerouting ports between EHCI and xHCI
236  *				controllers on the platform.
237  */
238 typedef enum xhci_quirk {
239 	XHCI_QUIRK_NO_MSI	= 0x01,
240 	XHCI_QUIRK_32_ONLY	= 0x02,
241 	XHCI_QUIRK_INTC_EHCI	= 0x04
242 } xhci_quirk_t;
243 
244 /*
245  * xHCI capability parameter flags. These are documented in xHCI 1.1 / 5.3.6.
246  */
247 typedef enum xhci_cap_flags {
248 	XCAP_AC64	= 0x001,
249 	XCAP_BNC	= 0x002,
250 	XCAP_CSZ	= 0x004,
251 	XCAP_PPC	= 0x008,
252 	XCAP_PIND	= 0x010,
253 	XCAP_LHRC	= 0x020,
254 	XCAP_LTC	= 0x040,
255 	XCAP_NSS	= 0x080,
256 	XCAP_PAE	= 0x100,
257 	XCAP_SPC	= 0x200,
258 	XCAP_SEC	= 0x400,
259 	XCAP_CFC	= 0x800
260 } xchi_cap_flags_t;
261 
262 /*
263  * Second set of capabilities, these are documented in xHCI 1.1 / 5.3.9.
264  */
265 typedef enum xhci_cap2_flags {
266 	XCAP2_U3C	= 0x01,
267 	XCAP2_CMC	= 0x02,
268 	XCAP2_FMC	= 0x04,
269 	XCAP2_CTC	= 0x08,
270 	XCAP2_LEC	= 0x10,
271 	XCAP2_CIC	= 0x20
272 } xhci_cap2_flags_t;
273 
274 /*
275  * These represent and store the various capability registers that we'll need to
276  * use. In addition, we stash a few other versioning related bits here. Note
277  * that we cache more information than we might need so that we have it for
278  * debugging purposes.
279  */
280 typedef struct xhci_capability {
281 	uint8_t			xcap_usb_vers;
282 	uint16_t		xcap_hci_vers;
283 	uint32_t		xcap_pagesize;
284 	uint8_t			xcap_max_slots;
285 	uint16_t		xcap_max_intrs;
286 	uint8_t			xcap_max_ports;
287 	boolean_t		xcap_ist_micro;
288 	uint8_t			xcap_ist;
289 	uint16_t		xcap_max_esrt;
290 	boolean_t		xcap_scratch_restore;
291 	uint16_t		xcap_max_scratch;
292 	uint8_t			xcap_u1_lat;
293 	uint16_t		xcap_u2_lat;
294 	xchi_cap_flags_t	xcap_flags;
295 	uint8_t			xcap_max_psa;
296 	uint16_t		xcap_xecp_off;
297 	xhci_cap2_flags_t	xcap_flags2;
298 	int			xcap_intr_types;
299 } xhci_capability_t;
300 
301 /*
302  * This represents a single logical DMA allocation. For the vast majority of
303  * non-transfer cases, it only represents a single DMA buffer and not a
304  * scatter-gather list.
305  */
306 typedef struct xhci_dma_buffer {
307 	caddr_t			xdb_va;		/* Buffer VA */
308 	size_t			xdb_len;	/* Buffer logical len */
309 	ddi_acc_handle_t	xdb_acc_handle;	/* Access handle */
310 	ddi_dma_handle_t	xdb_dma_handle;	/* DMA handle */
311 	int			xdb_ncookies;	/* Number of actual cookies */
312 	ddi_dma_cookie_t	xdb_cookies[XHCI_TRANSFER_DMA_SGL];
313 } xhci_dma_buffer_t;
314 
315 /*
316  * This is a single transfer descriptor. It's packed to match the hardware
317  * layout.
318  */
319 #pragma pack(1)
320 typedef struct xhci_trb {
321 	uint64_t	trb_addr;
322 	uint32_t	trb_status;
323 	uint32_t	trb_flags;
324 } xhci_trb_t;
325 #pragma pack()
326 
327 /*
328  * This represents a single transfer that we want to allocate and perform.
329  */
330 typedef struct xhci_transfer {
331 	list_node_t		xt_link;
332 	hrtime_t		xt_sched_time;
333 	xhci_dma_buffer_t	xt_buffer;
334 	uint_t			xt_ntrbs;
335 	uint_t			xt_short;
336 	uint_t			xt_timeout;
337 	usb_cr_t		xt_cr;
338 	boolean_t		xt_data_tohost;
339 	xhci_trb_t		*xt_trbs;
340 	uint64_t		*xt_trbs_pa;
341 	usb_isoc_pkt_descr_t	*xt_isoc;
342 	usb_opaque_t		xt_usba_req;
343 } xhci_transfer_t;
344 
345 /*
346  * This represents a ring in xHCI, upon which event, transfer, and command TRBs
347  * are scheduled.
348  */
349 typedef struct xhci_ring {
350 	xhci_dma_buffer_t	xr_dma;
351 	uint_t			xr_ntrb;
352 	xhci_trb_t		*xr_trb;
353 	uint_t			xr_head;
354 	uint_t			xr_tail;
355 	uint8_t			xr_cycle;
356 } xhci_ring_t;
357 
358 /*
359  * This structure is used to represent the xHCI Device Context Base Address
360  * Array. It's defined in section 6.1 of the specification and is required for
361  * the controller to start.
362  *
363  * The maximum number of slots supported is always 256, therefore we size this
364  * structure at its maximum.
365  */
366 #define	XHCI_MAX_SLOTS	256
367 #define	XHCI_DCBAA_SCRATCHPAD_INDEX	0
368 
369 typedef struct xhci_dcbaa {
370 	uint64_t		*xdc_base_addrs;
371 	xhci_dma_buffer_t	xdc_dma;
372 } xhci_dcbaa_t;
373 
374 typedef struct xhci_scratchpad {
375 	uint64_t		*xsp_addrs;
376 	xhci_dma_buffer_t	xsp_addr_dma;
377 	xhci_dma_buffer_t	*xsp_scratch_dma;
378 } xhci_scratchpad_t;
379 
380 /*
381  * Contexts. These structures are inserted into the DCBAA above and are used for
382  * describing the state of the system. Note, that while many of these are
383  * 32-bytes in size, the xHCI specification defines that they'll be extended to
384  * 64-bytes with all the extra bytes as zeros if the CSZ flag is set in the
385  * HCCPARAMS1 register, e.g. we have the flag XCAP_CSZ set.
386  *
387  * The device context covers the slot context and 31 endpoints.
388  */
389 #define	XHCI_DEVICE_CONTEXT_32	1024
390 #define	XHCI_DEVICE_CONTEXT_64	2048
391 #define	XHCI_NUM_ENDPOINTS	31
392 #define	XHCI_DEFAULT_ENDPOINT	0
393 
394 #pragma pack(1)
395 typedef struct xhci_slot_context {
396 	uint32_t	xsc_info;
397 	uint32_t	xsc_info2;
398 	uint32_t	xsc_tt;
399 	uint32_t	xsc_state;
400 	uint32_t	xsc_reserved[4];
401 } xhci_slot_context_t;
402 
403 typedef struct xhci_endpoint_context {
404 	uint32_t	xec_info;
405 	uint32_t	xec_info2;
406 	uint64_t	xec_dequeue;
407 	uint32_t	xec_txinfo;
408 	uint32_t	xec_reserved[3];
409 } xhci_endpoint_context_t;
410 
411 typedef struct xhci_input_context {
412 	uint32_t	xic_drop_flags;
413 	uint32_t	xic_add_flags;
414 	uint32_t	xic_reserved[6];
415 } xhci_input_context_t;
416 #pragma pack()
417 
418 /*
419  * Definitions and structures for maintaining the event ring.
420  */
421 #define	XHCI_EVENT_NSEGS	1
422 
423 #pragma pack(1)
424 typedef struct xhci_event_segment {
425 	uint64_t	xes_addr;
426 	uint16_t	xes_size;
427 	uint16_t	xes_rsvd0;
428 	uint32_t	xes_rsvd1;
429 } xhci_event_segment_t;
430 #pragma pack()
431 
432 typedef struct xhci_event_ring {
433 	xhci_event_segment_t	*xev_segs;
434 	xhci_dma_buffer_t	xev_dma;
435 	xhci_ring_t		xev_ring;
436 } xhci_event_ring_t;
437 
438 typedef enum xhci_command_ring_state {
439 	XHCI_COMMAND_RING_IDLE		= 0x00,
440 	XHCI_COMMAND_RING_RUNNING	= 0x01,
441 	XHCI_COMMAND_RING_ABORTING	= 0x02,
442 	XHCI_COMMAND_RING_ABORT_DONE	= 0x03
443 } xhci_command_ring_state_t;
444 
445 typedef struct xhci_command_ring {
446 	xhci_ring_t			xcr_ring;
447 	kmutex_t			xcr_lock;
448 	kcondvar_t			xcr_cv;
449 	list_t				xcr_commands;
450 	timeout_id_t			xcr_timeout;
451 	xhci_command_ring_state_t	xcr_state;
452 } xhci_command_ring_t;
453 
454 /*
455  * Individual command states.
456  *
457  * XHCI_COMMAND_S_INIT		The command has yet to be inserted into the
458  *				command ring.
459  *
460  * XHCI_COMMAND_S_QUEUED	The command is queued in the command ring.
461  *
462  * XHCI_COMMAND_S_RECEIVED	A command completion for this was received.
463  *
464  * XHCI_COMMAND_S_DONE		The command has been executed. Note that it may
465  *				have been aborted.
466  *
467  * XHCI_COMMAND_S_RESET		The ring is being reset due to a fatal error and
468  *				this command has been removed from the ring.
469  *				This means it has been aborted, but it was not
470  *				the cause of the abort.
471  *
472  * Note, when adding states, anything after XHCI_COMMAND_S_DONE implies that
473  * upon reaching this state, it is no longer in the ring.
474  */
475 typedef enum xhci_command_state {
476 	XHCI_COMMAND_S_INIT	= 0x00,
477 	XHCI_COMMAND_S_QUEUED	= 0x01,
478 	XHCI_COMMAND_S_RECEIVED = 0x02,
479 	XHCI_COMMAND_S_DONE	= 0x03,
480 	XHCI_COMMAND_S_RESET	= 0x04
481 } xhci_command_state_t;
482 
483 /*
484  * The TRB contents here are always kept in host byte order and are transformed
485  * to little endian when actually scheduled on the ring.
486  */
487 typedef struct xhci_command {
488 	list_node_t		xco_link;
489 	kcondvar_t		xco_cv;
490 	xhci_trb_t		xco_req;
491 	xhci_trb_t		xco_res;
492 	xhci_command_state_t	xco_state;
493 } xhci_command_t;
494 
495 typedef enum xhci_endpoint_state {
496 	XHCI_ENDPOINT_PERIODIC		= 0x01,
497 	XHCI_ENDPOINT_HALTED		= 0x02,
498 	XHCI_ENDPOINT_QUIESCE		= 0x04,
499 	XHCI_ENDPOINT_TIMED_OUT		= 0x08,
500 	/*
501 	 * This enpdoint is being torn down and should make sure it de-schedules
502 	 * itself.
503 	 */
504 	XHCI_ENDPOINT_TEARDOWN		= 0x10,
505 	/*
506 	 * This endpoint is currently used in polled I/O mode by the
507 	 * kernel debugger.
508 	 */
509 	XHCI_ENDPOINT_POLLED		= 0x20,
510 	/*
511 	 * This endpoint is open and in use by a pipe.
512 	 */
513 	XHCI_ENDPOINT_OPEN		= 0x40,
514 } xhci_endpoint_state_t;
515 
516 /*
517  * This is a composite of states that we need to watch for. We don't
518  * want to allow ourselves to set one of these flags while one of them
519  * is currently active.
520  */
521 #define	XHCI_ENDPOINT_SERIALIZE		(XHCI_ENDPOINT_QUIESCE |	\
522 					XHCI_ENDPOINT_TIMED_OUT)
523 
524 /*
525  * This is a composite of states that we need to make sure that if set, we do
526  * not schedule activity on the ring.
527  */
528 #define	XHCI_ENDPOINT_DONT_SCHEDULE	(XHCI_ENDPOINT_HALTED |		\
529 					XHCI_ENDPOINT_QUIESCE |		\
530 					XHCI_ENDPOINT_TIMED_OUT)
531 
532 /*
533  * Forwards required for the endpoint
534  */
535 struct xhci_device;
536 struct xhci;
537 
538 typedef struct xhci_endpoint_params {
539 	boolean_t		xepp_configured;
540 	uint_t			xepp_eptype;
541 	uint_t			xepp_burst;
542 	uint_t			xepp_ival;
543 	uint_t			xepp_max_esit;
544 	uint_t			xepp_avgtrb;
545 	uint_t			xepp_mps;
546 	uint_t			xepp_mult;
547 	uint_t			xepp_cerr;
548 } xhci_endpoint_params_t;
549 
550 typedef struct xhci_endpoint {
551 	struct xhci		*xep_xhci;
552 	struct xhci_device	*xep_xd;
553 	uint_t			xep_num;
554 	uint_t			xep_type;
555 	xhci_endpoint_state_t	xep_state;
556 	kcondvar_t		xep_state_cv;
557 	timeout_id_t		xep_timeout;
558 	list_t			xep_transfers;
559 	usba_pipe_handle_data_t	*xep_pipe;
560 	xhci_ring_t		xep_ring;
561 	xhci_endpoint_params_t	xep_params;
562 } xhci_endpoint_t;
563 
564 typedef struct xhci_device {
565 	list_node_t		xd_link;
566 	usb_port_t		xd_port;
567 	uint8_t			xd_slot;
568 	boolean_t		xd_addressed;
569 	usba_device_t		*xd_usbdev;
570 	xhci_dma_buffer_t	xd_ictx;
571 	kmutex_t		xd_imtx;	/* Protects input contexts */
572 	xhci_input_context_t	*xd_input;
573 	xhci_slot_context_t	*xd_slotin;
574 	xhci_endpoint_context_t	*xd_endin[XHCI_NUM_ENDPOINTS];
575 	xhci_dma_buffer_t	xd_octx;
576 	xhci_slot_context_t	*xd_slotout;
577 	xhci_endpoint_context_t	*xd_endout[XHCI_NUM_ENDPOINTS];
578 	xhci_endpoint_t		*xd_endpoints[XHCI_NUM_ENDPOINTS];
579 } xhci_device_t;
580 
581 typedef enum xhci_periodic_state {
582 	XHCI_PERIODIC_POLL_IDLE	= 0x0,
583 	XHCI_PERIODIC_POLL_ACTIVE,
584 	XHCI_PERIODIC_POLL_NOMEM,
585 	XHCI_PERIODIC_POLL_STOPPING
586 } xhci_periodic_state_t;
587 
588 typedef struct xhci_periodic_pipe {
589 	xhci_periodic_state_t	xpp_poll_state;
590 	usb_opaque_t		xpp_usb_req;
591 	size_t			xpp_tsize;
592 	uint_t			xpp_ntransfers;
593 	xhci_transfer_t		*xpp_transfers[XHCI_PERIODIC_IN_NTRANSFERS];
594 } xhci_periodic_pipe_t;
595 
596 typedef struct xhci_pipe {
597 	list_node_t		xp_link;
598 	hrtime_t		xp_opentime;
599 	usba_pipe_handle_data_t	*xp_pipe;
600 	xhci_endpoint_t		*xp_ep;
601 	xhci_periodic_pipe_t	xp_periodic;
602 } xhci_pipe_t;
603 
604 typedef struct xhci_usba {
605 	usba_hcdi_ops_t		*xa_ops;
606 	ddi_dma_attr_t		xa_dma_attr;
607 	usb_dev_descr_t		xa_dev_descr;
608 	usb_ss_hub_descr_t	xa_hub_descr;
609 	usba_pipe_handle_data_t	*xa_intr_cb_ph;
610 	usb_intr_req_t		*xa_intr_cb_req;
611 	list_t			xa_devices;
612 	list_t			xa_pipes;
613 } xhci_usba_t;
614 
615 typedef enum xhci_attach_seq {
616 	XHCI_ATTACH_FM		= 0x1 << 0,
617 	XHCI_ATTACH_PCI_CONFIG	= 0x1 << 1,
618 	XHCI_ATTACH_REGS_MAP	= 0x1 << 2,
619 	XHCI_ATTACH_INTR_ALLOC	= 0x1 << 3,
620 	XHCI_ATTACH_INTR_ADD	= 0x1 << 4,
621 	XHCI_ATTACH_SYNCH	= 0x1 << 5,
622 	XHCI_ATTACH_INTR_ENABLE	= 0x1 << 6,
623 	XHCI_ATTACH_STARTED	= 0x1 << 7,
624 	XHCI_ATTACH_USBA	= 0x1 << 8,
625 	XHCI_ATTACH_ROOT_HUB	= 0x1 << 9
626 } xhci_attach_seq_t;
627 
628 typedef enum xhci_state_flags {
629 	XHCI_S_ERROR		= 0x1 << 0
630 } xhci_state_flags_t;
631 
632 typedef struct xhci {
633 	dev_info_t		*xhci_dip;
634 	xhci_attach_seq_t	xhci_seq;
635 	int			xhci_fm_caps;
636 	ddi_acc_handle_t	xhci_cfg_handle;
637 	uint16_t		xhci_vendor_id;
638 	uint16_t		xhci_device_id;
639 	caddr_t			xhci_regs_base;
640 	ddi_acc_handle_t	xhci_regs_handle;
641 	uint_t			xhci_regs_capoff;
642 	uint_t			xhci_regs_operoff;
643 	uint_t			xhci_regs_runoff;
644 	uint_t			xhci_regs_dooroff;
645 	xhci_capability_t	xhci_caps;
646 	xhci_quirk_t		xhci_quirks;
647 	ddi_intr_handle_t	xhci_intr_hdl;
648 	int			xhci_intr_num;
649 	int			xhci_intr_type;
650 	uint_t			xhci_intr_pri;
651 	int			xhci_intr_caps;
652 	xhci_dcbaa_t		xhci_dcbaa;
653 	xhci_scratchpad_t	xhci_scratchpad;
654 	xhci_command_ring_t	xhci_command;
655 	xhci_event_ring_t	xhci_event;
656 	taskq_ent_t		xhci_tqe;
657 	kmutex_t		xhci_lock;
658 	kcondvar_t		xhci_statecv;
659 	xhci_state_flags_t	xhci_state;
660 	xhci_usba_t		xhci_usba;
661 } xhci_t;
662 
663 /*
664  * The xHCI memory mapped registers come in four different categories. The
665  * offset to them is variable. These represent the given register set that we're
666  * after.
667  */
668 typedef enum xhci_reg_type {
669 	XHCI_R_CAP,
670 	XHCI_R_OPER,
671 	XHCI_R_RUN,
672 	XHCI_R_DOOR
673 } xhci_reg_type_t;
674 
675 /*
676  * Polled I/O data structure
677  */
678 typedef struct xhci_polled {
679 	/*
680 	 * Pointer to the xhcip structure for the device that is to  be
681 	 * used as input in polled mode.
682 	 */
683 	xhci_t			*xhci_polled_xhci;
684 
685 	/*
686 	 * Pipe handle for the pipe that is to be used as input device
687 	 * in POLLED mode.
688 	 */
689 	usba_pipe_handle_data_t	*xhci_polled_input_pipe_handle;
690 
691 	/* Endpoint for the above */
692 	xhci_endpoint_t		*xhci_polled_endpoint;
693 
694 	/*
695 	 * The buffer that the USB HDI scan codes are copied into.
696 	 * A USB keyboard will report up to 8 bytes consisting of the
697 	 * modifier status, a reserved byte and up to 6 key presses.
698 	 * This buffer is sized to be large enough for one such report.
699 	 */
700 	uchar_t			xhci_polled_buf[8];
701 
702 	/*
703 	 * Track how many times xhci_polled_input_enter() and
704 	 * xhci_polled_input_exit() have been called so that the host
705 	 * controller isn't switched back to OS mode prematurely.
706 	 */
707 	uint_t			xhci_polled_entry;
708 
709 	/*
710 	 * Remember persistent errors that will prevent us from reading
711 	 * further input to avoid repeatedly polling to no avail
712 	 */
713 	int			xhci_polled_persistent_error;
714 } xhci_polled_t;
715 
716 /*
717  * Helper functions
718  */
719 extern xhci_t *xhci_hcdi_get_xhcip_from_dev(usba_device_t *);
720 extern xhci_device_t *xhci_device_lookup_by_slot(xhci_t *, int);
721 
722 /*
723  * Quirks related functions
724  */
725 extern void xhci_quirks_populate(xhci_t *);
726 extern void xhci_reroute_intel(xhci_t *);
727 
728 /*
729  * Interrupt related functions
730  */
731 extern uint_t xhci_intr(caddr_t, caddr_t);
732 extern boolean_t xhci_ddi_intr_disable(xhci_t *);
733 extern boolean_t xhci_ddi_intr_enable(xhci_t *);
734 extern int xhci_intr_conf(xhci_t *);
735 
736 /*
737  * DMA related functions
738  */
739 extern int xhci_check_dma_handle(xhci_t *, xhci_dma_buffer_t *);
740 extern void xhci_dma_acc_attr(xhci_t *, ddi_device_acc_attr_t *);
741 extern void xhci_dma_dma_attr(xhci_t *, ddi_dma_attr_t *);
742 extern void xhci_dma_scratchpad_attr(xhci_t *, ddi_dma_attr_t *);
743 extern void xhci_dma_transfer_attr(xhci_t *, ddi_dma_attr_t *, uint_t);
744 extern void xhci_dma_free(xhci_dma_buffer_t *);
745 extern boolean_t xhci_dma_alloc(xhci_t *, xhci_dma_buffer_t *, ddi_dma_attr_t *,
746     ddi_device_acc_attr_t *, boolean_t, size_t, boolean_t);
747 extern uint64_t xhci_dma_pa(xhci_dma_buffer_t *);
748 
749 /*
750  * DMA Transfer Ring functions
751  */
752 extern xhci_transfer_t *xhci_transfer_alloc(xhci_t *, xhci_endpoint_t *, size_t,
753     uint_t, int);
754 extern void xhci_transfer_free(xhci_t *, xhci_transfer_t *);
755 extern void xhci_transfer_copy(xhci_transfer_t *, void *, size_t, boolean_t);
756 extern int xhci_transfer_sync(xhci_t *, xhci_transfer_t *, uint_t);
757 extern void xhci_transfer_trb_fill_data(xhci_endpoint_t *, xhci_transfer_t *,
758     int, boolean_t);
759 extern void xhci_transfer_calculate_isoc(xhci_device_t *, xhci_endpoint_t *,
760     uint_t, uint_t *, uint_t *);
761 
762 /*
763  * Context (DCBAA, Scratchpad, Slot) functions
764  */
765 extern int xhci_context_init(xhci_t *);
766 extern void xhci_context_fini(xhci_t *);
767 extern boolean_t xhci_context_slot_output_init(xhci_t *, xhci_device_t *);
768 extern void xhci_context_slot_output_fini(xhci_t *, xhci_device_t *);
769 
770 /*
771  * Command Ring Functions
772  */
773 extern int xhci_command_ring_init(xhci_t *);
774 extern void xhci_command_ring_fini(xhci_t *);
775 extern boolean_t xhci_command_event_callback(xhci_t *, xhci_trb_t *trb);
776 
777 extern void xhci_command_init(xhci_command_t *);
778 extern void xhci_command_fini(xhci_command_t *);
779 
780 extern int xhci_command_enable_slot(xhci_t *, uint8_t *);
781 extern int xhci_command_disable_slot(xhci_t *, uint8_t);
782 extern int xhci_command_set_address(xhci_t *, xhci_device_t *, boolean_t);
783 extern int xhci_command_configure_endpoint(xhci_t *, xhci_device_t *);
784 extern int xhci_command_evaluate_context(xhci_t *, xhci_device_t *);
785 extern int xhci_command_reset_endpoint(xhci_t *, xhci_device_t *,
786     xhci_endpoint_t *);
787 extern int xhci_command_set_tr_dequeue(xhci_t *, xhci_device_t *,
788     xhci_endpoint_t *);
789 extern int xhci_command_stop_endpoint(xhci_t *, xhci_device_t *,
790     xhci_endpoint_t *);
791 
792 /*
793  * Event Ring Functions
794  */
795 extern int xhci_event_init(xhci_t *);
796 extern void xhci_event_fini(xhci_t *);
797 extern boolean_t xhci_event_process_trb(xhci_t *, xhci_trb_t *);
798 extern boolean_t xhci_event_process(xhci_t *);
799 
800 /*
801  * General Ring functions
802  */
803 extern void xhci_ring_free(xhci_ring_t *);
804 extern int xhci_ring_reset(xhci_t *, xhci_ring_t *);
805 extern int xhci_ring_alloc(xhci_t *, xhci_ring_t *);
806 
807 /*
808  * Event Ring (Consumer) oriented functions.
809  */
810 extern xhci_trb_t *xhci_ring_event_advance(xhci_ring_t *);
811 
812 
813 /*
814  * Command and Transfer Ring (Producer) oriented functions.
815  */
816 extern boolean_t xhci_ring_trb_tail_valid(xhci_ring_t *, uint64_t);
817 extern int xhci_ring_trb_valid_range(xhci_ring_t *, uint64_t, uint_t);
818 
819 extern boolean_t xhci_ring_trb_space(xhci_ring_t *, uint_t);
820 extern void xhci_ring_trb_fill(xhci_ring_t *, uint_t, xhci_trb_t *, uint64_t *,
821     boolean_t);
822 extern void xhci_ring_trb_produce(xhci_ring_t *, uint_t);
823 extern boolean_t xhci_ring_trb_consumed(xhci_ring_t *, uint64_t);
824 extern void xhci_ring_trb_put(xhci_ring_t *, xhci_trb_t *);
825 extern void xhci_ring_skip(xhci_ring_t *);
826 extern void xhci_ring_skip_transfer(xhci_ring_t *, xhci_transfer_t *);
827 
828 /*
829  * MMIO related functions. Note callers are responsible for checking with FM
830  * after accessing registers.
831  */
832 extern int xhci_check_regs_acc(xhci_t *);
833 
834 extern uint8_t xhci_get8(xhci_t *, xhci_reg_type_t, uintptr_t);
835 extern uint16_t xhci_get16(xhci_t *, xhci_reg_type_t, uintptr_t);
836 extern uint32_t xhci_get32(xhci_t *, xhci_reg_type_t, uintptr_t);
837 extern uint64_t xhci_get64(xhci_t *, xhci_reg_type_t, uintptr_t);
838 
839 extern void xhci_put8(xhci_t *, xhci_reg_type_t, uintptr_t, uint8_t);
840 extern void xhci_put16(xhci_t *, xhci_reg_type_t, uintptr_t, uint16_t);
841 extern void xhci_put32(xhci_t *, xhci_reg_type_t, uintptr_t, uint32_t);
842 extern void xhci_put64(xhci_t *, xhci_reg_type_t, uintptr_t, uint64_t);
843 
844 /*
845  * Runtime FM related functions
846  */
847 extern void xhci_fm_runtime_reset(xhci_t *);
848 
849 /*
850  * Endpoint related functions
851  */
852 extern int xhci_endpoint_init(xhci_t *, xhci_device_t *,
853     usba_pipe_handle_data_t *);
854 extern int xhci_endpoint_reinit(xhci_t *, xhci_device_t *,
855     xhci_endpoint_t *, usba_pipe_handle_data_t *);
856 extern void xhci_endpoint_release(xhci_t *, xhci_endpoint_t *);
857 extern void xhci_endpoint_fini(xhci_device_t *, int);
858 extern int xhci_endpoint_update_default(xhci_t *, xhci_device_t *,
859     xhci_endpoint_t *);
860 extern void xhci_endpoint_timeout_cancel(xhci_t *, xhci_endpoint_t *);
861 
862 extern int xhci_endpoint_setup_default_context(xhci_t *, xhci_device_t *,
863     xhci_endpoint_t *);
864 
865 extern uint_t xhci_endpoint_pipe_to_epid(usba_pipe_handle_data_t *);
866 extern boolean_t xhci_endpoint_is_periodic_in(xhci_endpoint_t *);
867 
868 extern void xhci_endpoint_serialize(xhci_t *, xhci_endpoint_t *);
869 extern int xhci_endpoint_quiesce(xhci_t *, xhci_device_t *, xhci_endpoint_t *);
870 extern int xhci_endpoint_schedule(xhci_t *, xhci_device_t *, xhci_endpoint_t *,
871     xhci_transfer_t *, boolean_t);
872 extern int xhci_endpoint_ring(xhci_t *, xhci_device_t *, xhci_endpoint_t *);
873 extern boolean_t xhci_endpoint_transfer_callback(xhci_t *, xhci_trb_t *);
874 
875 extern xhci_transfer_t *xhci_endpoint_determine_transfer(xhci_t *,
876     xhci_endpoint_t *, xhci_trb_t *, uint_t *);
877 
878 /*
879  * USB Framework related functions
880  */
881 extern int xhci_hcd_init(xhci_t *);
882 extern void xhci_hcd_fini(xhci_t *);
883 
884 /*
885  * Root hub related functions
886  */
887 extern int xhci_root_hub_init(xhci_t *);
888 extern int xhci_root_hub_fini(xhci_t *);
889 extern int xhci_root_hub_ctrl_req(xhci_t *, usba_pipe_handle_data_t *,
890     usb_ctrl_req_t *);
891 extern void xhci_root_hub_psc_callback(xhci_t *);
892 extern int xhci_root_hub_intr_root_enable(xhci_t *, usba_pipe_handle_data_t *,
893     usb_intr_req_t *);
894 extern void xhci_root_hub_intr_root_disable(xhci_t *);
895 
896 /*
897  * Polled I/O functions
898  */
899 extern int xhci_hcdi_console_input_init(usba_pipe_handle_data_t *, uchar_t **,
900     usb_console_info_impl_t *);
901 extern int xhci_hcdi_console_input_fini(usb_console_info_impl_t *);
902 extern int xhci_hcdi_console_input_enter(usb_console_info_impl_t *);
903 extern int xhci_hcdi_console_read(usb_console_info_impl_t *, uint_t *);
904 extern int xhci_hcdi_console_input_exit(usb_console_info_impl_t *);
905 extern int xhci_hcdi_console_output_init(usba_pipe_handle_data_t *,
906     usb_console_info_impl_t *);
907 extern int xhci_hcdi_console_output_fini(usb_console_info_impl_t *);
908 extern int xhci_hcdi_console_output_enter(usb_console_info_impl_t *);
909 extern int xhci_hcdi_console_write(usb_console_info_impl_t *, uchar_t *,
910     uint_t, uint_t *);
911 extern int xhci_hcdi_console_output_exit(usb_console_info_impl_t *);
912 
913 /*
914  * Logging functions
915  */
916 extern void xhci_log(xhci_t *xhcip, const char *fmt, ...) __KPRINTFLIKE(2);
917 extern void xhci_error(xhci_t *xhcip, const char *fmt, ...) __KPRINTFLIKE(2);
918 
919 /*
920  * Misc. data
921  */
922 extern void *xhci_soft_state;
923 
924 #ifdef __cplusplus
925 }
926 #endif
927 
928 #endif /* _SYS_USB_XHCI_XHCI_H */
929