Introduction

The Intel SoC FPGA Hardware Library (HWLIB) was created to address the needs of low-level software programmers requiring full access to the configuration and control facilities of SoC FPGA hardware.

The HWLIB is a software library architecturally comprised of two functional components:

• SoC Abstraction Layer (SoCAL)
• HW Manager

SoC Abstraction Layer (SoCAL)

The HWLIB provides a symbolic register abstraction layer SoC Abstraction Layer (SoCAL) that enables direct access and control of HPS device registers within the address space. This layer is necessary for enabling several key stakeholders (boot loader developers, driver developers, BSP developers, debug agent developers, and board bring-up engineers) requiring a precise degree of access and control of the hardware resources.

The SoCAL provides the benefits of:

• A logical interface abstraction to the HPS physical devices and registers including the bit-fields comprising them.
• A loosely coupled software interface to the underlying hardware that promotes software isolation from hardware changes in the system address map and device register bit field layouts.

Hardware Manager (HW Manager)

The HWLIB component provides a group of functional APIs that address more complex configuration and operational control aspects of selected HPS resources. The HW Manager functions are implemented using elemental operations provided by the SoCAL API to implement more complex functional capabilities and services. The HW Manager functions may also be implemented by the compound application of other functions in the HW Manager API to build more complex operations (for example, software controlled configuration of the FPGA).

HW Manager functions have the following characteristics:

• Functions employ a combination of low-level device operations provided by the SoCAL executed in a specific sequence to effect a desired operation.
• Functions may employ cross functional (such as from different IP blocks) device operations to implement a desired effect.
• Functions may have to satisfy specific timing constraints for the application of operations and validation of expected device responses.
• Functions provide a level of user protection and error diagnostics through parameter constraint and validation checks.

Hardware Library Reference Documentation

Hwlibs documentation is available here

Resources Required

Resource	Link
Quartus Prime Pro 20.3 (For Stratix 10, Arria 10)	https://fpgasoftware.intel.com/20.3/?edition=pro
Quartus Prime Std 20.1 (For Cyclone V, Arria V)	https://fpgasoftware.intel.com/20.1/?edition=standard
SoCEDS Std 20.1 ( For Cyclone V, Arria V)	https://fpgasoftware.intel.com/soceds/20.1/?edition=standard
Uboot	https://github.com/altera-opensource/u-boot-socfpga
HWLibs	https://github.com/altera-opensource/intel-socfpga-hwlib
ARM DS	https://fpgasoftware.intel.com/armds/

Installation

Linux Installation

Setup HWLibs

1. Launch terminal.

2. Run command below to clone HWLibs repository.

$git clone https://github.com/altera-opensource/intel-socfpga-hwlib

3. Go to tools folder

$cd intel-socfpga-hwlib/tools

Note: Use Linaro compiler version 7.2.0 instead of 11.2. Newer version will result in error during debugging.

4. Run install_linaro.sh. This script will setup Linaro toolchain, newlib and cygwin in your system.

$./install_linaro.sh

ARM DS Installation

1. Download Arm DS installer archive from https://fpgasoftware.intel.com/armds/. Current version is 2020.1 and the filename is called DS000-BN-00001-r20p1-00rel1.tgz.

2. Extract the archive and run the installer as root

tar xf DS000-BN-00001-r20p1-00rel1.tgz
cd DS000-BN-00001-r20p1-00rel1/
sudo ./armds-2020.1.sh

3. The installer will show the licensing agreement. Scroll using the spacebar until the end of the license the type "yes" and press Enter

Please answer with one of: 'yes' or 'no/quit'
Do you agree to the above terms and conditions? yes

4. Press Enter to run the platform requirements check.

Please answer with one of: 'yes/y' or 'no/n'
Run installation platform requirement checks? [default: yes] 
--- Running installation platform requirement checks
Running dependency check [succeeded]

5. Leave the default installation path (unless you want to change it) and press Enter.

Where would you like to install to? [default: /opt/arm/developmentstudio-2020.1]

6. Press Enter to allow the new folder to be created:

Please answer with one of: 'yes/y' or 'no/n'
'/opt/arm/developmentstudio-2020.1' does not exist, create? [default: yes] 
--- Installing to '/opt/arm/developmentstudio-2020.1' (This may take a while...)

7. Press Enter to allow the desktop menus to be added.

Please answer with one of: 'yes/y' or 'no/n'
Install desktop menu item additions? [default: yes] 
--- Installing menu entries

8. Press Enter to allow the drivers to be installed.

Post install stage provides the following functions:
- Installation of USB drivers for RealView ICE and DSTREAM hardware units
Please answer with one of: 'yes/y' or 'no/n'
Run post install setup scripts? [default: yes] 
--- Running post install setup scripts

9. Successful installation will result in the following message:

-----------------------------------
Installation completed successfully
-----------------------------------

To start using Arm Development Studio 2020.1 either:
- Create a suite sub-shell using /opt/arm/developmentstudio-2020.1/bin/suite_exec 
- Launch GUI tools via their desktop menu entries

The Release notes for the product can be found here: file:///opt/arm/developmentstudio-2020.1/sw/info/readme.html

Windows Installation

Setup HWLibs

For Windows user, please install MSYS2 Shell at this link and git for windows at this link manually.

1. After you have done the installation, launch MSYS2 Shell and run command below to install required package in MSYS2 shell.

$pacman -S --needed make gcc git

msys2_setup

2. Run command below to clone HWLibs repository.

$git clone https://github.com/altera-opensource/intel-socfpga-hwlib

3. Go to tools folder

$cd intel-socfpga-hwlib/tools

Note: Use Linaro compiler version 7.2.0 instead of 11.2. Newer version will result in error during debugging.

4. Run install_linaro.sh. This script will setup Linaro toolchain, newlib and cygwin in your system.

$./install_linaro.sh

ARM DS Installation

1. Download Arm DS Windows installer from https://fpgasoftware.intel.com/armds/. Current version is 2020.1. The filename is DS000-BN-00000-r20p1-00rel1.zip.

2. Unzip the file and run armds-2020.1.exe to start the installation.

armds_setup_1

armds_setup_2

3. Install the required drivers.

armds_driver_installation_1

ARM DS Licensing

Please refer to here for ARM DS Licensing.

The only SoC EDS component which requires a license is the Arm DS Intel SoC FPGA Edition. Two license options are available:

• Arm DS Intel SoC FPGA Edition License
• 30-day Evaluation of Arm DS Intel SoC FPGA Edition License

Refer to Arm DS Intel® SoC FPGA Edition Toolkit for details about DS features, and editions, including licensing.

Getting the License

Follow the steps below to get the License:

For Arm DS Intel SoC FPGA Edition License - If you have purchased a SoC development kit or a stand-alone license for DS Intel SoC FPGA Edition AE, then you have already received an Arm license serial number. This is a 15-digit alphanumeric string with two dashes in between. Use this serial number to activate your license in DS Intel SoC FPGA Edition, as shown in the "Activating the License" section.

For 30-Day Evaluation of DS-5 Intel SoC FPGA Edition License - If you want to evaluate the DS Intel SoC FPGA Edition, you can get a 30-Day Evaluation activation code by going to Arm DS Intel® SoC FPGA Edition Toolkit then clicking on Activate license code for Arm DS.

Activating the License

This section presents how to activate and apply the license.

1. Go to ARM Licensing Portal to generate a license file based on the license code you got with your Development Kit.

2. Start DS IDE

3. First time it is run it will ask you to add a product license. Select Add product license and click Next.

5. Select License File and browse to the place where you stored your generated license. Click Next.

6. The Arm Development Studio Intel FPGA Edition license will be selected. Click Next to activate it.

7. License will be activated. Click Finish to complete the process.

Peripherals support in HWLibs

No	Peripheral	Cyclone V/Arria V	Arria 10	Stratix 10
1	CAN	Cyclone V only	-	-
2	Cache	Yes	Yes	Yes
3	CCU	-	-	-
4	Clock Manager	Yes	Yes	Yes
5	DMA=330	Yes	Yes	Yes
6	Ethernet	-	Yes	Yes
7	FPGA Bridges (LWH2F, H2F)	Yes	Yes	-
8	FPGA Bridges (F2S)	Yes	Yes	-
9	FPGA Config	Yes	Yes	-
10	GPIO	Yes	Yes	Yes
11	HPS Cold Reset	Yes	Yes	-
12	HPS Warm Reset (SW)	-	Yes	-
13	I2C	Yes	Yes	Yes
14	Mailbox	-	-	-
15	NAND	Yes	Yes	-
16	OCRAM ECC	Yes	Yes	-
17	PR	-	-	-
18	QSPI	Yes	Yes	-
19	Reset Manager	Yes	Yes	Yes
20	RSU	-	-	-
21	SDMMC	Yes	Yes	Yes
22	SDRAM	Yes	Yes	Yes
23	SDRAM ECC	Yes	Yes	-
24	SMMU	-	-	-
25	SPI	Yes	Yes	Yes
26	DW Timer	Yes	Yes	Yes
27	UART	Yes	Yes	Yes
28	USB	-	-	-
29	Watchdog	Yes	Yes	Yes

Software Examples in HWLibs

1. Software examples are located in /intel-socfpga-hwlib/examples folder and are arranged according to FPGA family CVAV, A10 and S10.

2. Below are the software examples available for each of the device family.

Device Family	Examples available	Compiler
CVAV	Altera-SoCFPGA-HelloWorld-Baremetal	ARMCC
^	Altera-SoCFPGA-HardwareLib-16550-CV	GNU, ARMCC
^	Altera-SoCFPGA-HardwareLib-ECCL2-CV	GNU, ARMCC
^	Altera-SoCFPGA-HardwareLib-FPGA-CV	GNU, ARMCC
^	Altera-SoCFPGA-HardwareLib-Timer-CV	GNU, ARMCC
^	Altera-SoCFPGA-HardwareLib-Timer-AV	GNU, ARMCC
A10	Altera-SoCFPGA-HelloWorld-Baremetal-A10	GNU, ARMCC, ARMClang
^	Altera-SoCFPGA-HardwareLib-Timer-A10	GNU, ARMCC, ARMClang
S10	Altera-SoCFPGA-HelloWorld-Baremetal-S10	ARMClang

3. To compile the example, simply go into the example folder and run

$make

4. There are 2 switches that user can specify in the makefile – SEMIHOSTED and MEMORY. Example of running make command.

• Setting application to run on On-Chip RAM and enable semihosting (print to ARM DS console)

  $make SEMIHOSTED=1 and MEMORY=ocr

• Setting application to run on DDR and disable semihosting (print to UART). In order to use UART and DDR, there is a pre-requisite to load Uboot SPL.

  $make SEMIHOSTED=0 and MEMORY=ddr

5. Table below shows pre-requisites and expected output

SEMIHOSTED	MEMORY	Pre-requisite to load Uboot SPL	Output
0	OCR	Yes, for UART setup	Print to UART
0	DDR	Yes, for DDR calibration	Print to UART
1	OCR	No, no UART nor DDR is used	Print to ARM DS console
1	DDR	Yes, for DDR calibration	Print to ARM DS console

Running Arria 10 HWLib Example

The following are covered:

• Configuring the FPGA: In Arria 10, FPGA needs to be configured first in order to bring up HPS DDR
• Running U-Boot SPL: SPL needs to be ran to initialize hardware and bring up HPS DDR
• Running Arria 10 Timer Application: importing, building and running the sample application

Configuring FPGA

Arria 10 GHRD sof can be obtained in Arria 10 GSRD Release Contents

Note: You need to install Quartus Programmer to configure FPGA.

Launch terminal and run command below to configure FPGA.

$quartus_pgm -c 1 -m jtag -o ghrd_10as066n2.sof

Compiling Uboot

Arria 10 GHRD Quartus project can be obtained here

Launch terminal and run command below to untar the Quartus project

mkdir a10_soc_devkit_ghrd
tar -xzvf a10_soc_devkit_pro_ghrd_ACDS-20.3pro-20.1std.tar.gz -C a10_soc_devkit_ghrd/ 

Run commands below to compile Uboot

# Generate U-Boot device tree
cd /a10_soc_devkit_ghrd/
mkdir -p software/bootloader
cd software/bootloader

# Get the U-Boot sourece code
git clone https://github.com/altera-opensource/u-boot-socfpga
cd u-boot-socfpga
git checkout -b test -t origin/socfpga_v2020.07

# Generate DTS include file based on the handoff file
./arch/arm/mach-socfpga/qts-filter-a10.sh \
../../../hps_isw_handoff/hps.xml \
arch/arm/dts/socfpga_arria10_socdk_sdmmc_handoff.h

# Build U-Boot
export CROSS_COMPILE=arm-eabi-
make socfpga_arria10_defconfig
make -j 24

The following files are created in /u-boot-socfpga:

• spl/u-boot-spl - SPL executable
• spl/u-boot-spl-dtb.bin - SPL device tree
• u-boot - U-Boot executable
• u-boot-dtb.bin - U-Boot device tree
• u-boot-with-spl.sfp - flash image file with 4 x SPL + U-Boot image

Creating SPL and Uboot debug script

Create SPL debug script

cat <<EOT > ../debug-spl.ds

# initialize system
reset hardware
stop
wait 5s
set trust-ro-sections-for-opcodes off

# load spl and run up until the warm reset
loadfile \$sdir/u-boot-socfpga/spl/u-boot-spl 0x0
start
wait
restore \$sdir/u-boot-socfpga/spl/u-boot-spl.dtb.bin binary 0xffe00000
thbreak *0x0
continue
wait 60s

# load spl again and run up until spl_boot_device
loadfile \$sdir/u-boot-socfpga/spl/u-boot-spl 0x0
start
wait
restore \$sdir/u-boot-socfpga/spl/u-boot-spl.dtb.bin binary 0xffe00000
thbreak spl_boot_device
continue
wait 20s

EOT

Create U-Boot debug script

cat <<EOT > ../debug-u-boot.ds

# initialize system
stop
wait 5s
reset
stop
wait 5s
set trust-ro-sections-for-opcodes off

# load spl and run up until the warm reset
loadfile \$sdir/u-boot-socfpga/spl/u-boot-spl 0x0
start
wait
restore \$sdir/u-boot-socfpga/spl/u-boot-spl.dtb binary &__bss_end
thbreak *0x0
continue
wait 60s

# load spl again and run up until spl_boot_device
loadfile \$sdir/u-boot-socfpga/spl/u-boot-spl 0x0
start
wait
restore \$sdir/u-boot-socfpga/spl/u-boot-spl.dtb binary &__bss_end
thbreak spl_boot_device
continue
wait 60s

# load u-boot and run up to board_init_r
delete
loadfile \$sdir/u-boot-socfpga/u-boot
start 
wait
restore \$sdir/u-boot-socfpga/u-boot.dtb binary &_end
tbreak relocate_code
cont
wait 60s
symbol-file "\$sdir/u-boot-socfpga/u-boot" ((gd_t*)\$r9)->reloc_off
thbreak board_init_r
continue
wait 60s

EOT

Running Arria 10 Timer Example

1. Launch the terminal.

2. Go to folder /intel-fpga-hwlib/examples/A10/Altera-SoCFPGA-HardwareLib-Timer-A10-GNU

3. In Makefile, there is a parameter SEMIHOSTED ?= 1 which means Semihosting is enabled. With this setting, output will be printed on ARM DS Console.

4. If you want to change output printing to UART, specify SEMIHOSTED ?= 0. You need to load and run SPL to initialize UART.

5. Another parameter MEMORY ?= ocr means the application is set to run on On-Chip RAM.

6. If you want to run on DDR, specify MEMORY ?= ddr. You need to load and run SPL to initialize DDR.

7. Run $make to build the application image (application.axf).

8. Launch ARM DS IDE with command $armds_ide &.

9. In ARM DS Eclipse IDE, go to Run > Debug Configurations to open the Debug Configurations window. Right click Generic Arm C/C++ Application > New

10. In Connection Tab:

• Select target to be Intel SoC FPGA > Arria 10 SoC > Bare Metal Debug > Debug Cortex-A9_0
• Select target connection.

11. If application is set to run on DDR or print to UART, you need to run debug-spl.ds script created above to load and run spl. Steps 11 to 14 can be skipped if the application is set to run on On-Chip RAM and with Semihosting enabled.

12. To run debug-spl.ds. In Debugger Tab:

• Select Run control to be Connect Only
• Check Run debug initialization debugger script, and click the File System icon to browse for the script /a10_soc_devkit_ghrd/software/bootloader/debug-spl.ds
• Click Debug button

13. Serial console will display that SPL ran fine and calibrated DDR successfully.

14. DS debugger will show SPL stopped on the spl_boot_device function

15. Create a new debug configuration for application by going to Run > Debug Configurations to open the Debug Configurations window. Right click Generic Arm C/C++ Application > New * Select target to be Intel SoC FPGA > Arria 10 SoC > Bare Metal Debug > Debug Cortex-A9_0 * Select target connection.

16. In Files tab, go to Target Configuration > Application on host to download: to select and load application.axf image and click Debug.

17. Result is printed on the serial console.

Running Cyclone V HWLib Example

Compiling U-Boot

Cyclone V GHRD Quartus project can be obtained in Cyclone V GSRD Release Contents

Launch terminal and run command below to untar the Quartus project

mkdir cv_soc_devkit_ghrd
tar -xzvf cv_soc_devkit_ghrd.tar.gz -C cv_soc_devkit_ghrd/

Launch Embedded Command Shell

~/intelFPGA/20.1/embedded/embedded_command_shell.sh

Run commands below to compile Uboot

# Convert handoff data to source code
cd /cv_soc_devkit_ghrd
mkdir -p software/bootloader
bsp-create-settings \
	--type spl \
	--bsp-dir software/bootloader \
	--preloader-settings-dir "hps_isw_handoff/soc_system_hps_0" \
	--settings software/bootloader/settings.bsp

# Get the U-Boot source code
cd software/bootloader
git clone https://github.com/altera-opensource/u-boot-socfpga
cd u-boot-socfpga
git checkout -b test -t origin/socfpga_v2020.07

# Run the qts_filter to take the sources from the handoff 
# folder and the ones generated by bsp-create-settings, 
# format them appropriately and copy them to the U-Boot source code
./arch/arm/mach-socfpga/qts-filter.sh cyclone5 ../../../ ../ ./board/altera/cyclone5-socdk/qts/

# Build U-Boot
export CROSS_COMPILE=arm-eabi-
make socfpga_cyclone5_defconfig
make -j 24

The following files are created in /u-boot-socfpga:

• spl/u-boot-spl - SPL executable
• u-boot - U-Boot executable
• u-boot-with-spl.sfp - Bootable file: four copies of SPL and one copy on U-Boot image

Creating SPL and Uboot debug script

Create SPL debug script

cat <<EOT > ../debug-spl.ds
stop
wait 5s
reset
stop
wait 5s
set trust-ro-sections-for-opcodes off
loadfile \$sdir/u-boot-socfpga/spl/u-boot-spl 0x0
start
wait
restore \$sdir/u-boot-socfpga/spl/u-boot-spl.dtb binary &__bss_end
tbreak spl_boot_device
continue
wait 60s

EOT

Create U-Boot debug script

cat <<EOT > ../debug-u-boot.ds
stop
wait 5s
reset
stop
wait 5s
set trust-ro-sections-for-opcodes off
loadfile \$sdir/u-boot-socfpga/spl/u-boot-spl 0x0
start
wait
restore \$sdir/u-boot-socfpga/spl/u-boot-spl.dtb binary &__bss_end
tbreak spl_boot_device
continue
wait 60s
delete
loadfile \$sdir/u-boot-socfpga/u-boot
start 
wait
restore \$sdir/u-boot-socfpga/u-boot.dtb binary &_end
tbreak relocate_code
cont
wait 60s
symbol-file "\$sdir/u-boot-socfpga/u-boot" ((gd_t*)\$r9)->reloc_off
thbreak board_init_r
cont
wait 60s

EOT

Running Cyclone V Timer Example

1. Launch the terminal.

2. Go to folder /intel-fpga-hwlib/examples/CVAV/Altera-SoCFPGA-HardwareLib-Timer-CV-GNU

3. In Makefile, there is a parameter SEMIHOSTED ?= 1 which means Semihosting is enabled. With this setting, output will be printed on ARM DS Console.

4. If you want to change output printing to UART, specify SEMIHOSTED ?= 0. You need to load and run SPL to initialize UART.

5. Another parameter MEMORY ?= ocr means the application is set to run on On-Chip RAM.

6. If you want to run on DDR, specify MEMORY ?= ddr. You need to load and run SPL to initialize DDR.

7. Run $make to build the application image (application.axf).

8. Launch ARM DS IDE with command $armds_ide &.

9. In ARM DS Eclipse IDE, go to Run > Debug Configurations to open the Debug Configurations window. Right click Generic Arm C/C++ Application > New

10. In Connection Tab:

• Select target to be Altera > Cyclone V SoC (Dual Core) > Bare Metal Debug > Debug Cortex-A9_0
• Select target connection.

11. If application is set to run on DDR or print to UART, you need to run debug-spl.ds script created above to load and run spl. Steps 11 to 14 can be skipped if the application is set to run on On-Chip RAM and with Semihosting enabled.

12. To run debug-spl.ds. In Debugger Tab:

• Select Run control to be Connect Only
• Check Run debug initialization debugger script, and click the File System icon to browse for the script /cv_soc_devkit_ghrd/software/bootloader/debug-spl.ds
• Click Debug button

13. Serial console will display that SPL ran fine and calibrated DDR successfully.

14. DS debugger will show SPL stopped on the spl_boot_device function

15. Create a new debug configuration for application by going to Run > Debug Configurations to open the Debug Configurations window. Right click Generic Arm C/C++ Application > New * Select target to be Altera > Cyclone V SoC (Dual Core) > Bare Metal Debug > Debug Cortex-A9_0 * Select target connection.

16. In Files tab, go to Target Configuration > Application on host to download: to select and load application.axf image and click Debug.

17. Result is printed on the serial console.