[DO NOT MERGE] Fix usb suspend reset

sw/device/tests/BUILD

@@ -4508,6 +4508,7 @@ opentitan_test(
     silicon = silicon_params(
         test_cmd = """
             --bootstrap="{firmware}"
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
             --no-wait-for-usb-device
@@ -4546,6 +4547,7 @@ opentitan_test(
         test_cmd = """
             --bootstrap="{firmware}"
             --timeout=30s
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
             --no-wait-for-usb-device
@@ -4580,6 +4582,7 @@ opentitan_test(
     silicon = silicon_params(
         test_cmd = """
             --bootstrap="{firmware}"
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
             --no-wait-for-usb-device
@@ -4609,6 +4612,7 @@ opentitan_test(
     silicon = silicon_params(
         test_cmd = """
             --bootstrap="{firmware}"
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
             --wake=disconnect
@@ -4644,6 +4648,7 @@ opentitan_test(
     silicon = silicon_params(
         test_cmd = """
             --bootstrap="{firmware}"
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
             --no-wait-for-usb-device
@@ -4689,6 +4694,7 @@ opentitan_test(
     silicon = silicon_params(
         test_cmd = """
             --bootstrap="{firmware}"
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
             --wake=reset
@@ -4724,6 +4730,7 @@ opentitan_test(
     silicon = silicon_params(
         test_cmd = """
             --bootstrap="{firmware}"
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
             --no-wait-for-usb-device
@@ -4760,6 +4767,7 @@ opentitan_test(
     silicon = silicon_params(
         test_cmd = """
             --bootstrap="{firmware}"
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
             --no-wait-for-usb-device
@@ -4800,6 +4808,7 @@ opentitan_test(
     silicon = silicon_params(
         test_cmd = """
             --bootstrap="{firmware}"
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
         """,
@@ -4858,6 +4867,7 @@ opentitan_test(
     silicon = silicon_params(
         test_cmd = """
             --bootstrap="{firmware}"
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
             --exec=$(rootpath :usbdev_stream_host_harness)
@@ -4897,6 +4907,7 @@ opentitan_test(
     silicon = silicon_params(
         test_cmd = """
             --bootstrap="{firmware}"
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
             --exec=$(rootpath :usbdev_stream_host_harness)
@@ -4936,6 +4947,7 @@ opentitan_test(
     silicon = silicon_params(
         test_cmd = """
             --bootstrap="{firmware}"
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
             --exec=$(rootpath :usbdev_stream_host_harness)
@@ -4972,6 +4984,7 @@ opentitan_test(
     silicon = silicon_params(
         test_cmd = """
             --bootstrap="{firmware}"
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
             --no-wait-for-usb-device
@@ -5072,6 +5085,7 @@ opentitan_test(
             --bootstrap="{firmware}"
             --fin-phase=suspend
             --init-phase=suspend
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
         """,
@@ -5110,6 +5124,7 @@ opentitan_test(
             --bootstrap="{firmware}"
             --fin-phase=sleep-resume
             --init-phase=sleep-resume
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
         """,
@@ -5149,6 +5164,7 @@ opentitan_test(
             --bootstrap="{firmware}"
             --fin-phase=sleep-reset
             --init-phase=sleep-resume
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
         """,
@@ -5190,6 +5206,7 @@ opentitan_test(
             --bootstrap="{firmware}"
             --fin-phase=deep-resume
             --init-phase=sleep-disconnect
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
         """,
@@ -5229,6 +5246,7 @@ opentitan_test(
             --bootstrap="{firmware}"
             --fin-phase=deep-resume
             --init-phase=deep-resume
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
         """,
@@ -5268,6 +5286,7 @@ opentitan_test(
             --bootstrap="{firmware}"
             --fin-phase=deep-reset
             --init-phase=deep-resume
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
         """,
@@ -5307,6 +5326,7 @@ opentitan_test(
             --bootstrap="{firmware}"
             --fin-phase=shutdown
             --init-phase=deep-disconnect
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
         """,
@@ -5337,6 +5357,7 @@ opentitan_test(
             --bootstrap="{firmware}"
             --fin-phase=shutdown
             --init-phase=suspend
+            --strapping=USB_VBUS_SENSE
             --vbus-sense-en=VBUS_SENSE_EN
             --vbus-sense=VBUS_SENSE
         """,

sw/device/tests/usbdev_suspend.c

@@ -132,7 +132,7 @@
  * Timeout constants in microseconds;
  */
 enum {
-  TimeoutResumeMissed = 40U * 1000U,
+  TimeoutResumeMissed = 400U * 1000U,
   TimeoutResetMissed = 60U * 1000U,
   TimeoutWakeupResume = 30000u,
   TimeoutFinishMissed = 2000u,
@@ -1816,7 +1816,7 @@ bool usbdev_suspend_test(usbdev_suspend_phase_t init_phase,
       host_resumes = true;
       host_resets = true;
       host_disconnects = true;
-      verbose = false;
+      verbose = true;
       break;
 
     default:
@@ -1835,7 +1835,7 @@ bool usbdev_suspend_test(usbdev_suspend_phase_t init_phase,
 
       // Presently, the FPGA build is expected to be observed/monitored by a
       // developer, so verbose reporting is appropriate.
-      verbose = false;  // true;
+      verbose = true;  // true;
       break;
   }
 

sw/host/opentitanlib/src/app/config/hyperdebug_teacup.json

@@ -403,8 +403,14 @@
       "alias_of": "CN8_2"
     },
     {
+      // The VBUS sense pin (IOC7) is connected to the output of a buffer, controlled
+      // by IOA2 and VBUS_SENSE_EN. When the buffer is off, the pin is left floating
+      // but there is a pull-down resistor on the board. Unfortunately, the resistor
+      // is very weak which can cause some issues. This is why we also request a pull-down
+      // from hyperdebug on this pin.
       "name": "VBUS_SENSE",
       "mode": "Input",
+      "pull_mode": "PullDown",
       "alias_of": "CN10_18"
     }
   ],
@@ -515,5 +521,17 @@
         }
       ]
     }
+    {
+      "name": "USB_VBUS_SENSE",
+      "pins": [
+        // The IOA2 is set to push-pull low by default to prevent entering SPI rescue mode
+        // But IOA2 is also connected to the USB VBUS SENSE buffer which prevents the OT
+        // device from sensing USB.
+        {
+          "name": "IOA2",
+          "mode": "Input",
+        }
+      ]
+    },
   ]
 }

sw/host/opentitanlib/src/transport/errors.rs

@@ -17,8 +17,8 @@ pub enum TransportError {
     NoMatch,
     #[error("Found no USB device")]
     NoDevice,
-    #[error("Found multiple USB devices, use --usb-serial")]
-    MultipleDevices,
+    #[error("Found multiple USB devices ({0}), use --usb-serial")]
+    MultipleDevices(String),
     #[error("USB error: {0}")]
     UsbGenericError(String),
     #[error("Error opening USB device: {0}")]

sw/host/opentitanlib/src/util/usb.rs

@@ -127,7 +127,7 @@ impl UsbBackend {
     pub fn new(usb_vid: u16, usb_pid: u16, usb_serial: Option<&str>) -> Result<Self> {
         let mut devices = UsbBackend::scan(Some((usb_vid, usb_pid)), None, usb_serial)?;
         ensure!(!devices.is_empty(), TransportError::NoDevice);
-        ensure!(devices.len() == 1, TransportError::MultipleDevices);
+        ensure!(devices.len() == 1, TransportError::MultipleDevices(format!("{:?}", devices)));
 
         let (device, serial_number) = devices.remove(0);
         Ok(UsbBackend {
@@ -166,7 +166,7 @@ impl UsbBackend {
                     return Err(TransportError::NoDevice.into());
                 }
             }
-            ensure!(devices.len() == 1, TransportError::MultipleDevices);
+            ensure!(devices.len() == 1, TransportError::MultipleDevices(format!("{:?}", devices)));
 
             let (device, serial_number) = devices.remove(0);
             return Ok(UsbBackend {

sw/host/tests/chip/usb/BUILD

@@ -16,6 +16,7 @@ rust_library(
         "//sw/host/opentitanlib",
         "@crate_index//:anyhow",
         "@crate_index//:clap",
+        "@crate_index//:humantime",
         "@crate_index//:log",
         "@crate_index//:rusb",
     ],

sw/host/tests/chip/usb/README.md

@@ -0,0 +1,57 @@
+# USB tests
+
+This directory contains the test harnesses for USB tests.
+Some of these tests not only require permissions to access the OT USB device,
+but also the USB hub to which the OT USB device is connected.
+For this reason, it is **strongly** encouraged to connect the device under test
+to a dedicated hub and not your root hub (otherwise you will give access to all USB
+device on the bus to any program).
+
+If you do not have sufficient permissions, the test will fail and let you know.
+The following instructions explain how to correctly set those permissions.
+
+## Permissions for OT USB
+
+The OT USB device appears with VID 0x18d1 (Google) and PID 0x503a.
+Since the device will connect and disconnect several times during the test,
+the only correct way to set the permissions is to use a udev rule.
+The following rule is recommended:
+```
+# USB device under test: uses Google as VID and a Google allocated PID
+ACTION=="add|change", SUBSYSTEM=="usb|tty", ATTRS{idVendor}=="18d1", ATTRS{idProduct}=="503a", MODE="0666"
+```
+
+## Permissions for the hub
+
+The hub changes a lot less frequency than OT USB. Furthermore, most hubs do not have unique serial numbers,
+and it is common for all hubs in a system to have the same VID and PID. For this reason, the recommended
+way to set the hub permission is to set it manually. Doing so is a two step process:
+- identify the hub,
+- set the permission.
+
+### Identifying the hub
+
+You need to identify the bus and addres of the hub.
+The simplest option is to run a test, let it fail and use the error message to get the path.
+For example, running `//sw/device/tests:usbdev_deep_disconnect_test_fpga_cw310_sival_rom_ext` with
+the wrong permissions will lead the following error:
+```
+[2025-07-10T11:59:59.430Z INFO  usbdev_suspend] waiting for device...
+[2025-07-10T11:59:59.958Z INFO  usbdev_suspend] device found at bus=1 address=35
+[2025-07-10T11:59:59.958Z INFO  usbdev_suspend] parent hub at bus=1, address=2, port numbers=[2]
+[2025-07-10T11:59:59.958Z INFO  usbdev_suspend] device under test is on port 3
+361:Finished test usbdev_suspend: Err(for this test, you need to make sure that the program has sufficient permissions to access the hub
+```
+The important line is:
+```
+[2025-07-10T11:59:59.958Z INFO  usbdev_suspend] parent hub at bus=<BUS>, address=<ADDR>, port numbers=<PORTS>
+```
+From this, we now know the bus and address of the hub.
+
+### Setting the permissions
+
+Once you know the bus and address of the device, run as root:
+```bash
+chmod 0666 /dev/bus/usb/<BUS>/<ADDR>
+```
+Note that bus is usually 0 padded to three characters, and the address to 2 characters.