specification: CoVE-IO theory of operations

Describe CoVE-IO ABI operations, including platform setup, device
initialization and interface assignment.

Signed-off-by: Samuel Ortiz <[email protected]>

specification/coveio_abi.adoc

@@ -1,2 +1,34 @@
 [[coveio_abi]]
 == Confidential VM Extension (CoVE) IO ABI
+
+=== CoVE IO Host Extension
+
+[#sbi_covh_register_iommu()]
+=== Function: COVE IO Host IOMMU Registration (FID TBD)
+[source, C]
+-----
+struct sbiret sbi_covh_register_iommu(unsigned long iommu_id,
+                                      unsigned long msi_cfg[3]);
+-----
+
+[#sbi_covh_notify_iommu_msi()]
+=== Function: COVE IO Host IOMMU MSI notification (FID TBD)
+[source, C]
+-----
+struct sbiret sbi_covh_notify_iommu_msi(unsigned long iommu_id);
+-----
+
+[#sbi_covh_register_rp()]
+=== Function: COVE IO Host PCIe Root Port Registration (FID TBD)
+[source, C]
+-----
+struct sbiret sbi_covh_register_rp(unsigned long rp_id,
+                                   unsigned long mmio_ranges);
+----
+
+[#sbi_covh_create_spdm_session()]
+=== Function: COVE IO Host SPDM Session Creation (FID TBD)
+[source, C]
+-----
+struct sbiret sbi_covh_create_spdm_session()(unsigned long id);
+----

specification/glossary.adoc

@@ -29,6 +29,12 @@ computation in a Hardware-based TEE.
 | Confidential VM Extension | CoVE | A set of non-ISA RISC-V extensions that
 enables confidential computing on RISC-V platforms.
 
+| CoVE Guest SBI Extension | COVG | CoVE SBI extensions serviced by the TSM
+and called by TVMs.
+
+| CoVE Host SBI Extension | COVH | CoVE SBI extensions serviced by the TSM
+and called by host software components.
+
 | Device Interface | DI | TDISP term, Device Interface. Same as a TDI. A DI can
 be a Virtual Function (VF) or a Physical Function (PF).
 
@@ -94,6 +100,8 @@ Function (PF).
 (in TCB) intermediary between the VMM and the TVM. This module extends the TCB
 chain on the CoVE platform.
 
+| Transaction Layer Packet | TLP |
+
 | Trusted Computing Base | TCB | The hardware, software and firmware elements
 that are trusted by a relying party to protect the confidentiality and integrity
 of the relying parties' workload data and execution against a defined adversary

specification/theory_operations.adoc

@@ -1,2 +1,118 @@
 [[theory_operations]]
+
 == Theory of Operations
+
+The CoVE-IO specification extends the CoVE host and guest SBI extensions to
+allow TVMs to establish trust with TEE-IO devices, and then use and interact
+with those devices. Untrusted domain components are responsible for assigning
+TEE-IO devices to TVMs, and also for supporting the TVM acceptance or rejection
+of the assigned devices. The TSM, on the other hand, establishes and maintains
+the secure physical and logical links between TVMs and their assigned devices.
+
+The following sections describe the functionality of the TSM provided CoVE-IO
+extensions to support trusted I/O on CoVE enabled platforms.
+
+=== Platform Initialization
+
+==== IOMMU Registration and Setup
+
+The TSM relies on the availability of at least one IOMMU instance exclusvely
+associated with the TSM trusted domain. Those IOMMUs allow the TSM to perform
+address translations and protection from DMA and interrupts originating from
+assigned TDIs. The trusted domain IOMMU instances must be only visible and
+programmable by the TSM
+
+Trusted domain assigned IOMMUs can generate MSIs in order to signal the TSM
+about command completions, transaction faults or device page requests. Those
+MSIs target system physical memory, which is owned by the untrusted domain
+manager. As a consequence, it is the untrusted domain responsibility to reserve
+the MSI addresses and then rely on the TSM to program the IOMMUs with those
+reserved addresses. This is the IOMMU registration process, driven by the VMM
+for all IOMMUs that participate in TEE-IO and it goes as follows:
+
+1. The TSM is loaded.
+2. The untrusted domain manager (e.g. the host VMM) enumerates all platform
+   IOMMUs as PCIe devices.
+3. The untrusted IOMMU driver is loaded and probed.
+4. The untrusted IOMMU driver allocates MSI vectors for the trusted domain
+   IOMMUs. Those vectors must point to the untrusted IOMMU driver as the TSM can
+   not handle external interrupts.
+5. The untrusted domain manager registers the IOMMUs with the TSM by calling
+   into the `sbi_covh_register_iommu()` COVH function. The TSM gets the
+   allocated MSI vectors and configures the trusted IOMMU `s_msi_cfg_table`
+   register accordingly.
+6. When a trusted IOMMU sends an MSI, the untrusted IOMMU driver handles it and
+   notifies the TSM about a pending trusted IOMMU MSI by calling the
+   `sbi_covh_notify_iommu_msi()` COVH function.
+7. The TSM verifies that there is a pending MSI by reading the IOMMU `s_ipsr`
+   register, and handles the interrupts as needed.
+
+The untrusted driver can trick the TSM by either invoking the
+`sbi_covh_notify_iommu_msi()` COVH function while there are no pending MSI from
+the trusted IOMMU or not invoking it when there actually is one such pending
+interrupt. In the former case, the TSM can verify that there really is a pending
+MSI by checking the trusted IOMMU status registers. The latter case could cause
+a denial of service, which is not covered by the confidential computing threat
+model. If the TSM must ensure that a given command is completed without having
+to rely on untrusted IOMMU driver MSI notifications, it can queue an `IOFENCE.C`
+command after the desired command and check for the cqh advancing past the
+`IOFENCE.C` command index.
+
+==== PCIe Root Port Registration
+
+When the data link between the TDI and the TVM must be secured, trusted I/O
+relies on the PCIe IDE protocol. IDE provides confidentiality and integrity
+protection for TLPs received and transmitted between the physical device the TDI
+belongs to and its assigned PCIe root port (RP). Both endpoints (The RP and the
+physical device) must be configured with the same encryption keys through the
+IDE key management protocols and have their IDE PCIe extended capability
+configured as well.
+
+As described in the threat model and requirement sections, the the following
+trusted I/O rules apply:
+
+* As PCIe switches are outside of the TVM TCB, only selective IDE streams are
+  used to protect the PCIe link between the TVM and the TDI.
+* A single selective IDE stream is established between the TSM and the physical
+  device. All TDIs from the physical device share this single IDE stream.
+* For each physical device from which a TDI is attached to a TVM, the TSM
+  generates, owns and distributes the IDE stream keys to both the physical
+  device and the RP.
+* The TSM configures the RP PCIe IDE extended capability.
+
+As the TSM is responsible for setting both the RP IDE keys and PCI IDE
+capabilities, it must be the IDE operations owner for any downstream device for
+a given RP. As the overall platform resources owner, the untrusted domain
+software stack must register a RP for TEE I/O and IDE ownership with the TSM, by
+calling the `sbi_covh_register_rp()` COVH function. This function associates a
+RP id to its MMIO space (for the IDE capability configurations) and all the MMIO
+ranges that are routed through it. The TSM must compare these 2 arguments with
+the information it received from the platform RoT through the TEE I/O manifest.
+If both match, it can proceed into establishing an SPDM session with the RP.
+
+===== SPDM Session
+
+For each TDI that gets attached to a TVM, its corresponding PCIe root port must
+be configured with per-device IDE keys. This configuration is done through the
+PCIe IDE key management protocol (IDE_KM) that runs on top of an SPDM session.
+It is thus necessary to establish an SPDM session with all trusted I/O
+registered root ports. This is akin to considering the RP as just another
+trusted device for which the DSM is the platform RoT. The SPDM establishment
+thus happens between the TSM and the platform RoT. By having the RoT playing the
+RP DSM role, the RP vendor-specific IDE key management interface is abstracted
+by the RoT.
+
+After the untrusted domain manager successfully registers a root port with the
+TSM, it requests the TSM to establish a secured SPDM session with it by calling
+the COVH `sbi_covh_create_spdm_session()` function. The same function is used
+for establishing SPDM sessions with PCIe root ports and physical devices acting
+as SPDM responders. The Secured SPDM Session section describes the protocol
+followed by the TSM and the SPDM responder to establish this secured session.
+
+==== SPDM Flow
+
+==== Secure SPDM Session
+
+=== Device Initialization
+
+=== Interface Assignment