riscv/riscv-isa-manual

Rules for CSR and register usage

kersten1 opened this issue · 12 comments

kersten1 commented

CSR and Register are used somewhat interchangeably. What if we adopted these rules for usage?

  • CSR must always be capitalized.
  • Move first use of CSR in a chapter 1 - should include full text plus acronym. Control and Status Register (CSR).
  • When plural, lowercase the s. CSRs.
  • 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 para, you can use "register". As in, "This register also does this other thing."
  • 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 tics. So "Supervisor Status (sstatus) Register”. The rest of the references to that register can be "the sstatus CSR".
  • 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 like this: “misa also helps distinguish different variants of a design.” And instead use this: “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

I'm hopeful that this iteration contains all the comments :)

nick-knight commented

Control and State Register (CSR).

I think we prefer "status", not "state". I also don't think it's necessary to redefine the acronym in each chapter. I don't have strong opinions otherwise.

  • 👍1
kersten1 commented

@nick-knight Thanks! I updated the word.

About redefining in each section, I was thinking that it might come in handy when we start publishing HTML versions as I'm assuming each chapter will be on its own HTML page. However, could also link to definition in a glossary or else even add hover help that spells it out. I'm open for discussion!

nick-knight commented

My personal opinion is (and always has been) that the following text:

RISC-V defines a separate address space of 4096 Control and Status registers associated with each
hart.

hidden at the beginning of (now) Chapter 7, should be moved to Chapter 1. (As it currently stands, I think earlier uses of "CSR" are technically not yet defined.) The acronym could then be defined in Chapter 1. I think it's fair to trust the reader to read Chapter 1 first (and remember it).

allenjbaum commented
  • 👍1
kersten1 commented

@allenjbaum figured I'd take it in chunks. @nick-knight Okay so define CSR in chapter 1 and then first occurrence of an acronym in doc.

kasanovic commented

I would prefer to use CSR instead of register when clarifying the type of some object (e.g., "the misa CSR" rather than "the misa register"). We have other kinds of register that are not CSRs.

kersten1 commented

@kasanovic fair point! so first, how do I know which is a register and what is a specific CSR? Maybe I just need to pay attention to titles. I'm assuming that at least most of the instances of "register" that occur under a heading such as Machine-level CSRs are all CSRs. So looking at this para:

The misa CSR is a WARL read-write register reporting the ISA supported by the hart. This register
must be readable in any implementation, but a value of zero can be returned to indicate the misa
register has not been implemented, requiring that CPU capabilities be determined through a separate non-standard mechanism.

The first instance is correct - The misa CSR - but the instance of "misa register" should actually be "misa CSR"? What about "This register"?

Can the titles still use Register as long as they are under the CSR heading? So "Machine ISA (misa) Register" is fine? Just trying to figure out a best course of action here. I recommended using (for example) "misa register" because that seemed to be the most common usage. However, if CSR is more technically correct, then we should definitely move to that. Just might be a more significant change...

Can you confirm?

allenjbaum commented
gfavor commented
aamartin0000 commented

minor nit regarding @allenjbaum "... Fregs (pretend not to notice F0 is also the mask) and Vregs":

F0 has no special meaning in the floating-point registers. V0 is (usually, but not always) a mask register in the vector registers.

allenjbaum commented
kersten1 commented

moved issue to dev guide