Command Line Linux 24.3 - ArrowElectronics/Agilex-5 GitHub Wiki

Under Construction

Table of Contents

Quick Start Guide
Build Instructions

Quick Start Guide

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:

  1. Install the Quartus Prime Pro Programmer
  2. Prepare and install the SD Card.
  3. Configure the Board for the Demo
  4. Flash the FPGA configuration file.
  5. Connect to the HPS target terminal.
  6. Boot log
  7. Access FPGA PIO from Linux

Configure the Board for the Demo

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.

Configure the MSEL DIP Switches

The MSEL2 and MSEL1 DIP switches need to be set to the ON position (left) for Boot from QSPI configuration.


Assemble the Hardware

  • 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

Flash the FPGA configuration file

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.

Connect to the target terminal

  • 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

Run the demo

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

Access FPGA PIO from Linux

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

Build Instructions

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

Release Contents

Latest Source Code Release Contents - Branches and Commit IDs

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

Prerequisites

  • 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

Set up the Environment

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-

Build the Golden Hardware Reference Design

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

Build Arm Trusted Firmware

    $ 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)

Build u-boot

    $ 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

Create the Boot Script

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

Build the Linux kernel

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

Build kernel.itb

    $ 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

Build the Yocto Rootfs

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

Build the SD Card Image

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

Create an Integrated SOF file

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.

Linux Environment

    $ 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

Windows Environment

    $ 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

Create an Integrated JIC file

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.

Linux Environment

    $ 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

Windows Environment

    $ 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

Downloading via JTAG

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"

Return - Table of Contents
Return - AXE5-Eagle Platform

⚠️ **GitHub.com Fallback** ⚠️