github-mirrors/ibex
1
0
Fork 0
mirror of https://github.com/lowRISC/ibex.git synced 2025-04-23 21:39:13 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

[doc] Document debug CSRs

Browse source 
This resolves lowRISC/ibex#307.

Signed-off-by: Pirmin Vogel <vogelpi@lowrisc.org>
This commit is contained in:
Pirmin Vogel 2019-11-14 18:44:33 +01:00
parent d117b24a17
commit 46608d9f76
5 changed files with 90 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

75
doc/cs_registers.rst
View file

@ -46,7 +46,7 @@ Ibex implements all the Control and Status Registers (CSRs) listed in the follow
+---------+--------------------+--------+-----------------------------------------------+
| 0x3BF | ``pmpaddr15`` | WARL | PMP Address Register |
+---------+--------------------+--------+-----------------------------------------------+
| 0x7B0 | ``dcsr`` | RW | Debug Control and Status Register |
| 0x7B0 | ``dcsr`` | WARL | Debug Control and Status Register |
+---------+--------------------+--------+-----------------------------------------------+
| 0x7B1 | ``dpc`` | RW | Debug PC |
+---------+--------------------+--------+-----------------------------------------------+
@ -282,6 +282,79 @@ Reset Value: ``0x0000_0000``
| address[33:2] |
+----------------+
.. _csr-dcsr:
Debug Control and Status Register (dcsr)
----------------------------------------
CSR Address: ``0x7B0``
Reset Value: ``0x4000_0003``
Accessible in Debug Mode only.
Ibex implements the following bit fields.
Other bit fields read as zero.
+-------+------+------------------------------------------------------------------+
| Bit# | R/W | Description |
+-------+------+------------------------------------------------------------------+
| 31:28 | R | **xdebugver:** 4 = External spec-compliant debug support exists. |
+-------+------+------------------------------------------------------------------+
| 15 | RW | **ebreakm:** EBREAK in M-Mode behaves as described in Privileged |
| | | Spec (0), or enters Debug Mode (1). |
+-------+------+------------------------------------------------------------------+
| 12 | WARL | **ebreaku:** EBREAK in U-Mode behaves as described in Privileged |
| | | Spec (0), or enters Debug Mode (1). |
+-------+------+------------------------------------------------------------------+
| 8:6 | R | **cause:** 1 = EBREAK, 3 = halt request, 4 = step |
+-------+------+------------------------------------------------------------------+
| 2 | RW | **step:** When set and not in Debug Mode, execute a single |
| | | instruction and enter Debug Mode. |
+-------+------+------------------------------------------------------------------+
| 1:0 | WARL | **prv:** Privilege level the core was operating in when Debug |
| | | Mode was entered. May be modified by debugger to change |
| | | privilege level. Ibex allows transitions to all supported modes. |
| | | (M- and U-Mode). |
+-------+------+------------------------------------------------------------------+
Details of these configuration bits can be found in the RISC-V Debug Specification, version 0.13.2 (see Core Debug Registers, Section 4.8).
Note that **ebreaku** and **prv** are accidentally specified as RW in version 0.13.2 of the RISC-V Debug Specification.
More recent versions of the specification define these fields correctly as WARL.
.. _csr-dpc:
Debug PC Register (dpc)
-----------------------
CSR Address: ``0x7B1``
Reset Value: ``0x0000_0000``
When entering Debug Mode, ``dpc`` is updated with the address of the next instruction that would be executed (if Debug Mode would not have been entered).
When resuming, the PC is set to the address stored in ``dpc``.
The debug module may modify ``dpc``.
Accessible in Debug Mode only.
Debug Scratch Register 0 (dscratch0)
------------------------------------
CSR Address: ``0x7B2``
Reset Value: ``0x0000_0000``
Scratch register to be used by the debug module.
Accessible in Debug Mode only.
Debug Scratch Register 1 (dscratch1)
------------------------------------
CSR Address: ``0x7B3``
Reset Value: ``0x0000_0000``
Scratch register to be used by the debug module.
Accessible in Debug Mode only.
Time Registers (time(h))
------------------------

15
doc/debug.rst
View file

@ -11,10 +11,10 @@ Interface
+-----------------+-----------+-----------------------------+
| Signal | Direction | Description |
+=================+===========+=============================+
| ``debug_req_i`` | input | Request to enter debug mode |
| ``debug_req_i`` | input | Request to enter Debug Mode |
+-----------------+-----------+-----------------------------+
``debug_req_i`` is the "debug interrupt", issued by the debug module when the core should enter debug mode.
``debug_req_i`` is the "debug interrupt", issued by the debug module when the core should enter Debug Mode.
Parameters
----------
@ -22,7 +22,14 @@ Parameters
+---------------------+-----------------------------------------------------------------+
| Parameter | Description |
+=====================+=================================================================+
| ``DmHaltAddr`` | Address to jump to when entering debug mode |
| ``DmHaltAddr`` | Address to jump to when entering Debug Mode |
+---------------------+-----------------------------------------------------------------+
| ``DmExceptionAddr`` | Address to jump to when an exception occurs while in debug mode |
| ``DmExceptionAddr`` | Address to jump to when an exception occurs while in Debug Mode |
+---------------------+-----------------------------------------------------------------+
Core Debug Registers
--------------------
Ibex implements four core debug registers, namely :ref:`csr-dcsr`, :ref:`csr-dpc`, and two debug scratch registers.
All those registers are accessible from Debug Mode only.
If software tries to access them without the core being in Debug Mode, an illegal instruction exception is triggered.

2
doc/exception_interrupts.rst
View file

@ -55,7 +55,7 @@ It has interrupt ID 31, i.e., it has the highest priority of all interrupts and
All interrupt lines are level-sensitive.
It is assumed that the interrupt handler signals completion of the handling routine to the interrupt source, e.g., through a memory-mapped register, which then deasserts the corresponding interrupt line.
In debug mode, all interrupts including the NMI are ignored independent of ``mstatus``.MIE and the content of the ``mie`` CSR.
In Debug Mode, all interrupts including the NMI are ignored independent of ``mstatus``.MIE and the content of the ``mie`` CSR.
Recoverable Non-Maskable Interrupt

4
doc/integration.rst
View file

@ -88,9 +88,9 @@ Parameters
+------------------------------+-------------+------------+-----------------------------------------------------------------+
| ``MultiplierImplementation`` | string | "fast" | Multiplicator type, "slow", or "fast" |
+------------------------------+-------------+------------+-----------------------------------------------------------------+
| ``DmHaltAddr`` | int | 0x1A110800 | Address to jump to when entering debug mode |
| ``DmHaltAddr`` | int | 0x1A110800 | Address to jump to when entering Debug Mode |
+------------------------------+-------------+------------+-----------------------------------------------------------------+
| ``DmExceptionAddr`` | int | 0x1A110808 | Address to jump to when an exception occurs while in debug mode |
| ``DmExceptionAddr`` | int | 0x1A110808 | Address to jump to when an exception occurs while in Debug Mode |
+------------------------------+-------------+------------+-----------------------------------------------------------------+
Interfaces

4
doc/verification.rst
View file

@ -68,7 +68,7 @@ Testplan
The goal of this bench is to fully verify the Ibex core with 100%
coverage. This includes testing all RV32IMC instructions, privileged
spec compliance, exception and interrupt testing, debug mode operation etc.
spec compliance, exception and interrupt testing, Debug Mode operation etc.
The complete test list can be found in the file `dv/uvm/riscv_dv_extension/testlist.yaml
<https://github.com/lowRISC/ibex/blob/master/dv/uvm/riscv_dv_extension/testlist.yaml>`_.
@ -103,7 +103,7 @@ However, this checking model quickly falls apart once situations involving exter
as interrupts and debug requests) start being tested, as while ISS models can simulate traps due to
exceptions, they cannot model traps due to external stimulus.
In order to provide support for these sorts of scenarios to verify if the core has entered the
proper interrupt handler, entered debug mode properly, updated any CSRs correctly, and so on, the
proper interrupt handler, entered Debug Mode properly, updated any CSRs correctly, and so on, the
handshaking mechanism provided by the RISCV-DV instruction generator is heavily used, which
effectively allows the core to send status information to the testbench during program execution for
any analysis that is required to increase verification effectiveness.