<registers name="Trigger Registers" prefix="CSR_">
    The trigger registers are only accessible in machine and Debug Mode to
    prevent untrusted user code from causing entry into Debug Mode without the
    OS's permission.

    \begin{table}[H]
    \centering
    \caption{\Faction encoding}
    \label{tab:action}
    \begin{tabular}{|r|L|}
    \hline
    Value &amp; Description \\
    \hline
    0 &amp; Raise a breakpoint exception. (Used when software wants to use the
    trigger module without an external debugger attached.) \\
    \hline
    1 &amp; Enter Debug Mode. (Only supported when the trigger's \Fdmode is 1.)
    \\
    \hline
    2 &amp; Start tracing. \\
    \hline
    3 &amp; Stop tracing. \\
    \hline
    4 &amp; Emit trace data for this match. If it is a data access match, emit
    appropriate Load/Store Address/Data. If it is an instruction execution,
    emit its PC. \\
    \hline
    other &amp; Reserved for future use. \\
    \hline
    \end{tabular}
    \end{table}

    <register name="Trigger Select" short="tselect" address="0x7a0">
        This register determines which trigger is accessible through the other
        trigger registers. The set of accessible triggers must start at 0, and
        be contiguous.

        Writes of values greater than or equal to the number of supported
        triggers may result in a different value in this register than what was
        written. To verify that what they wrote is a valid index, debuggers can
        read back the value and check that \Rtselect holds what they wrote.

        Since triggers can be used both by Debug Mode and M Mode, the debugger
        must restore this register if it modifies it.

        <field name="index" bits="MXLEN-1:0" access="R/W" reset="0" />
    </register>

    <register name="Trigger Data 1" short="tdata1" address="0x7a1">
        <field name="type" bits="MXLEN-1:MXLEN-4" access="R/W" reset="Preset">
            0: There is no trigger at this \Rtselect.

            1: The trigger is a legacy SiFive address match trigger. These
            should not be implemented and aren't further documented here.

            2: The trigger is an address/data match trigger. The remaining bits
            in this register act as described in \Rmcontrol.

            3: The trigger is an instruction count trigger. The remaining bits
            in this register act as described in \Ricount.

            4: The trigger is an interrupt trigger. The remaining bits
            in this register act as described in \Ritrigger.

            5: The trigger is an exception trigger. The remaining bits
            in this register act as described in \Retrigger.

            15: This trigger exists (so enumeration shouldn't terminate), but
            is not currently available.

            Other values are reserved for future use.
        </field>
        <field name="dmode" bits="MXLEN-5" access="R/W" reset="0">
            0: Both Debug and M Mode can write the {\tt tdata} registers at the
            selected \Rtselect.

            1: Only Debug Mode can write the {\tt tdata} registers at the
            selected \Rtselect.  Writes from other modes are ignored.

            This bit is only writable from Debug Mode.
        </field>
        <field name="data" bits="MXLEN-6:0" access="R/W" reset="Preset">
            Trigger-specific data.
        </field>
    </register>

    <register name="Trigger Data 2" short="tdata2" address="0x7a2">
        Trigger-specific data.
        <field name="data" bits="MXLEN-1:0" access="R/W" reset="Preset" />
    </register>

    <register name="Trigger Data 3" short="tdata3" address="0x7a3">
        Trigger-specific data.
        <field name="data" bits="MXLEN-1:0" access="R/W" reset="Preset" />
    </register>

    <register name="Trigger Info" short="tinfo" address="0x7a4">
        <field name="0" bits="XLEN-1:16" access="R" reset="0" />
        <field name="info" bits="15:0" access="R" reset="Preset">
            One bit for each possible \Ftype enumerated in \Rtdataone. Bit N
            corresponds to type N. If the bit is set, then that type is
            supported by the currently selected trigger.

            If the currently selected trigger doesn't exist, this field
            contains 1.

            If \Ftype is not writable, this register may be unimplemented, in
            which case reading it causes an illegal instruction exception. In
            this case the debugger can read the only supported type from
            \Rtdataone.
        </field>
    </register>

    <register name="Match Control" short="mcontrol" address="0x7a1">
        This register is accessible as \Rtdataone when \Ftype is 2.

        Address and data trigger implementation are heavily dependent on how
        the processor core is implemented. To accommodate various
        implementations, execute, load, and store address/data triggers may fire at
        whatever point in time is most convenient for the implementation.
        The debugger may request specific timings as described in \Ftiming.
        Table~\ref{tab:hwbp_timing} suggests timings for the best user experience.

        \begin{table}[H]
        \centering
        \caption{Suggested Breakpoint Timings}
        \label{tab:hwbp_timing}
        \begin{tabular}{|r|l|}
        \hline
        Match Type                  &amp; Suggested Trigger Timing \\
        \hline
        Execute Address             &amp; Before \\
        Execute Instruction         &amp; Before \\
        Execute Address+Instruction &amp; Before \\
        Load Address                &amp; Before \\
        Load Data                   &amp; After \\
        Load Address+Data           &amp; After \\
        Store Address               &amp; Before \\
        Store Data                  &amp; Before \\
        Store Address+Data          &amp; Before \\
        \hline
        \end{tabular}
        \end{table}

        This trigger type may be limited to address comparisons (\Fselect is
        always 0) only. If that is the case, then \Rtdatatwo must be able to
        hold all valid virtual addresses but it need not be capable of holding
        other values.

        <field name="type" bits="MXLEN-1:MXLEN-4" access="R" reset="2" />
        <field name="dmode" bits="MXLEN-5" access="R/W" reset="0" />
        <field name="maskmax" bits="MXLEN-6:MXLEN-11" access="R" reset="Preset">
            Specifies the largest naturally aligned powers-of-two (NAPOT) range
            supported by the hardware when \Fmatch is 1. The value is the
            logarithm base 2 of the
            number of bytes in that range.  A value of 0 indicates that only
            exact value matches are supported (one byte range). A value of 63
            corresponds to the maximum NAPOT range, which is $2^{63}$ bytes in
            size.
        </field>
        <field name="0" bits="MXLEN-12:23" access="R" reset="0" />
        <field name="sizehi" bits="22:21" access="R/W" reset="0">
            This field only exists if MXLEN is greater than 32. In that case it
            extends \Fsize. If it does not exist then hardware operates as if
            the field contains 0.
        </field>
        <field name="hit" bits="20" access="R/W" reset="0">
            If this optional bit is implemented, the hardware sets it when this
            trigger matches. The trigger's user can set or clear it at any
            time. The trigger's user can use this bit to determine which
            trigger(s) matched.  If the bit is not implemented, it is always 0
            and writing it has no effect.
        </field>
        <field name="select" bits="19" access="R/W" reset="0">
            0: Perform a match on the virtual address.

            1: Perform a match on the data value loaded/stored, or the
            instruction executed.
        </field>
        <field name="timing" bits="18" access="R/W" reset="0">
            0: The action for this trigger will be taken just before the
            instruction that triggered it is executed, but after all preceding
            instructions are are committed.

            1: The action for this trigger will be taken after the instruction
            that triggered it is executed. It should be taken before the next
            instruction is executed, but it is better to implement triggers and
            not implement that suggestion than to not implement them at all.

            Most hardware will only implement one timing or the other, possibly
            dependent on \Fselect, \Fexecute, \Fload, and \Fstore. This bit
            primarily exists for the hardware to communicate to the debugger
            what will happen. Hardware may implement the bit fully writable, in
            which case the debugger has a little more control.

            Data load triggers with \Ftiming of 0 will result in the same load
            happening again when the debugger lets the hart run. For data load
            triggers, debuggers must first attempt to set the breakpoint with
            \Ftiming of 1.

            A chain of triggers that don't all have the same \Ftiming value
            will never fire (unless consecutive instructions match the
            appropriate triggers).
        </field>
        <field name="sizelo" bits="17:16" access="R/W" reset="0">
            This field contains the 2 low bits of \Fsize. The high bits come
            from \Fsizehi. The combined value is interpreted as follows:

            0: The trigger will attempt to match against an access of any size.
            The behavior is only well-defined if the select=0, or if the access
            size is MXLEN.

            1: The trigger will only match against 8-bit memory accesses.

            2: The trigger will only match against 16-bit memory accesses or
            execution of 16-bit instructions.

            3: The trigger will only match against 32-bit memory accesses or
            execution of 32-bit instructions.

            4: The trigger will only match against execution of 48-bit instructions.

            5: The trigger will only match against 64-bit memory accesses or
            execution of 64-bit instructions.

            6: The trigger will only match against execution of 80-bit instructions.

            7: The trigger will only match against execution of 96-bit instructions.

            8: The trigger will only match against execution of 112-bit instructions.

            9: The trigger will only match against 128-bit memory accesses or
            execution of 128-bit instructions.
        </field>
        <field name="action" bits="15:12" access="R/W" reset="0">
            The action to take when the trigger fires. The values are explained
            in Table~\ref{tab:action}.
        </field>
        <field name="chain" bits="11" access="R/W" reset="0">
            0: When this trigger matches, the configured action is taken.

            1: While this trigger does not match, it prevents the trigger with
            the next index from matching.

            A trigger chain starts on the first trigger with $|chain|=1$ after
            a trigger with $|chain|=0$, or simply on the first trigger if that
            has $|chain|=1$. It ends on the first trigger after that that has
            $|chain|=0$. This final trigger is part of the chain. The action on
            that final trigger will be taken if and only if all the triggers in
            the chain match at the same time.

            Because \Fchain affects the next trigger, hardware must zero it in
            writes to \Rmcontrol that set \Fdmode to 0 if the next trigger has
            \Fdmode of 1.
            In addition hardware should ignore writes to \Rmcontrol that set
            \Fdmode to 1 if the previous trigger has both \Fdmode of 0 and
            \Fchain of 1. Debuggers must avoid the latter case by checking
            \Fchain on the previous trigger if they're writing \Rmcontrol.

            Implementations that wish to limit the maximum length of a trigger
            chain (eg. to meet timing requirements) may do so by zeroing
            \Fchain in writes to \Rmcontrol that would make the chain too long.
        </field>
        <field name="match" bits="10:7" access="R/W" reset="0">
            0: Matches when the value equals \Rtdatatwo.

            1: Matches when the top M bits of the value match the top M bits of
            \Rtdatatwo. M is MXLEN-1 minus the index of the least-significant
            bit containing 0 in \Rtdatatwo.

            2: Matches when the value is greater than (unsigned) or equal to
            \Rtdatatwo.

            3: Matches when the value is less than (unsigned) \Rtdatatwo.

            4: Matches when the lower half of the value equals the lower half
            of \Rtdatatwo after the lower half of the value is ANDed with the
            upper half of \Rtdatatwo.

            5: Matches when the upper half of the value equals the lower half
            of \Rtdatatwo after the upper half of the value is ANDed with the
            upper half of \Rtdatatwo.

            Other values are reserved for future use.
        </field>
        <field name="m" bits="6" access="R/W" reset="0">
            When set, enable this trigger in M mode.
        </field>
        <field name="0" bits="5" access="R" reset="0" />
        <field name="s" bits="4" access="R/W" reset="0">
            When set, enable this trigger in S mode.
        </field>
        <field name="u" bits="3" access="R/W" reset="0">
            When set, enable this trigger in U mode.
        </field>
        <field name="execute" bits="2" access="R/W" reset="0">
            When set, the trigger fires on the virtual address or opcode of an
            instruction that is executed.
        </field>
        <field name="store" bits="1" access="R/W" reset="0">
            When set, the trigger fires on the virtual address or data of a store.
        </field>
        <field name="load" bits="0" access="R/W" reset="0">
            When set, the trigger fires on the virtual address or data of a load.
        </field>
    </register>

    <register name="Instruction Count" short="icount" address="0x7a1">
        This register is accessible as \Rtdataone when \Ftype is 3.

        \begin{commentary} This trigger type is intended to be used as a single
        step that's useful both for external debuggers and for software monitor
        programs. For that case it is not necessary to support \Fcount greater
        than
        1. The only two combinations of the mode bits that are useful in those
        scenarios are \Fu by itself, or \Fm, \Fs, and \Fu all set.

        If the hardware limits \Fcount to 1, and changes mode bits instead of
        decrementing \Fcount, this register can be implemented with just 2
        bits. One for \Fu, and one for \Fm and \Fs tied together.  If
        only the external debugger or only a software monitor needs to be
        supported, a single bit is enough.
        \end{commentary}

        <field name="type" bits="MXLEN-1:MXLEN-4" access="R" reset="3" />
        <field name="dmode" bits="MXLEN-5" access="R/W" reset="0" />
        <field name="0" bits="MXLEN-6:25" access="R" reset="0" />

        <field name="hit" bits="24" access="R/W" reset="0">
            If this optional bit is implemented, the hardware sets it when this
            trigger matches. The trigger's user can set or clear it at any
            time. The trigger's user can use this bit to determine which
            trigger(s) matched.  If the bit is not implemented, it is always 0
            and writing it has no effect.
        </field>
        <field name="count" bits="23:10" access="R/W" reset="1">
            When count is decremented to 0, the trigger fires. Instead of
            changing \Fcount from 1 to 0, it is also acceptable for hardware to
            clear \Fm, \Fs, and \Fu. This allows \Fcount to be hard-wired
            to 1 if this register just exists for single step.
        </field>

        <field name="m" bits="9" access="R/W" reset="0">
            When set, every instruction completed or exception taken in M mode decrements \Fcount
            by 1.
        </field>
        <field name="0" bits="8" access="R" reset="0" />
        <field name="s" bits="7" access="R/W" reset="0">
            When set, every instruction completed or exception taken in S mode decrements \Fcount
            by 1.
        </field>
        <field name="u" bits="6" access="R/W" reset="0">
            When set, every instruction completed or exception taken in U mode decrements \Fcount
            by 1.
        </field>

        <field name="action" bits="5:0" access="R/W" reset="0">
            The action to take when the trigger fires. The values are explained
            in Table~\ref{tab:action}.
        </field>
    </register>

    <register name="Interrupt Trigger" short="itrigger" address="0x7a1">
        This register is accessible as \Rtdataone when \Ftype is 4.

        This trigger may fire on any of the interrupts configurable in \Rmie
        (described in the Privileged Spec). The interrupts to fire on are
        configured by setting the same bit in \Rtdatatwo as would be set in
        \Rmie to enable the interrupt.

        Hardware may only support a subset of interrupts for this trigger.  A
        debugger must read back \Rtdatatwo after writing it to confirm the
        requested functionality is actually supported.

        The trigger only fires if the hart takes a trap because of the
        interrupt. (Eg. it does not fire when a timer interrupt occurs but that
        interrupt is not enabled in \Rmie.)

        When the trigger fires, all CSRs are updated as defined by the
        Privileged Spec, and the requested action is taken just before the
        first instruction of the interrupt/exception handler is executed.

        <field name="type" bits="MXLEN-1:MXLEN-4" access="R" reset="4" />
        <field name="dmode" bits="MXLEN-5" access="R/W" reset="0" />
        <field name="hit" bits="MXLEN-6" access="R/W" reset="0">
            If this optional bit is implemented, the hardware sets it when this
            trigger matches. The trigger's user can set or clear it at any
            time. The trigger's user can use this bit to determine which
            trigger(s) matched.  If the bit is not implemented, it is always 0
            and writing it has no effect.
        </field>
        <field name="0" bits="MXLEN-7:10" access="R" reset="0" />
        <field name="m" bits="9" access="R/W" reset="0">
            When set, enable this trigger for interrupts that are taken from M
            mode.
        </field>
        <field name="0" bits="8" access="R" reset="0" />
        <field name="s" bits="7" access="R/W" reset="0">
            When set, enable this trigger for interrupts that are taken from S
            mode.
        </field>
        <field name="u" bits="6" access="R/W" reset="0">
            When set, enable this trigger for interrupts that are taken from U
            mode.
        </field>
        <field name="action" bits="5:0" access="R/W" reset="0">
            The action to take when the trigger fires. The values are explained
            in Table~\ref{tab:action}.
        </field>
    </register>

    <register name="Exception Trigger" short="etrigger" address="0x7a1">
        This register is accessible as \Rtdataone when \Ftype is 5.

        This trigger may fire on up to MXLEN of the Exception Codes defined in
        \Rmcause (described in the Privileged Spec, with Interrupt=0). Those
        causes are configured by writing the corresponding bit in \Rtdatatwo.
        (Eg. to trap on an illegal instruction, the debugger sets bit 2 in
        \Rtdatatwo.)

        Hardware may support only a subset of exceptions. A debugger must read
        back \Rtdatatwo after writing it to confirm the requested functionality
        is actually supported.

        When the trigger fires, all CSRs are updated as defined by the
        Privileged Spec, and the requested action is taken just before the
        first instruction of the interrupt/exception handler is executed.

        <field name="type" bits="MXLEN-1:MXLEN-4" access="R" reset="4" />
        <field name="dmode" bits="MXLEN-5" access="R/W" reset="0" />
        <field name="hit" bits="MXLEN-6" access="R/W" reset="0">
            If this optional bit is implemented, the hardware sets it when this
            trigger matches. The trigger's user can set or clear it at any
            time. The trigger's user can use this bit to determine which
            trigger(s) matched.  If the bit is not implemented, it is always 0
            and writing it has no effect.
        </field>
        <field name="0" bits="MXLEN-7:10" access="R" reset="0" />
        <field name="m" bits="9" access="R/W" reset="0">
            When set, enable this trigger for exceptions that are taken from M
            mode.
        </field>
        <field name="0" bits="8" access="R" reset="0" />
        <field name="s" bits="7" access="R/W" reset="0">
            When set, enable this trigger for exceptions that are taken from S
            mode.
        </field>
        <field name="u" bits="6" access="R/W" reset="0">
            When set, enable this trigger for exceptions that are taken from U
            mode.
        </field>
        <field name="action" bits="5:0" access="R/W" reset="0">
            The action to take when the trigger fires. The values are explained
            in Table~\ref{tab:action}.
        </field>
    </register>
</registers>
