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 2016 Joyent, Inc.
14 */
15
16 #ifndef _SYS_USB_XHCI_XHCI_H
17 #define _SYS_USB_XHCI_XHCI_H
18
19 /*
20 * Extensible Host Controller Interface (xHCI) USB Driver
21 */
22
23 #include <sys/conf.h>
24 #include <sys/ddi.h>
25 #include <sys/sunddi.h>
26 #include <sys/taskq_impl.h>
27 #include <sys/sysmacros.h>
28 #include <sys/usb/hcd/xhci/xhcireg.h>
29
30 #include <sys/usb/usba.h>
31 #include <sys/usb/usba/hcdi.h>
32 #include <sys/usb/hubd/hub.h>
33 #include <sys/usb/usba/hubdi.h>
39 #endif
40
41 /*
42 * The base segment for DMA attributes was determined to be 4k based on xHCI 1.1
43 * / table 54: Data Structure Max Size, Boundary, and Alignment Requirement
44 * Summary. This indicates that the required alignment for most things is
45 * PAGESIZE, which in our current implementation is required to be 4K. We
46 * provide the ring segment value below for the things which need 64K alignment
47 *
48 * Similarly, in the same table, the maximum required alignment is 64 bytes,
49 * hence we use that for everything.
50 *
51 * Next is the scatter/gather lengths. For most of the data structures, we only
52 * want to have a single SGL entry, e.g. just a simple flat mapping. For many of
53 * our transfers, we use the same logic to simplify the implementation of the
54 * driver. However, for bulk transfers, which are the largest by far, we want to
55 * be able to leverage SGLs to give us more DMA flexibility.
56 *
57 * We can transfer up to 64K in one transfer request block (TRB) which
58 * corresponds to a single SGL entry. Each ring we create is a single page in
59 * size and will support at most 256 TRBs. We've selected to use up to 8 SGLs
60 * for these transfer cases. This allows us to put up to 512 KiB in a given
61 * transfer request and in the worst case, we can have about 30 of them
62 * outstanding. Experimentally, this has proven to be sufficient for most of the
63 * drivers that we support today.
64 */
65 #define XHCI_TRB_MAX_TRANSFER 65536
66 #define XHCI_DMA_ALIGN 64
67 #define XHCI_DEF_DMA_SGL 1
68 #define XHCI_TRANSFER_DMA_SGL 8
69 #define XHCI_MAX_TRANSFER (XHCI_TRB_MAX_TRANSFER * XHCI_TRANSFER_DMA_SGL)
70 #define XHCI_DMA_STRUCT_SIZE 4096
71
72 /*
73 * Properties and values for rerouting ehci ports to xhci.
74 */
75 #define XHCI_PROP_REROUTE_DISABLE 0
76 #define XHCI_PROP_REROUTE_DEFAULT 1
77
78 /*
79 * This number is a bit made up. Truthfully, the API here isn't the most useful
80 * for what we need to define as it should really be based on the endpoint that
81 * we're interested in rather than the device as a whole.
82 *
83 * We're basically being asked how many TRBs we're willing to schedule in one
84 * go. There's no great way to come up with this number, so we basically are
85 * making up something such that we use up a good portion of a ring, but not too
86 * much of it.
87 */
88 #define XHCI_ISOC_MAX_TRB 64
89
90 #ifdef DEBUG
91 #define XHCI_DMA_SYNC(dma, flag) VERIFY0(ddi_dma_sync( \
92 (dma).xdb_dma_handle, 0, 0, \
93 (flag)))
94 #else
95 #define XHCI_DMA_SYNC(dma, flag) ((void) ddi_dma_sync( \
96 (dma).xdb_dma_handle, 0, 0, \
97 (flag)))
98 #endif
99
100 /*
101 * This defines a time in 2-ms ticks that is required to wait for the controller
102 * to be ready to go. Section 5.4.8 of the XHCI specification in the description
103 * of the PORTSC register indicates that the upper bound is 20 ms. Therefore the
104 * number of ticks is 10.
105 */
106 #define XHCI_POWER_GOOD 10
107
108 /*
109 * Definitions to determine the default number of interrupts. Note that we only
110 * bother with a single interrupt at this time, though we've arranged the driver
111 * to make it possible to request more if, for some unlikely reason, it becomes
112 * necessary.
113 */
114 #define XHCI_NINTR 1
115
116 /*
117 * Default interrupt modulation value. This enables us to have 4000 interrupts /
118 * second. This is supposed to be the default value of the controller. See xHCI
119 * 1.1 / 4.17.2 for more information.
120 */
293 typedef struct xhci_trb {
294 uint64_t trb_addr;
295 uint32_t trb_status;
296 uint32_t trb_flags;
297 } xhci_trb_t;
298 #pragma pack()
299
300 /*
301 * This represents a single transfer that we want to allocate and perform.
302 */
303 typedef struct xhci_transfer {
304 list_node_t xt_link;
305 hrtime_t xt_sched_time;
306 xhci_dma_buffer_t xt_buffer;
307 uint_t xt_ntrbs;
308 uint_t xt_short;
309 uint_t xt_timeout;
310 usb_cr_t xt_cr;
311 boolean_t xt_data_tohost;
312 xhci_trb_t *xt_trbs;
313 usb_isoc_pkt_descr_t *xt_isoc;
314 usb_opaque_t xt_usba_req;
315 } xhci_transfer_t;
316
317 /*
318 * This represents a ring in xHCI, upon which event, transfer, and command TRBs
319 * are scheduled.
320 */
321 typedef struct xhci_ring {
322 xhci_dma_buffer_t xr_dma;
323 uint_t xr_ntrb;
324 xhci_trb_t *xr_trb;
325 uint_t xr_head;
326 uint_t xr_tail;
327 uint8_t xr_cycle;
328 } xhci_ring_t;
329
330 /*
331 * This structure is used to represent the xHCI Device Context Base Address
332 * Array. It's defined in section 6.1 of the specification and is required for
631 extern boolean_t xhci_ddi_intr_enable(xhci_t *);
632 extern int xhci_intr_conf(xhci_t *);
633
634 /*
635 * DMA related functions
636 */
637 extern int xhci_check_dma_handle(xhci_t *, xhci_dma_buffer_t *);
638 extern void xhci_dma_acc_attr(xhci_t *, ddi_device_acc_attr_t *);
639 extern void xhci_dma_dma_attr(xhci_t *, ddi_dma_attr_t *);
640 extern void xhci_dma_scratchpad_attr(xhci_t *, ddi_dma_attr_t *);
641 extern void xhci_dma_transfer_attr(xhci_t *, ddi_dma_attr_t *, uint_t);
642 extern void xhci_dma_free(xhci_dma_buffer_t *);
643 extern boolean_t xhci_dma_alloc(xhci_t *, xhci_dma_buffer_t *, ddi_dma_attr_t *,
644 ddi_device_acc_attr_t *, boolean_t, size_t, boolean_t);
645 extern uint64_t xhci_dma_pa(xhci_dma_buffer_t *);
646
647 /*
648 * DMA Transfer Ring functions
649 */
650 extern xhci_transfer_t *xhci_transfer_alloc(xhci_t *, xhci_endpoint_t *, size_t,
651 int, int);
652 extern void xhci_transfer_free(xhci_t *, xhci_transfer_t *);
653 extern void xhci_transfer_copy(xhci_transfer_t *, void *, size_t, boolean_t);
654 extern int xhci_transfer_sync(xhci_t *, xhci_transfer_t *, uint_t);
655 extern void xhci_transfer_trb_fill_data(xhci_endpoint_t *, xhci_transfer_t *,
656 int, boolean_t);
657 extern void xhci_transfer_calculate_isoc(xhci_device_t *, xhci_endpoint_t *,
658 uint_t, uint_t *, uint_t *);
659
660 /*
661 * Context (DCBAA, Scratchpad, Slot) functions
662 */
663 extern int xhci_context_init(xhci_t *);
664 extern void xhci_context_fini(xhci_t *);
665 extern boolean_t xhci_context_slot_output_init(xhci_t *, xhci_device_t *);
666 extern void xhci_context_slot_output_fini(xhci_t *, xhci_device_t *);
667
668 /*
669 * Command Ring Functions
670 */
671 extern int xhci_command_ring_init(xhci_t *);
697 /*
698 * General Ring functions
699 */
700 extern void xhci_ring_free(xhci_ring_t *);
701 extern int xhci_ring_reset(xhci_t *, xhci_ring_t *);
702 extern int xhci_ring_alloc(xhci_t *, xhci_ring_t *);
703
704 /*
705 * Event Ring (Consumer) oriented functions.
706 */
707 extern xhci_trb_t *xhci_ring_event_advance(xhci_ring_t *);
708
709
710 /*
711 * Command and Transfer Ring (Producer) oriented functions.
712 */
713 extern boolean_t xhci_ring_trb_tail_valid(xhci_ring_t *, uint64_t);
714 extern int xhci_ring_trb_valid_range(xhci_ring_t *, uint64_t, uint_t);
715
716 extern boolean_t xhci_ring_trb_space(xhci_ring_t *, uint_t);
717 extern void xhci_ring_trb_fill(xhci_ring_t *, uint_t, xhci_trb_t *, boolean_t);
718 extern void xhci_ring_trb_produce(xhci_ring_t *, uint_t);
719 extern boolean_t xhci_ring_trb_consumed(xhci_ring_t *, uint64_t);
720 extern void xhci_ring_trb_put(xhci_ring_t *, xhci_trb_t *);
721 extern void xhci_ring_skip(xhci_ring_t *);
722 extern void xhci_ring_skip_transfer(xhci_ring_t *, xhci_transfer_t *);
723
724 /*
725 * MMIO related functions. Note callers are responsible for checking with FM
726 * after accessing registers.
727 */
728 extern int xhci_check_regs_acc(xhci_t *);
729
730 extern uint8_t xhci_get8(xhci_t *, xhci_reg_type_t, uintptr_t);
731 extern uint16_t xhci_get16(xhci_t *, xhci_reg_type_t, uintptr_t);
732 extern uint32_t xhci_get32(xhci_t *, xhci_reg_type_t, uintptr_t);
733 extern uint64_t xhci_get64(xhci_t *, xhci_reg_type_t, uintptr_t);
734
735 extern void xhci_put8(xhci_t *, xhci_reg_type_t, uintptr_t, uint8_t);
736 extern void xhci_put16(xhci_t *, xhci_reg_type_t, uintptr_t, uint16_t);
737 extern void xhci_put32(xhci_t *, xhci_reg_type_t, uintptr_t, uint32_t);
|
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 */
15
16 #ifndef _SYS_USB_XHCI_XHCI_H
17 #define _SYS_USB_XHCI_XHCI_H
18
19 /*
20 * Extensible Host Controller Interface (xHCI) USB Driver
21 */
22
23 #include <sys/conf.h>
24 #include <sys/ddi.h>
25 #include <sys/sunddi.h>
26 #include <sys/taskq_impl.h>
27 #include <sys/sysmacros.h>
28 #include <sys/usb/hcd/xhci/xhcireg.h>
29
30 #include <sys/usb/usba.h>
31 #include <sys/usb/usba/hcdi.h>
32 #include <sys/usb/hubd/hub.h>
33 #include <sys/usb/usba/hubdi.h>
39 #endif
40
41 /*
42 * The base segment for DMA attributes was determined to be 4k based on xHCI 1.1
43 * / table 54: Data Structure Max Size, Boundary, and Alignment Requirement
44 * Summary. This indicates that the required alignment for most things is
45 * PAGESIZE, which in our current implementation is required to be 4K. We
46 * provide the ring segment value below for the things which need 64K alignment
47 *
48 * Similarly, in the same table, the maximum required alignment is 64 bytes,
49 * hence we use that for everything.
50 *
51 * Next is the scatter/gather lengths. For most of the data structures, we only
52 * want to have a single SGL entry, e.g. just a simple flat mapping. For many of
53 * our transfers, we use the same logic to simplify the implementation of the
54 * driver. However, for bulk transfers, which are the largest by far, we want to
55 * be able to leverage SGLs to give us more DMA flexibility.
56 *
57 * We can transfer up to 64K in one transfer request block (TRB) which
58 * corresponds to a single SGL entry. Each ring we create is a single page in
59 * size and will support at most 256 TRBs. To try and give the operating system
60 * flexibility when allocating DMA transfers, we've opted to allow up to 63
61 * SGLs. Because there isn't a good way to support DMA windows with the xHCI
62 * controller design, if this number is too small then DMA allocations and
63 * binding might fail. If the DMA binding fails, the transfer will fail.
64 *
65 * The reason that we use 63 SGLs and not the expected 64 is that we always need
66 * to allocate an additional TRB for the event data. This leaves us with a
67 * nicely divisible number of entries.
68 *
69 * The final piece of this is the maximum sized transfer that the driver
70 * advertises to the broader framework. This is currently sized at 512 KiB. For
71 * reference the ehci driver sized this value at 640 KiB. It's important to
72 * understand that this isn't reflected in the DMA attribute limitation, because
73 * it's not an attribute of the hardware. Experimentally, this has proven to be
74 * sufficient for most of the drivers that we support today. When considering
75 * increasing this number, please note the impact that might have on the
76 * required number of DMA SGL entries required to satisfy the allocation.
77 *
78 * The value of 512 KiB was originally based on the number of SGLs we supported
79 * multiplied by the maximum transfer size. The original number of
80 * XHCI_TRANSFER_DMA_SGL was 8. The 512 KiB value was based upon taking the
81 * number of SGLs and assuming that each TRB used its maximum transfer size of
82 * 64 KiB.
83 */
84 #define XHCI_TRB_MAX_TRANSFER 65536 /* 64 KiB */
85 #define XHCI_DMA_ALIGN 64
86 #define XHCI_DEF_DMA_SGL 1
87 #define XHCI_TRANSFER_DMA_SGL 63
88 #define XHCI_MAX_TRANSFER 524288 /* 512 KiB */
89
90 /*
91 * Properties and values for rerouting ehci ports to xhci.
92 */
93 #define XHCI_PROP_REROUTE_DISABLE 0
94 #define XHCI_PROP_REROUTE_DEFAULT 1
95
96 /*
97 * This number is a bit made up. Truthfully, the API here isn't the most useful
98 * for what we need to define as it should really be based on the endpoint that
99 * we're interested in rather than the device as a whole.
100 *
101 * We're basically being asked how many TRBs we're willing to schedule in one
102 * go. There's no great way to come up with this number, so we basically are
103 * making up something such that we use up a good portion of a ring, but not too
104 * much of it.
105 */
106 #define XHCI_ISOC_MAX_TRB 64
107
108 #ifdef DEBUG
109 #define XHCI_DMA_SYNC(dma, flag) VERIFY0(ddi_dma_sync( \
110 (dma).xdb_dma_handle, 0, 0, \
111 (flag)))
112 #else
113 #define XHCI_DMA_SYNC(dma, flag) ((void) ddi_dma_sync( \
114 (dma).xdb_dma_handle, 0, 0, \
115 (flag)))
116 #endif
117
118 /*
119 * TRBs need to indicate the number of remaining USB packets in the overall
120 * transfer. This is a 5-bit value, which means that the maximum value we can
121 * store in that TRD field is 31.
122 */
123 #define XHCI_MAX_TDSIZE 31
124
125 /*
126 * This defines a time in 2-ms ticks that is required to wait for the controller
127 * to be ready to go. Section 5.4.8 of the XHCI specification in the description
128 * of the PORTSC register indicates that the upper bound is 20 ms. Therefore the
129 * number of ticks is 10.
130 */
131 #define XHCI_POWER_GOOD 10
132
133 /*
134 * Definitions to determine the default number of interrupts. Note that we only
135 * bother with a single interrupt at this time, though we've arranged the driver
136 * to make it possible to request more if, for some unlikely reason, it becomes
137 * necessary.
138 */
139 #define XHCI_NINTR 1
140
141 /*
142 * Default interrupt modulation value. This enables us to have 4000 interrupts /
143 * second. This is supposed to be the default value of the controller. See xHCI
144 * 1.1 / 4.17.2 for more information.
145 */
318 typedef struct xhci_trb {
319 uint64_t trb_addr;
320 uint32_t trb_status;
321 uint32_t trb_flags;
322 } xhci_trb_t;
323 #pragma pack()
324
325 /*
326 * This represents a single transfer that we want to allocate and perform.
327 */
328 typedef struct xhci_transfer {
329 list_node_t xt_link;
330 hrtime_t xt_sched_time;
331 xhci_dma_buffer_t xt_buffer;
332 uint_t xt_ntrbs;
333 uint_t xt_short;
334 uint_t xt_timeout;
335 usb_cr_t xt_cr;
336 boolean_t xt_data_tohost;
337 xhci_trb_t *xt_trbs;
338 uint64_t *xt_trbs_pa;
339 usb_isoc_pkt_descr_t *xt_isoc;
340 usb_opaque_t xt_usba_req;
341 } xhci_transfer_t;
342
343 /*
344 * This represents a ring in xHCI, upon which event, transfer, and command TRBs
345 * are scheduled.
346 */
347 typedef struct xhci_ring {
348 xhci_dma_buffer_t xr_dma;
349 uint_t xr_ntrb;
350 xhci_trb_t *xr_trb;
351 uint_t xr_head;
352 uint_t xr_tail;
353 uint8_t xr_cycle;
354 } xhci_ring_t;
355
356 /*
357 * This structure is used to represent the xHCI Device Context Base Address
358 * Array. It's defined in section 6.1 of the specification and is required for
657 extern boolean_t xhci_ddi_intr_enable(xhci_t *);
658 extern int xhci_intr_conf(xhci_t *);
659
660 /*
661 * DMA related functions
662 */
663 extern int xhci_check_dma_handle(xhci_t *, xhci_dma_buffer_t *);
664 extern void xhci_dma_acc_attr(xhci_t *, ddi_device_acc_attr_t *);
665 extern void xhci_dma_dma_attr(xhci_t *, ddi_dma_attr_t *);
666 extern void xhci_dma_scratchpad_attr(xhci_t *, ddi_dma_attr_t *);
667 extern void xhci_dma_transfer_attr(xhci_t *, ddi_dma_attr_t *, uint_t);
668 extern void xhci_dma_free(xhci_dma_buffer_t *);
669 extern boolean_t xhci_dma_alloc(xhci_t *, xhci_dma_buffer_t *, ddi_dma_attr_t *,
670 ddi_device_acc_attr_t *, boolean_t, size_t, boolean_t);
671 extern uint64_t xhci_dma_pa(xhci_dma_buffer_t *);
672
673 /*
674 * DMA Transfer Ring functions
675 */
676 extern xhci_transfer_t *xhci_transfer_alloc(xhci_t *, xhci_endpoint_t *, size_t,
677 uint_t, int);
678 extern void xhci_transfer_free(xhci_t *, xhci_transfer_t *);
679 extern void xhci_transfer_copy(xhci_transfer_t *, void *, size_t, boolean_t);
680 extern int xhci_transfer_sync(xhci_t *, xhci_transfer_t *, uint_t);
681 extern void xhci_transfer_trb_fill_data(xhci_endpoint_t *, xhci_transfer_t *,
682 int, boolean_t);
683 extern void xhci_transfer_calculate_isoc(xhci_device_t *, xhci_endpoint_t *,
684 uint_t, uint_t *, uint_t *);
685
686 /*
687 * Context (DCBAA, Scratchpad, Slot) functions
688 */
689 extern int xhci_context_init(xhci_t *);
690 extern void xhci_context_fini(xhci_t *);
691 extern boolean_t xhci_context_slot_output_init(xhci_t *, xhci_device_t *);
692 extern void xhci_context_slot_output_fini(xhci_t *, xhci_device_t *);
693
694 /*
695 * Command Ring Functions
696 */
697 extern int xhci_command_ring_init(xhci_t *);
723 /*
724 * General Ring functions
725 */
726 extern void xhci_ring_free(xhci_ring_t *);
727 extern int xhci_ring_reset(xhci_t *, xhci_ring_t *);
728 extern int xhci_ring_alloc(xhci_t *, xhci_ring_t *);
729
730 /*
731 * Event Ring (Consumer) oriented functions.
732 */
733 extern xhci_trb_t *xhci_ring_event_advance(xhci_ring_t *);
734
735
736 /*
737 * Command and Transfer Ring (Producer) oriented functions.
738 */
739 extern boolean_t xhci_ring_trb_tail_valid(xhci_ring_t *, uint64_t);
740 extern int xhci_ring_trb_valid_range(xhci_ring_t *, uint64_t, uint_t);
741
742 extern boolean_t xhci_ring_trb_space(xhci_ring_t *, uint_t);
743 extern void xhci_ring_trb_fill(xhci_ring_t *, uint_t, xhci_trb_t *, uint64_t *,
744 boolean_t);
745 extern void xhci_ring_trb_produce(xhci_ring_t *, uint_t);
746 extern boolean_t xhci_ring_trb_consumed(xhci_ring_t *, uint64_t);
747 extern void xhci_ring_trb_put(xhci_ring_t *, xhci_trb_t *);
748 extern void xhci_ring_skip(xhci_ring_t *);
749 extern void xhci_ring_skip_transfer(xhci_ring_t *, xhci_transfer_t *);
750
751 /*
752 * MMIO related functions. Note callers are responsible for checking with FM
753 * after accessing registers.
754 */
755 extern int xhci_check_regs_acc(xhci_t *);
756
757 extern uint8_t xhci_get8(xhci_t *, xhci_reg_type_t, uintptr_t);
758 extern uint16_t xhci_get16(xhci_t *, xhci_reg_type_t, uintptr_t);
759 extern uint32_t xhci_get32(xhci_t *, xhci_reg_type_t, uintptr_t);
760 extern uint64_t xhci_get64(xhci_t *, xhci_reg_type_t, uintptr_t);
761
762 extern void xhci_put8(xhci_t *, xhci_reg_type_t, uintptr_t, uint8_t);
763 extern void xhci_put16(xhci_t *, xhci_reg_type_t, uintptr_t, uint16_t);
764 extern void xhci_put32(xhci_t *, xhci_reg_type_t, uintptr_t, uint32_t);
|