Scheme for specification prose

[dhower-qc]

We've tried two methods to conditionally apply asciidoc source depending on parameters or equations.

First, we tried using ERB. It works fine but requires some basic knowledge of Ruby.

Second, we tried using a [when,"condition"] Asciidoc style. It works for asciidoctor.js because I made a plugin, but doesn't work with asciidoctor(-pdf) because there is no plugin there yet.

I'm not sold on either approach. More discussion is needed.

[dhower-qc]

@edolnx, @kersten1

Stepping up a level, there are several things we want to identify about each statement in the prose.

• The type of statement (normative, non-normative)
• Any conditions that apply for the statement
• A unique identifier for the statement that can be referenced throughout the database (e.g., for test plans, executable spec, etc.)

Given that, here is a strawman for how we might represent prose in the database:

For the prose:

The mimpid CSR provides a unique encoding of the version of the processor implementation. This register must be readable in any implementation, but a value of 0 can be returned to indicate that the field is not implemented. The Implementation value should reflect the design of the RISC-V processor itself and not any surrounding system.

The mimpid CSR is MXLEN bits long.

[NOTE] The format of this field is left to the provider of the architecture source code, but will often be printed by standard tools as a hexadecimal string without any leading or trailing zeros, so the Implementation value can be left-justified (i.e., filled in from most-significant nibble down) with subfields aligned on nibble boundaries to ease human readability.

description:
- type: spec # short for normative
  text: |
    The `mimpid` CSR provides a unique encoding of the version of the processor implementation.
  id: misa-01
- type: spec
  text: |
    This register must be readable in any implementation,
    but a value of 0 can be returned to indicate that the field is not implemented.
  misa-02
- type: spec
  text: |
    The Implementation value should reflect the design of the RISC-V processor itself
    and not any surrounding system.
  id: misa-03
- type: spec
  text: |
    The `mimpid` CSR is MXLEN (32) bits long.
  cond: XLEN == 32
  id: misa-04
- type: spec
  text: |
    The `mimpid` CSR is MXLEN (64) bits long.
  cond: XLEN == 64
  id: misa-05
- type: info # short for non-normative
  text: |
    The format of this field is left to the provider of the architecture source code,
    but will often be printed by standard tools as a hexadecimal string without any leading
    or trailing zeros, so the Implementation value can be left-justified (i.e., filled in from
    most-significant nibble down) with subfields aligned on nibble boundaries to ease human
    readability.
  id: misa-06

Things I like:

• Can generate config-specific docs from this data
• Can build robust testplans & implementations from this data

Things I don't like:

• Pretty verbose

Note that we can probably come up with a way to generate the ids so you would never have to hand-type those.

Thoughts?

[ThinkOpenly]

Those "id" fields might become a pain to maintain. Do they need to persist, forever associated with the text? If a statement gets split during editing, does the original "id" need to continue to be associated with each new statement? I guess there could be some CI magic that tried to maintain order, but even that seems challenging. (Maybe it's good that editing the spec will become very difficult, and require great attention to detail?)

[dhower-qc]

Yes, the ids will likely be a pain. We could lessen the pain somewhat by generating most of the IDs with CI, but that won't solve everything.

The idea is that the ids would be immutable and forever tied to a single specification requirement/note/etc. The benefit (which to me seems substantial) is that it gives us the ability to reference a statement unambiguously across spec versions. So, for example, we can "this certification test tests Requirement misa-05" rather than "this certification test tests the second sentence of the third paragraph of Priv Section 3.1.4 in manual release 20240412."

As such, if a statement gets split for some reason, I think that would generate two new ids. The ids would not imply any order; misa-01 does not necessarily come before misa-02 in the prose, giving us some flexibility to reorder the spec without touching ids.

I understand it is unreasonable to encode the spec in this form during development. That's why I propose that it be an encoding step after freeze. And after encoding/ratification, statement changes are hopefully rare.