Allow CSRRS/C to read CLEN-wide values

src/insns/csrr_32bit.adoc

@@ -30,31 +30,52 @@ endif::[]
 Synopsis::
 CSR access (CSRRWI, CSRRS, CSRRSI, CSRRC, CSRRCI) 32-bit encodings
 
-Register Source Mnemonics::
-`csrr[s|c] rd, rs1, csr`
-
-Immediate Source Mnemonics::
-`csrr[w|s|c]i rd, imm, csr`
+Mnemonics for accessing capability CSRs at CLEN-wide aliases::
+`csrrs  cd, rs1, csr` +
+`csrrc  cd, rs1, csr` +
+`csrrwi cd, imm, csr` +
+`csrrsi cd, imm, csr` +
+`csrrci cd, imm, csr`
+
+Mnemonics for accessing XLEN-wide CSRs or capability CSRs at XLEN-wide aliases::
+`csrrs  rd, rs1, csr` +
+`csrrc  rd, rs1, csr` +
+`csrrwi rd, imm, csr` +
+`csrrsi rd, imm, csr` +
+`csrrci rd, imm, csr`
 
 Encoding::
 include::wavedrom/csr-instr.adoc[]
 
 Description::
 These are standard RISC-V CSR instructions with extended functionality for
-accessing CLEN-wide CSRs, such as <<mtvec>>/<<mtvecc>> which can be
+accessing CLEN-wide CSRs, such as <<mtvec>>/<<mtvecc>>, which can be
 accessed through either the RISC-V address or the capability address alias.
 +
-Unlike <<CSRRW>> these instruction perform the same update to CLEN-wide CSRs
- to either the XLEN or CLEN-wide alias as they only every perform an XLEN-wide update.
- Where a CLEN-wide CSR is updated, through either alias, the final address is determined
- as defined by RISC-V for these instructions. The metadata and tag are updated
- as defined in xref:extended_CSR_writing[xrefstyle=short].
+Unlike <<CSRRW>>, these instructions only update the address field and the tag
+as defined in xref:extended_CSR_writing[xrefstyle=short] when writing
+capability CSRs regardless of the CSR alias used. The final address to
+write to the capability CSR is determined as defined by RISC-V for these
+instructions.
 +
 See xref:aliased_CSRs[xrefstyle=short] for a list of CLEN-wide CSRs and
 xref:extended_CSR_writing[xrefstyle=short] for the action taken on writing an XLEN-wide value to each one.
 +
+If `cd` is `c0` (or `rd` is `x0`), then <<CSRRWI>> shall not read the CSR and
+and shall not cause any of the side effects that might occur on a CSR read. If
+`rs1` is `x0`, then <<CSRRS>>, <<CSRRC>>, <<CSRRSI>> and <<CSRRCI>> will not
+write to the CSR at all, and so shall not cause any of the side effects that
+might otherwise occur on a CSR write.
++
+The assembler pseudoinstruction to read a capability CSR at its CLEN alias,
+`csrr rd, csr`, is encoded as `csrrs cd, csr, c0`.
++
 Access to XLEN-wide CSRs from other extensions is as specified by RISC-V.
 
+NOTE: If `rs1` is `x0` and the CSR accessed is a capability, then <<CSRRS>>,
+<<CSRRC>>, <<CSRRSI>> and <<CSRRCI>> do not write so no representability check
+is needed in this case.
+
 Permissions::
 All non-user mode accessible CSRs require <<asr_perm>>, including existing RISC-V CSRs.
 

src/insns/csrrw_32bit.adoc

@@ -12,18 +12,18 @@ endif::[]
 Synopsis::
 CSR access (CSRRW) 32-bit encodings
 
-Mnemonic (XLEN-wide target, and XLEN-wide aliases of CLEN-wide CSRs)::
-`csrrw rd, rs1, csr`
-
-Mnemonics (CLEN-wide target)::
+Mnemonics for accessing capability CSRs at CLEN-wide aliases::
 `csrrw cd, cs1, csr`
 
+Mnemonics for accessing XLEN-wide CSRs or capability CSRs at XLEN-wide aliases::
+`csrrw rd, rs1, csr`
+
 Encoding::
 include::wavedrom/csrw-instr.adoc[]
 
 Description::
 This is a standard RISC-V CSR instructions with extended functionality for
-accessing CLEN-wide CSRs, such as <<mtvec>>/<<mtvecc>> which can be
+accessing CLEN-wide CSRs, such as <<mtvec>>/<<mtvecc>>, which can be
 accessed through either the RISC-V address or the capability address alias.
 +
 See xref:aliased_CSRs[xrefstyle=short] for a list of CLEN-wide CSRs and
@@ -33,6 +33,12 @@ CSRRW writes `cs1` to the CLEN-wide alias of extended CSRs, and reads a full cap
 +
 CSRRW writes `rs1` to the XLEN-wide alias of extended CSRs, and reads the address field into `rd`.
 +
+If `cd` is `c0` (or `rd` is `x0`), then the instruction shall not read the CSR
+and shall not cause any of the side effects that might occur on a CSR read.
++
+The assembler pseudoinstruction to write a capability CSR at its CLEN alias,
+`csrw csr, cs1`, is encoded as `csrrw c0, csr, cs1`.
++
 Access to XLEN-wide CSRs from other extensions is as specified by RISC-V.
 
 

src/riscv-integration.adoc

@@ -334,15 +334,21 @@ whole CSR with the CLEN width register operand.
 
 There are special rules for updating specific CLEN-wide CSRs as shown in <<extended_CSR_writing>>.
 
-{non-csrrw-and} specify *x* registers and so only access the address field
-of the capability when specifying a capability CSR such as <<mtvecc>>.
-They calculate the final address using the standard
-RISC-V behaviour (set bits, clear bits etc.) and that final address is
-updated in the capability. The update typically uses the semantics of a <<CSETADDR>>
-instruction which clears the tag if the capability is sealed, or if the
-updated address is not representable. <<extended_CSR_writing>> shows the
+When <<CSRRS>> and <<CSRRC>> instructions are accessing a capability width CSR,
+such as <<mtvecc>>, then the destination operand is a *c* register and the
+source operand is an *x* register. Therefore, the instructions atomically read
+CLEN bits from the CSR, calculate the final address using standard RISC-V
+behaviour (set bits, clear bits, etc), and that final address is written to the
+CSR capability's address field. The update typically uses the semantics of a
+<<CSETADDR>> instruction which clears the tag if the capability is sealed, or
+if the updated address is not representable. <<extended_CSR_writing>> shows the
 exact action taken for each capability width CSR.
 
+The <<CSRRWI>>, <<CSRRSI>> and <<CSRRCI>> variants are similar to <<CSRRW>>,
+<<CSRRS>>, and <<CSRRC>> respectively, when accessing a capability width CSR
+except that they update the capability's address only using an XLEN-bit value
+obtained by zero-extending a 5-bit unsigned immediate field.
+
 All CSR instructions cause CHERI exceptions if the <<pcc>> does not grant
 <<asr_perm>> and the CSR accessed is privileged.