Desktop Linux Falcon 26.1
Quick Start Guide
Build Instructions
Release Notes
This Quick Start Guide describes the architecture, hardware, and software setup needed to run the Desktop Linux demo_.
To run the Yocto Linux Command-Line demo, follow the steps below:
- Overview
- Theory of Operation
- Golden Hardware Reference Design (GHRD)
- 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.
The Arrow AXE5-Falcon is an Agilex 5 SoC development kit combining a dual ARM Cortex-A55 HPS cluster with a substantial FPGA fabric. While the HPS provides a capable embedded Linux platform, the Agilex 5 SoC does not include an integrated GPU or display controller — making HDMI output unavailable without FPGA assistance. The Altera VVP Video Frame Reader IP core bridges this gap by implementing a display pipeline entirely within the FPGA fabric, reading a Linux framebuffer from HPS DDR memory via a high-bandwidth AXI DMA master and driving a full 1920×1080p60 HDMI output through a chain of VVP video IP components. With this driver in place the AXE5-Falcon boots directly to a graphical Linux console on a standard HDMI monitor, enabling full desktop Linux development and demonstration workflows on the platform without any external display adapter or GPU.
The Altera VVP Video Frame Reader (VFR) is an FPGA IP core that performs continuous AXI DMA reads from a framebuffer in HPS DDR memory and streams the pixel data to a downstream video pipeline terminating at an HDMI transmitter. To expose this hardware to Linux as a standard display device, a DRM/KMS platform driver was developed for the Agilex 5 SoC. DRM/KMS (Direct Rendering Manager / Kernel Mode Setting) is the modern Linux display framework used by all current display stacks including Wayland, X11, and the kernel framebuffer console. It provides atomic modesetting, standardised buffer management via GEM, and fbdev emulation — the last of which allows the Linux boot console to appear on the HDMI display without any user-space display manager.
The driver allocates an 8 MB physically contiguous framebuffer from the Linux CMA (Contiguous Memory Allocator) pool and programs its physical address into the VFR hardware. CMA is required because the VFR DMA master takes a single base address and reads sequentially through memory — it cannot follow a scatter-gather list. The framebuffer is allocated as non-cacheable via the dma-noncoherent device tree property, ensuring that CPU writes bypass the ARM L1/L2 cache and go directly to DDR where the VFR can read them immediately via the F2SDRAM bridge. This avoids cache thrashing since the 8 MB framebuffer is four times the size of the Agilex 5 L3 cache, and keeps the cache available for the real CPU workload.
The driver targets kernel 6.18 and above, adapting to API changes introduced across recent kernel releases including the rename of CMA GEM helpers from CMA to DMA, the removal of the .date field from drm_driver, the addition of fbdev_probe as a required driver callback, and the migration of fbdev client setup to drm_client_setup_with_fourcc().
At probe time the driver maps two MMIO register blocks — the VFR at 0x20008000 and the Clocked Video Output (CVO) at 0x20006000 — and performs a VID_PID sanity check to confirm the correct IP is present. Since both components operate in Lite mode, the AXI4-S stream between them carries no embedded metadata packets. The CVO therefore has no way to determine frame dimensions from the stream and must be explicitly programmed via its IMG_INFO registers at startup. The driver's altera_vfr_cvo_init() function writes the frame width, height, colorspace, and bits-per-symbol to the CVO before the VFR is started, and forces the CVO input multiplexer to select the VFR stream via the REG_FALLBACK register.
On the first DRM atomic commit, vfr_program_bufset() stops the VFR, writes the full buffer set 0 descriptor — base address, stride, width, height, pixel format metadata, and field count — then commits and restarts the VFR in FREE_RUNNING mode. The framebuffer format is XRGB8888 (4 bytes per pixel), chosen because 4-byte pixels divide evenly into any power-of-2 AXI bus width, avoiding the fractional pixel alignment problems that occur with 3-byte RGB888 over a 256-bit AXI bus. The VFR is configured with 4 colour planes and Pixel Packing, so it reads 4 bytes per pixel from DDR and outputs a 32-bit tdata AXI4-S stream; the X padding byte is discarded at the TFP410 which only uses the lower 24 data pins. Subsequent page flips call vfr_update_base_addr() which updates only the base address and issues a commit, allowing the VFR to latch the new address at the next frame boundary without stopping.
The driver uses a no-vblank design because the VFR in Lite mode does not expose a hardware interrupt. A custom CRTC reset callback sets no_vblank=true on the CRTC state, and a custom non-blocking commit tail delivers page flip events immediately in atomic_flush rather than waiting for a hardware vblank signal. The VFR and CVO are clocked at 200 MHz (vid_clock) while the CVO timing generator and downstream pipeline run at 148.5 MHz (fr_clock). Running vid_clock faster than fr_clock provides headroom for DDR latency; the CVO VID_IS_ASYNC=1 parameter enables its internal CDC FIFO to safely bridge the two clock domains. A block diagram of the hardware pipeline is shown below and is integrated into the GHRD as the Video Subsystem.
The Golden Hardware Reference Design is an important part of a bootable Linux system and consists of the following components:
- Hard Processor System (HPS)
- Dual core Arm Cortex-A55 processor
- HPS Peripherals:
- SDMMC
- EMAC
- USB UART
- I2C
- USB 2.0
- Multi-Ported FrontEnd(MPFE) for HPS External Memory Interface (EMIF)
- FPGA Peripherals connected to Lightweight HPS-to-FPGA (LWS2F) AXI Bridge and JTAG to Avalon Master Bridge
- Four user push-button inputs
- Six user DIP switch inputs
- Four user I/O for RGB LED outputs
- JTAG UART
- System ID
The GHRD is constructed with a hierarchy. There is a top level that instantiates multiple subsystems. These include the following subsystems:
- Board
- Clock
- HPS
- EMIF
- Peripheral
There are two optional subsystems that can be included. They are not included in the default configuration.
- MIPI
- Video
This section presents the address maps as seen from the MPU .
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. There are no FPGA peripherals connected to the HPS-to-FPGA bridge in the default configuration.
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 0x00_2000_0000, is listed in the following table.
| Periheral | Address Offset | Size (bytes) | Attribute |
|---|---|---|---|
| sys_id | 0x0800_0000 | 8 | Unique system ID |
| pb | 0x0800_0010 | 16 | DIP switch input |
| dipsw | 0x0800_0020 | 16 | Push button input |
| rgb_led0 | 0x0800_0030 | 16 | RGB LED0 output display |
| rgb_led1 | 0x0800_0040 | 16 | RGB LED1 output display |
| rgb_led2 | 0x0800_0050 | 16 | RGB LED2 output display |
| rgb_led3 | 0x0800_0060 | 16 | RGB LED3 output display |
| usb_hub_rst | 0x0800_0070 | 16 | USB Hub reset |
| eth1_rst | 0x0800_0080 | 16 | Ethernet Phy (FPGA) reset |
The following components are required for the demo:
- AXE5-Falcon (TEI0183) development board,
- USB C to C Cable (for the USB Blaster III, HPS UART, and power)
- 2GB SD card
- Insert the SD card in the SD card cage, on the under side of the board.
- Attach the USB C cable to the USB (J25) connector
- Download the FPGA jic image axe5_falcon_top.hps.jic
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_falcon_top.hps.jic@1"
Option 2: Two Devices
$ quartus_pgm -c 1 -m jtag -o "pvi;axe5_falcon_top.hps.jic@2"
Program the device
This will take a few minutes to complete.
The AXE5-Falcon exposes two COM ports. One is driven from the FPGA and the other from the HPS. Select the higher COM port number that is exposed (HPS).
- 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 'CONF' button to boot the demo. This will initiate the following boot process.
- The Secure Device Manager (SDM) will read the jic file. This contains a partial FPGA image and the U-boot First Stage Boot Loader (FSBL). The partial image provides the HPS access to DDR and HPS I/O pins.
- The SDM releases the Arm processor cluster in the Hard Processing System (HPS) from reset.
- The Arm processor cluster then boots U-boot which completes the FPGA configuration. It then proceeds to boot Linux from the SD card
- The Linux password is root
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
Download or Build the Yocto Rootfs
Create an Integrated SOF file
Create an Integrated JIC file
Build the SD Card Image
Downloading via JTAG
| Component | Location | Branch | Tag/Commit ID |
|---|---|---|---|
| GHRD | https://github.com/ArrowElectronics/ghrd-socfpga | master | QPDS26.1_REL_GSRD_PR/a813239ce177133aeaae62a1f7b66860266addcd |
| Linux | https://github.com/ArrowElectronics/linux-socfpga | socfpga-6.18.2-lts | QPDS26.1_REL_GSRD_PR/232e81af478e344b8e0cdfcc4265f986a38ee4cc |
| U-Boot | https://github.com/ArrowElectronics/u-boot-socfpga | socfpga_v2026.01 | QPDS26.1_REL_GSRD_PR/14eb3d155c2f57769e1e16a72f1551661a336c56 |
| Arm Trusted Firmware | https://github.com/ArrowElectronics/arm-trusted-firmware | socfpga_v2.14.0 | QPDS26.1_REL_GSRD_PR/4a4b4573e12fabd0a88e95952af49840db6b770d |
- 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 26.1
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/26.1/quartus/bin64:$PATH"
Clone the repository
$ cd $TOP_FOLDER
$ git clone -b QPDS26.1_REL_GSRD_PR https://github.com/ArrowElectronics/ghrd-socfpga ghrd-socfpga
$ cd ghrd-socfpga/axe5_falcon_ghrd
Add pin assignments
quartus_sh -t sources/axe5_falcon_top.tcl
Compile the Quartus project
quartus_sh --flow compile axe5_falcon_top
The following file is created:
- $TOP_FOLDER/ghrd-socfpga/axe5_falcon_ghrd/output_files/axe5_falcon_top.sof
$ cd $TOP_FOLDER
$ rm -rf arm-trusted-firmware
$ git clone -b QPDS26.1_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 QPDS26.1_REL_GSRD_PR https://github.com/ArrowElectronics/u-boot-socfpga u-boot-socfpga
$ cd u-boot-socfpga
enable dwarf4 debug info, for compatibility with arm ds
$ sed -i 's/PLATFORM_CPPFLAGS += -D__ARM__/PLATFORM_CPPFLAGS += -D__ARM__ -gdwarf-4/g' arch/arm/config.mk
only boot from SD, do not try QSPI and NAND
$ sed -i 's/u-boot,spl-boot-order.*/u-boot\,spl-boot-order = \&mmc;/g' arch/arm/dts/socfpga_agilex5_axe5_falcon-u-boot.dtsi
disable NAND in the device tree
$ sed -i '/&nand {/!b;n;c\\tstatus = "disabled";' arch/arm/dts/socfpga_agilex5_axe5_falcon-u-boot.dtsi
link to atf
$ ln -s ../arm-trusted-firmware/build/agilex5/release/bl31.bin
build U-Boot
$ make clean && make mrproper
$ make socfpga_agilex5_defconfig
use created custom configuration file to merge with the default configuration obtained in .config file.
$ ./scripts/kconfig/merge_config.sh -O . -m .config config-fragment-falcon
$ 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
Download and compile Linux
$ cd $TOP_FOLDER
$ rm -rf linux-socfpga
$ git clone -b QPDS26.1_REL_GSRD_PR https://github.com/ArrowElectronics/linux-socfpga linux-socfpga
$ cd linux-socfpga
add arrow dts folder as Makefile option
$ sed -i '$ a subdir-y += arrow' arch/arm64/boot/dts/Makefile
$ make defconfig
use created custom configuration file to merge with the default configuration obtained in .config file.
$ ./scripts/kconfig/merge_config.sh -O ./ ./.config ./config-fragment-falcon
make oldconfig
$ make -j 64 Image && make arrow/socfpga_agilex5_axe5_falcon.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_falcon.dtb
The rootfs has been built and can be downloaded from the links below. Download both files and place them in the following folder
- $TOP_FOLDER/yocto/build/tmp/deploy/images/agilex5/
core-image-minimal-agilex5.rootfs-20240513114121.tar.gz
core-image-minimal-agilex5.rootfs.tar.gz
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
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 >/altera_pro/26.1/quartus/bin:$PATH"
$ cd $TOP_FOLDER/ghrd-socfpga/axe5_falcon_ghrd/output_files/
$ quartus_pfg -c axe5_falcon_top.sof axe5_falcon_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_falcon_ghrd/output_files/
$ copy u-boot-spl-dtb.hex from the linux host to the output_files directory
$ quartus_pfg -c axe5_falcon_top.sof axe5_falcon_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 >/altera_pro/26.1/quartus/bin64:$PATH"
$ cd $TOP_FOLDER/ghrd-socfpga/axe5_falcon_ghrd/output_files/
$ quartus_pfg -c axe5_falcon_top.sof axe5_falcon_top.jic -o hps=on -o device=MT25QU256 -o flash_loader=A5EE013BB23BE6S -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_falcon_ghrd/output_files/
$ copy u-boot-spl.ihex from linux host to the output_files directory
$ quartus_pfg -c axe5_falcon_top.sof axe5_falcon_top.jic -o hps=on -o device=MT25QU256 -o flash_loader=A5EE013BB23BE6S -o hps_path=u-boot-spl-dtb.hex -o mode=ASX4
The following files are created:
- $TOP_FOLDER/ghrd-socfpga/axe5_falcon_ghrd/output_files/axe5_falcon_top.hps.jic
- $TOP_FOLDER/ghrd-socfpga/axe5_falcon_ghrd/output_files/axe5_falcon_top.core.rbf (rename it to ghrd.core.rbf)
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_falcon_top_hps.sof@n"
Flash the QSPI. Use the Intel Download cable when programming the AXE5-falcon board from a Linux environment.
$ quartus_pgm -c 1 -m jtag -o "pvi;axe5_falcon_top.hps.jic@n"
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/ghrd-socfpga/axe5_falcon_ghrd/output_files/ghrd.core.rbf .
$ cp $TOP_FOLDER/u-boot-socfpga/u-boot.itb .
$ cp $TOP_FOLDER/linux-socfpga/arch/arm64/boot/Image .
$ cp $TOP_FOLDER/linux-socfpga/arch/arm64/boot/dts/arrow/socfpga_agilex5_axe5_falcon.dtb .
$ 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
- Initial release