GSRD User Guide
Introduction¶
GSRD Overview¶
The Golden System Reference Design (GSRD) is a reference design running on the Agilex™ 5 E-Series Premium Development Kit.
The GSRD is comprised of the following components:
- Golden Hardware Reference Design (GHRD)
- Reference HPS software including:
- Arm Trusted Firmware
- U-Boot
- Linux Kernel
- Linux Drivers
- Sample Applications
Prerequisites¶
The following are required to be able to fully exercise the Agilex 5 Premium Development Kit GSRD:
-
Altera® Agilex™ 5 FPGA E-Series 065B Premium Development Kit, ordering code DK-A5E065BB32AES1. Refer to board documentation for more information about the development kit.
- HPS Enablement Expansion Board. Included with the development kit.
- HPS NAND Board. Enables eMMC storage for HPS. Orderable separately.
- HPS Test Board. Supports SD card boot, and external Arm tracing. Orderable separately.
- Mini USB Cable. Included with the development kit.
- Micro USB Cable. Included with the development kit.
- Ethernet Cable. Included with the development kit.
- Micro SD card and USB card writer. Included with the development kit.
- Host PC with:
- 64 GB of RAM. Less will be fine for only exercising the binaries, and not rebuilding the GSRD.
- Linux OS installed. Ubuntu 22.04LTS was used to create this page, other versions and distributions may work too
- Serial terminal (for example GtkTerm or Minicom on Linux and TeraTerm or PuTTY on Windows)
- Altera® Quartus® Prime Pro Edition Version 24.3
- The instructions for rebuilding the binaries use Quartus version 24.2
- TFTP server. This used to download the eMMC binaries to board to be flashed by U-Boot
- Local Ethernet network, with DHCP server
- Internet connection. For downloading the files, especially when rebuilding the GSRD.
Prebuilt Binaries¶
The Agilex™ 5 Modular Development Kit GSRD binaries are located at https://releases.rocketboards.org/2024.07/:
Boot Source | Link |
---|---|
SD Card | https://releases.rocketboards.org/2024.11/gsrd/agilex5_modular_gsrd/ |
QSPI | https://releases.rocketboards.org/2024.11/qspi/agilex5_modular_qspi/ |
Component Versions¶
Altera® Quartus® Prime Pro Edition Version 24.3 and the following software component versions are used to build the GSRD:
Component | Location | Branch | Commit ID/Tag |
---|---|---|---|
GHRD | https://github.com/altera-opensource/ghrd-socfpga | master | QPDS24.3_REL_GSRD_PR |
Linux | https://github.com/altera-opensource/linux-socfpga | socfpga-6.6.37-lts | QPDS24.3_REL_GSRD_PR |
Arm Trusted Firmware | https://github.com/arm-trusted-firmware | socfpga_v2.11.0 | QPDS24.3_REL_GSRD_PR |
U-Boot | https://github.com/altera-opensource/u-boot-socfpga | socfpga_v2024.04 | QPDS24.3_REL_GSRD_PR |
Yocto Project | https://git.yoctoproject.org/poky | scarthgap | latest |
Yocto Project: meta-intel-fpga | https://git.yoctoproject.org/meta-intel-fpga | scarthgap | latest |
Yocto Project: meta-intel-fpga-refdes | https://github.com/altera-opensource/meta-intel-fpga-refdes | scarthgap | QPDS24.3_REL_GSRD_PR |
Release Notes¶
See https://www.rocketboards.org/foswiki/Documentation/IntelFPGAHPSEmbeddedSoftwareRelease
Development Kit¶
This release targets the Agilex 5 FPGA E-Series 065B Premium Development Kit. Refer to board documentation for more information about the development kit.
Installing HPS Daughtercard
This section shows how to install the included HPS Enablement Daughtercard. The installation for the other optional HPS Boards is similar.
1. Identify the correct thumb screws and washers needed, they are in a plastic bag:
2. Locate the area on the development board where the HPS Daughtercard needs to be installed:
3. Place the plastic washers on top of the three hex mounting posts:
4. Place HPS Board on top of the posts and washers:
5. Place the hex thumb screws on the two posts, as shown below. Note the 3rd one on the bottom is best unplaced as fully screwing that in may move the board. Also note the thumb screw close to the Ethernet connector is hard to screw, recommend to use small pliers and patience to make it secure. It is important that the HPS Board is secure, and does not move:
Note: If you need to swap HPS Boards frequently, it is recommended to remove the hex posts, and install the plastic washers between the PCB and the posts. This way you do not need to be careful for the washers not to move when you place the HPS Board on top of the posts. Note there are also plastic washers underneath the development board PCB, make sure to leave those in place when performing this operation
Changing MSEL
MSEL signals instruct the FPGA device on which configuration scheme to use. Configuration schemes used by the scenarios presented in this guide are JTAG and QSPI. MSEL is changed through dipswitch SW27. Only change the settings while the board is powered off.
Configuration OFF-OFF-OFF-OFF corresponds to JTAG:
Configuration OFF-ON-ON-OFF corresponds to JTAG:
GHRD Overview¶
The Golden Hardware Reference Design is an important part of the GSRD and consists of the following components:
- Hard Processor System (HPS)
- Dual core Arm Cortex-A76 processor
- Dual core Arm Cortex-A55 processor
- HPS Peripherals connected to HPS Enablement Expansion Board:
- Micro SD Card
- EMAC
- HPS JTAG debug
- I3C
- UART
- USB 3.1
- Multi-Ported Front End (MPFE) for HPS External Memory Interface (EMIF)
- FPGA Peripherals connected to Lightweight HPS-to-FPGA (LWH2F) AXI Bridge and JTAG to Avalon Master Bridge
- Three user LED outputs
- Four user DIP switch inputs
- Four user push-button inputs
- System ID
- FPGA Peripherals connected to HPS-to-FPGA (H2F) AXI Bridge
- 256KB of FPGA on-chip memory
The GHRD allows hardware designers to access each peripheral in the FPGA portion of the SoC with System Console, through the JTAG master module. This signal-level access is independent of the driver readiness of each peripheral.
MPU Address Maps
This section presents the address maps as seen from the MPU side.
HPS-to-FPGA Address Map
The three FPGA windows in the MPU address map provide access to 256 GB of FPGA space. First window is 1 GB from 00_4000_0000, second window is 15 GB from 04_4000_0000, third window is 240 GB from 44_0000_0000. The following table lists the offset of each peripheral from the HPS-to-FPGA bridge in the FPGA portion of the SoC.
Peripheral | Address Offset | Size (bytes) | Attribute |
---|---|---|---|
onchip_memory2_0 | 0x0 | 256K | On-chip RAM as scratch pad |
Lightweight HPS-to-FPGA Address Map
The the memory map of system peripherals in the FPGA portion of the SoC as viewed by the MPU, which starts at the lightweight HPS-to-FPGA base address of 0x00_2000_0000, is listed in the following table.
Peripheral | Address Offset | Size (bytes) | Attribute |
---|---|---|---|
sysid | 0x0001_0000 | 32 | Unique system ID |
led_pio | 0x0001_0080 | 16 | LED outputs |
button_pio | 0x0001_0060 | 16 | Push button inputs |
dipsw_pio | 0x0001_0070 | 16 | DIP switch inputs |
JTAG Master Address Map
There are three JTAG master interfaces in the design, one for accessing non-secure peripherals in the FPGA fabric, and another for accessing secure peripheral in the HPS through the FPGA-to-HPS Interface and another for FPGA fabric to SDRAM.
The following table lists the address of each peripheral in the FPGA portion of the SoC, as seen through the non-secure JTAG master interface.
Peripheral | Address Offset | Size (bytes) | Attribute |
---|---|---|---|
onchip_memory2_0 | 0x0004_0000 | 256K | On-chip RAM |
sysid | 0x0001_0000 | 32 | Unique system ID |
led_pio | 0x0001_0080 | 16 | LED outputs |
button_pio | 0x0001_0060 | 16 | Push button inputs |
dipsw_pio | 0x0001_0070 | 16 | DIP switch inputs |
Interrupt Routing
The HPS exposes 64 interrupt inputs for the FPGA logic. The following table lists the interrupt connections from soft IP peripherals to the HPS interrupt input interface.
Peripheral | Interrupt Number | Attribute |
---|---|---|
dipsw_pio | f2h_irq0[0] | 4 DIP switch inputs |
button_pio | f2h_irq0[1] | 4 Push button inputs |
Exercising Prebuilt Binaries¶
This section presents how to use the prebuilt binaries included with the GSRD release.
Configure Board¶
1. Leave all jumpers and switches in their default configuration.
2. Install the appropriate HPS Daughtercard.
3. Connect mini USB cable from vertical connector on HPS Daughtercard to host PC. This is used for the HPS serial console.
4. Connect micro USB cable from development board to host PC. This is used by the tools for JTAG communication.
5. Connect Ethernet cable from HPS Board to an Ethernet switch connected to local network. Local network must provide a DCHP server.
Configure Serial Console¶
All the scenarios included in this release require a serial connection. This section presents how to configure the serial connection.
1. Install a serial terminal emulator application on your host PC:
- For Windows: TeraTerm or PuTTY are available
- For Linux: GtkTerm or Minicom are available
2. Power down your board if powered up. This is important, as once powered up, with the micro USB JTAG cable connected, a couple more USB serial ports will enumerate, and you may choose the wrong port.
3. Connect mini-USB cable from the vertical mini-USB connector on the HPS Board to the host PC
4. On the host PC, an USB serial port will enumerate. On Windows machines it will be something like COM4
, while on Linux machines it will be something like /dev/tty/USB0
.
5. Configure your serial terminal emulator to use the following settings:
- Serial port: as mentioned above
- Baud rate: 115,200
- Data bits: 8
- Stop bits: 1
- CRC: disabled
- Hardware flow control: disabled
6. Connect your terminal emulator
HPS Enablement Board¶
This section presents how to use HPS Enablement Board to boot from SD card, and also from QSPI.
Booting from SD Card¶
Write SD Card
1. Download SD card image from the prebuilt binaries https://releases.rocketboards.org/2024.05/gsrd/agilex5_dk_a5e065bb32aes1_gsrd/sdimage.tar.gz and extract the archive, obtaining the file gsrd-console-image-agilex5_devkit.wic
.
2. Write the gsrd-console-image-agilex5_devkit.wic. SD card image to the micro SD card using the included USB writer in the host computer:
- On Linux, use the
dd
utility as shown next: - On Windows, use the Win32DiskImager program, available at https://sourceforge.net/projects/win32diskimager. For this, first rename the gsrd-console-image-agilex5_devkit.wic to an .img file (sdcard.img for example) and write the image as shown in the next figure:
Write QSPI Flash
1. Power down board
2. Set MSEL dipswitch SW27 to JTAG: OFF-OFF-OFF-OFF
3. Power up the board
4. Download and extract the JIC image, then write it to QSPI
wget https://releases.rocketboards.org/2024.05/gsrd/agilex5_dk_a5e065bb32aes1_gsrd/ghrd_a5ed065bb32ae6sr0.hps.jic.tar.gz
tar xf ghrd_a5ed065bb32ae6sr0.hps.jic.tar.gz
quartus_pgm -c 1 -m jtag -o "pvi;ghrd_a5ed065bb32ae6sr0.hps.jic"
Boot Linux
1. Power down board
2. Set MSEL dipswitch SW27 to ASX4 (QSPi): OFf-ON-ON-OFF
3. Power up the board
4. Wait for Linux to boot, use root
as user name, and no password wil be requested.
Run Sample Applications
1. Boot to Linux
2. Change current folder to intelFPGA
folder
syscheck
application
Press q
to exit the syscheck
application.
Control LEDs
1. Boot to Linux
2. Control LEDs by using the following sysfs entries:
- /sys/class/leds/fpga_led0/brightness
- /sys/class/leds/fpga_led1/brightness
- /sys/class/leds/fpga_led2/brightness
- /sys/class/leds/hps_led1/brightness
using commands such as:
cat /sys/class/leds/fpga_led0/brightness
echo 0 > /sys/class/leds/fpga_led0/brightness
echo 1 > /sys/class/leds/fpga_led1/brightness
Because of how the LEDs are connected, for the above commands 0
means LED is turned on, 1
means LED is turned off.
Connect to Board Using SSH
1. Boot to Linux
2. Determine the board IP address using the ifconfig
command:
root@agilex5devkit:~# ifconfig
eth0: flags=-28605<UP,BROADCAST,RUNNING,MULTICAST,DYNAMIC> mtu 1500
inet 192.168.1.153 netmask 255.255.255.0 broadcast 192.168.1.255
inet6 fe80::f0eb:c8ff:fec4:eed7 prefixlen 64 scopeid 0x20<link>
ether f2:eb:c8:c4:ee:d7 txqueuelen 1000 (Ethernet)
RX packets 649 bytes 45132 (44.0 KiB)
RX errors 0 dropped 226 overruns 0 frame 0
TX packets 56 bytes 8789 (8.5 KiB)
TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
device interrupt 23
lo: flags=73<UP,LOOPBACK,RUNNING> mtu 65536
inet 127.0.0.1 netmask 255.0.0.0
inet6 ::1 prefixlen 128 scopeid 0x10<host>
loop txqueuelen 1000 (Local Loopback)
RX packets 100 bytes 8408 (8.2 KiB)
RX errors 0 dropped 0 overruns 0 frame 0
TX packets 100 bytes 8408 (8.2 KiB)
TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
root
username, no password will be requested:
Note: Make sure to replace the above IP address to the one matching the output of running ifconfig
on youir board.
Visit Board Web Page
1. Boot to Linux
2. Determine board IP address using ifconfig
like in the previous scenario
3. Start a web browser and enter the IP address in the address bar
4. The web browser will display a page served by the web server running on the board.
- You will able to see which LED are ON and OFF in LED Status.
- You can Start and Stop the LED from scrolling. Set the delay(ms) in the LED Lightshow box.
- You can controll each LED with ON and OFF button.
- Blink each LED by entering the delay(ms) and click on the BLINK button.
Booting from QSPI¶
This section presents how to boot from QSPI. One notable aspect is that you need to wipe the SD card partitioning information, as otherwise U-Boot SPL could find a valid SD card image, and try to boot from that first.
Wipe SD Card
Either write 1MB of zeroes at the beginning of the SD card, or remove the SD card from the HPS Daughter Card. You can use dd
on Linux, or Win32DiskImager
on Windows to achieve this.
Write QSPI Flash
1. Power down board
2. Set MSEL dipswitch SW27 to JTAG: OFF-OFF-OFF-OFF
3. Power up the board
4. Download and extract the JIC image, then write it to QSPI:
wget https://releases.rocketboards.org/2024.05/qspi/agilex5_dk_a5e065bb32aes1_qspi/agilex_flash_image.hps.jic.tar.gz
tar xf agilex_flash_image.hps.jic.tar.gz
quartus_pgm -c 1 -m jtag -o "pvi;agilex_flash_image.hps.jic"
Boot Linux
1. Power down board
2. Set MSEL dipswitch SW27 to ASX4 (QSPi): OFf-ON-ON-OFF
3. Power up the board
4. Wait for Linux to boot, use root
as user name, and no password wil be requested.
Note: On first boot, the UBIFS rootfilesystem is initialized, and that takes a few minutes. This will not happen on next reboots. See a sample log below:
[ 17.033558] UBIFS (ubi0:4): Mounting in unauthenticated mode
[ 17.039470] UBIFS (ubi0:4): background thread "ubifs_bgt0_4" started, PID 130
[ 17.061510] UBIFS (ubi0:4): start fixing up free space
[ 20.644496] random: crng init done
[ 27.120040] platform soc:leds: deferred probe pending
[ 243.190874] UBIFS (ubi0:4): free space fixup complete
[ 243.315909] UBIFS (ubi0:4): UBIFS: mounted UBI device 0, volume 4, name "rootfs"
[ 243.323290] UBIFS (ubi0:4): LEB size: 65408 bytes (63 KiB), min./max. I/O unit sizes: 8 bytes/256 bytes
[ 243.332653] UBIFS (ubi0:4): FS size: 167117440 bytes (159 MiB, 2555 LEBs), max 6500 LEBs, journal size
HPS NAND Board¶
This section presents how to use HPS NAND Board to boot from eMMC.
Booting from eMMC¶
Configure Board
For this scenario, we are using the HPS NAND Board, which can be configured through dipswitch SW3 to enable either eMMC or NAND. Set SW3 to ON to enable eMMC.
Write eMMC Flash
We are writing the eMMC Flash by using U-Boot commands. We are getting to U-Boot prompt by booting from QSPI using a JIC image which contains U-Boot, thereby not relying on what is already in eMMC.
1. Download, and extract the eMMC image
wget https://releases.rocketboards.org/2024.05/emmc/agilex5_dk_a5e065bb32aes1_emmc/sdimage.tar.gz
tar xf sdimage.tar.gz
xaa
and xab
on your TFTP folder.
3. Power down the board.
4. Set MSEL dipswitch SW27 to JTAG: OFF-OFF-OFF-OFF
5. Power up the board
6. Download the helper JIC used to write the eMMC image, extract it and write it to QSPI:
wget https://releases.rocketboards.org/2024.05/emmc/agilex5_dk_a5e065bb32aes1_emmc/uboot.jic.tar.gz
tar xf uboot.jic.tar.gz
quartus_pgm -c 1 -m jtag -o "pvi;uboot.jic"
ifconfig
to use it as the IP address of the TFTP server
8. Power down the board
9. Set MSEL dipswitch SW27 to ASX4 (QSPi): OFf-ON-ON-OFF
10. Power up the board
11. Stop U-Boot at the boot countdown, to drop to U-Boot console
12. At the U-Boot console, run the following commands to write the SD card image:
setenv autoload no
dhcp
setenv serverip <tftp_server_ip_address>
tftp ${loadaddr} xaa
setexpr blkcnt1 ${filesize} / 0x200
mmc write ${loadaddr} 0 ${blkcnt1}
tftp ${loadaddr} xab
setexpr blkcnt2 ${filesize} / 0x200
mmc write ${loadaddr} ${blkcnt1} ${blkcnt2}
Write QSPI Flash
1. Power down the board.
2. Set MSEL dipswitch SW27 to JTAG: OFF-OFF-OFF-OFF
3. Power up the board
4. Download the JIC and write it to QSPI:
wget https://releases.rocketboards.org/2024.05/emmc/agilex5_dk_a5e065bb32aes1_emmc/ghrd_a5ed065bb32ae6sr0.hps.jic.tar.gz
tar xf ghrd_a5ed065bb32ae6sr0.hps.jic.tar.gz
quartus_pgm -c 1 -m jtag -o "pvi;ghrd_a5ed065bb32ae6sr0.hps.jic"
Boot Linux
1. Power down the board.
2. Set MSEL dipswitch SW27 to ASX4 (QSPi): OFf-ON-ON-OFF
3. Power up the board
4. Board will boot to Linux. Enter root
as username, no password will be requested
HPS Test Board¶
This section presents how to use HPS Test Board to boot from SD card.
Booting from SD Card¶
Configure Board
For this scenario we are using the HPS Test Board. There is single dipswitch on that board called SW1, which needs to be set to the ON position.
Write SD Card
1. Download SD card image from the prebuilt binaries https://releases.rocketboards.org/2024.05/debug/agilex5_dk_a5e065bb32aes1_debug/sdimage.tar.gz and extract the archive, obtaining the file gsrd-console-image-agilex5_devkit.wic
.
2. Write the SD card image to the micro SD card using the included USB writer in the host computer, and dd
utility on Linux, or Win32DiskImager on Windows, available at https://sourceforge.net/projects/win32diskimager. Please refer to the Booting from SD Card section for more details about this.
Write QSPI Flash
1. Power down the board.
2. Set MSEL dipswitch SW27 to JTAG: OFF-OFF-OFF-OFF
3. Power up the board
4. Download the JIC and write it to QSPI:
wget https://releases.rocketboards.org/2024.05/debug/agilex5_dk_a5e065bb32aes1_debug/ghrd_a5ed065bb32ae6sr0.hps.jic.tar.gz
tar xf ghrd_a5ed065bb32ae6sr0.hps.jic.tar.gz
quartus_pgm -c 1 -m jtag -o "pvi;ghrd_a5ed065bb32ae6sr0.hps.jic"
Boot Linux
1. Power down the board.
2. Set MSEL dipswitch SW27 to ASX4 (QSPi): OFf-ON-ON-OFF
3. Power up the board
4. Board will boot to Linux. Enter root
as username, no password will be requested
Rebuilding the GSRD¶
Yocto Build Prerequisites¶
1. Make sure you have Yocto system requirements met: https://docs.yoctoproject.org/5.0.1/ref-manual/system-requirements.html#supported-linux-distributions.
The command to install the required packages on Ubuntu 22.04 is:
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install openssh-server mc libgmp3-dev libmpc-dev gawk wget git diffstat unzip texinfo gcc \
build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping \
python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint xterm python3-subunit mesa-common-dev zstd \
liblz4-tool git fakeroot build-essential ncurses-dev xz-utils libssl-dev bc flex libelf-dev bison xinetd \
tftpd tftp nfs-kernel-server libncurses5 libc6-i386 libstdc++6:i386 libgcc++1:i386 lib32z1 \
device-tree-compiler curl mtd-utils u-boot-tools net-tools swig -y
On Ubuntu 22.04 you will also need to point the /bin/sh to /bin/bash, as the default is a link to /bin/dash:
Note: You can also use a Docker container to build the Yocto recipes, refer to https://rocketboards.org/foswiki/Documentation/DockerYoctoBuild for details. When using a Docker container, it does not matter what Linux distribution or packages you have installed on your host, as all dependencies are provided by the Docker container.
HPS Enablement Board¶
This section presents how to build the binaries for HPS Enablement Board.
Build SD Card Boot Binaries¶
The following diagram shows an overview of how the build process works for this use case:
Setup Environment
1. Create the top folder to store all the build artifacts:
sudo rm -rf agilex5_gsrd.enablement
mkdir agilex5_gsrd.enablement
cd agilex5_gsrd.enablement
export TOP_FOLDER=`pwd`
Download the compiler toolchain, add it to the PATH variable, to be used by the GHRD makefile to build the HPS Debug FSBL:
cd $TOP_FOLDER
wget https://developer.arm.com/-/media/Files/downloads/gnu/11.2-2022.02/binrel/\
gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu.tar.xz
tar xf gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu.tar.xz
rm -f gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu.tar.xz
export PATH=`pwd`/gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu/bin:$PATH
export ARCH=arm64
export CROSS_COMPILE=aarch64-none-linux-gnu-
Enable Quartus tools to be called from command line:
export QUARTUS_ROOTDIR=~/intelFPGA_pro/24.3/quartus/
export PATH=$QUARTUS_ROOTDIR/bin:$QUARTUS_ROOTDIR/linux64:$QUARTUS_ROOTDIR/../qsys/bin:$PATH
Build Hardware Design
cd $TOP_FOLDER
rm -rf ghrd-socfpga agilex5_soc_devkit_ghrd
git clone -b QPDS24.3_REL_GSRD_PR https://github.com/altera-opensource/ghrd-socfpga
mv ghrd-socfpga/agilex5_soc_devkit_ghrd .
rm -rf ghrd-socfpga
cd agilex5_soc_devkit_ghrd
make config
make DEVICE=A5ED065BB32AE6SR0 HPS_EMIF_MEM_CLK_FREQ_MHZ=800 HPS_EMIF_REF_CLK_FREQ_MHZ=100 generate_from_tcl
make sof
cd ..
The following files are created:
$TOP_FOLDER/agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0.sof
$TOP_FOLDER/agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0_hps_debug.sof
Build Core RBF
cd $TOP_FOLDER
rm -f ghrd_a5ed065bb32ae6sr0.rbf
quartus_pfg -c agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0_hps_debug.sof ghrd_a5ed065bb32ae6sr0.rbf -o hps=1
The following file is created:
$TOP_FOLDER/ghrd_a5ed065bb32ae6sr0.core.rbf
Set Up Yocto
1. Clone the Yocto script and prepare the build:
cd $TOP_FOLDER
rm -rf gsrd-socfpga
git clone -b QPDS24.3_REL_GSRD_PR https://github.com/altera-opensource/gsrd-socfpga
cd gsrd-socfpga
. agilex5_dk_a5e065bb32aes1-gsrd-build.sh
build_setup
Customize Yocto
1. Save the core.rbf
as $WORKSPACE/meta-intel-fpga-refdes/recipes-bsp/ghrd/files/agilex5_dk_a5e065bb32aes1_gsrd_ghrd.core.rbf
2. Update the recipe $WORKSPACE/meta-intel-fpga-refdes/recipes-bsp/ghrd/hw-ref-design.bb
as follows:
- Replace the entry
${GHRD_REPO}/agilex5_dk_a5e065bb32aes1_gsrd_${ARM64_GHRD_CORE_RBF};name=agilex5_dk_a5e065bb32aes1_gsrd_core
withfile://agilex5_dk_a5e065bb32aes1_gsrd_ghrd.core.rbf;sha256sum=<CORE_SHA>
whereCORE_SHA
is the sha256 checksum of the file - Delete the line
SRC_URI[agilex5_dk_a5e065bb32aes1_gsrd_core.sha256sum] = "bf11c8cb3b6d9487f93ce0e055b1e5256998a25b25ac4690bef3fcd6225ee1ae"
The above are achieved by the following instructions:
CORE_RBF=$WORKSPACE/meta-intel-fpga-refdes/recipes-bsp/ghrd/files/agilex5_dk_a5e065bb32aes1_gsrd_ghrd.core.rbf
ln -s $TOP_FOLDER/ghrd_a5ed065bb32ae6sr0.core.rbf $CORE_RBF
OLD_URI="\${GHRD_REPO}\/agilex5_dk_a5e065bb32aes1_gsrd_\${ARM64_GHRD_CORE_RBF};name=agilex5_dk_a5e065bb32aes1_gsrd_core"
CORE_SHA=$(sha256sum $CORE_RBF | cut -f1 -d" ")
NEW_URI="file:\/\/agilex5_dk_a5e065bb32aes1_gsrd_ghrd.core.rbf;sha256sum=$CORE_SHA"
sed -i "s/$OLD_URI/$NEW_URI/g" $WORKSPACE/meta-intel-fpga-refdes/recipes-bsp/ghrd/hw-ref-design.bb
sed -i "/agilex5_dk_a5e065bb32aes1_gsrd_core\.sha256sum/d" $WORKSPACE/meta-intel-fpga-refdes/recipes-bsp/ghrd/hw-ref-design.bb
Build Yocto
Build Yocto:
Gather files:
The following files are created:
$TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot-spl-dtb.hex
$TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot.itb
$TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/sdimage.tar.gz
Build QSPI Image
cd $TOP_FOLDER
rm -f ghrd_a5ed065bb32ae6sr0.hps.jic ghrd_a5ed065bb32ae6sr0.core.rbf
quartus_pfg \
-c agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0.sof ghrd_a5ed065bb32ae6sr0.jic \
-o device=MT25QU128 \
-o flash_loader=A5ED065BB32AE6SR0 \
-o hps_path=gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot-spl-dtb.hex \
-o mode=ASX4 \
-o hps=1
The following file is created:
$TOP_FOLDER/ghrd_a5ed065bb32ae6sr0.hps.jic
Build HPS RBF
This is an optional step, in which you can build an HPS RBF file, which can be used to configure the HPS through JTAG instead of QSPI though the JIC file.
cd $TOP_FOLDER
rm -f ghrd_a5ed065bb32ae6sr0.hps.rbf
quartus_pfg \
-c agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0.sof ghrd_a5ed065bb32ae6sr0.rbf \
-o hps_path=gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot-spl-dtb.hex \
-o hps=1
The following file is created:
$TOP_FOLDER/ghrd_a5ed065bb32ae6sr0.hps.rbf
Build QSPI Boot Binaries¶
The diagram below shows how booting from QSPI JIC is built. The hardware project compilation and Yocto build remain the same, and the QSPI JIC is built based on the resulted files:
1. Create the folder to contain all the files:
2. Get the ubinize.cfg
file which contains the details on how to build the root.ubi
volume, and agilex5_devkit_flash_image_hps.pfg
which contains the instructions for Programming File Generator on how to create the .jic file:
wget https://releases.rocketboards.org/2024.05/qspi/agilex5_dk_a5e065bb32aes1_qspi/ubinize.cfg
wget https://releases.rocketboards.org/2024.05/qspi/agilex5_dk_a5e065bb32aes1_qspi/agilex5_devkit_flash_image_hps.pfg
3. Link to the files that are needed from building the hardware design, and yocto:
ln -s $TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/console-image-minimal-agilex5_nor.ubifs rootfs.ubifs
ln -s $TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/kernel.itb .
ln -s $TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/boot.scr.uimg
ln -s $TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot-spl-dtb.hex .
ln -s $TOP_FOLDER/agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0.sof .
4. Process the u-boot.itb file to be exactly 2MB in size:
cp $TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot.itb .
uboot_part_size=2*1024*1024
uboot_size=`wc -c < u-boot.itb`
uboot_pad="$((uboot_part_size-uboot_size))"
truncate -s +$uboot_pad u-boot.itb
mv u-boot.itb u-boot.bin
5. Create the root.ubi
file and rename it to hps.bin
as Programming File Generator needs the .bin
extension:
6. Create the JIC file:
HPS NAND Board¶
This section presents how to build the binaries for HPS NAND Board, for booting from eMMC.
Build eMMC binaries¶
The following diagram shows how to build the eMMC binaries that target the HPS NAND Daughtercard:
Setup Environment
1. Create the top folder to store all the build artifacts:
Download the compiler toolchain, add it to the PATH variable, to be used by the GHRD makefile to build the HPS Debug FSBL:
cd $TOP_FOLDER
wget https://developer.arm.com/-/media/Files/downloads/gnu/11.2-2022.02/binrel/\
gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu.tar.xz
tar xf gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu.tar.xz
rm -f gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu.tar.xz
export PATH=`pwd`/gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu/bin:$PATH
export ARCH=arm64
export CROSS_COMPILE=aarch64-none-linux-gnu-
Enable Quartus tools to be called from command line:
export QUARTUS_ROOTDIR=~/intelFPGA_pro/24.3/quartus/
export PATH=$QUARTUS_ROOTDIR/bin:$QUARTUS_ROOTDIR/linux64:$QUARTUS_ROOTDIR/../qsys/bin:$PATH
Build Hardware Design
cd $TOP_FOLDER
rm -rf ghrd-socfpga agilex5_soc_devkit_ghrd
git clone -b QPDS24.3_REL_GSRD_PR https://github.com/altera-opensource/ghrd-socfpga
mv ghrd-socfpga/agilex5_soc_devkit_ghrd .
rm -rf ghrd-socfpga
cd agilex5_soc_devkit_ghrd
make config
make DEVICE=A5ED065BB32AE6SR0 HPS_EMIF_MEM_CLK_FREQ_MHZ=800 HPS_EMIF_REF_CLK_FREQ_MHZ=100 DAUGHTER_CARD=devkit_dc_emmc generate_from_tcl
make sof
cd ..
The following files are created:
$TOP_FOLDER/agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0.sof
$TOP_FOLDER/agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0_hps_debug.sof
Build Core RBF
cd $TOP_FOLDER
rm -f ghrd_a5ed065bb32ae6sr0.rbf
quartus_pfg -c agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0_hps_debug.sof ghrd_a5ed065bb32ae6sr0.rbf -o hps=1
The following file is created:
$TOP_FOLDER/ghrd_a5ed065bb32ae6sr0.core.rbf
Set Up Yocto
1. Clone the Yocto script and prepare the build:
cd $TOP_FOLDER
rm -rf gsrd-socfpga
git clone -b QPDS24.3_REL_GSRD_PR https://github.com/altera-opensource/gsrd-socfpga
cd gsrd-socfpga
. agilex5_dk_a5e065bb32aes1-gsrd-build.sh
build_setup
Customize Yocto
1. Save the core.rbf
as $WORKSPACE/meta-intel-fpga-refdes/recipes-bsp/ghrd/files/agilex5_dk_a5e065bb32aes1_emmc_ghrd.core.rbf
2. Update the recipe $WORKSPACE/meta-intel-fpga-refdes/recipes-bsp/ghrd/hw-ref-design.bb
as follows:
- Replace the entry
${GHRD_REPO}/agilex5_dk_a5e065bb32aes1_emmc_${ARM64_GHRD_CORE_RBF};name=agilex5_dk_a5e065bb32aes1_emmc_core
withfile://agilex5_dk_a5e065bb32aes1_emmc_ghrd.core.rbf;sha256sum=<CORE_SHA>
whereCORE_SHA
is the sha256 checksum of the file - Delete the line
SRC_URI[agilex5_dk_a5e065bb32aes1_emmc_core.sha256sum] = "bf11c8cb3b6d9487f93ce0e055b1e5256998a25b25ac4690bef3fcd6225ee1ae"
The above are achieved by the following instructions:
CORE_RBF=$WORKSPACE/meta-intel-fpga-refdes/recipes-bsp/ghrd/files/agilex5_dk_a5e065bb32aes1_emmc_ghrd.core.rbf
ln -s $TOP_FOLDER/ghrd_a5ed065bb32ae6sr0.core.rbf $CORE_RBF
OLD_URI="\${GHRD_REPO}\/agilex5_dk_a5e065bb32aes1_emmc_\${ARM64_GHRD_CORE_RBF};name=agilex5_dk_a5e065bb32aes1_emmc_core"
CORE_SHA=$(sha256sum $CORE_RBF | cut -f1 -d" ")
NEW_URI="file:\/\/agilex5_dk_a5e065bb32aes1_emmc_ghrd.core.rbf;sha256sum=$CORE_SHA"
sed -i "s/$OLD_URI/$NEW_URI/g" $WORKSPACE/meta-intel-fpga-refdes/recipes-bsp/ghrd/hw-ref-design.bb
sed -i "/agilex5_dk_a5e065bb32aes1_emmc_core\.sha256sum/d" $WORKSPACE/meta-intel-fpga-refdes/recipes-bsp/ghrd/hw-ref-design.bb
Build Yocto
Build Yocto:
Gather files:
The following files are created:
$TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot-spl-dtb.hex
$TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot.itb
$TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/sdimage.tar.gz
Build QSPI Image
cd $TOP_FOLDER
rm -f ghrd_a5ed065bb32ae6sr0.hps.jic ghrd_a5ed065bb32ae6sr0.core.rbf
quartus_pfg \
-c agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0.sof ghrd_a5ed065bb32ae6sr0.jic \
-o device=MT25QU128 \
-o flash_loader=A5ED065BB32AE6SR0 \
-o hps_path=gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot-spl-dtb.hex \
-o mode=ASX4 \
-o hps=1
The following file is created:
$TOP_FOLDER/ghrd_a5ed065bb32ae6sr0.hps.jic
Build HPS RBF
This is an optional step, in which you can build an HPS RBF file, which can be used to configure the HPS through JTAG instead of QSPI though the JIC file.
cd $TOP_FOLDER
rm -f ghrd_a5ed065bb32ae6sr0.hps.rbf
quartus_pfg \
-c agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0.sof ghrd_a5ed065bb32ae6sr0.rbf \
-o hps_path=gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot-spl-dtb.hex \
-o hps=1
The following file is created:
$TOP_FOLDER/ghrd_a5ed065bb32ae6sr0.hps.rbf
Building QSPI Helper JIC
We are writing the eMMC Flash by using U-Boot commands. We are getting to U-Boot prompt by booting from QSPI using a helper JIC image which contains U-Boot, thereby not relying on what is already in eMMC. The following diagram illustrates how the helper JIC is built, base on the GHRD and Yocto compilation results:
1. Create folder to contain the helper JIC artifacts
2. Retrieve the .pfg file instructing the Quartus Programming File Generator on how to create the JIC file, and tweak it a little bit to make it smaller:
cd jic-helper
wget https://releases.rocketboards.org/2024.05/emmc/agilex5_dk_a5e065bb32aes1_emmc/uboot-only.pfg
sed -i 's/directory=/hps="1" directory=/g' uboot-only.pfg
sed -i 's/type="JIC"/type="PERIPH_JIC"/g' uboot-only.pfg
sed -i 's/MT25QU02G/MT25QU01G/g' uboot-only.pfg
3. Bring in the files that are needed:
ln -s $TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot-spl-dtb.hex .
ln -s $TOP_FOLDER/agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0.sof .
4. Process u-boot.itb
file to be exactly 2MB in size, and have a .bin
extension as needed by Quartus Programming File Generator:
cp $TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot.itb .
uboot_part_size=2*1024*1024
uboot_size=`wc -c < u-boot.itb`
uboot_pad="$((uboot_part_size-uboot_size))"
truncate -s +$uboot_pad u-boot.itb
mv u-boot.itb u-boot.bin
5. Create the JIC file:
The following file will be created:
$TOP_FOLDER/jic-helper/agilex_flash_image.hps.jic
HPS Test Board¶
This section presents how to build the binaries for HPS Test Board.
Build SD Card Binaries¶
The following diagram shows how the binaries are built for the HPS Test Daughtercard:
Setup Environment
1. Create the top folder to store all the build artifacts:
Download the compiler toolchain, add it to the PATH variable, to be used by the GHRD makefile to build the HPS Debug FSBL:
cd $TOP_FOLDER
wget https://developer.arm.com/-/media/Files/downloads/gnu/11.2-2022.02/binrel/\
gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu.tar.xz
tar xf gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu.tar.xz
rm -f gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu.tar.xz
export PATH=`pwd`/gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu/bin:$PATH
export ARCH=arm64
export CROSS_COMPILE=aarch64-none-linux-gnu-
Enable Quartus tools to be called from command line:
export QUARTUS_ROOTDIR=~/intelFPGA_pro/24.3/quartus/
export PATH=$QUARTUS_ROOTDIR/bin:$QUARTUS_ROOTDIR/linux64:$QUARTUS_ROOTDIR/../qsys/bin:$PATH
Build Hardware Design
cd $TOP_FOLDER
rm -rf ghrd-socfpga agilex5_soc_devkit_ghrd
git clone -b QPDS24.3_REL_GSRD_PR https://github.com/altera-opensource/ghrd-socfpga
mv ghrd-socfpga/agilex5_soc_devkit_ghrd .
rm -rf ghrd-socfpga
cd agilex5_soc_devkit_ghrd
make config
make DEVICE=A5ED065BB32AE6SR0 HPS_EMIF_MEM_CLK_FREQ_MHZ=800 HPS_EMIF_REF_CLK_FREQ_MHZ=100 DAUGHTER_CARD=debug2 generate_from_tcl
make sof
cd ..
The following files are created:
$TOP_FOLDER/agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0.sof
$TOP_FOLDER/agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0_hps_debug.sof
Build Core RBF
cd $TOP_FOLDER
rm -f ghrd_a5ed065bb32ae6sr0.rbf
quartus_pfg -c agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0_hps_debug.sof ghrd_a5ed065bb32ae6sr0.rbf -o hps=1
The following file is created:
$TOP_FOLDER/ghrd_a5ed065bb32ae6sr0.core.rbf
Set Up Yocto
1. Clone the Yocto script and prepare the build:
cd $TOP_FOLDER
rm -rf gsrd-socfpga
git clone -b QPDS24.3_REL_GSRD_PR https://github.com/altera-opensource/gsrd-socfpga
cd gsrd-socfpga
. agilex5_dk_a5e065bb32aes1-gsrd-build.sh
build_setup
Customize Yocto
Replace the file $WORKSPACE/meta-intel-fpga-refdes/recipes-bsp/ghrd/files/agilex5_dk_a5e065bb32aes1_debug2_ghrd.core.rbf
with the rebuilt core.rbf file:
CORE_RBF=$WORKSPACE/meta-intel-fpga-refdes/recipes-bsp/ghrd/files/agilex5_dk_a5e065bb32aes1_debug2_ghrd.core.rbf
rm -f $CORE_RBF
ln -s $TOP_FOLDER/ghrd_a5ed065bb32ae6sr0.core.rbf $CORE_RBF
Build Yocto
Build Yocto:
Gather files:
The following files are created:
$TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot-spl-dtb.hex
$TOP_FOLDER/gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/sdimage.tar.gz
Build QSPI Image
cd $TOP_FOLDER
rm -f ghrd_a5ed065bb32ae6sr0.hps.jic ghrd_a5ed065bb32ae6sr0.core.rbf
quartus_pfg \
-c agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0.sof ghrd_a5ed065bb32ae6sr0.jic \
-o device=MT25QU128 \
-o flash_loader=A5ED065BB32AE6SR0 \
-o hps_path=gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot-spl-dtb.hex \
-o mode=ASX4 \
-o hps=1
The following file is created:
$TOP_FOLDER/ghrd_a5ed065bb32ae6sr0.hps.jic
Build HPS RBF
This is an optional step, in which you can build an HPS RBF file, which can be used to configure the HPS through JTAG instead of QSPI though the JIC file.
cd $TOP_FOLDER
rm -f ghrd_a5ed065bb32ae6sr0.hps.rbf
quartus_pfg \
-c agilex5_soc_devkit_ghrd/output_files/ghrd_a5ed065bb32ae6sr0.sof ghrd_a5ed065bb32ae6sr0.rbf \
-o hps_path=gsrd-socfpga/agilex5_dk_a5e065bb32aes1-gsrd-images/u-boot-agilex5-socdk-gsrd-atf/u-boot-spl-dtb.hex \
-o hps=1
The following file is created:
$TOP_FOLDER/ghrd_a5ed065bb32ae6sr0.hps.rbf
Notices & Disclaimers¶
Altera® Corporation technologies may require enabled hardware, software or service activation. No product or component can be absolutely secure. Performance varies by use, configuration and other factors. Your costs and results may vary. You may not use or facilitate the use of this document in connection with any infringement or other legal analysis concerning Altera or Intel products described herein. You agree to grant Altera Corporation a non-exclusive, royalty-free license to any patent claim thereafter drafted which includes subject matter disclosed herein. No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document, with the sole exception that you may publish an unmodified copy. You may create software implementations based on this document and in compliance with the foregoing that are intended to execute on the Altera or Intel product(s) referenced in this document. No rights are granted to create modifications or derivatives of this document. The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. Altera disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade. You are responsible for safety of the overall system, including compliance with applicable safety-related requirements or standards. © Altera Corporation. Altera, the Altera logo, and other Altera marks are trademarks of Altera Corporation. Other names and brands may be claimed as the property of others.
OpenCL* and the OpenCL* logo are trademarks of Apple Inc. used by permission of the Khronos Group™.
Created: May 25, 2024