ot_usbdev: Create initial usbdev block

docs/opentitan/earlgrey.md

@@ -269,6 +269,12 @@ There are two modes to handle address remapping, with different limitations:
 * `-device <name>,bus=<bus>,address=<address>` can be used to attach devices at a specific address
   to one of the three I2C buses. The buses are named `ot-i2c0`, `ot-i2c1`, and `ot-i2c2`.
 
+### USBDEV
+
+* `-chardev pty,id=usbdev` can be used to connect to the usbdev driver.
+
+See the [USBDEV documentation](usbdev.md)] for more details.
+
 ## Useful debugging options
 
 ### Device log traces

docs/opentitan/usbdev.md

@@ -0,0 +1,31 @@
+# OpenTitan USBDEV
+
+**Warning:** the USBDEV driver is still in development and not expected to work at the moment!
+
+## `usb` Chardev
+
+The USBDEV driver exposes a chardev with ID `usbdev` which can used to control some aspects of the
+emulation.
+Once connected, the driver accepts textual commands.
+Each command must end with a newline.
+The following commands are recognized:
+- `vbus_on`: turn on VBUS, see [#VBUS-handling](VBUS handling) for more details.
+- `vbus_off`: turn off VBUS, see [#VBUS-handling](VBUS handling) for more details.
+
+## VBUS handling
+
+On a real machine, the VBUS sense pin is usually connected to the VBUS connector so
+that the chip can detect when a cable is plugged in. For the purpose of emulation, a different
+approach needs to be taken. The driver supports two modes of operation which are controlled
+by the `vbus-override` property which can be set on the command-line by
+`-global ot-usbdev.vbus-override=<mode>`. The following modes are supported:
+
+- `vbus-override=on`: in this mode, the VBUS sense pin is entirely managed over the `usbdev`
+  chardev.
+  By default, the sense pin will be set to level low. The `vbus_on` and `vbus_off` commands
+  can be used to change the value of the sense pin. Note that in this mode, the VBUS sense signal
+  will be completely independent of the presence of a USB host.
+- `vbus-override=off`: in this mode, the `vbus_on` and `vbus_off` commands control a virtual "VBUS
+  enable" gate. The VBUS sense pin will be reported as level high if and only if the VBUS enable
+  gate is enabled **and** a USB host is connected to the driver.
+  By default, the VBUS gate is disabled.

hw/opentitan/Kconfig

@@ -191,6 +191,9 @@ config OT_TIMER
 config OT_UART
     bool
 
+config OT_USBDEV
+    bool
+
 config OT_UNIMP
     bool
 

hw/opentitan/meson.build

@@ -57,6 +57,7 @@ system_ss.add(when: 'CONFIG_OT_SRAM_CTRL', if_true: files('ot_sram_ctrl.c'))
 system_ss.add(when: 'CONFIG_OT_TIMER', if_true: files('ot_timer.c'))
 system_ss.add(when: 'CONFIG_OT_UART', if_true: files('ot_uart.c'))
 system_ss.add(when: 'CONFIG_OT_UNIMP', if_true: files('ot_unimp.c'))
+system_ss.add(when: 'CONFIG_OT_USBDEV', if_true: files('ot_usbdev.c'))
 
 riscv_ss.add(when: 'CONFIG_OT_VMAPPER', if_true: files('ot_vmapper.c'))