Updates to address issues 52 through 58 (chapter 5)

specification/Makefile

@@ -8,6 +8,7 @@ build:
 	@echo "Building asciidoc"
 	asciidoctor-pdf \
     --trace \
+    --attribute=allow-uri-read \
     --attribute=mathematical-format=svg \
     --attribute=pdf-fontsdir=docs-resources/fonts \
     --attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \

specification/appendix_c.adoc

@@ -0,0 +1,8 @@
+[[appendix_c]]
+== Appendix C: Nested virtualization based deployment model
+
+[id=dep2]
+[caption="Figure {counter:image}"]
+[title= ": Nested virtualization based deployment model for CoVE"]
+image::img_10.png[align=center]
+

specification/header.adoc

@@ -71,4 +71,5 @@ include::swlifecycle.adoc[]
 include::sbi_cove.adoc[]
 include::appendix_a.adoc[]
 include::appendix_b.adoc[]
+include::appendix_c.adoc[]
 include::bibliography.adoc[]

specification/overview.adoc

@@ -27,11 +27,12 @@ resources and platform capabilities to host the TVM workload. The terms
 hosting supervisor domain and OS/VMM are used interchangeably in this
 specification.
 
-[caption="Figure {counter:image}: ", reftext="Figure {image}"]
-[title= "TCB Isolation for VM workloads using Supervisor Domains"]
+[id=dep1]
+[caption="Figure {counter:image}", reftext="Figure {image}"]
+[title= ": TCB Isolation for VM workloads using Supervisor Domains"]
 image::img_0.png[]
 
-As shown in figure 1, the Confidential Supervisor Domain is managed by software
+As shown in <<dep1>>, the Confidential Supervisor Domain is managed by software
 that operates in HS-mode and manages resources granted to it by the Hosting
 Supervisor Domain Manager (the OS/VMM). The Confidential Supervisor Domain
 Manager is called the " *TEE Security Manager* " or *(TSM)* - it acts as the
@@ -81,7 +82,7 @@ TVMs may be hosted by the host OS/VMM via confidential supervisor domains.
 Each TVM may consist of the guest firmware, a guest OS and applications. The
 software components included in the TVM are implementation specific.
 
-As shown in figure 1, the M-mode firmware TSM-driver is in the TCB of all
+As shown in <<dep1>>, the M-mode firmware TSM-driver is in the TCB of all
 Supervisor domains and hence in the TCB for all CoVE workloads hosted on the
 platform. The TSM-driver (operating in M-mode) uses
 the hardware capabilities to provide:
@@ -137,9 +138,9 @@ state save and restore,  as well as enforcing invariants for memory assigned
 to the TVM (including G-stage translation). The host OS/VMM provides the
 typical VM resource management functionality for memory, IO etc.
 
-Confidential VMs (under a VMM) are shown in figure 1 and Confidential
+Confidential VMs (under a VMM) are shown in <<dep1>> and Confidential
 applications (managed by an untrusted host OS) are shown in the
-architecture figure 2. As evident from the architecture, the difference
+architecture <<dep1a>>. As evident from the architecture, the difference
 between these two scenarios is the software TCB (owned by the tenant within
 the TVM) for the tenant workload - in the application TEE case, a minimal
 guest runtime may be used; whereas in the VM TEE case, an enlightened
@@ -148,8 +149,9 @@ modes of operation are also possible as TEE workloads. Importantly, the HW
 mechanisms needed for both cases are identical, and can be supported with the
 CoVE ABI.
 
-[caption="Figure {counter:image}: ", reftext="Figure {image}"]
-[title= "TEE TCB for application workloads (hosted via a TVM)"]
+[id=dep1a]
+[caption="Figure {counter:image}", reftext="Figure {image}"]
+[title= ": TEE TCB for application workloads (hosted via a TVM)"]
 image::img_1.png[]
 
 The detailed architecture is described in the Section <<refarch>>. Note that the

specification/refarch.adoc

@@ -16,28 +16,32 @@ phases: the conversion of memory to confidential memory and the assignment of
 confidential memory (alongwith the enforcement of properties on use) to TVMs.
 To enforce isolation across Host and Confidential supervisor domains, CoVE
 requires isolation of physical memory (that supports paging when enabled). There
-are two deployment models possible here. CoVE ABI is equally applicable for both
-modes - this specification focusses on the second deployment model (b) where a
-peer supervisor domain is used to host confidential workloads.
+are two deployment models described below (1,2). CoVE ABI is applicable for both
+modes - this specification focuses on the first deployment model (1) where a
+primary host supervisor domain is used to host confidential workloads in a
+secondary confidential domain.
 
-a. When the TSM is the only root HS mode component on the platform, the G-stage
-page table can be used to enforce isolation between confidential TVMs and
+. The TSM operates in S/HS mode as a peer supervisor domain manager to the
+hosting supervisor domain which operates in S/HS mode as well. This model uses
+the MTT along with G-stage PT for confidential TVM isolation (where 1st
+stage PT is used by the Guest OS normally). The MTT is used to assign physical
+memory to the Confidential supervisor domain called *Confidential* memory and
+memory accessible to the hosting supervisor domain called *Non-Confidential*.
+MTT allows dynamic programming of the per-domain access permissions. This model
+is shown in <<dep1>>
+
+. The TSM is the only root HS mode component on the platform, hence, G-stage
+page tables can be used to enforce isolation between confidential TVMs and
 ordinary VMs. In this model the host VMM must execute in the de-privileged VS
 mode and the TSM must provide nested virtualization of the H-extension controls.
-This model may be suitable for client/embedded systems.
+This model may be suitable for client/embedded systems and is shown in <<dep2>>.
 
-b. The TSM operates in S/HS mode as a peer supervisor domain manager to the
-hosting supervisor domain which operates in S/HS mode as well. This model uses
-the MTT along with G-stage PT for confidential TVM isolation (where 1st
-stage PT is used by the Guest OS normally). The MTT
-is used to assign physical memory to the Confidential supervisor domain called
-*Confidential* memory and memory accessible to the hosting supervisor domain
-called *Non-Confidential*. MTT allows dynamic programming of the per-domain
-access permissions. A TVM and/or TSM needs to access both types of memory:
+A TVM and/or TSM needs to access both types of memory:
 
-* Confidential memory - used for TVM code, data
-* Non-confidential memory - used for communication between TVM and the non-TCB
-host software and/or non-TCB IO devices.
+* Confidential memory - used for TVM/TSM code and security-sensitive data;
+including state such as 1st-stage, G-stage page tables.
+* Non-confidential memory - used only for shared data, e.g. communication
+between the TVM/TSM and the non-TCB host software and/or non-TCB IO devices.
 
 The TSM COVH ABI provides interfaces to the OS/VMM to convert / donate
 memory from the hosting supervisor domain to the confidential supervisor domain.
@@ -57,6 +61,12 @@ permissions to access Confidential and Non-confidential memory
 * Hart not operating in a Confidential supervisor domain has access permissions
 only for Non-confidential memory
 
+The RDSM configures the MTT such that a hart executing in the hosting domain
+does not have access to any confidential memory regions. The RDSM configures the
+MTT for the confidential domain to allow access to confidential memory
+exclusively to that domain, but may also allow access to non-confidential
+(shared) memory regions to one or more secondary domains.
+
 [caption="Figure {counter:image}: ", reftext="Figure {image}"]
 [title= "Confidential memory conversion"]
 image::img_7.png[]
@@ -70,12 +80,13 @@ unique memory encryption key. These additional protection aspects are platform
 and implementation dependent.
 ====
 
-Confidential and non-confidential memory are both always assigned by the VMM -
-the TSM and TSM-driver are expected to manage the isolation for confidential
-memory by programming the Memory Tracking Table (MTT). The desired security
-properties of memory tracking are discussed below. The TSM manages
-finer-granular (page-based) allocation from confidential memory regions
-(enforced by the memory tracking hardware) using the G-stage page table.
+Confidential and non-confidential memory are both always assigned by the VMM
+i.e. the hosting supervisor domain - the TSM-driver is expected to manage the
+isolation for confidential memory assigned to any of the secondary supervisor
+domains by programming the Memory Tracking Table (MTT). The desired security
+properties of memory tracking are discussed below. The TSM (within a supervisor
+domain) manages page-based allocation using the G-stage page table from the set
+of confidential memory regions that are enforced by the memory tracking table.
 
 Four aspects of memory isolation are impacted due to this dynamic configurable
 property of the MTT:
@@ -88,9 +99,9 @@ supervisor domain to get the access permissions for the physical address. This
 lookup should be performed for each implicit and explicit memory access and per
 the paging sizes/modes supported by the hart.
 
-[caption="Figure {counter:image}: ", reftext="Figure {image}"]
+[caption="Figure {counter:image}: ", reftext="smmtt"]
 [title= "Memory Tracking for Supervisor Domains"]
-image::img_8.png[]
+image::https://github.com/riscv/riscv-smmtt/blob/main/images/fig2.png?raw=true[]
 
 ==== Management of isolation for Confidential Physical Memory
 
@@ -141,6 +152,17 @@ by the host for another TVM or VM or the host).
 These properties are implemented by the TSM in conjunction with
 the HW (e.g. MTT cache invalidations) via the proposed COVH interface.
 
+[NOTE]
+====
+Regarding stale data in memory: If the TVM is gracefully shutdown, it may scrub
+its confidential memory. If the TVM is not gracefully shutdown, or the host is
+reclaiming memory assigned to a TVM, the TSM must perform scrubbing of
+confidential memory before returning control of the memory to the host (via the
+MTT) or assigning to another TVM. If the TVM is converting memory from
+confidential to non-confidential, then the TVM must scrub the confidential
+memory being returned to the host via `sbi_covg_share_memory_region`.
+====
+
 === TSM initialization
 
 The CoVE architecture requires a hardware Root-of-trust for supporting
@@ -319,9 +341,9 @@ M-mode CSR `mttp` to disable non-TCB accesses to confidential memory.)
 (THCS.hssa.pc adjusted to refer to opcode after the ECALL that triggered
 the TEECALL / TEERESUME)
 
-The TSM is stateless across TEECALL invocations, however a security routine
-invoked in the TSM via a TEECALL may be interrupted and must be resumed via
-a TEERESUME i.e. _the TSM is preemptable but non-reentrant_. These
+The TSM-driver is stateless across TEECALL invocations, however a security
+routine invoked in the TSM via a TEECALL may be interrupted and must be resumed
+via a TEERESUME i.e. _the TSM is preemptable but non-reentrant_. These
 properties are enforced by the TSM-driver, and other models described above
 may be implemented. The TSM does not perform any dynamic resource
 management, scheduling, or interrupt handling of its own. The TSM is not
@@ -395,13 +417,13 @@ and the TSM-driver.
 There are two facets of TVM and TSM memory isolation that are
 implementation-specific:
 
-*a)* *Isolation from host software access* -  For the deployment model (a),
+*a)* *Isolation from host software access* -  For the deployment model 2,
 the CPU must enforce hardware-based access-control of TSM memory via
 the G-stage page tables to prevent the guest VMM from accessing TSM
-memory. For the deployment model (b). The CPU must also similarly enforce
+memory. For the deployment model 1, the CPU must also similarly enforce
 access-control of TSM memory to prevent access from host supervisor
 domain components (VMM and host OS that operate in V=0, HS-mode) software.
-Since in this deployment model (b), other supervisor domains have access to 1st
+Since in this deployment model, other supervisor domains have access to 1st
 and G-stage paging hardware, the root security manager (TSM-driver) must use MTT
 to isolate supervisor domain memory. In this deployment model,
 TEE and TVM address spaces are identified by supervisor domain identifiers