Skip to content

HPS PCIe Root Port System Example Design for the Agilex™ 7 I-Series Transceiver-SoC Development Kit

Introduction

This page demonstrate PCIe root port design example running on Agilex™ 7 I-Series Transceiver-SoC Development Kit with an end point.

Release Content

Release note and pre-build binaries can be found in the GitHub repository

The pre-build binaries Agilex-7_I-series_artifacts.zip contain the files below.

  • ghrd.core.rbf
  • ghrd.hps.rbf
  • Image.lzma
  • kernal.itb
  • sdimage.tar.gz
  • socfpga_agilex7_socdk.dtb
  • u-boot.itb

System Example Design Overview

This design is based on the Agilex 7 SoC Development Golden Hardware Reference Design (GHRD) which is part of the Golden System Reference Design (GSRD). This design demonstrate the Root port capability, configures the PCIe Subsystem to work in Root port mode and use MCDMA Bridge logic that converts the incoming TLPs from PCIe Subsystem into Memory mapped interface.

The block diagram show 3 paths between HPS and PCIe subsystem(PCIe HIP + AVMM bridge).

  • F2H AXI4 (burst enabled)/ACELite interface for data transfers from PCIe EP.
  • H2F AXI4 (burst enabled) interface is used for PCIe EP downstream application configuration space as well as any higher data rate transfers initiated by HPS depending on the application. And also, for PCIe EP configuration address space access.
  • H2F Light weight AXI-4 interface is used for CSR to different block in the design.

Helpful Reference Documentation

Hardware Description

Memory Map

HPS H2F Memory Map

Address Offset Size (Bytes) Peripheral Remarks
0x8000_0000 256K On Chip Memory Block memory implemented in the FPGA fabric
0x9000_0000 256M BAS Avalon MM Slave of AVMM Bridge’s BAS port
0xA000_0000 2M PCIe SS AXI-Lite interface AXI-Lite of PCIe SS

HPS LWH2F Memory Map

Address Offset Size (Bytes) Peripheral Remarks
0xF900_0000 8 System ID Hardware configuration system ID
0xF900_0200 16 CCT Cache Coherent Translator
0xF901_0000 16k PCIe CS Avalon MM Slave of PCIe Configuration Slave port (14b address space)
0xF901_8000 128 MSI-to-GIC Vector
0xF901_8080 16 MSI-to-GIC CSR Avalon MM Slave of MSI-to-GIC CSR port
0xF901_80A0 32 Performance Counter Hardware timer for benchmarking purposes
0xF901_80C0 1K AVMM CS Cpl TimeOut & System level Reg. map  Error registers along with Timeout values 

PCIe BAM interface

Address Offset Size (Bytes) Peripheral Remarks
0xF901_8000 128 MSI-to-GIC Vector MSI/MSI-X Transactions from PCIe Endpoint. These should be aligned addresses to avoid any re-alignment on BAM AVMM interface.
0x0000_0000 to 0x7FFF_FFFF 2G HPS F2H  HPS FPGA to HPS interface (SDRAM access)
0x10_8000_0000 to 0x11_FFFF_FFFF 6G HPS F2H  HPS FPGA to HPS interface (SDRAM access) -Expanded memory range. Actual allocation is 8G (0x10_0000_0000 to 0x11_FFFF_FFFF) to match the 2 power of <Num of bits).

Memory Range Support Expansion

HPS support additional memory for F2H interface. For this example design, memory range support start from initial 2GB at the address offset of 0x8000_0000 and additional 6G memory at address offset of 0x08_8000_0000 to 0x09_FFFF_FFFF. BAM to HPS F2H have multiple path with different Address Expander range as shown in the block diagram.

Memory Range Address
Base 2GB 0x8000_0000 to 0xFFFF_FFFF
Additional 30GB 0x08_8000_0000 to 0x0F_FFFF_FFFF

Setup Configuration

This design tested with the following setup:

  • Tested End Point:
    • PCI Express NVMe Gen4 SSD (Samsung 980 PRO PCIe 4.0 NVMe)
    • PCI Express Network Interface Card (Intel I350/I210)
  • Tools and software:
    • System with supported Linux distribution with Ubuntu 22.04 (LTS)
    • Altera® Quartus ®Prime Design Suite software 25.1.1 version
    • Serial terminal application such as Putty

Board Setup

Configuring board

Configuration switches on the board are as below:

Switch Position
S19 [1:4] OFF/OFF/ON/ON
S20 [1:4] ON/ON/ON/ON
S9 [1:4] ON/ON/ON/X
S10 [1:4] ON/ON/ON/ON
S15 [1:4] ON/ON/ON/OFF
S1 [1:4] OFF/OFF/OFF/OFF
S6 [1:4] OFF/OFF/OFF/OFF
S22 [1:4] ON/ON/ON/ON
S23 [1:4] ON/ON/ON/ON
S4 [1:4] ON/ON/ON/ON

Building the PCIe Root Port Design

Here are the steps to build either HW and SW files:

Setting up the environment

git clone https://github.com/altera-fpga/agilex7-ed-pcie-rp.git
cd agilex7-ed-pcie-rp/src/
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/14.3.rel1/binrel/\
arm-gnu-toolchain-14.3.rel1-x86_64-aarch64-none-linux-gnu.tar.xz
tar xf arm-gnu-toolchain-14.3.rel1-x86_64-aarch64-none-linux-gnu.tar.xz
rm -f arm-gnu-toolchain-14.3.rel1-x86_64-aarch64-none-linux-gnu.tar.xz
export PATH=`pwd`/arm-gnu-toolchain-14.3.rel1-x86_64-aarch64-none-linux-gnu/bin/:$PATH
export ARCH=arm64
export CROSS_COMPILE=aarch64-none-linux-gnu-

Building the Hardware Files

Enable Quartus tools to be called from command line:

export QUARTUS_ROOTDIR=~/altera_pro/25.1.1/quartus/
export PATH=$QUARTUS_ROOTDIR/bin:$QUARTUS_ROOTDIR/linux64:$QUARTUS_ROOTDIR/../qsys/bin:$PATH

Building the Hardware files:

cd hw/ag7i027_devkit/syn/
make all

Building the Software Files

Building the Software files:

cd $TOP_FOLDER/sw
. agilex7_dk_si_agi027fc-gsrd-build.sh
build_setup

Perform Yocto bitbake to generate binaries:

bitbake_image

Package binaries into build folder:

package

Generate the Programming file

cd $TOP_FOLDER
cd hw/ag7i027_devkit/syn/
quartus_pfg -c -o hps=on -o hps_path=u-boot-spl-dtb.hex output_files/ghrd_agib027r31b1e1vaa.sof output_files/ghrd_agib027r31b1e1vaa.rbf

Adding PCIe root port in dts

Refer to socfpga_agilex_pcie_root_port.dtsi for adding PCIe Root Port bindings to your custom DTS.

Running the System Example Design

1. Download SD card image from the prebuilt binaries Agilex-7_I-series_artifacts.zip and extract the archive, obtaining the file gsrd-console-image-agilex7.wic.

2. Write the gsrd-console-image-agilex7.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:
# Determine the device asociated with the SD card on the host computer. 
cat /proc/partitions
# This will return for example /dev/sdx
# Use dd to write the image in the corresponding device
sudo dd if=gsrd-console-image-agilex7.wic of=/dev/sdx bs=1M
# Flush the changes to the SD card
sync
  • On Windows, use the Win32DiskImager program, available at https://sourceforge.net/projects/win32diskimager. For this, first rename the gsrd-console-image-agilex7.wic to an .img file (sdcard.img for example) and write the image as shown in the next figure:

Program the development kit with hps.rbf file.

quartus_pgm -c 1 -m jtag -o p;ghrd.hps.rbf@1

Open the Putty serial terminal, it will show the board boot-up process.

Execute the lspci command to display information about all PCI devices on the system

        root@agilex7dksiagi027fc:~# lspci

There you will see both PCIe devices Rootport(00:00.0) & End Point(01:00.0)

Run the following command to retrieve detailed information about the PCIe Root Port: 

        lspci -vvv

fio transactions

Recommended command to perform write transactions on an NVMe SSD:

        fio --filename=/dev/nvme0n1 --rw=write --gtod_reduce=1 --blocksize=64k --size=2G --iodepth=2 --group_reporting --name=myjob --ioengine=libaio --numjobs=num_of_job

Recommended command to perform read transactions on an NVMe SSD:

        fio --filename=/dev/nvme0n1 --rw=read --gtod_reduce=1 --blocksize=64k --size=2G --iodepth=2 --group_reporting --name=myjob --ioengine=libaio --numjobs=num_of_job

Note

    You could change the parameters ==--size=**xG**== with 2G or 8G, ==--rw=**x**== with write or read, ==--numjobs=**x**== with values 4, 8, 16 or 20, i.e.:

    * fio --filename=/dev/nvme0n1 --rw= ==**write**== --gtod_reduce=1 --blocksize=64k --size= ==**2G**== --iodepth=2 --group_reporting --name=myjob --ioengine=libaio --numjobs= ==**4**==

    * fio --filename=/dev/nvme0n1 --rw= ==**read**== --gtod_reduce=1 --blocksize=64k --size= ==**2G**== --iodepth=2 --group_reporting --name=myjob --ioengine=libaio --numjobs= ==**8**==

    * fio --filename=/dev/nvme0n1 --rw= ==**write**== --gtod_reduce=1 --blocksize=64k --size= ==**8G**== --iodepth=2 --group_reporting --name=myjob --ioengine=libaio --numjobs= ==**16**==

    * fio --filename=/dev/nvme0n1 --rw= ==**read**== --gtod_reduce=1 --blocksize=64k --size= ==**8G**== --iodepth=2 --group_reporting --name=myjob --ioengine=libaio --numjobs= ==**20**==

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.

Last update: January 27, 2026
Created: January 27, 2026
Ask in the Forum