Debug spec v1.0 implementation

[JacobPease]

This pull request contains an early stage implementation of the Debug Specification. It has the basic features of halting, resuming, resetting, halting on reset, and reading GPRs, CSRs, and FPRs. In it's current state it provides a framework with which we can implement more complicated features, like stepping and going into debug mode on ebreaks in various privilege modes. Inside docs/debug/wallydebug.md is a list of features already implemented and features that are going to be implemented.

This PR also contains a new method of Verification for the Debug module. Since the Debug module is driven by commands sent over a JTAG interface, separate testvectors must drive the JTAG pins while Wally executes instructions. To accomplish this, a test building framework was developed taking advantage of the features of Spike and the RISC-V variant of OpenOCD which can be found at this repo: riscv-openocd

First we write assembly tests for Spike and we write Tcl scripts to drive OpenOCD. We then run these two programs together as separate processes and connect OpenOCD to Spike's remote bitbang interface. The Tcl commands drive the JTAG pins and allows the RISC-V code, which has certain stopping points in it, to finish executing, ending the test. OpenOCD is configured to output a log of all Debug Module Interface commands it writes over the JTAG interface. This log is scraped for testvectors and saved to a file.

When we run wsim with a configuration with DEBUG_SUPPORTED set high, the testbenches Debugger module is driven with the testvectors generated using OpenOCD and Spike. Several features have been verified using this method.

To build and run the debug tests, run the following commands starting in the cvw root directory:

source ./setup.sh
cd sim; make deriv
cd ../tests/debug
make
wsim debug64 wally64debug

In addition to remaining features to be added, there's room for other improvements and discussion on how to optimally modify the current setup. There are currently only tests written for the rv64gc configuration with Debug supported. Additionally, implementing Imperas support requires that wsim and the testbench be expanded to take two testvector references when doing single tests on a single elf file and a Debugger testvector file, though the rvvi interface to the DMI is simple and easy to add to the testbench. This rvvi DMI interface is serial interface agnostic and only requires that we connect the DMI signals.

[juanschroeder]

Hi @JacobPease . It would be great to have this. Would it be working with current master? I don't have an Arty A7 but I can try to test it in a Nexys A7 or a Genesys 2 if that helps.

[stineje]

Juan, Thanks for the email. Jacob and I aRe working to get this up to spec, hopefully this week. We are still going through code review, but hope to do another pass to get into master. Please feel free to try on Nexus A7 or Genesys 2 - I don’t have those boards with me right now, but would appreciate if you could look. Our debug implementation only is a minimal implementation that implements abstract read/write. We hope to add more once we get into master. We welcome any involvement you can have with this. Let me know any questions or issues. Take care. All my best, James On Jun 1, 2026, at 6:13 AM, Juan Schroeder ***@***.***> wrote: [https://avatars.githubusercontent.com/u/25896545?s=20&v=4]juanschroeder left a comment (openhwgroup/cvw#1590)<#1590 (comment)> Hi @JacobPease<https://github.com/JacobPease> . It would be great to have this. Would it be working with current master? I don't have an Arty A7 but I can try to test it in a Nexys A7 or a Genesys 2 if that helps. — Reply to this email directly, view it on GitHub<#1590?email_source=notifications&email_token=AFSIHPH3W66WYFIWAEDIKED45VJNZA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINJZGE3DENJQHE22M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#issuecomment-4591625095>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AFSIHPG6COV5ON3HCMI2KBL45VJNZAVCNFSM6AAAAACPGSQQPOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DKOJRGYZDKMBZGU>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>