Command Line Linux 24.3 - ArrowElectronics/Agilex-5 GitHub Wiki
Quick Start Guide
Build Instructions
This Quick Start Guide describes the hardware and software setup needed to run the Yocto Linux Command-Line demo.
In this demo configuration, the Agilex® 5 E boots a Yocto Linux Distribution which uses a terminal emulator to communicate with the user.
To run the Yocto Linux Command-Line demo, follow the steps below:
- Install the Quartus Prime Pro Programmer
- Prepare and install the SD Card.
- Configure the Board for the Demo
- Flash the FPGA configuration file.
- Connect to the HPS target terminal.
- Boot log
- Access FPGA PIO from Linux
The following components are required for the demo:
- AXE5-Eagle (TEI0185) development board,
- 12VDC 40W power supply
- Arrow-USB-Blaster (TEI-0004-02) for downloading to the FPGA
- 2 x micro-USB Cable (one for the Arrow Blaster, one for the HPS UART)
- 8GB SD card
Depending on the kit revision, additional components may need to be obtained. Please click on this link to review.
The MSEL2 and MSEL1 DIP switches need to be set to the ON position (left) for Boot from QSPI configuration.
- Insert the SD card in the J24 cage, on the right hand of the board.
- Attach the micro-USB cable to UART (J5) connector
- Plug the Arrow-USB-Blaster (TEI0004-02) into J34 with the USB connector facing to the right.
- Connect the power supply to the AXE5-Eagle J29 barrel connector
- Plug the AC-DC adapter into an AC outlet
- Download the FPGA jic image axe5_eagle_top_hps.jic
Use the Intel Download cable when programming the AXE5-Eagle board from a Linux environment.
The FPGA JTAG chain will expose 1 or 2 devices when auto-detected from the programmer. Follow the appropriate instructions to program the Agilex 5 FPGA for either scenario.
Open a shell (Nios V Command Shell for Windows)
Determine the number of JTAG devices
$ jtagconfig
One JTAG device 1) Arrow-USB-Blaster [ARA31601-TEI0004] 0364F0DD A5E(C065BB32AR0|D065BB32AR0) Two JTAG devices 1) Arrow-USB-Blaster [ARA31601-TEI0004] 4BA06477 ARM_CORESIGHT_SOC_600 0364F0DD A5E(C065BB32AR0|D065BB32AR0)
Option 1: One Device
$ quartus_pgm -c 1 -m jtag -o "pvi;axe5_eagle_top_hps.jic@1"
Option 2: Two Devices
$ quartus_pgm -c 1 -m jtag -o "pvi;axe5_eagle_top_hps.jic@2"
Program the device
This will take a few minutes to complete.
- A wired Micro USB serial port connection between the host PC and the embedded target is required
- Launch a terminal program (like Tera Term VT or Putty) and connect using serial port
- Select 115200 baud
- Select the appropriate target COM port
Press the 'NCONFIG' button to boot the demo. This will initiate the following boot process.
- The Secure Device Manager (SDM) will read the jic file. This contains the FPGA image and the U-boot First Stage Boot Loader (FSBL)
- When the FPGA is configured, the SDM will release the Arm processor cluster in the Hard Processing System (HPS) from reset.
- The Arm processor cluster then boots U-boot and Linux from the SD card
- The Linux password is root
RGB_LED2 is connected to a PIO peripheral in the FPGA. This is mapped via the HPS2FPGA Lightweight Bridge (LW HPS2FPGA) to the HPS.
The address of the PIO, accessible from the HPS, is 0x2000 0000 LW HPS2FPGA Bridge address + 0x0800 0050 PIO offset address in the FPGA ----------- 0x2800 0050
Physical addresses in hardware can be directly read or written from Linux user space using devmem.
Illuminate RGB_LED2 - red
$ devmem2 0x28000050 w 0x03
Illuminate RGB_LED2 - green
$ devmem2 0x28000050 w 0x05
Illuminate RGB_LED2 - blue
$ devmem2 0x28000050 w 0x06
Turn off RGB_LED2
$ devmem2 0x28000050 w 0x07
RGB_LED2 has been added as a LED device in Linux. This was done with the following lines of code in the Device Tree
View the LEDs as devices
$ ls /sys/class/leds
Illuminate RGB_LED2 - red
$ echo 1 > /sys/class/leds/fpga_led2_red/brightness
Turn off RGB_LED2
$ echo 0 > /sys/class/leds/fpga_led2_red/brightness
This build flow is derived from the instructions on the Building Bootloader for Agilex 5 page on RocketBoards
Release Contents
Prerequisites
Set up the Environment
Build the Golden Hardware Reference Design
Build Arm Trusted Firmware
Build u-boot
Build the Linux kernel
Build the Yocto Rootfs
Build the SD Card Image
Create an Integrated SOF file
Create an Integrated JIC file
Downloading via JTAG
Component | Location | Branch | Tag/Commit ID |
---|---|---|---|
GHRD | https://github.com/ArrowElectronics/ghrd-socfpga | master | QPDS24.3_REL_GSRD_PR/151a26be0aea93bb23064fea064b0b2f8843d201 |
Linux | https://github.com/ArrowElectronics/linux-socfpga | socfpga-6.6.37-lts | QPDS24.3_REL_GSRD_PR/e98c5f87520c8ceb08d7a98a69957db06c7ff79d |
U-Boot | https://github.com/ArrowElectronics/u-boot-socfpga | socfpga_v2024.04 | QPDS24.3_REL_GSRD_PR/dc428c375177c186c47b8eee7f90629921f0e577 |
Arm Trusted Firmware | https://github.com/ArrowElectronics/arm-trusted-firmware | socfpga_v2.11.0 | QPDS24.3_REL_GSRD_PR/9aee18305b73651b74301483510c29fef9ce23ce |
- Host machine running Linux (for Quartus, ATF, U-Boot, Linux & Yocto). Ubuntu 22.04 was used, but other versions may work too. For Quartus only, optionally, a Host Machine running Windows.
- Internet connection to download the tools and clone the repositories from github. If you are behind a firewall you will need your system administrator to enable you to get to the git trees.
- Quartus Prime Pro version 24.3
Open a shell
$ sudo rm -rf agilex_5
$ mkdir agilex_5
$ cd agilex_5
$ export TOP_FOLDER=`pwd`
Download and setup the the toolchain as follows:
$ 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-
This can be built under Windows or Linux.
Open a shell (niosv command shell for Windows)
For Linux, specify the path to the Quartus installation
$ export PATH="<path to >/intelFPGA_pro/24.3/quartus/bin64:$PATH"
Clone the repository
$ cd $TOP_FOLDER
$ git clone -b QPDS24.3_REL_GSRD_PR https://github.com/ArrowElectronics/ghrd-socfpga ghrd-socfpga
$ cd ghrd-socfpga/axe5_eagle_ghrd
Open Quartus and load the Project
$ File --> Open Project. Select axe5_eagle_top.
Compile the Quartus project
$ Processing --> Start Compilation
The following file is created:
- $TOP_FOLDER/ghrd-socfpga/axe5_eagle_ghrd/output_files/axe5_eagle_top.sof
$ cd $TOP_FOLDER
$ rm -rf arm-trusted-firmware
$ git clone -b QPDS24.3_REL_GSRD_PR https://github.com/ArrowElectronics/arm-trusted-firmware arm-trusted-firmware
$ cd arm-trusted-firmware
$ make -j 48 PLAT=agilex5 bl31
The following file is created:
- $TOP_FOLDER/arm-trusted-firmware/build/agilex5/release/bl31.bin (used for u-boot.itb generation)
$ cd $TOP_FOLDER
$ rm -rf u-boot-socfpga
$ git clone -b QPDS24.3_REL_GSRD_PR https://github.com/ArrowElectronics/u-boot-socfpga u-boot-socfpga
$ cd u-boot-socfpga
$ make clean && make mrproper
$ make socfpga_agilex5_axe5_eagle_defconfig
$ # use custom configuration file to merge with the default configuration obtained in .config file.
$ ./scripts/kconfig/merge_config.sh -O . -m .config config-fragment
$ ln -s ../arm-trusted-firmware/build/agilex5/release/bl31.bin
$ make -j 64
The following files are created:
- $TOP_FOLDER/u-boot-socfpga/u-boot.itb
- $TOP_FOLDER/u-boot-socfpga/spl/u-boot-spl-dtb.hex
U-boot will look for the boot.scr.uimg file in the devices specified by the ${boot_targets} environment variable. This script is used to launch Linux and to perform the FPGA configuration.
$ cd $TOP_FOLDER
$ rm -rf uboot-script && mkdir uboot-script && cd uboot-script
$ wget https://raw.githubusercontent.com/ArrowElectronics/refdes-agilex5/QPDS24.2_REL_AGILEX5_GSRD_PR/scripts/uboot.txt
$ wget https://raw.githubusercontent.com/ArrowElectronics/refdes-agilex5/QPDS24.2_REL_AGILEX5_GSRD_PR/scripts/uboot_script.its
$ mkimage -f uboot_script.its boot.scr.uimg
The following file is created:
- $TOP_FOLDER/uboot-script/boot.scr.uimg
Download and compile Linux
$ cd $TOP_FOLDER
$ rm -rf linux-socfpga
$ git clone -b QPDS24.3_REL_GSRD_PR https://github.com/ArrowElectronics/linux-socfpga linux-socfpga
$ cd linux-socfpga
$ make socfpga_agilex5_axe5_eagle_defconfig
$ make -j 64 Image && make arrow/socfpga_agilex5_axe5_eagle.dtb
The following files are created:
- $TOP_FOLDER/linux-socfpga/arch/arm64/boot/Image
- $TOP_FOLDER/linux-socfpga/arch/arm64/boot/dts/arrow/socfpga_agilex5_axe5_eagle.dtb
$ cd $TOP_FOLDER
$ rm -rf kernel_itb && mkdir kernel_itb && cd kernel_itb
$ wget https://raw.githubusercontent.com/ArrowElectronics/refdes-agilex5/QPDS24.2_REL_AGILEX5_GSRD_PR/scripts/fit_kernel_agilex5.its
$ cp $TOP_FOLDER/linux-socfpga/arch/arm64/boot/dts/arrow/socfpga_agilex5_axe5_eagle.dtb socfpga_agilex5_axe5_eagle.dtb
$ cp $TOP_FOLDER/linux-socfpga/arch/arm64/boot/Image Image
$ mkimage -f fit_kernel_agilex5.its kernel.itb
The following file is created:
- $TOP_FOLDER/inux-socfpga/kernel.itb
Use these instructions on Rocketboards to build the Rootfs. This is useful if you'd like to customize packages included in the rootfs.
The following file is created:
- $TOP_FOLDER/yocto/build/tmp/deploy/images/agilex5/core-image-minimal-agilex5.rootfs.tar.gz
Determine the device associated with the SD card on the host. Run the command below before and after inserting the SD card. The new drive letter will show up as /dev/sdx/ where x represents the actual letter (a,b,c,d etc). Substitute the letter x with the actual letter in the dd commands listed below.
$ cat /proc/partitions
$ cd $TOP_FOLDER
$ sudo rm -rf sd_card && mkdir sd_card && cd sd_card
$ wget https://releases.rocketboards.org/release/2020.11/gsrd/tools/make_sdimage_p3.py
$ # remove mkfs.fat parameter which has some issues on Ubuntu 22.04
$ sed -i 's/\"\-F 32\",//g' make_sdimage_p3.py
$ chmod +x make_sdimage_p3.py
$ mkdir fatfs && cd fatfs
$ cp $TOP_FOLDER/u-boot-socfpga/u-boot.itb .
$ cp $TOP_FOLDER/kernel_itb/kernel.itb .
$ cp $TOP_FOLDER/uboot-script/boot.scr.uimg .
$ cd ..
$ mkdir rootfs && cd rootfs
$ sudo tar xf $TOP_FOLDER/yocto/build/tmp/deploy/images/agilex5/core-image-minimal-agilex5.rootfs.tar.gz
$ cd ..
$ sudo python3 make_sdimage_p3.py -f \
-P fatfs/*,num=1,format=fat32,size=512M \
-P rootfs/*,num=2,format=ext3,size=512M \
-s 1024M \
-n sdcard.img
$ sudo chmod 777 sdcard.img
$ cd ..
Use dd utility to write the SD image to the SD card. Substitute the letter x with the actual drive letter discovered above.
$ sudo dd if=$TOP_FOLDER/sd_card/sdcard.img of=/dev/sdx bs=1M status=progress
Flush the changes to the SD card.
$ sudo sync
This section presents how to add the FSBL to the SOF file which is the output of the hardware project compilation. This creates a new SOF file which can be used to configure the device through the Quartus Programmer. This is useful during development, as it takes much less time than writing a configuration image to QSPI.
$ export PATH="<path to >/intelFPGA_pro/24.3/quartus/bin:$PATH"
$ cd $TOP_FOLDER/ghrd-socfpga/axe5_eagle_ghrd/output_files/
$ quartus_pfg -c axe5_eagle_top.sof axe5_eagle_top_hps.sof -o hps_path=$TOP_FOLDER/u-boot-socfpga/spl/u-boot-spl-dtb.hex
$ open a Nios V Command Shell
$ cd <path to>/ghrd-socfpga/axe5_eagle_ghrd/output_files/
$ copy u-boot-spl.ihex from the linux host to the output_files directory
$ quartus_pfg -c axe5_eagle_top.sof axe5_eagle_top_hps.sof -o hps_path=u-boot-spl-dtb.hex
This section shows how to take the integrated sof file and create a jic file that can be programmed into the SDM QSPI flash. Note that downloading a sof file will not support the functionality of the linux reboot command or the HPS COLD RESET due to SDM requirements. It is useful to flash the QSPI when these functions are necessary.
$ export PATH="<path to >/intelFPGA_pro/24.3/quartus/bin64:$PATH"
$ cd $TOP_FOLDER/ghrd-socfpga/axe5_eagle_ghrd/output_files/
$ quartus_pfg -c axe5_eagle_top.sof axe5_eagle_top_hps.jic -o device=MT25QU02G -o flash_loader=A5ED065BB32AE5SR0 -o hps_path=$TOP_FOLDER/u-boot-socfpga/spl/u-boot-spl-dtb.hex -o mode=ASX4
$ open a Nios V Command Shell
$ cd <path to>/ghrd-socfpga/axe5_eagle_ghrd/output_files/
$ copy u-boot-spl.ihex from linux host to the output_files directory
$ quartus_pfg -c axe5_eagle_top.sof axe5_eagle_top_hps.jic -o device=MT25QU02G -o flash_loader=A5ED065BB32AE5SR0 -o hps_path=u-boot-spl-dtb.hex -o mode=ASX4
The Agilex 5 device has two JTAG device IDs for the ARM SoC and FPGA respectively. The Secure Device Manager will determine whether to expose one or both.
Determine the number of JTAG devices.
$ jtagconfig
Two devices: 1) Arrow-USB-Blaster [ARA31601-TEI0004] 4BA06477 ARM_CORESIGHT_SOC_600 0364F0DD A5E(C065BB32AR0|D065BB32AR0) One device: 1) Arrow-USB-Blaster [ARA31601-TEI0004] 0364F0DD A5E(C065BB32AR0|D065BB32AR0) Substitute @n below with @1 for one device and @2 for two devices.
Download the sof.
$ quartus_pgm -c 1 -m jtag -o "p;axe5_eagle_top_hps.sof@n"
Flash the QSPI. Use the Intel Download cable when programming the AXE5-Eagle board from a Linux environment.
$ quartus_pgm -c 1 -m jtag -o "pvi;axe5_eagle_top_hps.jic@n"