Merge pull request #37 from riscv-admin/csr-format-design

.github/ISSUE_TEMPLATE/glossary-term.md

@@ -2,24 +2,22 @@
 name: Glossary term
 about: Add a term to the RISC-V glossary
 title: Glossary term requested.
-labels: ''
-assignees: ''
-
+labels: ""
+assignees: ""
 ---
 
 **New term or update existing**
+
 - [ ] New
 - [ ] Existing
 
 **Term**
 What is the term?
 
-
 **Definition**
 If this term is an acronym, what does the acronym stand for. If more explanation is required, please described.
 
 If you want an existing term modified, please provide new text.
 
-
 **Link**
 If you know a place that contains a good definition that cannot be reduced down to a glossary term entry, add link here.

.github/workflows/pre-commit.yml

@@ -0,0 +1,15 @@
+---
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - uses: pre-commit/[email protected]

.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+---
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-symlinks
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: v3.2.5
+    hooks:
+      - id: prettier
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.6.27
+    hooks:
+      - id: actionlint

LICENSE

@@ -49,7 +49,7 @@ exhaustive, and do not form part of our licenses.
      such as asking that all changes be marked or described.
      Although not required by our licenses, you are encouraged to
      respect those requests where reasonable. More_considerations
-     for the public: 
+     for the public:
 	wiki.creativecommons.org/Considerations_for_licensees
 
 =======================================================================

README.md

@@ -1,6 +1,5 @@
 # RISC-V documentation team
 
-Welcome to RISC-V documentation team repository. This repository tracks documentation work items for the RISC-V ISA specs, non-ISA docs, and the supporting documentation.  More details can be found in the [Doc SIG Charter](CHARTER.adoc).
-
-
+Welcome to RISC-V documentation team repository. This repository tracks documentation work items for the RISC-V ISA specs, non-ISA docs, and the supporting documentation. More details can be found in the [Doc SIG Charter](CHARTER.adoc).
 
+For complex tasks, a [projects](projects) dir contains more information.

projects/csr-format-design.md

@@ -0,0 +1,74 @@
+# Draft design doc
+
+## Overview
+
+Currently spec authors don't have much direction on the format to put their CSR definitions in or any workflow suggestions to then render those definitions in the spec (except perhaps using wavedrom or an asciidoc table).
+
+Early on, one spec [riscv-debug-spec XML](https://github.com/kbroch-rivosinc/riscv-debug-spec/tree/main/xml) did define a CSR format and create tooling to generate outputs. No other specs have adopted this format.
+
+This doc at a minimum hopes to give spec authors more options/direction on how to do this and preferably defines a common format for all to use.
+
+### Why standardize
+
+- consistency across specs (for authors and tooling)
+- allow for generation of multiple outputs (wavedrom, table, src headers, etc)
+
+## Requirements/Features
+
+- human read/writeable
+  - concise definitions (ex: allow for arrayed registers)
+  - allow body/description of register to span multiple lines
+  - possibly multiple input options (xmlx, etc)
+- machine readable
+- CSR format should provide all the parameters needed to express any CSR
+- use existing OSS CSR definitions if possible
+- use existing OSS tooling if possible
+- linting
+- validation
+
+## Design
+
+design questions/considerations:
+
+- inventory how spec CSRs are currently defined
+- can we use existing definitions (wavedrom or riscv-debug-spec XML)
+- tooling to convert from existing CSR format (see above) to new format
+
+explorations:
+
+- convert riscv-debug-spec XML into different formats
+- convert wavedrom bitfield into different formats
+- convert bytefield-svg into different formats
+- generate wavedrom, bytefield-svg, asciidoc-table outputs
+
+## References
+
+### CSR
+
+formats:
+
+- [riscv-debug-spec XML](https://github.com/kbroch-rivosinc/riscv-debug-spec/tree/main/xml)
+- [wavedrom/bitfield](https://github.com/wavedrom/bitfield)
+- [IP-XACT](https://www.accellera.org/downloads/standards/ip-xact)
+- [SystemRDL](https://www.accellera.org/downloads/standards/systemrdl)
+- [Open Titan's HJSON](https://opentitan.org/book/doc/contributing/style_guides/hjson_usage_style.html)
+- https://github.com/esynr3z/corsair
+- https://github.com/Juniper/open-register-design-tool
+- [nasa-jpl regvue JSON](https://github.com/nasa-jpl/regvue/blob/main/schema/register-description-format.adoc)
+- https://github.com/sifive/duh
+- https://github.com/Deep-Symmetry/bytefield-svg
+
+tooling:
+
+- [PeakRDL](https://peakrdl.readthedocs.io/en/latest/)
+- [ipyxact](https://github.com/olofk/ipyxact)
+- [riscv-debug-spec registers.py](https://github.com/kbroch-rivosinc/riscv-debug-spec/blob/main/registers.py)
+- https://github.com/rggen/rggen
+
+### General
+
+- [jsonnet](https://jsonnet.org/)
+- [json5](https://json5.org/)
+- validation
+  - https://docs.python-cerberus.org/index.html
+  - https://docs.pydantic.dev/latest/