[PATCH 11/22] usb: xhci: update port register bitfield comments for consistency

[Niklas Neronin <niklas.neronin@linux.intel.com>]

No functional changes.

Update comments in xhci-port.h to improve readability and ensure a
consistent format across all Port Register bit fields.

Each field now includes a brief description of its name, along with the
xHCI specification abbreviation when the macro uses a different name,
and its valid value range where applicable.

Bit field comment format:
/* <bit range> - <Field name>,<noteworthy information if any> */

These updates are based on the xHCI specification, revision 1.2.

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>
---
 drivers/usb/host/xhci-port.h | 63 ++++++++++++++++++++----------------
 drivers/usb/host/xhci.c      |  2 +-
 2 files changed, 36 insertions(+), 29 deletions(-)

diff --git a/drivers/usb/host/xhci-port.h b/drivers/usb/host/xhci-port.h
index 3aa23e143521..8cc175fb4dcb 100644
--- a/drivers/usb/host/xhci-port.h
+++ b/drivers/usb/host/xhci-port.h
@@ -1,17 +1,21 @@
 /* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * xHCI Host Controller USB Port Register Set
+ * xHCI Specification Section 5.4, Revision 1.2.
+ */
 
 #include <linux/bitfield.h>
 #include <linux/bits.h>
 
-/* PORTSC - Port Status and Control Register - port_status_base bitmasks */
-/* true: device connected */
+/* Port Status and Control (PORTSC) 5.4.8 */
+/* bit 0 - Current Connect Status (CCS) */
 #define PORT_CONNECT	BIT(0)
-/* true: port enabled */
+/* bit 1 - Port Enabled/Disabled (PED) */
 #define PORT_PE		BIT(1)
-/* bit 2 reserved and zeroed */
-/* true: port has an over-current condition */
+/* bit 2 - Rsvd */
+/* bit 3 - Over-current Active (OCA) */
 #define PORT_OC		BIT(3)
-/* true: port reset signaling asserted */
+/* bit 4 - Port Reset (PR) */
 #define PORT_RESET	BIT(4)
 /*
  * bits 8:5 - Port Link State, by default '5'.
@@ -61,23 +65,26 @@
 #define PIC_OFF		0
 #define PIC_AMBER	1
 #define PIC_GREEN	2
-/* Port Link State Write Strobe - set this when changing link state */
+/* bit 16 - Port Link State Write Strobe (LWS), set this when changing link state */
 #define PORT_LINK_STROBE	BIT(16)
-/* true: connect status change */
+/* bit 17 - Connect Status Change */
 #define PORT_CSC	BIT(17)
-/* true: port enable change */
+/* bit 18 - Port Enabled/Disabled Change */
 #define PORT_PEC	BIT(18)
-/* true: warm reset for a USB 3.0 device is done.  A "hot" reset puts the port
+/*
+ * bit 19 - Warm Port Reset Change
+ * Warm reset for a USB 3.0 device is done.  A "hot" reset puts the port
  * into an enabled state, and the device into the default state.  A "warm" reset
  * also resets the link, forcing the device through the link training sequence.
  * SW can also look at the Port Reset register to see when warm reset is done.
  */
 #define PORT_WRC	BIT(19)
-/* true: over-current change */
+/* bit 20 - Over-current Change */
 #define PORT_OCC	BIT(20)
-/* true: reset change - 1 to 0 transition of PORT_RESET */
+/* bit 21 - Port Reset Change (PRC) */
 #define PORT_RC		BIT(21)
-/* port link status change - set on some port link state transitions:
+/*
+ * bit 22 - Port Link State Change, set on some port link state transitions:
  *  Transition				Reason
  *  ------------------------------------------------------------------------------
  *  - U3 to Resume			Wakeup signaling from a device
@@ -91,28 +98,27 @@
  *  - Any state to inactive		Error on USB 3.0 port
  */
 #define PORT_PLC	BIT(22)
-/* port configure error change - port failed to configure its link partner */
+/* bit 23 - Port Config Error Change, port failed to configure its link partner */
 #define PORT_CEC	BIT(23)
-#define PORT_CHANGE_MASK	(PORT_CSC | PORT_PEC | PORT_WRC | PORT_OCC | \
-				 PORT_RC | PORT_PLC | PORT_CEC)
-
-
-/* Cold Attach Status - xHC can set this bit to report device attached during
- * Sx state. Warm port reset should be perfomed to clear this bit and move port
- * to connected state.
+/*
+ * bit 24 - Cold Attach Status
+ * xHC can set this bit to report device attached during Sx state.
+ * Warm port reset should be perfomed to clear this bit and move port to connected state.
  */
 #define PORT_CAS	BIT(24)
-/* wake on connect (enable) */
+/* bit 25 - Wake on Connect Enable (WCE) */
 #define PORT_WKCONN_E	BIT(25)
-/* wake on disconnect (enable) */
+/* bit 26 - Wake on Disconnect Enable (WDE) */
 #define PORT_WKDISC_E	BIT(26)
-/* wake on over-current (enable) */
+/* bit 27 - Wake on Over-current Enable (WOE) */
 #define PORT_WKOC_E	BIT(27)
-/* bits 28:29 reserved */
-/* true: device is non-removable - for USB 3.0 roothub emulation */
+/* bits 29:28 - RsvdZ */
+/* bit 30 - Device Removable (DR), for USB 3.0 roothub emulation */
 #define PORT_DEV_REMOVE	BIT(30)
-/* Initiate a warm port reset - complete when PORT_WRC is '1' */
+/* bit 31 - Warm Port Reset (WPR), complete when PORT_WRC is '1' */
 #define PORT_WR		BIT(31)
+#define PORT_CHANGE_MASK	(PORT_CSC | PORT_PEC | PORT_WRC | PORT_OCC | \
+				 PORT_RC | PORT_PLC | PORT_CEC)
 
 /* We mark duplicate entries with -1 */
 #define DUPLICATE_ENTRY ((u8)(-1))
@@ -185,7 +191,8 @@
 #define PORT_BESLD_MASK		GENMASK(13, 10)
 /* bits 31:14 - RsvdP */
 
-/* Set default HIRD/BESL value to 4 (350/400us) for USB2 L1 LPM resume latency.
+/*
+ * Set default HIRD/BESL value to 4 (350/400us) for USB2 L1 LPM resume latency.
  * Safe to use with mixed HIRD and BESL systems (host and device) and is used
  * by other operating systems.
  *
diff --git a/drivers/usb/host/xhci.c b/drivers/usb/host/xhci.c
index 9ae4f6b3e5ec..0e246755e979 100644
--- a/drivers/usb/host/xhci.c
+++ b/drivers/usb/host/xhci.c
@@ -4699,7 +4699,7 @@ static int xhci_set_usb2_hardware_lpm(struct usb_hcd *hcd,
 		if (udev->usb2_hw_lpm_besl_capable) {
 			/* if device doesn't have a preferred BESL value use a
 			 * default one which works with mixed HIRD and BESL
-			 * systems. See XHCI_DEFAULT_BESL definition in xhci.h
+			 * systems. See XHCI_DEFAULT_BESL definition in xhci-ports.h
 			 */
 			field = le32_to_cpu(udev->bos->ext_cap->bmAttributes);
 			if ((field & USB_BESL_SUPPORT) &&
-- 
2.50.1