JTAG On-Chip Debugger

[stnolting]

I am currently working on an on-chip debugger (OCD) that is compatible to the RISC-V External Debug Support - Version 0.13.2. It will support the execution based debugging scheme.

The NEORV32 OCD complex will be base on four modules:

• Debug Transfer Module (DTM): The DTM provides a JTAG TAP (test access port) that allows an external debugger to communicate with the debug control system (the debug module). This unit is already implemented and tested: github.com/stnolting/riscv-debug-dtm
• Debug Module (DM): The actual control system for the OCD. I am currently working on this.
• Debug Memory (DBMEM): The debug memory provides the "park loop" code and several memory-mapped registers accessible by the CPU via the processor-internal bus and by the DM. These memory-mapped registers are used to communicate halt/run/execute requests/acknowledges between the CPU (running in debug mode and executing the park loop) and the DM. This module is also "work-in-progress".
• CPU Debug Mode: The new CPU operation mode the CPU will be in when running on-chip debugging. The modifications to the CPU core are already done, tested and uploaded to the repository.

Status

💡 Check out the current state in the On-Chip Debugger Project Board

I have tested the whole OCD complex in its early stage and the results are quite promising. I am using "Open On-Chip Debugger 0.11.0-rc1+dev (SiFive OpenOCD 0.10.0-2020.12.1)" (RISC-V port of OpenOCD; prebuilt binaries available from SiFive) on Windows 10 with a FTDI FT2232H-56Q Mini Module as JTAG adapter to test everything on real hardware. The NEORV32 + OCD runs on an Intel Cyclone IV board.

Connecting to the NEORV32 OCD using OpenOCD:

N:\Projects\riscv-debug-dtm>openocd -f openocd\riscv_debug_ftdi.cfg
Open On-Chip Debugger 0.11.0-rc1+dev (SiFive OpenOCD 0.10.0-2020.12.1)
Licensed under GNU GPL v2
For bug reports:
        https://github.com/sifive/freedom-tools/issues
1
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 100 kHz
Info : JTAG tap: riscv.cpu tap/device found: 0x0cafe001 (mfg: 0x000 (<invalid>), part: 0xcafe, ver: 0x0)
Info : datacount=1 progbufsize=2
Info : Disabling abstract command reads from CSRs.
Info : Examined RISC-V core; found 1 harts
Info :  hart 0: XLEN=32, misa=0x40800100
Info : starting gdb server for riscv.cpu.0 on 3333
Info : Listening on port 3333 for gdb connections
Info : accepting 'telnet' connection on tcp/4444

OpenOCD can successfully connect to the DM/CPU via the DTM. Executing abstract commands and configuring and running the DM's program buffer also works: OpenOCD is able to read the CPU's misa CSR 🚀

Running, halting and single-stepping the CPU also works already. Furthermore, OpenOCD can read arbitrary memory locations using the low-level mdw command:

Open On-Chip Debugger
> halt
> mdw 0xffffffe0 8
0xffffffe0: 05f5e100 00000de0 00070035 00000000 00000000 80000000 00004000 00002000

> mdw 0xffff0000 64
0xffff0000: 00000093 00000113 00000193 00000213 00000293 00000313 00000393 00000713
0xffff0020: 00000793 80012117 fd810113 ffc17113 00010413 80010197 7cc18193 00000517
0xffff0040: 0c050513 30551073 34151073 34301073 34201073 30001073 30401073 30601073
0xffff0060: ffa00593 32059073 b0001073 b8001073 b0201073 b8201073 00010417 e8840413
0xffff0080: 00010497 f8048493 00042023 00440413 fe941ce3 80010597 f6c58593 80818613
0xffff00a0: 00c5d863 00058023 00158593 ff5ff06f 00001597 f4858593 80010617 f4860613
0xffff00c0: 80010697 f4068693 00d65c63 00058703 00e60023 00158593 00160613 fedff06f
0xffff00e0: 00000513 00000593 060000ef 30047073 00000013 10500073 0000006f ff810113

> resume
Disabling abstract command writes to CSRs.
>

So far, this looks quite promising!✨ 🚀 ✨ 🚀 ✨

TODOs

• some more testing
• I really need to clean-up all the code before pushing to the repo
• write a proper documentation - I have already started documenting the OCD but there are still a lot of blank spots...
• write a tutorial how to connect to the OCD using OpenOCD (Linux & Windows)
• more testing
• gdb integration
• future: maybe add "RISC-V trigger modules"
• even more testing

📢 Help Wanted 📢

I am not a software expert and I am quite new to the GNU Debugger. I would be very thankful if anyone could help with the integration of gdb. So if you have any questions or ideas or if you want to contribute in any way, feel free to comment. 😉

[suarezvictor]

OpenOCD already supports an interface to GDB using TCP port 3333
Connect from gdb with "target" command:
(gdb) target remote localhost:3333

[stnolting]

Hey @suarezvictor

OpenOCD already supports an interface to GDB using TCP port 3333
Connect from gdb with "target" command:
(gdb) target remote localhost:3333

Yes, I have seen that, but that is not what I wanted to address. Maybe my words were formulated way too vaguely 😄

The question is: How can I use the on-chip debugger to debug an actual application?
So far, I know that the executable (or to be more precisely, the *.elf file) needs to provide debug symbols so the debugger can relate the current CPU state to a specific point in the code. I'm doing research on these "low level gdb operations", but I am still a little bit overwhelmed... 😉

Do you know any good references for this?

[suarezvictor]

if you compile the .elf with debug information (i.e. -ggdb flag on gcc), gdb will interpret all
it seems the only thing you need to have ready is openocd listening on port 3333 (as it does bay default)
to me the question is already solved once you have that port listening, the rest is a matter of using existing tools, everybody will know how to do it
search on internet how to hook gdb to openocd and that's it
here is an example for eclipse IDE https://eclipse-embed-cdt.github.io/debug/openocd/

[stnolting]

here is an example for eclipse IDE https://eclipse-embed-cdt.github.io/debug/openocd/

Thanks for the reference! Now that the OCD hardware is implemented, I will start experimenting with the "software ecosystem".

[stnolting]

I have been experimenting with OpenOCD and gdb. Seems like things are not as complicated as expected 😄

However, I've tried to setup a simple "tutorial" that explains how to do a simple debugging of the sw/example/blink_led example application. The tutorial is available in project's documentation using breakpoints.

Link: https://stnolting.github.io/neorv32/#_debugging_using_the_on_chip_debugger

If you like, you can try it by yourself. 🚀
I would appreciate some feedback - as I am quite new to in-system debugging using GDB. 😉

[AWenzel83]

I just tried it, and it works, even with the mainline openOCD, since RISC-V support is available there, too. See Here (Chapter 16.10)

[stnolting]

Thank you very much for the feedback! :)

[suarezvictor]

Awesome, congrats!!

[MatejMozek]

Hi,

I am experimenting with neorv32 on a ColorLight i9 board, which comprises an Lattice ECP5 FPGA. This board features an DAP programming interface, which is directly connected to ECP5 JTAG port. Programming of FPGA works normally using ECPDAP.

In order to avoid the use of an additional FTDI based JTAG interface solely for debugging the neorv32, I tried to use the ECP5 primitive called JTAGG to connect neorv32 into JTAG chain and then use OpenOCD in similar fashion as described in the neorv32 documentation.

Table 416 in Lattice reference manual explains the JTAGG signals: There is a complete set of signals, which are connected directly to TAP controller (TCK, TMS, TDI, TDO) and there is a set of signals, which are the outputs of JTAGG component. Some outputs seem quite logical to use (JTDI, JTCK), while JTDO comes in two forms (JTDO1, JTDO2). In order to use JTDOx output, proper instruction has to be passed to the IR first, which is useless for working with OpenOCD.
I have tried to port-map JTAGG and neorv32 directly to ECP5 TAP controller pins (pin-to-pin), but I can't get OpenOCD (using cmsis-dap driver) or ECPDAP to report an additional device on the JTAG chain - they both do list the presence of ECP5 FPGA correctly.

Can you please advise on how to connect the JTAGG signals to the neorv32 interface in order to be able to list it in the JTAG chain?

[stnolting]

Hey there!

I am experimenting with neorv32 on a ColorLight i9 board, which comprises an Lattice ECP5 FPGA.

This looks like a nice FPGA board! I always wanted to play with a large Lattice device and this setup looks very good.

In order to avoid the use of an additional FTDI based JTAG interface solely for debugging the neorv32, I tried to use the ECP5 primitive called JTAGG to connect neorv32 into JTAG chain and then use OpenOCD in similar fashion as described in the neorv32 documentation.

Unfortunately, I have no experience with this FPGA family. However, Intel and Xilinx (AMD) devices also provide JTAG primitives... and in general, all these components are quite similar somehwow. But handling them is not easy (especially for the Xilinx version) and making them run with openOCD is another big issue. We had an extensive discussion about that in #479.

GitHub user @NikLeberg has added a setup for an Intel device that makes use of the internal JTAG component: https://github.com/stnolting/neorv32-setups/tree/main/quartus/on-chip-debugger-intel

Hopefully this can help you a little bit?! 🙈😅