Skip to content

Commit

Permalink
Add CSR schema docs
Browse files Browse the repository at this point in the history
  • Loading branch information
dhower-qc committed Jul 15, 2024
1 parent 7be4248 commit 11c4bdf
Show file tree
Hide file tree
Showing 3 changed files with 54 additions and 20 deletions.
2 changes: 1 addition & 1 deletion arch/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,6 @@ CSR fields are given a type, which _does not_ necessarily correspond to the WARL
| *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.
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 xref:csr/schema.adoc[schema] documentation and examples in the `arch/csr` folder for more information.

Some keys that only apply to certain CSRs are not shown above.
2 changes: 1 addition & 1 deletion arch/csr/mstatus.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ mstatus:
# MXLEN cannot change dynamically, so this will be converted to an integer
# in the genrated, configuration-dependent spec
length: MXLEN

description: The mstatus register tracks and controls the hart's current operating state.
definedBy: I
fields:
Expand Down
70 changes: 52 additions & 18 deletions schemas/csr_schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,7 @@
},
"csr_register": {
"type": "object",
"required": ["long_name", "description", "address", "priv_mode", "definedBy"],
"required": ["long_name", "length", "description", "priv_mode", "definedBy"],

"properties": {
"name": {
Expand All @@ -199,18 +199,31 @@
"description": "When a CSR is only defined in RV32, or RV64, the base that defines it. When defined in both, this field should be absent."
},
"long_name": {
"type": "string"
"type": "string",
"description": "Descriptive name for the CSR"
},
"description": {
"type": "string"
"type": "string",
"description": "A full Asciidoc description of the CSR, indended to be used as documentation."
},
"definedBy": {
"type": "string",
"pattern": "^([A-WY]|([SXZ][a-z]+))$"
"$ref": "schema_defs.json#/$defs/extension_name",
"description": "The extension that defines this CSR."
},
"address": {
"type": "integer",
"description": "CSR address"
"minValue": 0,
"maxValue": 4095,
"description": "Address of the CSR, as given to the CSR access instructions of the `Zicsr` extension"
},
"indirect_address": {
"type": "integer",
"description": "Indirect sddress of the CSR, as given to the indirect CSRs of the `Smcsrind`/`Sscdrind` extensions"
},
"indirect": {
"type": "boolean",
"default": false,
"description": "Whether or not the CSR is accessible via an indirect address"
},
"virtual_address": true, "$comment": "Conditionally required; see below",
"priv_mode": {
Expand All @@ -231,6 +244,7 @@
"$ref": "#/$defs/csr_field"
}
},
"description": "fields of this CSR",
"additionalProperties": false
},
"sw_read()": {
Expand All @@ -241,20 +255,40 @@
"additionalProperties": false,

"$comment": "If mode is VS, then there must be a virtual_address field",
"if": {
"properties": {
"priv_mode": { "const": "VS" }
}
},
"then": {
"properties": {
"virtual_address": {
"type": "number",
"description": "Address of the CSR viewed from VS-mode"
"allOf": [
{
"if": {
"properties": {
"priv_mode": { "const": "VS" }
}
},
"then": {
"properties": {
"virtual_address": {
"type": "number",
"description": "Address of the CSR viewed from VS-mode"
}
},
"required": ["virtual_address"]
}
},
"required": ["virtual_address"]
}
{
"oneOf": [
{
"properties": {
"indirect": { "const": false }
},
"required": ["address"]
},
{
"properties": {
"indirect": { "const": true }
},
"required": ["indirect_address"]
}
]
}
]
}
},

Expand Down

0 comments on commit 11c4bdf

Please sign in to comment.