Intel Stratix 10 SoC UEFI Boot Loader User Guide

RSS

UG-20080 | 2017.06.19

Intel Stratix 10 SoC UEFI Boot Loader User Guide

This document provides comprehensive information on Unified Extensible Firmware Interface (UEFI) boot loader for Intel^® Stratix^® 10 SoC.

Boot Flow Overview

The binary image of the UEFI boot loader can be stored on Quad SPI flash, NAND flash, or an SD/MMC card. On board power-up, the secure device manager (SDM) loads the UEFI boot loader directly onto Hard Processor System (HPS) on-chip RAM.

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

Note: For non-secure boot, the operating system package can include kernel image, device tree blob and filesystem. For secure boot it can be a secure kernel.

Figure 1. UEFI Boot Flow Overview

Recommended System Requirements

To load and execute the 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 Tem for Windows)
- Micro SD card slot or Micro SD card writer or SD capable writer with SD to micro SD converter

Minimum Software Requirements

Intel^® SoC FPGA Embedded Development Suite (SoC EDS) v17.0
Stratix^® 10 SoC Virtual Platform v1.3

Getting Started

Download Software Components

You must install the Intel^® SoC FPGA EDS v17.0 on your machine.

Download the SoC EDS from the Download Center.

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, the following components must be installed on your machine:

Git (You can download it from Git)

If you are using a Linux system, install packages are required. 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

Note: Intel^® has verified that the Ubuntu 14.04 Linux distribution and the Community Enterprise Operating System (CentOS) 6.8 Linux distribution support the Stratix^® 10 SoC Virtual Platform.

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 it from the SoC EDS installation path, by typing:

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

Supported Compiler Toolchain

The supported UEFI compiler toolchain is:

Linaro^®:
- aarch64-linux-gnu-gcc (crosstool-NG linaro-1.13.1-4.8-2014.04 - Linaro GCC 4.8-2014.04) 4.8.3 20140401 (prerelease)
- If you are using a Linux system, download the gcc-linaro-aarch64-linux-gnu-4.8-2014.04_linux.tar.
- If you are using a Windows system, download the gcc-linaro-aarch64-linux-gnu-4.8-2014.04_win32.zip.

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

Compiling the UEFI Source Code with the Linaro Tool Chain

Windows System

This section explains how to compile the UEFI source code with the Linaro toolchain in a Windows system:

Open the command prompt.

Go to your working directory and set the SOCEDS_DEST_ROOT to the location of your SoC EDS.

$ cd <your_working_directory>\uefi-socfpga
$ set SOCEDS_DEST_ROOT=<your_SOCEDS_location>

Set the GCC path to the location of the compiler toolchain.
```
$ set PATH=<your_Linaro GCC Toolchain_location>;%PATH%
```
Note:
If you encountered GCC error while compiling the UEFI source code after setting the path, you can edit the setup.bat file manually by entering the following command to use the full compiler path.
```
set GCC48_ARM_PREFIX= %DS5_ROOT%\sw\gcc\bin\arm-linux-gnueabihf-
set GCC48_AARCH64_PREFIX= <your working directory>\uefi_17v0_window\gcc-linaro-aarch64-linux-gnu-4.8-2014.04_win32\bin\aarch64-linux-gnu-
```
Run the setup command.
```
$ setup.bat
```
Build the UEFI by entering the following command:
```
$ make device=s10
```
The command prompt displays "Build Done" message once the UEFI is successfully compiled.

Linux System

This section explains how to compile the UEFI source code with the Linaro toolchain in a Linux system:

Open a terminal and enter the following command:

$ cd <your_uefi_directory>/uefi-socfpga
$ export PATH=<your gcc directory>/gcc-linaro-aarch64-linux-gnu-4.8-2014.04_linux/bin:$PATH

Clean the entire <your_uefi_directory>/uefi-socfpga/Build/ folder and BaseTools folder by entering the following command:
```
$ make clean
```
Compile the UEFI boot loader for the Stratix^® 10 SoC device by entering the following command:
```
$ make DEVICE=s10
```
Your terminal displays a "Build Done" message once the UEFI is successfully compiled.

UEFI Generated Files

Compiling the UEFI source code creates the following files in the <your_uefi_directory>/uefisocfpga/Build/Stratix10SoCPkg/RELEASE_GCC48 folder:

Table 1. UEFI Generated Files
File	Description
~ /uefi-socfpga/Build/Stratix10SoCPkg/RELEASE_GCC48/PEI.256 (256KB)	This is the main UEFI boot loader file. It contains the device tree for the HPS and the code that initializes the HPS. After initialization, the HPS can boot to Bare Metal application, RTOS, and Linux. You can extend the UEFI boot phase to boot from the Driver Execution Environment ROM (DXE.ROM) file and configure the UEFI network and shell support. The UEFI boot loader file is generated from the mkpimage tool by adding a header to the original file located at ~/uefisocfpga/Build/Stratix10SoCPkg/RELEASE_GCC48/FV/ALTERA_HPS_OCRAM_EFI_PART1.fd. Because the file size is 256 KB, it loads directly into the HPS on-chip using ARM DS-5^® 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/Stratix10SoCPkg/RELEASE_GCC48/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/Stratix10SoCPkg/RELEASE_GCC48/load_uefi_fw.ds	This is the DS-5 script template. It is imported to the DS-5 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/Stratix10SoCPkg/RELEASE_GCC48/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.

Stratix 10 SoC Virtual Platform

Installing the Stratix 10 SoC Virtual Platform

You must have an account to gain access to the Download Center. You must also be logged in to continue.

You can download and install the Stratix^® 10 SoC Virtual Platform from Intel^® 's software site.

Download the Stratix^® 10 SoC Virtual Platform tar file (Stratix10_vp.tgz) from the Stratix 10 SoC Virtual Platform Download page to your chosen directory.
Uncompress the virtual platform by typing the following command:
```
tar zxvf Stratix10_vp.tgz
```
This command creates a directory named Stratix10_vp which contains an installer named install.sh.

install.sh is a simple script that runs install_s10socvp.exe for you. install_s10socvp.exe installs the virtual platform to your directory.
Install the Stratix^® 10 SoC Virtual Platform, using one of two methods:
Note: The directory ./altera should not exist prior to installation because the installer will not overwrite an existing directory.
- Method 1: Type the following command if you would like to read the End User License Agreement before installation:
```
./Stratix10_vp/install.sh ./altera
```
  The installer displays the following message:
```
Please press return to display the End User License Agreement
```
  After the license agreement is displayed, answer y or n to the prompt:
```
Do you accept this End User License Agreement? [y/n]:
```
- Method 2: Type the following command if you would like to accept the End User License Agreement in advance:
```
./Stratix10_vp/install.sh -a ./altera
```
The Stratix^® 10 SoC Virtual Platform is now installed in ./altera.

Installing and Booting a Pre-Built Linux Kernel for the Stratix 10 SoC Virtual Platform

You can use the pre-built Linux kernel provided on RocketBoards.org to boot the Stratix^® 10 SoC Virtual Platform.

Open a console and go to the directory where your virtual platform is installed:
```
cd <PATH_TO_VP_INSTALL_DIR>
```

At the Linux prompt, type the following command to download the Stratix^® 10 SoC Virtual Platform Linux images:

wget --no-cache http://rocketboards.org/foswiki/pub/Documentation/\
Stratix10SoCVPLinux/linux-stratix10swvp-socfpga-4.5-angstrom-v2014.12-\
swvp-1.3.tgz

Uncompress the tgz file by typing the following command:
```
tar xvzf ./linux-stratix10swvp-socfpga-4.5-angstrom-v2014.12-swvp-1.3.tgz
```
This command creates the following files under <PATH_TO_VP_INSTALL_DIR>:
- ./sd-angstrom-v2014.12-stratix10swvp.img: contains the SD/MMC root file system image
- ./linux-system-sd.elf: contains the Linux kernel image
Note:
If the .img file is not writeable, you will see this error message:
```
Cannot insert disk, file not found:
      ./sd-angstrom-v2014.12-stratix10swvp.img
```
To run the Stratix^® 10 SoC Virtual Platform with the default pre-built Linux binaries, type the following command:
```
cd <PATH_TO_VP_INSTALL_DIR>
./run.exe
```
After the command completes, an Ångström prompt appears and you are at the login prompt. Login with a username of “root” and leave the password field blank to enter the root directory.

Running the SoC Virtual Platform with the UEFI Boot Loader

Follow these steps to run the Stratix^® 10 SoC Virtual Platform with the UEFI boot loader:

Go to SoC Virtual Platform installation directory, edit parameters.txt file to enable GNU debugger (GDB) session. You can enable the GBD session by uncommenting gdbstub_port=1234 statement in parameters.txt file.
Change your directory to the directory where your virtual platform is installed and launch the run.exe.
```
$ cd <your SoCVP directory>   
$ ./run.exe
```

Open a new terminal and launch a debugger by typing the following commands:

$ cd <Path to linaro toolchain>/ gcc-linaro-aarch64-linux-gnu-4.8-2014.04_linux/bin
$ ./aarch64-linux-gnu-gdb

Type the following commands at the GDB debugger prompt:

$ target remote:1234
$ restore <Path to UEFI source code>/Build/Stratix10SoCPkg/RELEASE_GCC48/PEI.256 binary 0xffe00000
$ set var $pc=0xffe00000

Run the SoC Virtual Platform by typing the following command:
```
$ continue
```

Ping and DHCP Test

This section describes how to use basic standard network commands: ifconfig and ping.

Ping Test

You can perform a ping test to verify network connectivity and communications. Follow these steps to perform the ping test. This test requires that you have installed the SoC Virtual Platform.

Launch the GNU debugger (GDB) using the instructions in the "Running the SoC Virtual Platform with the UEFI Boot Loader" section.

Enter the following commands at the GDB console:

$ target remote:1234
$ restore <Path to UEFI source code>/Build/Stratix10SoCPkg/RELEASE_GCC48/PEI.256 binary 0xffe00000
$ restore <Path to UEFI source code>/Build/Stratix10SoCPkg/RELEASE_GCC48/DXE.ROM binary 0x02000000
$ set var $pc=0xffe00000

Run the SoC Virtual Platform by typing the following command:
```
$ continue
```

Enter the following commands at the DXE console:

$ ifconfig -s eth0 static 192.168.0.9 255.255.255.0 192.168.0.1
$ ifconfig -l eth0
$ ping -n 2 192.169.0.1

Figure 2. Ping Test- DXE Console

DHCP Test

You can perform a DHCP test to the IP address of the DHCP server. Follow these steps to perform the DHCP test:

Launch the DXE console using the instructions in the "Ping Test" section.
Type the following command at the DXE console:
```
$ ifconfig -s eth0 dhcp
$ ifconfig -l eth0
```
The target console looks similar to the view below:

Figure 3. DHCP Test- Target Console

Note: A startup.nsh script is compiled when you build the boot loader. This script executes the commands automatically when DXE phase is entered.

TFTP

This section describes how to install a TFTP server and verify its functionality.

Note: You can perform the TFTP test only in a Linux based SoC Virual Platform environment.

Installing a TFTP Server at the CentOS Host Machine

Follow these steps to install a TFTP server at the CentOS host machine:

Install the required packages by typing the following command:
```
$ sudo yum install httpd xinetd syslinux tftp-server
```
Edit the /etc/xinetd.d/tftp file by typing following command:
```
$ vi /etc/xinetd.d/tftp
```
Enable the TFTP server by changing the disable=yes to no. You can change the server path to your desired location.
Change the TFTP port from 69 to 70 in the services.txt file to enable the transfer of the UDP packets.
```
$ sudo vi /etc/services
```

To start the TFTP server, type the following command:

$ sudo service xinetd stop
$ sudo service xinetd start

Running the TFTP on the Client Side

To run the TFTP on the client side follow these steps:

Boot to DXE phase using the instructions in the "Ping Test" section.
To apply the static IPv4 address configuaration for Ethernet interface, enter the following command at the DXE console:
```
$ ifconfig -s eth0 static 192.168.0.9 255.255.255.0 192.168.0.1
$ ifconfig -l eth0
```

Perform the TFTP test by typing the following commands:

$ fs 1:
$ tftp -r 70 192.168.0.1 <file located in the based directory of TFTP server>

Once the TFTP test is completed, ensure that the file is successfully transferred by typing the following command:
```
$ ls
```

Booting Linux From the Pit Stop Console

The following section describes how to boot Linux from the Pit Stop console. The Pit Stop Utility is a lightweight command-line interpreter that provides debug support through a fixed list of commands.

Note: Ensure that you have downloaded the SoC Virtual Platform.

Run the SoC Virtual Platform with the UEFI boot loader images using the instructions in "Running the SoC Virtual Platform with the UEFI Boot Loader" section.
Once UEFI boot loader is loaded, press any key to enter Pit Stop Utility.
To boot Linux from RAM enter the following command:
```
$ bootr
```

Booting VxWorks from DXE Console

Follow these steps to boot VxWorks from DXE Console:

Run the SoC Virtual Platform and open the DXE console using the instructions in the "Ping Test" section.
Using the DXE console, move the VxWorks image into your FAT partition. You can transfer the VxWorks image to your FAT partition in one of two ways:
- Use TFTP
- Include the VxWorks image in the SDM image you create
The following steps describe the TFTP method. You can configure your TFTP server and run the TFTP on the client side using the instructions in the "TFTP" section.
After the file transfer is complete, run the following commands at the DXE console to boot VxWorks.
```
$ runaxf vxWorks
```
Figure 4. Booting VxWorks at the DXE Console
VxWorks boots on the console. The target console looks similar to the view below:
Figure 5. Target Console

Booting PXE using Stratix 10 SoC Virtual Platform

The following section describes how to setup a Preboot Execution Environment (PXE) boot for the Stratix^® 10 SoC Virtual Platform on a dedicated Ubuntu machine.

Network Setup

Dependencies

To set up a PXE server on an Ubuntu machine, you must install certain dependencies. Type the following command:
```
$ sudo aptitude install bridge-utils iproute2
```
Ensure that the "tun" kernel module is in place.
```
$ sudo modprobe tun
```

Setup Internet via eth0 and Bridge through DHCP

For this configuration, you must establish an Internet connection through WiFi (wlan0 interface), which is on an external network. The IP address is obtained from an external DHCP server. The figure below depicts the Internet connection as a separate subnetwork.

You must also create a local sub-network with a local DHCP network. Local DHCP offers IP addresses to bridge interface br0. The PXE server (next server) is a bridge itself. The UEFI boot loader communicates with the PXE server through the TAP interface tap0. The Stratix^® 10 SoC UEFI boot loader obtains IP address for its eth0 interface from the DHCP server on br0 through tap0.

Figure 6. Setting up Internet

Configuration

To configure the network, you must create a script with the following commands. Ensure that you edit the user variable properly.

user=your-user-name
tap=tap0
bridge=br0
nic=eth0
echo "---> Creating taps..."
ip tuntap add dev $tap mode tap user $user
ip link set dev $tap up
echo "---> Creating bridge..."
brctl addbr $bridge
brctl setfd $bridge 0
brctl addif $bridge $nic
brctl addif $bridge $tap
echo "---> Bringing interfaces and bridge up..."
ifconfig $tap 192.168.0.4 promisc up
ifconfig $nic 192.168.0.9 promisc up
ifconfig $bridge 192.168.0.1 netmask 255.255.255.0 up
echo "---> Restart DHCP server"
service isc-dhcp-server restart

Run the next script from root. Be sure to use 192.168.0.1 as a PXE server IP address.
Note: If your "isc-dhcp-server" package wasn't installed correctly (with error message [FAIL] Starting ISC DHCP server: dhcpd[....] check syslog for diagnostics), be sure to run next command after executing script above: $ sudo dpkg –configure isc-dhcp-server

Preparing the Boot Image

A standard EFI application is required to prepare a boot image for PXE test. Use HelloWorld.efi located at Build\Stratix10SoCPkg\RELEASE_GCC48\AARCH64\HelloWorld.efi

Copy the HelloWorld.efi file to the TFTP boot file path by typing the following command:

$ cp HelloWorld.efi /var/lib/tftpboot

Setting up the TFTP Server in Ubuntu

Follow these steps to enable file transfer over the network:

Install the TFTP server by typing the following command:
```
$ sudo apt-get install tftpd-hpa tftp
```

Edit the /etc/default/tftpd-hpa file.

TFTP_USERNAME="tftp"
TFTP_DIRECTORY="/var/lib/tftpboot"
TFTP_ADDRESS="0.0.0.0:70"
TFTP_OPTIONS="--secure"

Starting Xinetd Services

You can run tftp daemon by two different ways:

Allow tftpd to run continuously by specifying RUN_DAEMON="yes" in tftpd-hpa configuration file.
Allow super-server to handle tftpd starting.

"Xinetd" is super-server daemon. It receives incoming requests over a network and launches the appropriate service for that request. In this case, Xinetd starts tftpd service when it caches TFTP request over the network. Follow these steps to start Xinetd services:

Install Xinetd by typing the following command:
```
$ sudo apt-get install xinetd
```
Create an /etc/xinetd.d/ftp file by entering the following commands:
```
service tftp
{
protocol = udp
port = 70
socket_type = dgram
wait = yes
user = root
server = /usr/sbin/in.tftpd
server_args = --secure /var/lib/tftpboot
disable = no
}
```
Note:
The ftp file contains the following arguments:
- server_args= -- secure: Use relative patches (not absolute).
- server_args=/var/lib/tftpboot: Path to TFTP files.
- disable=no: Enable spawning TFTPD process.
You may see the "man tftpd" for more details.
Once the configuration is modified, restart the Xinetd by typing the following command:
```
$ sudo service xinetd restart
```

Disable Firewall

Disable the firewall to ensure that it is not blocking DHCP/TFTP traffic (UDP).

You can turn off the firewall by entering the following commands:

$ iptables -F
$ iptables -X
$ iptables -P INPUT ACCEPT
$ iptables -P FORWARD ACCEPT
$ iptables -P OUTPUT ACCEPT
$ iptables -t mangle -F
$ iptables -t mangle -X
$ iptables -t nat -F
$ iptables -t nat -X

Check the iptables by running the following command:
```
$ iptables-save
```

DHCP Server

The DHCP server assigns IP addresses to clients.

Follow these steps to setup the DHCP server:

Install the DHCP server by entering the following command:
```
$ sudo apt-get install isc-dhcp-server
```
Note: If installation wasn't completed due to error, you can complete this after the network bridge is up. You can complete the "isc-dhcp-server" package installation using the sudo dpkg - - configure command.
You must edit the etc/default/isc-dhcp-server file with the following command:
```
INTERFACES=”br0”
```
Modify the etc/dhcp/dhcpd.conf file with the following commands:
```
allow booting;
allow bootp;
subnet 192.168.0.0 netmask 255.255.255.0 {
range 192.168.0.100 192.168.0.253;
}
next-server 192.168.01;
filename “HelloWorld.efi”;
```
Note: The dhcpd.conf file contains the following arguments:
- next-server: IP address of PXE server for that PC.
- filename: Boot loader file to be offered via TFTP.

Removing Configuration

You must create a script with the following commands to remove the configuration completed in the previous section.

tap=tap0
bridge=br0
nic=eth0
if ! brctl show | grep $bridge >/dev/null; then
echo -n "TAP Bridge $bridge does not exist "
echo "and no FMNetwork to stop."
exit 1
fi
# take down the bridge
ifdown $bridge
# remove the interfaces from the bridge
for tap in $taps; do
brctl delif $bridge $tap
ifconfig $tap down
# tapctrl -n $tap -a delete -t tap
ip link set dev $tap down
ip tuntap del dev $tap mode tap
done
brctl delif $bridge $nic
# delete the bridge
ifconfig $bridge down
brctl delbr $bridge
# unset promiscuous mode
ifconfig $nic -promisc
ifup $nic

PXE Client- UEFI

This section describes how to setup a PXE client with the UEFI boot loader running on the Stratix^® 10 SoC Virtual Platform and perform PXE boot.

SOC Virtual Platform Setting

The parameter.txt file must be modified with the following settings to enable the TAP interface for SoC Virtual Platform:

vlan:type = tap
#vlan:ifname = tap0 #This is default value
eth_mac = D0:67:E5:48:F4:49
multicast_passthrough = 1 #enable multicast messaging

Note: eth_mac is the MAC address of bridge br0.

Boot UEFI

Follow these steps to boot the next stage image with PXE boot:

Use the instructions in the "Ping Test" section to boot from the DXE console.
Press any key to choose the boot selection.
At the DXE console:
1. Enter 3 to choose the Boot Manager.
2. Enter 1 to choose the Add Boot Device Entry.
3. Enter 3 to choose the boot device which is PXE on MAC Address: 02:11:22:33:44:55.
4. Enter y to select an EFI application.
5. Type pxe as the Description for this new Entry.
6. Enter 7 to Return to main menu.
7. pxe appears in the boot selection menu. Enter 2 to boot from the PXE.
The console displays "Hello World" when the board is booted up successfully from the PXE.

Figure 7. Display Console

Revision History of Stratix 10 SoC UEFI Boot Loader User Guide

Date	Version	Changes
June 2017	2017.06.19	Initial release