SoCEDSGettingStarted

From Altera 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 Linux

This section presents how to run the provided Linux image on the board, to be able to run the Getting Started sections related to Linux.

Prerequisites:

  • Altera SoC Development Board (Cyclone V, or Arria 10)
  • Micro SD card with size at least 4GB
  • Host PC with either Linux or Windows
  • Serial terminal utility (for example TeraTerm on Windows or minicom on Linux)
  • SoC EDS 16.1b196+ (for the prebuilt Linux images)

Running Linux on Cyclone V SoC Board

1. Setup the board as described in Board Setup section.

2. Extract the SD card image from the archive <SoC EDS installation directory>\embeddedsw\socfpga\prebuilt_images\CycloneV_Linux_SDCard.tar.gz. The file is named CycloneV_Linux_SDCard.img.The command tar -xzf<filename> can be used from Embedded Command Shell to achieve this.

3. Write the SD card image to a micro SD card using the free tool Win32DiskImager from sourceforge.net on Windows or the dd utility on Linux.

4. Power up the board using the PWR switch.

5. Connect a serial terminal from the host PC to the serial port corresponding to the UART USB connection; and use 115,200 baud, no parity, 1 stop bit, no flow control settings.

6. After successful boot, Linux will ask for the login name. Enter root and press Enter

Cv-linux-booted.png

Running Linux on Arria 10 SoC Board

1. Setup the board as described in Board Setup section.

2. Extract the SD card image from the archive <SoC EDS installation directory>\embeddedsw\socfpga\prebuilt_images\arria10\Arria10_Linux_SDCard.tar.gz. The file is named Arria10_Linux_SDCard.img.The command tar -xzf<filename> can be used from Embedded Command Shell to achieve this.

3. Write the SD card image to a micro SD card using the free tool Win32DiskImager from sourceforge.net on Windows or the dd utility on Linux.

4. Power up the board using the PWR switch.

5. Connect a serial terminal from the host PC to the serial port corresponding to the UART USB connection; and use 115,200 baud, no parity, 1 stop bit, no flow control settings.

6. After successful boot, Linux will ask for the login name. Enter root and press Enter

A10-linux-booted.png

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

The ARM DS-5 Altera Edition provides very powerful Linux application debugging capabilities. This section presents running the ARM DS-5 Altera Edition for the first time, importing, compiling and running the Hello World Linux example application provided as part of SoC EDS. Note: This section uses a Linux host computer, as can be seen from the screen shots and the issued commands. However, the scenario can also be run on a Windows machine, although it is not usual for Linux development to be done on Windows.

Configuring Linux

  • For this getting started scenario we need Linux to be running on the target board and be connected to the local network.
  • The local network has to have a DHCP server that will allocate an IP address to the board.
  • Eclipse needs an account with a password to be able to connect to the target board. The root account does not have a password by default, so one needs to be set up.

The required steps are:

  1. Setup the board as described in the Getting Started with Board Setup section; and connect the HPS Ethernet Connector J2 to the local network.
  2. Start Linux on the target board, as described in the Getting Started with Running Linux section.
  3. On the Linux console, run the command ifconfig to determine the IP address of the board.
  4. On the Linux console, change the root password by running the passwd command. Ignore the warnings about a weak password.

Import Sample Application

1. Run Linux on the target board, as described in Running Linux

2. Start ARM DS-5 AE Eclipse, as described in Starting Eclipse

3. In Eclipse, select File > Import. The Import dialog box displays.

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

Linuxapp-import.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-Linux-GNU.tar.gz and click OK.

Linuxapp-import-select.png

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

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 executable file as shown in the figure below. The Console dialog box shows the commands and responses that were executed.

Linuxapp-compiled.png

Setting up Remote System Explorer

The ARM DS-5 AE can run and debug programs directly on the target with the help of the Remote System Explorer (RSE). Before this feature can be used, the RSE needs to be configured to connect to the target board running Linux.

1. In your Eclipse workspace, select Window > Open Perspective > Other. This will open the Open Perspective dialog box.

2. In the Open Perspective dialog box, click the Remote System Explorer and click OK.

3. In the Remote System Explorer view, right click Local and select New > Connection ….This will open the New Connection wizard. Note that Clicking the + sign achieves the same result

Linuxapp-define-connection.png

4. In the first page of the New Connection wizard, named Remote System Type view, select SSH only and click Next.

Linuxapp-new-connection.png

5. Enter the IP address of the board in the Host Name field. Click Finish to create the connection.

Linuxapp-define-host.png

6. In the Remote Systems panel, click the Target IP > Sftp Files > Root. This opens a dialog box to enter the username and password

Linuxapp-folders.png

7. Assign root to User ID and assign the password you selected in the Configuring Linux section to Password. Select the Save User ID and Save password check boxes. Click OK.

Linuxapp-password.png

8. Eclipse asks for confirmation of authenticity of the board. Click Yes.

9. Remote System Explorer shows the files on the DevKit board on the left panel.

Linuxapp-folders-expanded.png

Debugging the Sample Application

At this stage, we have a compiled Linux application and a properly configured Remote Systems Connection. This section shows how to create a Debugger Configuration and use it to run and debug the application.

1. Select Run > Debug Configurations… to open the Debug Configurations dialog box.

2. Right click the DS-5 Debugger and click New to create a new debug configuration.

3. Name the newly created debugger configuration, LinuxAppDebug_DevKit, by editing its name in the Connection tab.

4. In the Connection tab, select:# For the Free Web Edition license, select Generic > gdb server > Linux Application Debug > Download and Debug Application.# For the Subscription Edition or 30-day Evaluation Edition, select Altera > Cyclone 5 SoC > Linux Application Debug > Download and Debug Application.

5. In the Connection tab, select the newly created RSE connection and keep the default values. Note: On some systems, you may need to uncheck the ‘Use Extended Mode’ checkbox to prevent a ‘Unable to connect’ error.

Linuxapp-debug-1.png

6. Go to Files tab, and set the Target Configuration parameters:

  • Select the Application on host to download to be the hello executable file. Use the Workspace… browse button.
  • Edit the Target download directory to be "/home/root" (the root folder).# Edit the Target working directory to be "/home/root" (the root folder).

Linuxapp-target-config.png

7. Click the Debug button. A dialog window appears asking to switch to Debug perspective. Click Yes.

8. Eclipse downloads the application to the board and stops at main function entry.

Linuxapp-downloaded.png

At this stage, all the usual debugging features of DS-5 can be used, such as breakpoints, view variables, registers, tracing, and threads.

9. Click the Continue green button or press F8 to run the application. The hello message is printed on the Application Console.

Linuxapp-output.png

Getting Started with Linux Kernel and Driver Debugging

This section presents an example on of how to debug the Linux kernel and drivers using DS-5. The software engineers can use the dedicated Linux debugging features presented in this section together with the basic debugging features such as viewing registers, inspecting variables and setting breakpoints.

Notes:

  • In the scenario presented here the Linux kernel is already running on the board, but it can also be downloaded through the debugger.
  • This scenario uses the pre-built Linux images and Linux source code included in the SoC EDS.
  • These are examples only; use the latest sources from the Rocketboards for development.
  • This section uses a Linux host computer, as can be seen from the screenshots and the issued commands. However, the scenario can also be run on a Windows machine, although it is not usual for Linux development to be done on Windows.
  • The paths presented in this section assume the default installation paths were used. Adjust accordingly if non-standard location is used.

Prerequisites

  • Make sure the desired Linux kernel version is already running on the board. See the Getting Started with Running Linux section for instructions on how to run the provided Linux binaries on the board.
  • Make sure the Linux kernel executable file is accessible on the host computer. The kernel executable for the pre-built Linux image is located at <SoC EDS installation directory>/embeddedsw/socfpga/prebuilt_images/vmlinux.
  • Make sure the source code corresponding to the kernel running on the board are accessible on the host computer. The sources for the pre-built Linux image can be obtained by:
  1. Start Embedded Command Shell
  2. Run the following command: cd <SoC EDS installation directory>/embeddedsw/socfpga/sources/
  3. If your computer connects to the Internet using a proxy, you may need to use the following command to tell the Git utility about the proxy: git config --global http.proxy <proxy_name>
  4. Run the following command: ./git_clone.sh

Debugging the Linux Kernel and Drivers

This section presents how to create a Debug Configuration that is then used to debug the Linux kernel.

1. Start ARM DS-5 AE Eclipse, as described in Starting Eclipse

2. Select Run > Debug Configurations… to open the Debug Configurations dialog box.

3. In the Debug Configurations dialog box, right-click DS-5 Debugger on the left panel and select New.

4. In the Debug Configurations dialog box, perform the following:

  • Rename the configuration to DebugLinux_DevKit using the Name edit box
  • Select the Target to be Altera > CycloneVSoC >Linux Kernel and/or Device Driver Debug >Debug Cortex- A9x2 SMP via Altera USB-Blaster
  • Click the Browse button near the Connection edit box and select the desired USB Blaster instance

Kernel-config-connection.png

5. Click on the Debugger and perform the following steps:

  • Select option Connect Only for Run Control
  • Check Execute debugger commands check box
  • Add the debugger commands to stop cores and load image symbols for the Linux executable, as shown in the following figure
  • Add the path to the Linux source files on the host machine to allow the debugger to locate them

Kernel-debugger-settings.png

6. Click the Debug button. The debugger connects to the board, stops the cores as instructed and loads the kernel symbols. It determines where the cores are stopped, and highlights it in the source code.The following figure shows the debugger stopped in the idle instruction.

Kernel-stopped.png

7. To view the running threads, maximize the top left panel. It shows Active Threads with the two currently executing threads. Also the All Threads can be expanded to show all threads in the system.

Kernel-threads.png

8. Minimize the Debug Control panel and maximize the Functions panel from top right. All of the functions in the kernel are displayed. The Functions panel supports the following operations for each function:

  • Run up to the function
  • Set PC to function
  • Locate in source code, memory, or disassembly
  • Set breakpoints to software or hardware
  • Set trace points to enable, disable, or toggle

9. Select Modules panel to view the currently loaded modules. Note that the debugger has added breakpoints at the module load and module unload functions. As modules are loaded with insmod, and removed with rmmod, the DS-5 AE will reflect the changes.

Kernel-debugger-breakpoints.png

Getting Started with Program Tracing in a Linux Scenario

ARM DS-5 provides powerful tracing features, allowing PTM and STM tracing. It allows different tracing data destination types. This section presents an example of Program Tracing using PTM and storing the tracing information in memory using ETF.

The tracing scenario presented here uses Linux kernel debugging as an example, but any application can be traced in the same way. As shown, the tracing can be selected to show current core, a particular core, or follow the currently executing thread.

The following steps are necessary in order to enable PTM tracing:

1. Execute the steps described in the Getting Started with Linux Kernel and Driver Debugging section to perform Linux kernel debugging.

2. Select Run -> Debug Configurations and select the Debug Linux_DevKit configuration created at the previous step.

3. Select the Connection tab.

4. Click the Edit DTSL Options button.

Tracing-dtsl.png

5. In the DTSL dialog box, click Trace Buffer tab and select On Chip Trace Buffer (ETF) for the Trace capture method.

Tracing-trace-buffer.png

6. In the DTSL dialog box, click the Cortex-A9 tab, and enable tracing for both cores

Tracing-ptm.png

7. In the ETF tab, select the ETF to be enabled; and a buffer size of 0x8000, to match the ETF size on the Cyclone V SoC, which is 32 KB.

Tracing-etf.png

8. Click OK to exit the DSTL Configuration Editor.

9. Start a debugging session by starting the Debug Linux_DevKit debug configuration. The debugger stops the Linux kernel and configure tracing.

10. Let the kernel run by clicking the Continue green button or pressing F8.

11. After executing some commands from the Linux serial terminal, click Interrupt button or press F9. The Debugger shows the captured trace information.

Tracing-stats.png

The tracing window shows:

  • Core instructions as they were executed
  • Percentage occupied by each function
  • Histogram with function allocation

Getting Started with Cross Triggering in a Linux Scenario

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. Boot the board using the Linux SD card as shown in the Getting Started with Running Linux section.

2. Connect USB cable from the USB Blaster II™ connection to the host PC.

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

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

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

Ct-select-usb-blaster.png

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

Ct-select-fpga-device.png

7. In SignalTap II, under SOF Manager, click the Browse "…" button, browse to the file <SoC EDS Installation directory>/examples/hardware/cv_soc_devkit_ghrd/output_files/soc_system.sof and click Open.

Ct-browse-program-files.png

8. In Signal Tap II, under SOF Manager, click the Program button to program the FPGA.

Ct-program-fpga.png

9. After the FPGA is programmed, the SignalTap II will be ready to acquire

Ct-signaltap-ready-to-acquire.png

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

For this getting started scenario, we are using Quartus SignalTap II utility to control FPGA cross triggering.

Ct-signaltap-crosstrigger-options.png

Quartus SignalTap II GUI has the above depicted Trigger panel that controls cross-triggering:

  • The Trigger In panel determines whether HPS can trigger FPGA. Trigger In can be enabled and the Pattern can be selected with Don't care, Low, High, Rising Edge, for instance.
  • The Trigger out panel determines whether FPGA can trigger HPS. Trigger out can be enabled and the Level can be selected: Active High and Active Low.

Note: the above screenshot was taken with Lock Mode set to Allow all changes to give a better overview of the options.

Enabling Cross-triggering on HPS

1. Cross-triggering can be enabled in the DTSL dialog box, which can be accessed from the Connection tab of the Debug Configuration.

Tracing-dtsl.png

2. The Cross-Trigger tab of the DTSL Configuration Editor allows Cross-trigger configuration.

Ct-hps-crosstrigger-configuration.png

In order to allow FPGA cross triggers to trigger HPS, you need to:

  • Check the Enable FPGA > HPS Cross Triggering check box
  • Check the Assume Cross Triggers can be accessed check box

In order to allow HPS cross triggers to trigger FPGA, you need to:

  • Check the Enable HPS > FPGA Cross Triggering check box
  • Check the Assume Cross Triggers can be accessed check box

Note: In order to enable bi-directional triggering, you can check all three check boxes.

FPGA Triggering HPS Example

This section presents an example on how FPGA can trigger HPS to stop the execution.

This can be useful if you want to see what the HPS is doing at the moment the trigger comes from FPGA.

The required steps are to reproduce this scenario are: 1. Perform the steps from the Cross-triggering Prerequisites section.

2. Open the Debugger configuration and edit DTSL options to enable FPGA cross-triggering HPS as shown in the Enabling Cross-triggering on HPS section.

  • Check the Enable FPGA -> HPS Cross Triggering check box.
  • Un-check the Enable HPS-> FPGA Cross Triggering check box if checked.
  • Check the Assume Cross Triggers can be accessed check box.

3. Start the debug session by clicking Debug in the Debug Configuration dialog box. The debugger will stop the Linux kernel and display the current HPS state.

4. In Signal Tap II, configure a trigger on the fpga_dispw_pio[0] signal to trigger at any edge, by right clicking the corresponding cell in the Trigger Condition column

Ct-trigger-on-dispswitch.png

5. In Signal Tap II, configure the Trigger out to be sent to HPS, so that the SignalTap II sends the trigger to HPS whenever it performs an acquisition.

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

6. In Signal Tap II, configure the Trigger in to be disabled by setting its pattern to Don't Care. In this scenario we do not want the HPS to trigger FPGA.

Ct-disable-hps-trigger-in.png

7. In Eclipse debugger, let the Linux kernel continue running, by pressing the green Continue button or pressing F8.

8. In SignalTap II, press the Run Analysis button to arm Signal Tap:

Ct-run-analysis.png

9. SignalTap II will run the analysis and wait for the trigger from the DIP switch:

Ct-acquisition-in-progress.png

10.Change the state of the FPGA DIP switch 0 (SW1.5 on the board). This will trigger a Signal Tap II acquisition and stop Signal Tap II. This will be indicated by the status changing back to Ready to acquire.

Ct-dipswitch-toggled.png

Note: On the Data tab, you will be able to see the change on the DIP switch signal.

11.Go back to the Eclipse debugger; you will notice the execution has stopped. When SignalTap II is triggered, caused by a state change of the DIP switch, it sends the trigger to HPS, which in turn stops the cores, as instructed.

HPS Triggering FPGA Example

This section presents an example on how stopping HPS execution in the debugger can trigger FPGA to perform a SignalTap II acquisition. This can be useful, for example, if we want to see the state of some FPGA signals at the time the HPS is stopped in the debugger.

The required steps are to reproduce this scenario: 1. Perform the steps from the Cross-triggering Prerequisites section.

2. Open the Debugger configuration and edit DTSL options to enable FPGA cross-triggering HPS as shown in the Enabling Cross-triggering on HPS section.

  • Un-check the Enable FPGA -> HPS Cross Triggering check box.
  • Check the Enable HPS-> FPGA Cross Triggering check box if checked.
  • Check the Assume Cross Triggers can be accessed check box.

3. Start the debug session by clicking Debug in the Debug Configuration dialog box. The debugger will stop the Linux kernel and display the current HPS state.

4. In Signal Tap II, make sure all trigger signals are disabled by setting their condition to Don't care.

Ct-trigger-signals-disabled.png

5. In Signal Tap II, configure the Trigger in to be sensitive to both edges, so that the SignalTap II sends the trigger to HPS whenever it performs an acquisition.

Ct-configure-trigger-in.png

6. In Eclipse debugger, let the Linux kernel continue running, by pressing the green Continue button or pressing F8.

7. In SignalTap II, press the Run Analysis button to arm Signal Tap:

Ct-run-analysis.png

8. SignalTap II will run the analysis and wait for the trigger from HPS:

Ct-acquisition-in-progress.png

9. In Eclipse debugger, click the Interrupt button or press F9. This will stop the cores and send the trigger to FPGA.

10. SignalTap II will detect the trigger from HPS, perform an acquisition and stop. This will be indicated by the status changing back to Ready to acquire.

Getting Started with Streamline

ARM DS-5 Streamline performance analyzer is a GUI that brings together performance metrics, statistical profiling and power measurement in a system dashboard.You can quickly identify code hotspots, bottlenecks and other unintended effects of your code or the system architecture. This section presents how to launch the GUI, basic setup and how to capture data. For a more detailed instruction on viewing and using the data, please refer to the Streamline User Guide from ARM.

Before launching Streamlne, please finish the following steps:

1. Execute the Configuring Linux.

2. Execute the Setting up Remote System Explorer.

3. In the “Remote Systems” view, right click on “Ssh Terminal” under the connection you just built and then choose Launch Terminal. This will launch a terminal where we can run an application.

4. Run the gator to collect data for Streamline. If you used the sd card image from SoC EDS and have Linux booted, the gator should be running now. You don’t need to run it again.

Launch ssh terminal.png

In Eclipse Workspace, select Window > Show View > Other and then select “Streamline Data”. Click OK and the view will be displayed. From DS-5 5.23.1, Streamline is separated from Eclipse. Click “Launch Streamline” button to launch it.

Show streamline view.png

Launch streamline.png

Type the IP address of your board connection into the field, then click the “Counter Configuration” button Counter configuration button.png. You can import a script to describe events you want to collect or you can just simply click “Save” to load default events.

Counter configuration.png

Select “Start Capture” Start capture button.png. A window will pop up. Select a file name for the Streamline Capture File and then “Save”. Streamline will begin collecting data. Wait for a few seconds and then select “Stop Capture” Stop capture button.png to make sure that it is working. The result should look like this:

Streamline capture.png

This Timeline view has charts showing the values of each counter in the top half, and details of process execution in the bottom half. The data is not very interesting since we are not running any applications. Now we are going to run the Hello World Linux application to see what will happen.

In the ssh Terminal. Type “ls” to check if there is an executable called “hello”. If not, copy the executable you built in Getting Started with Linux Application Debugging to the root file system. If it’s not executable, type “chmod a+x hello” to change it.

Chmod.png

In Streamline, click “Start Capture”. Give it a new name. Then run the application by typing “./hello” in the ssh Terminal. Then go back to the Streamline and click “Stop”. The result should look like this:

Streamline capture2.png

Notice that here a new process called “hello” is added to the bottom panel. You can filter the counter data for each thread or process by clicking on it. The following picture shows the data when “hello” is executed.

Streamline capture2 read data.png

Personal tools