Subversion Repositories neorv32

<<<
:sectnums:
== On-Chip Debugger (OCD)

The NEORV32 Processor features an _on-chip debugger_ (OCD) implementing **execution-based debugging** that is compatible
to the **Minimal RISC-V Debug Specification Version 0.13.2**.
Please refer to this spec for in-deep information.
A copy of the specification is available in `docs/references/riscv-debug-release.pdf`.
The NEORV32 OCD provides the following key features:

* JTAG test access port
* run-control of the CPU: halting, single-stepping and resuming
* executing arbitrary programs during debugging
* accessing core registers (direct access to GPRs, indirect access to CSRs via program buffer)
* indirect access to the whole processor address space (via program buffer))
* compatible to the https://github.com/riscv/riscv-openocd[RISC-V port of OpenOCD];
  pre-built binaries can be obtained for example from https://www.sifive.com/software[SiFive]

.OCD Security Note
[IMPORTANT]
Access via the OCD is _always authenticated_ (`dmstatus.authenticated` == `1`). Hence, the
_whole system_ can always be accessed via the on-chip debugger. Currently, there is no option
to disable the OCD via software. The OCD can only be disabled by disabling implementation
(setting _ON_CHIP_DEBUGGER_EN_ generic to _false_).

[NOTE]
The OCD requires additional resources for implementation and _might_ also increase the critical path resulting in less
performance. If the OCD is not really required for the _final_ implementation, it can be disabled and thus,
discarded from implementation. In this case all circuitry of the debugger is completely removed (no impact
on area, energy or timing at all).

[TIP]
A simple example on how to use NEORV32 on-chip debugger in combination with `OpenOCD` and `gdb`
is shown in section https://stnolting.github.io/neorv32/ug/#_debugging_using_the_on_chip_debugger[Debugging using the On-Chip Debugger]
of the User Guide.

The NEORV32 on-chip debugger complex is based on three hardware modules:

.NEORV32 on-chip debugger complex
image::neorv32_ocd_complex.png[align=center]

[start=1]
. <<_debug_transport_module_dtm>> (`rtl/core/neorv32_debug_dtm.vhd`): External JTAG access tap to allow an external
  adapter to interface with the _debug module(DM)_ using the _debug module interface (dmi)_.
. <<_debug_module_dm>> (`rtl/core/neorv32_debug_tm.vhd`): Debugger control unit that is configured by the DTM via the
  the _dmi_. Form the CPU's "point of view" this module behaves as a memory-mapped "peripheral" that can be accessed
  via the processor-internal bus. The memory-mapped registers provide an internal _data buffer_ for data transfer
  from/to the DM, a _code ROM_ containing the "park loop" code,   a _program buffer_ to allow the debugger to
  execute small programs defined by the DM and a _status register_ that is used to communicate
  _halt_, _resume_ and _execute_ requests/acknowledges from/to the DM.
. CPU <<_cpu_debug_mode>> extension (part of`rtl/core/neorv32_cpu_control.vhd`):
  This extension provides the "debug execution mode" which executes the "park loop" code from the DM.
  The mode also provides additional CSRs.

**Theory of Operation**

When debugging the system using the OCD, the debugger issues a halt request to the CPU (via the CPU's
`db_halt_req_i` signal) to make the CPU enter _debug mode_. In this state, the application-defined architectural
state of the system/CPU is "frozen" so the debugger can monitor and even modify it.
While in debug mode, the CPU executes the "park loop" code from the _code ROM_ of the DM.
This park loop implements an endless loop, in which the CPU polls the memory-mapped _status register_ that is
controlled by the _debug module (DM)_. The flags of these register are used to communicate _requests_ from
the DM and to _acknowledge_ them by the CPU: trigger execution of the program buffer or resume the halted
application.



<<<
// ####################################################################################################################
:sectnums:
=== Debug Transport Module (DTM)

The debug transport module (VHDL module: `rtl/core/neorv32_debug_dtm.vhd`) provides a JTAG test access port (TAP).
The DTM is the first entity in the debug system, which connects and external debugger via JTAG to the next debugging
entity: the debug module (DM).
External JTAG access is provided by the following top-level ports.

.JTAG top level signals
[cols="^2,^2,^2,<8"]
[options="header",grid="rows"]
|=======================
| Name          | Width | Direction | Description
| `jtag_trst_i` | 1     | in        | TAP reset (low-active); this signal is optional, make sure to pull it _high_ if it is not used
| `jtag_tck_i`  | 1     | in        | serial clock
| `jtag_tdi_i`  | 1     | in        | serial data input
| `jtag_tdo_o`  | 1     | out       | serial data output
| `jtag_tms_i`  | 1     | in        | mode select
|=======================

.Maximum JTAG Clock
[IMPORTANT]
All JTAG signals are synchronized to the processor clock domain by oversampling them in DTM. Hence, no additional
clock domain is required for the DTM. However, this constraints the maximal JTAG clock frequency (`jtag_tck_i`) to be less
than or equal to **1/5** of the processor clock frequency (`clk_i`).

[NOTE]
If the on-chip debugger is disabled (_ON_CHIP_DEBUGGER_EN_ = false) the JTAG serial input `jtag_tdi_i` is directly
connected to the JTAG serial output `jtag_tdo_o` to maintain the JTAG chain.

[WARNING]
The NEORV32 JTAG TAP does not provide a _boundary check_ function (yet?). Hence, physical device pins cannot be accessed.

The DTM uses the "debug module interface (dmi)" to access the actual debug module (DM).
These accesses are controlled by TAP-internal registers.
Each registers is selected by the JTAG instruction register (`IR`) and accessed through the JTAG data register (`DR`).

[NOTE]
The DTM's instruction and data registers can be accessed using OpenOCDs `irscan` and `drscan` commands.
The RISC-V port of OpenOCD also provides low-level command (`riscv dmi_read` & `riscv dmi_write`) to access the _dmi_
debug module interface.

JTAG access is conducted via the *instruction register* `IR`, which is 5 bit wide, and several *data registers* `DR`
with different sizes.
The data registers are accessed by writing the according address to the instruction register.
The following table shows the available data registers:

.JTAG TAP registers
[cols="^2,^2,^2,<8"]
[options="header",grid="rows"]
|=======================
| Address (via `IR`) | Name     | Size [bits] | Description
| `00001`            | `IDCODE` | 32          | identifier, default: `0x0CAFE001` (configurable via package's `jtag_tap_idcode_*` constants)
| `10000`            | `DTMCS`  | 32          | debug transport module control and status register
| `10001`            | `DMI`    | 41          | debug module interface (_dmi_); 7-bit address, 32-bit read/write data, 2-bit operation (`00` = NOP; `10` = write; `01` = read)
| others             | `BYPASS` | 1           | default JTAG bypass register
|=======================

.`DTMCS` - DTM Control and Status Register
[cols="^2,^3,^1,<8"]
[options="header",grid="rows"]
|=======================
| Bit(s) | Name           | r/w | Description
| 31:18  | -              | r/- | _reserved_, hardwired to zero
| 17     | `dmihardreset` | r/w | setting this bit will reset the DM interface; this bit auto-clears
| 16     | `dmireset`     | r/w | setting this bit will clear ste sticky error state; this bit auto-clears
| 15     | -              | r/- | _reserved_, hardwired to zero
| 14:12  | `idle`         | r/- | recommended idle states (= 0, no idle states required)
| 11:10  | `dmistat`      | r/- | DMI statu: `00` = no error, `01` = reserved, `10` = operation failed, `11` = failed operation during pending DMI operation
| 9:4    | `abits`        | r/- | number of DMI address bits (= 7)
| 3:0    | `version`      | r/- | `0001` = spec version 0.13
|=======================

[INFO]
See the https://github.com/riscv/riscv-debug-spec[RISC-V debug specification] for more information regarding the data
registers and operations. A local copy can be found in `docs/references`.



<<<
// ####################################################################################################################
:sectnums:
=== Debug Module (DM)

According to the RISC-V debug specification, the DM (VHDL module: `rtl/core/neorv32_debug_dm.vhd`)
acts as a translation interface between abstract operations issued by the debugger and the platform-specific
debugger implementation. It supports the following features (excerpt from the debug spec):

* Gives the debugger necessary information about the implementation.
* Allows the hart to be halted and resumed and provides status of the current state.
* Provides abstract read and write access to the halted hart's GPRs.
* Provides access to a reset signal that allows debugging from the very first instruction after reset.
* Provides a mechanism to allow debugging the hart immediately out of reset. (_still experimental_)
* Provides a Program Buffer to force the hart to execute arbitrary instructions.
* Allows memory access from a hart's point of view.

The NEORV32 DM follows the "Minimal RISC-V External Debug Specification" to provide full debugging
capabilities while keeping resource (area) requirements at a minimum level.
It implements the **execution based debugging scheme** for a single hart and provides the following
hardware features:

* program buffer with 2 entries and implicit `ebreak` instruction afterwards
* no _direct_ bus access (indirect bus access via the CPU)
* abstract commands: "access register" plus auto-execution
* no _dedicated_ halt-on-reset capabilities yet (but can be emulated)

The DM provides two "sides of access": access from the DTM via the _debug module interface (dmi)_ and access from the
CPU via the processor-internal bus. From the DTM's point of view, the DM implements a set of <<_dm_registers>> that
are used to control and monitor the actual debugging. From the CPU's point of view, the DM implements several
memory-mapped registers (within the _normal_ address space) that are used for communicating debugging control
and status (<<_dm_cpu_access>>).


:sectnums:
==== DM Registers

The DM is controlled via a set of registers that are accessed via the DTM's _dmi_.
The "Minimal RISC-V Debug Specification" requires only a subset of the registers specified in the spec.
The following registers are implemented.
Write accesses to any other registers are ignored and read accesses will always return zero.
Register names that are encapsulated in "( )" are not actually implemented; however, they are listed to explicitly show
their functionality.

.Available DM registers
[cols="^2,^3,<7"]
[options="header",grid="rows"]
|=======================
| Address | Name           | Description
|  `0x04` | `data0`        | Abstract data 0, used for data transfer between debugger and processor
|  `0x10` | `dmcontrol`    | Debug module control
|  `0x11` | `dmstatus`     | Debug module status
|  `0x12` | `hartinfo`     | Hart information
|  `0x16` | `abstracts`    | Abstract control and status
|  `0x17` | `command`      | Abstract command
|  `0x18` | `abstractauto` | Abstract command auto-execution
|  `0x1d` | (`nextdm`)     | Base address of _next_ DM; read as zero to indicate there is only _one_ DM
|  `0x20` | `progbuf0`     | Program buffer 0
|  `0x21` | `progbuf1`     | Program buffer 1
|  `0x38` | (`sbcs`)       | System bus access control and status; read as zero to indicate there is no _direct_ system bus access
|  `0x40` | `haltsum0`     | Halt summary 0
|=======================


:sectnums!:
===== **`data`**

[cols="4,27,>7"]
[frame="topbot",grid="none"]
|======
| 0x04 | **Abstract data 0** | `data0`
3+| Reset value: _UNDEFINED_
3+| Basic read/write registers to be used with abstract command (for example to read/write data from/to CPU GPRs).
|======


:sectnums!:
===== **`dmcontrol`**

[cols="4,27,>7"]
[frame="topbot",grid="none"]
|======
| 0x10 | **Debug module control register** | `dmcontrol`
3+| Reset value: 0x00000000
3+| Control of the overall debug module and the hart. The following table shows all implemented bits. All remaining bits/bit-fields are configures as "zero" and are
read-only. Writing '1' to these bits/fields will be ignored.
|======

.`dmcontrol` - debug module control register bits
[cols="^1,^2,^1,<8"]
[options="header",grid="rows"]
|=======================
| Bit | Name [RISC-V]  | R/W | Description
| 31  | `haltreq`      | -/w | set/clear hart halt request
| 30  | `resumereq`    | -/w | request hart to resume
| 28  | `ackhavereset` | -/w | write `1` to clear `*havereset` flags
|  1  | `ndmreset`     | r/w | put whole processor into reset when `1`
|  0  | `dmactive`     | r/w | DM enable; writing `0`-`1` will reset the DM
|=======================


:sectnums!:
===== **`dmstatus`**

[cols="4,27,>7"]
[frame="topbot",grid="none"]
|======
| 0x11 | **Debug module status register** | `dmstatus`
3+| Reset value: 0x00000000
3+| Current status of the overall debug module and the hart. The entire register is read-only.
|======

.`dmstatus` - debug module status register bits
[cols="^1,^2,<10"]
[options="header",grid="rows"]
|=======================
| Bit   | Name [RISC-V]     | Description
| 31:23 | _reserved_        | reserved; always zero
| 22    | `impebreak`       | always `1`; indicates an implicit `ebreak` instruction after the last program buffer entry
| 21:20 | _reserved_        | reserved; always zero
| 19    | `allhavereset`    .2+| `1` when the hart is in reset
| 18    | `anyhavereset`
| 17    | `allresumeack`    .2+| `1` when the hart has acknowledged a resume request
| 16    | `anyresumeack`
| 15    | `allnonexistent`  .2+| always zero to indicate the hart is always existent
| 14    | `anynonexistent`
| 13    | `allunavail`      .2+| `1` when the DM is disabled to indicate the hart is unavailable
| 12    | `anyunavail`
| 11    | `allrunning`      .2+| `1` when the hart is running
| 10    | `anyrunning`
|  9    | `allhalted`       .2+| `1` when the hart is halted
|  8    | `anyhalted`
|  7    | `authenticated`   | always `1`; there is no authentication
|  6    | `authbusy`        | always `0`; there is no authentication
|  5    | `hasresethaltreq` | always `0`; halt-on-reset is not supported (directly)
|  4    | `confstrptrvalid` | always `0`; no configuration string available
| 3:0   | `version`         | `0010` - DM is compatible to version 0.13
|=======================


:sectnums!:
===== **`hartinfo`**

[cols="4,27,>7"]
[frame="topbot",grid="none"]
|======
| 0x12 | **Hart information** | `hartinfo`
3+| Reset value: see below
3+| This register gives information about the hart. The entire register is read-only.
|======

.`hartinfo` - hart information register bits
[cols="^1,^2,<8"]
[options="header",grid="rows"]
|=======================
| Bit   | Name [RISC-V] | Description
| 31:24 | _reserved_    | reserved; always zero
| 23:20 | `nscratch`    | `0001`, number of `dscratch*` CPU registers = 1
| 19:17 | _reserved_    | reserved; always zero
| 16    | `dataccess`   | `0`, the `data` registers are shadowed in the hart's address space
| 15:12 | `datasize`    | `0001`, number of 32-bit words in the address space dedicated to shadowing the `data` registers = 1
| 11:0  | `dataaddr`    | = `dm_data_base_c(11:0)`, signed base address of `data` words (see address map in <<_dm_cpu_access>>)
|=======================


:sectnums!:
===== **`abstracts`**

[cols="4,27,>7"]
[frame="topbot",grid="none"]
|======
| 0x16 | **Abstract control and status** | `abstracts`
3+| Reset value: see below
3+| Command execution info and status.
|======

.`abstracts` - abstract control and status register bits
[cols="^1,^2,^1,<8"]
[options="header",grid="rows"]
|=======================
| Bit   | Name [RISC-V] | R/W | Description
| 31:29 | _reserved_    | r/- | reserved; always zero
| 28:24 | `progbufsize` | r/- | `0010`; size of the program buffer (`progbuf`) = 2 entries
| 23:11 | _reserved_    | r/- | reserved; always zero
| 12    | `busy`        | r/- | `1` when a command is being executed
| 11    | _reserved_    | r/- | reserved; always zero
| 10:8  | `cmerr`       | r/w | error during command execution (see below); has to be cleared by writing `111`
| 7:4   | _reserved_    | r/- | reserved; always zero
| 3:0   | `datacount`   | r/- | `0001`; number of implemented `data` registers for abstract commands = 1
|=======================

Error codes in `cmderr` (highest priority first):

* `000` - no error
* `100` - command cannot be executed since hart is not in expected state
* `011` - exception during command execution
* `010` - unsupported command
* `001` - invalid DM register read/write while command is/was executing


:sectnums!:
===== **`command`**

[cols="4,27,>7"]
[frame="topbot",grid="none"]
|======
| 0x17 | **Abstract command** | `command`
3+| Reset value: 0x00000000
3+| Writing this register will trigger the execution of an abstract command. New command can only be executed if
`cmderr` is zero. The entire register in write-only (reads will return zero).
|======

[NOTE]
The NEORV32 DM only supports **Access Register** abstract commands. These commands can only access the
hart's GPRs (abstract command register index `0x1000` - `0x101f`).

.`command` - abstract command register - "access register" commands only
[cols="^1,^2,<8"]
[options="header",grid="rows"]
|=======================
| Bit   | Name [RISC-V]      | R/W | Description / required value
| 31:24 | `cmdtype`          | -/w | `00000000` to indicate "access register" command
| 23    | _reserved_         | -/w | reserved, has to be `0` when writing
| 22:20 | `aarsize`          | -/w | `010` to indicate 32-bit accesses
| 21    | `aarpostincrement` | -/w | `0`, post-increment is not supported
| 18    | `postexec`         | -/w | if set the program buffer is executed _after_ the command
| 17    | `transfer`         | -/w | if set the operation in `write` is conducted
| 16    | `write`            | -/w | `1`: copy `data0` to `[regno]`; `0` copy `[regno]` to `data0`
| 15:0  | `regno`            | -/w | GPR-access only; has to be `0x1000` - `0x101f`
|=======================


:sectnums!:
===== **`abstractauto`**

[cols="4,27,>7"]
[frame="topbot",grid="none"]
|======
| 0x18 | **Abstract command auto-execution** | `abstractauto`
3+| Reset value: 0x00000000s
3+| Register to configure when a read/write access to a DM repeats execution of the last abstract command.
|======

.`abstractauto` - Abstract command auto-execution register bits
[cols="^1,^2,^1,<8"]
[options="header",grid="rows"]
|=======================
| Bit   | Name [RISC-V]        | R/W | Description
| 17    | `autoexecprogbuf[1]` | r/w | when set reading/writing from/to `progbuf1` will execute `command again`
| 16    | `autoexecprogbuf[0]` | r/w | when set reading/writing from/to `progbuf0` will execute `command again`
|  0    | `autoexecdata[0]`    | r/w | when set reading/writing from/to `data0` will execute `command again`
|=======================


:sectnums!:
===== **`progbuf`**

[cols="4,27,>7"]
[frame="topbot",grid="none"]
|======
| 0x20 | **Program buffer 0** | `progbuf0`
| 0x21 | **Program buffer 1** | `progbuf1`
3+| Reset value: `NOP`-instruction
3+| General purpose program buffer for the DM.
|======


:sectnums!:
===== **`haltsum0`**

[cols="4,27,>7"]
[frame="topbot",grid="none"]
|======
| 0x40 | **Halt summary 0** | `haltsum0`
3+| Reset value: _UNDEFINED_
3+| Bit 0 of this register is set if the hart is halted (all remaining bits are always zero). The entire register is read-only.
|======

:sectnums:
==== DM CPU Access

From the CPU's point of view, the DM behaves as a memory-mapped peripheral that includes

* a small ROM that contains the code for the "park loop", which is executed when the CPU is _in_ debug mode.
* a program buffer populated by the debugger host to execute small programs
* a data buffer to transfer data between the processor and the debugger host
* a status register to communicate debugging requests

.Park Loop Code Sources
[NOTE]
The assembly sources of the **park loop code** are available in `sw/ocd-firmware/park_loop.S`. Please note, that these
sources are not intended to be changed by the used. Hence, the makefile does not provide an automatic option
to compile and "install" the debugger ROM code into the HDL sources and require a manual copy
(see `sw/ocd-firmware/README.md`).

The DM uses a total address space of 128 words of the CPU's address space (= 512 bytes) divided into four sections
of 32 words (= 128 bytes) each.
Please note, that the program buffer, the data buffer and the status register only uses a few effective words in this
address space. However, these effective addresses are mirrored to fill up the whole 128 bytes of the section.
Hence, any CPU access within this address space will succeed.

.DM CPU access - address map (divided into four sections)
[cols="^2,^4,^2,<7"]
[options="header",grid="rows"]
|=======================
| Base address | Name [VHDL package]              | Actual size | Description
| `0xfffff800` | `dm_code_base_c` (= `dm_base_c`) |   128 bytes | Code ROM for the "park loop" code
| `0xfffff880` | `dm_pbuf_base_c`                 |    16 bytes | Program buffer, provided by DM
| `0xfffff900` | `dm_data_base_c`                 |     4 bytes | Data buffer (`dm.data0`)
| `0xfffff980` | `dm_sreg_base_c`                 |     4 bytes | Control and status register
|=======================

[NOTE]
From the CPU's point of view, the DM is mapped to an _"unused"_ address range within the processor's
<<_address_space>> right between the bootloader ROM (BOOTROM) and the actual processor-internal IO
space at addresses `0xfffff800` - `0xfffff9ff`

When the CPU enters or re-enters (for example via `ebreak` in the DM's program buffer) debug mode, it jumps to
the beginning of the DM's "park loop" code ROM at `dm_code_base_c`. This is the _normal entry point_ for the
park loop code. If an exception is encountered during debug mode, the CPU jumps to `dm_code_base_c + 4`,
which is the _exception entry point_.

**Status Register**

The status register provides a direct communication channel between the CPU executing the park loop and the
host-controlled controller of the DM. Note that all bits that can be written by the CPU (acknowledge flags)
cause a single-shot (1-cycle) signal to the DM controller and auto-clear (always read as zero).
The bits that are driven by the DM controller and are read-only to the CPU and keep their state until the CPU
acknowledges the according request.

.DM CPU access - status register
[cols="^2,^2,^2,<8"]
[options="header",grid="rows"]
|=======================
| Bit | Name            | CPU access | Description
| 0   | `halt_ack`      | -/w        | Set by the CPU to indicate that the CPU is halted and keeps iterating in the park loop
| 1   | `resume_req`    | r/-        | Set by the DM to tell the CPU to resume normal operation (leave parking loop and leave debug mode via `dret` instruction)
| 2   | `resume_ack`    | -/w        | Set by the CPU to acknowledge that the CPU is now going to leave parking loop & debug mode
| 3   | `execute_req`   | r/-        | Set by the DM to tell the CPU to leave debug mode and execute the instructions from the program buffer; CPU will re-enter parking loop afterwards
| 4   | `execute_ack`   | -/w        | Set by the CPU to acknowledge that the CPU is now going to execute the program buffer
| 5   | `exception_ack` | -/w        | Set by the CPU to inform the DM that an exception occurred during execution of the park loop or during execution of the program buffer
|=======================



<<<
// ####################################################################################################################
:sectnums:
=== CPU Debug Mode

The NEORV32 CPU Debug Mode `DB` (part of `rtl/core/neorv32_cpu_control.vhd`) is compatible to the "Minimal RISC-V Debug Specification 0.13.2".
It is enabled/implemented by setting the CPU generic _CPU_EXTENSION_RISCV_DEBUG_ to "true" (done by setting processor
generic _ON_CHIP_DEBUGGER_EN_).
It provides a new operation mode called "debug mode".
When enabled, three additional CSRs are available (section <<_cpu_debug_mode_csrs>>) and also the "return from debug mode"
instruction `dret` is available when the CPU is "in" debug mode.

[IMPORTANT]
The CPU _debug mode_ requires the `Zicsr` and `Zifencei` CPU extension to be implemented (top generics _CPU_EXTENSION_RISCV_Zicsr_
and _CPU_EXTENSION_RISCV_Zifencei_ = true).

.Hardware Watchpoints and Breakpoints
[NOTE]
The NEORV32 CPU _debug mode_ does not provide a hardware "trigger module" (which is optional in the RISC-V debug spec). However, gdb
provides a native _emulation_ for code (breakpoints using `break` instruction) and data (polling data watchpoints in automated
single-stepping) triggers.

The CPU debug-mode is entered when one of the following events appear:

[start=1]
. executing `ebreak` instruction (when `dcsr.ebreakm` is set and in machine mode OR when `dcsr.ebreaku` is set and in user mode)
. debug halt request from external DM (via CPU signal `db_halt_req_i`, high-active, triggering on rising-edge)
. finished executing of a single instruction while in single-step debugging mode (enabled via `dcsr.step`)

From a hardware point of view, these "entry conditions" are special synchronous (`ebreak` instruction) or asynchronous
(single-stepping "interrupt"; halt request "interrupt") traps, that are handled invisibly by the control logic.

.WFI instruction
[WARNING]
The wait-for-interrupt instruction `wfi` puts the CPU into sleep mode. The CPU will resume normale operation
when at least one interrupt source becomes pending (= at least one bit in `mip` CSR is set).
However, the CPU will _also resume_ from sleep mode if there is a halt request from the debug module (DM).

Whenever the CPU **enters debug-mode** it performs the following operations:

* move `pc` to `dpcs`
* copy the hart's current privilege level to `dcsr.prv`
* set `dcrs.cause` according to the cause why debug mode is entered
* **no update** of `mtval`, `mcause`, `mtval` and `mstatus` CSRs
* load the address configured via the CPU _CPU_DEBUG_ADDR_ generic to the `pc` to jump to "debugger park loop" code in the debug module (DM)

When the CPU **is in debug-mode** the following things are important:

* while in debug mode, the CPU executes the parking loop and the program buffer provided by the DM if requested
* effective CPU privilege level is `machine` mode, any PMP configuration is bypassed
* the `wfi` instruction acts as a `nop` (also during single-stepping)
* if an exception occurs:
** if the exception was caused by any debug-mode entry action the CPU jumps to the _normal entry point_
   (= _CPU_DEBUG_ADDR_) of the park loop again (for example when executing `ebreak` _in_ debug-mode)
** for all other exception sources the CPU jumps to the _exception entry point_ ( = _CPU_DEBUG_ADDR_ + 4)
   to signal an exception to the DM and restarts the park loop again afterwards
* interrupts are disabled; however, they will remain pending and will get executed after the CPU has left debug mode
* if the DM makes a resume request, the park loop exits and the CPU leaves debug mode (executing `dret`)

Debug mode is left either by executing the `dret` instruction footnote:[`dret` should only be executed _inside_ the debugger
"park loop" code (-> code ROM in the debug module (DM).)] (_in_ debug mode) or by performing
a hardware reset of the CPU. Executing `dret` outside of debug mode will raise an illegal instruction exception.
Whenever the CPU **leaves debug mode** the following things happen:

* set the hart's current privilege level according to `dcsr.prv`
* restore `pc` from `dpcs`
* resume normal operation at `pc`


:sectnums:
==== CPU Debug Mode CSRs

Two additional CSRs are required by the _Minimal RISC-V Debug Specification_: The debug mode control and status register
`dcsr` and the program counter `dpc`. Providing a general purpose scratch register for debug mode (`dscratch0`) allows
faster execution of program provided by the debugger, since _one_ general purpose register can be backup-ed and
directly used.

[NOTE]
The debug-mode control and status registers (CSRs) are only accessible when the CPU is _in_ debug mode.
If these CSRs are accessed outside of debug mode (for example when in `machine` mode) an illegal instruction exception
is raised.


:sectnums!:
===== **`dcsr`**

[cols="4,27,>7"]
[frame="topbot",grid="none"]
|======
| 0x7b0 | **Debug control and status register** | `dcsr`
3+| Reset value: 0x00000000
3+| The `dcsr` CSR is compatible to the RISC-V debug spec. It is used to configure debug mode and provides additional status information.
The following bits are implemented. The reaming bits are read-only and always read as zero.
|======

.Debug control and status register bits
[cols="^1,^2,^1,<8"]
[options="header",grid="rows"]
|=======================
| Bit   | Name [RISC-V] | R/W | Event
| 31:28 | `xdebugver` | r/- | always `0100` - indicates external debug support exists
| 27:16 | -           | r/- | _reserved_, read as zero
| 15    | `ebereakm`  | r/w | `ebreak` instructions in `machine` mode will _enter_ debug mode when set
| 14    | [line-through]#`ebereakh`# | r/- | `0` - hypervisor mode not supported
| 13    | [line-through]#`ebereaks`# | r/- | `0` - supervisor mode not supported
| 12    | `ebereaku`  | r/w | `ebreak` instructions in `user` mode will _enter_ debug mode when set
| 11    | [line-through]#`stepie`#    | r/- | `0` - IRQs are disabled during single-stepping
| 10    | [line-through]#`stopcount`# | r/- | `0` - counters increment as usual
| 9     | [line-through]#`stoptime`#  | r/- | `0` - timers increment as usual
| 8:6   | `cause`     | r/- | cause identifier - why debug mode was entered
| 5     | -           | r/- | _reserved_, read as zero
| 4     | [line-through]#`mprven`# | r/- | `0` - `mstatus.mprv` is ignored when in debug mode
| 3     | [line-through]#`nmip`#   | r/- | `0` - non-maskable interrupt is pending
| 2     | `step`      | r/w | enable single-stepping when set
| 1:0   | `prv`       | r/w | CPU privilege level before/after debug mode
|=======================


:sectnums!:
===== **`dpc`**

[cols="4,27,>7"]
[frame="topbot",grid="none"]
|======
| 0x7b1 | **Debug program counter** | `dpc`
3+| Reset value: _UNDEFINED_
3+| The `dcsr` CSR is compatible to the RISC-V debug spec. It is used to store the current program counter when
debug mode is entered. The `dret` instruction will return to `dpc` by moving `dpc` to `pc`.
|======


:sectnums!:
===== **`dscratch0`**

[cols="4,27,>7"]
[frame="topbot",grid="none"]
|======
| 0x7b2 | **Debug scratch register 0** | `dscratch0`
3+| Reset value: _UNDEFINED_
3+| The `dscratch0` CSR is compatible to the RISC-V debug spec. It provides a general purpose debug mode-only scratch register.
|======