initial adoc format of draft spec v0.51

bibliography.adoc

@@ -1,4 +1,4 @@
 [bibliography]
 == Bibliography
 
-bibliography::[]
+

chapter2.adoc

@@ -1,47 +1,27 @@
 [[chapter2]]
-== The Second Chapter
+== Semantics and Security Properties
 
-. The first item.
+The Supervisor Domain Access Protection extension (Smmtt) specifies if a physically addressed memory or device mapped region is accessible (read, write) by a particular supervisor domain (or not). Associating a memory region with a supervisor domain via Smmtt implies that the physical addressable region is accessible only from software or hardware access occurring in the context of the owner supervisor domain. Hence, software or hardware accesses that originate from other supervisor domains outside the owner supervisor domain are prevented by hardware. The RDSM has access to all supervisor domains.
 
-. The second item.
-+
-.. The first sub item.
+In order to enforce these properties, the following architecture interfaces are required: 
 
-.. The second sub item.
-+
-[CAUTION]
-====
-A moment of caution is required for this block of text must be read and apreciated for its importance.
-====
+* An interface to signal the active supervisor domain under which a hart is operating. This is a dynamic control state on the hart that can be held in an M-mode CSR and modifiable by the RDSM via the CSR r/w instructions  - herewith called the supervisor domain identifier assigned to the hart. Domains are orthogonal to privilege levels within the supervisor domain and since Smmtt enables physical memory isolation, there is one CSR (per hart) managed by the M-mode. Similarly for devices, a supervisor domain identifier may be assigned to the device to signify assignment - A cross-reference to the IO supervisor domain will be added in the future; Isolation of data within a device is out of scope of this specification.
 
-. Yet another item.
+* An interface to set the access permissions for a memory region or page associated with a supervisor domain. This interface allows dynamic changes of association (which may require appropriate flushing of any state cached in harts). The association mapping is programmed via an Memory Tracking Table (MTT) structure, accessed via per-hart M-mode CSRs and which may be backed by additional in-memory structures. The M-mode CSR interface is expected to program the root physical page (MTTPPN) - for when the MTT is a memory-based structure, the MTTPPN would hold the physical address of the root page of the MTT structure in memory - the MTT is expected to be memory resident at time of access. Write access to MTT structures must be restricted by and to the RDSM (except for when explicitly allowed by the RDSM). Privilege levels may affect changes in the MTT under purview of the Supervisor Domain Security Manager (SDSM) either through an SBI interface into M-mode (or may have the ability to edit MTT structures by virtue of how the MTT structure in memory is accessible to lower privilege levels). 
 
-. Again, an item.
+* MTT checker - this functional block looks up the MTT using the physical address of the access as an index to retrieve the access permissions for the supervisor domain. This checker thus enforces that for a load initiated by the hart, the physical address is readable, and for a store initiated by the hart, the physical address is also writable, else reports a fault. An access violation is reported as a trap to the M-mode Root domain security manager, and the access is disallowed with no data divulged. This checker may be implemented as an MMU extension in the hart. The MTT checker is designed to work together with the page-based virtual memory (MMU) systems and Physical Memory Protection (PMP) mechanism. Read and Write permissions for memory are derived from the page table, the PMP and the MTT - an access is allowed only when all protection mechanisms allow the access. When paging is enabled, instructions that access virtual memory may result in multiple physical-memory accesses, including (implicit S-mode) accesses to the page tables. MTT checks also apply to these implicit accesses - those accesses will be treated as reads for translation and as writes when A/D bits are updated in page table entries for Svadu is implemented). 
 
-.. A multi-line item.
-+
-This item has multiple lines.
-+
-By multiple lines, this is what we mean.
-+
-Seriously, multiple.
+* Physical address metadata selector - To support IO/memory sharing, a hart/device may perform accesses to memory exclusively accessible to its supervisor domain, and to memory shared globally with all supervisor domains or other specific supervisor domains. Memory sharing between supervisor domains is achieved by simply making the physical memory region accessible to the supervisor domains via the MTT structure. Access to physical addresses initiated from a hart or a device that is initialized with an MTT in non-Bare mode and valid supervisor domain identifier may be denied by virtue of the permissions in the MTT lookup - such disallowed accesses cause a trap to the RDSM to report a fault. When access to shared memory is allowed by the MTT, it may need to be additionally qualified to enforce downstream security-controls. To achieve this, a physical address metadata selector may be provided as part of the access. The possible metadata are specified in N(16?) of MXLEN bit CSRs per hart. The metadata that is associated with the accessed physical address is selected via a 4-bit physical address metadata selector field programmed into the S-mode or G-stage page table leaf entry traversed as part of the address translation. The domain workload is expected to manage the S-mode page table selectors, and the SDSM is expected to manage the G-stage page table entry selectors.
 
-=== An example table
+Additional protection/isolation for memory associated with a supervisor domain is orthogonal (and usage-specific). Such additional protection for memory may be derived by the use of cryptography and/or access-control mechanisms. The mechanisms chosen for these additional protection methods are independent of Smmtt and may be platform-specific, though they may utilize the physical address metadata selected during the access. The TCB of a particular supervisor domain may be independently evaluated via attestation of the HW and SW TCB by a relying party using standard Public-Key Infrastructure-based mechanisms.
 
-[cols="^1,^1,^1,^1,^3,^3",stripes=even,options="header"]
-|===
-4+|Letters _and_ bits {set:cellbgcolor:green} 2+|A much longer area
-|L|R|W|X|Quarter 1|Quarter 2
-|{set:cellbgcolor:!} 0|0|0|0 2+|Rows alternate colors
-|0|0|0|1|Thing 1|Thing 2
-|1|0|0|0|Thing 3|Thing 4
-|1|1|1|1 2+|Span Thing 1 and 2
-|===
+Memory regions may be accessed by harts or by other devices on the platform. When harts and devices are assigned to a supervisor domain, the hart/device is said to perform memory accesses in the context of that supervisor domain. For all accesses using a physical address, the SDID is the supervisor domain identifier programmed into a CSR.  This CSR is programmed on the hart by the Root Domain Security Manager (RDSM). The assignment of the hart/device to a supervisor domain may be static (e.g. device assignment to a VM) or dynamic (e.g. scheduling a VM virtual cpu within a domain). The MTT for the supervisor domain active on the hart is programmed on the hart along with the supervisor domain identifier. The MTT does not perform any address translation; it simply provides access permissions for the physically addressed region/page (post any S-mode and/or G-stage address translation) to enforce the isolation properties per the use case requirements (see Figure 2.1). 
 
-=== Sub section
+The assignment of devices and IOMMUs to supervisor domains is also expected to be under the purview of the RDSM. The specifics of device assignment are expected to be device/bus-specific and are out of scope of this specification.
+
+[caption="Figure {counter:image}: ", reftext="Figure {image}"]
+[title= "MTT lookup for Domain Access"]
+image::fig2.png[]
 
-Diam donec adipiscing tristique risus indexterm:[risus]. Nisl rhoncus mattis rhoncus urna. Egestas egestas fringilla phasellus faucibus scelerisque eleifend donec pretium vulputate. Porta non pulvinar neque laoreet suspendisse interdum consectetur libero id. Massa vitae tortor condimentum lacinia quis vel. Donec ac odio tempor orci. Mi sit amet mauris commodo quis imperdiet massa tincidunt. Quis enim lobortis scelerisque fermentum dui. Lacus viverra vitae congue eu. Sed faucibus turpis in eu mi bibendum neque. Sit amet porttitor eget dolor. Aliquet eget sit amet tellus cras adipiscing enim. Id cursus metus aliquam eleifend mi. Vestibulum lorem sed risus ultricies tristique nulla aliquet.
 
-=== Yet another subsection
 
-Quam lacus suspendisse faucibus interdum posuere lorem ipsum. Nulla aliquet enim tortor at auctor urna nunc id cursus. Massa massa ultricies mi quis hendrerit dolor magna. Integer enim neque volutpat ac tincidunt. Dolor magna eget est lorem ipsum dolor. Urna neque viverra justo nec. Neque gravida in fermentum et. Fringilla ut morbi tincidunt augue interdum velit euismod. Dolor sit amet consectetur adipiscing elit. Eu facilisis sed odio morbi. In cursus turpis massa tincidunt dui. Orci indexterm:[orci] phasellus egestas tellus rutrum tellus. Semper eget duis at tellus at urna condimentum. Orci porta non pulvinar neque laoreet suspendisse interdum consectetur.

chapter3.adoc

@@ -0,0 +1,118 @@
+[[chapter3]]
+
+== Supervisor Domain Identifier and Protection Register (mttp) 
+
+The `mttp` register is an XLEN-bit read/write register, formatted as shown in Figure 3.1 for XLEN=32 and Figure 3.2 for XLEN=64, which controls physical address protection for supervisor domains (see Section 2). This register holds the physical page number (PPN) of the root page of the memory tracking table (MTT). The MTT is a structure that holds the read, write access permission bits for a physical address; a supervisor domain identifier (SDID), which facilitates address protection fences on a per-supervisor-domain basis; and the MODE field, which selects the address protection scheme for physical addresses. 
+
+Attempts to read or write mttp while executing in U, S or HS-mode will raise an illegal instruction exception. 
+
+[width="100%",cols="9%,6%,11%,11%,20%,43%",options="header",]
+[frame=none, grid=none]
+|===
+<|31 
+>|30
+<|29 
+>|22
+<|21 
+>|0
+|===
+[width="100%",cols="9%,6%,11%,11%,20%,43%",options="header",]
+|===
+2+^| Mode (WARL) 
+2+^| SDID (WARL) 
+2+^| MTPPN (WARL)
+|===
+[width="100%",cols="9%,6%,11%,11%,20%,43%",options="header",]
+[frame=none, grid=none]
+|===
+2+^|2 
+2+^|8 
+2+^|22
+|===
+
+Figure 3.1: mttp when XLEN=32 for MODE values Bare, Smmtt34.
+
+[width="100%",cols="11%,6%,16%,4%,20%,43%",options="header",]
+[frame=none, grid=none]
+|===
+<|63 
+>|60 
+<|59 
+>|44 
+<|43 
+>|0
+|===
+
+[width="100%",cols="11%,6%,16%,4%,20%,43%",options="header",]
+|===
+2+^|Mode (WARL) 
+2+^|SDID (WARL) 
+2+^|MTPPN (WARL)
+|===
+
+[width="100%",cols="11%,6%,16%,4%,20%,43%",options="header",]
+[frame=none, grid=none]
+|===
+2+^|4 
+2+^|16 
+2+^|44
+|===
+
+Figure 3.2: mttp when XLEN=64, for MODE values Bare, Smmtt46, Smmtt56.
+
+Table 3.1 shows the encodings of the MODE field when XLEN=32 and XLEN=64. When mttp MODE=Bare, supervisor physical addresses have no MTT-based protection across supervisor domains beyond the physical memory protection scheme described in Section 3.7 of the RISC-V privileged architecture specification [1]. In this case, the remaining fields (SDID, MTTPPN) in mttp must be set to zeros, else generate a fault. When XLEN=32, the other valid settings for MODE are Smmtt34 and Smmtt34rw, to support allow/disallow and read-write access permissions for 34-bit system physical addresses. 
+
+When XLEN=64, other than BARE, the other valid settings for MODE are Smmtt[46, 56][rw] to support read-write/access permissions for 56-bit system physical addresses. 
+
+The remaining MODE settings when XLEN=64 are reserved for future use and may define different interpretations of the other fields in mttp. 
+
+[width="100%",cols="10%,14%,76%",options="header",]
+|===
+|Value |Name |Description
+|0 |Bare |No inter-supervisor domain protection
+
+|1 |Smmtt34 |Page-based supervisor domain protection for 34 bit physical
+addresses with access allowed/disallowed per page
+
+|2 |Smmtt34rw |Page-based supervisor domain protection for 34 bit
+physical addresses with RW permissions per page
+|===
+
+Table 3.1: Encoding of mttp MODE field for XLEN=32.
+
+[width="100%",cols="10%,14%,76%",options="header",]
+|===
+|Value |Name |Description
+|0 |Bare |No inter-supervisor domain protection
+
+|1 |Smmtt46 |Page-based supervisor domain protection for 46 bit physical
+addresses
+
+|2 |Smmtt46rw |Page-based supervisor domain protection for 46 bit
+physical addresses with RW permissions per page
+
+|3 |Smmtt56 |Page-based supervisor domain protection for 56 bit physical
+addresses
+
+|4 |Smmtt56rw |Page-based supervisor domain protection for 46 bit
+physical addresses with RW permissions per page
+
+|3-15 |- |_Reserved_
+|===
+
+Table 3.2: Encoding of mttp MODE field for XLEN=64.
+
+Implementations are not required to support all defined MODE settings when XLEN=64. A write to mttp with an unsupported MODE value is not ignored. Instead, the fields of mttp are WARL in the normal way, when so indicated. 
+
+The MTTPPN refers to an MTT L3 table or an MTT L2 table based on physical address width (PAW). For 56<=PAW<46, L3 table must be of size 2^(PAW-43) bytes and naturally aligned to that sized byte boundary. For 46<=PAW<32 the MTT L2 table must be of size 2^(PAW-23) or 2^(PAW-22) bytes (depending on the Smmtt mode selected) and must be naturally aligned to that sized byte boundary. In these modes, the lowest two bits of the physical page number (PPN) in mttp always read as zeros. 
+
+The number of SDID bits is UNSPECIFIED and may be zero. The number of implemented SDID bits, termed SDIDLEN, may be determined by writing one to every bit position in the SDID field, then reading back the value in mttp to see which bit positions in the SDID field hold a one. The least-significant bits of SDID are implemented first: that is, if SDIDLEN > 0, SDID[SDIDLEN-1:0] is writable. The maximal value of SDIDLEN, termed SDIDMAX, is 8 for Smmtt34[rw] or 16 for Smmtt46[rw], Smmtt56[rw]. 
+
+The mttp register is considered active for the purposes of the physical address protection algorithm unless the effective privilege mode is M. 
+
+Physical accesses that began while mttp was active are not required to complete or terminate when mttp is no longer active, unless an FENCE.MTT instruction matches the SDID (and address?) is executed. The FENCE.MTT instruction must be used to ensure that updates to the MTT address protection data structures are observed by subsequent implicit reads to those structures by a hart.
+
+Note that writing mttp does not imply any ordering constraints between S-mode and G-stage page-table updates and subsequent address translations. If a supervisor domain's physical page protection structure has been modified, or if a SDID is reused, it may be necessary to execute an FENCE.MTT instruction before or after writing mttp.
+
+
+