\chapter{RISC-V Debug}
\label{sec:core_debug}

Modifications to the RISC-V core to support debug are kept to a minimum.  There
is a special execution mode (Debug Mode) and a few extra CSRs. The DM takes care
of the rest.

\section{Debug Mode} \label{debugmode}

Debug Mode is a special processor mode used only when a hart is halted for
external debugging. How Debug Mode is implemented is not specified here.

\begin{steps}{When executing code from the Program Buffer, the hart stays
    in Debug Mode and the following apply:}
\item All operations are executed at machine mode privilege level, except that
    \Fmprv in \Rmstatus is ignored.
\item All interrupts (including NMI) are masked.
\item Exceptions don't update any registers.  That includes {\tt cause}, {\tt
    epc}, {\tt tval}, {\tt dpc}, and \Rmstatus. They do end execution of the
    Program Buffer.
\item No action is taken if a trigger matches.
\item Trace is disabled.
\item Counters may be stopped, depending on \Fstopcount in \Rdcsr.
\item Timers may be stopped, depending on \Fstoptime in \Rdcsr.
\item The {\tt wfi} instruction acts as a {\tt nop}.
\item Almost all instructions that change the privilege level have undefined
    behavior.  This includes {\tt ecall}, {\tt mret}, {\tt hret}, {\tt sret},
    and {\tt uret}.  (To change the privilege level, the debugger can write
    \Fprv in \Rdcsr). The only exception is {\tt ebreak}. When that is executed
    in Debug Mode, it halts the hart again but without updating \Rdpc or \Rdcsr.
\end{steps}

\section{Load-Reserved/Store-Conditional Instructions}

The reservation registered by an {\tt lr} instruction on a memory address may
be lost when entering Debug Mode or while in Debug Mode.  This means that there
may be no forward progress if Debug Mode is entered between {\tt lr} and {\tt
sc} pairs.

\begin{commentary}
    This is a behavior that debug users must be aware of. If they have a
    breakpoint set between a {\tt lr} and {\tt sc} pair, or are stepping
    through such code, the {\tt sc} may never succeed.  Fortunately in general use
    there will be very few instructions in such a sequence, and anybody
    debugging it will quickly notice that the reservation is not occurring.
    The solution in that case is to set a breakpoint on the first instruction
    after the {\tt sc} and run to it.
\end{commentary}

\section{Single Step}

A debugger can cause a halted hart to execute a single instruction and then
re-enter Debug Mode by setting \Fstep before setting \Fresumereq.

If executing or fetching that instruction causes an exception, Debug Mode is
re-entered immediately after the PC is changed to the exception handler and the
appropriate {\tt tval} and {\tt cause} registers are updated.

If executing or fetching the instruction causes a trigger to fire, Debug Mode
is re-entered immediately after that trigger has fired. In that case \Fcause is
set to 2 (trigger) instead of 4 (single step).  Whether the instruction is
executed or not depends on the specific configuration of the trigger.

If the instruction that is executed causes the PC to change to an address where
an instruction fetch causes an exception, that exception does not occurr until
the next time the hart is resumed. Similarly, a trigger at the new address does
not fire until the hart actually attempts to execute that instruction.

\section{Reset}

If the halt signal (driven by the hart's halt request bit in the Debug Module)
is asserted when a hart comes out of reset, the hart must
enter Debug Mode before executing any instructions, but after performing any
initialization that would usually happen before the first instruction is
executed.

\subsection{{\tt dret} Instruction} \label{dret}

To return from Debug Mode, a new instruction is defined: {\tt dret}. It has an
encoding of 0x7b200073. On harts which support this instruction,
executing {\tt dret} in Debug Mode changes \Rpc to the value
stored in \Rdpc. The current privilege level is changed to that specified by
\Fprv in \Rdcsr. The hart is no longer in debug mode.

Executing {\tt dret} outside of Debug Mode causes an illegal instruction exception.

It is not necessary for the debugger to know whether an implementation supports
{\tt dret}, as the Debug Module will ensure that it is executed if necessary.
It is defined in this specification only to reserve the opcode and
allow for reusable Debug Module implementations.

\section{Core Debug Registers} \label{debreg}

The supported Core Debug Registers must be implemented for each hart that can
be debugged.

\input{core_registers.tex}

\section{Virtual Debug Registers} \label{virtreg}

Virtual debug registers are a requirement on the debugger SW/interface,
not on the Core designer.

\input{sw_registers.tex}
