Intel Arria 10 SoC UEFI Boot Loader User Guide

RSS

UG-20100 | 2017.12.15

Intel Arria 10 SoC UEFI Boot Loader User Guide

This document provides instructions on how to use the Unified Extensible Firmware Interface (UEFI) boot loader for Intel^® Arria^® 10 SoC as a second stage boot loader.

The instructions in this document summarize how to:

Recompile the hardware design that comes with your Intel^® Arria^® 10 SoC Embedded Development Suite (EDS) 15.0.1.
Generate and build both the UEFI boot loader and UEFI boot loader device tree.
Program the UEFI boot loader image into the QSPI or SD/MMC card.
Program the HPS to load an real-time operating system (RTOS) or bare-metal application directly from flash devices at board power-on.

Acronyms and Definitions

Table 1. UEFI Boot Loader User Guide Acronyms and Definitions
Acronym or Term	Definition
AXF	Object file format generated by Arm^® compiler that contains both object code and debug information. File extension is .axf.
BSP	Board support package
CRC	Cyclical redundancy check
DDR4	DDR4 SDRAM; an abbreviation for double data rate fourth generation synchronous dynamic random-access memory.
DTB	Device tree blob. File extension is .dtb.
DTS	Device tree source. File extension is .dts.
DS-5	Arm^® Development Studio 5^® (DS-5^®) Intel^® SoC FPGA Edition; an end-to-end suite of tools for embedded C/C++ software development on any Intel^® SoC FPGA. The tool combines the features of the Arm^® DS-5^® Intel^® SoC FPGA Edition with powerful FPGA debugging capabilities, providing unmatched visibility and control of your SoC FPGA. The SoC FPGA Embedded Design Suite (EDS) installs the Arm^® Development Studio 5^® (DS-5^®) Intel^® SoC FPGA Edition.
ELF	Executable and linkable format; a common standard file format for executables, object code, shared libraries and core dumps. File extenstion is .elf.
FPGA	Field programmable gate array
FTDI	Future technology devices international; a Scottish, privately held semiconductor device company specializing in Universal Serial Bus (USB) technology.
GHRD	Golden hardware reference design
GSRD	Golden system reference design
INF	EDK tool module information (INF) file
I/O	Input and output
JTAG	Joint Test Action Group; a software development and debug port
LED	light emitting diode
MKPIMAGE	The second-stage boot loader (SSBL) image tool; this tool creates a boot ROM compatible image of the Intel^® boot loader. The mkpimage tool generates the header and CRC checksum and inserts them into the output image with the SSBL program image and its exception vector.
OCRAM	on-chip RAM
PEI (UEFI)	UEFI pre-EFI initialization phase
RTOS	Real-time operating system
QSPI	Quad serial peripheral interface
Platform Designer	A system integration tool that is included as part of Intel^® Quartus^® Prime software. Platform Designer captures system-level hardware designs at a high level of abstraction and also automates the task of defining and integrating custom HDL design blocks, commonly referred to as design modules, IP cores, or components.
Intel^® Quartus^® Prime	A programmable logic design software produced by Intel^® . You can analyze and synthesize HDL designs using Intel^® Quartus^® Prime.
RBF	Raw binary file. Contains configuration data for use outside of the Intel^® Quartus^® Prime software. A raw binary file contains the binary equivalent of a tabular text file (.ttf). File extension is .rbf.
SoC FPGA EDS	SoC FPGA Embedded Design Suite is a comprehensive tool suite for embedded software development of Intel^® SoC devices. The tool suite contains development tools, utility programs, run-time software and application examples that enable firmware and application software development on the Intel^® SoC hardware platform.
SOF	SRAM object file with a .sof file extension. The compiler's assembler module or the `makeprogfile` command line utility generates this binary file A .sof file contains the data for configuring all of the SRAM-based Intel^® devices supported by the Intel^® Quartus^® Prime software.
SPI	Serial peripheral interface
SRAM	Static random access memory
UART	Universal asynchronous receiver and transmitter
UEFI	The Unified Extensible Firmware Interface (UEFI) is a specification that defines a software interface between an operating system and platform firmware. UEFI replaces the Basic Input/Output System (BIOS) firmware interface, originally present in all IBM^® PC-compatible personal computers. In practice, most UEFI firmware images provide legacy support for BIOS services. UEFI can support remote diagnostics and repair of computers, even without another operating system.
USB	Universal serial bus

Recommended System Requirements

To load and execute the Intel^® Stratix^® 10 SoC Unified Extensible Firmware Interface (UEFI) boot loader, your system must meet the following requirements.

Minimum Hardware Requirements

Windows^® PC or Linux^® workstation with the following configuration:
- Serial termination (Minicom for Linux^® and Tera Term for Windows^®)
- Micro SD card slot or Micro SD card writer or SD capable writer with SD to micro SD converter
Intel^® Arria^® 10 SoC development board revision A.1 or A.2. Alternatively, you can use Intel^® Arria^® 10 SoC development board revision B.1 with:
- DDR4 memory card
- Boot MicroSD flash daughter card (6XX-44320R) or Boot QSPI flash daughter card (6XX-44334R)

Minimum Software Requirements

Table 2. SoC FPGA Embedded Design Suite and Intel^® Quartus^® Prime Version
Intel^® Arria^® 10 SoC Development Board	SoC FPGA Embedded Design Suite	Git Tag of socfpga_udk2015 Branch
RevA.1 or A.2	v15.0.1 or 15.1	`tags/rel_socfpga_arria10_soceds_15.0.1`
RevB.1	v15.1.1	`tags/rel_socfpga_arria10_soceds_15.1.1`
RevC1	v16.0	`tags/rel_socfpga_arria10_soceds_16.0`

Installation Folders

The default installation folder for the Intel^® Quartus^® Prime Pro Edition Programmer and tools are:

Table 3. Quartus Installation Directory
Intel^® Quartus^® Prime Pro Edition Installation Directory	Description
`c:\altera\15.1.1\qprogrammer` on Windows^® `~/altera/15.1.1/qprogrammer` on Linux^®	Intel^® Quartus^® Prime Pro Edition Programmer installation path
`c:\altera\15.1.1\quartus` on Windows^® `~/altera/15.1.1/quartus` on Linux^®	Intel^® Quartus^® Prime Pro Edition installation path

The default installation folders for the SoC FPGA EDS are:

Table 4. SoC FPGA EDS Installation Directory
Intel^® Quartus^® Prime Pro Edition Installation Directory	Description
`c:\altera\15.1.1\qprogrammer` on Windows^® `~/altera/15.1.1/embedded` on Linux^®	SoC FPGA EDS Programmer installation path
`c:\altera\15.1.1\embedded\examples\hardware` on Windows^® `~/altera/15.1.1/embedded\examples\hardware` on Linux^®	SoC FPGA EDS hardware examples path

Throughout this document <Quartus_Installation_Directory> denotes the installation location for the Intel^® Quartus^® Prime Pro Edition tools. <SoCEDS_Installation_Directory> denotes the installation location of the SoC FPGA EDS.

Boot Flow Overview

A typical UEFI boot flow runs entirely on the on-chip memory of the HPS and is a default selection for booting a bare-metal application and RTOS. UEFI replaces the MPL boot loader on Cyclone^® V and Arria^® V devices.

UEFI boot loader tasks include:

Initializing DDR SDRAM memory
Configuring low level hardware such as PLL, IOs, and pin-muxing
Supporting basic hardware diagnostic features
Fetching subsequent boot software such as the operating system package or kernel image.

Figure 1. Typical UEFI Boot Flow

Pre-DDR diagnostic boot flow boots into a diagnostic utility called Pit Stop. This utility executes from the on-chip memory of the HPS and debugs and performs diagnosis prior to booting the next stage. The PcdEnablePitStopUtility token in the Arria10SoCPkg.dsc file enables the Pit Stop utility.

Figure 2. Pre-DDR Diagnostic Boot Flow

Post-DDR boot stage, also known as UEFI DXE phase, supports extended UEFI functionality. This boot flow allows you to access a broad range of pre-existing UEFI utilities already developed by the open source community.

Booting the DXE phase requires DDR SDRAM to be ready. In the post-DDR extended boot flow, you can boot into the UEFI shell to access features such as TFTP file transfer, scripting and running your UEFI applications. You can continue to boot after the UEFI shell by using commands such as:

runaxf to boot to an ELF binary
Linux Loader to continue booting in Linux

Note: SoC FPGA EDS 16.0 and above supports booting Linux.

Figure 3. Post-DDR Extended Boot Flow

Getting Started

Compiling the Hardware Design

Task Time: 30 Minutes

If you make any changes, you must re-compile the design that is packaged in the SoC FPGA EDS. Otherwise, you can directly work with the pre-compiled design. As an example, the following sections describe how to compile the hardware design packaged in the SoC FPGA EDS.

Open a Intel Quartus Prime Project

Open a Nios II command shell.

Make a copy of the GHRD into your working directory:

$ cd /cygdrive/<your_working_directory>

$ cp -r /cygdrive/c/altera/16.0/embedded/examples/hardware/a10_soc_devkit_ghrd/ .

$ cd a10_soc_devkit_ghrd

Figure 4. Copying GHRD to Working Directory

Delete the pre-built output, software handoff, GHRD and boot loader files. These files are regenerated when you re-compile the hardware design.
```
$ rm -rf output_files/ software/ hps_isw_handoff/ ghrd_10as066n2/ software/bootloader sd_fat.tar.gz
```
Launch Intel^® Quartus^® Prime.
```
$quartus &
```
Open the hardware project in Intel^® Quartus^® Prime by selecting File > Open Project.

Figure 5. Open Project File
Browse to the ~a10_soc_devkit_ghrd folder.
Select the ghrd_10as066n2.qpf project file and click Open.

Figure 6. Open Project File

Intel^® Quartus^® Prime loads the project.

Generate the System in Platform Designer

In Intel^® Quartus^® Prime, select Tools > Qsys from the menu bar to start the Platform Designer tool.

Figure 7. Opening the Platform Designer Tool

An Open file dialog box appears.
Select the ~/a10_soc_devkit_ghrd/ghrd_10as066n2.qsys file and click Open.

Figure 8. Opening a Project from the Dialog Box

Platform Designer loads the project and displays the system.
Figure 9. Loading the Platform Designer Project
Click the Generate HDL... button on the bottom right corner of the window.
When the Generation dialog box appears, click the Generate button.

Figure 10. Generation Window

Platform Designer generates the system and a Generate Completed window appears.
Click Close to get back to the main Platform Designer window.
Click Finish in the lower right corner to close the Platform Designer window and return to the main Intel^® Quartus^® Prime window.

Compile the Design in Intel Quartus Prime

Compile the project in Intel^® Quartus^® Prime by selecting Processing > Start Compilation from the main menu.

Figure 11. Starting the Design Compilation

On completion, Intel^® Quartus^® Prime displays a compilation status in the Messages window below.

Figure 12. Compilation Messages and Status Window

The compilation process generates these files:

Table 5. Compilation Output Files
File	Description
`~/a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.sof`	FPGA configuration file
`~/a10_soc_devkit_ghrd/hps_isw_handoff`	Handoff folder containing XML files for generating the U-Boot device tree

Converting the Programming File

You must convert the SOF file produced by compiling the hardware design to the RBF format required by the UEFI boot loader. This section describes how to convert the SOF file into a single RBF file consisting of a combined CORE and PERIPH file. This section also describes how to convert the SOF file into two RBF files: a CORE file and separate a PERIPH file.

Note: You must generate two separate RBF files for SD card image generation. For QSPI image generation, you only need to generate the single RBF file that combines the CORE and PERIPH files.

Converting the SOF File into Two Split RBF Files

Splitting the SOF file creates two files:

Peripheral file (PERIPH): Configures the I/O
Core file (CORE): configures the FPGA fabric

Open an SoC FPGA EDS command shell.

Type the following command to convert the file:

$ quartus/bin/quartus_cpf -c --hps -o bitstream_compression=on
 <your_working directory>/a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.sof
 <your_working directory>/a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.rbf

Figure 13. SoC FPGA EDS File Conversion Command

The command creates the following files in your <your_working directory>/a10_soc_devkit_ghrd/output_files/ folder:

Table 6. Split RBF Files
File	Description
~ /a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.periph.rbf	I/O configuration file
~ /a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.core.rbf	FPGA fabric configuration file

Converting the SOF File into a Single RBF File

Different methods exist to convert the SOF into a single RBF file. The following two sections describe how to use the Intel^® Quartus^® Prime Pro Edition Programmer command line tools or the GUI converter to convert the programming file.

Single RBF Conversion Using the GUI Converter

Launch Intel^® Quartus^® Prime Pro Edition.
From the Intel^® Quartus^® Prime Pro Edition menu, select File > Convert Programming Files....

Figure 14. Convert Programming Files Selection
Select the Programming file type to be Raw Binary File (.rbf).

Figure 15. Programming File Type Selection
Select the Mode to be Passive Parallel x8 or Passive Parallel x16.

Figure 16. Selecting Mode
Click SOF Data and then click Add File....

Figure 17. Add SOF File
Browse to <your_working_directory>/a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.sof file and click Open.

Figure 18. Open SOF File
In the Conversion setup files window type ghrd_10as066n2.rbf in the File Name prompt.
Click the Close button to exit the Convert Programming File window.
These steps create a ghrd_10as066n2.rbf file in the <your_working_directory>/a10_soc_devkit_ghrd/output_files/ folder.

Single RBF Conversion Using the Intel Quartus Prime Pro Edition Programmer Command Line Tools

Open an SoC FPGA EDS command shell.
Type the following command to convert the file:
```
$ quartus/bin/quartus_cpf -c -o bitstream_compression=on
 <your_working directory>/a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.sof 
 <your_working directory>/a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.rbf
```
Figure 19. SoC FPGA EDS File Conversion Command
The command creates the following file: <your_working directory>/a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.rbf.

Generating the Boot Loader and Device Tree for UEFI Boot Loader

Task Time: 30 minutes

In this section, you generate a device tree in a Flattened Device Tree (FDT) binary format, DTB file. The UEFI build process uses this file to develop the hardware configuration.

Note: The boot loader and the kernel require different device trees for the Intel^® Arria^® 10 SoC. This section refers to the boot loader device tree.

The following figure represents an overview of the boot loader flow.

Figure 20. Boot Loader Flow

Generating the Boot Loader DTS File for 16.0 Release and Below

This section describes how to run the Boot Loader Generator (BSP Editor) in the Windows^® and Linux^® environments to generate the device tree.

A device tree is a data structure that describes the underlying hardware to a firmware or an operating system. The UEFI boot loader uses the device tree blob (DTB) to handle variations of hardware configuration without having to modify a single line of source code. This flexibility is particularly important for highly configurable Intel^® SoC FPGAs.

The device tree generator tool is a part of the SoC FPGA EDS and creates the device tree for SoC systems that contain FPGA designs created using Platform Designer. The generated device tree describes the HPS peripherals, selected FPGA soft IP and peripherals that are configuration dependent.

Windows Environment

Start an embedded command shell.

Figure 21. Open an Embedded Command Shell

Go to the a10_soc_devkit_ghrd folder.

$ cd <Working_Directory>/a10_soc_devkit_ghrd/

Start the BSP Editor.
```
$ bsp-editor&
```
In the BSP Editor window, select File > New HPS BSP... to open a new BSP window.
In the new BSP window:
1. Click the browse (…) button next to the Preloader Setting Directory text box and browse to the <your_working_directory>/a10_soc_devkit_ghrd/hps_isw_handoff folder.
2. Select the Operating system to be U-Boot Bootloader (Arria 10 HPS) in the pull-down menu.
3. Leave the Use default locations enabled to create the new BSP in the <your_working_directory>/a10_soc_devkit_ghrd/software/uboot_bsp folder.
4. Click OK to create the BSP settings file and close the New BSP window.
Figure 22. New BSP Window Settings
In the BSP Editor window, edit the BSP settings as follows:
- boot_device: Boot from SD/MMC (default)
- model: SOCFPGA Arria 10 Dev Kit (default)
- rbf_filename: ghrd_10as066n2.rbf (default was socfpga.rbf)
- peripheral_rbf_filename: periph.rbf (default)
- core_rbf_filename: core.rbf (default)
- disable_uboot_build: unchecked (default)
Figure 23. BSP Settings
In the BSP Editor window, click Generate in the lower right hand corner to produce the source code and the U-Boot device tree.
When the file generation is complete, click Close in the BSP Editor window.
The following files are generated in the <your_working_directory>//a10_soc_devkit_ghrd/software/uboot_bsp folder:
- config.mk
- devicetree.dts
- Makefile
- settings.bsp
- uboot.ds

Linux Environment

Start and embedded command shell and go to the a10_soc_devkit_ghrd folder.

$ ~/altera/16.0/embedded/embedded_command_shell.sh
$ cd <Working_Directory>/a10_soc_devkit_ghrd/

Start the BSP Editor.
$ bsp-editor&
In the BSP Editor window, select File > New HPS BSP... to open a New BSP window.
In the new BSP window:
1. Click the browse (…) button next to the Preloader Setting Directory text box and browse to the <Working_Directory>/a10_soc_devkit_ghrd/hps_isw_handoff folder.
2. Select the Operating system to be U-Boot Bootloader (Arria 10 HPS) in the pull-down menu.
3. Leave the Use default locations enabled to create the new BSP in the <your_working_directory>/a10_soc_devkit_ghrd/software/uboot_bsp folder.
4. Click OK to create the BSP settings file and close the New BSP window.
Figure 24. New BSP Window Settings
In the BSP Editor window, edit the BSP settings as follows:
- boot_device: Boot from SD/MMC (default)
- model: SOCFPGA Arria 10 Dev Kit (default)
- peripheral_rbf_filename: ghrd_10as066n2.periph.rbf (default is periph.rbf)
- core_rbf_filename: ghrd_10as066n2.core.rbf (default is core.rbf)
- disable_uboot_build: unchecked (default)
Figure 25. BSP Settings
In the BSP Editor window, click Generate in the lower right hand corner to produce the source code and the U-Boot device tree.
When the file generation is complete, click Close in the BSP Editor window.
The following files are generated in the <your_working_directory>//a10_soc_devkit_ghrd/software/uboot_bsp folder:
- config.mk
- devicetree.dts
- Makefile
- settings.bsp
- uboot.ds

Generating a Boot Loader DTB File for the 16.0 Release and Below

This task describes how to compile the U-Boot device tree source (DTS) into the device tree binary (DTB).

In the command shell, go to the U-boot folder and type the following commands:

$ cd <your_working_directory>/a10_soc_devkit_ghrd/software/uboot_bsp
$ dtc -O dtb -o devicetree.dtb -I dts devicetree.dts

These commands create the devicetree.dtb file in <your_working_directory>/a10_soc_devkit_ghrd/software/uboot_bsp folder.

Generating the Boot Loader DTS File for the 16.1 Release

This section describes how to run the Boot Loader Generator (BSP Editor) in the Windows^® and Linux^® environments to generate the device tree using the Intel^® Quartus^® Prime Pro Edition 16.1 release.

Windows Environment

Start an embedded command shell.

Figure 26. Open an Embedded Command Shell

Go to the a10_soc_devkit_ghrd folder.

$ cd <your_working_directory>/a10_soc_devkit_ghrd/

Start the BSP Editor.
```
$ bsp-editor&
```
In the BSP Editor window, select File > New HPS BSP... to open a new BSP window.
In the new BSP window:
1. Click the browse (…) button next to the Preloader Setting Directory text box and browse to the <your_working_directory>/a10_soc_devkit_ghrd/hps_isw_handoff folder. Click Open to return to the new BSP window.
2. Select the Operating system to be UEFI Bootloader (Arria 10 HPS) in the pull-down menu.
3. Leave the Use default locations enabled to create the new BSP in the <Working_Directory>/a10_soc_devkit_ghrd/software/uefi_bsp folder.
4. Click OK to create the BSP settings file and close the New BSP window.
Figure 27. New BSP Window Settings
In the BSP Editor window, edit the BSP settings as follows:
- boot_device: Boot from SD/MMC (default)
- model: SOCFPGA Arria 10 Dev Kit (default)
- disable_uefi_build: unchecked (default)
- rbf_filename: ghrd_10as066n2.rbf (default was socfpga.rbf)
- peripheral_rbf_filename: periph.rbf (default)
- core_rbf_filename: core.rbf (default)
- rbf_offset: 0x720000 (default)
Figure 28. BSP Settings
In the BSP Editor window, click Generate in the lower right hand corner to produce the source code and the UEFI device tree.
When the file generation is complete, click Close in the BSP Editor window.
The following files are generated in the <your_working_directory>//a10_soc_devkit_ghrd/software/uboot_bsp folder:
- config.mk
- devicetree.dts
- Makefile
- settings.bsp

Linux Environment

Start and embedded command shell and go to the a10_soc_devkit_ghrd folder.

$ ~/altera/16.1/embedded/embedded_command_shell.sh
$ cd <your_working_directory>/a10_soc_devkit_ghrd/

Start the BSP Editor.
$ bsp-editor&
In the BSP Editor window, select File > New HPS BSP... to open a New BSP window.
In the new BSP window:
1. Click the browse (…) button next to the Preloader Setting Directory text box and browse to the <your_working_directory>/a10_soc_devkit_ghrd/hps_isw_handoff folder. Click Open to return to the new BSP window.
2. Select the Operating system to be UEFI Bootloader (Arria 10 HPS) in the pull-down menu.
3. Leave the Use default locations enabled to create the new BSP in the <your_working_directory>/a10_soc_devkit_ghrd/software/uefi_bsp folder.
4. Click OK to create the BSP settings file and close the New BSP window.
Figure 29. New BSP Window Settings
In the BSP Editor window, edit the BSP settings as follows:
- boot_device: Boot from SD/MMC (default)
- model: SOCFPGA Arria 10 Dev Kit (default)
- rbf_filename: ghrd_10as066n2.rbf (default was socfpga.rbf)
- peripheral_rbf_filename: periph.rbf (default)
- core_rbf_filename: core.rbf (default)
- disable_uboot_build: 0x720000 (default)
Figure 30. BSP Editor Settings
In the BSP Editor window, click Generate in the lower right hand corner to produce the source code and the UEFI device tree.
When the file generation is complete, click Close in the BSP Editor window.
The following files are generated in the <Working_Directory>//a10_soc_devkit_ghrd/software/uefi_bsp folder:
- config.mk
- devicetree.dts
- Makefile
- settings.bsp

Generating a Boot Loader DTB File for the 16.1 Release

This task describes how to compile the UEFI device tree source (DTS) into the device tree binary (DTB).

In the command shell, go to the UEFI folder and type the following commands:

$ cd <your_working_directory>/a10_soc_devkit_ghrd/software/uefi_bsp
$ dtc -O dtb -o devicetree.dtb -I dts devicetree.dts

These commands create the devicetree.dtb file in <your_working_directory>/a10_soc_devkit_ghrd/software/uefi_bsp folder.

Building the UEFI Boot Loader

To build a UEFI boot loader, you must obtain the UEFI source code and compile the UEFI source with the supported toolchain.

You can compile the UEFI source code either in a Windows^® or in a Linux^® system.

Prerequisites

For Windows^® System

If you are using a Windows^® system, you must install the following components on your machine:

Git (Download from Git)
SoC FPGA EDS: this design suite come with a python tool
Arm^® Development Studio 5^® Intel^® SoC FPGA Edition for Windows^®

For Linux^® System

If you are using a Linux^® system, you must install packages. Depending on your Linux^® distribution, the command to install the packages is different:

If you are using a Ubuntu distribution, type:

$ sudo apt-get install uuid-dev build-essential

If you using a Fedora distribution, type:

$ sudo yum install uuid-devel libuuid-devel

For building UEFI, the Python package is required. If your host does not have Python installed, you can obtain the package from the SoC FPGA EDS installation path, by typing:

export PATH=$SOCEDS_DEST_ROOT/host_tools/python/bin/:$PATH

Note:

If you receive an error on hashlib.py, ensure that you have libssl.so.1.0.0 installed on your machine. You can install by typing:

$ export LD_LIBRARY_PATH=$SOCEDS_DEST_ROOT/host_tools/python/lib/:$LD_LIBRARY_PATH
$ /sbin/ldconfig

Supported Compiler Toolchain

The supported UEFI compiler toolchain is:

Linaro^®:
- arm-linux-gnueabihf-gcc (crosstool-NG linaro-1.13.1-4.8-2014.04 – Linaro GCC 4.8-2014.04) 4.8.3 20140401 (pre-release))
- This toolchain is available within the SoC FPGA EDS installation package.
Arm^® Toolchain (armcc, armlink)
- This tool chain is available within the SoC FPGA EDS Arm^® DS-5^® Intel^® SoC FPGA Edition installation package.

Obtaining the UEFI Source Code

The UEFI source code is located in GitHub. The following steps show you how to get the UEFI source code.

Open a terminal.
Create a new directory path to check out the UEFI source code from the GitHub.
```
$ mkdir /data/<username>/<Path_to_UEFI_Source_Code>
```
Change your directory to this UEFI working directory and clone the UEFI source from the git trees.
```
$ cd /data/<username>/<Path_to_UEFI_Source_Code>

$ git clone https://github.com/altera-opensource/uefi-socfpga
```
When completed, change to the uefi-socfpga folder and perform a git check out.
```
$ cd uefi-socfpga 
$ git checkout -b socvp_socfpga_udk2015 – track origin/socvp_socfpga_udk2015
```
Type the following command to generate a hard reset and make git point to the respective git tag for your board:
- RevC1 board:
```
$ git reset --hard tags/rel_socfpga_arria10_soceds_16.0
```
- Rev B board:
```
$ git reset --hard tags/rel_socfpga_arria10_soceds_15.1.1
```
- Rev A.1 or RevA.2 board:
```
$ git reset --hard tags/rel_socfpga_arria10_soceds_15.0.1
```

Preparing the Handoff DTB

If you are using an Intel^® SoC FPGA development kit and the standard GHRD, you can find the handoff device tree blob (DTB) installed as part of SoC FPGA EDS. The exact location of this file is <SoCEDS_installation_directory>/examples/hardware/a10_soc_devkit_ghrd/software/boot loader/devicetree.dtb.

If you are using a custom board or creating your own design, you must run make in your U-boot folder to build your customize boot loader and the U-boot handoff device tree blob (DTB). Refer to the sub-sections in Generating a Boot Loader DTB file for instructions.

Once the compilation is successful, you can find the devicetree.dtb file in the <your_working_directory>/a10_soc_devkit_ghrd/software/uboot_bsp folder.

Replace your <your_uefi_directory>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dtb file with the newly generated <your_working_directory>/a10_soc_devkit_ghrd/software/uboot_bsp/devicetree.dtb file. Alternatively, you can add the HANDOFF_DTB= <dtb_file_path> parameter to the make command later as mentioned in the Compile UEFI section.

$ make HANDOFF_DTB=<your_working_directory>/a10_soc_devkit_ghrd/software/uboot_bsp/devicetree.dtb

Updating the Device Tree Blob

A typical device tree contains all or some of the following:

Number of CPUs
Size and location of various RAMs
Buses and Bridges
Peripheral device connections
Interrupt controllers and IRQ line connections
Specific device driver configurations, such as:
- Ethernet MAC address
- Peripheral input clock

If any of these configurations change in your design, you must update your DTB. Some examples of a change might be:

Changing your boot flash daughter card type
Clock changes
Pin changes
Firewall and bridge configuration changes

Compiling the UEFI

This section describes how to compile the UEFI source code with the Linaro™ toolchain and Arm^® toolchain in Windows^® and Linux^® environments.

Note:

Reference to the make command is made in the following sections. To learn more about the make command, type:

$ make help

This command displays information on how to use make as well as options and examples.

Compiling the UEFI in a Windows Environment

This task describes how to compile the UEFI with the Linaro™ GCC compiler.

Open the command prompt.
Change your directory to your working directory.
```
$ cd <your_working_directory>/uefi-socfpga
```
Set the SOCEDS_DEST_ROOT and the DS5_ROOT according to the location of the SoC FPGA EDS and Arm^® DS-5^® Intel^® SoC FPGA Edition tools, respectively.
Configure the RVCT_TOOLS_PATH correctly in the setup.bat file. For Intel^® Quartus^® Prime Pro Edition v16.1, set RVCT_TOOLS_PATH=%DS5_ROOT%\sw\ARMCompiler5.06u3\bin\in the setup.bat file. In the previous setup file it is set to RVCT_TOOLS_PATH=%DS5_ROOT%\sw\ARMCompiler5.06u2\bin\ in setup.bat file. However, no ARMCompiler5.06u2 exists in the folder. Only the ARMCompiler5.06u3, ARMCompiler6.5 and ARMCompiler49Addon exist in the filepath. Therefore, you must correct this parameter path assignment. If you do not correct the path, the following reporting errors are generated:
```
Cannot find armcc.exe
Please install DS-5
```
At the command prompt type: $ setup.
Build the UEFI:
```
$ make clean
$ make
```
Note: When you build the UEFI, ensure your path to the UEFI source code is not too long. You may encounter some errors when the path is too long in the Windows^® environment. If you see an error similar to the screenshot below, shorten your path to the UEFI source code and recompile the source code again to remove the error.

Figure 31. UEFI Build Errors from Lengthy Path Name

Compiling the UEFI in the Linux Environment

Open a terminal window and enter the following command:
```
$ cd <your_uefi_directory>/uefi-socfpga
$ make clean
```
Note: The make clean command deletes the entire <your_uefi_directory>/uefi-socfpga/Build/ folder and also cleans the BaseTools folder.
Compile the UEFI boot loader for the by typing the following command:
```
$ make
```
The build process takes less than three minutes.
Note: Typing the make command is equivalent to typing: make DEVICE=a10 COMPILER=gcc.
When the build is successful, you see a Build Done message.

Compiling the UEFI with the ARMCC Compiler

To compile the UEFI with the ARMCC compiler open a terminal window and enter the following commands:

$ cd <your_uefi_directory>/uefi-socfpga
$ make clean
$ make DEVICE=a10 COMPILER=armcc HANDOFF_DTB=a10_soc_devkit_ghrd_qspi/software/bootloader/devicetree.dtb

Generated Files from UEFI Compile

Compiling the UEFI source creates four files in the <your_uefi_directory>/uefi-socfpga/Build/ folder:

Table 7. Generated Files from UEFI Compile
File	Description
~ /uefi-socfpga/Build/PEI.256 (256 KB)	This file is the main UEFI boot loader and contains the device tree for the HPS. The code initializes the HPS, which can boot directly to baremetal application, RTOS or Linux. You can extend the UEFI boot phase to boot to the Driver Execution Environment ROM (DXE.ROM) and configure the UEFI network and shell support. The .256 in the file name indicates the on-chip RAM size is 256 KB. Because the file size is 256 KB, it loads directly into the HPS on-chip using Arm^® DS-5^® Intel^® SoC FPGA Edition Development Studio. This file generates the Pre EFI Initialization ROM (PEI.ROM) file. The PEI.ROM file contains four duplicate images of the UEFI boot loader
~ /uefi-socfpga/Build/PEI.ROM (1MB = 256KB X 4)	This file is programmed onto the flash daughter card. The size of this file is four times bigger because the boot ROM can support up to four backup images. For example, if the first image (256KB) is corrupted, the boot ROM loads the second image and so on.
~ /uefi-socfpga/Build/load_uefi_fw.ds	This is the Arm^® DS-5^® Intel^® SoC FPGA Edition script template. It is imported to the Arm^® DS-5^® Intel^® SoC FPGA Edition tool and loads the UEFI firmware for debug and development purposes. This script loads the debug symbols for the user. Currently, it only supports the GCC compiler. ARMCC is not supported.
~ /uefi-socfpga/Build/DXE.ROM	This file loads the optional second stage of the UEFI boot loader when you want to boot the UEFI shell and utilize the TFTP feature or run a UEFI application.The difference between the PEI.ROM file and the DXE.ROM file are: The PEI.ROM file loads and executes from the HPS on-chip RAM. The DXE.ROM file executes from the DDR SDRAM. The PEI.ROM file generally initializes the HPS while the DXE.ROM file targets the Ethernet MAC and PHY providing full network stack support.

Creating an SD Card Image

This section describes how to create an SD card boot image by using the precompiled Linux binaries package as a beginning template. This section also provides instructions on how to compile a simple "HelloWorld" Bare Metal application and how to update individual elements on the SD card.

Task Time: 30 minutes

Creating an SD Card Image on Linux

Open a terminal window.
Make a copy of the GSRD into your working directory.
Download the pre-built SD card image from here.
Use the Arria10_Linux_SDCard.tar.gz as a base image and modify the image to boot with UEFI boot loader.
Expand the compressed Linux SD card image.
```
$ tar xzvf Arria10_Linux_SDCard.tar.gz
```
Insert the SD card reader into your machine. Enable the San Disk SDDR-113 by navigating to Devices > USB Devices > SanDisk SDDR-113 [9412].

Figure 32. Enabling SanDisk SDDR-113 [9412]
Determine the device associated with the SD card on the host by running the following command before and after inserting the card in the reader:
```
$ cat /proc/partitions
```
Figure 33. SD Card Determination Using cat Command

Alternatively, you can accomplish the same through the following menu selection on your machine: Applications > System Tools > Disk Utility
Figure 34. SD Card Determination Using Disk Utility

This selection opens a Disk Utility Window:
Figure 35. Disk Utility Window
Use the dd utility to overwrite the Arria10_Linux_SDCard.img file with the generated PEI.ROM and write the image into the SD card.
```
$ cd <your_uefi_directory>/uefi-socfpga

$ dd if=Build/PEI.ROM of=/<your_SDCard_directory>/ Arria10_Linux_SDCard.img bs=512 seek=2048 conv=notrunc
```
Figure 36. Image Overwrite Using dd Utility
Insert the SD card reader into your host machine and use the dd utility to write the image into the SD card.
```
$ sudo dd if=/<your_SDCard_directory>/ Arria10_Linux_SDCard.img of=/dev/sdb bs=1M
```
Figure 37. Image Write Using dd Utility

Creating an SD Card Image on Windows

This task explains how to write the SD image to the SD card on a Windows^®

PC.

Download the pre-built SD card image from here.
Use the Arria10_Linux_SDCard.tar.gz as a base image and modify the image to boot with UEFI boot loader.
Extract the compressed SD card image from the compressed archive Arria10_Linux_SDCard.tar.gz using WinZip or or a similar tool to create the Arria10_Linux_SDCard.img file.
Use the Win32DiskImager to write the image to the SD card. Please refer to the Win32DiskImager Tool Installation instructions for steps to install this tool on your machine.
Insert the SD card reader into your machine.
Start Win32DiskImage by selecting Start > All Programs > Win32DiskImager from the Windows^® program search or by double-clicking the Win32DiskImager icon on your desktop.
When the Win32Disk Imager window appears, click the icon highlighted below and browse to <your_SDCard_Image_Directory> .

Figure 38. File Browse in Win32 Disk Imager Dialog Box
Select Arria10_Linux_SDCard.img and click Open.
Click Write. The writing process may take some time. Check the Progress bar for status updates.
After a Done status displays and a Complete dialog box appears, click OK to exit the Complete dialog box.
Select Exit to close the Win32DiskImager window.

Compile the Bare Metal Application Source Code

This task describes how to modify and build the HelloWorld BareMetal application example that comes with the SoC FPGA EDS 15.0. The HelloWorld application writes an output to the first serial interface.

Open a terminal.
Make a copy of the HelloWorld BareMetal application example code into your working directory. For example, if your working directory is /data/<username>/GSRD, type:
```
$ cd /data/<username>/GSRD

$ cp -r ~/altera/15.0/embedded/examples/software/Altera-SoCFPGA-HelloWorld-Baremetal-ARMCC.tar.gz/ .
```
Extract the compressed HelloWorld project from archive.
```
$ tar -xvf Altera-SoCFPGA-HelloWorld-Baremetal-ARMCC.tar.gz
```
Figure 39. HelloWorld Application Extraction
When complete, change to the Altera-SoCFPGA-HelloWorld-Baremetal-ARMCC folder and edit the Makefile.
```
$ cd Altera-SoCFPGA-HelloWorld-Baremetal-ARMCC

$ gedit Makefile
```
Change line 6 in the Makefile from BOARD=cycloneV to BOARD=arria10.

Figure 40. Makefile Edit
Click the Save icon and exit the Makefile.
Open the arria10_scatter.scat file by typing:
```
$ gedit arria10_scatter.scat
```
Modify the arria10_scatter.scat file as shown in the screenshots below to make the Bare Metal application compile for DDR SDRAM instead of on-chip RAM.
The text that you must change in the arria10_scatter.scat is highlighted in orange:
Figure 41. Original arria10_scatter.scat File

The replacement text is shown below:
Figure 42. Modified arria10_scatter.scat File
Click the Save icon and exit arria10_scatter.scat file.
Open the helloworld.c source file.
```
$ gedit hello.c
```
Edit the file according to your own custom code. Below is an example of a HelloWorld program that allows you to see "Hello World from Baremetal Application!" messages displaying on the board.

Figure 43. Original hello.c File

The screenshot below shows the modified hello.c file.
Figure 44. Modified hello.c File
Click the Save icon and exit the hello.c file.
Type make at the prompt to start the compilation.
Convert the .axf file to .elf file format.
```
$ fromelf  --bin Altera-SoCFPGA-HelloWorld-Baremetal-ARMCC.axf --output=bootimage.bin
```
Figure 45. .axf to .elf File Conversion

Updating Individual Elements on the SD Card

This task describes how to update the following elements individually into the SD card:

ghrd_10as066n2.periph.rbf
ghrd_10an066n2.core.rbf
bootimage.bin (Bare Metal Image)
kernel-uImage.bin (Integrity Image)
vxWorks.bin (VxWorks Image)

Open the SD card to view the FAT partition. Go to Application > System Tool > Disk Utility.
Observe that the FAT partition location at /dev/sdb1.

Figure 46. Disk Utility FAT Partition View
Open a Terminal.

Mount /dev/sdb1 (FAT) on the host machine and copy the core.rbf and periph.rbf files and application image into the FAT partition using the commands shown below:

$ sudo mount /dev/sdb1 sdcard/

$ sudo cp GSRD/GSRD/ghrd_10as066n2.periph.rbf sdcard/

$ sudo cp GSRD/GSRD/ghrd_10as066n2.core.rbf sdcard/

$ sudo cp GSRD/GSRD/bootimage.bin sdcard/

$ sudo cp GSRD/GSRD/kernel-uImage.bin sdcard/

$ sudo cp GSRD/GSRD/vxWorks.bin sdcard/

$ sudo umount sdcard

Programming the Bare Metal Image

This task describes how to configure your program to boot the Bare Metal application program automatically on your target board after power up.

Open a terminal window and enter the following command:
```
$ cd <your_uefi_directory>/uefi-socfpga
```
Run the following command to open and edit the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
```
$ gedit AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc
```
Set the PcdSdmmc_BOOTIMAGE_FILENAME parameter in the file to bootimage.bin.

Figure 47. Editing Arria10SoCPkg.dsc Parameters
Click Save.
Re-compile the UEFI Bootloader for the Intel^® Arria^® 10 SoC FPGA device using the following command. The build process takes less than 3 minutes.
```
$ make fast
```
When the build completes successfully, a Build Done message appears.

Figure 48. Build Done Message

Use the dd utility to overwrite the sd_card_linux_boot_image.img file with the generated PEI.ROM.

$ cd <your_uefi_directory>/uefi-socfpga 

$ dd if=Build/PEI.ROM of=/<your_SDCard_directory>/sd_card_linux_boot_image.img bs=512 seek=2048 conv=notrunc

Insert the SD card reader into your host machine.
Use the dd utility or Win32DiskImager to write the sd_card_linux_boot_image.img into the SD Card.
If you are using the dd utility type:
```
$ sudo dd if=/<your_SDCard_directory>/sd_card_linux_boot_image.img of=/dev/sdb bs=1M
```
If you are using the Win32DiskImager:
1. Double-click the Win32DiskImager Icon.
2. When the Win32DiskImager dialog box appears, browse to select the sd_card_linux_boot_image.img file and click Open.
3. Select the Write button.
4. When the Confirm overwrite dialog box appears, click Yes to continue. A progress bar appears.
  
  Figure 49. Win32 Disk Imager Overwrite Confirmation
5. After the write operation completes, a Complete dialog box appears. Click OK to exit the dialog box and then click Exit in the Image File window.
  
  Figure 50. Exit Win32 Disk Imager
6. Remove the SD card reader from your host.

Programming the Integrity Real-Time Operating System Image

This task describes how to boot the Integrity Real-Time Operating System (RTOS) automatically on your target board after power up.

Open a terminal window and enter the following command:
```
$ cd <your_uefi_directory>/uefi-socfpga
```
Run the following command to open and edit the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
```
$ gedit AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc
```
Set the PcdSdmmc_BOOTIMAGE_FILENAME parameter in the file to kernel-uImage.bin.

Figure 51. Editing Arria10SoCPkg.dsc Parameters
Click Save.
Re-compile the UEFI Bootloader for the Intel^® Arria^® 10 SoC FPGA device using the following command. The build process takes less than 3 minutes.
```
$ make fast
```
When the build completes successfully, a Build Done message appears.

Figure 52. Build Done Message

Use the dd utility to overwrite the sd_card_linux_boot_image.img file with the generated PEI.ROM.

$ cd <your_uefi_directory>/uefi-socfpga 

$ dd if=Build/PEI.ROM of=/<your_SDCard_directory>/sd_card_linux_boot_image.img bs=512 seek=2048 conv=notrunc

Insert the SD card reader into your host machine.
Use the dd utility or Win32DiskImager to write the sd_card_linux_boot_image.img into the SD Card.
If you are using the dd utility type:
```
$ sudo dd if=/<your_SDCard_directory>/sd_card_linux_boot_image.img of=/dev/sdb bs=1M
```
If you are using the Win32DiskImager:
1. Double-click the Win32DiskImager Icon.
2. When the Win32 Disk Imager dialog box appears, browse to select the sd_card_linux_boot_image.img file and click Open.
3. Select the Write button.
4. When the Confirm overwrite dialog box appears, click Yes to continue. A progress bar appears.
  
  Figure 53. Win32 Disk Imager Overwrite Confirmation
5. After the write operation completes, a Complete dialog box appears. Click OK to exit the dialog box and then click Exit in the Image File window.
  
  Figure 54. Exit Win32 Disk Imager
6. Remove the SD card reader from your host.

Programming the VxWorks Real-Time Operating System Image

This task describes how to boot the Integrity Real-Time Operating System (RTOS) automatically on your target board after power up.

Open a terminal window and enter the following command:
```
$ cd <your_uefi_directory>/uefi-socfpga
```
Run the following command to open and edit the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
```
$ gedit AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc
```
Set the PcdSdmmc_BOOTIMAGE_FILENAME parameter in the file to kernel-uImage.bin.

Figure 55. Editing Arria10SoCPkg.dsc Parameters
Click Save.
Re-compile the UEFI Bootloader for the Intel^® Arria^® 10 SoC FPGA device using the following command. The build process takes less than 3 minutes.
```
$ make fast
```
When the build completes successfully, a Build Done message appears.

Figure 56. Build Done Message

Use the dd utility to overwrite the sd_card_linux_boot_image.img file with the generated PEI.ROM.

$ cd <your_uefi_directory>/uefi-socfpga 

$ dd if=Build/PEI.ROM of=/<your_SDCard_directory>/sd_card_linux_boot_image.img bs=512 seek=2048 conv=notrunc

Insert the SD card reader into your host machine.
Use the dd utility or Win32DiskImager to write the sd_card_linux_boot_image.img into the SD Card.
If you are using the dd utility type:
```
$ sudo dd if=/<your_SDCard_directory>/sd_card_linux_boot_image.img of=/dev/sdb bs=1M
```
If you are using the Win32DiskImager:
1. Double-click the Win32DiskImager Icon.
2. When the Win32DiskImager dialog box appears, browse to select the sd_card_linux_boot_image.img file and click Open.
3. Select the Write button.
4. When the Confirm overwrite dialog box appears, click Yes to continue. A progress bar appears.
  
  Figure 57. Win32 Disk Imager Overwrite Confirmation
5. After the write operation completes, a Complete dialog box appears. Click OK to exit the dialog box and then click Exit in the Image File window.
  
  Figure 58. Exit Win32 Disk Imager
6. Remove the SD card reader from your host.

Creating a QSPI Image

This section describes how to update the GSRD to enable booting from QSPI on your target board.

Approximate completion time: 80 minutes

Updating the Golden Hardware Reference Design to Boot from QSPI

The SoC FPGA EDS GHRD enables booting from SDMMC by default. There are two options available for you to change the booting from SDMMC to QSPI:

Manually change the configuration to QSPI by:
- Opening the HPS in Platform Designer to modify the pin muxing and enable peripherals
- Changing pin assignments in Intel^® Quartus^® Prime Pro Edition
- Changing the top level Verilog file to include the QSPI signals instead of the SD/MMC signals.
Manually changing the configuration is time-intensive.
Another, more efficient option is by taking advantage of the Makefile feature. The example shown in this sections uses this method to perform the boot conversion from SDMMC to QSPI.

Start an embedded command shell. Make a copy of the ghrd folder into your QSPI working directory.

$ ~/altera/15.0/embedded/embedded_command_shell.sh

$ mkdir <your_qspi_working_directory>/a10_soc_devkit_ghrd_qspi

$ cd <your_qspi_working_directory>/a10_soc_devkit_ghrd_qspi

$ tar xvzf ~/altera/15.0/embedded/examples/hardware/a10_soc_devkit_ghrd/tgz/*.tar.gz

When complete, run the following commands to enable booting from QSPI and generate the Platform Designer file:

$ sed -i ‘s/HPS_BOOT_DEVICE := SDMMC/HPS_BOOT_DEVICE := QSPI/g’ Makefile

$ sed -i ‘s/QUARTUS_CPF_ENABLE_SPLIT_RBF := 1/QUARTUS_CPF_ENABLE_SPLIT_RBF := 0/g’ Makefile

$ make scrub_clean

$ make quartus_generate_top quartus_generate_qsf_qpf qsys_generate_qsys

After a series of messages ending in Info: save_system ghrd_10as066n2.qsys, a prompt appears.

Compiling the Hardware and Software for QSPI

This task describes how to use the GHRD Makefile to compile both the hardware and the software (U-Boot).

Start and embedded command shell and go into your QSPI GHRD folder.

$ ~/altera/15.0/embedded/embedded_command_shell.sh

$ cd <your_qspi_working_directory>/a10_soc_devkit_ghrd_qspi

Run the make all command. The compilation process may take some time to complete.

$ make all

The make all command creates the following files:

Table 8. Output Files from make all Command
File	Description
~ /a10_soc_devkit_ghrd_qspi/software/boot loader/devicetree.dtb	Boot Loader Device Tree Image
~ /a10_soc_devkit_ghrd_qspi/output_files/ghrd_10as066n2.rbf	I/O Ring and FPGA Fabric Configuration File

Compiling the UEFI Source Code with the Updated QSPI Device Tree Blob

This task describes how to re-compile the UEFI source code using the updated device tree blob (DTB) generated for the QSPI booting with the Linaro™ toolchain.

Open a Terminal window and enter the following command:
```
$ cd <your_uefi_directory>/uefi-socfpga
```
Compile the UEFI boot loader for Intel^® Arria^® 10 SoC FPGA device using the following command. This build process takes less than three minutes.
```
$ make DEVICE=a10 COMPILER=gcc HANDOFF_DTB=[QSPI bootloader DTB file path]
```
An example of a [QSPI boot loader DTB file path] is:
```
/data/<username>/GSRD/a10_soc_devkit_ghrd_qspi/software/bootloader/devicetree.dtb
```
Once the build completes, the following completion information highlighted by the orange text box appears:
Figure 59. make Completion

These steps generate four files in your <your_uefi_directory>/uefi-socfpga/Build/ folder:
- DXE.ROM
- load_uefi_fw.ds
- PEI.256
- PEI.ROM

QSPI Layout

The following diagram deptics the QSPI Layout. Items to note within the diagram are:

Boot loader images 0, 1, 2, and 3 are loaded with PEI.ROM
Linux DTB and Linux filesystem are only programmed when you are booting Linux
The next stage boot image can be either a zImage, an RTOS binary image or a Bare Metal application binary image.
DXE.ROM is an optional second phase of the UEFI boot loader
RBF is generated from the SOF file using the quartus_cpf tool

Figure 60. QSPI Layout

Updating Individual Elements into the QSPI

This task describes how to update the following elements individually into the QSPI memory:

ghrd_10as066n2.rbf
PEI.ROM (UEFI boot loader binary image)
bootimage.bin (Bare Metal Image)
kernel-uImage.bin (Integrity Image)
vxWorks.bin (VxWorks Image)

Connect the JTAG Intel^® FPGA Download Cable II from your host to the Intel^® Arria^® 10 SoC FPGA development board.
Install the QSPI daughter card into J23.
Power up the board.
To program the compiled UEFI image into the QSPI, type the following commands:
```
$ cd <your_uefi_directory>/uefi-socfpga

$ program_qspi
```
Or you can alternatively type:
```
$ quartus_hps -c1 -oP Build/PEI.ROM --addr=0x00000000
```

Program the single RBF into the QSPI.

If you have a GHRD design, you can use the make command:

$ cd <your_qspi_working_directory>/a10_soc_devkit_ghrd_qspi 

$ make program_qspi-rbf

If you want to program the single RBF manually without the GHRD Makefile, type:

$ mkimage -A arm -T firmware -C none -O u-boot -a 0 -e 0 -n "RBF" -d ghrd_10as066n2.rbf ghrd_10as066n2.rbf.mkimage

$ quartus_hps -c1 -oP --addr=0x00720000 ghrd_10as066n2.rbf.mkimage

If you are booting the DXE phase, program the DXE.ROM file into the QSPI.
```
$ quartus_hps -c1 -oP Build/DXE.ROM --addr=0x00620000
```

Programming the Bare Metal Image

This task describes how to program the Bare Metal image into QSPI.

Go to your generated Baremetal HelloWorld image directory. For example:
```
$ cd /data/<username>/GSRD/Altera-SoCFPGA-HelloWorld-Baremetal-ARMCC
```

Run the following command to add mkimage header to bootimage.bin to indicate the filesize.

$ mkimage -A arm -T firmware -C none -a 0x100000 -e 0x100000 -n "UserApp" -d bootimage.bin bootimage.bin.mkimage

Type the following command to flash the boot image into the QSPI.
```
$ quartus_hps -c1 -d 2 -o P --addr=0x00120000 bootimage.bin.mkimage
```
Figure 61. Commands for Programming the Bare Metal Image

Programming the Integrity Real-Time Operating System Image

Go to your Integrity image directory. An example of a directory path is /data/<username>/sdcard/a10_soc.
```
$ cd /data/<username>/sdcard/a10_soc
```
Type the following command to flash the Integrity RTOS image into the QSPI.
Note: This kernel-uImage.bin file is already included in the header.
```
$ quartus_hps -c 1 - 2 -o P --addr=0x00120000 kernel-uImage.bin
```
Figure 62. Flashing the Integrity RTOS Image into QSPI

Programming the VxWorks Real-Time Operating System Image

Go to your VxWorks^® image directory. The directory used in this example is: /data/<username>/sdcard/a10_soc.
```
$ cd /data/<username>/sdcard/a10_soc
```

Add the mkimage header to your vxWorks.bin to your to indicate the filesize.

$ mkimage -A arm -T firmware -C none -a 0x100000 -e 0x100000 -n "vxWorks" -d vxWorks.bin vxWorks.bin.mkimage

Flash the boot image into the QSPI by typing:

 quartus_hps -c 1 -d 2 --o P --addr=0x00120000 vxWorks.bin.mkimage

Booting the Board with SD/MMC

Configuring the Board

This section presents the necessary board settings for running the UEFI boot loader on the Intel^® Arria^® 10 SoC FPGA development board.

Figure 63. Intel^® Arria^® 10 SoC FPGA Development Board

Confirm that the memories are installed in the following way:

A DDR4 memory card is installed on the HPS memory socket.
An SD boot card is installed on the boot flash socket.

Confirm that the board switches are configured as in the tables below:

Table 9. Switch Configuration
Switch Type	Required Setting	Function
SW1 Settings
SW1.1 – I2C flag	OFF	ON (0): System MAX5 is the I²C master. OFF (1): HPS is the I²C master.
RevA.1 and RevA.2 Board
SW1.2 – factory_load	ON	ON (0): Load the user design from flash at power up. OFF (1): Load the factory design from flash at power up.
SW1.3 – msel1	ON	ON (up): `MSEL[1]` is 0. OFF (down): `MSEL[1]` is 1.
SW1.4 – msel0	ON	ON (up): `MSEL[0]` is 0. OFF (down): `MSEL[0]` is 1.
RevB.1 Board
SW1.2 – dc_power_ctrl	ON	ON (0): Do not turn on FMC/PCIE power directly. OFF (1): Turn on FMC/PCIE power directly.
SW1.3 – factory_load	ON	ON (0): Load the user design from flash at power up. OFF (1): Load the factory design from flash at power up.
SW1.4 – security_mode	ON	Reserved
SW2 Settings : ALL ON
SW3 Settings
SW3.1 – Arria10	OFF	ON – Arria10 JTAG Bypass OFF – Arria10 JTAG Enable
SW3.2 – IO MAXV	ON	ON – MAXV JTAG Bypass OFF – MAXV JTAG Enable
SW3.3 – FMCA	ON	ON – FMCA JTAG Bypass OFF – FMCA JTAG Enable
SW3.4 – FMCB	ON	ON – FMCB JTAG Bypass OFF – FMCB JTAG Enable
SW3.5 – PCIE	ON	ON – PCIE JTAG Bypass OFF – PCIE JTAG Enable
SW3.6 – MSTR0	OFF	See "Master Switch Settings" Table
SW3.7 – MSTR1	OFF
SW3.8 – MSTR2	OFF
SW4 Settings: ALL OFF (RevA.1 & RevA.2 Board)
SW4 Settings: (RevB.1 Board)
SW4.1 – reserve	OFF	-
SW4.2 – MSEL0	ON	ON=1 OFF=0
SW4.3 – MSEL1	OFF
SW4.4 – MSEL2	OFF

Table 10. Master Switch Settings
MSTR[2]	MSTR[1]	MSTR[0]	Master Selected
ON	ON	ON	Boot
OFF	ON	ON	FMCA (not implemented yet)
ON	OFF	ON	FMCB (not implemented yet)
ON	ON	OFF	FTRACE
OFF	OFF	OFF	ON-BOARD UBII
ON	OFF	OFF	MAXV A Programming Mode (only for advanced user)
OFF	ON	OFF	GUI Mode

Confirm that the following jumpers are configured as follows:

Place jumpers on J16 and J17
Leave all other jumpers unplaced

Configuring the Serial Connection

The Intel^® Arria^® 10 SoC FPGA development board has a built-in FTDI USB-to-serial converter chip that allows the host computer to see the board as a virtual serial port. CentOS 6.5 has built-in drivers for the FTDI USB-to-serial converter chip. Therefore, you do not need to install a driver. In Windows^®, the SoC FPGA EDS installation automatically installs the required drivers if necessary.

The serial communication parameters listed below:

Baud rate: 115200 bps
Parity: none
Flow control: none
Stop bits: 1
Data bits: 8

In Windows^®, a terminal emulator such as Tera Term can be used to connect to the Intel^® Arria^® 10 SoC FPGA development board. Refer to the Tera Term Installation section for the instructions on how to install Term Term and how to configure serial port settings from the tool menu.

You can use the Linux^® minicom utility to connect to the Intel^® Arria^® 10 SoC FPGA development board. Refer to the Minicom Installation section for instructions on how to install the minicom on CentOS and Ubuntu and how to configure the serial port settings from the tool menu.

Booting a Bare Metal Application from SD/MMC

Complete the steps in Creating an SD Card Image on Linux or Creating an SD Card Image on Windows depending on your OS.
Complete the corresponding steps in Compile the Bare Metal Application Source Code and Programming the Bare Metal Image.
Insert the programmed SD/MMC card into J23.
Start a serial terminal program.
Power up the board. During this time, there is no console output for approximately 15 seconds.
For a normal boot flow, you see a series of output messages on your serial terminal program ending with the following completion message:

Figure 64. BareMetal Boot Completion Message Output
If you are in DXE phase, the following output message displays on your serial terminal program for post-DDR extended diagnostic boot flow.

Figure 65. DXE Phase Output Message

Booting Integrity Real-Time Operating System from SD/MMC

Complete the steps in Creating an SD Card Image on Linux section or Creating an SD Card Image on Windows depending on your OS.
Complete the corresponding steps in Programming the Integrity Real-Time Operating System Image.
Insert the programmed SD/MMC daughter card into J23.
Start a serial terminal program.
Power up the board. During this time, there is no console output for approximately 15 seconds.
For a normal boot flow, you see a series of output messages on your serial terminal program ending with the following completion message:

Figure 66. Integrity RTOS Boot Completion Message Output

Booting from VxWorks Real-Time Operating System from SD/MMC

Complete the steps in Creating an SD Card Image on Linux section or Creating an SD Card Image on Windows section depending on your OS.
Complete the corresponding steps in Programming the VxWorks Real-Time Operating System Image.
Insert the programmed SD/MMC daughter card into J23.
Start a serial terminal program.
Power up the board. During this time, there is no console output for approximately 15 seconds.
For a normal boot flow, you see a series of output messages on your serial terminal program ending with the following completion message:

Figure 67. Integrity RTOS Boot Completion Message Output

Booting the Board with QSPI

Configuring the Board

Confirm that the memories are installed in the following way:

A DDR4 memory card is installed on the HPS memory socket.
A QSPI daughter card is installed on the boot flash socket.

Confirm that the board switches are configured as in the tables below:

Table 11. Switch Configuration
Switch Type	Required Setting	Function
SW1 Settings
SW1.1 – I2C flag	OFF	ON (0): System MAX5 is the I²C master. OFF (1): HPS is the I²C master.
RevA.1 and RevA.2 Board
SW1.2 – factory_load	ON	ON (0): Load the user design from flash at power up. OFF (1): Load the factory design from flash at power up.
SW1.3 – msel1	ON	ON (up): `MSEL[1]` is 0. OFF (down): `MSEL[1]` is 1.
SW1.4 – msel0	ON	ON (up): `MSEL[0]` is 0. OFF (down): `MSEL[0]` is 1.
RevB.1 Board
SW1.2 – dc_power_ctrl	ON	ON (0): Do not turn on FMC/PCIE power directly. OFF (1): Turn on FMC/PCIE power directly.
SW1.3 – factory_load	ON	ON (0): Load the user design from flash at power up. OFF (1): Load the factory design from flash at power up.
SW1.4 – security_mode	ON	Reserved
SW2 Settings : ALL ON
SW3 Settings
SW3.1 – Arria10	OFF	ON – Arria10 JTAG Bypass OFF – Arria10 JTAG Enable
SW3.2 – IO MAXV	ON	ON – MAXV JTAG Bypass OFF – MAXV JTAG Enable
SW3.3 – FMCA	ON	ON – FMCA JTAG Bypass OFF – FMCA JTAG Enable
SW3.4 – FMCB	ON	ON – FMCB JTAG Bypass OFF – FMCB JTAG Enable
SW3.5 – PCIE	ON	ON – PCIE JTAG Bypass OFF – PCIE JTAG Enable
SW3.6 – MSTR0	OFF	See "Master Switch Settings" Table
SW3.7 – MSTR1	OFF
SW3.8 – MSTR2	OFF
SW4 Settings: ALL OFF (RevA.1 & RevA.2 Board)
SW4 Settings: (RevB.1 Board)
SW4.1 – reserve	OFF	-
SW4.2 – MSEL0	ON	ON=1 OFF=0
SW4.3 – MSEL1	OFF
SW4.4 – MSEL2	OFF

Table 12. Master Switch Settings
MSTR[2]	MSTR[1]	MSTR[0]	Master Selected
ON	ON	ON	Boot
OFF	ON	ON	FMCA (not implemented yet)
ON	OFF	ON	FMCB (not implemented yet)
ON	ON	OFF	FTRACE
OFF	OFF	OFF	ON-BOARD UBII
ON	OFF	OFF	MAXV A Programming Mode (only for advanced user)
OFF	ON	OFF	GUI Mode

Confirm that the following jumpers are configured as follows:

Place jumpers on J16 and J17
Leave all other jumpers unplaced

Configuring the Serial Connection

The serial communication parameters listed below:

Baud rate: 115200 bps
Parity: none
Flow control: none
Stop bits: 1
Data bits: 8

Booting a Bare Metal Application from QSPI

This task describes how to use a UEFI boot loader to boot the HelloWorld Bare Metal application on the board.

Complete the steps in Updating the Golden Hardware Reference Design to Boot from QSPI, Compiling the Hardware and Software for QSPI and Compiling the UEFI Source Code with the Updated QSPI Device Tree Blob.
Complete the steps in Programming the Bare Metal Image.
Insert the programmed QSPI daughter card into J23.
Start a serial terminal program.
Power up the board. During this time, there is no console output for approximately 15 seconds.
For a normal boot flow, you see a series of output messages on your serial terminal program ending with the following completion message:

Figure 68. Bare Metal Boot Completion Message Output
If you are in DXE phase, the following output message displays on your serial terminal program for post-DDR extended diagnostic boot flow.

Figure 69. DXE Phase Output Message

Booting Integrity Real-Time Operating System from QSPI

Complete the steps in Updating the Golden Hardware Reference Design to Boot from QSPI, Compiling the Hardware and Software for QSPI and Compiling the UEFI Source Code with the Updated QSPI Device Tree Blob.
Complete the steps in the Programming the Integrity Real-Time Operating System Image section.
Insert the programmed QSPI daughter card into J23.
Start a serial terminal program.
Power up the board. During this time, there is no console output for approximately 15 seconds.
A series of output messages display on your serial terminal program ending with the following completion message:

Figure 70. Integrity RTOS Boot Completion Message Output

Booting from VxWorks Real-Time Operating System from QSPI

Complete the steps in Updating the Golden Hardware Reference Design to Boot from QSPI, Compiling the Hardware and Software for QSPI and Compiling the UEFI Source Code with the Updated QSPI Device Tree Blob.
Complete the steps in Programming the VxWorks Real-Time Operating System Image.
Insert the programmed QSPI daughter card into J23.
Start a serial terminal program.
Power up the board. During this time, there is no console output for approximately 15 seconds.
A series of output messages display on your serial terminal program ending with the following completion message:

Figure 71. VxWorks RTOS Boot Completion Message Output

Early I/O Release

Task time: 30 minutes

Early I/O release enables DDR functioning prior to programming the core raw binary file (RBF). This feature provides a faster boot time because the shared I/O and hard memory controller I/O are configured and released for immediate access by the HPS. Early I/O release also enables availability of the shared I/O so that device can obtain the core RBF from the TFTP server instead of flash. The CSS then configures and releases the FPGA fabric allowing the HPS to have access. Early I/O release also provides early response in time critical systems.

The peripheral RBF configures shared I/O, hard memory controller I/O, and hard memory controller settings such as memory type, frequency and timings. The core RBF configures the FPGA fabric, FPGA I/O and FPGA PLL settings. You can choose to combine the peripheral and core RBF into one RBF that configures both the FPGA fabric and the I/O Control Shift registers (IOCSRs). Using a combined RBF creates a performance penalty that is much slower than splitting the RBFs. When you split the RBFs, the core RBF loads into SDRAM instead of on-chip RAM from flash providing a larger data transfer block and boosting performance.

Boot Flow

After device power up, the peripheral RBF loads into on-chip RAM from flash. The configuration subsystem (CSS) uses the peripheral RBF to configure the IOCSRs. Once the configuration is done, and the FPGA enters early user mode and the shared I/O exit reset. At this point, the SDRAM is ready for loading a larger size image. Subsequently, the core RBF is loaded into SDRAM. The CSS uses the core RBF to configure the FPGA fabric and FPGA I/O. Once the configuration finishes, the FPGA enters user mode, the CSS releases the FPGA I/O from reset, and the device can now boot to DXE or OS.

You can load the core RBF automatically upon power up or manually through the Pit Stop command. When you load the core RBF automatically, the core RBF file name (SDMMC) or offset (QSPI/NAND) are defined in the modifiable DSC file. When you load the core RBF manually, you must key in the core RBF file name or offset using the Pit Stop utility.

There are three boot flows supported by current UEFI:

An automatically loaded peripheral RBF and core RBF
An automatically loaded peripheral RBF and manually loaded core RBF through Pit Stop
An automatically loaded and combined RBF

Enabling Early I/O Release

The figure below shows the high-level steps to enable early I/O release.

Figure 72. Early I/O Release Enable

Automatically Loaded Peripheral RBF and Core RBF

To automatically load the peripheral RBF and core RBF, use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
Configure the gAlteraSocFpgaTokenSpaceGuid.PcdAutoProgramCoreRbf value to 1.

Figure 73. Arria10SoCPkg.dsc Parameter Edit

Automatically Loaded Peripheral RBF And Manually Loaded RBF Through Pit Stop

To automatically load the peripheral RBF and manually load core RBF, use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
Configure the gAlteraSocFpgaTokenSpaceGuid.PcdAutoProgramCoreRbf value to 0.

Figure 74. Arria10SoCPkg.dsc Parameter Edit

Refer to the Pit Stop Usage Guide section for the program core RBF command to load the core RBF through the Pit Stop utility manually.

Automatically Loaded Combined RBF

To automatically load the combined RBF, use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
Configure the gAlteraSocFpgaTokenSpaceGuid.PcdAutoProgramCoreRbf value to 1.

Figure 75. Arria10SoCPkg.dsc Parameter Edit

Device Tree Support

Figure 76. DTS Design for SD/MMC Booting

Figure 77. DTS Design for QSPI Booting

Early I/O Release Output Messages

The following messages display when you enable early I/O release and power up the board:

Figure 78. Early I/O Release Output Messages

Booting Linux Using the UEFI Boot Loader

Task time: 60 minutes

SoC FPGA EDS version 16.0 and newer supports booting of a Linux^® operating system on an Intel^® Arria^® 10 SoC FPGA using the UEFI boot loader.

Boot Linux Support

The following table shows the supported Linux^® boot flows.

Table 13. Supported Linux^® Boot Methods
No.	Boot Method	SD/MMC Supported?	QSPI Supported?
1	Boot the Linux^® zImage from the PEI phase automatically without user intervention.	Yes	Yes
2	Boot the Linux^® zImage from the PEI phase manually by using the Pit Stop utility.	Yes	Yes
3	Boot the Linux^® zImage from the DXE phase automatically without intervention.	Yes	No
4	Boot Linux zImage from DXE phase by typing command at UEFI shell.	Yes	No

Prerequisites

You must have the following items to boot Linux^® on the Intel^® Arria^® 10 SoC FPGA development board.

Intel^® Arria^® 10 SoC FPGA development board
SoC FPGA EDS version 16.0 or newer
Latest UEFI boot loader source code (minimum tag: rel_socfpga_arria10_soceds_16.0)
Pre-built Linux^® SD card image from here.

Note: You must program the UEFI boot loader in your SD card. You can do this by referring to the Creating an SD Card Image on Linux section. Follow the steps in this section until you complete the instructions to use the dd utility to overwrite the Arria10_Linux_SDCard.img file with the generated PEI.ROM and write the image into the SD card.

Booting Linux from the PEI Phase

Booting Linux from the PEI Phase Automatically

This task describes how to enable booting of Linux^® from the PEI phase automatically.

Use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
To boot the Linux^® zImage stored on an SD card or in QSPI flash right after the UEFI PEI phase initialization, configure the gAlteraSocFpgaTokenSpaceGuid.PcdBoot_LOAD_ZIMAGE_AT_PEI_PHASE value to 1.
Configure the gAlteraSocFpgaTokenSpaceGuid.PcdBoot_LOAD_UEFI_DXE_PHASE value to 0.
Recompile the source code and update the SD card image with the modified PEI.ROM for the changes to take effect.
Power cycle the board and observe the following output messages on your serial terminal program:

Figure 79. Serial Terminal Output Message

Booting Linux from the PEI Phase Using SD/MMC or QSPI Manually

If you are currently booting in another operating system and want to boot Linux^® from the PEI phase manually, execute the following instructions:

Boot to the Pit Stop utility. Refer to the Enabling or Disabling the Pit Stop Utility section for instructions.
Type the bootz command.

Note: This method does not require you to recompile the source code, but you must ensure the SD card image is correct. The SD card must have the zImage file inside the FAT32 partition and also have a Linux^® partition.

Figure 80. Boot Linux Manually Using SD/MMC

Figure 81. Boot Linux Manually Using QSPI

Booting Linux from the DXE Phase

Booting Linux from the DXE Phase Using SD/MMC

This task describes how to enable booting of Linux^® from the DXE phase.

Use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
To boot the Linux^® zImage stored on an SD card or in QSPI flash right after the DXE phase, configure the gAlteraSocFpgaTokenSpaceGuid.PcdBoot_LOAD_ZIMAGE_AT_PEI_PHASE value to 0.
Configure the gAlteraSocFpgaTokenSpaceGuid.PcdBoot_LOAD_UEFI_DXE_PHASE value to 1.
Recompile the source code and update the SD card image with the modified DXE.ROM for the changes to take effect.
Once the compilation is successful, copy the following two files into the SD card FAT32 partition:
- <your_uefi_socfpga_directory>/uefi-socfpga/Build/DXE.ROM
- <your_uefi_socfpga_directory>/uefi-socfpga/AlteraPlatformPkg/Applications/LinuxLoader/bootz.nsh

Booting Linux from the DXE Phase Using SD/MMC Manually

When you boot the Linux^® zImage stored in QSPI Flash manually, the DXE phase boots until the UEFI shell appears and you type another command for further program execution. This can be done by typing the bootz command.

Note: This command runs the UEFI shell script <your_uefi_socfpga_directory>/uefi-socfpga/AlteraPlatformPkg/Applications/LinuxLoader/bootz.nsh which you copy into the FAT32 partition.

Figure 82. bootz Command when Booting Linux from the DXE Phase

Booting Linux from the DXE Phase Using SD/MMC Automatically

To configure Linux^® to boot automatically in the DXE phase, you must edit the UEFI shell start-up script. The startup.nsh is the start-up script file that the UEFI shell automatically runs at boot.

Use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/ShellScript/startup.nsh file.
Append the following line to the last line of the file:
```
bootz
```
Figure 83. startup.nsh Edit
Save the file and recompile the UEFI boot loader code.
Update the SD card image with the new PEI.ROM file for the changes to take effect.
Power cycle the board and observe the following output messages on your serial terminal program:

Figure 84. Terminal Output Message

Debugging an Example Project

Task time: 35 minutes

The Arm^® Development Studio 5^® Intel^® SoC FPGA Edition provides very powerful Bare Metal debugging capabilities. The Arm^® DS-5^® Intel^® SoC FPGA Edition debugger connects to an Intel^® Intel^® FPGA Download Cable II to debug a Bare Metal application.

This section describes how to configure the Eclipse Arm^® DS-5^® Intel^® SoC FPGA Edition platform and start the Arm^® DS-5^® Intel^® SoC FPGA Edition debugger from the Eclipse IDE using the debug view. The debug view allows you to manage the debugging and running of a program in the workbench. You can use the debug view to set breakpoints and watchpoints in the code and trace variables.

Configuring and Starting the Debugger in Eclipse

This task describes how to configure your project setting to use Eclipse with the Arm^® DS-5^® Intel^® SoC FPGA Edition debugger.

Connect the mini USB cable from the Intel^® Arria^® 10 SoC FPGA development board Intel^® FPGA Download Cable II port to the PC.
Verify that your JTAG Intel^® FPGA Download Cable II can detect the devices. The diagram below shows an example.

Figure 85. Verifying Device Detection
Start the Eclipse application if it is not yet started. Select Start Menu > All Programs > ARM DS-5 > Eclipse for DS-5 to start Eclipse from the program search window. Alternatively, you can start Eclipse from the Embedded Command Shell window.
The Eclipse tool, part of the Arm^® DS-5^® Intel^® SoC FPGA Edition, prompts for the workspace folder to be used. You can use the suggested folder and click OK.
The Arm^® DS-5^® Intel^® SoC FPGA Edition Welcome screen appears. You can use this screen to access documentation, tutorials and videos.
Select Window > Open Perspective > DS-5 Debug to open the workbench.

Figure 86. Opening the DS-5 Workbench
Select Run > Debug Configurations... to access the launch configurations.

Figure 87. Opening Debug Configurations
In the Debug Configuration dialog box left panel, select DS-5 Debugger > New_configuration

Figure 88. Opening New Configuration
Enter your preferred Name. In the example shown below, the Name text field has an entry of A10_SOC_DEBUG.

Figure 89. New Configuration Name Text Field
Configure the target to be Altera > Arria 10 SoC > Bare Metal Debug > Debug Cortex-A9_0.

Figure 90. Configure Target Connection
In the Target Connection pull-down menu, select USB-Blaster connection.

Figure 91. Select USB Blaster Connection
For the Bare Metal Debug Connection, click Browse… and select USB-BlasterII on localhost [USB-1]:USB-BlasterII USB-1.

Figure 92. Selecting Bare Metal Debug Connection
Select the Debugger tab and select the Connect only option.

Figure 93. Connect Only Selection for Run Control
Click the Debug button.
In the DS-5 Debug window, select Import Script….

Figure 94. Import Script
Browse to your Arm^® DS-5^® Intel^® SoC FPGA Edition script location under Build/load_uefi_fw.ds. In this example, /data/<username>/pggit/uefi-socfpga/Build/load_uefi_fw.ds is selected.

Figure 95. Browsing to the load_uefi_fw.ds File
Click Open.
Edit your load_uefi_fw.ds file by selecting the pencil icon.

Figure 96. Editing the load_uefi_fw.ds File
Verify the load_uefi_fw.ds file loads the correct Build/PEI.256 path. If not, edit the path to locate the correct Build/PEI.256 file path. In this example, the PEI.256 file is found at: /data/<username>/pggit/uefisocfpga/Build/PEI.256. Make the following change from the screenshot below:

Figure 97. Original PEI.256 Path

To the following path:
Figure 98. Modified PEI.256 Path
Click Save.
Double-click the load_uefi_fw.ds file to run the updated script.
If you encounter the error messages below, verify that you have edited the load_uefi_fw.ds to the correct path. Proceed to step 24 if you do not see this error.

Figure 99. Error Message Window
Click Save and double-click the load_uefi_fw.ds file to run the updated script.
Select Window > Show View > App Console to enable the App Console window.

Figure 100. Enabling the App Console Window
Click the continue green arrow to run the application.
The following content appears in the App Console window:

Figure 101. App Console Window

At the same time, pin multiplexing configuration output messages appear on the serial terminal program window.

Figure 102. Serial Terminal Pin Multiplexing Configuration Output Messages
Use the Outline view to edit and view your source file. If you encounter a "Source Not Found" error, click Set Path Substitution.

Figure 103. Correcting a "Source Not Found" Error
When the Edit Substitute Path dialog box appears, configure the Host Path to the correct path and click OK.

Figure 104. Configuring the Host Path

Setting a Breakpoint

You can set breakpoints in your program for debugging purposes. This task describes how to set a breakpoint on line 324 of the FpgaManager.c file.

Open the FpgaManager.c file from the Outline view.
Go to line 324 to insert the breakpoint. Right click and select DS-5 Breakpoints > Toggle Breakpoint.

Figure 105. Inserting a Breakpoint in the FpgaManager.c File
When you resume your application, the debugger stops on this line.

Figure 106. Breakpoint Stop
Use the Step Over or Step Into arrows in the Debug Window to step through your code.

Watching Variable Contents

This task describes how to check the contents of a variable.

Select Window > Show View > Variables.

Figure 107. Entering Variable Content View
Observe the content of your variables in the Variables window. The screenshot below shows the Locals variable content for the AlteraSDMmcPei.c file.

Figure 108. Locals Variable Watch

UEFI Boot Loader Customization

This section presents a list of useful customization recipes for the UEFI boot loader to run on your custom board.

Task time: 15 minutes

Changing the Platform Name

If you are not using the Intel^® Arria^® 10 SoC FPGA development board and want to change to your platform name, you can edit parameters in the Arria10SoCPkg.dsc file to support this.

Use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
Change the PLATFORM NAME below to your custom board name.

Figure 109. Editing the PLATFORM NAME in the Arria10soCPkg.dsc File
Configure the gAlteraSoCFpgaTokenSpaceGuid.PcdIsAlteraSoCFPGADevelopmentBoards value from 1 to 0.

Figure 110. Modifying the Board Specific PCD Value

Turning Off the Debug Features for Production Release

This task describes how to turn off the debugging feature of your UEFI for production release.

Use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
Configure the gAlteraHpsTokenSpaceGuid.PcdenableSemihosting value from 1 to 0.

Figure 111. Modifying Semihosting Support Parameter
In addition, you can also disable the following three suggested sections for your production release build in order to reduce the boot time.

Figure 112. Disabling Suggested Parameters for Boot Time Reduction

Modifying the UART Port Number for Serial Terminal Messages

The Intel^® Arria^® 10 SoC FPGA development board is uses UART1 for the serial terminal messages. If your custom board uses UART0 instead of UART1, you must change the UART base address so that your output messages display on the correct UART port.

Use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
Configure the gEfiMdeModulePkgTokenSpaceGuid.PcdSerialRegisterBase value from 0xFFC02100 to 0xFFC02000.

Figure 113. Modifying the UART Serial Terminal Parameter
If you want to boot faster and do not want to see any output messages in the serial terminal, configure the gEfiMdeModulePkgTokenSpaceGuid.PcdSerialRegisterBase value to 0x0.

Adding Custom Board Initialization Code

You can add your custom board initialization code to the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/PlatformPei/Board.c file.

Add your code in the function named BoardSpecificInitialization in the Board.c file. For the initial release of UEFI boot loader, the function call is at line 136, but the line number may change in the future.

Figure 114. Adding Custom Board Initialization Code

Enabling Checksum for the FPGA Image

Task time: 15 minutes

To prevent a system down caused by using a corrupted FPGA image, you can wrap the FPGA image with mkimage, and the mkimage header checksum can be used for verification to ensure the integrity of FPGA image is programmed into FPGA fabric.

Before programming the FPGA fabric, a section of FPGA image or full FPGA image is loaded to an on-chip RAM and SDRAM for computing. The checksum is verified as correct before the FPGA fabric is programmed.

Configuration in UEFI

To enable checksum for the FPGA image, use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
Configure the gAlteraSocFpgaTokenSpaceGuid.PcdCheckFpgaImage value to 1.

Figure 115. Enable the FPGA Image Checksum Parameter
Use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dts file.
Replace cff-file = "ghrd_10as066n2.periph.rbf" within the chosen node with cff-file = "ghrd_10as066n2.periph.rbf.mkimage".

Figure 116. Original cff-file Variable Value

Figure 117. cff-file Variable Value After Modification
Type the following command to generate the Arria10SoCPkg.dtb file.
```
$ dtc -O dtb -o Arria10SoCPkg.dtb -I dts Arria10SoCPkg.dts
```
Run make to compile UEFI. This process may take some time to complete.
```
$ make
```

Generate mkimage

Type the following command to convert the file.

$ quartus/bin/quartus_cpf -c --hps -o bitstream_compression=on 
<your_working_directory>/a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.sof 
<your_working_directory>/a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.rbf

This command creates the following files in the <your_working_directory>/a10_soc_devkit_ghrd/output_files/ folder:

Table 14. Resultant RBF File Output
File	Description
~ /a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.periph.rbf	I/O ring configuration file
~ /a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.core.rbf	FPGA fabric configuration file

Type the following command to add the mkimage header to ghrd_10as066n2.periph.rbf:

$ mkimage -A arm -T firmware -C none -O u-boot -a 0 -e 0 -n "RBF" -d ghrd_10as066n2.periph.rbf ghrd_10as066n2.periph.rbf.mkimage

Type the following command to add the mkimage header to the ghrd_10as066n2.core.rbf:
```
$ mkimage -A arm -T firmware -C none -O u-boot -a 0 -e 0 -n "RBF" -d ghrd_10as066n2.core.rbf ghrd_10as066n2.core.rbf.mkimage
```
The following files are now in your <your_working_directory>/a10_soc_devkit_ghrd/output_files/ folder:
Figure 118. Resultant mkimage Files

Create the SD Card image with the PEI.ROM, ghrd_10as066n2.periph.rbf.mkimage, and ghrd_10as066n2.core.rbf.mkimage.

Download the make_sdimage.py tool from here.
Note:
To obtain more information about the make_sdimage.py tool, please run the tool with the -h option:
```
$ ./make_sdimage.py -h
```

Create a new folder and cd to it. Copy the required files that are listed in the table below into the current folder.

Table 15. Required Files for the make_sdimage.py Tool
File	Description
~/uefi-socfpga/Build/PEI.ROM	UEFI boot loader image
~/uefi-socfpga/Build/DXE.ROM	Optional second phase of UEFI boot loader image when you want to boot to UEFI Shell
~/a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.core.rbf.mkimage	Compressed FPGA configuration file
~/a10_soc_devkit_ghrd/output_files/ghrd_10as066n2.periph.rbf.mkimage	Compressed FPGA I/O configuration file
`<SoCEDS_installation_directory>`/embeddedsw/socfpga/prebuilt_images/ socfpga_arria10.dtb	Linux Device Tree Blob
`<SoCEDS_installation_directory>`/embeddedsw/socfpga/prebuilt_images/zImage	Compressed Linux kernel image
`<SoCEDS_installation_directory>`/embeddedsw/socfpga/prebuilt_images/angstrom-rootfs.tar.gz	Root filesystem as a compressed tarball

Create the root filesystem for the SD card image.

$ mkdir rootfs

$ cd rootfs

$ sudo tar xzf ../angstrom-rootfs.tar.gz .

Call the make_sdimage.py script by typing the following:

$ cd ../

$ sudo ./make_sdimage.py -f -P PEI.ROM,num=3,format=raw,size=10M,type=A2 -P rootfs/*,num=2,format=ext3,size=1500M -P zImage,DXE.ROM,ghrd_10as066n2.core.rbf.mkimage,ghrd_10as066n2.periph.rbf.mkimage,socfpga_arria10.dtb,num=1,format=fat32,size=500M -s 2G -n sd_card_image_a10_uefi.img

Power on the board with the above SD image. If the image is corrupt, the error message "FPGA: Bad Data Checksum" appears.

NAND Bad Block Management

NAND is unmanaged flash and requires software to manage it. NAND is not reliable compared to other flash types such as NOR. Therefore, new NAND flash may contain some bad blocks. This issue can also apply throughout the life cycle of a NAND flash where certain blocks may turn bad.

Bad Block Marker

A block is the smallest entity for erase. Although the bad area might happen at certain pages, the whole block is marked as a bad block. The bad block marker is in the spare area (OOB) within the first page of each block. A block is considered bad if the value of a bad block marker is not 0xFF.

Figure 119. NAND Layout

Note: The bad block marker location at the spare area varies according to page size.

Table 16. NAND Bad Block Location by Manufacturer
Manufacturer	Chip Type	Page Size	Device Size	Bad Block Marker Location
Micron & Others ¹	SLC	512 bytes	x8	6th byte at 1st page OOB
Micron & Others¹	SLC	512 bytes	x16	1st byte at 1st page OOB
Micron & Others¹	SLC	>512 bytes	Any	1st byte at 1st page OOB
Micron	MLC	Any	Any	1st byte at 1st page OOB
Samsung	MLC	Any	Any	1st byte at last page OOB
Hynix	MLC	Any	Any	1st byte at last page OOB
Samsung	SLC	Any	Any	1st byte at 2nd page OOB
Hynix	SLC	Any	Any	1st byte at 2nd page OOB
Toshiba	SLC	Any	Any	1st byte at 2nd page OOB
AMD	SLC	Any	Any	1st byte at 2nd page OOB
Macronix	SLC	Any	Any	1st byte at 2nd page OOB

¹ Others refers to other configurations not mentioned in the table.

Bad Block Handling

You must specify the number of bad blocks that can be skipped through the programming of a particular image. By default, the gAlteraSocFpgaTokenSpaceGuid.PcdNandStopIfMoreThanThisNumberBadBlocks value is configured to 1 which means the UEFI flags a fail operation when it encounters more than one bad block.

Use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
Change the gAlteraSocFpgaTokenSpaceGuid.PcdNandStopIfMoreThanThisNumberBadBlock value to your requirements.

Note: You can choose to skip a bad block by specifying the skip or noskip option in the NAND command through the Pit Stop utility. For detailed information please refer to the NAND Flash sub-section in the List of Pit Stop Utility Commands and Use section.

Enabling the UEFI DXE Phase and the UEFI Shell

Task time: 60 minutes

For a Windows^® build, ensure that the SoC FPGA EDS and Arm^® DS-5^® Intel^® SoC FPGA Edition debugger tools are installed on your machine.
Complete the steps in Obtaining the UEFI Source Code.
To boot in the DXE phase, edit the ~:\uefisocfpga\AlteraPlatformPkg\Arria10SoCPkg\Arria10SoCPkg.dsc file to change the PcdBoot_LOAD_UEFI_DXE_PHASE token value from 0 to 1 before you run the make command. To edit the file type:
```
$ notepad AlteraPlatformPkg\Arria10SoCPkg\Arria10SoCPkg.dsc
```
Figure 120. Modifying the PcdBoot_LOAD_UEFI_DXE_PHASE Parameter
Verify that the SOCEDS_DEST_ROOT and DS5_ROOT is set under the Windows^® environment.
- Set SOCEDS_DEST_ROOT=c:\altera\15.1\embedded
- Set DS5_ROOT=”C:\Progra~1\DS-5”
Note: If you install Arm^® DS-5^® Intel^® SoC FPGA Edition in the Program Files, the path C:\Progra~1\DS-5 is to prevent a build error from occurring due to a space between the word “Program Files” in the path. For other locations, please set the path correctly.
Open a new Windows^® command prompt and execute the following commands:
```
~:\uefi-socfpga > setup

~:\uefi-socfpga> make
```
After the build is successful, you can copy the generated DXE.ROM file into the SD Card FAT32 partition.

Using the Network Feature Under the UEFI Shell

Task time: 20 minutes

This section describes how to use Ethernet features under the UEFI Shell after booting to the DXE Phase. The UEFI Shell network stack supports static and dynamic host configuration protocol (DHCP) IP Addressing. The basic functionality includes the standard network commands:

ifconfig
ping
tftp

Verify that your the HPS Ethernet port on your board is connected to the network.

Obtain the IP Address from the DHCP Server

Type 1 to select the shell.
Observe the following messages that confirm that the DHCP works.

Figure 121. DHCP Confirmation Messages

Note:
The first command, if config -s eth0 dhcp, that is shown in the screenshot above is to instruct the backend services to start DHCP initialization. On a typical corporate network, it may take up to 5 seconds for the DHCP server to assign the board an IP address. Thus, there is a stall 500000 command to delay 5 seconds.

The ifconfig -l eth0 command lists the IP address assigned to this board. For complete help, type help ifconfig in the UEFI Shell.

Use a Static IP Address

To use the static IPv4 address configuration for the Ethernet interface, type the following command:

ifconfig -s eth0 static 192.168.0.5 255.255.255.0 192.168.0.1

where the parameters are:

IFCONFIG [-s <Name> dhcp | <static <IP> <Mask> <Gateway>> | <dns <IP>>]

Note: Type help ifconfig for a detailed explanation of the command.

Ping Test

This task describes how to pin the host name of the IP address.

Complete the steps in Checking Your Machine or Laptop IPv4 Address.
Type the following command:
```
ping 137.57.118.26
```
Note: 137.57.118.26 is the host IP address.

Figure 122. Ping Test Output

TFTP Test

This task describes how to verify that the TFTP is working correctly on your board.

Complete the steps in TFTPd64 By Ph.Jounin Installation.
Complete the steps in Enabling the TFTP Server through the Windows Firewall.
Complete the steps in Using the TFTP Server in Windows.
Type the following command to perform the tftp test:
```
tftp 137.57.118.26 1.png
```
Note: 137.57.118.26 is the host IP address and 1.png is the file located in the base directory of the TFTP server.

Figure 123. tftp Command
When the tftp is complete, list the directory to confirm that the 1.png file has transferred successfully.

Figure 124. List 1.png File Transfer

Creating your First UEFI Application

This task describes how to create and run a HelloWorldBaremetal and BlinkingLED_A1-SoCDevKit application on a Intel^® Arria^® 10 SoC FPGA RevB.1 board.

Task time: 60 minutes

Open a Windows^® command prompt and go to the ~:\uefi-socfpga directory. Type the following command to compile the HelloWorldBaremetal and BlinkingLED_A10SoCDevKit example application:
```
$ make app
```
Expect the compilation to take some time. Files are generated under the UEFI root ~:\uefi-socfpga\Build folder during this time.
Figure 125. make app File Output
Copy the following two UEFI application images into the SD card.
- ~:\uefi-socfpga\Build\HelloWorldBaremetal.efi
- ~:\uefi- socfpga\Build\BlinkingLED_A10SoCDevKit.efi
Figure 126. Copying UEFI Application Images
Type the following commands under the UEFI shell on your board to run the UEFI application:
```
Shell> fs1:

FS1:\> HelloWorldBaremetal.efi

FS1:\> BlinkingLED_A10SoCDevKit.efi
```
Observe the following output messages on your serial terminal program:
Figure 127. Output Messages

Using Arm DS-5 Intel SoC FPGA Edition (For Windows Only)

Task time: 15 minutes

Importing the DS-5 Project

This task describes how to import the pre-existing Arm^® DS-5^® Intel^® SoC FPGA Edition project file in the UEFI Git repository's root directory into the Arm^® DS-5^® Intel^® SoC FPGA Edition project.

Launch Arm^® DS-5^® Intel^® SoC FPGA Edition in Eclipse.
Select File > Import.

Figure 128. File Import Selection in the Arm^® DS-5^® Intel^® SoC FPGA Edition Eclipse Window
Select General > Existing Projects into Workspace.

Figure 129. Selecting an Existing Project
Select the Browse button and browse to the root directory of the uefi-socfpga Git repository.

Figure 130. Browse to Project Location
Click Finish.

Building UEFI in Arm DS-5 Intel SoC FPGA Edition

At the Project Explorer window in Eclipse, right click on the root node and select Build Configurations > Set Active.
A list of build options that can be Set Active appear as shown below:
Figure 131. Build Configuration Options
Select Build All to perform the make operation or make app operation. Alternatively, select Clean All to perform the make clean operation.

Importing the Arm DS-5 Intel SoC FPGA Edition Debug Script

This task describes how to import the UEFI debug script that is generated under the UEFI root ~\uefi-socfpga\Build folder after the UEFI build completes.

Switch to the Arm^® DS-5^® Intel^® SoC FPGA Edition perspective by selecting Windows > Open Perspective > DS-5 Debug.

Figure 132. Opening DS-5 Debug
Select Windows > Show View > Scripts.
At the Scripts explorer window, click the import script icon.
Browse to the ~:\uefi-socfpga\Build folder and import the Arria10SoCPkg.ds5 file.

Pit Stop Utility Guide

Approximate time: 10 minutes

You can use the Pit Stop Utility to debug the Intel^® Arria^® 10 SoC UEFI Bootloader. This tool is available during the on-chip RAM boot phase after the HPS initialization and prior to booting to the subsequent SDRAM boot phase. When enabled, the tool prompts you with the message “Press any key in N seconds to enter Pit Stop utility”. This light weight command-line interpreter provides a fixed list of useful debug commands, such as:

Memory related commands: memory read, memory write, memory dump and memory compare.
QSPI/NAND Flash commands: probe, read, write, erase and update.
SD/MMC commands: block read and write.
FAT32 file system commands: list files, HEX dump of file and reading an entire file into memory.
CPU jump command: hands off to a program loaded at a specific memory offset address.

Enabling or Disabling the Pit Stop Utility

Intel^® recommends that you enable this debug feature during the development stage and disable it prior to product release.

Use your preferred editor to open the <your_uefi_socfpga>/uefi-socfpga/AlteraPlatformPkg/Arria10SoCPkg/Arria10SoCPkg.dsc file.
Configure the gAlteraSocFpgaTokenSpaceGuid.PcdEnablePitStopUtility to your requirements:
- 0 to disable
- 1 to enable
Figure 133. Modifying the Pit Stop Utility Parameter

Pit Stop Utility Commands and Use

Memory and Memory-Mapped I/O Commands

Command	Usage	Description
Read	`mr addr [count]`	32-bit memory read. Read a 32-bit word (4 bytes) of data from `addr` and display the data in HEX format. `addr`: memory address, must be 32-bit aligned. `count`: If not specified, the default value is 1. If specified, increase the address by a 32-bit word (4 bytes) for the next count.
Write	`mw addr data [count]`	32-bits memory write. Write a 32-bit word (4 bytes) of data to `addr`. If the `count` is more than one, the same piece of data is written to the subsequence address. `addr`: memory address must be 32-bit aligned. `count`: If not specified, the default value is 1. If specified, increase the address by a 32-bit word (4 bytes) for the next count.
Compare	`mcmp addr1 addr2 [count]`	32-bit memory compare. Compare a 32-bit word (4 bytes) of data between two different 32-bit memory locations for a `count` iteration and print out the differences in the process. `addr`: memory address, must be 32 bits aligned. `count`: If not specified,the default value is 1. If specified, increase the address by a 32-bit word (4 bytes) for the next count.
Dump	`mdmp addr len`	Memory Hex Dump. Each byte (8-bits) is represented as a two-digit hexadecimal number. `addr`: memory address, must be 32-bit aligned. `len`: number of bytes, must be 32-bit aligned.

QSPI Flash Commands

Command	Usage	Description
Probe	`qspi probe`	Initialize flash device
Read	`qspi read addr offset len`	Read ‘len’ bytes starting at ‘offset’ to memory at ‘addr’
Write	`qspi write addr offset len`	Write `len` bytes from memory at `addr` to flash at `offset`
Erase	`qspi erase offset len`	Erase `len` bytes of data from the offset
Update	`qspi update addr offset len`	Erase and write `len` bytes from memory at `addr` to flash at `offset`

NAND Flash Commands

Command	Usage	Description
Probe	`nand probe`	Initialize flash device
Bad	`nand bad`	Report the bad blocks
Read raw	`nand read addr offset len raw`	Read raw data `len` bytes starting at flash `offset` to memory at `addr`
Read skip	`nand read addr offset len skip`	Read `len` bytes starting at flash `offset` to memory at `addr` but skip bad block
Read noskip	`nand read addr offset len noskip`	Read `len` bytes starting at flash `offset` to memory at `addr` without skip bad block
Read spare	`nand read addr block page spare`	Read spare data `len` bytes starting at flash `offset` to memory at `addr`
Write raw	`nand write addr offset len raw`	Write raw data `len` bytes from memory at `addr` to flash at `offset`
Write skip	`nand write addr offset len skip`	Write `len` bytes from memory at addr to flash at `offset` but skip bad block
Write noskip	`nand write addr offset len noskip`	Write `len` bytes from memory at `addr` to flash at `offset` without skip bad block
Write spare	`nand write addr block page spare`	Write spare data `len` bytes from memory at `addr` to flash at `offset`
Erase skip	`nand erase offset len skip`	Erase `len` bytes from offset but skip bad blocks
Erase noskip	`nand erase offset len noskip`	Erase `len` bytes rom `offset` without skip bad blocks
Update skip	`nand update addr offset len skip`	Erase, then write `len` bytes from memory at `addr` to flash at `offset` but skip bad blocks
Update noskip	`nand update addr offset len noskip`	Erase then write `len` bytes from memory at `addr` to flash at `offset` without skip bad blocks

SD/MMC Commands

Command	Usage	Description
Read	`mmc read addr offset blockcnt`	Block Read. `addr`: memory address to read the data. `offset`: LBA block number to read from. `blockcnt`: number of blocks of data.
Write	`mmc write addr offset blockcnt`	Block Write. `addr`: memory address to write the data. `offset`: LBA block number to write to. `blockcnt`: number of blocks of data.

Command

Usage

Description

Read

mmc read addr offset blockcnt

Block Read.

addr: memory address to read the data.

offset: LBA block number to read from.

blockcnt: number of blocks of data.

Write

mmc write addr offset blockcnt

Block Write.

addr: memory address to write the data.

offset: LBA block number to write to.

blockcnt: number of blocks of data.

FAT32 File System Commands

Command	Usage	Description
List files	`ls`	Display a list of files in root directory of FAT32 partition.
Read file	`fatload mmc addr file`	Load a file into a memory location. `addr`: destination memory address. `file`: filename of a file located in root directory of a FAT32 partition
HexDump File	`hexdump file`	Display a file as HEX dump. `file`: filename of a file located in root directory of a FAT32 partition.

Command

Usage

Description

List files

ls

Display a list of files in root directory of FAT32 partition.

Read file

fatload mmc addr file

Load a file into a memory location.

addr: destination memory address.

file: filename of a file located in root directory of a FAT32 partition

HexDump File

hexdump file

Display a file as HEX dump.

file: filename of a file located in root directory of a FAT32 partition.

Others

Command	Usage	Description
Jump	`jump addr`	Transfers the flow of execution to the entry `addr`
Boot zImage	`bootz [filename.dtb]`	Boot Linux: SoC FPGA zImage `filename.dtb`: filename of a Linux^® .dtb file located in root directory of a FAT32 partition. If unspecified, it is based on the `PcdFileName_LINUX_DTB` parameter.
Program core rbf	`programrbf flashtype rbftype file/offset`	Program the core .rbf file into the SD/MMC, QSPI or NAND flash memory. If you are using SD/MMC flash: `flashtype`: mmc `rbftype`: core or peripheral or combined `file`: filename of your SD/MMC core.rbf file If you are using a QSPI flash: flashtype: qspi `rbftype`: core or peripheral or combined `offset`: in this case, the offset address which is 0x820000 If you are using NAND flash: `flashtype`: nand `rbftype`: core or peripheral or combined `offset`: in this case, the offset address which is 0x820000

Command

Usage

Description

Jump

jump addr

Transfers the flow of execution to the entry addr

Boot zImage

bootz [filename.dtb]

Boot Linux: SoC FPGA zImage

filename.dtb: filename of a Linux^® .dtb file located in root directory of a FAT32 partition. If unspecified, it is based on the PcdFileName_LINUX_DTB parameter.

Program core rbf

programrbf flashtype rbftype file/offset

Program the core .rbf file into the SD/MMC, QSPI or NAND flash memory.

If you are using SD/MMC flash:

flashtype: mmc
rbftype: core or peripheral or combined
file: filename of your SD/MMC core.rbf file

If you are using a QSPI flash:

flashtype: qspi
rbftype: core or peripheral or combined
offset: in this case, the offset address which is 0x820000

If you are using NAND flash:

flashtype: nand

rbftype: core or peripheral or combined

offset: in this case, the offset address which is 0x820000

Help

Command	Usage	Description
`help`	help	List all available commands in the Pit Stop Utility

Porting HWLIBs to UEFI Guidelines

Task time: 10 minutes

Coding Standard

UEFI follows the EDK2 coding standard v2 instead of the C coding standard in HWLIBs. The following sections highlight the EDK2 coding standard v2 guidelines.

General Rules

Do not use tab characters. Use spaces instead.
Start a new line with double spacing.

Naming Conventions

Start each word or concept with a capital letter followed by lowercase letters.

Example: UefiVariable

Type and Macro Names

Use all capital letters for both #define and typedef declarations. This clearly differentiates static declarations from dynamic data types.
```
UINT32 UefiVariable
```
Each word of a concept shall be separated by an underscore character. The underscore effectively separates the words, making the names more readable.
```
typedef UINT32 THIS_IS_AN_EXAMPLE_OF_WHAT_TO_DO_FOR_UEFI 
typedef struct MyStruct {
int one;
int two;
int three;
} MY_STRUCT;
```
The use of the _t suffix, designating a type, is not allowed.
The names of guard macros shall end with an underscore character.
```
#ifndef FILE_NAME_H_ 
#define FILE_NAME_H_ 
```

Variables

In UEFI, modular variables and global variables replace the static and global variables found in HWLIBs. Any variable with a file scope, or better, shall be prefixed by an m or g. There are no exceptions to this rule. The m prefix identifies a variable with module scope, while a g prefix identifies a global variable.

Example global variable: gThisIsAGlobalVariableName
Example modular variable: mThisIsaModuleVariableName

Function

Each type specification for the argument variable must be preceded by IN and /or OUT modifiers. The modifiers are used to indicate whether the argument is an input or output variable. It is recommended that the IN variables are first and OUT variables are next. If data passes in and out through a variable, mark it as both IN and OUT. Mark a buffer that passes into a routine that modifies the contents of the buffer as IN and OUT. EFIAPI is an optional functional modifier.

EFI_STATUS
EFIAPI
FunctionName (
		IN UINTN Arg1,
		IN UINTN Arg2,
		OUT UINTN *Arg3,
		IN OUT UINTN * Arg4
);
{
		UINTN Local;
		…
}

Comment

All comments must start with double slash // instead of /* and */.

// This is my comment

Data Types Conversion

Table 17. Conversion of Data Types from HWLIBS to UEFI
HWLIB	UEFI
`uint8_t`	`UINT8`
`uint16_t`	`UINT16`
`uint32_t`	`UINT32`
`uint64_t`	`UINT64`
`unsigned int`	`UINTN`
`char`	`CHAR8`
`bool`	`BOOLEAN`
`const`	`CONST`
`void`	`VOID`
`int`	`INTN`
`int8_t`	`INT16`
`int32_t`	`INT32`
`int64_t`	`INT64`

Status Code Conversion

Table 18. Status Code Conversion from HWLIBs to UEFI
HWLIB	UEFI
`ALT_STATUS_CODE`	`EFI_STATUS`
`ALT_E_SUCCESS`	`EFI_SUCCESS`
`ALT_E_ERROR`	`EFI_DEVICE_ERROR`
`ALT_E_FPGA_CFG`	N/A
`ALT_E_FPGA_CRC`	`EFI_CRC_ERROR`
`ALT_E_FPGA_CFG_STM`	N/A
`ALT_E_FPGA_PWR_OFF`	N/A
`ALT_E_FPGA_NO_SOC_CTRL`	N/A
`ALT_E_FPGA_NOT_USER_MODE`	`EFI_NOT_READY`
`ALT_E_ARG_RANGE`	`EFI_UNSUPPORTED`
`ALT_E_BAD_ARG`	`EFI_NOT_FOUND`
`ALT_E_BAD_OPERATION`	N/A
`ALT_E_INV_OPTION`	`EFI_INVALID_PARAMETER`
`ALT_E_TMO`	`EFI_TIMEOUT`
`ALT_E_RESERVED`	`EFI_ACCESS_DENIED`
`ALT_E_BAD_CLK`	N/A
`ALT_E_BAD_VERSION`	`EFI_INCOMPATIBLE_VERSION`
`ALT_E_BUF_OVF`	`EFI_VOLUME_FUL`

Header Conversion

Header	HWLIB	UEFI
IO memory access	`<stdio.h>`	`<Library/loLib.h>`
Memory	`<stdio.h>`	`<Library/BaseMemoryLib.h>` `<Library/MemoryAllocationLib.h>`
Debug	`<stdio.h>`	`<Library/DebugLib.h>` `<Library/PrintLib.h>` `<Library/SerialPortPrintLib.h>`
Timer	`<time.h>`	`<Library/TimerLib.h>`
Assert	`<assert.h>`	`Assert.h`
String/String Conversion	`<string.h>` `<stdlib.h>`	`<Library/BaseLib.h>`
Device Tree	N/A	`<libfdt.h>`
Math	`<math.h>`	`<Library/BaseLib.h>`

Basic I/O Functions Conversion

Table 19. Basic I/O Function Conversion from HWLIBs to UEFI
HWLIB	UEFI
`alt_write_word`	`MmioWrite32`
`alt_read_word`	`MmioRead32`
`alt_setbits_word`	`MmioOr32`
`alt_clrbits_word`	`MmioAnd32`

As an example, in HWLIBs the function:

alt_write_word (data, address);

must be written in the following way for UEFI:

MmioWrite32 (address, data);

Tera Term Installation

Task time: 20 minutes

Tera Term is an open-source, free, software implemented, terminal emulator (communications) program. It emulates different types of computer terminals, from DEC VT100 to DEC VT382. It supports telnet, SSH 1 and SSH 2 and serial port connections. It also has a built-in macro scripting language and useful plugins.

This task describes how to install Tera Term into your machine.

Download the tool from here.
Download the installer teraterm486.exe into your local drive.
Double-click on the Tera Term installer teraterm486.exe.
The Setup – Tera Term window appears. Click Next to continue the setup.

Figure 134. Tera Term Setup Wizard
Check the radio button for I accept the agreement and click Next.

Figure 135. Accepting the Tera Term Agreement
Leave the installation folder as default and click Next to proceed with the installation.

Figure 136. Selecting the Installation Folder
When the Select Components topic appears, click Next.
Select English (default) as the language to be used and click Next.
Leave the Start Menu Folder path as the default of Tera Term and click Next.

Figure 137. Tera Term Start Menu Folder
Leave the Additional Tasks selection as default and Click Next to continue.

Figure 138. Tera Term Additional Tasks Selection
When the Ready to Install window appears, click Install.

Figure 139. Ready to Install Selection
When the installation wizard finishes, the Completing the Tera Term Setup Wizard window appears. Click Finish to exit the Setup. Tera Term is installed.

Figure 140. Completing the Tera Term Setup Wizard

Making a Serial Connection

Start Tera Term by selecting Start > All Programs > Tera Term > Tera Term in the Program Files menu selection or by double-cliking on the Tera Term icon on your desktop.
When the Tera Term: New connection pop-up window appears within the program, select which serial port you would like to enable.
1. Select the Serial radio button.
2. Select your port from the Port drop down menu.
3. Press OK
Note: If the New connection window does not open when you start Tera Term, you can get there by navigating to File > New Connection....

Figure 141. Tera Term Serial Port Selection

The serial port connection opens. Tera Term defaults to a baud rate setting of 9600 bps (8 bit data-no parity-1 stop bit).
If you need to adjust the serial settings, go to Setup > Serial port....
In the Tera Term: Serial port setup window, adjust the settings in each of the pull down selections and click OK. In the example below, the serial port has a configuration of 115200 bps, 8-bit data, no parity and 1 stop bit.

Figure 142. Serial Port Setup Selection

The title of the Tera Term window changes to COM8:115200baud – Tera Term VT. The blank window with the blinking cursor is where data is both sent (by typing) and received.
Figure 143. New Tera Term Window
Configure your Tera Term: Keyboard setup as shown below:

Figure 144. Tera Term Keyboard Setup

Minicom Installation

Task time: 15 minutes

Minicom is a text-based modem control and terminal emulation program for Unix-like operating systems. A common use for Minicom is to setup a remote serial console.

The virtual serial port is usually named /dev/ttyUSB0. In order to determine the device name associated with the virtual serial port on your host PC, please perform the following steps:
1. Type ls /dev/ttyUSB* to determine which USB serial device are already installed
2. Connect mini USB cable from J10 to the PC. This will enable the PC to communicate with the board, even if the board is not powered yet.
3. Use the ls /dev/ttyUSB* command again to determine which new USB serial device appeared.
On CentOS, type:
```
sudo yum install minicom
```
On Ubuntu, type:
```
sudo apt-get install minicom
```

Making a Serial Connection

Configure Minicom.
```
$ sudo minicom -s
```
A configuration menu appears.
Figure 145. Configuration Menu
Under the Serial port setup, choose the following:
- Serial device: /dev/ttyUSB0 (edit to match the system as necessary)
- Bps/Par/Bits: 115200 8N1
- Hardware Flow Control: No
- Software Flow Control: No
Figure 146. Serial Port Setup
Hit [ESC] to return to the main configuration menu.
Select Save setup as dfl to save the default setup.
Select Exit to exit the menu.

Win32DiskImager Tool Installation

Task time: 10 minutes

Win32DiskImager writes a raw disk image to a removable device or can backup a removable device to a raw image file. It is very useful for embedded development, namely Arm^® development projects.

To install Win32DiskImager into your machine, execute the following steps:

Download the tool from here.
Download the installer Win32DiskImager-0.9.5-install.exe into your local drive.
Double-click the installer Win32DiskImager-0.9.5-install.exe to start the installation for Win32DiskImager into your local machine.
When the Setup – Win32DiskImager window appears, click Next to proceed.

Figure 147. Win32DiskImager Setup Window
Check the radio button for I accept the agreement and click Next.
Configure the installation path as below and click Next.

Figure 148. Installation Path
Leave the Select Start Menu Folder as the default Image Writer and click Next.

Figure 149. Select Start Menu Folder
Check the box for Create a desktop icon and click Next. The Ready to Install window appears.
Click Install to proceed with the installation.
When the installation wizard has finished, the Completing the Win32DiskImager Setup Wizard window appears. Click Finish to exit the setup. Win32DiskImager is now installed.

When the installation process completes, you can launch Win32DiskImager and view the README file. The README describes the functions and limitations of the Win32DiskImager and indicates that Win32DiskImager is a free tool released under a GNU General Public License (GPL).

Using Win32Disk Imager

Using Win32DiskImager is a very simple three-step process:

Select the IMG file you want to write.
Select the removable device onto which to write the IMG file.
Hit the Write button and wait for the process to complete.

TFTPd64 By Ph.Jounin Installation

Task time: 30 minutes

Tftp64 is an IPv6 ready application which includes DHCP, TFTP, DNS, SNTP and Syslog servers as well as a TFTP client. The program allows you to maximize performance when transferring the data from a TFTP server. The included DHCP server provides unlimited automatic or static IP address assignment.

Download the tool from here
Download the installer, tftpd64-4.51-setup.exe, into your local drive.
Double-click on the Tftpd64 installer, tftpd64-4.51-setup.exe.
Click I Agree.
Leave the installation components as default selection and click Next to proceed with the installation.

Figure 150. Tftpd64 Installation Options
Leave the installation directory as default and click Install to proceed.

Figure 151. Tftpd64 Installation Directory
When the installation completes, click Close to exit the installation setup.

Checking Your Machine or Laptop IPv4 Address

Click on your machine Internet connection access icon by selecting Open Network and Sharing Center.
Select Local Area Connection 3. The Local Area Connection 3 Status pop-up window appears.
Click on Details… .
Read the IPv4 Address.

Enabling the TFTP Server through the Windows Firewall

Click on your machine Internet connection access icon follow by selecting Open Network and Sharing Center.
Select Windows Firewall.
Select Allow a program or feature through Windows Firewall.
Scroll down and check the TFTP Server checkbox to allow this program to communicate through Windows^® Firewall

Figure 152. Enabling TFTP Server to Communication Through Firewall

Using the TFTP Server in Windows

Start Tftpd64 by selecting Start > All > Tftpd64 > Tftpd64. Alternatively, you can double-click the Tftpd64 icon on your desktop.
When the Tftpd64 program opens, click on the Settings button.

Figure 153. Selecting the Settings Button
Click on the Global tab and put a check mark only to the TFTP Server option. Remove checkmarks from all other options.

Figure 154. Tftpd64 Settings
Click on the TFTP tab. The tab appears as shown below.

Figure 155. Tftpd64 Global Settings: TFTP Tab
Click on the Browse button to specify the Base Directory. You must specify the Base Directory of the TFTP Server. Select the TFTP folder in your computer as the Base Directory.

Note: All the files transferred using TFTP Server are placed in the Base Directory.
Under the TFTP Security option, select the Standard option. Ensure that you select the option Bind TFTP to this address, which is your machine IPv4 address. Use the address that is available in the drop down box.
Once you have performed all the above steps, click OK. A window appears asking to restart Tftpd64 to apply the new settings.
Click OK.

Revision History of Intel Arria 10 SoC UEFI Boot Loader User Guide

Version	Changes
2017.12.15	Initial release

For Windows® System

For Linux® System

For Windows^® System

For Linux^® System