Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
usb: xhci: improve xhci-caps.h comments
No functional changes.
This patch updates comments in xhci-caps.h for better readability and
consistency. Each Capability Register bit field now includes a brief
description of its name and valid range, following a uniform comment
format across the file.
These updates are based on the xHCI specification, revision 1.2.
Bit field comment format:
/* <bit range> - <Field name>,<noteworthy information if any> */
Why print the bit range?
The bit range aids in identifying missing macros and reserved bit ranges.
Signed-off-by: Niklas Neronin <niklas.neronin@linux.intel.com>
Signed-off-by: Mathias Nyman <mathias.nyman@linux.intel.com>
Link: https://patch.msgid.link/20251119142417.2820519-19-mathias.nyman@linux.intel.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
authored by
Niklas Neronin
and committed by
Greg Kroah-Hartman
edab0090
8e9a3a1e
+57
-43
+57
-43
drivers/usb/host/xhci-caps.h
+57
-43
drivers/usb/host/xhci-caps.h
···
1
1
/* SPDX-License-Identifier: GPL-2.0 */
2
+
/*
3
+
* xHCI Host Controller Capability Registers.
4
+
* xHCI Specification Section 5.3, Revision 1.2.
5
+
*/
2
6
3
-
/* hc_capbase bitmasks */
4
-
/* bits 7:0 - how long is the Capabilities register */
7
+
/* hc_capbase - bitmasks */
8
+
/* bits 7:0 - Capability Registers Length */
5
9
#define HC_LENGTH(p) XHCI_HC_LENGTH(p)
6
-
/* bits 31:16 */
10
+
/* bits 15:8 - Rsvd */
11
+
/* bits 31:16 - Host Controller Interface Version Number */
7
12
#define HC_VERSION(p) (((p) >> 16) & 0xffff)
8
13
9
14
/* HCSPARAMS1 - hcs_params1 - bitmasks */
10
-
/* bits 0:7, Max Device Slots */
15
+
/* bits 7:0 - Number of Device Slots */
11
16
#define HCS_MAX_SLOTS(p) (((p) >> 0) & 0xff)
12
17
#define HCS_SLOTS_MASK 0xff
13
-
/* bits 8:18, Max Interrupters */
18
+
/* bits 18:8 - Number of Interrupters, max values is 1024 */
14
19
#define HCS_MAX_INTRS(p) (((p) >> 8) & 0x7ff)
15
20
/* bits 31:24, Max Ports - max value is 255 */
16
21
#define HCS_MAX_PORTS(p) (((p) >> 24) & 0xff)
17
22
18
23
/* HCSPARAMS2 - hcs_params2 - bitmasks */
19
-
/* bits 0:3, frames or uframes that SW needs to queue transactions
20
-
* ahead of the HW to meet periodic deadlines */
24
+
/*
25
+
* bits 3:0 - Isochronous Scheduling Threshold, frames or uframes that SW
26
+
* needs to queue transactions ahead of the HW to meet periodic deadlines.
27
+
*/
21
28
#define HCS_IST(p) (((p) >> 0) & 0xf)
22
-
/* bits 4:7, max number of Event Ring segments */
29
+
/* bits 7:4 - Event Ring Segment Table Max, 2^(n) */
23
30
#define HCS_ERST_MAX(p) (((p) >> 4) & 0xf)
24
-
/* bits 21:25 Hi 5 bits of Scratchpad buffers SW must allocate for the HW */
25
-
/* bit 26 Scratchpad restore - for save/restore HW state - not used yet */
26
-
/* bits 27:31 Lo 5 bits of Scratchpad buffers SW must allocate for the HW */
31
+
/* bits 20:8 - Rsvd */
32
+
/* bits 25:21 - Max Scratchpad Buffers (Hi), 5 Most significant bits */
33
+
/* bit 26 - Scratchpad restore, for save/restore HW state */
34
+
/* bits 31:27 - Max Scratchpad Buffers (Lo), 5 Least significant bits */
27
35
#define HCS_MAX_SCRATCHPAD(p) ((((p) >> 16) & 0x3e0) | (((p) >> 27) & 0x1f))
28
36
29
37
/* HCSPARAMS3 - hcs_params3 - bitmasks */
30
-
/* bits 0:7, Max U1 to U0 latency for the roothub ports */
38
+
/* bits 7:0 - U1 Device Exit Latency, Max U1 to U0 latency for the roothub ports */
31
39
#define HCS_U1_LATENCY(p) (((p) >> 0) & 0xff)
32
-
/* bits 16:31, Max U2 to U0 latency for the roothub ports */
40
+
/* bits 15:8 - Rsvd */
41
+
/* bits 31:16 - U2 Device Exit Latency, Max U2 to U0 latency for the roothub ports */
33
42
#define HCS_U2_LATENCY(p) (((p) >> 16) & 0xffff)
34
43
35
-
/* HCCPARAMS - hcc_params - bitmasks */
36
-
/* true: HC can use 64-bit address pointers */
44
+
/* HCCPARAMS1 - hcc_params - bitmasks */
45
+
/* bit 0 - 64-bit Addressing Capability */
37
46
#define HCC_64BIT_ADDR(p) ((p) & (1 << 0))
38
-
/* true: HC can do bandwidth negotiation */
47
+
/* bit 1 - BW Negotiation Capability */
39
48
#define HCC_BANDWIDTH_NEG(p) ((p) & (1 << 1))
40
-
/* true: HC uses 64-byte Device Context structures
41
-
* FIXME 64-byte context structures aren't supported yet.
42
-
*/
49
+
/* bit 2 - Context Size */
43
50
#define HCC_64BYTE_CONTEXT(p) ((p) & (1 << 2))
44
-
/* true: HC has port power switches */
51
+
#define CTX_SIZE(_hcc) (HCC_64BYTE_CONTEXT(_hcc) ? 64 : 32)
52
+
/* bit 3 - Port Power Control */
45
53
#define HCC_PPC(p) ((p) & (1 << 3))
46
-
/* true: HC has port indicators */
54
+
/* bit 4 - Port Indicators */
47
55
#define HCS_INDICATOR(p) ((p) & (1 << 4))
48
-
/* true: HC has Light HC Reset Capability */
56
+
/* bit 5 - Light HC Reset Capability */
49
57
#define HCC_LIGHT_RESET(p) ((p) & (1 << 5))
50
-
/* true: HC supports latency tolerance messaging */
58
+
/* bit 6 - Latency Tolerance Messaging Capability */
51
59
#define HCC_LTC(p) ((p) & (1 << 6))
52
-
/* true: no secondary Stream ID Support */
60
+
/* bit 7 - No Secondary Stream ID Support */
53
61
#define HCC_NSS(p) ((p) & (1 << 7))
54
-
/* true: HC supports Stopped - Short Packet */
62
+
/* bit 8 - Parse All Event Data */
63
+
/* bit 9 - Short Packet Capability */
55
64
#define HCC_SPC(p) ((p) & (1 << 9))
56
-
/* true: HC has Contiguous Frame ID Capability */
65
+
/* bit 10 - Stopped EDTLA Capability */
66
+
/* bit 11 - Contiguous Frame ID Capability */
57
67
#define HCC_CFC(p) ((p) & (1 << 11))
58
-
/* Max size for Primary Stream Arrays - 2^(n+1), where n is bits 12:15 */
68
+
/* bits 15:12 - Max size for Primary Stream Arrays, 2^(n+1) */
59
69
#define HCC_MAX_PSA(p) (1 << ((((p) >> 12) & 0xf) + 1))
60
-
/* Extended Capabilities pointer from PCI base - section 5.3.6 */
70
+
/* bits 31:16 - xHCI Extended Capabilities Pointer, from PCI base: 2^(n) */
61
71
#define HCC_EXT_CAPS(p) XHCI_HCC_EXT_CAPS(p)
62
72
63
-
#define CTX_SIZE(_hcc) (HCC_64BYTE_CONTEXT(_hcc) ? 64 : 32)
64
-
65
-
/* db_off bitmask - bits 31:2 Doorbell Array Offset */
73
+
/* DBOFF - db_off - bitmasks */
74
+
/* bits 1:0 - Rsvd */
75
+
/* bits 31:2 - Doorbell Array Offset */
66
76
#define DBOFF_MASK (0xfffffffc)
67
77
68
-
/* run_regs_off bitmask - bits 0:4 reserved */
78
+
/* RTSOFF - run_regs_off - bitmasks */
79
+
/* bits 4:0 - Rsvd */
80
+
/* bits 31:5 - Runtime Register Space Offse */
69
81
#define RTSOFF_MASK (~0x1f)
70
82
71
83
/* HCCPARAMS2 - hcc_params2 - bitmasks */
72
-
/* true: HC supports U3 entry Capability */
84
+
/* bit 0 - U3 Entry Capability */
73
85
#define HCC2_U3C(p) ((p) & (1 << 0))
74
-
/* true: HC supports Configure endpoint command Max exit latency too large */
86
+
/* bit 1 - Configure Endpoint Command Max Exit Latency Too Large Capability */
75
87
#define HCC2_CMC(p) ((p) & (1 << 1))
76
-
/* true: HC supports Force Save context Capability */
88
+
/* bit 2 - Force Save Context Capabilitu */
77
89
#define HCC2_FSC(p) ((p) & (1 << 2))
78
-
/* true: HC supports Compliance Transition Capability */
90
+
/* bit 3 - Compliance Transition Capability, false: compliance is enabled by default */
79
91
#define HCC2_CTC(p) ((p) & (1 << 3))
80
-
/* true: HC support Large ESIT payload Capability > 48k */
92
+
/* bit 4 - Large ESIT Payload Capability, true: HC support ESIT payload > 48k */
81
93
#define HCC2_LEC(p) ((p) & (1 << 4))
82
-
/* true: HC support Configuration Information Capability */
94
+
/* bit 5 - Configuration Information Capability */
83
95
#define HCC2_CIC(p) ((p) & (1 << 5))
84
-
/* true: HC support Extended TBC Capability, Isoc burst count > 65535 */
96
+
/* bit 6 - Extended TBC Capability, true: Isoc burst count > 65535 */
85
97
#define HCC2_ETC(p) ((p) & (1 << 6))
86
-
/* true: HC support Extended TBC TRB Status Capability */
98
+
/* bit 7 - Extended TBC TRB Status Capability */
87
99
#define HCC2_ETC_TSC(p) ((p) & (1 << 7))
88
-
/* true: HC support Get/Set Extended Property Capability */
100
+
/* bit 8 - Get/Set Extended Property Capability */
89
101
#define HCC2_GSC(p) ((p) & (1 << 8))
90
-
/* true: HC support Virtualization Based Trusted I/O Capability */
102
+
/* bit 9 - Virtualization Based Trusted I/O Capability */
91
103
#define HCC2_VTC(p) ((p) & (1 << 9))
92
-
/* true: HC support Double BW on a eUSB2 HS ISOC EP */
104
+
/* bit 10 - Rsvd */
105
+
/* bit 11 - HC support Double BW on a eUSB2 HS ISOC EP */
93
106
#define HCC2_EUSB2_DIC(p) ((p) & (1 << 11))
107
+
/* bits 31:12 - Rsvd */