Add example CSR spec to arch docs

arch/README.adoc

@@ -190,3 +190,50 @@ Some fields are shifted before use, and can be represented using the `left_shift
 
 === CSRs
 
+.CSR specification for `marchid`
+[source,yaml]
+----
+marchid: # <1>
+  long_name: Machine Architecture ID
+  address: 0xf12 # <2>
+  priv_mode: M # <3>
+  length: MXLEN # <4>
+  description: | # <5>
+    Asciidoc description
+  definedBy: I # <6>
+  fields: # <7>
+    Architecture:
+      location_rv32: 31-0 # <8>
+      location_rv64: 63-0
+      type: RO # <7>
+      description: Vendor-specific microarchitecture ID. # <9>
+      reset_value(): return ARCH_ID; # <10>
+----
+<1> CSR name
+<2> CSR address (used by CSRs that not indirect)
+<3> Least-privileged mode required to access the CSR
+<4> Length of the CSR, in bits. Can either be an integer (_e.g._ 32, 64), or 'MXLEN', 'SXLEN', or 'VSXLEN' when the length is equal to the XLEN in M, S, or VS mode, respectively.
+<5> Asciidoc description
+<6> Defining extension. Can be list when more than one extension defines the CSR.
+<7> List of fields in the CSR
+<8> Location. In this case, the location changes with XLEN, so `location_rv32` and `location_rv64` are used. When the location does not change, use the single key `location`.
+<9> Type of the field. See below for more information.
+<10> Reset value. In this case, the reset value is determined by the configuration, so it is specified as an IDL function.
+
+CSR fields are given a type, which _does not_ necessarily correspond to the WARL/WLRL types in the RVI specs. We use a different format here because the RVI CSR types are vauge and inconsistent. The types are:
+
+[cols="1,4"]
+|===
+| Type | Meaning
+
+| *RO* | Read-only
+| *RO-H* | Read-only, and hardware updates the field
+| *RW* | Read-write
+| *RW-R* | Read-write, but only a restricted set of values are allowed
+| *RW-H* | Read-write, and hardware updates the field
+| *RW-RH* | Read-write, only a restricted set of values are allowed, and hardware updates the field
+|===
+
+In many cases, the values of CSR and/or CSR field data are configuration dependent. Some of that is covered directly by the data model (_e.g._, with `location_rv32`, `location_rv64`), but some cases are too complex to express with YAML. For this reason, many of the keys can be specified as IDL functions. See the schema documentation and examples in the `arch/csr` folder for more information.
+
+Some keys that only apply to certain CSRs are not shown above.