How to start U-Boot (v2019.04 or later) with Arm® DS (DS-5) Debugger (Cyclone® V SoC / Arria® V SoC edition)

This article is an updated version of the former title "How to start U-Boot (v2019.04 or later) with the DS-5 Debugger (Cyclone^® V SoC / Arria^® V SoC edition)".

The standardized Arm tools for software integrated development environment for Altera^® SoC FPGAs have been changed from Arm^® DS-5 for SoC FPGA Edition (DS-5) to Arm^® Development Studio for SoC FPGA Edition (Arm^® DS).

Arm^® DS is the successor to DS-5, and its usability has not changed significantly. Most of the information in this article is applicable to both Arm^® DS and DS-5.

Introduction

Altera^® SoC FPGAs use the U-Boot when booting Linux, which provides a variety of features for debugging and development.

In this article, we will show you how to boot the U-Boot from Arm^® DS / DS-5 debugger targeting the Cyclone^® V SoC, starting in 2019.04.

By invoking U-Boot from Arm^® DS / DS-5, you can see from Arm^® DS / DS-5 the state of memory and registers at the time of processing, and you can apply a break for a specific process from Arm^® DS / DS-5.

Prerequisites

This article assumes that SoC EDS (SoC FPGA Embedded Development Suite) v20.1 has already been set up.

For instructions on how to setup SoC EDS v20.1, please refer to the following contents page: 
How to Install SoC FPGA Embedded Development Suite (SoC EDS) ver. 20.1

 

Reference: 
This article targets the Cyclone^® V SoC, but the same procedure can be followed for the Arria^® V SoC.

Reference: 
This article does not cover the U-Boot build procedure. Please refer to the following page to complete the build process. 
Bootloader generation flow for SoC EDS v19.1 std / v19.3 pro or later (Cyclone^® V SoC / Arria^® V SoC edition)

When running relatively recent versions of U-Boot such as v2019.xx or v2020.xx connected to the Arm^® DS (DS-5) debugger, JTAG related errors may appear and operations from the debugger may not work. Please refer to the following article when you build U-Boot. 
How to deal with JTAG related error message when starting U-Boot (v2019.04 or later) with Arm^® DS (DS-5) debugger

Reference: 
If you are using Arria^® 10 SoC, please refer to the following article page: 
How to start U-Boot (v2019.04 or later) with Arm^® DS (DS-5) Debugger (Arria^® 10 SoC edition)

 

1. Starting Arm^® DS / DS-5

1-1. For Arm^® DS

1-1-1. For Windows PC

(1) Start the following Embedded Command Shell from the Windows Start menu.

Figure 1. Start Embedded Command Shell (Windows)

(2) Execute the cmdsuite program (suite_exe) from Embedded Command Shell (example for Arm^® DS version 2023.1).

$ /cygdrive/c/Program\ Files/Arm/Development\ Studio\ 2023.1/bin/cmdsuite.exe

(3) Execute the bash program, returning to the Embedded Command Shell prompt color.

$ bash

(4) From the Embedded Command Shell, run the armds_ide & command from Embedded Command Shell to start Arm^® DS Eclipse.

$ armds_ide &

Figure 2. Startup of Arm^® DS Eclipse (Windows) 

 

1-1-2. For Linux PC

(1) When working on a Linux OS (such as Ubuntu), first start the terminal (terminal). 
Then, by executing "embedded_command_shell.sh" on the terminal, a shell environment with environment variable settings for SoC EDS will be launched.

•  
  • For SoC EDS v20.1 Pro:

$ ~/intelFPGA_pro/20.1/embedded/embedded_command_shell.sh

•  
  • For SoC EDS v20.1 Std:

$ ~/intelFPGA/20.1/embedded/embedded_command_shell.sh

(2) Run the cmdsuite program (suite_exe) from Embedded Command Shell (example for Arm^® DS version 2023.1)

$ /opt/arm/developmentstudio-2023.1/bin/suite_exec bash

(3) From Embedded Command Shell armds_ide & command from the Embedded Command Shell to start Arm^® DS Eclipse.

$ armds_ide &

Figure 3. Startup of Arm^® DS Eclipse (Linux)

1-2. For DS-5

1-2-1. For Windows PC

(1) Start the following Embedded Command Shell from the Windows Start menu.

Figure 4. Starting Embedded Command Shell (Windows)

(2) From the Embedded Command Shell, run the command eclipse & to launch DS-5 Eclipse.

$ eclipse &

Figure 5. Starting DS-5 Eclipse (Windows)

1-2-2. For Linux PC

(1) When working on a Linux OS (such as Ubuntu), first start the terminal.

(2) Then, execute "embedded_command_shell.sh" on the terminal to launch a shell environment with environment variable settings for SoC EDS.

•  
  • For SoC EDS v20.1 Pro:

$ ~/intelFPGA_pro/20.1/embedded/embedded_command_shell.sh

•  
  • For SoC EDS v20.1 Std:

$ ~/intelFPGA/20.1/embedded/embedded_command_shell.sh

(3) Run the command eclipse & to launch DS-5 Eclipse.

$ eclipse &

Figure 6. Starting DS-5 Eclipse (Linux) 

 

1-3. Selecting a Workspace and Starting Arm^® DS / DS-5

(1) After the Arm^® DS / DS-5 splash screen is displayed, the workspace selection screen is displayed.

Figure 7. Workspace Selection Screen

(2) When Arm^® DS / DS-5 is started up for the first time, the "Welcome" screen can be closed immediately. The "Welcome" screen can be closed immediately after the first startup of Arm^® DS / DS-5.

Figure 8. Eclipse screen of the workspace specified for the first time 

 

2. Creating a project

(1) Next, create an Arm^® DS / DS-5 project for U-Boot.
From the "File" menu, select "New" => "Makefile Project with Existing Code".

Figure 9. Select "Makefile Project with Existing Code"

(2) In the "New Project" window, specify the "Project Name" (cv_uboot_project in the example below) and the location of the BSP project including U-Boot in the "Existing Code Location" field. The location can be specified in a separate window by clicking the [Brouse...] button.

In the example below, the location where U-Boot for SD card boot for Cyclone^® V SoC was created on the page of the other article below (/home/<user>/cv_example.sdmmc/cv_soc_devkit_ghrd/software/bootloader) is specified.

Bootloader generation flow for SoC EDS v19.1 std / v19.3 pro or later (Cyclone^® V SoC / Arria^® V SoC edition)

Other items do not need to be edited. After specifying the location, click the [Finish] button.

Figure 10. Creating a New Project

(3) If a project (blue frame) is added to the Project Explorer as shown in the figure below, the project has been successfully created. However, the uboot.ds debug script file originally included in the project will not allow proper debugging of the U-Boot with the Arm^® DS / DS-5.

Attached in this article are sample debug script files uboot.ds and preloader.ds for v2019.04 and later versions of the U-Boot.

Please download these debug script files, drag & drop them into your project and copy them over.

Figure 11. Drag & drop uboot.ds and preloader.ds into the project and copy them over 

 

3. Debug configuration settings

(1) Configure the configuration settings for debugging.
Select "Debug Configuration" from the "Run" menu. 
Alternatively, right-click on the project in the Project Explorer and select "Debug As" => "Debug Configurations" from the menu that appears.

Figure 12. Select "Debug Configuration" from the "Run" menu

(2) When the "Debug Configurations" window as shown below is launched,

• For Arm^® DS:
  Right click on "Generic ARM C/C++ Application" and select "New Configuration".
• For DS-5:
  Right click on "DS-5 Debugger" and select "New".

This will generate a new debug configuration.

Figure 13. Creating a New Debug Configuration

Although there are many tabs in the menu, only two tabs, the "Connection" tab and the "Debugger" tab, need to be set for this operation.

 

3-1. "Connection" tab settings

"Select target" as "Intel SoC FPGA ⇒ Cyclone V SoC (Dual Core) ⇒ Bare Metal Debug ⇒ Debug Cortex-A9_0". Set all other items in the red frame according to the environment to be debugged.

Note: 
To specify the "Connection", click on the [Browse...] button to select from the list displayed in a separate window, but the target board must be connected via the FPGA download cable (USB-Blaster) and powered on beforehand.

Note: 
When using the FPGA Download Cable (USB-Blaster) in a Linux OS environment, the USB device identification rule (ID) must be registered in udev.

Reference:
3.2. Installing the FPGA Download Cable Driver on Linux • Altera FPGA Download Cable User Guide • Altera Documentation and Resources Center

In addition, you can specify any name for the newly created configuration by editing the "Name" (the blue line in the figure below).

Figure 14. "Connection" tab settings 

 

3-2. "Debugger" tab settings

Set the same settings as shown in the screen image below (red frame).

Both "Debugger Script" and "Source Search Directory" can be specified from the [Workspace...] button. 

After completing the configuration, click the [Apply] button to save the configuration. If the configuration has been renamed, the new name will be reflected in the blue box on the left side of the window when the configuration is saved.

Figure 15. "Debugger" tab settings 

 

4. Start debugging

(1) Click the [Debug] button to start debugging.

Figure 16. Click the [Debug] button

(2) If a message appears asking you to confirm switching to the Debug perspective (screen layout for debugging), click [Yes].

Figure 17. Confirmation message for switching to the Debug perspective

(3) Once the connection to the target is established, wait for the connection to be completed. Check the progress status on the log and progress bar in the "Commands" view.

Figure 18. Progress of connection with target 

 

5. Debugging connection completed

When the connection is successfully completed, it stops at the breakpoint near the beginning of the function board_init_r.

Figure 19. Connection with debugger completed

At this point, the UART terminal should display a log like the following example.

Figure 20. UART Terminal Log 

 

Summary

The above steps are all that is required to load the U-Boot from the Arm^® DS / DS-5 and start execution. Now you can operate the debugger for debugging.

If you run U-Boot to the end by using the "Continue" button (or the F8 key) in the debug control window on the Arm^® DS / DS-5 debugger, the U-Boot console will be enabled and you can perform various debugging operations by entering commands using U-Boot.

Figure 21. The U-Boot console is enabled and various commands can be used

When accessing the FPGA, be sure to open the bridge between the HPS and the FPGA. To open the bridge, use the following commands in the U-Boot.

$ bridge enable

As you can see, it is actually surprisingly easy to activate U-Boot from Arm^® DS / DS-5. 
We hope you will make use of it! 

 

Links to related articles

Please refer to the following articles related to boot loaders and U-Boot:

• Bootloader generation flow for SoC EDS v19.1 std / v19.3 pro or later (Cyclone^® V SoC / Arria^® V SoC edition)
• Bootloader generation flow for SoC EDS v19.1 Std / v19.3 Pro or later (Arria^® 10 SoC edition)
• Bootloader generation flow for SoC EDS v19.1 std / v19.3 pro or later (Appendix: Building Linux binaries - Cyclone^® V SoC / Arria^® 10 SoC edition) 

Attached Samples

This is a sample file of the U-Boot debug script for Cyclone^® V SoC / Arria^® V SoC used in this article.

• For Arm^® DS:
  preloader.ds (for Arm DS)
  uboot.ds (for Arm DS)
   
• For DS-5:
  preloader.ds (for DS-5)
  uboot.ds (for DS-5)