// Index auto-generated on 2023-12-21 11:57:08.575997 from ../xml/core_registers.xml
These registers are only accessible from Debug Mode.
[[csr_]]
[cols="1,6",options="header"]
|===
|Address |Name
|0x7b0 | Debug Control and Status (`dcsr`)
|0x7b1 | Debug PC (`dpc`)
|0x7b2 | Debug Scratch Register 0 (`dscratch0`)
|0x7b3 | Debug Scratch Register 1 (`dscratch1`)
|===
// Registers auto-generated on 2023-12-21 11:57:08.577409 from ../xml/core_registers.xml
==== Debug Control and Status (((dcsr)), at 0x7b0)

[[csr_dcsr]]
Upon entry into Debug Mode, \FcsrDcsrV and \FcsrDcsrPrv are updated
with the privilege level the hart was previously in, and \FcsrDcsrCause
is updated with the reason for Debug Mode entry.  Other than these
fields and \FcsrDcsrNmip, the other fields of \RcsrDcsr are only
writable by the external debugger.

\begin{steps}{Table~\ref{tab:dcsrcausepriority} shows the priorities of
reasons for entering Debug Mode.  Implementations should implement
priorities as shown in the table. For compatibility with old versions of this spec, resethaltreq and haltreq are
allowed to be at different positions than shown as long as:}
\item resethaltreq is higher priority than haltreq
\item the relative order of the other four causes is maintained
\end{steps}

\begin{table}[H]
\centering
\caption{Priority of reasons for entering Debug Mode from highest to lowest.}
\label{tab:dcsrcausepriority}
\begin{tabular}{|c|c|}
\hline
\FcsrDcsrCause encoding & Cause \\
\hline
5 & resethaltreq \\
\hline
6 & halt group \\
\hline
3 & haltreq \\
\hline
2 & trigger (See table~\ref{tab:priority} for detailed priority) \\
\hline
1 & ebreak \\
\hline
4 & step \\
\hline
\end{tabular}
\end{table}

\begin{commentary}
Note that mcontrol/mcontrol6 triggers which fire after the
instruction which hit the trigger are considered
to be high priority causes on the subsequent instruction.  Therefore,
an execute trigger with timing=after on an ebreak instruction is lower
priority than the ebreak itself because the trigger will fire after the
ebreak instruction.  For the same reason, if a single instruction is
stepped with both icount and \FcsrDcsrStep then the \FcsrDcsrStep has
priority.  See table~\ref{tab:priority} for the relative priorities of
triggers with respect to the ebreak instruction.

Most multi-hart implementations will probably hardwire \FcsrDcsrStoptime
to 0, as the implementation can get complicated and the benefit is
small.
\end{commentary}

This CSR is read/write.
[float="center",align="center",cols="<2,<3,^1,^1",options="header"]
|===
|Field |Description |Access |Reset
|[[dcsrdebugver,dcsrdebugver]] `debugver`
|

0 (none): There is no debug support.


4 (1.0): Debug support exists as it is described in this document.


15 (custom): There is debug support, but it does not conform to any +
available version of this spec.
|R
|Preset
|[[dcsrebreakvs,dcsrebreakvs]] `ebreakvs`
|

0 (exception): {\tt ebreak} instructions in VS-mode behave as described in the +
Privileged Spec.


1 (debug mode): {\tt ebreak} instructions in VS-mode enter Debug Mode.

This bit is hardwired to 0 if the hart does not support virtualization mode.
|WARL
|0
|[[dcsrebreakvu,dcsrebreakvu]] `ebreakvu`
|

0 (exception): {\tt ebreak} instructions in VU-mode behave as described in the +
Privileged Spec.


1 (debug mode): {\tt ebreak} instructions in VU-mode enter Debug Mode.

This bit is hardwired to 0 if the hart does not support virtualization mode.
|WARL
|0
|[[dcsrebreakm,dcsrebreakm]] `ebreakm`
|

0 (exception): {\tt ebreak} instructions in M-mode behave as described in the +
Privileged Spec.


1 (debug mode): {\tt ebreak} instructions in M-mode enter Debug Mode.
|R/W
|0
|[[dcsrebreaks,dcsrebreaks]] `ebreaks`
|

0 (exception): {\tt ebreak} instructions in S-mode behave as described in the +
Privileged Spec.


1 (debug mode): {\tt ebreak} instructions in S-mode enter Debug Mode.

This bit is hardwired to 0 if the hart does not support S-mode.
|WARL
|0
|[[dcsrebreaku,dcsrebreaku]] `ebreaku`
|

0 (exception): {\tt ebreak} instructions in U-mode behave as described in the +
Privileged Spec.


1 (debug mode): {\tt ebreak} instructions in U-mode enter Debug Mode.

This bit is hardwired to 0 if the hart does not support U-mode.
|WARL
|0
|[[dcsrstepie,dcsrstepie]] `stepie`
|

0 (interrupts disabled): Interrupts (including NMI) are disabled during single stepping +
with \FcsrDcsrStep set. +
This value should be supported.


1 (interrupts enabled): Interrupts (including NMI) are enabled during single stepping +
with \FcsrDcsrStep set.

Implementations may hard wire this bit to 0. +
In that case interrupt behavior can be emulated by the debugger.

The debugger must not change the value of this bit while the hart +
is running.
|WARL
|0
|[[dcsrstopcount,dcsrstopcount]] `stopcount`
|

0 (normal): Increment counters as usual.


1 (freeze): Don't increment any hart-local counters while in Debug Mode or +
on {\tt ebreak} instructions that cause entry into Debug Mode. +
These counters include the {\tt instret} CSR. On single-hart cores +
{\tt cycle} should be stopped, but on multi-hart cores it must keep +
incrementing.

An implementation may hardwire this bit to 0 or 1.
|WARL
|Preset
|[[dcsrstoptime,dcsrstoptime]] `stoptime`
|

0 (normal): \Rtime continues to reflect \Rmtime.


1 (freeze): \Rtime is frozen at the time that Debug Mode was entered. When +
leaving Debug Mode, \Rtime will reflect the latest +
value of \Rmtime again.

While all harts have \FcsrDcsrStoptime=1 and are in Debug Mode, +
\Rmtime is allowed to stop incrementing.

An implementation may hardwire this bit to 0 or 1.
|WARL
|Preset
|[[dcsrcause,dcsrcause]] `cause`
|Explains why Debug Mode was entered.

When there are multiple reasons to enter Debug Mode in a single +
cycle, hardware should set \FcsrDcsrCause to the cause with the highest +
priority.  See table~\ref{tab:dcsrcausepriority} for priorities.

1 (ebreak): An {\tt ebreak} instruction was executed.


2 (trigger): A Trigger Module trigger fired with action=1.


3 (haltreq): The debugger requested entry to Debug Mode using \FdmDmcontrolHaltreq.


4 (step): The hart single stepped because \FcsrDcsrStep was set.


5 (resethaltreq): The hart halted directly out of reset due to \Fresethaltreq. It +
is also acceptable to report 3 when this happens.


6 (group): The hart halted because it's part of a halt group. +
Harts may report 3 for this cause instead.

Other values are reserved for future use.
|R
|0
|[[dcsrv,dcsrv]] `v`
|Extends the prv field with the virtualization mode the hart was operating +
in when Debug Mode was entered. The encoding is described in Table +
\ref{tab:privmode}. +
A debugger can change this value to change the hart's virtualization mode +
when exiting Debug Mode. +
This bit is hardwired to 0 on harts that do not support virtualization mode.
|WARL
|0
|[[dcsrmprven,dcsrmprven]] `mprven`
|

0 (disabled): \FcsrMstatusMprv in \Rmstatus is ignored in Debug Mode.


1 (enabled): \FcsrMstatusMprv in \Rmstatus takes effect in Debug Mode.

Implementing this bit is optional. It may be tied to either 0 or 1.
|WARL
|Preset
|[[dcsrnmip,dcsrnmip]] `nmip`
|When set, there is a Non-Maskable-Interrupt (NMI) pending for the hart.

Since an NMI can indicate a hardware error condition, +
reliable debugging may no longer be possible once this bit becomes set. +
This is implementation-dependent.
|R
|0
|[[dcsrstep,dcsrstep]] `step`
|When set and not in Debug Mode, the hart will only execute a single +
instruction and then enter Debug Mode. See Section~\ref{stepBit} +
for details.

The debugger must not change the value of this bit while the hart +
is running.
|R/W
|0
|[[dcsrprv,dcsrprv]] `prv`
|Contains the privilege mode the hart was operating in when Debug +
Mode was entered. The encoding is described in Table +
\ref{tab:privmode}.  A debugger can change this value to change +
the hart's privilege mode when exiting Debug Mode.

Not all privilege modes are supported on all harts. If the +
encoding written is not supported or the debugger is not allowed to +
change to it, the hart may change to any supported privilege mode.
|WARL
|3
|===

==== Debug PC (((dpc)), at 0x7b1)

[[csr_dpc]]
Upon entry to debug mode, \RcsrDpc is updated with the virtual address of
the next instruction to be executed. The behavior is described in more
detail in Table~\ref{tab:dpc}.

\begin{table}[H]
\centering
\caption{Virtual address in DPC upon Debug Mode Entry}
\label{tab:dpc}
\begin{tabular}{|l|L|}
\hline
Cause & Virtual Address in DPC \\
\hline
{\tt ebreak} & Address of the {\tt ebreak} instruction \\
\hline
single step & Address of the instruction that would be executed
next if no debugging was going on. Ie. $\Rpc+4$ for 32-bit instructions
that don't change program flow, the destination PC on taken
jumps/branches, etc. \\
\hline
trigger module & The address of the next instruction to be
executed at the time that debug mode was entered. If the trigger is
\RcsrMcontrol and \FcsrMcontrolTiming is 0 or if the trigger is
\RcsrMcontrolSix and \FcsrMcontrolSixHitOne is 0, this
corresponds to the address of the instruction which caused the trigger
to fire. \\
\hline
halt request & Address of the next instruction to be
executed at the time that debug mode was entered \\
\hline
\end{tabular}
\end{table}

Executing the Program Buffer may cause the value of \RcsrDpc to become
\unspecified. If that is the case, it must be possible to read/write
\RcsrDpc using an abstract command with \FacAccessregisterPostexec not
set.  The debugger must attempt to save \RcsrDpc between halting and
executing a Program Buffer, and then restore \RcsrDpc before leaving
Debug Mode.

\begin{commentary}
Allowing \RcsrDpc to become \unspecified\ upon Program Buffer
execution allows for direct implementations that don't have a
separate PC register, and do need to use the PC when executing the
Program Buffer.
\end{commentary}

If the Access Register abstract command supports reading \RcsrDpc while
the hart is running, then the value read should be the address of a
recently executed instruction.

If the Access Register abstract command supports writing \RcsrDpc while
the hart is running, then the executing program should jump to the
written address shortly after the write occurs.

The writability of \RcsrDpc follows the same rules as \Rmepc as defined
in the Privileged Spec.  In particular, \RcsrDpc must be able to hold
all valid virtual addresses and the writability of the low bits depends
on IALIGN.

When resuming, the hart's PC is updated to the virtual address stored in
\RcsrDpc. A debugger may write \RcsrDpc to change where the hart resumes.

This CSR is read/write.

==== Debug Scratch Register 0 (((dscratch0)), at 0x7b2)

[[csr_dscratch0]]
Optional scratch register that can be used by implementations that need
it. A debugger must not write to this register unless \RdmHartinfo
explicitly mentions it (the Debug Module may use this register internally).

This CSR is read/write.

==== Debug Scratch Register 1 (((dscratch1)), at 0x7b3)

[[csr_dscratch1]]
Optional scratch register that can be used by implementations that need
it. A debugger must not write to this register unless \RdmHartinfo
explicitly mentions it (the Debug Module may use this register internally).

This CSR is read/write.

