SoCEDSGettingStarted

From Intel FPGA Wiki
Jump to: navigation, search

Contents

Introduction

This page contains a set of getting started guides to help users with getting started with Altera SoC EDS.

The currently covered version of SoC EDS is 16.1b196.

Getting Started with Board Setup

This section presents how to setup the Altera SoC Development board in order to use it with the getting started guides from this page.

Cyclone V Board (rev.E) Setup

Dual in-line package (DIP) Switch Settings:

Switch Setting
SW1 all switches OFF
SW2 all switches OFF
SW3 ON-OFF-OFF-OFF-ON-ON
SW4 OFF-OFF-ON-ON

Jumper Settings:

Switch Description Setting
J5 9V Open
J6 JTAG_HPS_SEL Shorted
J7 JTAG_SEL Shorted
J9 UART Signals Open
J13 OSC1_CLK_SEL Shorted
J16 JTAG_MIC_SEL Open
J26 CLKSEL0 2-3 Shorted
J27 CLKSEL1 2-3 Shorted
J28 BOOTSEL0 1-2 Shorted
J29 BOOTSEL1 2-3 Shorted
J30 BOOTSEL2 1-2 Shorted
J31 SPI_I2C Open

External Connections:

  • External 19V power supply connected to J22 – DC Input
  • Mini USB cable connected from host PC to J37 – Altera USB Blaster II connector. This is used for connecting the host PC to the board for debugging purposes.
  • Mini USB cable connected from host PC to J8 – UART USB connector. This is used for exporting the UART interface to the host PC.
  • Ethernet cable from connector J2 to local network. This is used if Linux network connectivity is desired.

Arria V Board (rev. B) Setup

Arria 10 Board (rev. C) Setup

Memory Cards:

  • Make sure DDR4 memory card is installed
  • Make sure SD/MMC boot card is installed

Dip Switch Settings:

Switch Setting
SW1 all OFF
SW2 all OFF
SW3 OFF-OFF-ON-ON-ON-OFF-OFF-OFF
SW4 all OFF

Jumper Settings:

  • Place jumpers J16, J17,J32:9-10,J42:9-10
  • Leave all other jumpers unplaced

External Connections:

  • Make sure SW5 (power) is OFF
  • Connect Micro USB cable from J22 to Host PC - for JTAG debugging
  • Connect Mini USB cable from J10 to Host PC - for serial terminal connection
  • Connect external 12V power supply to J36 (input power) connector

Getting Started with Running the Tools

This section presents how to run some of the tools provided with the SoC EDS.

Starting the Embedded Command Shell

The Embedded Command Shell is an utility that allows all the tools provided with the SoC EDS to be conveniently available from the command line interface.

The Embedded Command Shell can be started by using the following instructions:

  • On Windows, go to Start > All Programs > Altera > SoC Embedded Design Suite > Embedded Command Shell,

Embedded-command-shell-windows.png

  • On Linux, run the script <SoC EDS installation directory>/embedded_command_shell.sh

Embedded-command-shell-linux.png

Starting the ARM DS-5 AE Eclipse

This section presents how to start the ARM DS-5 AE Eclipse environment.

The required steps are:

1. Start an Embedded Command Shell - click here for instructions

2. Start the ARM DS-5 AE Eclipse by running the command eclipse in the Embedded Command Shell.

3. Select a Workspace when asked to (you will need to have write permission to that folder) and press OK.

Eclipse-select-workspace.png

4. Eclipse will be started. The Welcome window allows access to useful getting started materials. If closed, the Welcome window can be re-opened by going to Help > Welcome to DS-5.

Eclipse-started.png

Getting Started with the Second Stage Bootloader

The Second Stage Bootloader (SSBL) is an essential tool for Altera SoC devices. It typically performs the low-level initialization, brings up SDRAM memory, loads the next boot stage from flash to SDRAM and executes it. On Cyclone V and Arria V SoC Devices the SSBL is also called "Preloader", while on Arria 10 SoC devices the SSBL is also called "Bootloader".

This section presents examples on how to generate and compile the SSBL for the Altera SoC Devices.

Generating and Compiling Cyclone V Preloader

This section presents an example of how to generate and compile the Preloader for the Cyclone V SoC Golden Hardware Reference Design (GHRD) that is provided with SoC EDS. The process for Arria V devices is very similar.

The Preloader is already delivered as part of the GHRD in the <SoC EDS installation directory>/examples/hardware/cv_soc_devkit_ghrd/software/preloader folder. In this example, you will re-create the Preloader in the folder <SoC EDS installation directory>/examples/hardware/cv_soc_devkit_ghrd/software/spl_bsp

The following pre-requisites are necessary in order to run the steps from this guide:

  • Host PC running Windows or Linux
  • SoC EDS 16.1b196+

The screenshots presented in this section were created using the Windows version of SoC EDS, but the example can be run in a very similar way on a Linux host PC.

The steps required to generate and build the default Preloader are:

1. Make sure the hardware design is compiled, so that the hardware-software handoff information is up to date. In our case this is already done, since the GHRD that is delivered with SoC EDS is already compiled.

2. Start an Embedded Command Shell click here for instructions

3. Start the BSP Editor by typing bsp-editor in the Embedded Command Shell.

4. Go to File > New HPS BSP .... This will open the New BSP dialog box.

Gs-preloader-1.png

5. In the New BSP dialog box, click the ... button and browse to the <SoCEDS folder>\examples\hardware\cv_soc_devkit_ghrd\hps_isw_handoff\soc_system_hps_0 folder which contains the hardware-software handoff folder. The rest of the settings in the New BSP Dialog box will be filled automatically with their default values.

Gs-preloader-3.png

6. Click OK to close the New BSP window. This will bring you back to the main BSP Editor window.

7. In the BSP Editor window the user can configure the Preloader. For this exercise, leave all settings at their default values, except making sure that SDRAM_SCRUBBING is checked.

Gs-preloader-5.png

8. Click Generate in the BSP Editor window to generate the Preloader files.

9. Click Exit in the BSP Editor window box to exit the application.

10. In the Embedded Command Shell, execute the following commands to build the Preloader

cd <SoC EDS installation directory>\examples\hardware\cv_soc_devkit_ghrd\software\spl_bsp
make 

11. The Preloader will be compiled ready to be used in the above folder.

Gs-preloader-6.png

Some of the more relevant files that are created:

File Description
preloader-mkpimage.bin Preloader with the proper header to be loaded by BootROM
uboot-socfpga\spl\u-boot-spl Preloader ELF file, to be used for debugging purposes

Generating and Compiling Arria 10 Bootloader

This section presents how to generate and compile the two available bootloader options for A10:

  • U-Boot Bootloader
  • UEFI Bootloader

Generating and Compiling Arria 10 U-Boot

This section presents an example of how to generate and compile the Bootloader for the Arria 10 SoC Golden Hardware Reference Design (GHRD) that is provided with SoC EDS.

The U-Bootis already delivered as part of the GHRD in the <SoC EDS installation directory>/examples/hardware/a10_soc_devkit_ghrd/software/bootloader folder. In this example, you will re-create the Bootloader in the folder <SoC EDS installation directory>/examples/hardware/a10_soc_devkit_ghrd/software/uboot_bsp

The following pre-requisites are necessary in order to run the steps from this guide:

  • Host PC running Linux or Windows
  • SoC EDS 16.1b196+

Note: U-Boot compilation is only supported on Linux host PCs. For both Windows and Linux, precompiled versions of U-Boot are provided, so this is not a limitation unless the user wants to edit the U-Boot source code, in which case a Linux host platform is needed.

The steps required to generate and build the default Bootloader are:

1. Make sure the hardware design is compiled, so that the hardware-software handoff information is up to date. In our case this is already done, since the GHRD that is delivered with SoC EDS is already compiled.

2. Start an Embedded Command Shell click here for instructions

3. Start the BSP Editor by running the command 'bsp-editor' in the Embedded Command Shell.

4. Go to File > New HPS BSP .... This will open the New BSP dialog box.

Gs-bootloader-1.png

5. In the New BSP dialog box, click the ... button and browse to the <SoCEDS folder>\examples\hardware\a10_soc_devkit_ghrd\hps_isw_handoff folder which contains the hardware-software handoff folder. Select the Operating System to be U-Boot Bootloader (Arria 10 HPS). The rest of the settings in the New BSP Dialog box will be filled automatically with their default values.

Gs-bootloader-2.png

6. Click OK to close the New BSP window. This will bring you back to the main BSP Editor window.

7. In the BSP Editor window the user can configure the Bootloader. For this exercise, leave all settings at their default values, except editing the rbf file names to match the ones needed already included with the precompiled GHRD:

Gs-bootloader-3.png

8. Click Generate in the BSP Editor window to generate the Bootloader files.

9. Click Exit in the BSP Editor window box to exit the application.

10. In the Embedded Command Shell, execute the following commands to build the Bootloader.

cd <SoC EDS installation directory<\examples\hardware\a10_soc_devkit_ghrd\software\uboot_bsp
make 

11. The U-Boot will be compiled ready to be used in the above folder.

Gs-bootloader-4.png

Some of the more relevant files that are created:

File Description
uboot_w_dtb-mkpimage.bin Combined U-Boot and U-Boot Device Tree Image, with the BootROM required header added
uboot-socfpga/u-boot Bootloader ELF file, to be used for debugging purposes
devicetree.dtb U-Boot Device Tree Binary, to be used for debugging purposes

Generating and Compiling Arria 10 UEFI

This section presents an example of how to generate and compile the UEFI Bootloader for the Arria 10 SoC Golden Hardware Reference Design (GHRD) that is provided with SoC EDS.

The following pre-requisites are necessary in order to run the steps from this guide:

  • Host PC running Linux or Windows
  • SoC EDS 16.1b196+

Note: U-Boot compilation is only supported on Linux host PCs. For both Windows and Linux, precompiled versions of U-Boot are provided, so this is not a limitation unless the user wants to edit the U-Boot source code, in which case a Linux host platform is needed.

The steps required to generate and build the UEFI are:

1. Make sure the hardware design is compiled, so that the hardware-software handoff information is up to date. In our case this is already done, since the GHRD that is delivered with SoC EDS is already compiled.

2. Start an Embedded Command Shell click here for instructions

3. Start the BSP Editor by typing bsp-editor in the Embedded Command Shell.

4. Go to File > New HPS BSP .... This will open the New BSP dialog box.

Gs-bootloader-1.png

5. In the New BSP dialog box, click the ... button and browse to the <SoCEDS folder>\examples\hardware\a10_soc_devkit_ghrd\hps_isw_handoff folder which contains the hardware-software handoff folder.

Select the Operating System to be UEFI Bootloader (Arria 10 HPS). The rest of the settings in the New BSP Dialog box will be filled automatically with their default values.

Gs-uefi-2.png

6. Click OK to close the New BSP window. This will bring you back to the main BSP Editor window.

7. In the BSP Editor window the user can configure the UEFI. For this exercise, leave all settings at their default values, except editing the rbf file names to match the ones needed already included with the precompiled GHRD:

Gs-uefi-3.png


8. Click Generate in the BSP Editor window to generate the UEFI Bootloader files.

9. Click Exit in the BSP Editor window box to exit the application.

10. In the Embedded Command Shell, execute the following commands to build the UEFI Bootloader.

cd <SoC EDS installation directory<\examples\hardware\a10_soc_devkit_ghrd\software\uefi_bsp
make 

11. The UEFI will be compiled in the above folder.

Gs-uefi-4.png

Some of the more relevant files that are created:

File Description
uefi-socfpga/Build/PEI.ROM Combined UEFI and UEFI Device Tree Image, with the BootROM required header added. Equivalent to uboot_w_dtb-mkpimage.bin.
devicetree.dtb UEFI Device Tree Binary, to be used for debugging purposes

Configuring FPGA from Cyclone V Preloader

The Cyclone V Preloader has the ability to configure the FPGA by using configuration data stored in one of the following two locations:

  • specific address in QSPI Flash
  • specific file name on a SD/MMC FAT Partition

In order to configure the FPGA, an RBF file needs to be used. The RBF file is obtained by converting a SOF file to RBF by using the Quartus II Programmer. Note: The options for generating the RBF file need to match the MSEL settings on the board.

RBF File Stored in QSPI Flash Memory

The following steps are required to enable the Preloader to configure the FPGA from an RBF file stored in QSPI Flash memory:

1. Configure the Preloader load the next boot stage from QSPI (Check BOOT_FROM_QSPI and uncheck the other BOOT_FROM options).

2. Generate Preloader.

3. Compile Preloader, to make sure all the source code is available.

4. Modify file <bsp directory>/uboot-socfpga/include/configs/socfpga_common.h to have the macro CONFIG_SPL_FPGA_LOAD defined. It is undefined by default.

5. If needed, edit the file <bsp directory>/uboot-socfpga/include/configs/socfpga_common.h to modify the CONFIG_SPL_FPGA_QSPI_ADDR macro to select a different location for the RBF data in flash.

6. Re-compile the Preloader and flash it to QSPI.

7. Wrap the RBF file with the mkimage header. This is used by the Preloader to determine the RBF file size. This can be achieved by using a command similar with the following:

mkimage -A arm -T standalone -C none -a 0 -e 0 -n "fpga image" -d <file.rbf> <file.img> 

8. Program the wrapped RBF file to QSPI at the address CONFIG_SPL_FPGA_QSPI_ADDR.

9. Set up MSEL accordingly and boot board.

RBF File Stored on SD/MMC Card

The following steps are required to enable the Preloader to configure the FPGA from an RBF file stored on SD/MMC card:

1. Configure the Preloader load the next boot stage from SD/MMC (check BOOT_FROM_SDMMC and uncheck the other BOOT_FROM options).

2. Enable Preloader FAT Support (check FAT_SUPPORT).

3. Edit FAT_BOOT_PARTITION if necessary (default is "1").

4. Edit the FAT_LOAD_PAYLOAD_NAME if necessary (default is "u-boot.img").

5. Compile Preloader to make sure all the source code is available.

6. Modify file <bsp directory>/uboot-socfpga/include/configs/socfpga_common.h to have the macro CONFIG_SPL_FPGA_LOAD defined. It is undefined by default.

7. If needed, modify file <bsp directory>/uboot-socfpga/include/configs/socfpga_common.h to change the macro CONFIG_SPL_FPGA_FAT_NAME (the default is "fpga.rbf").

8. Re-compile the Preloader and write it to the SD card.

9. Write the RBF file to the selected FAT partition on the SD Card and using the selected file name.

10.Set up MSEL accordingly and boot board.

Getting Started with Basic Baremetal Development

This section demonstrates importing, compiling and debugging the Hello World bare-metal example application provided as part of SoC EDS.

Pre-requisites:

  • Altera SoC Development Board (Cyclone V, Arria V or Arria 10)
  • Host PC running Windows or Linux
  • SoC EDS 16.1b196+

The screen snapshots and commands presented in this section were created using the Windows version of SoC EDS, but the example can be run in a very similar way on a Linux host PC.

Note: Make sure that Linux (or another OS) is not running on the board prior to doing this example. An OS can interfere with the feature of downloading and debugging bare-metal applications.

Sample Application Overview

The provided sample application prints a “Hello” message on the debugger console, by using semihosting. This way no pins are used and all communication happens through JTAG. The application is located in the On-Chip RAM, and therefore does not require the SDRAM memory on the board to be configured.

This application can run on any board supporting the SoC device because of its simplicity, and it does not require pins or external resources to be configured. Only 64KB of OCRAM is used, so the application is compatible with Cyclone V, Arria V and Arria 10.

Importing the Sample Application

1. Start Eclipse - click here for instructions

2. Go to File > Import. The Import dialog box appears.

3. In the Import dialog box, select General > Existing Projects into Workspace and click Next. This will open the Import Projects dialog box

Eclipse-import-existing-project.png

4. In the Import Projects dialog box, select the Select Archive File option.

5. Click Browse, then navigate to <SoC EDS installation directory>\embedded\examples\software\, select the file Altera-SoCFPGA-HelloWorld-Baremetal-GNU.tar.gz and click Open.

Eclipse-import-baremetal-hello.png

6. Click Finish. The project is imported. The project files are displayed in the Project Explorer panel.

Eclipse-baremetal-hello-imported.png

Compiling the Sample Application

1. To compile the application, select the project in Project Explorer.

2. Select Project > Build Project.

3. The project compiles and the Project Explorer shows the newly created hello.axf executable file as shown in the figure below. The Console dialog box shows the commands and responses that were executed.

Eclipse-baremetal-hello-compiled.png

Debugging the Sample Application

1. Setup the board as described in the Board Setup section and power it up. Make sure Linux or another OS is not booted, which can interfere with baremetal debugging.

2. Select Run > Debug Configurations.. to access the launch configurations. The sample project comes with a pre-configured launcher that allows the application to be run on the board.

3. In the Debug Configurations dialog box, on the left panel, select DS-5 Debugger > Altera-SoCFPGAHelloWorld-Baremetal-Debug.

4. By default, the launcher assumes the Cyclone V as a target:

Debug-baremetal-cyclone-target.png

You can change the target to match your board, if needed:

  • Cyclone V: Altera > Cyclone V SoC (Dual Core) > Bare Metal Debug > Debug Cortex-A9_0
  • For Arria V: Altera > Arria V SoC > Bare Metal Debug > Debug Cortex-A9_0
  • For Arria 10: Altera > Arria 10 SoC > Bare Metal Debug > Debug Cortex-A9_0

5. Make sure the Target Connection is selected as USB-Blaster.

6. Click the Browse button in the Bare Metal Debug Connection and select the desired USB Blaster and click OK.

Eclipse-select-usb-blaster.png

7. Click the Debug button from the bottom of the Debug Configurations dialog box. 8. Eclipse will ask whether to switch to Debug Perspective. Click Yes to accept it.

Eclipse-switch-debug-perspective.png

9. The debugger downloads the application on the board through JTAG, enables semi-hosting using the provided script, and runs the application until the PC reaches the main function. At this stage, all the debugging features of DS-5 can be used: viewing and editing registers and variables, looking at the disassembly code.

Eclipse-baremetal-started.png

10. Click Continue green button (or press F8) to run the application. It displays the hello message in the Application Console.

Eclipse-baremetal-done.png]

11. Click Disconnect from Target button to close the debugging session.

Getting Started with HwLibs Baremetal Development

This section presents how to get started with bare-metal development, demonstrating the following:

  • Importing the sample application
  • Compiling the sample application
  • Configuring the FPGA fabric
  • Viewing peripheral registers
  • Performing tracing
  • Performing cross-triggering

The following pre-requisites are necessarys:

  • CV, AV or A10 SoC Development Kit
  • Host PC running Linux or Windows - the screenshots were taken from a Linux host, but Windows operation is similar
  • SoC EDS 16.1b196+

Note that the detailed instructions and screnshots in this section were taken on a Linux host machine, using the Cyclone V, ARMCC based example. All the other variants of the sample application (targeting AV, A10 boards and also GCC compiler) will be usable in a very similar manner on both Linux and Windows host machines.

Sample Application Overview

Sample application projects are provided for all supported platforms: Cyclone V SoC, Arria V SoC and Arria 10 SoC, each in two different versions: targeting ARMCC and GCC compilers.

The table below contains the links for all the sample application projects:

Device Compiler Example
CV ARMCC File:SoCFPGA-GettingStarted-CV-ARMCC.tar.gz
CV GCC File:SoCFPGA-GettingStarted-CV-GCC.tar.gz
AV ARMCC File:SoCFPGA-GettingStarted-AV-ARMCC.tar.gz
AV GCC File:SoCFPGA-GettingStarted-AV-GCC.tar.gz
A10 ARMCC File:SoCFPGA-GettingStarted-A10-ARMCC.tar.gz
A10 GCC File:SoCFPGA-GettingStarted-A10-GCC.tar.gz

The following diagram shows an overview of the HPS and FPGA hardware components used by the sample application:

Baremetal-app-overview.png

The sample application is using the GHRD (Golden Hardware Reference Design) that is included with SoC EDS and demonstrates the following:

  • HPS SDRAM
  • HPS MMU and Caches
  • HPS timers
  • HPS Interrupts
  • FPGA-to-HPS bridge
  • FPGA IP: SysId, PIO (used by Dip Switches, Push Buttons, LEDs)
  • FPGA interrupts

The sample application source code is common between all projects, with only a few ifdef statements used. This was made possible by the following:

  • The SoCs are similar
  • The HwLibs APIs are similar
  • The GHRDs (Golden Hardware Reference Designs) are similar
  • The "system.h" file was automatically generated with "sopc-create-header-files" and contains the addresses of all the FPGA IPs

The sample application flow is:

  • Set up the system: MMU, Caches, Timer, FPGA2HPS bridge
  • Set up the FPGA IP for push buttons: generate interrupt on state change
  • Read and display the SysID id and timestamp parameters
  • Blinks the FPGA LEDs 0..3 with a frequency and direction that can be changed by pressing the FPGA push-buttons 0 & 1.
  • Pushing and holding down FPGA push buttons 0 & 1 terminates the application.

Since the sample application communicates with IP in the FPGA fabric, we need to first configure FPGA before running the application. Also, in order to have the SDRAM configured, and the HPS peripherals initialized properly, we need to run the Preloader (or Bootloader) first.

Import the Sample Application

1. Start an Embedded Command Shell

2. Start DS-5 by running "eclipse&" command from the Embedded Command Shell

3. In Eclipse, to to File > Import...

Bmgs-eclipse-import-project.png

4. Select General > Existing Projects into Workspace and click Next

Bmgs-import-existing-project.png

5. Select Select Archive and click on Browse

Bmgs-import-archive.png

6. Select the desired project archive and click OK

Bmgs-browse-import-archive.png

7. Click OK

Bmgs-import-finish.png

8. The project will be imported and displayed in the Project Explorer

Bmgs project imported.png

The project contains the following:

File Description
.project C project settings file
system.h Addresses of all FPGA IPs accessible by ARM
src/main.c Main application file
src/alt_pt.c MMU page table source
src/alt_pt.h MMU page table header
src/pio.c FPGA PIO driver source
src/pio.h FPGA PIO driver header
src/sysid.c FPGA SysId driver source
src/sysid.h FPGA SysId driver header
cv-sdram.scat Linker script
hwlibs/ Hardware Libs source code folder
SoCFPGA-GettingStarted-CV-ARMCC-Configure-FPGA.launch Eclipse external tool launcher for configuring FPGA
SoCFPGA-GettingStarted-CV-ARMCC-Create-SystemH.launch Eclipse external tool launcher for re-generating system.h
SoCFPGA-GettingStarted-CV-ARMCC.launch Eclipse debug launcher for the application
SoCFPGA-GettingStarted-CV-ARMCC-Run-Bootloader.launch Eclipse debug launcher for the bootloader

Build the Sample Application

1. In Eclipse, go to Project > Build Project

Bmgs build project.png

2. The project will be building. Note that it may take a few minutes if you are running on Windows, and have a virus scanner configured to aggressively scan all opened files.

Bmgs project building.png

3. The project will be built, with a summary of executable image memory used being displayed, and also the duration of the build process.

Bmgs project built.png

The file Debug/SoCFPGA-GettingStarted-CV-ARMCC.axf now contains the application executable.

Configure FPGA

Since the bare-metal application uses IP in the FPGA fabric, we need to first configure the FPGA before we are able to run the application. This section uses Eclipse and Quartus Programmer to configure FPGA, but there are other ways to do it, such as using an external FPGA configuration device, or by using HPS itself.

1. In Eclipse, go to Run > External Tools > External Tool Configurations...

Bmgs external tools configs.png

2. Under Program select SoCFPGA-GettingStarted-CV-ARMCC-Configure-FPGA. You will be able to see the tool that is being called, and its parameters. Click on Run.

Bmgs ext tools config fpga.png

3. After a few seconds, the FPGA is configured, and the console with display the status message of the programmer

Bmgs fpga configured.png

Run Bootloader

In order to have the SDRAM configured, and the HPS peripherals initialized properly, we need to run the Preloader (or Bootloader on A10 ) first.

Typically the Bootloader/Preloader are automatically fetched and invoked by BootROM at boot time, but, for development purposes, this section presents how to run the Bootloader using the DS-5 debugger.

1. In Eclipse, go to Run > Debug Configurations

Bmgs debug configurations.png

2. In the Debug Configurations window, on the left pane, go select DS-5 Debugger > SoCFPGA-GettingStarted-CV-ARMCC-Run-Bootloader and click on Browse button

Bmgs bootloader debug config.png

3. Select the desired USB Blaster connection, then click Select

Bmgs browse usb balster.png

4. The slected USB Blaster instance will now be displayed in the Connection field

Bmgs bootloader click debug.png

5. If desired, go to the Debug panel to see how the debugger will be run: it will connect to the board, then run a script that run the bootloader, then exit the debugger.

Bmgs bootloader script.png

6. Click on Debug Button at the bottom of the Debug Configurations' window.

7. Eclipse will ask you to switch to the Debug Perspective. Accept by clicking Yes

Bmgs open perspective.png

8. Eclipse will run the Bootloader, and you will be able to see its output on the UART console

Bmgs bootloader log.png

9. After running the Bootloader, the debugger will automatically close the debugging session, as instructed by the 'quit' command

Bm bootloader done.png

Debug Application

Now, that we have the FPGA configured, and the Bootloader was ran, we can actually use the debugger to run the sample application.

1. In Eclipse, go to Run > Debug Configurations

Bmgs debug configurations.png

2. On the left pane, select DS-5 Debugger > SoCFPGA-GettingStarted-CV-ARMCC

3. Click Browse to select the USB Blaster instance

Bm debug config application.png

4. Select the desired USB Blaster instance and click Select

Bmgs browse usb balster.png

5. The selected USB Blaster instance will be displayed in the Connection field

Bmgs bootloader click debug.png

6. If desired, take a look at the Files tab to see the following:

  • Executable name to be downloaded, with the selected options to download symbols
  • Path where the SVD file is located, containing the register descriptions

Bmgs debug files.png

7. If desired, take a look a the Debug tab to see that the debugger was configured to break and start debugging from the main symbol

Bmgs debug debug.png

8. Click on the Debug button at the bottom of the Debug Configuration window. The application will be downloaded, and ran until it reaches the main function

Bmgs app started.png

9. Click on the green Continue button or press F5. The application will continue, and display the following messages on the UART console:

Bmgs app intro log.png

10. Interact with the application doing the following:

  • Press FPGA button 0 multiple times to move LEDs right in increasing blinking frequency
  • Press FPGA button 1 multiple times to slow the LEDs blinking frequency, then make them move in the opposite direction with increased frequency
  • Press and keep pressed both FPGA button 0 and button 1 at the same time to terminate the application

Bmgs final log.png

11. Eclipse DS-5 will show application status as exited

Bmgs app done.png

View Core, System and FPGA Peripheral Registers

The ARM DS-5 Altera Edition allows you to specify the peripheral IP register descriptions using .svd files. The .svd files are resulted from the hardware project compilation using ACDS. The .svd files contain the description of both HPS peripheral registers, such as UART, EMAC, and timers, and the Soft IP peripheral registers residing on FPGA side.

Note: The soft IP register descriptions are not generated for all soft IP cores. Do not expect to have registers for all the cores they use on FPGA. Some may have it, some may not. The DS-5 debugger allows the user to see the following while debugging bare-metal applications:

  • ARM Cortex-A9 Registers
  • HPS Peripheral Registers
  • FPGA Fabric Registers

The sample application comes pre-configured with the SVD file created when compiling the hardware project, in order to be able to enable viewing the above registers.

1. Open the Debug Configuration and look in the Files tab to see how this is configured.

Bmgs svd settings.png

2. Start a Debug session

3. Put a breakpoint in the source code where the LED PIO data register is updated with the new state of the LEDs, by clicking the left gutter near that line

Bmgs register breakpoint.png

4. Let the application run, by clicking Continue green button or by pressing F5 and it will hit the breakpoint and stop there

Bmgs breakpoint hit.png

5. Look at the Registers panel to see the available registers

Bmgs registers overview.png

6. Expand the Core registers group to see the CPU registers

Bmgs core registers.png

7. Expand the Peripherals > osc1timer0 registers to see the registers corresponding to the timer used by the sample bare-metal application

Bmgs hps timer registers.png

8. Expand the Peripherals > altera_avalaon_pio_led_pio_s1 to see the registers corresponding to the LED PIO FPGA IP.

Bmgs fpga registers.png

If you want, you can change the value of the altera_avalaon_pio_led_pio_s1_DATA register to see how it affects the state of the LEDs.

Note: Do not try to access the soft IP registers before the FPGA is programmed or before the bridges are open. Otherwise, the debugger will generate a memory access abort and the debugging session will fail. This includes having any soft IP registers groups expanded in the Registers dialog box. The debugger will try to access them in order to refresh the view and it will generate a memory access abort if they are not accessible. Always collapse the soft IP register view after usage if there is any chance they will not be available to the debugger.

Perform Program Tracing

Cortex-A9 supports the program tracing option, that can be used by DS-5 to provide the user with a useful debugging and profiling tool. This section explains how to enable program tracing, and how to view the trace.

Note that the tracing information can be stored in the internal trace buffer, in system memory, or on an external trace unit using dedicated pins. This section presents how to use the internal 32KB trace buffer, that offers plenty of storage space for typical debug scenarios, since the tracing data is heavily compressed.

1. In Eclipse, with the sample project open, go to Run > Debug Configurations and select the application debug configuration.

2. In the Connection tab, click on the Edit button near the DTSL Options label.

Bmgs click dtsl.png

3. In the DTSL Options window, go to Trace Buffer tab and select the Trace Buffer option to be On Chip Trace Buffer (ETF)

Bmgs dtsl tb.png

4. In the Cortex-A9 tab, select Enable Cortex A9 core trace and enable just the Core 0 trace, since we are not using Core 1

Bmgs dtsl trace.png

5. In the ETF tab, check the Configure the on-chip trace buffer and edit the value to be 0x8000, which is 32,768 bytes - the actual size of the buffer.

Bmgs dtsl buf size.png

6. Click on the Debug button at the bottom of the Debug Configuration window to start a debug session. The DS-5 will download and run the application up to entering the main function. In the Trace panel, you will be able to see a trace of the functions that were executed between the program entrypoint and the main function. The top of the panel displays executed functions, in descending duration, while the bottom of the panel displays a trace of all assembly instructions executed:

Bmgs trace log.png

7. Put a breakpoint in the program, then let the program go

Bmgs set trace breakpoint.png

8. The breakpoint will be hit, execution will stop

Bmgs trac bkpt hit.png

9. You can scroll through the program trace log, and the C file cursor will be kept in sync by DS-5 to enable you to correlate the assembly log with the actual C source code

Bmgs trace browse.png

Perform Cross Triggering

The Altera SoC offers powerful cross-triggering capability between the HPS and the FPGA fabric. The HPS can trigger the FPGA and also the FPGA can trigger the HPS.

ARM has updated the DS-5 tool specifically for Altera to enable this SoC capability to be easily used.

This section presents an example of how cross-triggering can be used.

The Golden Hardware Reference Design (GHRD) contains the necessary instrumentation to be able to use Quartus Signal Tap II tool to demonstrate cross-triggering.

The Quartus Signal Tap II utility is an optional component of the SoC EDS installation, and is selected by default.

Cross-triggering Prerequisites

This section presents the preparation steps that are required in order to perform the cross triggering scenarios. We boot the HPS, start Signal Tap II and program the FPGA. Note: Any debugging scenario on HPS can be running, as long as it uses a JTAG connection. It does not necessarily have to be Linux. It could be a bare metal program, for example.

1. Configure FPGA and run Bootloader as presented in previous sections

2. Open the Quartus SignalTap II program by running the command <Quartus installation directory>/bin/quartus_stpw. This assumes you have accepted the default settings when installing SoC EDS.

3. In Signal Tap II, select File > Open, browse to <SoC EDS Installation directory>/examples/hardware/cv_soc_devkit_ghrd/cti_tapping.stp and click Open

Bmgs stp file opened.png

4. In Signal Tap II, on the JTAG Chain Configuration > Hardware, select the USB Blaster II Instance

Bmgs stp select jtag.png

5. In SignalTap II, on the JTAG Chain Configuration > Device, select the FPGA device.

Bmgs stp select device.png

6. The SignalTap will change its status as Ready to acquire

Bmgs stp opened.png

7. Make sure to change the Lock Mode from Allow all changes to Allow trigger condition changes only. Otherwise some of the changes may require a recompilation of the hardware project.

Ct-signaltap-lock-mode.png

Enabling Cross-triggering on FPGA

The SignalTap offers the following options for controlling cross-triggering:

  • Trigger in from HPS: default to Dont'care, which means not enabled. Can be also set to high or low.
  • Trigger out to HPS" can be set as high or low. Can also be disabled, but this would require unlocking the configuration, and re-compiling the hardware design in Quartus Prime.

Bmgs stp trigger options.png

Enabling Cross-triggering on ARM

ARM DS-5 offers the possibility of controlling the cross-triggering options.

1. Open the Debug Configuration window for debugging the application.

2. Click on the Edit button near the DTSL Options label

Bmgs click dtsl.png

3. The DTSL Options window will be opened, go to the Cross-trigger tab

Bmgs hps crosstrig options.png


The options include:

  • Enabling cross-triggering from FPGA to Core 0
  • Enabling cross-triggering from FPGA to Core 1
  • Enabling cross-triggering from HPS to FPGA

The Assume Cross Triggers can be accessed option needs to be enabled in order for cross-triggering to work.

In order to enable bi-directional triggering, you need to check all the boxes.

Scenario #1: FPGA triggers HPS

In this scenario, we will use an activity on FPGA (LED state change) to cause a SignalTap acquisition, that, in turn, will trigger an HPS breakpoint through cross-triggering.

1. Configure FPGA and run Bootloader as shown in previous sections

2. In Eclipse Project, configure the HPS to be triggered by FPGA in the DTSL options

Bmgs dtsl fpga trig hps.png

3. Start debugging the application in Eclipse, and let it run. Press the FPGA buttons 0 & 1 to let it start toggling LEDs.

4. Start Signal Tap, and connect it to the running FPGA as shown in a previous section

5. In SignalTap, right-click on the fpga_led_pio[0] and select it to trigger on any edge

Bmgs stp trig on led0.png

6. In SignalTap, enable the trigger out to HPS

Ct-enable-trigger-out-to-hps.png

7. In SignalTap, disable trigger in from HPS

Ct-disable-hps-trigger-in.png

8. In SignalTap, click on Run analysis button

Ct-run-analysis.png

9. The SignalTap will start searching for an edge on the LED[0] signal

Ct-acquisition-in-progress.png

10. Once the LED[0] changes its state, SignalTap will detect that an trigger a capture, showing the state of the signals at the capture time

Bmgs stp led capture.png

11. SignalTap will then trigger HPS, which will stop as if it hit a breakpoint. We can then see what HPS was running at the time, which is exactly the LED toggling code

Bmgs xtrig prog stopped.png

Scenario #2: HPS triggers FPGA

In this scenario, we will break program execution on HPS, which will create a trigger to FPGA which will then issue a SignalTap capture, that we will be able to observe.

1. Configure FPGA and run Bootloader as shown in previous sections2. In Eclipse Project, configure the FPGA to be triggered by HPS in the DTSL options

Bmgs dtsl hps trig fpga.png

3. Start debugging the application in Eclipse, and let it run.

4. In SignalTap, right-click the fpga_led_pio[0] and select Don't care so that it does not create a SignalTap trigger.

Bmgs stp trig cleared.png

5. In SignalTap, configure the HPS trigger in pattern to be Either Edge

Bmgs stp config trig in.png

6. In SignalTap, click on Run analysis button

Ct-run-analysis.png

7. The SignalTap will start waiting for a trigger from HPS

Ct-acquisition-in-progress.png

8. In Eclipse, stop the program execution by clicking the Interrupt yellow button. The program execution will stop as if a breakpoint was hit

Bmgs xtrig break hps.png

9. The HPS program break will cause a trigger to be sent to FPGA, which will cause a SignalTap acquisition, showing the signals at the moment of the capture

Bmgs stp led capture.png

Creating a Bare-metal HwLibs Project Automatically

This section presents how to create a complete bare-metal HwLibs project, by using a provided script which can create both plugin-based projects and Makefile-based projects.

The specific example provided creates a plugin-managed project (all settings are managed from Eclipse DS-5 GUI) but the script itself can also create Makefile-based projects, and the instructions are identical for both cases.

Note that the project can also be created manually, instructions for how to do it manually are provided here but it is much more convenient to use the script.

The pre-requisites for running the steps in this section are:

  • Host PC running either Windows or Linux
  • SoC EDS 16.1b196+
  • Quartus Prime Standard 16.1b196+ - needed in order to create the system.h file that contains the addresses of all FPGA slaves accessible by ARM. If Quartus Prime is not installed, these features will not be available, and a warning message will be displayed.

1. Download the script from File:Create hwlibs project.zip and extract it on the local computer - the file create_hwlibs_project.py will be created.

2. Start an Embedded Command Shell. The script needs to be run from an Embedded Command Shell, since it environment variables and tools that are only available from Embedded Command Shell. Python is also required, and is available from the Embedded Command Shell.

3. Mark the script as executable by running the following command:

chmod +x create_hwlibs_project.py

4. Run the script with --help option to see the available options:

$./create_hwlibs_project.py  --help
Usage: ./create_hwlibs_project.py \
    --project-name=<project_name> \
    [--project-type=<plugin|makefile>] \
    --device=<av|cv|a10> \
    --compiler=<armcc|gcc> \
    --printf-method=<uart|semihosting> \
    --memory=<ocram|sdram> \
    [--bootloader-script=<default|file_name>] \
    [--fpga-config-file=<default|file_name>] \
    [--svd-folder=<default|folder_name>] \
    [--sopcinfo-file=<default|file_name>]

The table below contains a detailed explanation of all the parameters of the script:

Option Mandatory Description
--project-name yes Project name to be used. Must not have spaces or special characters. Just letters, numbers and underscores.
--project-type no Can be 'makefile' or 'plugin'. Defaults to 'plugin' is not specified.
--device yes Can be 'cv', 'av' or 'a10'
--compiler yes Can be either 'armcc' or 'gcc'
--printf-method yes Can be either 'uart' or 'semihosting'
--memory yes Can be either 'sdram' or 'ocram'
--bootloader-script no Provide bootloader script (full path) to be used to create an Eclipse debug configuration for running the Bootloader.
Use 'default' value to specify that the corresponding GHRD bootloader script should be used.
--fpga-config-file no Provide the FPGA configuration file (full SOF path) to be used to create an Eclipse external tool launcher for FPGA configuration.
Use 'default' value to specify that the corresponding GHRD FPGA configuration file should be used.
--svd-folder no Provide the folder (full path) where the SVD file is stored, to be passed to the debugger to be able to show the peripheral registers.
Use 'default' value to specify the that corresponding GHRD SVD folder should be used.
--sopcinfo-file no Provide sopcinfo file (full path) to be used to generate system.h.
Use 'default' value to specify that the corresponding GHRD sopcinfo should be used.
--help no Display usage message

5. For example, run the script to generate a plugin-managed Arria 10 project using GCC, SDRAM, semihosting, and default GHRD sof, SVD and bootloaders:

./create_hwlibs_project.py \
    --project-name=Example-A10-GCC \
    --device=a10 \
    --compiler=gcc \
    --printf-method=semihosting \
    --memory=sdram \
    --bootloader-script=default \
    --fpga-config-file=default \
    --svd-folder=default \
    --sopcinfo-file=default

6. The script will create a complete project, as shown below:

Create-bm-project-with-script.png

In this particular case, the following files were created:

Example-A10-GCC/
    .project                                    - Eclipse project file
    .cproject                                   - C project file, containing all the compilation settings
    hwlibs/                                     - Folder with all the relevant HwLibs source code
    src/main.c                                  - Application source code, containing just a 'hello world' simple main.c
    system.h                                    - Offsets for all FPGA peripherals used in the associated hardware design
    arria10-dk-ram-hosted.ld                    - Linker script
    Example-A10-GCC-Configure-FPGA.launch       - External tool launcher for configuring the FPGA
    Example-A10-GCC-Create-SystemH.launch       - External tool launcher for re-generating the 'system.h' when the FPGA contents is changed
    Example-A10-GCC.launch                      - Debug launcher for debugging the application
    Example-A10-GCC-Run-Bootloader.launch       - Debug launcher for running the Bootloader 

7. Start Eclipse

8. In Eclipse, go to File > Import

Bmgs-eclipse-import-project.png

9. Select General > Existing Projects into Workspace and click Next

Bmgs-import-existing-project.png

10. Make sure to choose Select Root Directory then click Browse

Bmgs import select dir.png

11. Browse to the newly created project folder and click OK

Bmgs-import-example-project-folder.png

12.Make sure to check the Copy Projects Into Workspace, otherwise some features will not work. (An alternative is to create the project directly in the workspace folder, then you do not need to copy the project in the workspace). Click Finish

Import-copy-project.png

13. The project will be imported, and available in Eclipse

Bmgs-created-project-imported.png

For detailed usage of the created project, you can refer to this section, since the Getting Started Application projects were also generated using this script.

Creating a Bare-metal HwLibs Project Manually

The ARM DS-5 AE can manage bare-metal projects in a GUI environment, without using Makefiles. This section presents examples on how to use this feature.

Note that these instructions are provided for reference only, and the recommended method to create a new project is to use the script-based automated method documented here .

The pre-requisites for running the steps in this section are:

  • Host PC running either Windows or Linux
  • SoC EDS 16.1b196+

The screenshots are all taken in a Windows environment, but the usage is identical on a Linux environment.

GCC Bare-Metal Project Management

This section shows a complete example on how the ARM DS-5 AE can be used to manage GCC-based projects in a GUI environment.

The steps required by this example are:

Creating the Project

1. Start Eclipse - click here for instructions

2. Go to File > New > C Project

Eclipse-new-c-project.png

3. Edit Project Name to be TestGccProject, select Project Type to be Executable > Empty Project, and select Toolchains to be Altera Baremetal GCC.

New-gcc-project.png

4. Click Finish - this will create the project.

Setting Build Options

1. Go to Project > Properties to open the Project Properties window.

2. Go to C/C++ Build > Settings to access compilation settings for compiler, assembler and linker.

Here are the recommended settings for the compiler target:

Eclipse-gcc-compiler-settings.png

The recommended settings for the assembler target are similar:

Eclipse-gcc-assembler-settings.png

The linker script to be used also must be selected. In order to do that, go to C/C++ Build > Settings > GCC C Linker > Image and edit the Linker script to point to the desired linker script file.

For Arria V and Cyclone V projects, the following linker script files are available in the folder <SoC EDS installation directory>\host_tools\mentor\gnu\arm\baremetal\arm-altera-eabi\lib\:

File Description
cycloneV-dk-oc-ram.ld Targetting OCRAM (On Chip RAM)
cycloneV-dk-oc-ram-hosted.ld Targetting OCRAM (On Chip RAM) - with semihosting enabled
cycloneV-dk-ram.ld Targetting SDRAM
cycloneV-dk-ram-hosted.ld Targetting SDRAM - with semihosting enabled

For Arria 10 projects, the following linker script files are available in the folder <SoC EDS installation directory>\host_tools\mentor\gnu\arm\baremetal\arm-altera-eabi\lib\:

File Description
arria10-dk-oc-ram.ld Targetting OCRAM
arria10-dk-oc-ram-hosted.ld Targetting OCRAM - with semihosting enabled
arria10-dk-ram.ld Targetting SDRAM
arria10-dk-ram-hosted.ld Targetting SDRAM - with semihosting enabled

In order to run our example with semihosting enabled on a Cyclone V SoC board, let's select the linker file as ${SOCEDS_DEST_ROOT}/host_tools/mentor/gnu/arm/baremetal/arm-altera-eabi/lib/cycloneV-dk-oc-ram-hosted.ld:

Eclipse-gcc-linker-script.png

Note that we have used ${SOCEDS_DEST_ROOT} variable defined inside Embedded Command Shell, so that we did not have to type the whole absolute path. Also note that on a Windows machine both back slashes and forward slashes work when used in the path, but on a Linux host machine only forward slashes work.

Write Application Source Code

1. Go to File > New > Source File to open the New Source File dialog.

2. In the New Source File dialog, edit the Source file to be test.c and click Finish.

Eclipse-new-source-file.png

3. Edit the test.c file to contain the text shown in the following image

Eclipse-gcc-program.png

Build Application

1. Build the application by going to Project > Build Project

Eclipse-gcc-built.png

ARMCC Bare-Metal Project Management

This section shows a complete example on how the ARM DS-5 AE can be used to manage ARMCC-based projects in a GUI environment.

The steps required by this example are:

Creating the Project

1. Start Eclipse - click here for instructions

2. Go to File > New > C Project

Eclipse-new-c-project.png

3. Edit Project Name to be TestArmccProject, select Project Type to be Executable > Empty Project, and select Toolchains to be ARM Compiler 5.

New-armcc-project.png

4. Click Finish - this will create the project.

Creating the Scatter File

This section presents how to create the linker scatter file that is used by ARMCC linker to determine the placement of the program in the target memory.

1. Go to File > New > Other ...

2. Select Scatter File Editor > Scatter File and click Next.

New-scatter-file.png

3. Select the TestArmccProject, edit the file name to be scatter.scat and click Finish.

New-scatter-file-2.png

4. When targetting a Cyclone V or Arria V device, edit the file "scatter.scat" to contain the following:


Scatter-file-text.png

The above linker script instructs the linker on how to link the application:

  • Defines OCRAM base address (0xFFFF0000) and size (0x10000)
  • Loads all application sections in the OCRAM
  • Allocates a maximum of 16K (0x4000) for stack an heap

If desired, click on the "Regions/Section" tab and you will see a graphical view of the linker script.

Scatter-file-graphic.png

The parameters can easily be changed for targeting Arria 10 devices, where there are 256KB of OCRAM located at 0xFFFE00000.

When targeting SDRAM, for AV/CV/A10 on all Altera DevKits, the start address is 0x100000 (1MB) and the total length is 0x3FF00000 (1023MB).

Setting Build Options

1. Go to Project > Properties to open the Project Properties window.

2. Go to C/C++ Build > Settings to access compilation settings for compiler, assembler and linker.

At the very minimum, set the target cpu to be Cortex A-9, then accept all the default settings:

Eclipse-armcc-target.png

3. Go to C/C++ Build > Settings > ARM Linker 5 > Image Layout and then click Browse

4. Select the newly created file scatter.scat and click Open.

Note that in the picture below we use a project-relative path for the file, so that the project would be importable/exportable on a different machine or path. We do this by using the ${workspace_loc:/${ProjName}}/ path, which refers to the current project folder.

Eclipse-armcc-linker-script.png

5. Click OK to close the Project Properties window.

Write Application Source Code

1. Go to File > New > Source File to open the New Source File dialog.

2. In the New Source File dialog, edit the Source file to be test.c and click Finish.

Eclipse-new-source-file2.png

3. Edit the test.c file to contain the text shown in the following image

Eclipse-armcc-program.png

Build Application

1. Build the application by going to Project > Build Project

Eclipse-armcc-built.png

Adding HwLibs Your Project

This section explains how to add the HwLibs files to your DS-5 project, for both armcc and gcc GUI managed projects. Adding HwLibs will allow you to use both the HwMgr APIs and the SoCAL low level macros.

HwLibs folder structure

The HwLibs are part of the SoC EDS installation, and are stored in <SoC EDS installation directory>/ip/altera/hps/altera_hps/hwlib/:

hwlib
    include              - HwLibs include files, common
        soc_a10          - HwLibs include files, device specific for A10
            socal        - SoCAL include files, device specific for A10
        soc_cv_av        - HwLibs include files for CV and AV
            socal        - SoCAL include files, device specific for CV and AV
    src
        hwmgr            - HwLibs source code files, common
            soc_a10      - HwLibs source code files, device specific for A10
            soc_cv_av    - HwLibs source code files, device specific for CV and AV
         utils           - Utility source code

Adding the files to the Project

This section explains how to add the HwLibs files to a project that is managed by DS-5 GUI. It does not apply to Makefile-based projects, where the user must manually manage the Makefile.

In order for the HwLibs source code to be added to the project, the following steps are required:

  • Copy the relevant HwLibs files from SoC EDS into the current DS-5 project folder
  • Refresh the DS-5 project so that the files are recognized by DS-5 and added to the project
  • Add the required include paths to the compiler settings
  • Add the required macro definitions to the compiler settings

1. Copy the relevant HwLibs source code to to the project

It is required to copy only the HwLibs files that are relevant to the compiler (armcc or gcc) and device (av/cv or a10) that are targeted. Also, it is recommended to copy just the files that will be used, otherwise the compilation time would be longer.


Adjust Project Settings

The project settings need to be adjusted, to:

  • Define the device macro "soc_cv_av" or "soc_a10", depending on the device that is targeted
  • Add the hwlib/include folder to the compile include path
GCC Project

1. Go to Project > Settings > C/C++ Build > Settings > GCC C Compiler > Symbols then click on the "+" to add another macro, enter "soc_cv_av" or "soc_a10" depending on your target device, then click OK. Your settings will look similar to the following:

Eclipse-gcc-hwlibs-macro.png

2. If want to redirect printf operation to UART instead of semihosting, you will need to also define the following macros:

Macro Description
PRINTF_UART Routes printf to UART instead of semihosting in the debugger console
DEFAULT_TERM Selects which UART to use for printf. Use "term0" for UART0 and "term1" for UART1.

If instead you want to use semihosting, with the debugger console showing the printf, then you only need to define one macro:

Macro Description
PRINTF_HOST Routes printf to semihosting, with debugger console showing the output instead of UART

3. Go to Project > Settings > C/C++ Build > Settings > GCC C Compiler > Includes then clock on "+" to add an include path then click on Workspace and select the hwlibs/include folder then click OK. Your settings will look like this: Eclipse-gcc-hwlibs-include.png

ARMCC Project

1. Go to Project > Settings > C/C++ Build > Settings > ARM Compiler 5 > Preprocessor then click on the "+" to add another macro, enter "soc_cv_av" or "soc_a10" depending on your target device, then click OK. Your settings will look similar to the following:

Eclipse-armcc-hwlibs-macro.png

2. If want to redirect printf operation to UART instead of semihosting, you will need to also define the following macros:

Macro Description
PRINTF_UART Routes printf to UART instead of semihosting in the debugger console
DEFAULT_TERM Selects which UART to use for printf. Use "term0" for UART0 and "term1" for UART1.

If instead you want to use semihosting, with the debugger console showing the printf, then you only need to define one macro:

Macro Description
PRINTF_HOST Routes printf to semihosting, with debugger console showing the output instead of UART

3. Go to Project > Settings > C/C++ Build > Settings > ARM Compiler 5 > Includes then clickon "+" to add an include path then click on Workspace and select the hwlibs/include folder then click OK. Your settings will look like this:

Eclipse-armcc-hwlibs-include.png

Using SDRAM With Your Project

In order to use SDRAM, the following are required:

  • Update the project to use a linker script that targets SDRAM instead of OCRAM. This is already covered in the sections about creating a new project
  • Initialize the SDRAM. This is achieved by running the FSBL (First Stage Bootloader):
    • On CV and AV: the FSBL is called "Preloader" and is typically SPL
    • On A10: the FSBL is called "Bootloader" and is typically U-Boot

After the SDRAM is initialized, the bare-metal project can be downloaded into SDRAM, and debugged as usual. It is recommended to run the FSBL before each debugging session, since it puts all the hardware in a known state.

Configuring FPGA IO - Required on A10

On A10, the FPGA IO also needs to be configured before running the FSBL to initialize SDRAM. In a typical runtime scenario, this is accomplished either by the FPGA being configured from an external agent (such as QSPI flash or PCIe) or by FPGA being configured by the FSBL itself with an image retrieved from flash.

In a debugging environment, it is preferable to:

  • Configure FPGA with Quartus Programmer - a tool included by default with the SoC EDS installation; and
  • Use an FSBL that was set up for "external configuration" so that it does not try to configure the FPGA with an image from flash.

The simplest way to configure the A10 FPGA is by using the command line version of Quartus Programmer from an Embedded Command Shell:

quartus_pgm --no_banner --mode=jtag -o "p;$SOCEDS_DEST_ROOT/examples/hardware/a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.sof"

A10-program-fpga-embedded-command-shell.png

There is also a GUI version of the Quartus programmer that can be started by running the "quartus_pgmw" command from an Embedded Command Shell.

Running the First Stage Bootloader

This section contains the instructions required to run the FSBL from the debugger. The instruction are generic, applying to AV/CV and A10, but the screenshots were taken on a CV setup.

1. In Eclipse, go to Run > Debug Configurations then right-click on "DS-5 Debugger" and click "New"

2. Rename the configuration from "New_configuration" to "Preloader"

3. Under Connection tab, select the desired target platform:

  • for CV: Altera > Cyclone V SoC (Dual Core) > Bare Metal Debug > Debug Cortex-A9_0
  • for AV: Altera > Arria V SoC > Bare Metal Debug > Debug Cortex-A9_0

4. Select Target Configuration to be "USB-Blaster" instead of "DSTREAM".

5. On Connections click Browse to select you USB Blaster debugger instance.

Here is how your project settings connection tab would look in case of CV:

Eclipse-run-preloader-connection.png

6. Under Debugger tab, select the Run Control to be "Connect Only"

7. Check Run debug initialization debugger script and enter the path to the Bootloader script, according to your platform. When using the Altera SoC Development Kit, the available pre-compiled options are:

  • For CV: <SoC EDS Folder>/examples/hardware/cv_soc_devkit_ghrd/software/preloader/preloader.ds
  • For AV: <SoC EDS Folder>examples/hardware/av_soc_devkit_ghrd/software/preloader/preloader.ds
  • For A10: <SoC EDS Folder>/examples/hardware/a10_soc_devkit_ghrd/software/bootloader_ext_cfg/uboot.ds

Here is how your project settings debugger tab would look in case of CV, using the pre-compiled Preloader for the CV DevKit:

Eclipse-run-preloader-debugger.png

8. Click on the Debug button and confirm perspective switch.

9. The debugger will run the Preloader/Bootloader, and will stop on a pre-defined breakpoint:

Eclipse-preloader-run.png

If you are monitoring the serial console output, you will be able to see the Preloader messages:

Eclipse-preloader-console-output.png

11. Disconnect from the target by clicking the Disconnect red button.

12. You can now run a Debug Configuration that uses SDRAM, since it was brought up by Preloader/Bootloader.

Cyclone V HwLibs FPGA Baremetal Example

The SoC Hardware Libraries example program is part of the Altera SoC Embedded Design Suite (EDS). You can run the sample program on a Cyclone V SoC development kit board.The example program demonstrates using the Hardware Library to programmatically configure the FPGA and exercise soft IP control from the hard processor system (HPS).

HwLibs Sample Application Overview

The Bare Metal sample application uses the HWLIB API to:

  • Programmatically configure the FPGA from the HPS* Initialize and bring up the Advanced eXtensible Interface (AXI) bridge interfaces between the HPS and the FPGA
  • Exercise the FPGA soft IP parallel I/O (PIO) core from the HPS to toggle the development board LEDs

The sample application uses the development kit Golden System Reference Design (GSRD) FPGA configuration. The sample application uses the following files:

  • FPGA configuration SRAM Object File (.sof)
  • Preloader executable file for proper initialization of the GSRD HPS component

The sample application is built with a makefile that performs the following steps:

  1. Copies Hardware Libraries source code from installation folder to the current project folder.
  2. Compiles the example C source code files with the GNU Compiler Collection (GCC) tool chain from Mentor Graphics
  3. Copies the .sof file from the GSRD folder
  4. Converts the .sof file to a compressed Raw Binary File (.rbf) format with the quartus_cpf utility available in the Altera Complete Design Suite or the Quartus II software programmer.
  5. Converts the .rbf to an equivalent Executable and Linking Format File (.elf) object file with the GCC objcopy utility.
  6. Links the example program and the FPGA configuration resource object files into the HWLIB example executable file.

A debugger script performs the following steps to help execute the sample application:

  1. Loads the preloader image and places a breakpoint at the end of the image
  2. Runs the preloader image until it reaches the breakpoint. This properly configures the HPS component according to the GSRD
  3. Loads the HwLibs sample application

Importing the Sample Application

1. Start Eclipse - click here for instructions

2. Go to File > Import. The Import dialog box appears.

3. In the Import dialog box, select General > Existing Projects into Workspace and click Next. This will open the Import Projects dialog box

Eclipse-import-existing-project.png

4. In the Import Projects dialog box, select the Select Archive File option.

5. Click Browse, then navigate to <SoC EDS installation directory>\embedded\examples\software\, select the file Altera-SoCFPGA-HardwareLib-FPGA-CV-GNU.tar.gz and click Open.

6. Click Finish. The project is imported. The project files are displayed in the Project Explorer panel.

Hwlibs-imported.png

Compiling the Sample Application

1. To compile the application, select the project in Project Explorer.

2. Select Project > Build Project.

3. The project compiles and the Project Explorer shows the newly created hwlib.axf executable file as shown in the figure below. The Console dialog box shows the commands and responses that were executed.

Hwlibs-compiled.png

Debugging the Sample Application

The bare-metal sample application comes with a pre-configured Eclipse Workspace Launcher that allows you to load, run, and debug the sample application. The Workspace Launcher uses the Altera USB-Blaster II board connection. It uses a debugger script to load and run the Preloader to configure the HPS component, and then loads the sample application.

To run the sample application, perform the following steps:

1. Setup the board as described in the Board Setup section and power it up. Make sure Linux or another OS is not booted, which can interfere with baremetal debugging.

2. Select Run > Debug Configurations.. to access the launch configurations. The sample project comes with a pre-configured launcher that allows the application to be run on the board.

3. In the Debug Configurations dialog box, on the left panel, select DS-5 Debugger > Altera-SoCFPGA-HardwareLib-FPGA-CV-GNU-Debug.

4. The launcher is already configured to us the Cyclone V as a target: Altera > Cyclone V SoC (Dual Core) > Bare Metal Debug > Debug Cortex-A9_0.

5. Make sure the Target Connection is selected as USB-Blaster.

6. Click the Browse button in the Bare Metal Debug Connection and select the desired USB Blaster and click OK.

7. Click the Debug button from the bottom of the Debug Configurations dialog box.

8. Eclipse will ask whether to switch to Debug Perspective. Click Yes to accept it.

9. The debugger downloads the application on the board through JTAG, enables semi-hosting using the provided script, and runs the application until the PC reaches the main function. At this stage, all the debugging features of DS-5 can be used: viewing and editing registers and variables, looking at the disassembly code.

Eclipse-hwlibs-started.png

10. Click Continue green button (or press F8) to run the application. It displays the hello message in the Application Console.

Hwlibs-output.png]

11. Click Disconnect from Target button to close the debugging session.


Getting Started with Linux Application Debugging

Moved to https://rocketboards.org/foswiki/Documentation/LinuxApplicationDebuggingWithDS5

Getting Started with Linux Kernel and Driver Debugging

Moved to https://rocketboards.org/foswiki/Documentation/LinuxKernelDebuggingWithDS5

Getting Started with Program Tracing in a Linux Scenario

Moved to https://rocketboards.org/foswiki/Documentation/LinuxKernelDebuggingWithDS5

Personal tools