How to start U-Boot (v2019.04 or later) with Arm® DS (DS-5) Debugger (Arria® 10 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 (Arria^® 10 SoC edition)".

The standardized Arm genuine tool as a software integrated development environment for Altera^® SoC FPGAs has 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 various 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 Arria^® 10 SoC, as of 2019.04.

By launching U-Boot from Arm^® DS / DS-5, you will be able to see the state of memory and registers from Arm^® DS / DS-5 as you perform operations, and you can apply breaks on specific operations 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 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 (Arria® 10 SoC edition)

When running relatively recent versions of U-Boot such as v2019.xx and 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 Cyclone^® V SoC or Arria^® V SoC, please refer to the following article: 
How to start U-Boot (v2019.04 or later) with Arm^® DS (DS-5) Debugger (Cyclone^® V SoC / Arria^® V SoC edition)

Basically, the procedure is the same as the one described in the article page for Cyclone^® V SoC / Arria ^® V SoC (above), but for Arria^® 10 SoC, please note the following points. 

Note: 
U-Boot requires configuration of the FPGA side circuitry. 
External FPGA Configuration Depending on the Enable/Disable option, the following actions should be taken beforehand. If access to the boot device (SD card, QSPI Flash, NAND Flash) for the Hard Processor System (HPS) is not working well, please enable the External FPGA Configuration option in the BSP Editor when generating the U-Boot to be debugged. FPGA Configuration option in the BSP Editor when generating the U-Boot for debugging.

• If External FPGA Configuration is enabled: 
  Please configure the FPGA side with a .sof file before starting debugging. 
   
• If External FPGA Configuration is disabled: 
  Please write the .rbf file in the proper location on the boot device in advance. 
   

1. Booting 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 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 Embedded Command Shell, select eclipse & Start 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 (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) Launch DS-5 Eclipse by entering the command 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 the U-Boot for SD card boot for Arria^® 10 SoC was created (/home/<user>/a10_example.sdmmc/a10_soc_devkit_ghrd/software/bootloader).

Bootloader generation flow for SoC EDS v19.1 Std / v19.3 Pro or later (Arria^® 10 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 and 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".

Figure 13. Creating a New Debug Configuration

Although there are many tabs in the menu, only two tabs, "Connections" and "Debugger," need to be set in this step.

3-1. "Connection" tab settings

"Select target" as "Intel SoC FPGA ⇒ Arria 10 SoC ⇒ 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 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

Furthermore, by editing the "Name" (blue line in the figure below), you can specify any name for the newly created configuration (in this example, a10_uboot_debug is specified).

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. 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

Note:
If "External FPGA Configuration" is enabled, write the .sof file at this point to complete the FPGA side configuration. FPGA Configuration" is disabled, be sure to write the .rbf file to the boot device in advance.)

(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 DS-5 and start execution. Now you can operate the debugger for debugging.

When the U-Boot is executed to the end by pressing the "Continue" button (or F8 key) on the debug control window of the Arm^® DS / DS-5 debugger, the console of the U-Boot is enabled and various debugging by command input using the U-Boot The U-Boot console is enabled, and various debugging operations can be performed by inputting commands using U-Boot.

Finally, a list of U-Boot commands (in HELP view) is shown in the figure below. Please refer to the available command operations.

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

$ bridge enable

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

Figure 21. List of U-Boot commands (HELP display) 

 

Links to related articles

Please refer to the following articles related to the boot loader 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 Arria^® 10 SoC used in this article. 
After downloading, please rename the files to preloader.ds and uboot.ds before use.

• 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)