Introduction
In 2022, the RiscFree IDE for Intel® FPGAs, a software integration development environment and debugger for the Nios® V processor, were released for free. The RiscFree IDE not only supports the Nios® V processor but also includes debugging capabilities for Cyclone® V SoC and Intel® Arria® 10 SoC, which incorporate Arm Processors as hard macros. However, the documentation barely mentioned these capabilities as of 2022.
Here, we would like to share our experience using the RiscFree IDE as a debugger for the Arm Processor on the Cyclone® V SoC, including downloading and debugging the bootloader1.
For our setup, we used the Terasic DE10-Nano board, and the Host PC running the debugger was using Windows.
RiscFree IDE for Intel® FPGAs
The RiscFree IDE for Intel® FPGAs is a tool co-developed by Ashling (a company specializing in embedded processor development tools) and Intel. It is primarily an Eclipse IDE-based tool offered for software development and debugging of the Nios® V processor, which is based on the RISC-V architecture. The RiscFree IDE features its own debug server, allowing for heterogeneous and multicore debugging of both Nios® V processors and Arm CPUs. However, in this instance, we will use OpenOCD as the debug server, similar to debugging the Nios® V processor, to debug the ARM Cortex-A9 processor on the Cyclone® V SoC2.
For more about OpenOCD, refer to my brief explanation in the article About OpenOCD. You could say that this is a version of doing the command-line-based debugging work described in that article, but using the GUI of RiscFree IDE.
Tools Installation
First, it is necessary to have one of the Intel® Quartus® Prime Pro/Standard/Lite edition software installed. The version should be v22.2 or later for the Pro edition and v22.1 or later for the Standard/Lite editions.3
With the Intel® Quartus® Prime Pro edition software, it's possible to use RiscFree just with the installation of the Intel® Quartus® Prime Pro Programmer.
There are different installers for the RiscFree IDE for Pro and Standard editions. Please use the RiscFree IDE installer available under the "Additional Software" tab on the download page of the Intel® Quartus® Prime software edition you are using. If you're using the Intel® Quartus® Prime Lite edition software, you can use the RiscFree IDE downloaded from the Intel® Quartus® Prime Standard edition software page. Regardless of the edition used, the tools necessary for the debugging work that will be conducted (OpenOCD and RiscFree IDE) are available for free.
After installing the Intel® Quartus® Prime software, please install the RiscFree IDE. When installing the RiscFree IDE, you will need to specify the install folder of the Intel® Quartus® Prime software.
Furthermore, it's assumed that an environment capable of building boot code is available. Since the bootloader is based on U-Boot, a Linux environment (including Virtual Machines) is required.
Example: Downloading the Bootloader
First, launch the RiscFree IDE. On Windows, it can be started from the Intel FPGA folder registered in the Start menu. Initially, it will ask for a workspace folder, so specify an appropriate working folder.
Debug Configurations Settings
Here, assuming that the code has already been built, we will proceed directly to setting up debugging. From the menu, select Run -> Debug configurations...
The following screen will appear.
In the list on the left, many debugging modes are displayed, but here we double-click (select) "GDB OpenOCD Debugging" (the first key point).
This action opens a screen to create a new debugging configuration using OpenOCD.
Below, we will go through the settings in each tab of the Debug Configurations.
Main Tab
In the "Name:" field at the top right, enter a suitable configuration name. Here, we are using preloader_debug. Also, in the "C/C++ Application:" field, enter the path to the elf file you want to debug by pressing the Browse... button4. In this example, we specify a separately created bootloader elf file (......\spl\u-boot-spl). Note that the ......\spl\ folder must also contain the u-boot-spl-dtb.bin file generated alongside u-boot-spl.
Debugger Tab
Next, click the Debugger tab. Change the default settings as shown below.
- For OpenOCD's "Executable path:", specify the openocd.exe included with the Intel® Quartus® Prime software
- Append to OpenOCD's "Config options:" as shown in the figure
- For GDB Client's "Executable name:", specify the arm gdb included with RiscFree6
- Append to GDB Client's "Commands:" as shown in the figure
To launch OpenOCD, the "Config options:" must include the specification ```-f ``` (the second key point). In the example above, we have specified a file named cyclone5_client.cfg located in the workspace folder. For the contents of the configuration file, please refer to About OpenOCD. The same cyclone5_client.cfg file from this article is used here5. For convenience, it is also reposted below.
The cyclone5_client.cfg file details:
###############################################################
# Point: Specify aji_client as the driver
adapter driver aji_client
###############################################################
# Chip name: Can be changed to any name (we'll use cvsoc)
set _CHIPNAME cvsoc
###############################################################
# HPS TAP(Test Access Port)/DAP(Debug Access Port) JTAG ID
set _DAP_TAPID 0x4ba00477
###############################################################
# Declare HPS DAP as a JTAG TAP(Test Access Port)
jtag newtap $_CHIPNAME cpu -irlen 4 -expected-id $_DAP_TAPID
###############################################################
# Declare that the HPS's TAP is an ARM DAP(Debug Access Port).
# Do this when the target is ARMv6-M, ARMv7, or ARMv8
dap create $_CHIPNAME.dap -chain-position $_CHIPNAME.cpu
###############################################################
# The target for gdb debugger operation is core0 of HPS DAP
target create $_CHIPNAME.cpu.0 cortex_a -dap $_CHIPNAME.dap -coreid 0 -dbgbase 0x80110000
Startup Tab
Next, click the Startup tab and change the default settings as shown below:
- Uncheck the "Initial Reset" checkbox.
- Add "delete breakpoints" to the "Initialization command".
- Uncheck the "Enable Arm semihosting" checkbox, as the code being debugged does not use the semihosting feature.
- For "Load symbols", select "Use file" and specify u-boot-spl (the code to be debugged).
- Uncheck the "Load executable" checkbox (since the binary code with the device tree is loaded in the Run/Restart Commands, this is not necessary).
- Uncheck the "Pre-run/Restart reset" checkbox.
- Add restore u-boot-spl-dtb.bin binary 0xffff0000 and set $pc=0xffff0000 to "Run/Restart Commands".
- Set "spl_boot_device" in the "Set breakpoint at:" field (to stop u-boot-spl here after the debugger starts).
Recent versions of u-boot-spl (2020.xx onwards, versions that generate a u-boot-spl-dtb.bin file upon build) require the memory to load an image (u-boot-spl-dtb.bin) with a device tree blob (dtb) appended at the end of the program code, which is done in "Run/Restart Commands". Also, because the code is loaded as a binary file rather than an elf, the execution start address is not set automatically, hence, the command sets $pc.
The bootloader u-boot-spl is designed to complete all necessary initializations for the startup of HPS by the time it executes up to spl_boot_device, which is why "spl_boot_device" is specified in "Set breakpoint at:". The spl_boot_device function is executed in the final stage of the u-boot-spl(bootloader), serving as the entry point to the flow that loads the next binary (normally the full-featured U-Boot code) into SDRAM and transfers execution to it.
Currently, OpenOCD does not seem to support the reset command with the Intel® FPGA Download Cable (formerly known as USB Blaster cable), hence the "Initial Reset" and "Pre-run/Restart reset" checkboxes are turned off. (Leaving them on displays error messages in
SVD Path Tab
Finally, click on the SVD Path tab (the settings for the Source and Common tabs can remain at their defaults). Here, load the .svd file for the Cyclone® V SoC that is provided in the RiscFree installation folder. This file defines the Register Map for the peripherals of the Cyclone® V SoC, making it easier to access the peripheral registers (more on this later).
Download & Execution
With all the settings configured, let’s proceed with debugging (downloading & execution).
Ensure the DE10-nano board is connected to your PC via the USB port for the Intel® FPGA Download Cable (formerly USB Blaster cable), with the SD card removed and the board powered on.
Click the "Apply" button at the bottom right to save your settings, then click the "Debug" button.
After clicking, if a dialog box asking if you want to switch to the Debug perspective appears, press OK. You will then see messages from OpenOCD in the Console, indicating that it is connecting to the DE10-nano board.
After a short delay, more messages from OpenOCD will appear in the Console, indicating that the connection is complete, and the following screen will be displayed.
This screen shows that the u-boot-spl (bootloader) has been downloaded and execution has begun from its start address, pausing at the breakpoint set at the spl_boot_device function, as seen in the window for spl_gen5.c.
If the DE10-nano board’s serial USB port is connected to the PC and a serial terminal is open, you will see the following output:
This confirms that the bootloader (u-boot-spl) has been successfully downloaded and executed.
Peripheral Register Access
Next, let's use the Peripherals window to check the register access of peripheral circuits. (It is assumed that the debugger is connected to the target and the CPU execution has stopped at the beginning of spl_boot_device.)
If the Peripherals window is not displayed, select Window -> Show view -> Peripherals from the menu. This should display the Peripherals as shown below.
Setting the svd file in Debug Configurations' SVD path allows easy access to each peripheral of the HPS. Let's take a look at the state of WatchDogTimer0 for example. Scroll down in the Peripherals window, find l4wd0, and check the checkbox next to it.
In the Memory window, click on the ">" next to wdt_cr of l4wd0 to view the bits of the wdt_cr register.
The wdt_cr register's wdt_en (bit-0) is set to 0x1:enabled, indicating that the WatchDogTimer is currently active.
Clicking the Step over button in the debugger controls and then looking at the state of l4wd0,
shows that the wdt_ccvr register is highlighted in yellow, indicating a change in value (counting down from 0x01F542CD to 0x01F542BE).
To stop l4wd0, it is possible by issuing a reset to l4wd0 from the reset manager (rstmgr) by setting the bit-6 of the rstmgr's permodrst register to 1. This operation can easily be done using the Peripherals/Memory window, so please give it a try (change the Value of bit-6 in the rstmgr's permodrst register).
Additionally, though not introduced here, normal operations such as displaying and accessing in Memory, Variables, Expressions, Registers windows frequently used in debugging work as expected.
Notes & Tips
Finally, here is a list of some noteworthy points and tips:
- Command inputs for gdb can be made from the Debugger Console Window. Although no input prompt appears, you can click on the Debugger Console and enter commands from the keyboard. (There are scenarios where entering commands directly is more convenient, such as setting breakpoints with hb, thb, etc.)
- For setting breakpoints through the GUI, it is recommended to use hardware breakpoints. Hardware breakpoints tend to work more reliably.
- Messages from OpenOCD are output to standard error, so they appear in red in the Console. If the red text is bothersome, you can change the Standard Error text color to something more subdued from the Console's Preference settings (accessible by right-clicking inside the Console window).
- Sometimes, the debug connection may drop if the Disassembly window is displayed. It might be better to display the Disassembly window only when necessary.
- Since OpenOCD cannot reset the Arm processor, depending on the previous state of the CPU core, you may need to use the board's reset switch or power ON/OFF to reset at the start of debugging.
Conclusion
The RiscFree IDE is bundled with the Intel® Quartus® Prime software as an integrated software development environment for the Nios® V processor. We have attempted to **use the RiscFree IDE debugger for debugging the Arm processor of SoC FPGAs**.
Thanks to the OpenOCD server, various debugging tasks can now be performed without any problems through the GUI. While there are differences in responsiveness and functionality compared to paid debuggers, it serves as a valuable tool for SoC FPGA debugging that can be used freely and easily.
References
Notices & Disclaimers
Intel technologies may require enabled hardware, software, or service activation. No product or component can be absolutely secure. Your costs and results may vary.
© Intel Corporation. Intel, the Intel logo, and other Intel marks are trademarks of Intel Corporation or its subsidiaries. Other names and brands may be claimed as the property of others.
For SoC FPGAs, the U-Boot spl (secondary program loader) is used as the standard bootloader (previously it was referred to as the preloader).
In tests, debugging with OpenOCD, as introduced here, worked as expected in versions v22.3Pro or v22.1Std.
With the Intel® Quartus® Prime Pro edition software, it is possible to use RiscFree just with the installation of the Intel® Quartus® Prime Pro Programmer.
Note that using variables (using $ in the description) in this specification will cause an error when launching the debugger.
As you can tell from the last line of this .cfg file, this configuration allows debugging access to core0 only. While it seems possible to connect to other cores, it has not been tested.
If you are using the latest Intel® Quartus® Prime software version 24.1 as of the time of writing, please use aarch64 gdb client.
Link Copied
