Merge pull request #24 from riscv/jhauser_issues

Address Jhauser issues

Makefile

@@ -14,7 +14,7 @@
 
 DATE ?= $(shell date +%Y-%m-%d)
 VERSION ?= v0.0.0
-REVMARK ?= Draft
+REVMARK ?= Stable
 DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \
 riscvintl/riscv-docs-base-container-image:latest
 

body.adoc

@@ -174,10 +174,10 @@ The 32-bit `sctrdepth` register specifies the depth of the CTR buffer.
 
 .Supervisor Control Transfer Records Depth Register Field Definitions
 [%unbreakable]
-[width="100%",cols="15%,75%,10%",options="header",]
+[width="100%",cols="15%,85%",options="header",]
 |===
-|Field |Description |Access
-|DEPTH |Selects the depth of the CTR buffer. Encodings:
+|Field |Description
+|DEPTH |WARL field that selects the depth of the CTR buffer. Encodings:
 
 ‘000 - 16
 
@@ -194,17 +194,16 @@ The 32-bit `sctrdepth` register specifies the depth of the CTR buffer.
 The depth of the CTR buffer dictates the number of entries to which the hardware records transfers. For a depth of N, the hardware records transfers to entries 0..N-1. All <<_entry_registers, Entry Registers>> read as '0' and are read-only when the selected entry is in the range N to 255.  When the depth is increased, the newly accessible entries contain unspecified but legal values.
 
 It is implementation-specific which DEPTH value(s) are supported.
-|WARL
 |===
 
-Attempts to access `sctrdepth` from VS-mode raise a virtual-instruction exception, unless CTR state enable access restrictions apply.  See <<State Enable Access Control>>.
+Attempts to access `sctrdepth` from VS-mode or VU-mode raise a virtual-instruction exception, unless CTR state enable access restrictions apply.  See <<State Enable Access Control>>.
 
 [NOTE]
 [%unbreakable]
 ====
-_It is expected that kernels will access `sctrdepth` only at boot, to select the maximum supported depth value.  More frequent accesses may result in reduced performance in virtualization scenarios, as a result of traps from VS-mode incurred._
+_It is expected that operating systems (OSs) will access `sctrdepth` only at boot, to select the maximum supported depth value.  More frequent accesses may result in reduced performance in virtualization scenarios, as a result of traps from VS-mode incurred._
 
-_There may be scenarios where software chooses to operate on only a subset of the entries, to reduce overhead.  In such cases tools may choose to read only the lower entries, and kernels may choose to save/restore only on the lower entries while using SCTRCLR to clear the others._
+_There may be scenarios where software chooses to operate on only a subset of the entries, to reduce overhead.  In such cases tools may choose to read only the lower entries, and OSs may choose to save/restore only on the lower entries while using SCTRCLR to clear the others._
 
 _The value in configurable depth lies in supporting VM migration.  It is expected that a platform spec may specify that one or more CTR depth values must be supported.  A hypervisor may wish to restrict guests to using one of these required depths, in order to ensure that such guests can be migrated to any system that complies with the platform spec.  The trapping behavior specified for VS-mode accesses to `sctrdepth` ensures that the hypervisor can impose such restrictions._
 ====
@@ -226,11 +225,11 @@ The 32-bit `sctrstatus` register grants access to CTR status information and is
 
 .Supervisor Control Transfer Records Status Register Field Definitions
 [%unbreakable]
-[width="100%",cols="15%,75%,10%",options="header",]
+[width="100%",cols="15%,85%",options="header",]
 |===
-|Field |Description |Access
-|WRPTR |Indicates the physical CTR buffer entry to be written next.  Incremented on new transfers recorded (see <<Behavior>>), and decremented on qualified returns when `mctrctl`.RASEMU=1 (see <<RAS (Return Address Stack) Emulation Mode>>).  For a given CTR depth (where depth = 2^(DEPTH+4)^), WRPTR wraps to 0 on an increment when the value matches depth-1, and to depth-1 on a decrement when the value is 0.  Bits above those needed to represent depth-1 (e.g., bits 7:4 for a depth of 16) are read-only 0. On depth changes, WRPTR holds an unspecified but legal value. |WARL 
-|FROZEN |Inhibit transfer recording. See <<Freeze>>. |WARL
+|Field |Description
+|WRPTR |WARL field that indicates the physical CTR buffer entry to be written next.  Incremented on new transfers recorded (see <<Behavior>>), and decremented on qualified returns when `mctrctl`.RASEMU=1 (see <<RAS (Return Address Stack) Emulation Mode>>).  For a given CTR depth (where depth = 2^(DEPTH+4)^), WRPTR wraps to 0 on an increment when the value matches depth-1, and to depth-1 on a decrement when the value is 0.  Bits above those needed to represent depth-1 (e.g., bits 7:4 for a depth of 16) are read-only 0. On depth changes, WRPTR holds an unspecified but legal value.
+|FROZEN |Inhibit transfer recording. See <<Freeze>>.
 |===
 
 Undefined bits in `sctrstatus` are WPRI. Status fields may be added by future extensions,
@@ -401,7 +400,7 @@ The SCTRCLR instruction performs the following operations:
 
 Any read of `ctrsource`, `ctrtarget`, or `ctrdata` that follows SCTRCLR, such that it precedes the next qualified control transfer, will return the value 0.  Further, the first recorded transfer following SCTRCLR will have `ctrdata`.CCV=0. 
 
-SCTRCLR raises an illegal-instruction exception in U-mode, and a virtual-instruction exception in VU-mode.
+SCTRCLR raises an illegal-instruction exception in U-mode, and a virtual-instruction exception in VU-mode, unless CTR state enable access restrictions apply.  See <<State Enable Access Control>>.
 
 == State Enable Access Control
 
@@ -413,10 +412,16 @@ When Smstateen is implemented, the `mstateen0`.CTR bit controls access to CTR re
 
 When `mstateen0`.CTR=0, qualified control transfers executed in privilege modes less privileged than M-mode will continue to implicitly update entry registers and `sctrstatus`.
 
-If the H extension is implemented and `mstateen0`.CTR=1, the `hstateen0`.CTR bit controls access to supervisor CTR state when V=1.  This state includes `sctrctl` (really vsctrctl), `sctrdepth`, `sctrstatus`, and `sireg*` (really `vsireg*`) when `siselect` (really `vsiselect`) is in 0x200..0x2FF.  `hstateen0`.CTR is read-only 0 when `mstateen0`.CTR=0.
+If the H extension is implemented and `mstateen0`.CTR=1, the `hstateen0`.CTR bit controls access to supervisor CTR state when V=1.  This state includes `sctrctl` (really vsctrctl), `sctrstatus`, and `sireg*` (really `vsireg*`) when `siselect` (really `vsiselect`) is in 0x200..0x2FF.  `hstateen0`.CTR is read-only 0 when `mstateen0`.CTR=0.
 
 When `mstateen0`.CTR=1 and `hstateen0`.CTR=1, VS-mode accesses to supervisor CTR state behave as described in <<CSRs>> and <<Entry Registers>> above, while SCTRCLR behaves as described in <<Supervisor CTR Clear Instruction>>.  When `mstateen0`.CTR=1 and `hstateen0`.CTR=0, both VS-mode accesses to supervisor CTR state and VS-mode execution of SCTRCLR raise a virtual-instruction exception.
 
+[NOTE]
+[%unbreakable]
+====
+`__sctrdepth__` _is not included in the above list of supervisor CTR state controlled by `hstateen0`.CTR since accesses to `sctrdepth` from VS-mode raise a virtual-instruction exception regardless of the value of `hstateen0`.CTR._
+====
+
 When `hstateen0`.CTR=0, qualified control transfers executed while V=1 will continue to implicitly update entry registers and `sctrstatus`.
 
 The CTR bit is bit 54 in `mstateen0` and `hstateen0`.