Changes since v0.5:

 - #2095: Fix syntax errors and inconsistencies in documentation
 - #2071: Clarify bit widths in documentation examples
 - #2015: Use UnsafeCell in registers (see issue #2005)
 - #1939: Make the Field::mask and FieldValue::mask fields private
 - #1823: Allow large unsigned values as bitmasks + add bitmask! helper macro
 - #1554: Allow lifetime parameters for `register_structs! { Foo<'a> { ..`
 - #1661: Add `Aliased` register type for MMIO with differing R/W behavior

Thanks to @namyoonw, @brghena, @dabross, @gendx, @hudson-ayers, and @pfmooney
for contributions, fixes, and testing!

Closes #2138.

This partially reverts commit fed7a58 ("Make the Field::mask
and FieldValue::mask fields private.") introduced through GitHub pull
request tock#1939.

In order to be able to implement atomic RISC-V CSR bit-field-set and
bit-field-clear operations which operate on tock-register's Fields,
access to the Field::mask field is required.

Signed-off-by: Leon Schuermann <[email protected]>

2512: rv32i: use atomic CSR instructions for rv32i::support::atomic r=phil-levis a=lschuermann

### Pull Request Overview

This pull request contains a bunch of cleanly separated commits, enabling us to switch the `rv32i::support::atomic` to use RISC-V atomic CSR instructions.

Previously, the mstatus CSR was first read and then written to clear the machine mode interrupts. If an interrupt would arrive between these instructions, it could have changed mstatus, whereas this function would write back the previously read and modified register contents. Furthermore, if an interrupt handler would have cleared MIE between reading and writing the CSR, this function would set MIE again after execution of the passed in function.

As far as I can tell, this is not a real issue currently, due to the way interrupt handlers work and the fact that rv32i::support::atomic is already executed when the CPU is already in machine mode. However, it's best not to rely on this and use proper RISC-V instructions.

Additionally, this eliminates 7 instructions and one branch on rustc 1.52.0-nightly.

The other commits leading up to this are:

- riscv-csr: support atomic read/write & bit-field-set/clear ops

  Add atomic_replace, read_and_set_bits and read_and_clear_bits methods to the RISC-V CSR register wrappers to support the corresponding CSRRW, CSRRS and CSRRC RISV-C instructions.

  Using the atomic instructions can be required to prevent race conditions in interrupt contexts and context switches. Furthermore, using a combined read and write can often save instructions compared to a sequential read and write.

  The CSRR rd, csr and CSRW csr, rs1 instructions used in the RISC-V CSR register wrapper currently are assembler pseudo-instructions encoded as CSRRS rd, csr, x0 and CSRRW x0, csr, rs1 respectively (see RISC-V Specification v2.2, Volume I, 2.8 Control and Status Register Instructions).

- tock-registers: make Field::mask field public

  This partially reverts commit fed7a58 ("Make the Field::mask and FieldValue::mask fields private.") introduced through GitHub pull request tock#1939.

  In order to be able to implement atomic RISC-V CSR bit-field-set and bit-field-clear operations which operate on tock-register's Fields, access to the Field::mask field is required.

- tock-registers: fix Copy and Clone implementation on Field

  A Field contains a PhantomData over a generic R: RegisterLongName, and a PhantomData<R> is copyable regardless of whether R: Copy. However, using #[derive(Copy, Clone)] will generate

      #[automatically_derived]
      #[allow(unused_qualifications)]
      impl<T: ::core::marker::Copy + IntLike,
           R: ::core::marker::Copy + RegisterLongName>
              ::core::marker::Copy for Field<T, R> {}

  and hence Field will only implement Copy when R: Copy.

  Manually implementing Clone and Copy works around this issue. See rust-lang/rust#26925 for more information on this issue.

- riscv-csr: provide atomic read and set/clear field methods

  Add atomic read and set/clear methods for Fields on RISC-V CSR register wrappers. This wraps the read_and_set_bits and read_and_clear_bits into a more developer-friendly method that is compatible with the tock-registers types.


### Testing Strategy

This pull request was tested by compiling and looking at the generated assembly, as well as running litex/sim in Verilator and looking at the instruction trace.


### TODO or Help Wanted

N/A


### Documentation Updated

- [x] ~Updated the relevant files in `/docs`, or~ no updates are required.

### Formatting

- [x] Ran `make prepush`.


Co-authored-by: Leon Schuermann <[email protected]>

This partially reverts commit 89505ae ("Make the Field::mask
and FieldValue::mask fields private.") introduced through GitHub pull
request tock/tock#1939.

In order to be able to implement atomic RISC-V CSR bit-field-set and
bit-field-clear operations which operate on tock-register's Fields,
access to the Field::mask field is required.

Signed-off-by: Leon Schuermann <[email protected]>

This partially reverts commit fed7a58 ("Make the Field::mask
and FieldValue::mask fields private.") introduced through GitHub pull
request #1939.

In order to be able to implement atomic RISC-V CSR bit-field-set and
bit-field-clear operations which operate on tock-register's Fields,
access to the Field::mask field is required.

BUG=none
TEST=make

Signed-off-by: Leon Schuermann <[email protected]>
(cherry picked from commit 3fba562)
Change-Id: I01d414d8b317999387eca785bc26dbb0c2304b71

Changes since v0.5:

 - #2095: Fix syntax errors and inconsistencies in documentation
 - #2071: Clarify bit widths in documentation examples
 - #2015: Use UnsafeCell in registers (see issue #2005)
 - #1939: Make the Field::mask and FieldValue::mask fields private
 - #1823: Allow large unsigned values as bitmasks + add bitmask! helper macro
 - #1554: Allow lifetime parameters for `register_structs! { Foo<'a> { ..`
 - #1661: Add `Aliased` register type for MMIO with differing R/W behavior

Thanks to @namyoonw, @brghena, @dabross, @gendx, @hudson-ayers, and @pfmooney
for contributions, fixes, and testing!

Closes #2138.

BUG=none
TEST=make

(cherry picked from commit 72a1e1e)
Change-Id: Ia2dbf69c950e3581a43f5d6601a5cf94abace750