Skip to content

Latest commit

 

History

History
134 lines (99 loc) · 4.98 KB

tagging_normative_rules.adoc

File metadata and controls

134 lines (99 loc) · 4.98 KB

How to Tag Normative Rules in the ISA Manuals

The ISA manuals contain a mix of normative and informative (AKA non-normative) content. We use AsciiDoctor’s anchor facility to tag normative text which is extracted by tools provided in the docs-resources GitHub repository to create machine-readable and human-readable representations of normative rules.

Tagging Normative Rules in RISC-V International Standards

First, please read the How to Tag Normative Rules in RISC-V International Standards for information that applies to all RISC-V International standards. This document provides information such as:

  • What exactly is a "normative rule"?

  • How does one add normative rule tags to the AsciiDoc files using the AsciiDoc anchor facility?

  • Ins and outs and gotchas when using the AsciiDoc anchor facility.

  • How are the normative rules extracted from the AsciiDoc files?

Tagging Normative Rules in ISA Manuals

Now that you’ve read How to Tag Normative Rules in RISC-V International Standards, here’s some information specific to tagging normative rules in the ISA manuals.

The ISA manual builds upon the anchor naming convention of a "norm:" prefix by following it with an enum identifying the ISA manual object type, another colon, one or more names describing the object(s) related to the tag, another colon and finally an ID that identifies the associated behavior. It looks like this (where <> delimit names, [] indicates optional, * means 0 or more, and _ is used to separate multiple object names if needed):

norm:<object-type>:<object-name>[_<object-name>]*:<id>

There are some cases (e.g., CSR field names) where there is a hierachy of object names and so there are additional colon-separated object-names. Here’s what it looks like with 2 hiearchy levels with a parent/child relationship:

norm:<object-type>:<parent-object-name>[_<parent-object-name>]*:<child-object-name>[_child-<object-name>]*:<id>
Note
 We aren’t too worried about having long tag names since they are invisible unless viewing the raw AsciiDoc source so don’t clutter the ISA manual output formats like PDFs. So, we’ve leaned in the direction of having longer names that provide information about what is being tagged.

The justification for this naming convention is:

  • Encourages consistency and regularity in names

  • Helps ensure anchor names are unique across both ISA manuals (they are in one global namespace)

  • Provides some information about which ISA objects (e.g., instructions, extensions, CSRs) are related to the tagged text

Naming Convention Details

The following table shows the supported ISA object types, the naming convention for them, and examples for each.

Format Description

Format norm:base:<base-name>:<id>
Example norm:base:rv32i:xregsz

One base ISA (rv32i/rv32e/rv64i)

Format norm:bases:<base-name>[_<base-name>]+:<id>
Example norm:bases:rv32i_rv64i:num-xregs

List of bases

Format norm:basegrp:<group-name>:<id>
Example norm:base:all:x0eq0

Named group of bases (e.g., rv32, all)

Format norm:ext:<ext-name>:<id>
Example norm:Zilsd_reg_pairs

Single extension

Format norm:exts:<ext-name>[_<ext-name>]:<id>
Example norm:exts:F_D:num-fregs

List of extensions

Format norm:extgrp:<group-name>:<id>
Example norm:extgrp:security:attacks

Named group of extensions

Format norm:enc:insttable:<inst-name>
Example norm:enc:insttable:add

Table cell for instruction encoding

Format norm:inst:<inst-name>:<id>
Example norm:add_op

Single instruction

Format norm:insts:<inst-name>[_<inst-name>]+:<id>
Example norm:add_sub_overflow

List of instructions

Format norm:instgrp:<group-name>:<id>
Example norm:instgrp:division:div_by_zero

Named group of insts (e.g., branch, load)

Format norm:csr:<csr-name>:<id>
Example norm:misa_sz

Single CSR

Format norm:csrs:<csr-name>[_<csr-name>]+:<id>
Example norm:csrs:mstatus_sstatus:sz

List of CSRs

Format norm:csrgrp:<group-name>:<id>
Example norm:csrgrp:status:sz

Named group of CSRs

Format norm:csrfld:<csr-name>:<field-name>:<id>
Example norm:misa_mxl_base_int_sz

Single CSR field

Format norm:csrflds:<csr-name>:<field-name>[_<field-name>]+:<id>
Example norm:csrflds:hip:vseip_vseie:ro

List of fields in the same CSR

Format norm:csrsfld:<csr-name>[_<csr-name>]+:<field-name>:<id>
Example norm:csrsfld:vsip_vsie:ssi:operation

Same field in the listed CSRs

Format norm:param:<param-name>:<id>
Example norm:endianness_little_or_big

Single parameter

Format norm:params:<param-name>[_<param-name>]+:<id>
Example norm:params:mutable-misa-a_mutable-misa-b:operation

List of parameters

Format norm:paramgrp:<group-name>:<id>
Example norm:paramgrp:mtval-va-report:operation

Named group of parameters