== CSRs

The RISC-V privileged specification affords flexibility as to which CSRs are implemented, and how they behave. This section documents the concrete behaviour of Hazard3's standard and nonstandard M-mode CSRs, as implemented.

NOTE: All CSR addresses not listed in this section are unimplemented. Accessing an unimplemented CSR will cause an illegal instruction exception (`mcause` = 2). This includes all U-mode and S-mode CSRs.

All CSRs are 32-bit; MXLEN is fixed at 32 bits on Hazard3.


=== Standard M-mode CSRs

IMPORTANT: The https://github.com/riscv/riscv-isa-manual/releases/download/Ratified-IMFDQC-and-Priv-v1.11/riscv-privileged-20190608.pdf[RISC-V Privileged Specification] should be your primary reference for writing software to run on Hazard3. This section specifies those details which are left implementation-defined by the RISC-V Privileged Specification, for sake of completeness, but portable RISC-V software should not rely on these details.

==== mvendorid

Address: `0xf11`

Vendor identifier. Read-only, configurable constant.

[cols="10h,20h,~", options="header"]
|===
| Bits | Name | Description
| 31:0 | - | Should contain either all-zeroes, or a valid JEDEC JEP106 vendor ID using the encoding in the RISC-V specification (_not_ the same as a JTAG IDCODE)
|===

==== marchid

Address: `0xf12`

Architecture identifier for Hazard3. Read-only, constant.

[cols="10h,20h,~", options="header"]
|===
| Bits | Name | Description
| 31 | - | 0: Open-source implementation
| 30:0 | - | 0x1b (decimal 27): the https://github.com/riscv/riscv-isa-manual/blob/master/marchid.md[registered] architecture ID for Hazard3
|===


==== mimpid

Address: `0xf13`

Implementation identifier. Read-only, configurable constant.

[cols="10h,20h,~", options="header"]
|===
| Bits | Name | Description
| 31:0 | - | Should contain the git hash of the Hazard3 revision from which the processor was synthesised, or all-zeroes.
|===

==== mhartid

Address: `0xf14`

Hart identification register. Read-only, configurable constant.

[cols="10h,20h,~", options="header"]
|===
| Bits | Name | Description
| 31:0 | - | Hazard3 cores possess only one hardware thread, so this is a unique per-core identifier, assigned consecutively from 0.
|===

==== mstatus

Address: `0x300`

The below table lists the fields which are _not_ hardwired to 0:

[cols="10h,20h,~", options="header"]
|===
| Bits | Name | Description
| 12:11 | `mpp` | Previous privilege level. Always `0x3`, indicating M-mode.
| 7 | `mpie` | Previous interrupt enable. Readable and writable. Is set to the current value of `mstatus.mie` on trap entry. Is set to 1 on trap return.
| 3 | `mie` | Interrupt enable. Readable and writable. Is set to 0 on trap entry. Is set to the current value of `mstatus.mpie` on trap return.
|===

==== mstatush

Address: `0x310`

This CSR is present, but it is entirely hardwired to zero. Its presence is required for compliance.

==== misa

Address: `0x301`

Read-only, constant. Value depends on which ISA extensions Hazard3 is configured with. The table below lists the fields which are _not_ always hardwired to 0:

[cols="10h,20h,~", options="header"]
|===
| Bits | Name | Description
| 31:30 | `mxl` | Always `0x1`. Indicates this is a 32-bit processor.
| 23 | `x` | 1 if the core is configured to support trap-handling, otherwise 0. Hazard3 has nonstandard CSRs to enable/disable external interrupts on a per-interrupt basis, see <<reg-meie0>> and <<reg-meip0>>. The `misa.x` bit must be set to indicate their presence. Hazard3 does not implement any custom instructions.
| 12 | `m` | 1 if the M extension is present, otherwise 0.
| 2 | `c` | 1 if the C extension is present, otherwise 0.
|===

==== medeleg

Address: `0x302`

Unimplemented, as only M-mode is supported. Access will cause an illegal instruction exception.

==== mideleg

Address: `0x303`

Unimplemented, as only M-mode is supported. Access will cause an illegal instruction exception.

==== mie

Address: `0x304`

Interrupt enable register. Not to be confused with `mstatus.mie`, which is a global enable, having the final say in whether any interrupt which is both enabled in `mie` and pending in `mip` will actually cause the processor to transfer control to a handler.

The table below lists the fields which are _not_ hardwired to 0:

[cols="10h,20h,~", options="header"]
|===
|Bits | Name | Description
| 11 | `meie` | External interrupt enable. Hazard3 has internal custom CSRs to further filter external interrupts, see <<reg-meie0>>.
| 7 | `mtie` | Timer interrupt enable. A timer interrupt is requested when `mie.mtie`, `mip.mtip` and `mstatus.mie` are all 1.
| 3 | `msie` | Software interrupt enable. A software interupt is requested when  `mie.msie`, `mip.mtip` and `mstatus.mie` are all 1.
|===

NOTE: RISC-V reserves bits 16+ of `mie`/`mip` for platform use, which Hazard3 could use for external interrupt control. On RV32I this could only control 16 external interrupts, so Hazard3 instead adds nonstandard interrupt enable registers starting at <<reg-meie0>>, and keeps the upper half of `mie` reserved.

==== mip

Address: `0x344`

Interrupt pending register. Read-only.

NOTE: The RISC-V specification lists `mip` as a read-write register, but the bits which are writable correspond to lower privilege modes (S- and U-mode) which are not implemented on Hazard3, so it is documented here as read-only.

The table below lists the fields which are _not_ hardwired to 0:

[cols="10h,20h,~", options="header"]
|===
|Bits | Name | Description
| 11 | `meip` | External interrupt pending. When 1, indicates there is at least one interrupt which is asserted (hence pending in <<reg-meip0>>) and enabled in <<reg-meie0>>.
| 7 | `mtip` | Timer interrupt pending. Level-sensitive interrupt signal from outside the core. Connected to a standard, external RISC-V 64-bit timer.
| 3 | `msip` | Software interrupt pending. In spite of the name, this is not triggered by an instruction on this core, rather it is wired to an external memory-mapped register to provide a cross-hart level-sensitive doorbell interrupt.
|===

NOTE: Hazard3 assumes interrupts to be level-sensitive at system level. Bits in `mip` are cleared by servicing the requestor and causing it to deassert its interrupt request.

==== mtvec

Address: `0x305`

Trap vector base address. Read-write. Exactly which bits of `mtvec` can be modified (possibly none) is configurable when instantiating the processor, but by default the entire register is writable. The reset value of `mtvec` is also configurable.

[cols="10h,20h,~", options="header"]
|===
|Bits | Name | Description
| 31:2 | `base` | Base address for trap entry. In Vectored mode, this is _OR'd_ with the trap offset to calculate the trap entry address, so the table must be aligned to its total size, rounded up to a power of 2. In Direct mode, `base` is word-aligned.
| 0 | `mode` | 0 selects Direct mode -- all traps (whether exception or interrupt) jump to `base`. 1 selects Vectored mode -- exceptions go to `base`, interrupts go to `base \| mcause << 2`.
|===

NOTE: In the RISC-V specification, `mode` is a 2-bit write-any read-legal field in bits 1:0. Hazard3 implements this by hardwiring bit 1 to 0.

NOTE: Hazard3 has an additional nonstandard vectoring mode, where external interrupts are each separated into distinct vectors and `mcause` values. This is enabled through the implementation-defined control register, <<reg-midcr>>, since the RISC-V specification reserves `mtvec.mode == 2, 3` for future standard use.

==== mcounteren

Address: `0x306`

Unimplemented, as only M-mode is supported. Access will cause an illegal instruction exception.

Not to be confused with <<reg-mcountinhibit>>.

==== mscratch

Address: `0x340`

Read-write 32-bit register. No specific hardware function -- available for software to swap with a register when entering a trap handler.

==== mepc

Address: `0x341`

Exception program counter. When entering a trap, the current value of the program counter is recorded here. When executing an `mret`, the processor jumps to `mepc`. Can also be read and written by software.

On Hazard3, bits 31:1 of `mepc` are capable of holding all 31-bit values. Bit 0 is hardwired to 0, as per the specification.

All traps on Hazard3 are precise. For example, a load/store bus error will set `mepc` to the exact address of the load/store instruction which encountered the fault.

==== mcause

Address: `0x342`

Exception cause. Set when entering a trap to indicate the reason for the trap. Readable and writable by software.

NOTE: On Hazard3, most bits of `mcause` are hardwired to 0. Only bit 31, and enough least-significant bits to index all exception and all interrupt causes (at least four bits), are backed by registers. Only these bits are writable; the RISC-V specification only requires that `mcause` be able to hold all legal cause values.

The most significant bit of `mcause` is set to 1 to indicate an interrupt cause, and 0 to indicate an exception cause. The following interrupt causes may be set by Hazard3 hardware:

[cols="10h,~", options="header"]
|===
| Cause | Description
| 3 | Software interrupt (`mip.msip`)
| 7 | Timer interrupt (`mip.mtip`)
| 11 | External interrupt (`mip.meip`)
|===

Numbers >16 are used for to disambiguate between external IRQs when expanded vectoring is enabled -- see <<reg-midcr>>.

The following exception causes may be set by Hazard3 hardware:

[cols="10h,~", options="header"]
|===
| Cause | Description
| 1 | Instruction access fault
| 2 | Illegal instruction
| 3 | Breakpoint
| 4 | Load address misaligned
| 5 | Load access fault
| 6 | Store/AMO address misaligned
| 7 | Store/AMO access fault
| 11 | Environment call
|===

NOTE: Not every instruction fetch bus cycle which returns a bus error leads to an exception. Hazard3 prefetches instructions ahead of execution, and associated bus errors are speculated through to the point the processor actually attempts to decode the instruction. Until this point, the error can be flushed by a branch, with no ill effect.

==== mtval

Address: `0x343`

Hardwired to 0.

==== pmpcfg0...3

Address: `0x3a0` through `0x3a3`

Unimplemented. Access will cause an illegal instruction exception.

==== pmpaddr0...15

Address: `0x3b0` through `0x3bf`

Unimplemented. Access will cause an illegal instruction exception.

==== mcycle

Address: `0xb00`

Lower half of the 64-bit cycle counter. Readable and writable by software. Increments every cycle, unless `mcountinhibit.cy` is 1, or the processor is in Debug Mode (as <<reg-dcsr>>.`stopcount` is hardwired to 1).

If written with a value `n` and read on the very next cycle, the value read will be exactly `n + 1` (ignoring wrapping).

==== mcycleh

Address: `0xb80`

Upper half of the 64-bit cycle counter. Readable and writable by software. Increments every time `mcycle` wraps from `0xffffffff` to `0x00000000` upon increment.

==== minstret

Address: `0xb02`

Lower half of the 64-bit instruction retire counter. Readable and writable by software. Increments with every instruction exectued, unless `mcountinhibit.ir` is 1, or the processor is in Debug Mode (as <<reg-dcsr>>.`stopcount` is hardwired to 1).

==== minstreth

Address: `0xb82`

Upper half of the 64-bit instruction retire counter. Readable and writable by software. Increments every time `minstret` wraps from `0xffffffff` to `0x00000000` upon increment.

==== mhpmcounter3...31

Address: `0xb03` through `0xb1f`

Hardwired to 0.

==== mhpmcounter3...31h

Address: `0xb83` through `0xb9f`

Hardwired to 0.


[[reg-mcountinhibit]]
==== mcountinhibit

Address: `0x320`

Counter inhibit. Read-write. The table below lists the fields which are _not_ hardwired to 0:

[cols="10h,20h,~", options="header"]
|===
| Bits | Name | Description
| 2 | `ir` | When 1, inhibit counting of `minstret`/`minstreth`
| 0 | `cy` | When 1, inhibit counting of `mcycle`/`mcycleh`
|===

==== mhpmevent3...31

Address: `0x323` through `0x33f`

Hardwired to 0.

==== tselect

Address: `0x7a0`

Unimplemented. Reads as 0, write causes illegal instruction exception.

==== tdata1...3

Address: `0x7a1` through `0x7a3`

Unimplemented. Access will cause an illegal instruction exception.

=== Standard Debug Mode CSRs

This section describes the Debug Mode CSRs, which are follow the 0.13.2 RISC-V debug specification. The <<debug-chapter>> section gives more detail on the remainder of Hazard3's debug implementation, including the Debug Module.

All Debug Mode CSRs are 32-bit; DXLEN is always 32.

[[reg-dcsr]]
==== dcsr

Address: `0x7b0`

Debug control and status register. Access outside of Debug Mode will cause an illegal instruction exception. Relevant fields are implemented as follows:

[cols="10h,20h,~", options="header"]
|===
| Bits | Name | Description
| 31:28 | `xdebugver` | Hardwired to 4: external debug support as per RISC-V 0.13.2 debug specification.
| 15 | `ebreakm` | When 1, `ebreak` instructions will break to Debug Mode instead of trapping in M mode.
| 11 | `stepie` | Hardwired to 0: no interrupts are taken during hardware single-stepping.
| 10 | `stopcount` | Hardwired to 1: `mcycle`/`mcycleh` and `minstret`/`minstreth` do not increment in Debug Mode.
| 9 | `stoptime` | Hardwired to 1: core-local timers don't increment in debug mode. This requires cooperation of external hardware based on the halt status to implement correctly.
| 8:6 | `cause` | Read-only, set by hardware -- see table below.
| 2 | `step` | When 1, re-enter Debug Mode after each instruction executed in M-mode.
| 1:0 | `prv` | Hardwired to 3, as only M-mode is implemented.
|===

Fields not mentioned above are hardwired to 0.

Hazard3 may set the following `dcsr.cause` values:

[cols="10h,~", options="header"]
|===
| Cause | Description
| 1 | Processor entered Debug Mode due to an `ebreak` instruction executed in M-mode.
| 3 | Processor entered Debug Mode due to a halt request, or a reset-halt request present when the core reset was released.
| 4 | Processor entered Debug Mode after executing one instruction with single-stepping enabled.
|===

Cause 5 (`resethaltreq`) is never set by hardware. This event is reported as a normal halt, cause 3. Cause 2 (trigger) is never used because there are no triggers. (TODO?)

==== dpc

Address: `0x7b1`

Debug program counter. When entering Debug Mode, `dpc` samples the current program counter, e.g. the address of an `ebreak` which caused Debug Mode entry. When leaving debug mode, the processor jumps to `dpc`. The host may read/write this register whilst in Debug Mode.

==== dscratch0

Address: `0x7b2`

Not implemented. Access will cause an illegal instruction exception.

To provide data exchange between the Debug Module and the core, the Debug Module's `data0` register is mapped into the core's CSR space at a read/write M-custom address -- see <<reg-dmdata0>>.

==== dscratch1

Address: `0x7b3`

Not implemented. Access will cause an illegal instruction exception.

=== Custom CSRs

These are all allocated in the space `0xbc0` through `0xbff` which is available for custom read/write M-mode CSRs, and `0xfc0` through `0xfff` which is available for custom read-only M-mode CSRs.

Hazard3 also allocates a custom _Debug Mode_ register <<reg-dmdata0>> in this space.

[[reg-dmdata0]]
==== dmdata0

Address: `0xbff`

The Debug Module's internal `data0` register is mapped to this CSR address when the core is in debug mode. At any other time, access to this CSR address will cause an illegal instruction exception.

NOTE: The 0.13.2 debug specification allows for the Debug Module's abstract data registers to be mapped into the core's CSR address space, but there is no Debug-custom space, so the read/write M-custom space is used instead to avoid conflict with future versions of the debug specification.

The Debug Module uses this mapping to exchange data with the core by injecting `csrr`/`csrw` instructions into the prefetch buffer. This in turn is used to implement the Abstract Access Register command. See <<debug-chapter>>.

This CSR address is given by the `dataaddress` field of the Debug Module's `hartinfo` register, and `hartinfo.dataaccess` is set to 0 to indicate this is a CSR mapping, not a memory mapping.

[[reg-midcr]]
==== midcr

Address: `0xbc0`

Implementation-defined control register. Miscellaneous nonstandard controls.

[cols="10h,20h,~", options="header"]
|===
| Bits | Name | Description
| 31:1 | - | RES0
| 0 | `eivect` | Modified external interrupt vectoring. If 0, use standard behaviour: all external interrupts set interrupt `mcause` of 11 and vector to `mtvec + 0x2c`. If 1, external interrupts use distinct interrupt `mcause` numbers 16 upward, and distinct vectors `mtvec + (irq + 16) * 4`. Resets to 0. Has no effect when `mtvec[0]` is 0.
|===

[[reg-meie0]]
==== meie0

Address: `0xbe0`

External interrupt enable register 0. Contains a read-write bit for each external interrupt request IRQ0 through IRQ31. A `1` bit indicates that interrupt is currently enabled.

Addresses `0xbe1` through `0xbe3` are reserved for further `meie` registers, supporting up to 128 external interrupts.

An external interrupt is taken when all of the following are true:

* The interrupt is currently asserted in `meip0`
* The matching interrupt enable bit is set in `meie0`
* The standard M-mode interrupt enable `mstatus.mie` is set
* The standard M-mode global external interrupt enable `mie.meie` is set

`meie0` resets to *all-ones*, for compatibility with software which is only aware of `mstatus` and `mie`. Because `mstatus.mie` and `mie.meie` are both initially clear, the core will not take interrupts straight out of reset, but it is strongly recommended to configure `meie0` before setting the global interrupt enable, to avoid interrupts from unexpected sources.

[[reg-meip0]]
==== meip0

Address: `0xfe0`

External IRQ pending register 0. Contains a read-only bit for each external interrupt request IRQ0 through IRQ31. A `1` bit indicates that interrupt is currently asserted. IRQs are assumed to be level-sensitive, and the relevant `meip0` bit is cleared by servicing the requestor so that it deasserts its interrupt request.

Addresses `0xfe1` through `0xfe3` are reserved for further `meip` registers, supporting up to 128 external interrupts.

When any bit is set in both `meip0` and `meie0`, the standard external interrupt pending bit `mip.meip` is also set. In other words, `meip0` is filtered by `meie0` to generate the standard `mip.meip` flag. So, an external interrupt is taken when _all_ of the following are true:

* An interrupt is currently asserted in `meip0`
* The matching interrupt enable bit is set in `meie0`
* The standard M-mode interrupt enable `mstatus.mie` is set
* The standard M-mode global external interrupt enable `mie.meie` is set

In this case, the processor jumps to either:

* `mtvec` directly, if vectoring is disabled (`mtvec[0]` is 0)
* `mtvec + 0x2c`, if vectoring is enabled (`mtvec[0]` is 1) and modified external IRQ vectoring is disabled (`midcr.eivect` is 0)
* `mtvect + (mlei + 16) * 4`, if vectoring is enabled (`mtvec[0]` is 1) and modified external IRQ vectoring is enabled (`midcr.eivect` is 1). `
** `mlei` is a read-only CSR containing the lowest-numbered pending-and-enabled external interrupt.

==== mlei

Address: `0xfe4`

Lowest external interrupt. Contains the index of the lowest-numbered external interrupt which is both asserted in `meip0` and enabled in `meie0`. Can be used for faster software vectoring when modified external interrupt vectoring (`midcr.eivect = 1`) is not in use.

[cols="10h,20h,~", options="header"]
|===
| Bits | Name | Description
| 31:5 | - | RES0
| 4:0 | - | Index of the lowest-numbered active external interrupt. A LSB-first priority encode of `meip0 & meie0`. Zero when no external interrupts are both pending and enabled.
|===


==== Maybe-adds

An option to clear a bit in `meie0` when that interrupt is taken, and set it when an `mret` has a matching `mcause` for that interrupt. Makes preemption support easier.
