Skip to content

normative-rules.md

Latest commit

 

History

History
118 lines (95 loc) · 7.44 KB

normative-rules.md

File metadata and controls

118 lines (95 loc) · 7.44 KB

How to Tag Normative Rules in RISC-V International Standards

What is a Normative Rule?

Normative rules specify the behaviors an implementation must meet in order to be compliant with the standard. Each normative rule can be thought of as a complete individual testable behavior. In some cases, normative rules allow a plurality of acceptable implementations. These are called "parameters" and can be thought of as a special case of a normative rule.

Examples of Normative Rules:

ISA Manual Text
"For RV32I, the 32 x registers are each 32 bits wide, i.e., XLEN=32."
"Register x0 is hardwired with all bits equal to 0."
"ADDI adds the sign-extended 12-bit immediate to register rs1."
"M-mode code can access all CSRs at lower privilege levels."

Examples of Parameter Normative Rules:

ISA Manual Text Type Allowed Values
"The EEI will define whether the memory system is little-endian or big-endian." Enum little or big
"The misa register must be readable in any implementation, but a value of zero can be returned to indicate the misa register has not been implemented." Boolean true/false
"If misa is nonzero, the MXL field indicates the effective XLEN in M-mode, a constant termed MXLEN." Integer 32 or 64

Extracting Normative Rules

RISC-V International standards are written in an open-source markup language known as AsciiDoc. If normative rules are not explicitly listed in the visible content of a standard (usually in tables with a unique ID for each normative rule), the AsciiDoc anchor facility is used to "tag" normative text. This latter case is the focus of the remainder of this document.

When normative rules aren't explicitly listed by a standard, it is likely the standard was written without easy identification of normative rules in mind. This can lead to multiple normative rules being located in one tag (tag = anchored section of normative text) known as a "many:1" mapping (many normative rules mapped to one tag) or a normative rule needing to reference multiple tags known as a "1:many" mapping (one normative rule mapped to multiple tags). Here's examples of these cases:

  • "many:1" (normative rules for ANDI, ORI, and XORI instructions mapped to one tag)
    ANDI, ORI, XORI are logical operations that perform bitwise AND, OR, and XOR on register rs1 and the sign-extended 12-bit immediate and place the result in rd.
  • "1:many"
    TBD: waiting for ideal example

Quite often there is a "1:1" mapping between normative rules and tags, but not always! Because of this "not always" reality, standards provide YAML files that provide the mapping between normative rules and tags. This repository contains a simple Ruby script that uses these YAML files to create the canonical list of normative rules for its associated standard. This script can output these normative rules in formats suitable for both human-friendly and machine-readable formats.

AsciiDoc Anchor Background

AsciiDoc provides facilities to create invisible anchors associated with an entire paragraph or portions of a paragraph. These anchors are only visible in raw AsciiDoc files and are invisible in the PDF and GitHub AsciiDoc previewer. Each "tag" added to an AsciiDoc file to indentify normative text (remember, not always 1:1 mapping from normative rules to tags) has an associated anchor name. These anchor names must be unique across all the AsciiDoc files used by a particular standard but aren't required to be unique across standards. Each RISC-V standard defines the naming convention of these anchor names but the anchor names must start with the prefix of "norm:" so they can be readily located by tools.

AsciiDoc supports several styles of anchors:

  • inline anchor such as:
    We must [#goal]#free the world#.

  • paragraph anchor such as:

    [[foo]]
    This is an anchor for the entire paragraph.

    This isn't part of the anchor since it is the next paragraph.

  • You must use the paragraph anchor for table cells, list items, or description list terms

    • For table cells and list items, put the anchor before its associated text as follows:
      • Table cell

      | [[foo]] Here are the table cell contents | next cell

      • List item

      * [[foo]] Here is the list item

    • For description list terms (e.g., Apples, Oranges), put the anchor immediately after the term on its own line as follows:

      Apples::
      [[apple-colors]]
      Typically be red, yellow, or green.

      Oranges:: Generally orange in color

      Bananas::
      [[banana-color]]
      Generally yellow in color

      • These won't work
      • Bananas:: [[banana-color]] Generally yellow in color
      • [[banana-color]] Bananas:: Generally yellow in color
      • [[banana-color]]
        Bananas::
        Generally yellow in color

Naming restrictions:

  • Start anchor names with a letter and use : to separate fields in the anchor name. No spaces allowed in name.
  • Use underscores to separate lists of items between colons (e.g., :insts:add_sub) since RISC-V uses - in some names (e.g., R-type).
  • Replace . in items with - (e.g., fence.tso becomes fence-tso) so all anchors types used work properly (see https://docs.asciidoctor.org/asciidoc/latest/attributes/id/#block-assignment for details).

If you'd like to get more detailed AsciiDoc information on anchors, please read:

Adding anchors into AsciiDoc files

  1. Anchor to part of a paragraph

    Syntax: [#<anchor-name>]# ... #
    Example: Here is an example of [#foo]#anchoring part# of a paragraph and can have [#bar]#multiple anchors# if needed.
    Tagged text: anchoring part and multiple anchors

    Limitations:

    • Can't anchor text across multiple paragraphs.
    • Can't use in table cells, list items, or description list items (see #3 below for work-around).
    • Must have text next to the 2nd hash symbol (i.e., can't have newline after [#<anchor-name]#).
    • Can't put inside admonitions such as [NOTE] (see #5 below for solution).
    • Can't have . in anchor-name (replace with -)

  2. Anchor to entire paragraph

    Syntax: [[<anchor-name]]
    Example: [[zort]]
    Here is an example of anchoring a whole paragraph.
    Tagged text: Entire paragraph

  3. Anchor to entire table cell, list entry, or description list entry

    Example: | Alan Turing | [[Alan_Turing_Birthday]] June 23, 1912 | London
    Tagged text: None (just creates hyperlink to anchor in table/list so not so useful)

    Limitations:

    • Anchor must be to entire contents of cell/item.
    • Only one anchor per cell/item.

  4. Anchor inside admonition (e.g. [NOTE]):

  • Must use [[<anchor-name]] before each paragraph (with unique anchor names of course) being tagged
  • Can't use [#<anchor-name]#Here's some note text.# since it just shows up in HTML as normal text
  • Don't put [[<<anchor-name]] before the entire admonition (e.g., before [NOTE]) to apply to entire admonition (one or more paragraphs) since it will just create a hyperlink with no associated text.