Debug Know-How: Ashling RiscV NIOS V debug using Command Line

#sharing #debug #niosv

Disclaimer: This article is provided as-is for educational purposes only, without warranty of any kind. Use the information at your own risk. Always verify implementations in your specific environment and consult official Altera documentation for production deployments.

Introduction

When a NIOS V design hangs and the RiscV Ashling GUI becomes unresponsive, you can still debug effectively using the command line. This guide outlines clear, step-by-step instructions for setting breakpoints and monitoring system behavior using GDB server.

Steps

1)       Open a terminal and enter:
>> niosv-shell

2)       Run the following command three times to create three terminals:
>> xterm&

• Terminal 1 is to open a port
• Terminal 2 is to control breakpoints
• Terminal 3 is to monitor output print messages

3)       TERMINAL#1: Identify the JTAGIDCODE and Start GDB Server
irst, display the connected JTAG device:
>> jtagconfig

 Then start the Ashling GDB server and note down the port number (in this case is 38791):
>> ash-riscv-gdb-server --auto-detect true --probe-type usb-blaster-2 --tap-number 1 --device 034BB0DD --core-number 0

4)       TERMINAL#2: Load the ELF file
Launch GDB:
>> riscv32-unknown-elf-gdb run.elf

Inside the GDB prompt:
>> file run.elf
>> target remote: 38791
>> load run.elf

5)       TERMINAL#3: Run JUART Terminal
Use JUART to monitor output:
>> juart-terminal -c 1 -d 1 -i 0

This will display system logs, print messages, and output triggered by breakpoints.

6)       TERMINAL#2: You may now begin debugging using standard GDB commands.
Set a breakpoint:
>> break <line number>

Continue execution until the breakpoint:
>> c

Step line-by-line
>> n

7)       Repeat Step (6) as needed - run, monitor output via JUART, examine behavior, and continue.

Tips and observations

In some cases, the system hangs only when code runs continuously. This may indicate a insufficient time-to-execute issue.

Running commands line-by-line (e.g., using `n`) adds implicit delay between operations, preventing hangs. If continuous execution hangs but step execution does not, consider adding delays such as:

>> usleep (<value>)

Start with a larger value, then gradually reduce it until the hang reappears to identify the required timing margin.

For example, the following operations in the function have been identified as the root cause of insufficient time between issuing rd_word and wr_word:

Use a large sleep value first to confirm that adding delay resolves the hang issue.
>> #define SLEEP2 10000

If the initial delay proves effective, reduce it step‑by‑step until you find the minimum acceptable value that prevents the hang.
>> #define SLEEP2 20

Conclusion

This procedure should help you debug NIOS V designs reliably even when the GUI tools fail.