Emulated eXtensible Host Controller Interface (xHCI) device

Special thanks to @luqmana getting this started in early 2023:
https://github.com/luqmana/propolis/commits/xhci/

The version of the standard referenced throughout the comments in
this module is xHCI 1.2, but we do not implement the features required
of a 1.1 or 1.2 compliant host controller - that is, we are only
implementing a subset of what xHCI version 1.0 requires of an xHC,
as described by version 1.2 of the *specification*.

https://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/extensible-host-controler-interface-usb-xhci.pdf

At present, the only USB device supported is a USB 2.0 `NullUsbDevice`
with no actual functionality, which exists as a proof-of-concept and
as a means to show that USB `DeviceDescriptor`s are successfully
communicated to the guest in phd-tests.

```
   +---------+
   | PciXhci |
   +---------+
        | has-a
  +-----------------------------+
  |          XhciState          |
  |-----------------------------|
  | PCI MMIO registers          |
  | XhciInterrupter             |
  | DeviceSlotTable             |
  | Usb2Ports + Usb3Ports       |
  | CommandRing                 |
  | newly attached USB devices  |
  +-----------------------------+
      | has-a               |
+-------------------+       | has-a
|  XhciInterrupter  |   +-----------------+
|-------------------|   | DeviceSlotTable |
| EventRing         |   |-----------------|
| MSI-X/INTxPin     |   | DeviceSlot(s)   |___+------------------+
+-------------------+   | DCBAAP          |   |    DeviceSlot    |
                        | Active USB devs |   |------------------|
                        +-----------------+   | TransferRing(s)  |
                                              +------------------+
```

Conventions
===========

Wherever possible, the framework represents `Trb` data through a further
level of abstraction, such as enums constructed from the raw TRB
bitfields before being passed to other parts of the system that use
them, such that the behavior of identifying `TrbType` and accessing
their fields properly according to the spec lives in a conversion
function rather than strewn across implementation of other xHC
functionality.

The nomenclature used is generally trading the "Descriptor" suffix for
"Info", e.g. the high-level enum-variant version of an `EventDescriptor`
is `EventInfo` (which is passed to the `EventRing` to be converted into
Event TRBs and written into guest memory).

For 1-based indices defined by the spec (slot ID, port ID), we use
[SlotId] and [PortId] and their respective `.as_index()` methods to
index into our internal arrays of slots and ports, such that we aspire
to categorically avoid off-by-one errors of omission (of `- 1`).
(Note that indexing into the DCBAA is *not* done with this method, as
position 0 in it is reserved by the spec for the Scratchpad described
in xHCI 1.2 section 4.20)

Implementation
==============

`DeviceSlotTable`
-----------------

When a USB device is attached to the xHC, it is enqueued in a list
within `XhciState` along with its `PortId`. The next time the xHC runs:

- it will update the corresponding **PORTSC** register and inform the
  guest with a TRB on the `EventRing`, and if enabled, a hardware
  interrupt.
- it moves the USB device to the `DeviceSlotTable` in preparation for
  being configured and assigned a slot. When the guest xHCD rings
  Doorbell 0 to run an `EnableSlot` Command, the `DeviceSlotTable`
  assigns the first unused slot ID to it.

Hot-plugging devices live (i.e. not just attaching all devices defined
by the instance spec at boot time as is done now) is not yet
implemented.

Device-slot-related Command TRBs are handled by the `DeviceSlotTable`.
The command interface methods are written as translations of the
behaviors defined in xHCI 1.2 section 4.6 to Rust, with liberties taken
around redundant `TrbCompletionCode` writes; i.e. when the outlined
behavior from the spec describes the xHC placing a `Success` into a new
TRB on the `EventRing` immediately at the beginning of the command's
execution, and then overwriting it with a failure code in the event of
a failure, our implementation postpones the creation and enqueueing of
the event until after the outcome of the command's execution (and thus
the Event TRB's values) are all known.

Ports
-----

Root hub port state machines (xHCI 1.2 section 4.19.1) and port
registers are managed by `Usb2Port`, which has separate methods for
handling register writes by the guest and by the xHC itself.

TRB Rings
---------

**Consumer**:

The `CommandRing` and each slot endpoint's `TransferRing` are
implemented as `ConsumerRing<CommandInfo>` and
`ConsumerRing<TransferInfo>`. Dequeued work items are converted from
raw `CommandDescriptor`s and `TransferDescriptor`s, respectively).

Starting at the dequeue pointer provided by the guest, the
`ConsumerRing` will consume non-Link TRBs (and follow Link TRBs, as in
xHCI 1.2 figure 4-15) into complete work items. In the case of the
`CommandRing`, `CommandDescriptor`s are each only made up of one `Trb`,
but for the `TransferRing` multi-TRB work items are possible, where all
but the last item have the `chain_bit` set.

**Producer**:

The only type of producer ring is the `EventRing`. Events destined for
it are fed through the `XhciInterrupter`, which handles enablement and
rate-limiting of PCI-level machine interrupts being generated as a
result of the events.

Similarly (and inversely) to the consumer rings, the `EventRing`
converts the `EventInfo`s enqueued in it into `EventDescriptor`s to be
written to guest memory regions defined by the `EventRingSegment` Table.

Doorbells
---------

The guest writing to a `DoorbellRegister` makes the host controller
process a consumer TRB ring (the `CommandRing` for doorbell 0, or the
corresponding slot's `TransferRing` for nonzero doorbells). The ring
consumption is performed by the doorbell register write handler, in
`process_command_ring` and `process_transfer_ring`.

Timer registers
---------------

The value of registers defined as incrementing/decrementing per time
interval, such as **MFINDEX** and the `XhciInterrupter`'s **IMODC**,
are simulated with `VmGuestInstant`s and `Duration`s rather than by
repeated incrementation. (`VmGuestInstant` is a new type defined in
this change with a similar interface to `std::time::Instant`, but
using timestamps provided by the VMM.)

Migration
---------

The types defined for serializing the device state are admittedly
undercooked; advice about what a cleaner approach could look like
before committing to the 'V1' of the format are quite welcome.

DTrace support
==============

To see a trace of all MMIO register reads/writes and TRB
enqueue/dequeues:

```sh
pfexec ./scripts/xhci-trace.d -p $(pgrep propolis-server)
```

The name of each register as used by DTrace is `&'static`ally defined in
`registers::Registers::reg_name`.

Author: lif

Cargo.lock

@@ -42,6 +42,7 @@ use propolis::hw::qemu::{
     ramfb,
 };
 use propolis::hw::uart::LpcUart;
+use propolis::hw::usb::xhci;
 use propolis::hw::{nvme, virtio};
 use propolis::intr_pins;
 use propolis::vmm::{self, Builder, Machine};
@@ -98,6 +99,9 @@ pub enum MachineInitError {
     #[error("failed to specialize CPUID for vcpu {0}")]
     CpuidSpecializationFailed(i32, #[source] propolis::cpuid::SpecializeError),
 
+    #[error("xHC USB root hub port number invalid: {0}")]
+    UsbRootHubPortNumberInvalid(String),
+
     #[cfg(feature = "falcon")]
     #[error("softnpu p9 device missing")]
     SoftNpuP9Missing,
@@ -814,6 +818,45 @@ impl MachineInitializer<'_> {
         Ok(())
     }
 
+    /// Initialize xHCI controllers, connect any USB devices given in the spec,
+    /// add them to the device map, and attach them to the chipset.
+    pub fn initialize_xhc_usb(
+        &mut self,
+        chipset: &RegisteredChipset,
+    ) -> Result<(), MachineInitError> {
+        for (xhc_id, xhc_spec) in &self.spec.xhcs {
+            info!(
+                self.log,
+                "Creating xHCI controller";
+                "pci_path" => %xhc_spec.pci_path,
+            );
+
+            let log = self.log.new(slog::o!("dev" => "xhci"));
+            let bdf: pci::Bdf = xhc_spec.pci_path.into();
+            let xhc = xhci::PciXhci::create(self.machine.hdl.clone(), log);
+
+            for (usb_id, usb) in &self.spec.usbdevs {
+                if *xhc_id == usb.xhc_device {
+                    info!(
+                        self.log,
+                        "Attaching USB device";
+                        "usb_id" => %usb_id,
+                        "xhc_pci_path" => %xhc_spec.pci_path,
+                        "usb_port" => %usb.root_hub_port_num,
+                    );
+                    xhc.add_usb_device(usb.root_hub_port_num).map_err(
+                        MachineInitError::UsbRootHubPortNumberInvalid,
+                    )?;
+                }
+            }
+
+            self.devices.insert(xhc_id.clone(), xhc.clone());
+            chipset.pci_attach(bdf, xhc);
+        }
+
+        Ok(())
+    }
+
     #[cfg(feature = "failure-injection")]
     pub fn initialize_test_devices(&mut self) {
         use propolis::hw::testdev::{

bin/propolis-server/src/lib/initializer.rs

@@ -5,7 +5,7 @@
 //! Conversions from version-0 instance specs in the [`propolis_api_types`]
 //! crate to the internal [`super::Spec`] representation.
 
-use std::collections::BTreeMap;
+use std::collections::{BTreeMap, BTreeSet};
 
 use propolis_api_types::instance_spec::{
     components::{
@@ -44,6 +44,9 @@ pub(crate) enum ApiSpecError {
     #[error("network backend {backend} not found for device {device}")]
     NetworkBackendNotFound { backend: SpecKey, device: SpecKey },
 
+    #[error("USB host controller {xhc} not found for device {device}")]
+    HostControllerNotFound { xhc: SpecKey, device: SpecKey },
+
     #[allow(dead_code)]
     #[error("support for component {component} compiled out via {feature}")]
     FeatureCompiledOut { component: SpecKey, feature: &'static str },
@@ -61,6 +64,8 @@ impl From<Spec> for InstanceSpecV0 {
             cpuid,
             disks,
             nics,
+            xhcs,
+            usbdevs,
             boot_settings,
             serial,
             pci_pci_bridges,
@@ -121,6 +126,14 @@ impl From<Spec> for InstanceSpecV0 {
             );
         }
 
+        for (id, xhc) in xhcs {
+            insert_component(&mut spec, id, ComponentV0::Xhci(xhc));
+        }
+
+        for (id, usb) in usbdevs {
+            insert_component(&mut spec, id, ComponentV0::UsbPlaceholder(usb));
+        }
+
         for (name, desc) in serial {
             if desc.device == SerialPortDevice::Uart {
                 insert_component(
@@ -230,6 +243,7 @@ impl TryFrom<InstanceSpecV0> for Spec {
             BTreeMap::new();
         let mut dlpi_backends: BTreeMap<SpecKey, DlpiNetworkBackend> =
             BTreeMap::new();
+        let mut xhci_controllers: BTreeSet<SpecKey> = BTreeSet::new();
 
         for (id, component) in value.components.into_iter() {
             match component {
@@ -249,6 +263,10 @@ impl TryFrom<InstanceSpecV0> for Spec {
                 ComponentV0::DlpiNetworkBackend(dlpi) => {
                     dlpi_backends.insert(id, dlpi);
                 }
+                ComponentV0::Xhci(xhc) => {
+                    xhci_controllers.insert(id.to_owned());
+                    builder.add_xhci_controller(id, xhc)?;
+                }
                 device => {
                     devices.push((id, device));
                 }
@@ -365,6 +383,19 @@ impl TryFrom<InstanceSpecV0> for Spec {
                 ComponentV0::P9fs(p9fs) => {
                     builder.set_p9fs(p9fs)?;
                 }
+                ComponentV0::Xhci(xhci) => {
+                    builder.add_xhci_controller(device_id, xhci)?;
+                }
+                ComponentV0::UsbPlaceholder(usbdev) => {
+                    if xhci_controllers.contains(&usbdev.xhc_device) {
+                        builder.add_usb_device(device_id, usbdev)?;
+                    } else {
+                        return Err(ApiSpecError::HostControllerNotFound {
+                            xhc: usbdev.xhc_device.to_owned(),
+                            device: device_id,
+                        });
+                    }
+                }
                 ComponentV0::CrucibleStorageBackend(_)
                 | ComponentV0::FileStorageBackend(_)
                 | ComponentV0::BlobStorageBackend(_)

bin/propolis-server/src/lib/spec/api_spec_v0.rs

@@ -9,7 +9,7 @@ use std::collections::{BTreeSet, HashSet};
 use propolis_api_types::instance_spec::{
     components::{
         board::Board as InstanceSpecBoard,
-        devices::{PciPciBridge, SerialPortNumber},
+        devices::{PciPciBridge, SerialPortNumber, UsbDevice, XhciController},
     },
     PciPath, SpecKey,
 };
@@ -65,13 +65,17 @@ pub(crate) enum SpecBuilderError {
 
     #[error("failed to read default CPUID settings from the host")]
     DefaultCpuidReadFailed(#[from] cpuid_utils::host::GetHostCpuidError),
+
+    #[error("a USB device is already attached to xHC {0} root hub port {1}")]
+    UsbPortInUse(SpecKey, u8),
 }
 
 #[derive(Debug, Default)]
 pub(crate) struct SpecBuilder {
     spec: super::Spec,
     pci_paths: BTreeSet<PciPath>,
     serial_ports: HashSet<SerialPortNumber>,
+    xhc_usb_ports: BTreeSet<(SpecKey, u8)>,
     component_names: BTreeSet<SpecKey>,
 }
 
@@ -154,6 +158,23 @@ impl SpecBuilder {
         }
     }
 
+    fn register_usb_device(
+        &mut self,
+        usbdev: &UsbDevice,
+    ) -> Result<(), SpecBuilderError> {
+        // slightly awkward: we have to take a ref of an owned tuple for
+        // .contains() below, and in either case we need an owned SpecKey,
+        // so we'll just clone it once here
+        let xhc_and_port =
+            (usbdev.xhc_device.to_owned(), usbdev.root_hub_port_num);
+        if self.xhc_usb_ports.contains(&xhc_and_port) {
+            Err(SpecBuilderError::UsbPortInUse(xhc_and_port.0, xhc_and_port.1))
+        } else {
+            self.xhc_usb_ports.insert(xhc_and_port);
+            Ok(())
+        }
+    }
+
     /// Adds a storage device with an associated backend.
     pub(super) fn add_storage_device(
         &mut self,
@@ -355,6 +376,26 @@ impl SpecBuilder {
         Ok(self)
     }
 
+    pub fn add_xhci_controller(
+        &mut self,
+        device_id: SpecKey,
+        xhc: XhciController,
+    ) -> Result<&Self, SpecBuilderError> {
+        self.register_pci_device(xhc.pci_path)?;
+        self.spec.xhcs.insert(device_id, xhc);
+        Ok(self)
+    }
+
+    pub fn add_usb_device(
+        &mut self,
+        device_id: SpecKey,
+        usbdev: UsbDevice,
+    ) -> Result<&Self, SpecBuilderError> {
+        self.register_usb_device(&usbdev)?;
+        self.spec.usbdevs.insert(device_id, usbdev);
+        Ok(self)
+    }
+
     /// Yields the completed spec, consuming the builder.
     pub fn finish(self) -> super::Spec {
         self.spec

bin/propolis-server/src/lib/spec/builder.rs

@@ -26,7 +26,7 @@ use propolis_api_types::instance_spec::{
         board::{Chipset, GuestHypervisorInterface, I440Fx},
         devices::{
             NvmeDisk, PciPciBridge, QemuPvpanic as QemuPvpanicDesc,
-            SerialPortNumber, VirtioDisk, VirtioNic,
+            SerialPortNumber, UsbDevice, VirtioDisk, VirtioNic, XhciController,
         },
     },
     v0::ComponentV0,
@@ -66,6 +66,8 @@ pub(crate) struct Spec {
     pub cpuid: CpuidSet,
     pub disks: BTreeMap<SpecKey, Disk>,
     pub nics: BTreeMap<SpecKey, Nic>,
+    pub xhcs: BTreeMap<SpecKey, XhciController>,
+    pub usbdevs: BTreeMap<SpecKey, UsbDevice>,
     pub boot_settings: Option<BootSettings>,
 
     pub serial: BTreeMap<SpecKey, SerialPort>,

bin/propolis-server/src/lib/spec/mod.rs

@@ -563,6 +563,7 @@ async fn initialize_vm_objects(
         &properties,
     ))?;
     init.initialize_network_devices(&chipset).await?;
+    init.initialize_xhc_usb(&chipset)?;
 
     #[cfg(feature = "failure-injection")]
     init.initialize_test_devices();

bin/propolis-server/src/lib/vm/ensure.rs

@@ -1274,6 +1274,13 @@ fn setup_instance(
                     block::attach(nvme.clone(), backend).unwrap();
                     chipset_pci_attach(bdf, nvme);
                 }
+                "pci-xhci" => {
+                    let log = log.new(slog::o!("dev" => "xhci"));
+                    let bdf = bdf.unwrap();
+                    let xhci = hw::usb::xhci::PciXhci::create(hdl.clone(), log);
+                    guard.inventory.register_instance(&xhci, &bdf.to_string());
+                    chipset_pci_attach(bdf, xhci);
+                }
                 qemu::pvpanic::DEVICE_NAME => {
                     let enable_isa = dev
                         .options

bin/propolis-standalone/src/main.rs

@@ -190,6 +190,33 @@ pub struct P9fs {
     pub pci_path: PciPath,
 }
 
+/// Describes a PCI device implementing the eXtensible Host Controller Interface
+/// for the purpose of attaching USB devices.
+///
+/// (Note that at present no functional USB devices have yet been implemented.)
+#[derive(Clone, Deserialize, Serialize, Debug, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct XhciController {
+    /// The PCI path at which to attach the guest to this xHC.
+    pub pci_path: PciPath,
+}
+
+/// Describes a USB device, requires the presence of an XhciController.
+///
+/// (Note that at present no USB devices have yet been implemented
+/// outside of a null device for testing purposes.)
+#[derive(Clone, Deserialize, Serialize, Debug, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct UsbDevice {
+    /// The name of the xHC to which this USB device shall be attached.
+    pub xhc_device: SpecKey,
+    /// The root hub port number to which this USB device shall be attached.
+    /// For USB 2.0 devices, valid values are 1-4, inclusive.
+    /// For USB 3.0 devices, valid values are 5-8, inclusive.
+    pub root_hub_port_num: u8,
+    // TODO(lif): a field for device type (e.g. HID tablet, mass storage...)
+}
+
 /// Describes a synthetic device that registers for VM lifecycle notifications
 /// and returns errors during attempts to migrate.
 ///

crates/propolis-api-types/src/instance_spec/components/devices.rs

@@ -27,6 +27,8 @@ pub enum ComponentV0 {
     SoftNpuPort(components::devices::SoftNpuPort),
     SoftNpuP9(components::devices::SoftNpuP9),
     P9fs(components::devices::P9fs),
+    Xhci(components::devices::XhciController),
+    UsbPlaceholder(components::devices::UsbDevice),
     MigrationFailureInjector(components::devices::MigrationFailureInjector),
     CrucibleStorageBackend(components::backends::CrucibleStorageBackend),
     FileStorageBackend(components::backends::FileStorageBackend),

crates/propolis-api-types/src/instance_spec/v0.rs

@@ -97,6 +97,10 @@ impl Device {
     pub fn get<T: FromStr, S: AsRef<str>>(&self, key: S) -> Option<T> {
         self.get_string(key)?.parse().ok()
     }
+
+    pub fn get_integer<S: AsRef<str>>(&self, key: S) -> Option<i64> {
+        self.options.get(key.as_ref())?.as_integer()
+    }
 }
 
 #[derive(Debug, Deserialize, Serialize, PartialEq)]