FAQs for RISC-V Debugger

The embedded tools company

Search FAQs

PDF document ( 72KB / 23-Jan-2021 )

[System Designer] Which combinations of 'mcontrol' on-chip triggers are supported?
Ref: 0546

The RISC-V debug specification defines a trigger module, which holds a set of triggers. Each trigger can be individually configured for one of multiple trigger types (such as 'mcontrol'), and depending on the trigger type the trigger can be configured with various options. The debug specification allows system designs with heterogeneous trigger capabilities, which means not every trigger must support the same trigger types and same trigger type configuration options.

The following are the requirements for the trigger type 'mcontrol' in order to be compatible with the current version of the Lauterbach RISC-V debugger:

  • The debugger only uses the largest contiguous block of triggers that support the type 'mcontrol'. Example: if only trigger indexes 1, 4, 5, 6, 9 support type 'mcontrol', then the debugger will only use the contiguous block of indexes 4, 5, 6.

  • Each mcontrol trigger has various optional configuration options (execute, store, load, chain, ...). The debugger currently only uses configuration options that are supported by all triggers of the contiguous mcontrol block (see above). The exception is the 'chain' option, which is used if it is supported by all except the last trigger in that block.

[System Designer] Which core registers (CSRs) are needed by the debugger?
Ref: 0531

The debugger does not only need access to debug registers of the Debug Module. In order to function properly, several core registers (Control and Status Registers, CSRs) need to be accessible/implemented as well. The following summary lists CSRs that stand in the context of debugging, and mentions whether they are needed or not:

Core Debug Registers
  • Debug Control and Status (dcsr)
    1. Mandatory register. Without it, debug support is not possible.
  • Debug PC (dpc)
    1. Mandatory register. Without it, debug support is not possible.
  • Debug Scratch Register 0/1 (dscratch0/1)
    1. Optional register. The Lauterbach debugger does currently not use these registers.

Debug/Trace Registers
  • Debug/Trace trigger register select (tselect):
    1. [debug spec v0.13.x]: Mandatory, no matter if triggers are implemented or not
    2. [debug spec v0.14.x and later]: Mandatory if any triggers are implemented, otherwise optional
  • First Debug/Trace trigger data register (tdata1):
    1. [debug spec v0.13.x]: Mandatory, no matter if triggers are implemented or not
    2. [debug spec v0.14.x and later]: Mandatory if any triggers are implemented, otherwise optional
  • Second Debug/Trace trigger data register (tdata2):
    1. Mandatory if any triggers are implemented, otherwise optional
  • Third Debug/Trace trigger data register (tdata3):
    1. Optional register (from debugger perspective). Currently the debugger does only support match control triggers, for which tdata3 is not used. Might however be used for other trigger types in the future.
  • Trigger Info (tinfo):
    1. Mandatory if triggers are implemented and the "trigger type bitfield" (tdata1->type) is writable. Otherwise optional.

Machine-Level Control and Status Registers (Machine-Level CSRs)
  • Machine ISA Register (misa):
    1. This register helps the debugger to determine the capabilities of the core under debug.

      It helps to determine the base ISA of the core. Also, it helps to determine supported ISA extensions such as e.g. floating-point ("F"/"D"), for which the debugger needs to access and display additional floating-point registers.

      If this register is not implemented, the debugger has to fall back to less reliable and intrusive try & error methods to determine the information mentioned above. Therefore, it is highly recommended to implement this register, so that the debugger can work in a reliable and minimally-intrusive way.

[System Designer] Which debug registers and their bitfields that are declared as "optional" are needed by the debugger?
Ref: 0530

In some aspects the RISC-V debug specification is very generic and leaves room for optional features and implementations. Several debug registers of the Debug Module (DM), or bitfields within these debug registers, are declared as optional. The following lists all optional debug registers as well as all debug registers that contain optional bitfields, and describes whether they are currently needed by the debugger.

Please note that this list can change at any time in the future. If a register or bitfield is not in this list, then the debug specification sees it as non-optional, and consequently it is also required by our debugger.

  1. Abstract Data 0 - 11 (data0 - data11): The required amount of dataX registers depends on several factors, such as base ISA (RV32, RV64, ...) of all cores that are connected to the RISC-V debug module. Also it depends on the implemented set of features in the debug module, in particular the implemented abstract commands.
  2. Debug Module Control (dmcontrol):
    1. hasel bitfield: recommended for multicore debugging, otherwise not
  3. Hart Info (hartinfo): Currently this register is not used, as the debugger does not use programs that do explicitly access data or dscratch registers. Future versions of the debug driver might make use of the fact that programs that directly access data or dscratch registers are faster. Compatibility for such future performance improvements is only possible if this register is implemented. If it is not implemented the debug driver will still work, but without these performance improvements.
  4. Abstract Command Autoexec (abstractauto): Although this register is declared as optional, we highly recommend to implement it. The 'autoexecdata[0]' feature allows significant performance boosts when executing multiple consecutive abstract commands. This is e.g. extensively used during memory read/write via program buffer or abstract command.
    Our debug driver does currently not work with designs that do not have this feature implemented.
  5. Program Buffer 0 - 15 (progbuf0 - progbuf15): The debug specification allows program buffer sizes between 0 and 16. A size of 0 means that there is no program buffer at all. In general there are two main ways of implementing a valid RISC-V debug IP (which are described in the RISC-V debug specification in more detail):

    1. Abstract Command Based Approach: All main operations and interactions of the debugger are done via abstract commands. In this case, no program buffer is needed, so program buffer size can be 0.

      However, the current ratified debug specification v0.13.x does not provide a proper mechanism to detect/discover if a certain abstract command type is supported, and which individual options of an abstract command are supported. In particular, this affects the debugger system discovery for the "access memory" abstract command, which is why Lauterbach can currently only provide limited support for this mechanism. See the discussions of the official RISC-V debug workgroup for more details. Due to these discrepancies regarding system discovery of abstract commands in v0.13.x, we currently recommend to use the "Execution Based" approach instead until the issues with system discovery are resolved (potentially in a future version of the debug specification).

    2. Execution Based Approach: The main operations and interactions of the debugger do partially rely on the program buffer execution.
      In this case the Lauterbach debugger currently uses the program buffer in a variety of scenarios, and there might be added additional scenarios in the future, or existing scenarios and behaviors change due to bug fixes or improvements. Therefore it is difficult to "recommend" a certain (small) program buffer size without knowing whether this size might be sufficient for all features in the future. Also, the required program buffer size depends on whether the 'implicit ebreak' feature is implemented (dmstatus.impebreak).
      What can be said however is that, as of the current implementation of the debug driver (state 2020-03-27), a program buffer size of 3 (without implicit ebreak) or 2 (with implicit ebreak) is the minimum that is sufficient for all currently available features.
      However it is not unlikely that an advanced and improved future driver might require (or at least could make good use of) a larger program buffer.
      In summary, in case that a system designer wants to stay on the safe side for future updates of the driver, and if chip area is not quite that important, then we suggest a full program buffer size of 16. However, as mentioned, the current minimum size mentioned above is also sufficient. Also, in case that the driver will add functions that require a size larger than the minimum size mentioned above, we will always leave a "fallback" option with possibly reduced functionality for hardware with smaller program buffer sizes. Hardware with a program buffer size that is smaller than the requirements mentioned above can however not work with our debug driver, if you go with the "execution based" approach.
  6. System Bus Address (sbaddress0/1/2) + System Bus Data (sbdata0/1/2/3): These optional registers are only needed if you want to access memory via the system bus. The debugger can also work without system bus access. Whether you need the system bus access or not depends on the individual needs of the user and on the target architecture.
  7. Halt region registers (Debug Module address 0x40 - 0x5f):
    1. If the Debug Module is only connected to a single RISC-V hart (i.e. zero is the only valid index in dmcontrol->hartsel), the debugger does not need the halt region registers, as the halt state of the hart can be determined via the status bits in dmstatus.
    2. However, in a system with more than one RISC-V hart connected to the Debug Module, the status bits in dmstatus are not sufficient to determine the halt state of each hart individually. Consequently, in such a system the halt region registers are necessary for the debugger. The debugger does not need all 32 halt region registers to be present, but at least each register that corresponds to an available hart.

Can non-standard / custom RISC-V ISA extensions be supported?
Ref: 0528

The RISC-V ISA specification defines ISA extensions, which can complement a base ISA set with certain additional instructions. Despite the standard ISA extensions, the ISA specification also standardizes a way to define own non-standard / custom ISA extensions.

There are a different options how custom, non-standard ISA extensions can be supported by our tool:

  1. Direct Integration: In some circumstances Lauterbach can directly add support for certain custom ISA extensions to TRACE32. This mainly affects the disassembler and optionally the instruction set simulator. The support for the custom extensions can then be enabled by e.g. selecting the corresponding CPU entry via the SYStem.CPU command. If and under which circumstances such a direct integration into our software can be provided needs to be discussed individually.

  2. Disassembler plugin via APU API: Lauterbach provides an API that allows customers to load their own custom "disassembler plugin" (via DLL), in order to extend the Lauterbach disassembler functionality by own non-standard instructions of ISA extensions. This API is called "API for Auxiliary Processing Unit" (APU API). More information can be found at https://www.lauterbach.com/pdf/api_apu.pdf

    The advantages of using such a plugin are:
    1. Customers can test their ISA extension(s) already in very early stages of their chip and toolchain development and have full control over any changes.
    2. There is no license arrangement with Lauterbach required.
    3. It is not necessary to reveal details about the ISA extensions to Lauterbach or any other party (beneficial for confidential extensions).

    Please be aware of the restrictions: The APU API is not supported by the TRACE32 instruction set simulator. Lauterbach does provide an API for the simulator, however this API only allows to simulate periphery behavior (https://www.lauterbach.com/pdf/simulator_api_lib.pdf) and not behavior of a whole core.

Which RISC-V base ISAs are supported?
Ref: 0526

The RISC-V specification defines base ISAs for 32bit (RV32), 64bit (RV64) and 128bit (RV128). The Lauterbach debug driver generally supports core architectures with RV32 and RV64 base ISA. However, RV128 ISA cores are currently not supported.

Which standard RISC-V ISA extensions are supported?
Ref: 0527

The RISC-V ISA specification defines certain standard ISA extensions, which can complement a base ISA set with certain additional instructions (e.g. the "A" extension for atomic instructions).

Our RISC-V debugger supports all standard ISA extensions that are defined in the RISC-V ISA specification. This includes support by our disassembler and instruction set simulator. For certain special extensions such as floating point extensions ("F"), our RISC-V debugger can display the content of additional floating point registers and modify their values. Our support covers any valid combination of these standard ISA extensions.

Which versions of the RISC-V debug specification are supported by the Lauterbach debugger?
Ref: 0525

The Lauterbach RISC-V debugger does support designs based on the official RISC-V debug specification (see link to the RISC-V homepage below).
The first officially ratified debug spec version was version v0.13, which is why our debugger supports all v0.13.x versions and any versions after that. However any unofficial draft versions before the first ratified v0.13 (such as v0.11) are not supported.

Also be aware that conformity of RISC-V hardware with the official RISC-V debug specification is not the only criterion for seamless compatibility with Lauterbach tools. The hardware should also meet the requirements that are listed in the "RISC-V Debugger" FAQ category on our homepage, in all questions that have the prefix "[System Designer]" .

Which ways of integrating a RISC-V debug module into a SoC are currently supported?
Ref: 0529

Please see the Lauterbach RISC-V debugger manual (link below), chapter "Quick Start for Debug Module Configuration" for details.

Copyright © 2021 Lauterbach GmbH, Altlaufstr.40, 85635 Höhenkirchen-Siegertsbrunn, Germany   Impressum     Privacy Policy
The information presented is intended to give overview information only.
Changes and technical enhancements or modifications can be made without notice. Report Errors
Last generated/modified: 23-Jan-2021