trigger.tex

\chapter{Trigger Module}
\label{sec:trigger}

Triggers can cause a breakpoint exception, entry into Debug Mode, or a trace action
without having to execute a special instruction. This makes them invaluable
when debugging code from ROM. They can trigger on execution of instructions at
a given memory address, or on the address/data in loads/stores.  These are all
features that can be useful without having the Debug Module present, so the
Trigger Module is broken out as a separate piece that can be implemented
separately.

Triggers do not fire while in Debug Mode.

\begin{steps}{Each trigger may support a variety of features. A debugger can
    build a list of all triggers and their features as follows:}
\item Write 0 to \Rtselect.
\item Read back \Rtselect and check that it contains the written value. If not,
    exit the loop.
\item Read \Rtinfo.
\item If that caused an exception, the debugger must read \Rtdataone to
    discover the type. (If \Ftype is 0, this trigger doesn't exist. Exit the
    loop.)
\item If \Finfo is 1, this trigger doesn't exist. Exit the loop.
\item Otherwise, the selected trigger supports the types discovered in \Finfo.
\item Repeat, incrementing the value in \Rtselect.
\end{steps}

\begin{commentary}
    There are two ways to check whether a given trigger is the last one to
    support these implementations:
    \begin{enumerate}
        \item When no hardware triggers are implemented at all, all related
            registers return 0. The algorithm above terminates when checking
            \Ftype.
        \item When 2 triggers are implemented, \Rtselect is just a single bit
            that selects one of the two. When the debugger writes 2, it reads
            back as 0 which terminates the enumeration.
    \end{enumerate}
\end{commentary}

\section{Native M-Mode Triggers}
\label{sec:mmtrigger}

Triggers can be used for native debugging. On a fully featured system triggers
will be set using \Fu or \Fs, and when firing they can cause a breakpoint exception
to trap to a more privileged mode. It is possible to set triggers natively to
fire in M mode as well. In that case there is no higher privilege mode to trap
to. When such a trigger causes a breakpoint exception while already in a trap
handler, this will leave the system unable to resume normal execution.

On full-featured systems this is a remote corner case that can probably be
ignored. On systems that only implement M mode, however, it is recommended to
implement one of two solutions to this problem. This way triggers can be useful
for native debugging of even M mode code.

The simple solution is to have the hardware prevent triggers with action=0 from
firing while in M mode and while \Fmie in \Rmstatus is 0. Its limitation is
that interrupts might be disabled at other times when a user might want
triggers to fire.

A more complex solution is to implement \Fmte and \Fmpte in \Rtcontrol. This
solution has the benefit that it only disables triggers during the trap
handler.

A user setting M mode triggers that cause breakpoint exceptions will have to be
aware of any problems that might come up with the particular system they are
working on.

\section{Trigger Registers}

These registers are CSRs, accessible using the RISC-V {\tt csr} opcodes and
optionally also using abstract debug commands.

Most trigger functionality is optional. All {\tt tdata} registers follow
write-any-read-legal semantics. If a debugger writes an unsupported
configuration, the register will read back a value that is supported (which may
simply be a disabled trigger).  This means that a debugger must always read
back values it writes to {\tt tdata} registers, unless it already knows already
what is
supported.  Writes to one {\tt tdata} register may not modify the contents of
other {\tt tdata} registers, nor the configuration of any trigger besides the
one that is currently selected.

\input{hwbp_registers.tex}