forked from riscv/riscv-debug-spec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathtrigger.tex
203 lines (175 loc) · 9.42 KB
/
trigger.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
\chapter{Trigger Module (TM)}
\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 piece that can be implemented separately.
A hart can be compliant with this specification without implementing any
trigger functionality at all, but if it is implemented then it must conform to
this section. If triggers aren't implemented, the CSRs might not exist at all and
accessing them results in an illegal instruction exception.
Triggers do not fire while in Debug Mode.
\section{Enumeration}
\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 \RcsrTselect. If this results in an illegal instruction
exception, then there are no triggers implemented.
\item Read back \RcsrTselect and check that it contains the written value. If not,
exit the loop.
\item Read \RcsrTinfo.
\item If that caused an exception, the debugger must read \RcsrTdataOne to
discover the type. (If \FcsrTdataOneType is 0, this trigger doesn't exist. Exit the
loop.)
\item If \FcsrTinfoInfo is 1, this trigger doesn't exist. Exit the loop.
\item Otherwise, the selected trigger supports the types discovered in \FcsrTinfoInfo.
\item Repeat, incrementing the value in \RcsrTselect.
\end{steps}
\begin{commentary}
The above algorithm reads back \RcsrTselect so that implementations which have
$2^n$ triggers only need to implement $n$ bits of \RcsrTselect.
The algorithm checks \RcsrTinfo and \FcsrTdataOneType in case the implementation has $m$
bits of \RcsrTselect but fewer than $2^m$ triggers.
\end{commentary}
\section{Actions}
Triggers can be configured to take one of several actions when they fire.
Table~\ref{tab:action} lists all options.
\begin{table}[H]
\centering
\caption{\FcsrMcontrolAction encoding}
\label{tab:action}
\begin{tabular}{|r|L|}
\hline
Value & Description \\
\hline
0 & Raise a breakpoint exception into M-Mode. (Used when software wants to
use the trigger module without an external debugger attached.)
\Rmepc must contain the virtual address of the next instruction that must
be executed to preserve the program flow. \\
\hline
1 & Enter Debug Mode.
\RcsrDpc must contain the virtual address of the next instruction that must
be executed to preserve the program flow.
This action is only legal when the trigger's \FcsrTdataOneDmode is 1.
Since the {\tt tdata} registers are WARL, hardware should clear the action
field whenever the action field is 1, \FcsrTdataOneDmode is cleared, and the
new value of the action field would also be 1. \\
\hline
2 -- 5 & Reserved for use by the trace specification. \\
\hline
8 -- 9 & Signal the firing of the trigger to other blocks within the hart (e.g. as countable events to hpmcounters). Use external debug trigger output 0 or 1 (respectively). \\
\hline
other & Reserved for future use. \\
\hline
\end{tabular}
\end{table}
\section{Priority}
Table~\ref{tab:priority} lists the synchronous exceptions from the Privileged
Spec, and where the various types of triggers fit in. The first 3 columns come
from the Privileged Spec, and the final column shows where triggers fit in.
Priorities in the table are separated by horizontal lines, so e.g. etrigger and
itrigger have the same priority.
If this table contradicts the table in the Privileged Spec, then the latter
takes precedence.
This table only applies if triggers are precise. Otherwise triggers
will fire some indeterminate time after the event, and the priority is
irrelevant.
When triggers are chained, the priority is the lowest priority of the triggers
in the chain.
\begin{table}[H]
\centering
\label{tab:priority}
\begin{tabular}{|l|r|l|l|}
\hline
Priority & Exception & Description & Trigger \\
& Code & & \\
\hline
{\em Highest} & 3 & & etrigger \\
& 3 & & icount \\
& 3 & & itrigger \\
& 3 & & mcontrol/mcontrol6 after \\
& & & \hspace{2em}(on previous instruction) \\
\hline
& 3 & Instruction address breakpoint & mcontrol/mcontrol6 execute address before \\ \hline
& 12 & Instruction page fault & \\ \hline
& 1 & Instruction access fault & \\ \hline
& 3 & & mcontrol/mcontrol6 execute data before \\ \hline
& 2 & Illegal instruction & \\
& 0 & Instruction address misaligned & \\
& 8, 9, 11 & Environment call & \\
& 3 & Environment break & \\
& 3 & Load/Store/AMO address breakpoint & mcontrol/mcontrol6 load/store address before \\
& 3 & & mcontrol/mcontrol6 store data before \\ \hline
& 6 & Store/AMO address misaligned & \\
& 4 & Load address misaligned & \\ \hline
& 15 & Store/AMO page fault & \\
& 13 & Load page fault & \\ \hline
& 7 & Store/AMO access fault & \\
& 5 & Load access fault & \\
{\em Lowest} & 3 & & mcontrol/mcontrol6 load data before \\
\hline
\end{tabular}
\caption{Synchronous exception priority in decreasing priority order.}
\end{table}
When multiple triggers in the same priority fire at once, \FcsrMcontrolHit (if
implemented) is set for all of them. If one of these triggers has
the ``enter Debug Mode'' action (1) and another
trigger has the ``raise a breakpoint exception'' action (0),
the preferred behavior is to have both actions take place. It is
implementation-dependent which of the two happens first. This ensures both
that the presence of an external debugger doesn't affect execution and that a
trigger set by user code doesn't affect the external debugger. If this is not
implemented, then the hart must enter Debug Mode and ignore the breakpoint
exception. In the latter case, \FcsrMcontrolHit of the trigger whose action is 0 must still
be set, giving a debugger an opportunity to handle this case. What happens with
trace actions when triggers with different actions are also firing is left to
the trace specification.
\section{Native M-Mode Triggers}
\label{sec:mmtrigger}
Triggers can be used for native debugging. On a fully featured hart, triggers
will be set using \FcsrMcontrolU or \FcsrMcontrolS, 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 might leave the hart unable to resume normal execution.
On full-featured harts this is a remote corner case that can probably be
ignored. On harts 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 \FcsrMcontrolMie 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 \FcsrTcontrolMte and \FcsrTcontrolMpte in \RcsrTcontrol. 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 hart 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.
Almost all 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 must not modify the contents of
other {\tt tdata} registers, nor the configuration of any trigger besides the
one that is currently selected.
The combination of these rules means that a debugger cannot simply set a
trigger by writing \RcsrTdataOne, then \RcsrTdataTwo, etc. The current value
of \RcsrTdataTwo might not be legal with the new value of \RcsrTdataOne. To
help with this situation, it is guaranteed that writing 0 to \RcsrTdataOne
disables the trigger, and leaves it in a state where \RcsrTdataTwo and
\RcsrTdataThree can be written with any value that makes sense for any
trigger type supported by this trigger.
\begin{steps}{As a result, a debugger can write any supported trigger as
follows:}
\item Write 0 to \RcsrTdataOne.
\item Write desired values to \RcsrTdataTwo and \RcsrTdataThree.
\item Write desired value to \RcsrTdataOne.
\end{steps}
\input{hwbp_registers.tex}