debugger_implementation.tex

\chapter{Debugger Implementation}

\section{C Header File}

\href{https://github.com/riscv/riscv-debug-spec}
{https://github.com/riscv/riscv-debug-spec} contains instructions for generating
a C header file that defines macros for every field in every register/abstract
command mentioned in this document.

\section{External Debugger Implementation}

This section details how an external debugger might use the described debug
interface to perform some common operations on RISC-V cores using the JTAG DTM
described in Section~\ref{sec:jtagdtm}.
All these examples assume a 32-bit core but it should be easy to adapt the
examples to 64- or 128-bit cores.

To keep the examples readable, they all assume that everything succeeds, and
that they complete faster than the debugger can perform the next access. This
will be the case in a typical JTAG setup. However, the debugger must always
check the sticky error status bits after performing a sequence of actions. If
it sees any that are set, then it should attempt the same actions again,
possibly while adding in some delay, or explicit checks for status bits.

\subsection{Debug Module Interface Access} \label{dmiaccess}

To read an arbitrary Debug Module register, select \RdtmDmi, and scan in a value
with \FdtmDmiOp set to 1, and \FdmSbaddressZeroAddress set to the desired register address. In
Update-DR the operation will start, and in Capture-DR its results will be
captured into \FdmSbdataZeroData.  If the operation didn't complete in time, \FdtmDmiOp will be 3
and the value in \FdmSbdataZeroData must be ignored. The busy condition must be cleared by
writing \FdtmDtmcsDmireset in \RdtmDtmcs, and then the second scan scan must be performed again.
This process must be repeated until \FdtmDmiOp returns 0.
In later operations the debugger should allow for more time between Update-DR and
Capture-DR.

To write an arbitrary Debug Bus register, select \RdtmDmi, and scan in a value
with \FdtmDmiOp set to 2, and \FdmSbaddressZeroAddress and \FdmSbdataZeroData set to the desired register
address and data respectively. From then on everything happens exactly as with
a read, except that a write is performed instead of the read.

It should almost never be necessary to scan IR, avoiding a big part of the
inefficiency in typical JTAG use.

\subsection{Checking for Halted Harts}

A user will want to know as quickly as possible when a hart is halted (e.g.\ due
to a breakpoint).  To efficiently determine which harts are halted when there
are many harts, the debugger uses the {\tt haltsum} registers. Assuming the
maximum number of harts exist, first it checks \RdmHaltsumThree. For each bit set
there, it writes \Fhartsel, and checks \RdmHaltsumTwo. This process repeats
through \RdmHaltsumOne and \RdmHaltsumZero. Depending on how many harts exist, the
process should start at one of the lower {\tt haltsum} registers.

\subsection{Halting} \label{deb:halt}

To halt one or more harts, the debugger selects them, sets \FdmDmcontrolHaltreq, and then
waits for \FdmDmstatusAllhalted to indicate the harts are halted. Then it can clear
\FdmDmcontrolHaltreq to 0, or leave it high to catch a hart that resets while halted.

\subsection{Running}

First, the debugger should restore any registers that it has overwritten.
Then it can let the selected harts run by setting \FdmDmcontrolResumereq. Once
\FdmDmstatusAllresumeack is set, the debugger knows the selected harts have resumed.
Harts might halt very quickly after resuming (e.g.
by hitting a software breakpoint) so the debugger cannot use
\FdmDmstatusAllhalted/\FdmDmstatusAnyhalted to check whether the hart resumed.

\subsection{Single Step}

Using the hardware single step feature is almost the same as regular running.
The debugger just sets \FcsrDcsrStep in \RcsrDcsr before letting the hart run. The hart
behaves exactly as in the running case, except that interrupts may be disabled
(depending on \FcsrDcsrStepie) and it only fetches and executes a single instruction
before re-entering Debug Mode.

\subsection{Accessing Registers}

\subsubsection{Using Abstract Command} \label{deb:abstractreg}

\noindent Read \Szero using abstract command:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmCommand & \FacAccessregisterAarsize$=2$, \FacAccessregisterTransfer, \FacAccessregisterRegno = 0x1008 & Read \Szero \\
    \hline
    Read & \RdmDataZero & - & Returns value that was in \Szero \\
    \hline
\end{tabular}
\medskip

\noindent Write \Rmstatus using abstract command:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmDataZero & new value & \\
    \hline
    Write & \RdmCommand & \FacAccessregisterAarsize$=2$, \FacAccessregisterTransfer, \FacAccessregisterWrite, \FacAccessregisterRegno = 0x300 & Write \Rmstatus \\
    \hline
\end{tabular}
\medskip

\subsubsection{Using Program Buffer} \label{deb:regprogbuf}

Abstract commands are used to exchange data with GPRs. Using this mechanism, other
registers can be accessed by moving their value into/out of GPRs.

\noindent Write \Rmstatus using program buffer:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmProgbufZero & {\tt csrw s0, MSTATUS} & \\
    \hline
    Write & {\tt progbuf1} & {\tt ebreak} & \\
    \hline
    Write & \RdmDataZero & new value & \\
    \hline
    Write & \RdmCommand & \FacAccessregisterAarsize$=2$, \FacAccessregisterPostexec, \FacAccessregisterTransfer, \FacAccessregisterWrite, \FacAccessregisterRegno = 0x1008 &
        Write \Szero, then execute program buffer \\
    \hline
\end{tabular}
\medskip

\noindent Read \Fone using program buffer:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmProgbufZero & {\tt fmv.x.s s0, f1} & \\
    \hline
    Write & {\tt progbuf1} & {\tt ebreak} & \\
    \hline
    Write & \RdmCommand & \FacAccessregisterPostexec & Execute program buffer \\
    \hline
    Write & \RdmCommand & \FacAccessregisterTransfer, \FacAccessregisterRegno = 0x1008 & read \Szero \\
    \hline
    Read & \RdmDataZero & - & Returns the value that was in \Fone \\
    \hline
\end{tabular}
\medskip

\subsection{Reading Memory}

\subsubsection{Using System Bus Access} \label{deb:mrsysbus}

With system bus access, addresses are physical system bus addresses.

\noindent Read a word from memory using system bus access:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmSbcs & \FdmSbcsSbaccess$=2$, \FdmSbcsSbreadonaddr & Setup \\
    \hline
    Write & \RdmSbaddressZero & address & \\
    \hline
    Read & \RdmSbdataZero & - & Value read from memory \\
    \hline
\end{tabular}
\medskip

\noindent Read block of memory using system bus access:

\begin{tabular}{|r|r|p{13em}|l|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmSbcs & \FdmSbcsSbaccess$=2$, \FdmSbcsSbreadonaddr, \FdmSbcsSbreadondata, \FdmSbcsSbautoincrement &
            Turn on autoread and autoincrement \\
    \hline
    Write & \RdmSbaddressZero & address & Writing address triggers read and increment \\
    \hline
    Read & \RdmSbdataZero & - & Value read from memory \\
    \hline
    Read & \RdmSbdataZero & - & Next value read from memory \\
    \hline
    ... & ... & ... & ... \\
    \hline
    Write & \RdmSbcs & 0 & Disable autoread \\
    \hline
    Read & \RdmSbdataZero & - & Get last value read from memory. \\
    \hline
\end{tabular}
\medskip

\subsubsection{Using Program Buffer} \label{deb:mrprogbuf}

Through the Program Buffer, the hart performs the memory accesses. Addresses
are physical or virtual (depending on \FcsrDcsrMprven and other system
configuration).

\noindent Read a word from memory using program buffer:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmProgbufZero & {\tt lw s0, 0(s0)} & \\
    \hline
    Write & {\tt progbuf1} & {\tt ebreak} & \\
    \hline
    Write & \RdmDataZero & address & \\
    \hline
    Write & \RdmCommand & \FacAccessregisterWrite, \FacAccessregisterPostexec, \FacAccessregisterRegno = 0x1008 & Write \Szero, then execute program buffer \\
    \hline
    Write & \RdmCommand & \FacAccessregisterRegno = 0x1008 & Read \Szero \\
    \hline
    Read & \RdmDataZero & - & Value read from memory \\
    \hline
\end{tabular}
\medskip

\noindent Read block of memory using program buffer:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmProgbufZero & {\tt lw s1, 0(s0)} & \\
    \hline
    Write & {\tt progbuf1} & {\tt addi s0, s0, 4} & \\
    \hline
    Write & {\tt progbuf2} & {\tt ebreak} & \\
    \hline
    Write & \RdmDataZero & address & \\
    \hline
    Write & \RdmCommand & \FacAccessregisterWrite, \FacAccessregisterPostexec, \FacAccessregisterRegno = 0x1008 & Write \Szero, then execute program buffer \\
    \hline
    Write & \RdmCommand & \FacAccessregisterPostexec, \FacAccessregisterRegno = 0x1009 & Read \Sone, then execute program buffer \\
    \hline
    Write & \RdmAbstractauto & \FdmAbstractautoAutoexecdata[0] & Set \FdmAbstractautoAutoexecdata[0] \\
    \hline
    Read & \RdmDataZero & - & Get value read from memory, then execute program buffer \\
    \hline
    Read & \RdmDataZero & - & Get next value read from memory, then execute program buffer \\
    \hline
    ... & ... & ... & ... \\
    \hline
    Write & \RdmAbstractauto & 0 & Clear \FdmAbstractautoAutoexecdata[0] \\
    \hline
    Read & \RdmDataZero & - & Get last value read from memory. \\
    \hline
\end{tabular}
\medskip

\subsubsection{Using Abstract Memory Access} \label{deb:mrabstract}

Abstract memory accesses act as if they are performed by the hart, although the
actual implementation may differ.

\noindent Read a word from memory using abstract memory access:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \Rdataone & address & \\
    \hline
    Write & \RdmCommand & cmdtype=2, \FacAccessmemoryAamsize=2 & \\
    \hline
    Read & \RdmDataZero & - & Value read from memory \\
    \hline
\end{tabular}
\medskip

\noindent Read block of memory using abstract memory access:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmAbstractauto & 1 & Re-execute the command when \RdmDataZero is accessed \\
    \hline
    Write & \Rdataone & address & \\
    \hline
    Write & \RdmCommand & cmdtype=2, \FacAccessmemoryAamsize=2, \FacAccessmemoryAampostincrement=1 & \\
    \hline
    Read & \RdmDataZero & - & Read value, and trigger reading of next address \\
    \hline
    ... & ... & ... & ... \\
    \hline
    Write & \RdmAbstractauto & 0 & Disable auto-exec \\
    \hline
    Read & \RdmDataZero & - & Get last value read from memory. \\
    \hline
\end{tabular}
\medskip

\subsection{Writing Memory} \label{writemem}

\subsubsection{Using System Bus Access} \label{deb:mrsysbus}

With system bus access, addresses are physical system bus addresses.

\noindent Write a word to memory using system bus access:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmSbcs & \FdmSbcsSbaccess$=2$ & Configure access size \\
    \hline
    Write & \RdmSbaddressZero & address & \\
    \hline
    Write & \RdmSbdataZero & value & \\
    \hline
\end{tabular}
\medskip

\noindent Write a block of memory using system bus access:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmSbcs & \FdmSbcsSbaccess$=2$, \FdmSbcsSbautoincrement & Turn on autoincrement \\
    \hline
    Write & \RdmSbaddressZero & address & \\
    \hline
    Write & \RdmSbdataZero & value0 & \\
    \hline
    Write & \RdmSbdataZero & value1 & \\
    \hline
    ... & ... & ... & ... \\
    \hline
    Write & \RdmSbdataZero & valueN & \\
    \hline
\end{tabular}
\medskip

\subsubsection{Using Program Buffer} \label{deb:mrprogbuf}

Through the Program Buffer, the hart performs the memory accesses. Addresses
are physical or virtual (depending on \FcsrDcsrMprven and other system
configuration).

\noindent Write a word to memory using program buffer:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmProgbufZero & {\tt sw s1, 0(s0)} & \\
    \hline
    Write & {\tt progbuf1} & {\tt ebreak} & \\
    \hline
    Write & \RdmDataZero & address & \\
    \hline
    Write & \RdmCommand & \FacAccessregisterWrite, \FacAccessregisterRegno = 0x1008 & Write \Szero \\
    \hline
    Write & \RdmDataZero & value & \\
    \hline
    Write & \RdmCommand & \FacAccessregisterWrite, \FacAccessregisterPostexec, \FacAccessregisterRegno = 0x1009 & Write \Sone, then execute program buffer \\
    \hline
\end{tabular}
\medskip

\noindent Write block of memory using program buffer:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmProgbufZero & {\tt sw s1, 0(s0)} & \\
    \hline
    Write & {\tt progbuf1} & {\tt addi s0, s0, 4} & \\
    \hline
    Write & {\tt progbuf2} & {\tt ebreak} & \\
    \hline
    Write & \RdmDataZero & address & \\
    \hline
    Write & \RdmCommand & \FacAccessregisterWrite, \FacAccessregisterRegno = 0x1008 & Write \Szero \\
    \hline
    Write & \RdmDataZero & value0 & \\
    \hline
    Write & \RdmCommand & \FacAccessregisterWrite, \FacAccessregisterPostexec, \FacAccessregisterRegno = 0x1009 & Write \Sone, then execute program buffer \\
    \hline
    Write & \RdmAbstractauto & \FdmAbstractautoAutoexecdata[0] & Set \FdmAbstractautoAutoexecdata[0] \\
    \hline
    Write & \RdmDataZero & value1 & \\
    \hline
    ... & ... & ... & ... \\
    \hline
    Write & \RdmDataZero & valueN & \\
    \hline
    Write & \RdmAbstractauto & 0 & Clear \FdmAbstractautoAutoexecdata[0] \\
    \hline
\end{tabular}
\medskip

\subsubsection{Using Abstract Memory Access} \label{deb:mwabstract}

Abstract memory accesses act as if they are performed by the hart, although the
actual implementation may differ.

\noindent Write a word to memory using abstract memory access:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \Rdataone & address & \\
    \hline
    Write & \RdmDataZero & value & \\
    \hline
    Write & \RdmCommand & cmdtype=2, \FacAccessmemoryAamsize=2, write=1 & \\
    \hline
\end{tabular}
\medskip

\noindent Write a block of memory using abstract memory access:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \Rdataone & address & \\
    \hline
    Write & \RdmDataZero & value0 & \\
    \hline
    Write & \RdmCommand & cmdtype=2, \FacAccessmemoryAamsize=2, write=1, \FacAccessmemoryAampostincrement=1 & \\
    \hline
    Write & \RdmAbstractauto & 1 & Re-execute the command when \RdmDataZero is accessed \\
    \hline
    Write & \RdmDataZero & value1 & \\
    \hline
    Write & \RdmDataZero & value2 & \\
    \hline
    ... & ... & ... & ... \\
    \hline
    Write & \RdmDataZero & valueN & \\
    \hline
    Write & \RdmAbstractauto & 0 & Disable auto-exec \\
    \hline
\end{tabular}
\medskip

\subsection{Triggers}

A debugger can use hardware triggers to halt a hart when a certain event
occurs.  Below are some examples, but as there is no requirement on the number
of features of the triggers implemented by a hart, these examples might not be
applicable to all implementations.  When a debugger wants to set a trigger, it
writes the desired configuration, and then reads back to see if that
configuration is supported.  All examples assume XLEN=32.

\noindent Enter Debug Mode when the instruction at 0x80001234 is
executed, to be used as an instruction breakpoint in ROM:

\begin{tabulary}{\textwidth}{|r|r|L|}
    \hline
    \RcsrTdataOne & 0x6980105c & type=6, dmode=1, action=1, select=0, match=0, m=1, s=1, u=1, vs=1, vu=1, execute=1 \\
    \hline
    \RcsrTdataTwo & 0x80001234 & address \\
    \hline
\end{tabulary}
\medskip

\noindent Enter Debug Mode when performing a load at address 0x80007f80 in
M-mode or S-mode or U-mode:

\begin{tabulary}{\textwidth}{|r|r|L|}
    \hline
    \RcsrTdataOne & 0x68001059 & type=6, dmode=1, action=1, select=0, match=0, m=1, s=1, u=1, load=1 \\
    \hline
    \RcsrTdataTwo & 0x80007f80 & address \\
    \hline
\end{tabulary}
\medskip

\noindent Enter Debug Mode when storing to an address between
0x80007c80 and 0x80007cef (inclusive) in VS-mode or VU-mode
when hgatp.VMID=1:

\begin{tabulary}{\textwidth}{|r|r|L|}
    \hline
    \RcsrTdataOne 0 & 0x69801902 & type=6, dmode=1, action=1, chain=1, select=0, match=2, vs=1, vu=1, store=1 \\
    \hline
    \RcsrTdataTwo 0 & 0x80007c80 & start address (inclusive) \\
    \hline
    \RcsrTextraThirtytwo 0 & 0x03000000 & mhselect=6, mhvalue=0 \\
    \hline
    \RcsrTdataOne 1 & 0x69801182 & type=6, dmode=1, action=1, select=0, match=3, vs=1, vu=1, store=1 \\
    \hline
    \RcsrTdataTwo 1 & 0x80007cf0 & end address (exclusive) \\
    \hline
    \RcsrTextraThirtytwo 1 & 0x03000000 & mhselect=6, mhvalue=0 \\
    \hline
\end{tabulary}
\medskip

\noindent Enter Debug Mode when storing to an address between
0x81230000 and 0x8123ffff (inclusive):

\begin{tabulary}{\textwidth}{|r|r|L|}
    \hline
    \RcsrTdataOne & 0x698010da & type=6, dmode=1, action=1, select=0, match=1, m=1, s=1, u=1, vs=1, vu=1, store=1 \\
    \hline
    \RcsrTdataTwo & 0x81237fff & 16 upper bits to match exactly, then 0, then all ones. \\
    \hline
\end{tabulary}
\medskip

\noindent Enter Debug Mode when loading from an address between
0x86753090 and 0x8675309f or between 0x96753090 and 0x9675309f (inclusive):

\begin{tabulary}{\textwidth}{|r|r|L|}
    \hline
    \RcsrTdataOne 0 & 0x69801a59 & type=6, dmode=1, action=1, chain=1, match=4, m=1, s=1, u=1, vs=1, vu=1, load=1 \\
    \hline
    \RcsrTdataTwo 0 & 0xfff03090 & Mask for low half, then match for low half \\
    \hline
    \RcsrTdataOne 1 & 0x698012d9 & type=6, dmode=1, action=1, match=5, m=1, s=1, u=1, vs=1, vu=1, load=1 \\
    \hline
    \RcsrTdataTwo 1 & 0xefff8675 & Mask for high half, then match for high half \\
    \hline
\end{tabulary}
\medskip

\subsection{Handling Exceptions}

Generally the debugger can avoid exceptions by being careful with the programs
it writes. Sometimes they are unavoidable though, e.g.\ if the user asks to
access memory or a CSR that is not implemented. A typical debugger will not
know enough about the hardware platform to know what's going to happen, and must attempt
the access to determine the outcome.

When an exception occurs while executing the Program Buffer, \FdmAbstractcsCmderr becomes
set. The debugger can check this field to see whether a program encountered an
exception.  If there was an exception, it's left to the debugger to know what
must have caused it.

\subsection{Quick Access} \label{quickaccess}

There are a variety of instructions to transfer data between GPRs and the {\tt
data} registers. They are either loads/stores or CSR reads/writes. The specific
addresses also vary. This is all specified in \RdmHartinfo. The examples here use
the pseudo-op {\tt transfer dest, src} to represent all these options.

Halt the hart for a minimum amount of time to perform a single memory write:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmProgbufZero & {\tt transfer arg2, s0} & Save \Szero \\
    \hline
    Write & {\tt progbuf1} & {\tt transfer s0, arg0} & Read first argument (address) \\
    \hline
    Write & {\tt progbuf2} & {\tt transfer arg0, s1} & Save \Sone \\
    \hline
    Write & {\tt progbuf3} & {\tt transfer s1, arg1} & Read second argument (data) \\
    \hline
    Write & {\tt progbuf4} & {\tt sw s1, 0(s0)} & \\
    \hline
    Write & {\tt progbuf5} & {\tt transfer s1, arg0} & Restore \Sone \\
    \hline
    Write & {\tt progbuf6} & {\tt transfer s0, arg2} & Restore \Szero \\
    \hline
    Write & {\tt progbuf7} & {\tt ebreak} & \\
    \hline
    Write & \RdmDataZero & address & \\
    \hline
    Write & {\tt data1} & data & \\
    \hline
    Write & \RdmCommand & 0x10000000 & Perform quick access \\
    \hline
\end{tabular}

This shows an example of setting the \FcsrMcontrolM bit in \RcsrMcontrol to
enable a hardware breakpoint in M-mode.
Similar quick access instructions could have been used previously
to configure the trigger that is being enabled here:

\begin{tabular}{|c|r|p{0.3\textwidth}|p{0.3\textwidth}|}
    \hline
    Op & Address & Value & Comment \\
    \hline
    Write & \RdmProgbufZero & {\tt transfer arg0, s0} & Save \Szero \\
    \hline
    Write & {\tt progbuf1} & {\tt li s0, (1 << 6)} & Form the mask for \FcsrMcontrolM bit \\
    \hline
    Write & {\tt progbuf2} & {\tt csrrs x0, \RcsrTdataOne, s0} & Apply the mask to \RcsrMcontrol \\
    \hline
    Write & {\tt progbuf3} & {\tt transfer s0, arg2} & Restore \Szero \\
    \hline
    Write & {\tt progbuf4} & {\tt ebreak} & \\
   \hline
    Write & \RdmCommand & 0x10000000 & Perform quick access \\
   \hline
\end{tabular}

\section{Native Debugger Implementation}

The spec contains a few features to aid in writing a native debugger. This
section describes how some common tasks might be achieved.

\subsection{Single Step} \label{nativestep}

Single step is straightforward if the OS or a debug stub runs in M-Mode while the
program being debugged runs in a less privileged mode. When a step is required,
the OS or debug stub writes \FcsrIcountCount=1, \FcsrIcountAction=0,
\FcsrIcountM=0 before returning control to the lower user program with an
{\tt mret} instruction.

Stepping code running in the same privilege mode as the debugger is more
complicated, depending on what other debug features are implemented.

If hardware implements \FcsrTcontrolMpte and \FcsrTcontrolMte, then stepping
through non-trap code which doesn't allow for nested interrupts is also
straightforward.

If hardware automatically prevents \FcsrMcontrolSixAction=0 triggers from
matching when entering a trap handler as described in
Section~\ref{sec:nativetrigger}, then a carefully written trap handler can
ensure that interrupts are disabled whenever the icount trigger must not match.

If neither of these features exist, then single step is doable, but tricky to
get right. To single step, the debug stub would execute something like:
\begin{verbatim}
    li    t0, \FcsrIcountCount=4, \FcsrIcountAction=0, \FcsrIcountM=1
    csrw  tdata1, t0    /* Write the trigger. */
    lw    t0, 8(sp)     /* Restore t0, count decrements to 3 */
    lw    sp, 0(sp)     /* Restore sp, count decrements to 2 */
    mret                /* Return to program being debugged. count decrements to 1 */
\end{verbatim}

There is an additional problem with using \RcsrIcount to single step.  An
instruction may cause an exception into a more privileged mode where the trigger
is not enabled.  The exception handler might address the cause of the exception,
and then restart the instruction.  Examples of this include page faults, FPU
instructions when the FPU is not yet enabled, and interrupts.
When a user is single stepping
through such code, they will have to step twice to get past the restarted
instruction. The first time the exception handler runs, and the second time the
instruction actually executes. That is confusing and usually undesirable.

To help users out, debuggers should detect when a single step restarted an
instruction, and then step again. This way the users see the expected behavior
of stepping over the instruction. Ideally the debugger would notify the user
that an exception handler executed the first time.

The debugger should perform this extra step when the PC doesn't change during a
regular step.

\begin{commentary}
    It is safe to perform an extra step when the PC changes, because every
    RISC-V instruction either changes the PC or has side effects when repeated,
    but never both.
\end{commentary}

To avoid an infinite loop if the exception handler does not address the cause of
the exception, the debugger must execute no more than a single extra step.