Merge remote-tracking branch 'origin/main' into pr/dhower/201

Author: Derek Hower

.github/ISSUE_TEMPLATE/data-entry.md

@@ -0,0 +1,10 @@
+---
+name: Data Entry
+about: Add new data into the database
+title: ''
+labels: data entry
+assignees: ''
+
+---
+
+**Describe the data**

.vscode/settings.json

@@ -9,5 +9,5 @@
   "files.watcherExclude": {
     "**/.home": true
   },
-  "asciidoc.antora.enableAntoraSupport": true
+  "asciidoc.antora.showEnableAntoraPrompt": true
 }

README.adoc

@@ -28,7 +28,7 @@ This repository contains:
 
 === Working examples:
 
- * Generate https://riscv-software-src.github.io/riscv-unified-db/manual/index.html[configuration-specific documentation] taylored to the set of implemented extensions and unnamed implementation options (_e.g._, `./do gen:html[generic_rv64]`).
+ * Generate https://riscv-software-src.github.io/riscv-unified-db/manual/html/index.html[configuration-specific documentation] taylored to the set of implemented extensions and unnamed implementation options (_e.g._, `./do gen:html[generic_rv64]`).
  ** Only implemented extensions/instructions/CSRs are included
  ** Unreachable/unimplemented parts of the formal specification are pruned away
  ** A dedicated documentation page for every implemented instruction, including its encoding, pruned execution behavior, and what types of exceptions it may cause.
@@ -108,5 +108,3 @@ Quick start:
 == More info
 
  * xref:arch/README.adoc[Architecture specification format]
- * xref:_site/ruby/arch_def/index.html[Ruby database object model documentation]
- * xref:_site/ruby/idl/index.html[IDL Compiler documentation]

arch/csr/menvcfg.yaml

@@ -247,8 +247,8 @@ menvcfg:
       type: RW-R
       sw_write(csr_value): |
         if ((csr_value.CBIE == 0) ||
-            (ALLOW_CBO_INVAL_UPGRADE_TO_FLUSH && (csr_value.CBIE == 1)) ||
-            (csr_value.CBIE == 3)) {
+            (csr_value.CBIE == 1) ||
+            ((!FORCE_UPGRADE_CBO_INVAL_TO_FLUSH) && (csr_value.CBIE == 3))) {
           return csr_value.CBIE;
         } else {
           return CSR[menvcfg].CBIE;

arch/csr/mstatus.yaml

@@ -22,9 +22,29 @@ mstatus:
         
         Read-only bit that summarizes whether either the FS, XS, or VS
         fields signal the presence of some dirty state.
-      type: RO-H
-      reset_value: UNDEFINED_LEGAL
-      affectedBy: [F, D, V]
+      definedBy:
+        anyOf: [F,V] # NOTE: if you implement a custom extension overlay that writes to XS, then you need to add your extension here in the overlay as well
+      type(): |
+        # this is read-only if FS and VS are both read-only
+        # otherwise, it is read-only with hardware update
+
+        if (implemented?(ExtensionName::F) && (HW_MSTATUS_FS_DIRTY_UPDATE != "never")) {
+          return CsrFieldType::ROH;
+        } else if (implemented?(ExtensionName::V) && (HW_MSTATUS_VS_DIRTY_UPDATE != "never")) {
+          return CsrFieldType::ROH;
+        } else {
+          return CsrFieldType::RO;
+        }
+      reset_value(): |
+        # the reset value is known if both FS and VS are legal
+        # make this a function call so that it can be displayed succinctly in docs
+
+        if (mstatus_sd_has_known_reset()) {
+          return mstatus_sd_reset_value();
+        } else {
+          return UNDEFINED_LEGAL;
+        }
+
     MPV:
       location: 39
       base: 64
@@ -339,7 +359,8 @@ mstatus:
           # there will be no hardware update in this case because we know the F extension isn't implemented
           return MSTATUS_FS_WRITEABLE ? CsrFieldType::RW : CsrFieldType::RO;
         }
-      definedBy: F
+      definedBy:
+        anyOf: [F, S]
       reset_value(): |
         if (CSR[misa].F == 1'b1){
           return UNDEFINED_LEGAL;
@@ -410,9 +431,38 @@ mstatus:
         When a vector register or vector CSR is written, VS obtains the value 3.
         Values 1 and 2 are valid write values for software, but are not interpreted by hardware
         other than to possibly enable a previously-disabled vector unit.
-      type: RW-H
-      reset_value: UNDEFINED_LEGAL
-      definedBy: V
+      definedBy:
+        anyOf: [V, S]
+      type(): |
+        if (CSR[misa].V == 1'b1){
+          return CsrFieldType::RWH;
+        } else if ((CSR[misa].S == 1'b0) && (CSR[misa].V == 1'b0)) {
+          # must be read-only-0
+          return CsrFieldType::RO;
+        } else {
+          # there will be no hardware update in this case because we know the V extension isn't implemented
+          return MSTATUS_VS_WRITEABLE ? CsrFieldType::RW : CsrFieldType::RO;
+        }
+      reset_value(): |
+        if (CSR[misa].V == 1'b1){
+          return UNDEFINED_LEGAL;
+        } else if ((CSR[misa].S == 1'b0) && (CSR[misa].V == 1'b0)) {
+          # must be read-only-0
+          return 0;
+        } else {
+          # there will be no hardware update in this case because we know the V extension isn't implemented
+          return MSTATUS_VS_WRITEABLE ? UNDEFINED_LEGAL : 0;
+        }
+      sw_write(csr_value): |
+        if (CSR[misa].V == 1'b1){
+          return ary_includes?<$array_size(MSTATUS_VS_LEGAL_VALUES), 2>(MSTATUS_VS_LEGAL_VALUES, csr_value.FS) ? csr_value.FS : UNDEFINED_LEGAL_DETERMINISTIC;
+        } else if ((CSR[misa].S == 1'b0) && (CSR[misa].V == 1'b0)) {
+          # must be read-only-0
+          return 0;
+        } else {
+          # there will be no hardware update in this case because we know the V extension isn't implemented
+          return ary_includes?<$array_size(MSTATUS_VS_LEGAL_VALUES), 2>(MSTATUS_VS_LEGAL_VALUES, csr_value.FS) ? csr_value.FS : UNDEFINED_LEGAL_DETERMINISTIC;
+        }
     SPP:
       location: 8
       description: |

arch/ext/F.yaml

@@ -246,13 +246,13 @@ F:
         Values are:
         [separator="!"]
         !===
-        h! none  ! Hardware never writes `mstatus.FS`
+        h! never  ! Hardware never writes `mstatus.FS`
         h! precise  ! Hardware writes `mstatus.FS` to the Dirty (3) state precisely when F registers are modified
         h! imprecise ! Hardware writes `mstatus.FS` imprecisely. This will result in a call to unpredictable() on any attempt to read `mstatus` or write FP state.
         !===
       schema:
         type: string
-        enum: ["none", "precise", "imprecise"]
+        enum: ["never", "precise", "imprecise"]
     MSTATUS_FS_LEGAL_VALUES:
       description: |
         The set of values that mstatus.FS will accept from a software write.
@@ -268,4 +268,4 @@ F:
         assert MSTATUS_FS_LEGAL_VALUES.include?(0) && MSTATUS_FS_LEGAL_VALUES.include?(3) if ext?(:F)
 
         # if HW is writing FS, then Dirty (3) better be a supported value
-        assert MSTATUS_FS_LEGAL_VALUES.include?(3) if ext?(:F) && (HW_MSTATUS_FS_DIRTY_UPDATE != "none")
+        assert MSTATUS_FS_LEGAL_VALUES.include?(3) if ext?(:F) && (HW_MSTATUS_FS_DIRTY_UPDATE != "never")

arch/ext/S.yaml

@@ -254,6 +254,15 @@ S:
         type: boolean
       extra_validation:
         assert MSTATUS_FS_WRITEABLE == true if ext?(:F)
+    MSTATUS_VS_WRITEABLE:
+      description: |
+        When `S` is enabled but `V` is not, mstatus.VS is optionally writeable.
+
+        This parameter only has an effect when both S and V mode are disabled.
+      schema:
+        type: boolean
+      extra_validation:
+        assert MSTATUS_VS_WRITEABLE == true if ext?(:V)
     MSTATUS_FS_LEGAL_VALUES:
       description: |
         The set of values that mstatus.FS will accept from a software write.
@@ -267,6 +276,22 @@ S:
       also_defined_in: F
       extra_validation: |
         assert MSTATUS_FS_LEGAL_VALUES.include?(0) && MSTATUS_FS_LEGAL_VALUES.include?(3) if ext?(:F)
+    MSTATUS_VS_LEGAL_VALUES:
+      description: |
+        The set of values that mstatus.VS will accept from a software write.
+      schema:
+        type: array
+        items:
+          type: integer
+          enum: [0,1,2,3]
+        maxItems: 4
+        uniqueItems: true
+      also_defined_in: V
+      extra_validation: |
+        assert MSTATUS_VS_LEGAL_VALUES.include?(0) && MSTATUS_VS_LEGAL_VALUES.include?(3) if ext?(:V)
+
+        # if HW is writing VS, then Dirty (3) better be a supported value
+        assert MSTATUS_VS_LEGAL_VALUES.include?(3) if ext?(:V) && (HW_MSTATUS_VS_DIRTY_UPDATE != "never")
     MSTATUS_TVM_IMPLEMENTED:
       description: |
         Whether or not mstatus.TVM is implemented.

arch/ext/V.yaml

@@ -14,4 +14,34 @@ V:
       description: |
         Indicates whether or not the `V` extension can be disabled with the `misa.V` bit.
       schema:
-        type: boolean
+        type: boolean
+    HW_MSTATUS_VS_DIRTY_UPDATE:
+      description: |
+        Indicates whether or not hardware will write to `mstatus.VS`
+
+        Values are:
+        [separator="!"]
+        !===
+        h! never  ! Hardware never writes `mstatus.VS`
+        h! precise  ! Hardware writes `mstatus.VS` to the Dirty (3) state precisely when V registers are modified
+        h! imprecise ! Hardware writes `mstatus.VS` imprecisely. This will result in a call to unpredictable() on any attempt to read `mstatus` or write vector state.
+        !===
+      schema:
+        type: string
+        enum: ["never", "precise", "imprecise"]
+    MSTATUS_VS_LEGAL_VALUES:
+      description: |
+        The set of values that mstatus.VS will accept from a software write.
+      schema:
+        type: array
+        items:
+          type: integer
+          enum: [0,1,2,3]
+        maxItems: 4
+        uniqueItems: true
+      also_defined_in: S
+      extra_validation: |
+        assert MSTATUS_VS_LEGAL_VALUES.include?(0) && MSTATUS_VS_LEGAL_VALUES.include?(3) if ext?(:V)
+
+        # if HW is writing VS, then Dirty (3) better be a supported value
+        assert MSTATUS_VS_LEGAL_VALUES.include?(3) if ext?(:V) && (HW_MSTATUS_VS_DIRTY_UPDATE != "never")

arch/ext/Zicbom.yaml

@@ -15,12 +15,12 @@ Zicbom:
       also_defined_in: [Zicboz, Zicbop]
       schema:
         type: integer
-    ALLOW_CBO_INVAL_UPGRADE_TO_FLUSH:
+    FORCE_UPGRADE_CBO_INVAL_TO_FLUSH:
       description: |
-        When true, an implementation can (when `menvcfg.CBIE` == `01`) upgrade a `cbo.inval`
-        instruction to a `cbo.flush`.
+        When true, an implementation prohibits setting `menvcfg.CBIE` == `11` such that all `cbo.inval`
+        instructions either trap (when `menvcfg.CBIE` == '00') or flush (when `menvcfg.CBIE` == '01').
 
-        When false, an implementation does not support the upgrade, and the value '01' cannot be
-        written to `menvcfg.CBIE`.
+        When false, an implementation allows a true INVAL operation for `cbo.inval`, and thus supports
+        the setting `menvcfg.CBIE` == `11`.
       schema:
         type: boolean

arch/inst/A/lr.w.yaml

@@ -45,7 +45,8 @@ lr.w:
      Software should not set the _rl_ bit on an LR instruction unless the _aq_ bit is also set.
      LR.rl and SC.aq instructions are not guaranteed to provide any stronger ordering than those
      with both bits clear, but may result in lower performance.
-  definedBy: A
+  definedBy:
+    anyOf: [A, Zalrsc]
   assembly: xd, xs1
   encoding:
     match: 00010--00000-----010-----0101111