OpenCores
URL https://opencores.org/ocsvn/neorv32/neorv32/trunk

Subversion Repositories neorv32

[/] [neorv32/] [trunk/] [docs/] [datasheet/] [on_chip_debugger.adoc] - Blame information for rev 66

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 60 zero_gravi
<<<
2
:sectnums:
3
== On-Chip Debugger (OCD)
4
 
5
The NEORV32 Processor features an _on-chip debugger_ (OCD) implementing **execution-based debugging** that is compatible
6
to the **Minimal RISC-V Debug Specification Version 0.13.2**.
7
Please refer to this spec for in-deep information.
8
A copy of the specification is available in `docs/references/riscv-debug-release.pdf`.
9
The NEORV32 OCD provides the following key features:
10
 
11
* JTAG test access port
12
* run-control of the CPU: halting, single-stepping and resuming
13
* executing arbitrary programs during debugging
14
* accessing core registers (direct access to GPRs, indirect access to CSRs via program buffer)
15
* indirect access to the whole processor address space (via program buffer))
16
* compatible to the https://github.com/riscv/riscv-openocd[RISC-V port of OpenOCD];
17
  pre-built binaries can be obtained for example from https://www.sifive.com/software[SiFive]
18
 
19 61 zero_gravi
.OCD Security Note
20
[IMPORTANT]
21
Access via the OCD is _always authenticated_ (`dmstatus.authenticated` == `1`). Hence, the
22 65 zero_gravi
_whole system_ can always be accessed via the on-chip debugger. Currently, there is no option
23
to disable the OCD via software. The OCD can only be disabled by disabling implementation
24
(setting _ON_CHIP_DEBUGGER_EN_ generic to _false_).
25 61 zero_gravi
 
26 60 zero_gravi
[NOTE]
27
The OCD requires additional resources for implementation and _might_ also increase the critical path resulting in less
28
performance. If the OCD is not really required for the _final_ implementation, it can be disabled and thus,
29
discarded from implementation. In this case all circuitry of the debugger is completely removed (no impact
30
on area, energy or timing at all).
31
 
32
[TIP]
33
A simple example on how to use NEORV32 on-chip debugger in combination with `OpenOCD` and `gdb`
34 62 zero_gravi
is shown in section https://stnolting.github.io/neorv32/ug/#_debugging_using_the_on_chip_debugger[Debugging using the On-Chip Debugger]
35
of the User Guide.
36 60 zero_gravi
 
37
The NEORV32 on-chip debugger complex is based on three hardware modules:
38
 
39
.NEORV32 on-chip debugger complex
40
image::neorv32_ocd_complex.png[align=center]
41
 
42
[start=1]
43
. <<_debug_transport_module_dtm>> (`rtl/core/neorv32_debug_dtm.vhd`): External JTAG access tap to allow an external
44
  adapter to interface with the _debug module(DM)_ using the _debug module interface (dmi)_.
45
. <<_debug_module_dm>> (`rtl/core/neorv32_debug_tm.vhd`): Debugger control unit that is configured by the DTM via the
46
  the _dmi_. Form the CPU's "point of view" this module behaves as a memory-mapped "peripheral" that can be accessed
47
  via the processor-internal bus. The memory-mapped registers provide an internal _data buffer_ for data transfer
48
  from/to the DM, a _code ROM_ containing the "park loop" code,   a _program buffer_ to allow the debugger to
49
  execute small programs defined by the DM and a _status register_ that is used to communicate
50
  _halt_, _resume_ and _execute_ requests/acknowledges from/to the DM.
51
. CPU <<_cpu_debug_mode>> extension (part of`rtl/core/neorv32_cpu_control.vhd`):
52
  This extension provides the "debug execution mode" which executes the "park loop" code from the DM.
53
  The mode also provides additional CSRs.
54
 
55
**Theory of Operation**
56
 
57
When debugging the system using the OCD, the debugger issues a halt request to the CPU (via the CPU's
58
`db_halt_req_i` signal) to make the CPU enter _debug mode_. In this state, the application-defined architectural
59
state of the system/CPU is "frozen" so the debugger can monitor and even modify it.
60
While in debug mode, the CPU executes the "park loop" code from the _code ROM_ of the DM.
61
This park loop implements an endless loop, in which the CPU polls the memory-mapped _status register_ that is
62
controlled by the _debug module (DM)_. The flags of these register are used to communicate _requests_ from
63
the DM and to _acknowledge_ them by the CPU: trigger execution of the program buffer or resume the halted
64
application.
65
 
66
 
67
 
68
<<<
69
// ####################################################################################################################
70
:sectnums:
71
=== Debug Transport Module (DTM)
72
 
73
The debug transport module (VHDL module: `rtl/core/neorv32_debug_dtm.vhd`) provides a JTAG test access port (TAP).
74
The DTM is the first entity in the debug system, which connects and external debugger via JTAG to the next debugging
75
entity: the debug module (DM).
76 61 zero_gravi
External JTAG access is provided by the following top-level ports.
77 60 zero_gravi
 
78
.JTAG top level signals
79
[cols="^2,^2,^2,<8"]
80
[options="header",grid="rows"]
81
|=======================
82
| Name          | Width | Direction | Description
83
| `jtag_trst_i` | 1     | in        | TAP reset (low-active); this signal is optional, make sure to pull it _high_ if it is not used
84
| `jtag_tck_i`  | 1     | in        | serial clock
85
| `jtag_tdi_i`  | 1     | in        | serial data input
86
| `jtag_tdo_o`  | 1     | out       | serial data output
87
| `jtag_tms_i`  | 1     | in        | mode select
88
|=======================
89
 
90
.JTAG Clock
91
[IMPORTANT]
92
The actual JTAG clock signal is **not** used as primary clock. Instead it is used to synchronize
93
JTGA accesses, while all internal operations trigger on the system clock. Hence, no additional clock domain is required
94
for integration of this module.
95
However, this constraints the maximal JTAG clock (`jtag_tck_i`) frequency to be less than or equal to
96
1/4 of the system clock (`clk_i`) frequency.
97
 
98
[NOTE]
99
If the on-chip debugger is disabled (_ON_CHIP_DEBUGGER_EN_ = false) the JTAG serial input `jtag_tdi_i` is directly
100
connected to the JTAG serial output `jtag_tdo_o` to maintain the JTAG chain.
101
 
102
[WARNING]
103
The NEORV32 JTAG TAP does not provide a _boundary check_ function (yet?). Hence, physical device pins cannot be accessed.
104
 
105
The DTM uses the "debug module interface (dmi)" to access the actual debug module (DM).
106
These accesses are controlled by TAP-internal registers.
107
Each registers is selected by the JTAG instruction register (`IR`) and accessed through the JTAG data register (`DR`).
108
 
109
[NOTE]
110
The DTM's instruction and data registers can be accessed using OpenOCDs `irscan` and `drscan` commands.
111
The RISC-V port of OpenOCD also provides low-level command (`riscv dmi_read` & `riscv dmi_write`) to access the _dmi_
112
debug module interface.
113
 
114
JTAG access is conducted via the *instruction register* `IR`, which is 5 bit wide, and several *data registers* `DR`
115
with different sizes.
116
The data registers are accessed by writing the according address to the instruction register.
117
The following table shows the available data registers:
118
 
119
.JTAG TAP registers
120
[cols="^2,^2,^2,<8"]
121
[options="header",grid="rows"]
122
|=======================
123
| Address (via `IR`) | Name     | Size [bits] | Description
124
| `00001`            | `IDCODE` | 32          | identifier, default: `0x0CAFE001` (configurable via package's `jtag_tap_idcode_*` constants)
125
| `10000`            | `DTMCS`  | 32          | debug transport module control and status register
126
| `10001`            | `DMI`    | 41          | debug module interface (_dmi_); 7-bit address, 32-bit read/write data, 2-bit operation (`00` = NOP; `10` = write; `01` = read)
127
| others             | `BYPASS` | 1           | default JTAG bypass register
128
|=======================
129
 
130
[INFO]
131
See the https://github.com/riscv/riscv-debug-spec[RISC-V debug specification] for more information regarding the data
132
registers and operations.
133
A local copy can be found in `docs/references`.
134
 
135
 
136
 
137
<<<
138
// ####################################################################################################################
139
:sectnums:
140
=== Debug Module (DM)
141
 
142
According to the RISC-V debug specification, the DM (VHDL module: `rtl/core/neorv32_debug_dm.vhd`)
143
acts as a translation interface between abstract operations issued by the debugger and the platform-specific
144
debugger implementation. It supports the following features (excerpt from the debug spec):
145
 
146
* Gives the debugger necessary information about the implementation.
147
* Allows the hart to be halted and resumed and provides status of the current state.
148
* Provides abstract read and write access to the halted hart's GPRs.
149
* Provides access to a reset signal that allows debugging from the very first instruction after reset.
150
* Provides a mechanism to allow debugging the hart immediately out of reset. (_still experimental_)
151
* Provides a Program Buffer to force the hart to execute arbitrary instructions.
152
* Allows memory access from a hart's point of view.
153
 
154
The NEORV32 DM follows the "Minimal RISC-V External Debug Specification" to provide full debugging
155
capabilities while keeping resource (area) requirements at a minimum level.
156
It implements the **execution based debugging scheme** for a single hart and provides the following
157
hardware features:
158
 
159
* program buffer with 2 entries and implicit `ebreak` instruction afterwards
160
* no _direct_ bus access (indirect bus access via the CPU)
161
* abstract commands: "access register" plus auto-execution
162
* no _dedicated_ halt-on-reset capabilities yet (but can be emulated)
163
 
164
The DM provides two "sides of access": access from the DTM via the _debug module interface (dmi)_ and access from the
165
CPU via the processor-internal bus. From the DTM's point of view, the DM implements a set of <<_dm_registers>> that
166
are used to control and monitor the actual debugging. From the CPU's point of view, the DM implements several
167
memory-mapped registers (within the _normal_ address space) that are used for communicating debugging control
168
and status (<<_dm_cpu_access>>).
169
 
170
 
171
:sectnums:
172
==== DM Registers
173
 
174
The DM is controlled via a set of registers that are accessed via the DTM's _dmi_.
175
The "Minimal RISC-V Debug Specification" requires only a subset of the registers specified in the spec.
176
The following registers are implemented.
177
Write accesses to any other registers are ignored and read accesses will always return zero.
178
Register names that are encapsulated in "( )" are not actually implemented; however, they are listed to explicitly show
179
their functionality.
180
 
181
.Available DM registers
182
[cols="^2,^3,<7"]
183
[options="header",grid="rows"]
184
|=======================
185
| Address | Name           | Description
186
|  `0x04` | `data0`        | Abstract data 0, used for data transfer between debugger and processor
187
|  `0x10` | `dmcontrol`    | Debug module control
188
|  `0x11` | `dmstatus`     | Debug module status
189
|  `0x12` | `hartinfo`     | Hart information
190
|  `0x16` | `abstracts`    | Abstract control and status
191
|  `0x17` | `command`      | Abstract command
192
|  `0x18` | `abstractauto` | Abstract command auto-execution
193
|  `0x1d` | (`nextdm`)     | Base address of _next_ DM; read as zero to indicate there is only _one_ DM
194
|  `0x20` | `progbuf0`     | Program buffer 0
195
|  `0x21` | `progbuf1`     | Program buffer 1
196
|  `0x38` | (`sbcs`)       | System bus access control and status; read as zero to indicate there is no _direct_ system bus access
197
|  `0x40` | `haltsum0`     | Halt summary 0
198
|=======================
199
 
200
 
201
:sectnums!:
202
===== **`data`**
203
 
204
[cols="4,27,>7"]
205
[frame="topbot",grid="none"]
206
|======
207
| 0x04 | **Abstract data 0** | `data0`
208
3+| Reset value: _UNDEFINED_
209
3+| Basic read/write registers to be used with abstract command (for example to read/write data from/to CPU GPRs).
210
|======
211
 
212
 
213
:sectnums!:
214
===== **`dmcontrol`**
215
 
216
[cols="4,27,>7"]
217
[frame="topbot",grid="none"]
218
|======
219
| 0x10 | **Debug module control register** | `dmcontrol`
220
3+| Reset value: 0x00000000
221
3+| Control of the overall debug module and the hart. The following table shows all implemented bits. All remaining bits/bit-fields are configures as "zero" and are
222
read-only. Writing '1' to these bits/fields will be ignored.
223
|======
224
 
225
.`dmcontrol` - debug module control register bits
226
[cols="^1,^2,^1,<8"]
227
[options="header",grid="rows"]
228
|=======================
229
| Bit | Name [RISC-V]  | R/W | Description
230
| 31  | `haltreq`      | -/w | set/clear hart halt request
231
| 30  | `resumereq`    | -/w | request hart to resume
232
| 28  | `ackhavereset` | -/w | write `1` to clear `*havereset` flags
233
|  1  | `ndmreset`     | r/w | put whole processor into reset when `1`
234
|  0  | `dmactive`     | r/w | DM enable; writing `0`-`1` will reset the DM
235
|=======================
236
 
237
 
238
:sectnums!:
239
===== **`dmstatus`**
240
 
241
[cols="4,27,>7"]
242
[frame="topbot",grid="none"]
243
|======
244
| 0x11 | **Debug module status register** | `dmstatus`
245
3+| Reset value: 0x00000000
246
3+| Current status of the overall debug module and the hart. The entire register is read-only.
247
|======
248
 
249
.`dmstatus` - debug module status register bits
250
[cols="^1,^2,<10"]
251
[options="header",grid="rows"]
252
|=======================
253
| Bit   | Name [RISC-V]     | Description
254
| 31:23 | _reserved_        | reserved; always zero
255
| 22    | `impebreak`       | always `1`; indicates an implicit `ebreak` instruction after the last program buffer entry
256
| 21:20 | _reserved_        | reserved; always zero
257
| 19    | `allhavereset`    .2+| `1` when the hart is in reset
258
| 18    | `anyhavereset`
259
| 17    | `allresumeack`    .2+| `1` when the hart has acknowledged a resume request
260
| 16    | `anyresumeack`
261
| 15    | `allnonexistent`  .2+| always zero to indicate the hart is always existent
262
| 14    | `anynonexistent`
263
| 13    | `allunavail`      .2+| `1` when the DM is disabled to indicate the hart is unavailable
264
| 12    | `anyunavail`
265
| 11    | `allrunning`      .2+| `1` when the hart is running
266
| 10    | `anyrunning`
267
|  9    | `allhalted`       .2+| `1` when the hart is halted
268
|  8    | `anyhalted`
269
|  7    | `authenticated`   | always `1`; there is no authentication
270
|  6    | `authbusy`        | always `0`; there is no authentication
271
|  5    | `hasresethaltreq` | always `0`; halt-on-reset is not supported (directly)
272
|  4    | `confstrptrvalid` | always `0`; no configuration string available
273
| 3:0   | `version`         | `0010` - DM is compatible to version 0.13
274
|=======================
275
 
276
 
277
:sectnums!:
278
===== **`hartinfo`**
279
 
280
[cols="4,27,>7"]
281
[frame="topbot",grid="none"]
282
|======
283
| 0x12 | **Hart information** | `hartinfo`
284
3+| Reset value: see below
285
3+| This register gives information about the hart. The entire register is read-only.
286
|======
287
 
288
.`hartinfo` - hart information register bits
289
[cols="^1,^2,<8"]
290
[options="header",grid="rows"]
291
|=======================
292
| Bit   | Name [RISC-V] | Description
293
| 31:24 | _reserved_    | reserved; always zero
294
| 23:20 | `nscratch`    | `0001`, number of `dscratch*` CPU registers = 1
295
| 19:17 | _reserved_    | reserved; always zero
296
| 16    | `dataccess`   | `0`, the `data` registers are shadowed in the hart's address space
297
| 15:12 | `datasize`    | `0001`, number of 32-bit words in the address space dedicated to shadowing the `data` registers = 1
298
| 11:0  | `dataaddr`    | = `dm_data_base_c(11:0)`, signed base address of `data` words (see address map in <<_dm_cpu_access>>)
299
|=======================
300
 
301
 
302
:sectnums!:
303
===== **`abstracts`**
304
 
305
[cols="4,27,>7"]
306
[frame="topbot",grid="none"]
307
|======
308
| 0x16 | **Abstract control and status** | `abstracts`
309
3+| Reset value: see below
310
3+| Command execution info and status.
311
|======
312
 
313
.`abstracts` - abstract control and status register bits
314
[cols="^1,^2,^1,<8"]
315
[options="header",grid="rows"]
316
|=======================
317
| Bit   | Name [RISC-V] | R/W | Description
318
| 31:29 | _reserved_    | r/- | reserved; always zero
319
| 28:24 | `progbufsize` | r/- | `0010`; size of the program buffer (`progbuf`) = 2 entries
320
| 23:11 | _reserved_    | r/- | reserved; always zero
321
| 12    | `busy`        | r/- | `1` when a command is being executed
322
| 11    | _reserved_    | r/- | reserved; always zero
323
| 10:8  | `cmerr`       | r/w | error during command execution (see below); has to be cleared by writing `111`
324
| 7:4   | _reserved_    | r/- | reserved; always zero
325
| 3:0   | `datacount`   | r/- | `0001`; number of implemented `data` registers for abstract commands = 1
326
|=======================
327
 
328
Error codes in `cmderr` (highest priority first):
329
 
330
* `000` - no error
331
* `100` - command cannot be executed since hart is not in expected state
332
* `011` - exception during command execution
333
* `010` - unsupported command
334
* `001` - invalid DM register read/write while command is/was executing
335
 
336
 
337
:sectnums!:
338
===== **`command`**
339
 
340
[cols="4,27,>7"]
341
[frame="topbot",grid="none"]
342
|======
343
| 0x17 | **Abstract command** | `command`
344
3+| Reset value: 0x00000000
345
3+| Writing this register will trigger the execution of an abstract command. New command can only be executed if
346
`cmderr` is zero. The entire register in write-only (reads will return zero).
347
|======
348
 
349
[NOTE]
350
The NEORV32 DM only supports **Access Register** abstract commands. These commands can only access the
351
hart's GPRs (abstract command register index `0x1000` - `0x101f`).
352
 
353
.`command` - abstract command register - "access register" commands only
354
[cols="^1,^2,<8"]
355
[options="header",grid="rows"]
356
|=======================
357 65 zero_gravi
| Bit   | Name [RISC-V]      | R/W | Description / required value
358
| 31:24 | `cmdtype`          | -/w | `00000000` to indicate "access register" command
359
| 23    | _reserved_         | -/w | reserved, has to be `0` when writing
360
| 22:20 | `aarsize`          | -/w | `010` to indicate 32-bit accesses
361 66 zero_gravi
| 21    | `aarpostincrement` | -/w | `0`, post-increment is not supported
362 65 zero_gravi
| 18    | `postexec`         | -/w | if set the program buffer is executed _after_ the command
363
| 17    | `transfer`         | -/w | if set the operation in `write` is conducted
364
| 16    | `write`            | -/w | `1`: copy `data0` to `[regno]`; `0` copy `[regno]` to `data0`
365
| 15:0  | `regno`            | -/w | GPR-access only; has to be `0x1000` - `0x101f`
366 60 zero_gravi
|=======================
367
 
368
 
369
:sectnums!:
370
===== **`abstractauto`**
371
 
372
[cols="4,27,>7"]
373
[frame="topbot",grid="none"]
374
|======
375
| 0x18 | **Abstract command auto-execution** | `abstractauto`
376
3+| Reset value: 0x00000000s
377
3+| Register to configure when a read/write access to a DM repeats execution of the last abstract command.
378
|======
379
 
380
.`abstractauto` - Abstract command auto-execution register bits
381
[cols="^1,^2,^1,<8"]
382
[options="header",grid="rows"]
383
|=======================
384
| Bit   | Name [RISC-V]        | R/W | Description
385
| 17    | `autoexecprogbuf[1]` | r/w | when set reading/writing from/to `progbuf1` will execute `command again`
386
| 16    | `autoexecprogbuf[0]` | r/w | when set reading/writing from/to `progbuf0` will execute `command again`
387
|  0    | `autoexecdata[0]`    | r/w | when set reading/writing from/to `data0` will execute `command again`
388
|=======================
389
 
390
 
391
:sectnums!:
392
===== **`progbuf`**
393
 
394
[cols="4,27,>7"]
395
[frame="topbot",grid="none"]
396
|======
397
| 0x20 | **Program buffer 0** | `progbuf0`
398
| 0x21 | **Program buffer 1** | `progbuf1`
399
3+| Reset value: `NOP`-instruction
400
3+| General purpose program buffer for the DM.
401
|======
402
 
403
 
404
:sectnums!:
405
===== **`haltsum0`**
406
 
407
[cols="4,27,>7"]
408
[frame="topbot",grid="none"]
409
|======
410
| 0x40 | **Halt summary 0** | `haltsum0`
411
3+| Reset value: _UNDEFINED_
412
3+| Bit 0 of this register is set if the hart is halted (all remaining bits are always zero). The entire register is read-only.
413
|======
414
 
415
:sectnums:
416
==== DM CPU Access
417
 
418
From the CPU's point of view, the DM behaves as a memory-mapped peripheral that includes
419
 
420
* a small ROM that contains the code for the "park loop", which is executed when the CPU is _in_ debug mode.
421
* a program buffer populated by the debugger host to execute small programs
422
* a data buffer to transfer data between the processor and the debugger host
423
* a status register to communicate debugging requests
424
 
425
.Park Loop Code Sources
426
[NOTE]
427
The assembly sources of the **park loop code** are available in `sw/ocd-firmware/park_loop.S`. Please note, that these
428
sources are not intended to be changed by the used. Hence, the makefile does not provide an automatic option
429
to compile and "install" the debugger ROM code into the HDL sources and require a manual copy
430
(see `sw/ocd-firmware/README.md`).
431
 
432
The DM uses a total address space of 128 words of the CPU's address space (= 512 bytes) divided into four sections
433
of 32 words (= 128 bytes) each.
434
Please note, that the program buffer, the data buffer and the status register only uses a few effective words in this
435
address space. However, these effective addresses are mirrored to fill up the whole 128 bytes of the section.
436
Hence, any CPU access within this address space will succeed.
437
 
438
.DM CPU access - address map (divided into four sections)
439
[cols="^2,^4,^2,<7"]
440
[options="header",grid="rows"]
441
|=======================
442
| Base address | Name [VHDL package]              | Actual size | Description
443
| `0xfffff800` | `dm_code_base_c` (= `dm_base_c`) |   128 bytes | Code ROM for the "park loop" code
444
| `0xfffff880` | `dm_pbuf_base_c`                 |    16 bytes | Program buffer, provided by DM
445
| `0xfffff900` | `dm_data_base_c`                 |     4 bytes | Data buffer (`dm.data0`)
446
| `0xfffff980` | `dm_sreg_base_c`                 |     4 bytes | Control and status register
447
|=======================
448
 
449
[NOTE]
450
From the CPU's point of view, the DM is mapped to an _"unused"_ address range within the processor's
451
<<_address_space>> right between the bootloader ROM (BOOTROM) and the actual processor-internal IO
452
space at addresses `0xfffff800` - `0xfffff9ff`
453
 
454
When the CPU enters or re-enters (for example via `ebreak` in the DM's program buffer) debug mode, it jumps to
455
the beginning of the DM's "park loop" code ROM at `dm_code_base_c`. This is the _normal entry point_ for the
456
park loop code. If an exception is encountered during debug mode, the CPU jumps to `dm_code_base_c + 4`,
457
which is the _exception entry point_.
458
 
459
**Status Register**
460
 
461
The status register provides a direct communication channel between the CPU executing the park loop and the
462
host-controlled controller of the DM. Note that all bits that can be written by the CPU (acknowledge flags)
463
cause a single-shot (1-cycle) signal to the DM controller and auto-clear (always read as zero).
464
The bits that are driven by the DM controller and are read-only to the CPU and keep their state until the CPU
465
acknowledges the according request.
466
 
467
.DM CPU access - status register
468
[cols="^2,^2,^2,<8"]
469
[options="header",grid="rows"]
470
|=======================
471
| Bit | Name            | CPU access | Description
472
| 0   | `halt_ack`      | -/w        | Set by the CPU to indicate that the CPU is halted and keeps iterating in the park loop
473
| 1   | `resume_req`    | r/-        | Set by the DM to tell the CPU to resume normal operation (leave parking loop and leave debug mode via `dret` instruction)
474
| 2   | `resume_ack`    | -/w        | Set by the CPU to acknowledge that the CPU is now going to leave parking loop & debug mode
475
| 3   | `execute_req`   | r/-        | Set by the DM to tell the CPU to leave debug mode and execute the instructions from the program buffer; CPU will re-enter parking loop afterwards
476
| 4   | `execute_ack`   | -/w        | Set by the CPU to acknowledge that the CPU is now going to execute the program buffer
477
| 5   | `exception_ack` | -/w        | Set by the CPU to inform the DM that an exception occurred during execution of the park loop or during execution of the program buffer
478
|=======================
479
 
480
 
481
 
482
<<<
483
// ####################################################################################################################
484
:sectnums:
485
=== CPU Debug Mode
486
 
487
The NEORV32 CPU Debug Mode `DB` (part of `rtl/core/neorv32_cpu_control.vhd`) is compatible to the "Minimal RISC-V Debug Specification 0.13.2".
488
It is enabled/implemented by setting the CPU generic _CPU_EXTENSION_RISCV_DEBUG_ to "true" (done by setting processor
489
generic _ON_CHIP_DEBUGGER_EN_).
490
It provides a new operation mode called "debug mode".
491
When enabled, three additional CSRs are available (section <<_cpu_debug_mode_csrs>>) and also the "return from debug mode"
492
instruction `dret` is available when the CPU is "in" debug mode.
493
 
494
[IMPORTANT]
495 64 zero_gravi
The CPU _debug mode_ requires the `Zicsr` and `Zifencei` CPU extension to be implemented (top generics _CPU_EXTENSION_RISCV_Zicsr_
496
and _CPU_EXTENSION_RISCV_Zifencei_ = true).
497 60 zero_gravi
 
498 65 zero_gravi
.Hardware Watchpoints and Breakpoints
499
[NOTE]
500
The NEORV32 CPU _debug mode_ does not provide a hardware "trigger module" (which is optional in the RISC-V debug spec). However, gdb
501
provides a native _emulation_ for code (breakpoints using `break` instruction) and data (polling data watchpoints in automated
502
single-stepping) triggers.
503 60 zero_gravi
 
504 65 zero_gravi
The CPU debug-mode is entered when one of the following events appear:
505
 
506 60 zero_gravi
[start=1]
507
. executing `ebreak` instruction (when `dcsr.ebreakm` is set and in machine mode OR when `dcsr.ebreaku` is set and in user mode)
508
. debug halt request from external DM (via CPU signal `db_halt_req_i`, high-active, triggering on rising-edge)
509
. finished executing of a single instruction while in single-step debugging mode (enabled via `dcsr.step`)
510
 
511
From a hardware point of view, these "entry conditions" are special synchronous (`ebreak` instruction) or asynchronous
512
(single-stepping "interrupt"; halt request "interrupt") traps, that are handled invisibly by the control logic.
513
 
514 65 zero_gravi
.WFI instruction
515
[WARNING]
516
The wait-for-interrupt instruction `wfi` puts the CPU into sleep mode. The CPU will resume normale operation
517
when at least one interrupt source becomes pending (= at least one bit in `mip` CSR is set).
518
However, the CPU will _also resume_ from sleep mode if there is a halt request from the debug module (DM).
519 60 zero_gravi
 
520 65 zero_gravi
Whenever the CPU **enters debug-mode** it performs the following operations:
521
 
522 60 zero_gravi
* move `pc` to `dpcs`
523
* copy the hart's current privilege level to `dcsr.prv`
524
* set `dcrs.cause` according to the cause why debug mode is entered
525
* **no update** of `mtval`, `mcause`, `mtval` and `mstatus` CSRs
526
* load the address configured via the CPU _CPU_DEBUG_ADDR_ generic to the `pc` to jump to "debugger park loop" code in the debug module (DM)
527
 
528 65 zero_gravi
When the CPU **is in debug-mode** the following things are important:
529 60 zero_gravi
 
530
* while in debug mode, the CPU executes the parking loop and the program buffer provided by the DM if requested
531 65 zero_gravi
* effective CPU privilege level is `machine` mode, any PMP configuration is bypassed
532
* the `wfi` instruction acts as a `nop` (also during single-stepping)
533
* if an exception occurs:
534
** if the exception was caused by any debug-mode entry action the CPU jumps to the _normal entry point_
535
   (= _CPU_DEBUG_ADDR_) of the park loop again (for example when executing `ebreak` _in_ debug-mode)
536
** for all other exception sources the CPU jumps to the _exception entry point_ ( = _CPU_DEBUG_ADDR_ + 4)
537
   to signal an exception to the DM and restarts the park loop again afterwards
538
* interrupts are disabled; however, they will remain pending and will get executed after the CPU has left debug mode
539 60 zero_gravi
* if the DM makes a resume request, the park loop exits and the CPU leaves debug mode (executing `dret`)
540
 
541
Debug mode is left either by executing the `dret` instruction footnote:[`dret` should only be executed _inside_ the debugger
542
"park loop" code (-> code ROM in the debug module (DM).)] (_in_ debug mode) or by performing
543
a hardware reset of the CPU. Executing `dret` outside of debug mode will raise an illegal instruction exception.
544
Whenever the CPU **leaves debug mode** the following things happen:
545
 
546
* set the hart's current privilege level according to `dcsr.prv`
547
* restore `pc` from `dpcs`
548
* resume normal operation at `pc`
549
 
550
 
551
:sectnums:
552
==== CPU Debug Mode CSRs
553
 
554
Two additional CSRs are required by the _Minimal RISC-V Debug Specification_: The debug mode control and status register
555
`dcsr` and the program counter `dpc`. Providing a general purpose scratch register for debug mode (`dscratch0`) allows
556
faster execution of program provided by the debugger, since _one_ general purpose register can be backup-ed and
557
directly used.
558
 
559
[NOTE]
560
The debug-mode control and status registers (CSRs) are only accessible when the CPU is _in_ debug mode.
561
If these CSRs are accessed outside of debug mode (for example when in `machine` mode) an illegal instruction exception
562
is raised.
563
 
564
 
565
:sectnums!:
566
===== **`dcsr`**
567
 
568
[cols="4,27,>7"]
569
[frame="topbot",grid="none"]
570
|======
571
| 0x7b0 | **Debug control and status register** | `dcsr`
572
3+| Reset value: 0x00000000
573
3+| The `dcsr` CSR is compatible to the RISC-V debug spec. It is used to configure debug mode and provides additional status information.
574
The following bits are implemented. The reaming bits are read-only and always read as zero.
575
|======
576
 
577
.Debug control and status register bits
578
[cols="^1,^2,^1,<8"]
579
[options="header",grid="rows"]
580
|=======================
581
| Bit   | Name [RISC-V] | R/W | Event
582
| 31:28 | `xdebugver` | r/- | always `0100` - indicates external debug support exists
583
| 27:16 | -           | r/- | _reserved_, read as zero
584
| 15    | `ebereakm`  | r/w | `ebreak` instructions in `machine` mode will _enter_ debug mode when set
585
| 14    | [line-through]#`ebereakh`# | r/- | `0` - hypervisor mode not supported
586
| 13    | [line-through]#`ebereaks`# | r/- | `0` - supervisor mode not supported
587
| 12    | `ebereaku`  | r/w | `ebreak` instructions in `user` mode will _enter_ debug mode when set
588 64 zero_gravi
| 11    | [line-through]#`stepie`#    | r/- | `0` - IRQs are disabled during single-stepping
589 60 zero_gravi
| 10    | [line-through]#`stopcount`# | r/- | `0` - counters increment as usual
590
| 9     | [line-through]#`stoptime`#  | r/- | `0` - timers increment as usual
591 64 zero_gravi
| 8:6   | `cause`     | r/- | cause identifier - why debug mode was entered
592 60 zero_gravi
| 5     | -           | r/- | _reserved_, read as zero
593 64 zero_gravi
| 4     | [line-through]#`mprven`# | r/- | `0` - `mstatus.mprv` is ignored when in debug mode
594
| 3     | [line-through]#`nmip`#   | r/- | `0` - non-maskable interrupt is pending
595 60 zero_gravi
| 2     | `step`      | r/w | enable single-stepping when set
596
| 1:0   | `prv`       | r/w | CPU privilege level before/after debug mode
597
|=======================
598
 
599
 
600
:sectnums!:
601
===== **`dpc`**
602
 
603
[cols="4,27,>7"]
604
[frame="topbot",grid="none"]
605
|======
606
| 0x7b1 | **Debug program counter** | `dpc`
607
3+| Reset value: _UNDEFINED_
608
3+| The `dcsr` CSR is compatible to the RISC-V debug spec. It is used to store the current program counter when
609
debug mode is entered. The `dret` instruction will return to `dpc` by moving `dpc` to `pc`.
610
|======
611
 
612
 
613
:sectnums!:
614
===== **`dscratch0`**
615
 
616
[cols="4,27,>7"]
617
[frame="topbot",grid="none"]
618
|======
619
| 0x7b2 | **Debug scratch register 0** | `dscratch0`
620
3+| Reset value: _UNDEFINED_
621
3+| The `dscratch0` CSR is compatible to the RISC-V debug spec. It provides a general purpose debug mode-only scratch register.
622
|======
623
 
624
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.