Intel® Stratix® 10 SoC FPGA Boot User Guide

ID 683847
Date 1/17/2024
Document Table of Contents

6.3. FPGA Partial Reconfiguration from Linux

The Partial Reconfiguration started from Linux relies on the device tree overlay mechanism which allows you to modify the original device tree at run time.

The components needed to perform the Platform Reconfiguration from Linux are listed next. These items are already provided as part of the Partial Reconfiguration example provided in the following RocketBoards page: Intel® Stratix® 10 SoC GSRD: Partial Reconfiguration

  • dtbt—This is a script used to manage the overlay. This script provides the dtbt command that can be called from the Linux shell providing the ability to add or remove an overlay to the device tree and also list the overlays currently applied. This is located under Linux file system at /sbin directory. The source code for this script can be seen from the altera-opensource / dtbt web page.
  • pr_fpga_static_region.dtbo—This is the overlay for the static region. This is generated from the pr_fpga_static_region.dts file and creates the new device tree nodes that describe the PR region and the freeze controller. The attributes for the PR region node are expected to be updated by the PR persona overlays. This overlay needs to be applied before persona overlays. This file is located under Linux file system at the /boot/devicetree directory. Next is shown the structure of the static region device tree overlay DTS.
    Note: The static region and PR region can also be defined directly from the initial Linux device tree as alternative to use an overlay for this purpose.
    fragment@0 {
        target-path = "/soc/base_fpga_region";  /* Device tree hierarchy */
        __overlay__ {
    	   /* PR region node */
                compatible = "fpga-region";
                fpga-bridges = <&freeze_controller_0>;
               /* PR freeze Controller node */
               freeze_controller@offset {
                 compatible = "altr,freeze_controller-ver", "altr,freeze-bridge-controller";
  • pr_personaX.dtbo—This is the overlay for the PR Persona X and extends the fpga_pr_regionN node created in the PR Static Region overlay. This overlay is generated from the pr_personaX.dts file. Here is where it is indicated which is the RBF file that corresponds to the FPGA design to be loaded in the PR region (referred to as the personaX.rbf). This overlay also defines additional nodes and specific attributes that applies for this persona in the PR region node in the device tree. There is a PR Persona overlay file for each persona FPGA design to be loaded in the PR region. These overlay files are located under Linux file system at the /boot/devicetree directory. Next is shown the structure of the PR Persona Overlay DTS.
    fragment@1 {
        target-path = "/soc/base_fpga_region/fpga_pr_regionN";
        __overlay__ {
           firmware-name = "personaX.rbf";  /* RBF file for this persona */
           /* Specific attributes for this PR Persona in fpga_pr_regionN  node*/
                /* Specific attributes for this PR Persona in sub node A */
                /* Specific attributes for this PR Persona in sub node B */
  • personaX.rbf—This is the bitstream used by personaX overlay and corresponds to the FPGA design to be loaded into the PR region.

    During the partial reconfiguration started by Linux, this accesses the PR RBF files under its file system at the /lib/firmware directory.
    Note: In the hardware design, it is not allowed enabling both SGMII and PR at the same time. Because of this, the hardware design needs to be recompiled with SGMII disabled and PR enabled to allow PR to be used.
The following figure shows the components involved in Partial Reconfiguration for 2 Persona using the Linux device tree overlays mechanism:
Figure 34. Components Involved
As indicated before, to perform the partial reconfiguration from Linux, we make use of the dtbt command which allows the device tree overlays handling. At the time that the overlay is applied, the PR is performed automatically, and the Linux driver associated to the overlay is loaded. The following table lists some of the functionality that this command provides:
Description Command Usage
List overlays applied dtbt -l
Add an overlay dtbt -a <.dtbo to apply> -p <.dtbo search path>
Remove an overlay dtbt -r <.dtbo to remove > -p <.dtbo search path>
Note: When the PR overlay is removed, the corresponding Linux driver is removed.
To perform the PR successfully, the following sequence should be followed from the Linux shell:
  1. Load static region overlay and confirm that this was applied by listing the overlays.
    # dtbt -a pr_fpga_static_region.dtbo -p /boot/devicetree
    # dtbt -l

    Only one static region overlay should be shown.

  2. Perform PR by loading the desired overlay and confirm that this was applied by listing the overlays applied.
    # dtbt -a pr_persona0.dtbo -p /boot/devicetree
    # dtbt -l

    Static region and persona0 overlays should be shown.

  3. If another PR persona wants to be loaded, the current PR persona overlay needs to be removed and then the new PR Persona overlay should be applied.
    root@agilex:~# dtbt -r pr_persona0.dtbo -p /boot/devicetree
    root@agilex:~# dtbt -a pr_persona1.dtbo -p /boot/devicetree
    root@agilex:~# dtbt -l

    Static region and persona1 overlays should be shown.