Learning HPS + Nios® V Design on DE25-Nano (Agilex™ 5) 2 ~ Synchronization Using Mailbox ~

1. Introduction

In "Learning HPS + Nios® V Design on DE25-Nano (Agilex™ 5) 1 ~ Booting Nios® V from HPS ~" (hereafter referred to as "Booting Nios^® V from HPS"), we built a minimal design on the Agilex 5 SoC that simultaneously incorporates the Hard Processor System (HPS) and Nios V, enabling the HPS to boot the Nios V application.
This configuration clearly separates higher-level control using Linux from real-time control tightly coupled with FPGA logic.

However, in actual systems, simply booting Nios V is not sufficient. There are many cases where state notifications and processing completion notifications must be exchanged between HPS and Nios V to synchronize and control each other.

In this article, we explain the procedure for adding a Mailbox interface between HPS and Nios V, enabling basic synchronization and communication between the software components.
By using the Mailbox, HPS and Nios V can maintain their role separation while realizing more practical cooperative operation.

Reference: Learning HPS + Nios® V Design on DE25-Nano (Agilex™ 5) 1 ~ Booting Nios® V from HPS ~

2. Environment

Host PC: Linux (Ubuntu 22.04)
Target: Terasic DE25-Nano Board (Equipped with Agilex™ 5 SoC FPGA)
Quartus Prime: Version 25.3.1 Pro
Base Design (Design created in Booting Nios® V from HPS):
- HW Design: de25nano_golden_top_QP25.3_base.qar
- SD Image: sdimage_de25nano_gsrd_QPDS25.3.1_20260208_01_base.zip

Note:
The procedures in this article assume that you have completed Booting Nios® V from HPS.

3. Operation Image

In the sample created in this article, you will observe how HPS and Nios V work cooperatively via the Mailbox.

When the Nios V application is launched from Linux on the HPS, LED control by Nios V begins.
Next, a Linux application that changes the LED blinking period is launched, and the user inputs a new period. The entered value is sent via the Mailbox, and upon receiving this notification, Nios V changes the LED blinking period.
After the LED period change is completed, Nios V sends a completion notification via the Mailbox to notify the HPS side. Upon receiving this, the Linux application ends, confirming that HPS and Nios V are synchronized and cooperating.

[Figure 1] LED Blinking Period Change Process Flow

4. Environment Setup Procedure

4-1. HW Design Creation

Open the base design using Platform Designer and add the necessary IPs.

4-1-1. Adding Required IP

In this work, we will only add the following Mailbox IPs.

Avalon Mailbox IP 1
Purpose: Used to notify control commands from HPS to Nios V.
Main configuration parameters:
- Parameters
  - Enable Message Arrival Interrupt Output: ON
  - Enable Mailbox Space Available Interrupt Output: OFF

Avalon Mailbox IP 2
Purpose: Used to return processing results or completion notifications from Nios V to HPS.
Main configuration parameters: Same as "Avalon Mailbox IP 1".

4-1-2. Completed Design

The overall view of Platform Designer is as follows.
* The red frame indicates the added IP.
* The light blue arrows indicate command and interrupt signal flow from HPS to Nios V.
* The orange arrows indicate command and interrupt signal flow from Nios V to HPS.

Platform Designer.png — [Figure 3] Overall View of Platform Designer

4-1-3. Generating sof File

After creating the design in Platform Designer, execute Generate and perform a full compile in Quartus to generate the sof file.
After generating the sof file, execute the following command to include "u-boot-spl-dtb.hex" from the base environment into the sof file.
* In this article, the Quartus Project Directory name is "DE25-Nano_GHRD_QP25.3.1".

cd DE25-Nano_GHRD_QP25.3.1/output_files
quartus_pfg -c golden_top.sof golden_top_hps.sof -o hps_path=u-boot-spl-dtb.hex

The HW design is now complete.

4-2. SW Design Creation

4-2-1. Nios V

4-2-1-1. BSP Creation

Refer to "4-2-1-1. BSP Creation" in "Booting Nios® V from HPS" for the procedure to create the BSP.

4-2-1-2. Nios V Application Creation

Add Mailbox control as follows to the Nios V application created in "Booting Nios® V from HPS".

Specifically, the Mailbox control receives asynchronously sent LED blinking period change commands from HPS via interrupt. If the specified period is within the valid range (100–10000 msec), it changes the setting. After the change, it sends a period change completion command via Mailbox. If the period is out of range, it sends an error command via Mailbox.

Refer to "4-2-1-2. Nios V Application Creation" in "Booting Nios® V from HPS" for the procedure to create the Nios V application executable.
* Please save the attached led_output.c from this article to your host PC environment in advance.

4-2-2. HPS

4-2-2-1. Linux (Kernel, Device Tree, RootFS) Modifications

To control the Mailbox from Linux applications (register access and interrupt reception), configure the Mailbox IP as a UIO (Userspace I/O) device.

Here, we modify the device tree and driver settings accordingly.

Device Tree Modification
Modify "socfpga_agilex5_de25nano.dtb" stored in the FAT partition of the base SD Image.

dtb - dts Conversion
Run the following command to convert the binary .dtb to text .dts format.

dtc -I dtb -O dts -o socfpga_agilex5_de25nano.dts socfpga_agilex5_de25nano.dtb

Adding UIO Device
Edit the text file "socfpga_agilex5_de25nano.dts" and add a UIO device (mailbox_uio0) under soc@0 as follows.

    soc@0 {
        compatible = "simple-bus";
        ranges = <0x00 0x00 0x00 0xffffffff>;
        #address-cells = <0x01>;
        #size-cells = <0x01>;
        device_type = "soc";
        interrupt-parent = <0x03>;
　　　　　　　　　　：
　　　　　　　　　　：
        mailbox_uio0: mailbox@20041000 {
            compatible = "generic-uio";
            reg = <0x20041000 0x1000>;
            interrupts = <0x00 0x13 0x04>;
        };
    };

* The reg sets the access range for the two Avalon Mailbox IPs (RX/TX).
* The receive interrupt is connected to IRQ 2 of "fpga2hps_interrupt_irq0", so interrupts is set to Shared Peripheral Interrupt 19 (0x13).

Reference: Shared Peripheral Interrupt Assignment
4.2.5.1. GIC Shared Peripheral Interrupts Map for the SoC HPS • Hard Processor System Technical Reference Manual Agilex™ 5 SoCs • Altera Documentation and Resources Center

Reference: Modified file (socfpga_agilex5_de25nano.dts)

dts - dtb Conversion
Run the following command to convert the .dts back to .dtb.

dtc -I dts -O dtb -o socfpga_agilex5_de25nano.dtb socfpga_agilex5_de25nano.dts

The converted "socfpga_agilex5_de25nano.dtb" is the file to be stored in the FAT partition of the SD Image.

Enabling UIO (uio_pdrv_genirq)
Simply defining compatible = "generic-uio" in the device tree does not automatically enable the UIO (uio_pdrv_genirq) driver. This is because "uio_pdrv_genirq" requires specifying the target compatible via a startup parameter (of_id).
Therefore, to use UIO, you must explicitly specify generic-uio to the UIO driver.

Linux Boot
Boot Linux on the target board (DE25-Nano).
Create modprobe Configuration File
Create a modprobe configuration file (uio_pdrv_genirq.conf) as follows to ensure "uio_pdrv_genirq" binds correctly and persists.

root@agilex5:~# vi /etc/modprobe.d/uio_pdrv_genirq.conf

* In vi editor, add the following to uio_pdrv_genirq.conf
options uio_pdrv_genirq of_id=generic-uio

Note:
The UIO enabling procedure will be performed later in "5-2. Operation Verification".

4-2-2-2. Linux Application Creation

This application initializes the Mailbox, then waits for user input of the LED blinking period.
When the user inputs the LED blinking period, it sends a command to the Nios V application via the Mailbox and waits for an interrupt.
Upon receiving an interrupt from the Mailbox (i.e., a command sent from the Nios V application), it retrieves the command from the Mailbox and waits again for LED blinking period input.

The procedure to create the Linux application executable is as follows.
* Please save the attached chg_period.c and Makefile from this article to your host PC environment in advance.

Create the directory "hps/src/chg_period" under software

cd DE25-Nano_GHRD_QP25.3.1
mkdir -p software/hps/src/chg_period

Place the above program (chg_period.c) and Makefile under hps/src/chg_period

cd software/hps/src/chg_period
cp <program storage directory>/chg_period.c .
cp <Makefile storage directory>/Makefile .

Build

make

By following the above steps, the executable (chg_period) will be created in the build directory.

5. Operation Verification

5-1. Preparation

Place the Nios V application, HPS device tree, and Linux application created in "4. Environment Setup Procedure" onto the SD card.

Placing the Nios V Application
The Nios V application (led_output.bin) can be copied as a normal file to the FAT partition on the SD card using a PC file explorer or similar.
Placing the Device Tree
Similar to the Nios V application, copy it as a normal file to the FAT partition on the SD card using a PC file explorer or similar.
Placing the Linux Application
After booting the target board (DE25-Nano) and starting Linux, copy the Linux application (chg_period) to the file system over the network.
* WinSCP was used for copying during this verification.

Note that the copied file initially lacks execution permissions, so run the following command to grant execute permissions.

root@agilex5:~# chmod 755 chg_period

5-2. Operation Check

5-2-1. How to Change LED Blinking Period

Run the Linux application exe_niosv to start the Nios V application. Then run the Linux application chg_period, which displays the prompt for LED blinking period input ($ Input LED Blink period).
Inputting a value between 100 and 10000 changes the LED blinking period.

In this verification, the LED blinking period was changed to 100 msec and 1000 msec as shown below.

Before running the applications, boot the target board (DE25-Nano) and configure it with "golden_top_hps.sof" generated in "4-1-3. Generating sof File" using Quartus Programmer. Also, start juart-terminal to check the Nios V application log.

root@agilex5:~# ./exe_niosv
root@agilex5:~# ./chg_period
$ Input LED Blink period (100 - 10000 [msec])
-> 100

$ Input LED Blink period (100 - 10000 [msec])
-> 1000

5-2-2. Application Execution Results

When the application runs successfully, the following results occur.

juart-terminal Log
The juart-terminal displays logs such as "Change speed" as shown below.

Linux Application Log
When the LED blinking period is changed from the Linux application, the Linux terminal outputs logs like "Send command", "Waiting for Mailbox IRQ", and "Get command".

LED Blinking Video
The Nios V application blinks the FPGA LEDs in four patterns.
The video on the left shows the operation when 100 msec is specified from the Linux application, and the video on the right shows the operation when 1000 msec is specified.
* LED#7 (the leftmost LED) is controlled separately from the Nios V application.

6. Conclusion

This article introduced how to coordinate between HPS and Nios V using Mailbox on the DE25-Nano board.

By introducing a communication mechanism via Mailbox, command transmission/reception and interrupt notification synchronization control between HPS and Nios V become possible.
This enables flexible coordinated control, such as real-time changes to Nios V operation based on instructions from the HPS side. Especially, event-driven communication using interrupts allows efficient data coordination without relying on polling, improving overall system responsiveness and processing efficiency.

We hope this method will be useful in your future development as one approach to system design leveraging FPGA flexibility.

Sample Design

The design created by following the procedures in this article can be downloaded from the following links.

HW Design: de25nano_golden_top_QP25.3_MB.qar
Configuration File: golden_top_hps.sof
SD Image: sdimage_de25nano_gsrd_QPDS25.3.1_20260208_01_MB.zip

Related to

led_output.c
3 KB Download
Makefile
2 KB Download
chg_period.c
3 KB Download
socfpga_agilex5_de25nano.dts
30 KB Download