Add the schema doc

arch/csr/schema.adoc

@@ -0,0 +1,221 @@
+= Schema for CSR defintions
+
+A CSR defintion is a mapping (_i.e._, hash, dictionary, ...) containing exactly one key
+equal to the CSR name, and pointing to an object specified below. For example:
+
+.CSR object
+[source,yaml]
+----
+mstatus:
+  long_name: Machine status
+  # ...
+----
+
+The CSR object has the following information:
+
+Long name::
+
+[IMPORTANT] long_name is a required key
+
+|===
+| *key*         | long_name
+| *value type*  | String
+| *description* | A descriptive name for the CSR
+|===
+
+Description::
+
+[IMPORTANT] description is a required key
+
+|===
+| *key*         | description
+| *value type*  | String
+| *description* | A full Asciidoc description of the CSR, indended to be used as documentation.
+|===
+
+Defining extension::
+
+[IMPORTANT] definedBy is a required key
+
+|===
+| *key*         | definedBy
+| *value type*  | String
+| *description* | The extension that defines this CSR.
+|===
+
+Privilege Mode::
+
+[IMPORTANT] `priv_mode` is a required key
+
+|===
+| *key*         | priv_mode
+| *value type*  | one of ["M", "S", "U", or "VS"]
+| *description* | The least-privilege mode that can access this CSR
+|===
+
+Length::
+
+[IMPORTANT] `length` is a required key
+
+|===
+| *key*         | length
+| *value type*  | one of [32, 64, "MXLEN", "SXLEN", "VSXLEN"]
+| *description* | Length, in bits, of the CSR. Can either be a 32, 64 or MXLEN, SXLEN, VSXLEN to indicate that is is equal to the effective XLEN for a given mode
+|===
+
+Indirect::
+
+|===
+| *key*         | indirect
+| *value type*  | Boolean
+| *default*     | false
+| *description* | Whether or not the CSR is accessible through the indirect CSRs of the `Smcdrind`/`Sscdrind` extensions.
+|===
+
+Address::
+
+[IMPORTANT] `address` is a required key *unless* the CSR is only accessible through the indirect registers of the `Smcsrind`/`Sscrind` extensions, in which case `indirect_address` is required. Both `address` and `indirect_address` may be specified when a CSR is accessible directly and indirectly.
+
+|===
+| *key*         | address
+| *value type*  | Integer between 0-4095, inclusive
+| *description* | Address of the CSR, as given to the CSR access instructions of the `Zicsr` extension
+|===
+
+|===
+| *key*         | indirect_address
+| *value type*  | Integer
+| *description* | Indirect sddress of the CSR, as given to the indirect CSRs of the `Smcsrind`/`Sscdrind` extensions
+|===
+
+Virtual Address::
+
+[IMPORTANT] `virtual_address` is required when the `priv_mode` of the CSR is VS.
+
+|===
+| *key*         | virtual_address
+| *value type*  | Integer between 0-4095, inclusive
+| *description* | Address of the CSR viewed from VS-mode
+|===
+
+Custom Software Read::
+
+|===
+| *key*         | sw_read()
+| *value type*  | String of IDL code that returns a read value
+| *description* | Function that returns the value of the CSR when read by software (i.e., a Zicsr instruction). If not specified, the value last written (possibly filtered through field `write(csr_value)` functions) is returned.
+|===
+
+Fields::
+
+[IMPORTANT] `fields` is a required key
+
+|===
+| *key*         | fields
+| *value type*  | Mapping of field name (String) to field data (Object)
+| *description* | Function that returns the value of the CSR when read by software (i.e., a Zicsr instruction). If not specified, the value last written (possibly filtered through field `write(csr_value)` functions) is returned.
+|===
+
+== Schema for CSR fields
+
+A CSR field defintion is a mapping (_i.e._, hash, dictionary, ...) containing exactly one key
+equal to the CSR field name, in uppercase, and pointing to an object specified below.
+
+Location::
+
+[IMPORTANT] `location` is required *unless* the location is depenent on the XLEN of a certain mode, in which case both `location_rv32` and `location_rv64` are required
+
+|===
+| *key*         | location
+| *value type*  | Integer (when the field is a single bit) -OR- a String of "MSB-LSB"
+| *description* | Location of the field within the CSR.
+|===
+
+|===
+| *key*         | location_rv32
+| *value type*  | Integer (when the field is a single bit) -OR- a String of "MSB-LSB"
+| *description* | Location of the field within the CSR in RV32.
+|===
+
+|===
+| *key*         | location_rv64
+| *value type*  | Integer (when the field is a single bit) -OR- a String of "MSB-LSB"
+| *description* | Location of the field within the CSR in RV64.
+|===
+
+Base::
+
+When a CSR field is only present in RV32 or RV64, the `base` field is used.
+
+|===
+| *key*         | base
+| *value type*  | One of [32, 64]
+| *description* | Effective XLEN for this field to exist.
+|===
+
+Reset Value::
+
+[IMPORTANT] `reset_value` is required *unless* the reset value is dependent on a configuration option, in which case `reset_value()` is required.
+
+|===
+| *key*         | reset_value
+| *value type*  | Integer -OR- "UNDEFINED_LEGAL"
+| *description* | Value of the field coming out of reset. When the specific value is not defined, "UNDEFINED_LEGAL" is use to indicate that the value isn't known but is gauranteed to a legal value for the field.
+|===
+
+|===
+| *key*         | reset_value()
+| *value type*  | String of IDL code that returns a reset value
+| *description* | Value of the field coming out of reset. When the specific value is not defined, the special value UNDEFINED_LEGAL can be returned to indicate that the value isn't known but is gauranteed to a legal value for the field.
+|===
+
+Type::
+
+[IMPORTANT] `type` is required, unless the type is configuration-dependent, in which case `type()` is required
+
+Each field specifies a type as one of:
+
+[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
+|===
+
+|===
+| *key*         | type
+| *value type*  | One of ["RO", "RO-H", "RW", "RW-R", "RW-H", "RW-RH"]
+| *description* | The type of the field, as described above
+|===
+
+|===
+| *key*         | type()
+| *value type*  | String of IDL code that returns a CsrFieldType
+| *description* | Type of the field, as a CsrFieldType enum value
+|===
+
+Custom Write Function::
+
+[IMPORTANT] `write(csr_value)` is required when the type of the field is restricted ("RW-R" or "RW-RH")
+
+|===
+| *key*         | write(csr_value)
+| *value type*  | String of IDL code that is run when the software writes the field
+| *description* | Function implementing custom write behavior for the CSR. The csr_value parameter is the *entire* attempted CSR write value. Fields within the attempted write value can be accessed with a dot operator (e.g., csr_value.SXL, csr_value.VGEIN, ...)
+|===
+
+|===
+| *key*         | legal?(csr_value)
+| *value type*  | String of IDL code that returns whether or not an attempted write is legal
+| *description* | Function that returns whether or not an attempted value for the field is legal. The csr_value parameter is the *entire* attempted CSR write value. Fields within the attempted write value can be accessed with a dot operator (e.g., csr_value.SXL, csr_value.VGEIN, ...)
+|===
+
+Alias::
+
+Some fields are aliases for another field, often in a different CSR. THe `alias` key is used to indicate that this field just points somewhere else.
+