From 0ae3c6c96d047093db783625e0bb5a60cbac14a3 Mon Sep 17 00:00:00 2001
From: Josh Holtrop <jholtrop@gmail.com>
Date: Sat, 23 Sep 2023 11:59:20 -0400
Subject: [PATCH] Document xHCI operational registers

---
 src/hulk/usb/xhci.d | 67 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/src/hulk/usb/xhci.d b/src/hulk/usb/xhci.d
index 7a106b6..a99896c 100644
--- a/src/hulk/usb/xhci.d
+++ b/src/hulk/usb/xhci.d
@@ -121,15 +121,82 @@ struct XHCI
      */
     struct OperationalRegisters
     {
+        /**
+         * 0 run/stop (RS)
+         * 1 host controller reset (HCRST)
+         * 2 interrupter enable (INTE)
+         * 3 host system error enable (HSEE)
+         * 6:4 reserved
+         * 7 light host controller reset (LHCRST)
+         * 8 controller save state (CSS)
+         * 9 controller restore state (CRS)
+         * 10 enable wrap event (EWE)
+         * 11 enable U3 MFINDEX stop (UE3S)
+         * 12 stopped short packet enable (SPE; xHCI v1.1+)
+         * 13 CEM enable (CME; xHCI v1.1+)
+         * 14 extended TBC enable (ETE; xHCI v1.2+)
+         * 15 extended TBC TRB status enable (TSC_EN; xHCI v1.2+)
+         * 16 VTIO enable (VTIOE; xHCI v1.2+)
+         * 31:17 reserved
+         */
         uint usb_command;
+
+        /**
+         * 0 HCHalted
+         * 1 reserved
+         * 2 Host System Error (HSE)
+         * 3 Event Interrupt (EINT)
+         * 4 Port Change Detected (PCD)
+         * 7:5 reserved
+         * 8 Save State Status (SSS)
+         * 9 Restore State Status (RSS)
+         * 10 Save/Restore Error (SRE)
+         * 11 Controller Not Ready (CNR)
+         * 12 Host Controller Error (HCE)
+         * 31:13 reserved
+         */
         uint usb_status;
+
+        /**
+         * 15:0 Page Size (actual page size is 2^(x+12))
+         * 31:16 reserved
+         */
         uint page_size;
+
         uint[2] _reserved01;
+
+        /**
+         * 15:0 Notification Enable
+         * 31:16 reserved
+         */
         uint dn_ctrl;
+
+        /**
+         * 0 Ring Cycle State (RCS)
+         * 1 Command Stop (CS)
+         * 2 Command Abort (CA)
+         * 3 Command Ring Running (CRR)
+         * 5:4 reserved
+         * 63:6 Command Ring Pointer
+         */
         ulong cr_ctrl;
+
         uint[4] _reserved02;
+
+        /**
+         * 5:0 reserved
+         * 63:6 Device Context Base Address Array Pointer
+         */
         ulong dcbaap;
+
+        /**
+         * 7:0 Max Device Slots Enabled (MaxSlotsEn)
+         * 8 U3 Entry Enable (U3E; xHCI v1.1+)
+         * 9 Configuration Information Enable (CIE; xHCI v1.1+)
+         * 31:10 reserved
+         */
         uint config;
+
         uint _reserved03;
     }
     static assert(OperationalRegisters.sizeof == 0x40u);