RISC-V Style guidelines

Whether you are creating a new extention or even a stand alone doc for RISC-V, follow these style guidelines to improve readability.

Basic formatting

Follow these basic formatting guidelines.

  • Use italic for new terms. The Atomic Layer Deposition is a layer-by-layer process that results in the deposition of thin films one atomic layer at a time in a highly controlled manner.

  • Use monospace for the following items:

  • Use monospace bold for the following items:

    • Hex numbers. Hex numbers start with 0x.

    • Binary numbers. Binary numbers start with 0b.

    • Non-base 10 literals

    • Non-base 10 number ranges

Do not use any special formatting for base 10.

Formatting guidelines for names

  • Instructions are lowercase (ld, c.lw)

  • Extensions are Capitialized (A, C, Zicsr)

  • CSR short names are lowercase (misa).

  • All of these names are in monospace.

CSR formatting

Use the following guidelines when you document a CSR:

  • The acronym CSR must always be capitalized.

  • When plural, lowercase the s. CSRs.

  • The word Register is capitalized in title, but lowercase in text. "Supervisor Status (sstatus) Register”. But “The sstatus register…”

  • When in doubt, use "CSR" to indicate the type of register. You can then intermingle CSR and register in the text. So "The misa CSR is used to…​" And then later in the paragraph, you can use "register". As in, "This register also does this other thing."

  • Avoid starting a sentence with a CSR name.

  • In a title, the format is “Long name (short name) Register. All other references in that section can use the short name, but it must be in monospace. So "Supervisor Status (sstatus) Register”. The rest of the references to that register can be "the sstatus CSR.

  • The short name is always lower case and monospace: sstatus.

  • As a general rule, whenever you use a term in tics, it should be followed by what the thing is to help with translation. So avoid statements similar to this one: “misa also helps distinguish different variants of a design.” And instead use this one: “The misa CSR also helps distinguish different variants of a design.”

  • Fields for registers are formatted in this style: register.FIELD. For example, sstatus.SPP.

Table formatting

Follow these formatting rules when you create a table.

  • Align tables to center with the options float="center" and align="center".

  • Use table header coding to indicate a header. Don’t use a different font, color, or any background indication.

  • Sort rows in either a logical order or by alphabetizing the rows and columns.

  • If your table is long or complicated, consider creating multiple tables. Remember that tables can be hard for screen readers to parse. If your table is complex, be sure that the contents are described in the text.

  • Use table captions to describe your table contents. Captions appear after the table and are controlled by the theme.

  • If you use footnotes in your table, make sure they appear immediately after the table.

Column header formatting

Follow these column header rules.

  • Use sentence case.

  • Write concise headings and omit articles (a, an, the).

  • Don’t end with punctuation, including a period, an ellipsis, or a colon.

  • Use table headings for the first column and the first row only.

Punctuation in tables

Follow these punctuation rules for tables.

  • If all cells in a table column are complete sentences, then end each cell with a period.

  • If all cells in a table column are sentence fragments, then do not use a period to end each cell.

  • If cells in a table column contain a mixture of complete and fragmented sentences, then first try to make them all parallel - either all complete sentences or all sentence fragments. However, if this approach is impractical, then punctuate each cell independently, and punctuate appropriate for that individual cell.

  • Do not end column headers with punctuation, including a period, an ellipsis, or a colon.