VexRiscv-Debug

SWD Debug support in VexRiscv

RISC-V Debug Support

RISC-V ISA

RISC-V is an open standard instruction set architecture based on established RISC (Reduced Instruction Set Computer) principles.

Comparing to ARM and x86, a RISC-V CPU has the following advantages:

Free : RISC-V is open-source.
Simple : RISC-V is much smaller than other commercial ISAs.
Modular : RISC-V has a small standard base ISA, with multiple standard extensions.
Stable : Base and first standard extensions are already frozen. There is no need to worry about major updates.
Extensibility : Specific functions can be added based on extensions. There are many more extensions are under development.

RISC-V Minimal Viable Debugger

To create a minimum viable debugger on a RISC-V Processor, you need the following capabilities:

Memory Access: The ability to peek and poke memory. This means reading from and writing to specific memory locations. Alternatively, the ability to push instructions (through the program buffer) can also suffice if direct memory access is not possible or is restricted.
CPU Register Access: The ability to read and write CPU registers. Registers are special storage locations within the CPU that are used for calculations, control, and status information.
CPU Control: The ability to control the CPU. This involves several key actions:
- Halting the CPU: Stopping the CPU’s execution.
- Single-stepping the CPU: Executing one instruction at a time.
- Resetting the CPU: Restarting the CPU.
- Setting Breakpoints: Pausing the CPU when it reaches a certain instruction or memory location.

Here’s a simplified diagram representing these core components:

     +---------------------+      +-----------------------+
     |    Debugger Host    |      |    Target Device      |
     +---------------------+      +-----------------------+
             |                           |
             |      (Debug Interface)    |
             v                           v
    +-----------------------+      +-----------------------+
    |   Memory Access       |----->| Memory                |
    |  (Read/Write)         |      |                       |
    +-----------------------+      +-----------------------+
             |                           |
             |                           |
    +-----------------------+      +-----------------------+
    | CPU Register Access   |----->| CPU Registers         |
    |  (Read/Write)         |      |                       |
    +-----------------------+      +-----------------------+
             |                           |
             |                           |
    +-----------------------+      +-----------------------+
    |   CPU Control         |----->| CPU (Halt, Step, etc.)|
    | (Halt, Step, Reset)   |      |                       |
    +-----------------------+      +-----------------------+

Vexriscv Processor

VexRiscv is an FPGA-friendly CPU core that implements the RISC-V instruction set architecture (ISA). Designed with flexibility and scalability in mind, it caters to a wide range of applications, from compact microcontroller-based systems to more complex multi-core configurations. The project is open-source under the MIT license, promoting community collaboration and adaptation.

VexRiscv is developed using SpinalHDL, a high-level hardware description language that enhances design modularity and reusability. This approach allows for a plugin-based architecture, enabling users to customize and extend the CPU’s capabilities to meet specific project requirements.

JTAG support in Vexriscv (official stack)

For the official debug path, JTAG follows the RISC-V Debug Specification DTM (IEEE 1149.1 TAP + DTMCS/DMI registers), not the custom Murax DebugPlugin protocol.

+-----------------+
|  GDB (Host PC)  |
+-------+---------+
        |
        v
+-----------------+     +--------------------+
|  riscv-openocd  | --> |  JTAG adapter    |
|  (riscv-target) |     | (TCK,TMS,TDI,TDO) |
+-----------------+     +--------------------+
                                  |
                                  v
                    +--------------------------------------------------------------+
                    |                     Target (FPGA)                            |
                    |  DebugTransportModuleJtagTap                                 |
                    |    → DebugBus (DebugCmd/DebugRsp)                            |
                    |    → DebugModule.scala                                       |
                    |    → DebugHartBus → CsrPlugin (withPrivilegedDebug)          |
                    |    → VexRiscv CPU                                            |
                    +--------------------------------------------------------------+

RTL: SpinalHDL/lib/.../cpu/riscv/debug/DebugTransportModuleJtag.scala, DebugModule.scala. Generator: sbt "runMain vexriscv.demo.GenFullWithOfficialRiscvDebug".

Host setup (official JTAG — baseline before SWD)

Terminal 1:

openocd -f interface/ftdi/olimex-jtag-tiny.cfg -f target/riscv.cfg

Terminal 2:

riscv32-unknown-elf-gdb hello.elf
(gdb) target extended-remote :3333
(gdb) load
(gdb) break main
(gdb) continue

Target setup

SWD support in Vexriscv

SWD stands for Serial Wire Debug. The key differences between JTAG and SWD are :

SWD uses a two-wire interface (SWCLK and SWDIO) whereas JTAG uses four or five wires.
SWD can reduce pin count on the target; throughput depends on probe and adapter implementation.

The following conceptual diagram explains the general components and data flow involved in debugging via SWD:

MkDocs icon

In the diagram:

The Debug Host PC runs debugging software such as GDB and OpenOCD.
The Debug Transport Module (DTM) converts the USB/JTAG interface to SWD, communicating with the target system through the SWCLK and SWDIO pins.
The SW-DP (Debug Port) handles the SWD protocol and provides access to the Debug Module(DM).
The Debug Module(DM) provides access to the CPU’s registers, controls the CPU execution, and provides access to system memory via the system bus.
The VexRiscv CPU and the Memory System are debugged through this interface.

To add SWD transport for the official RISC-V debug stack in VexRiscv:

1. Debug Module (DM) — already exists

DebugModule.scala in SpinalHDL implements the RISC-V DM and connects via DebugBus(7).
Task 1 is to ensure VexRiscv SoC generators wire it correctly (enableRiscvDebug(), withPrivilegedDebug) and complete any missing spec features — not to build DM from scratch.

2. SWD Debug Transport (new DTM)

A new DebugTransportModuleSwd implements ARM ADI SW-DP (Phases 2A/2B) plus an AP→DebugBus bridge (Phases 2C/2D). This replaces JTAG-DTM on the wire only; the DM is unchanged.

3. Debug Module Interface (DMI)

DMI is the register bus between transport and DM, exposed in SpinalHDL as DebugBus (DebugCmd / DebugRsp). It is not memory-mapped in the CPU address space.
CPU system memory is reached via DM System Bus Access or abstract/program-buffer paths.

Breakdown of Tasks

1. Complete official RISC-V debug integration in VexRiscv

Goal: Ensure the existing SpinalHDL DebugModule + JTAG DTM path is fully wired in VexRiscv SoC generators and meets project requirements.

Note: DebugModule.scala, DebugTransportModuleJtag.scala, and CsrPlugin debug support already exist under SpinalHDL/lib/.../cpu/riscv/debug/. This task completes integration and any missing DM features — it does not duplicate Murax DebugPlugin work.

Detailed milestones: Standard Debug Spec Milestone.

2. SWD Debug Transport Implementation

Goal: Add ARM ADI SWD as an alternate DTM to the official DebugBus (alongside JTAG-DTM). Reference Specs: ARM Debug Interface Architecture Specification ADIv6.0

The following Architecture diagram explains the components and data flow involved in debugging VexRiscv via SWD, showing both existing (implemented) and new (to be built) components with their implementation phases:

JTAG Path (EXISTING):                        SWD Path (NEW):
==============================               ==============================

JTAG TAP + dtmcs/dmi                         SWD Interface (Phase 2A)
(DebugTransportModuleJtag.scala)             + SW-DP registers (Phase 2B)
  - JTAG state machine                        - SWD protocol state machine
              |                                          |
              |  both produce the                        |
              |  same interface                          | DMI Bus Adapter
              v                                          | (Phase 2C)
        DebugBus (DebugCmd/DebugRsp)                     v
              |                                    DebugBus (DebugCmd/DebugRsp)
              |                                          |
              +──────────────► same bus ◄────────────────+
                                  |
                                  v
                     Debug Module (DM)  ◄── NO CHANGES NEEDED
                     (DebugModule.scala)    (transport-agnostic)
                                  |
                          DebugHartBus
                                  |
                                  v
                     VexRiscv CPU        ◄── NO CHANGES NEEDED
                     (CsrPlugin.scala)      (transport-agnostic)

Note:

The Debug Module and VexRiscv CPU are transport-agnostic i.e. they work identically whether accessed via JTAG or SWD. The Debug Module and VexRiscv CPU need NO changes — they only see DebugBus commands and have no knowledge of whether they came from JTAG or SWD.
Phase 2A (SWD Interface) + Phase 2B (SW-DP) together are the SWD equivalent of the existing JTAG DTM. They handle the wire protocol and produce DebugBus commands — the same DebugCmd/DebugRsp interface that the JTAG DTM already produces.
For SoC-level change: Add withSwdTransport() to DebugModuleFiber.scala alongside withJtagTap(). Instantiate one transport per SoC build (via generator flag ). DebugModuleFiber OR-combines debugBuses and assumes only one interface is active i.e. do not wire JTAG-DTM and SWD-DTM concurrently without explicit arbitration.
Why Phase 2C (DMI Bus Adapter) is needed: In the JTAG path, the dmi shift register directly carries DMI address+data+op, so the translation to DebugBus is straightforward. In SWD, access goes through DP registers — the debugger writes SELECT to pick an AP address, then issues AP read/write operations. The adapter translates this DP/AP register access model into DebugBus read/write commands.

Phase 2A: SWD Protocol State Machine

Spec Reference: ADIv6.0 Sec B4.1-B4.2
File: DebugTransportModuleSwd.scala — line-layer component SwdPhy

Tasks for Phase 2A.

Phase 2B: DP Register File

Spec Reference: ADIv6.0 Sec B2.2 (DP Reference Information)
File: same DebugTransportModuleSwd.scala (SW-DP register component behind the 2A seam)

Tasks for Phase 2B.

Phase 2C: DMI Bus Adapter (SWD→DebugBus Bridge)

Spec Reference: Custom bridge layer
Files: DebugTransportModuleSwd.scala (bridge) + DebugModuleFiber.scala (withSwdTransport())

Tasks for Phase 2C.

Standalone testing using simulation of Phases 2A–2C

Phases 2A–2C can be implemented and verified with test bench entirely inside a VexRiscv project using Verilator — no SoC/LiteX/cluster generation required.

3. System Integration into SoC and Toolchain

Goal: Integrate the new debug architecture into the top-level FPGA/System design.

Stock riscv-openocd riscv-target does not support RISC-V over ARM SW-DP (OpenOCD #378).

Strategy	Description
Custom OpenOCD target	New `target/vexriscv_swd.cfg` + Tcl helpers: `transport select swd`, `adapter driver cmsis-dap`, then `dap info`, `dap apreg`, scripted reads/writes to `DMI_ADDR`/`DMI_DATA` at AP0. Reuse existing `riscv` examination once DM is reachable.

Tasks for system integration.

4. Verification & Test Infrastructure

Goal: Ensure the entire debug pipeline behaves per spec.

Tasks for testing & verification.

5. Documentation & Developer Interface

Goal: Make integration/usage clear for future development.

Tasks for documentation.

This site is open source. Improve this page.