Questions regarding the HPS GSRD User Guide for the Agilex™ 5

[pjw]

Questions regarding the HPS GSRD User Guide for the Agilex™ 5 E-Series Premium Dev Kit
(https://altera-fpga.github.io/rel-25.1.1/embedded-designs/agilex-5/e-series/premium/gsrd/ug-gsrd-agx5e-premium/)

1. In the document, there is no mention of separately generating or modifying the device tree. Does this mean that even if I change HPS options or modify the system in Platform Designer, I don’t need to worry about the device tree? According to the guide, to use the GHRD I only need to update the RBF file location in the Yocto script. If the system design (Platform Designer) is modified, do I still not need to change anything else in the Yocto script?

2. In the Build Hardware Design section, the flow generates legacy_baseline_hps_debug.sof. Is this file strictly necessary? What is its purpose?

3. In the Build Hardware Design section, the command make legacy_baseline-sw-build is executed. This builds hps_wipe.s and generates an hps_wipe.ihex file. Is there ever a need to modify hps_wipe.s depending on HPS options? Can users simply use the hps_wipe.s file provided by Altera instead of creating their own?

[RolandoS_Altera]

Hello PJW, I will try to respond your questions.

1. The GSRD (Golden System Reference Design) includes the hardware component (referred as hardware design or GHRD - Golden Hardware reference design) and the HPS SW components.  If you want to use the HPS in your project, then you need to instantiate this one in Platform design and if this is the case you need to indicate what controllers in the HPS you need to use (for example the UART, the SD Controller, the ethernet controller, etc). Besides of the HPS, you also may want to create any design in the FPGA fabric (like a timer or GPIO controller, an On-Chip RAM, NIOS V, etc). If you want that HPS makes use of  the controllers in the HPS that you enabled in the hardware design or if you want that the HPS interacts with the hardware in the FPGA fabric, then you need to enable in the HPS software (could be U-Boot or Linux) the corresponding driver that allows the HPS to interact with that controller or piece of hardware in the fabric. To enable these drivers, you need to build the driver (this is done through CONFIGS) and also need to enable and configure the driver(through decive tree). In the same way if the HPS controller needs to interact with an external device like a SD card memory, serial RTC, ethernet phy device, you also need to enable the corresponding driver (also through device tree and CONFIGS). The GSRD that we provide already includes the CONFIGS and device tree settings that allow the HPS to interact with the reference design. If you enable something more in the hardware design, you will likely need to enable the corresponding driver in the HPS software. The GSRD in this page, relies on Yocto, which is a framework that allow to build the HPS software. This framework relies on some device trees that are already public in the external repositories (for example for Linux at https://github.com/altera-fpga/linux-socfpga/tree/socfpga-6.12.19-lts/arch/arm64/boot/dts/intel/socfpga_agilex5*) and also from additional layers included in other repositories (https://github.com/altera-fpga/meta-intel-fpga-refdes/tree/master/recipes-bsp/device-tree/files). The framework integrates all the recipes/components and build the binaries needed. So to respond to your first question, if you add more components in your hardware design and if you need the HPS to interact with them, then you do need to update the device tree.

In the user guide we show customers how they integrate a custom hardware design into the Yocto recipes that includes this is the binaries (but don't directly show how you can to update the HPS software if any new component is added to the hardware design,  the assumption is that the customer is familiar with the Yocto framework). Now, why do we need to include the hardware design in the HPS binaries created by Yocto? Well, there is an boot mode name HPS boot first, that is the one that the GSRD exercise, in which the hardware design is divided in 2 pieces, called phase1 and phase 2. The phase 1 includes the HPS and its peripherals, while the phase 2 includes the rest of the fabric and the idea is that the HPS first boots and then from U-Boot or Linux the HPS configures the phase 2 section (referred as core.rbf) . So in this mode, the phase 1 (hps.rbf) is the QSPI device while the phase2 is included in the SD-Card (in the case of the GSRD this is included as part of the kernel.itb file).  In order to get familiar with the boot flow, I sugest you to start with this page that shows you how to build most of the components (ATF, U-Boot, Linux individually): https://altera-fpga.github.io/rel-25.1/embedded-designs/agilex-5/e-series/premium/boot-examples/ug-linux-boot-agx5e-premium/

2. The legacy_baseline_hps_debug.sof is a binary that includes the hardware design (phase 1) and a dummy HPS software as FSBL (first stage boot loader). This dummy HPS doesn't do anything, but just enter into an infinity loop. This acts as our FSBL. We used this with the debugger. First load this image and the HPS enters into this loop, and then we connect the debugger to load the real HPS software. You can refer to https://altera-fpga.github.io/rel-25.1/demos/agilex-5/e-series/premium/riscfree-debug-u-boot/ug-riscfree-debug-uboot-agx5e-premium/ in which it shows how this is used.

3. The hps_wipe.s is the actual dummy HPS software that does some initial configuration and then enters into an infinite loop. I don't think that there is any need to modify this file. In our GSRD or the boot example that I showed above we use the u-boot-spl-dtb.hex instead as our FSBL, so this one is in charge of setup the DDR memory and some other hardware components in the HPS and then load second stage bootloader(SSBL which is u-boot.itb).

[pjw]

Thank you very much for the detailed explanation. Since this is my first time working with embedded Linux and Yocto, it is quite difficult for me. I will need to keep studying.

First of all, I don’t know what “CONFIGS” refers to.
Also, I understand that if there are design changes that the HPS needs to interact with, the device tree must be updated. What I am not clear about is how to update the device tree. Is the device tree rebuilt and updated through a Yocto recipe?

[RolandoS_Altera · Accepted solution]

Hello

In U-Boot and Linux there are some files that allow you to indicate if you need to build a driver or not. These are the configs. For example for agilex 5 we have these:

U-Boot: https://github.com/altera-fpga/u-boot-socfpga/blob/socfpga_v2025.04/configs/socfpga_agilex5_defconfig

Linux: https://github.com/altera-fpga/linux-socfpga/blob/socfpga-6.12.19-lts/arch/arm64/configs/defconfig

If a CONFIG is set to 'y' it means that the corresponding driver will be built and integrated into the Linux kernel. If it's set to 'm', the driver will be build but be created as an independent module that you need to load using the insmod command. If it's set to 'n', then the driver is not built and won't be available to the Linux kernel.

In the GSRD page, Yocto is the one that updates the device tree along to CONFIGS and other things. Yocto is very powerful but difficult to use. What I understand about the Yocto flow is that it gets the content of the Linux/ATF/U-Boot repo with a specific branch indicated in a recipe, and then executes recipes that update device trees and CONFIGS and also apply patches (to fix an issue or support any specific functionality). You need to create or modify these recipes to do what you want. Once that the repo is updated this is built and generates the Linux/ATF/U-Boot binaries. Then also Yocto has recipes to build Linux file system, libraries and applications that are copied into the file system. When it gets all components already built, Yocto also integrates these in you final binaries that could be a SD card image, a .rpd or .jic image to boot from QSPI, etc.  But to update the recipes is it needed to have certain level of knowledge about Yocto. The good thing is that this is popular and there are many resources in the web.

Again, if you are starting with our devices and you don't have much experience with Linux, I suggest you to start with https://altera-fpga.github.io/rel-25.1/embedded-designs/agilex-5/e-series/premium/boot-examples/ug-linux-boot-agx5e-premium/.

Also we have a very nice simulator for our Agilex 5 device that could help you to ramp up on this, in case you don't have a dev kit:

https://www.altera.com/products/development-tools/simics-virtual-platform

[pjw]

It was truly an excellent and kind answer. It was very helpful. I will try more things. Thank you.