HOWTO Create a Devicetree for Arria 10 SoC

Required environment

This write-up relies on a Linux development host environment with a bash shell.

This write-up references these built-in bash shell functions:

cd echo export read type

This write-up references these standard Linux utilities:

base64 cat cp dd find git grep ls make mkdir scp sed sort sudo sync tar wget xz

This write-up references these programs provided by the Intel FPGA software tools installation:

sopc-create-header-files

You can check your current environment by running this loop in your bash shell:

[]$ for NEXT in \
cd echo export read type \
base64 cat cp dd find git grep ls make mkdir scp sed sort sudo sync tar wget xz \
sopc-create-header-files
do
type -t ${NEXT:?} > /dev/null &&
{ echo "    located - ${NEXT:?}" ; } ||
{ echo "NOT located - ${NEXT:?}" ; }
done

If your development environment is missing any of the references from above, then you may need to install the packages or tools that provide those dependencies before you can execute some of the examples described below.

Overview

At the time of this writing the current Intel FPGA tools era is 22.2. The references below will be specific to that Intel FPGA software release environment.

This write-up will demonstrate how to create a devicetree for your own custom FPGA hardware implementation in an SoC FPGA device. As a reference and demonstration platform we will refer to materials that are prepared for use on the Arria 10 SoC development kit. The Golden Hardware Reference Design (GHRD) is a hardware example that is used to create a pre-built Linux SD card example called the Golden System Reference Design (GSRD). The GHRD and GSRD images are distributed on releases.rocketboards.org. We will use the GSRD reference design as the foundation of this write-up and demonstrate how we would create our own devicetree implementation for the GHRD FPGA hardware design as if we were attempting to do this for our own custom hardware platform.

In this write-up we provide many command line examples that are intended to be copied and pasted right on the command line of your Linux development host if you choose to evaluate them. We have made every attempt to create generic command examples that do not incorporate specific environmental requirements that your environment may not provide, but in some cases, you may find that you must edit the example commands to fit your environment more appropriately.

In this write-up we also provide some source file examples and patch examples that you will need to create and apply if you choose to evaluate this content directly. Since the source files and patch files require complex and specific white space that is challenging to represent accurately in various markdown languages that this write-up is distributed in, we have chosen to distribute these source and patch examples as xz compressed base64 encoded text along with command lines that you can use to recreate the precise output that is required for the source and patch files. Here is an example of how this works, you should be able to copy and paste the initial command line below along with all the base64 encoded data through the EOF line onto your Linux command line on your development host and have it produce the results that we show below:

[]$ cat << EOF | base64 -d -i | xz -d
/Td6WFoAAATm1rRGAgAhARwAAAAQz1jM4AJGAPRdAASdiQQG8RGxyToYaWl0rK7DBoB3YK3stuMt
gHWBpFTOaL6Q3l77rOjasGselnIn4jTcx7dH78l1cEuNQqasL+6EoEGJ3YTfPY8kk1Hn3SeCf5sN
9YrpTYB8eSZT36lBlNCuGBLE57vg+xwZvy44MmvtDbi6ZapUTEXN8JfQqXAsRzKyuxm91bd8Rmhj
HTTkbeNneZBqRLsR2vcF/XiP+QwFnSQKx2K5GMSQ8PI09lGfjvRoKaBIO6KAaEiFMjIxi6+jIfXM
lymiiHAW5VGrl1+yuBaFBCOZxeHSGll+OZYB2Vm3QzyscokCoknlAgthhLI8fuMARjY/RHmJ0LMA
AZACxwQAAJ3vYEixxGf7AgAAAAAEWVo=
EOF

When we place this decoded content into the write-up, we convert all the tab characters to spaces to maintain the desired representation of the original content but make it easier for the markdown language environments to represent the vertical alignment accurately. These white space substitutions will change the meaning of some of the patch contents, so you cannot simply cut and paste this text representation for its intended use:

        ranges = <
                S10_LW_H2F_BASE SYSID_QSYS_BASE SYSID_QSYS_BASE SYSID_QSYS_SPAN
                S10_LW_H2F_BASE LED_PIO_BASE    LED_PIO_BASE    LED_PIO_SPAN
                S10_LW_H2F_BASE BUTTON_PIO_BASE BUTTON_PIO_BASE BUTTON_PIO_SPAN
                S10_LW_H2F_BASE DIPSW_PIO_BASE  DIPSW_PIO_BASE  DIPSW_PIO_SPAN
                S10_LW_H2F_BASE ILC_BASE        ILC_BASE        ILC_SPAN
        >;

        ILC: ILC@ILC_UNIT_ADDRESS {
                compatible = "altr,ilc-1.0";
                reg = <S10_LW_H2F_BASE ILC_BASE ILC_SPAN>;
                interrupt-parent = <&intc>;
                interrupts = <
                        0       BUTTON_PIO_IRQ  IRQ_TYPE_LEVEL_HIGH
                        0       DIPSW_PIO_IRQ   IRQ_TYPE_LEVEL_HIGH
                >;
                altr,sw-fifo-depth = <32>;
        };

Throughout the rest of this write-up, we will provide the xz compressed base64 encoded content followed immediately by the decoded representation with the white space modifications as we just demonstrated above.

Initial Arria 10 SoC DK board setup, tools setup, and other setup

Start by getting the Arria 10 SoC DK board set up and configured to run the pre-built SD card image and get the tools and development environment properly configured.

Create a working directory and change into it:

[]$ mkdir a10_soc_example
[]$ cd a10_soc_example

Download the SD card image and the GHRD project image for the Arria 10 SoC DK. At the time of this writing the latest version is the 2022.07 release:

[]$ wget https://releases.rocketboards.org/2022.07/gsrd/a10_gsrd/sdimage.tar.gz
[]$ wget https://releases.rocketboards.org/2022.07/gsrd/a10_gsrd/\
a10_soc_devkit_ghrd_QPDS-22.2pro-21.1std.tar.gz

Extract the SD card image:

[]$ tar xf sdimage.tar.gz

Extract the GHRD project image into a new directory:

[]$ mkdir a10_soc_devkit_ghrd
[]$ tar -C a10_soc_devkit_ghrd -xf a10_soc_devkit_ghrd_QPDS-22.2pro-21.1std.tar.gz

Program the SD image onto a micro-SD card:

[]$ sudo dd if=gsrd-console-image-arria10.wic of=<path-to-sd-card> bs=16M
[]$ sync

Plug the micro-SD card into the Arria 10 SoC DK and boot the board to ensure that you have a working platform. Once you have booted into the Linux environment, verify the Linux kernel version that is being used so that we can create an appropriate devicetree of our own for that Linux kernel environment. Devicetrees are specific to each kernel release, the node, and binding requirements for the devicetree can and often do change from kernel release to kernel release.

Log into the target and run the 'uname' command to determine the kernel version:

arria10 login: root
root@arria10:~# uname -a
Linux arria10 5.15.30-altera #1 SMP Fri Jun 24 03:52:26 UTC 2022 armv7l GNU/Linux

In this case you can see that this version of the pre-built SD card contains a 5.15.30 kernel version, and it was built in June 2022. We will use that information to select the Linux kernel commit that we check out below.

Clone the linux-socfpga git repository and change into the directory:

[]$ git clone https://github.com/altera-opensource/linux-socfpga.git
[]$ cd linux-socfpga

We need to select a commit to check out of the repo that is on the branch that the kernel was built with above. We don't need the exact commit that was used to build the kernel we are running but we want something close to that kernel. The repo is consistently tagged with branch release tags in the form "rel_<branch-name>_<YY>.<MM>.<release>", so if we grep the git tags from the repo looking for the version that we see in the output above we can probably see the tags associated with that branch of the kernel from the repo:

[]$ git tag | grep 5.15.30
rel_socfpga-5.15.30-lts_22.08.02_pr
rel_socfpga-5.15.30-lts_22.09.01_pr

We can see that the "socfpga-5.15.30-lts" kernel tags are present, and we see that the earliest release was tagged in August of 2022. We will use the 22.08.02_pr tag as our target. We check out that commit on a new branch with the same name like this:

[]$ git checkout \
-b rel_socfpga-5.15.30-lts_22.08.02_pr \
rel_socfpga-5.15.30-lts_22.08.02_pr

If you do not have a cross compiler to compile the Linux kernel for Armv7 cores, download one now:

[]$ wget https://developer.arm.com/-/media/Files/downloads/gnu-a/10.3-2021.07/\
binrel/gcc-arm-10.3-2021.07-x86_64-arm-none-linux-gnueabihf.tar.xz

[]$ tar xf gcc-arm-10.3-2021.07-x86_64-arm-none-linux-gnueabihf.tar.xz

Setup the environment so the Linux kernel build environment understands what we are building for:

[]$ export ARCH=arm
[]$ export CROSS_COMPILE=\
<path-to>/gcc-arm-10.3-2021.07-x86_64-arm-none-linux-gnueabihf/bin/arm-none-linux-gnueabihf-

You may want to verify that the compiler can be located in your environment, you can test that with the type command:

[]$ type -P ${CROSS_COMPILE:?}gcc
<path-to>/gcc-arm-10.3-2021.07-x86_64-arm-none-linux-gnueabihf/bin/arm-none-linux-gnueabihf-gcc

Arria 10 SoC devicetree orientation

Our strategy for building our own devicetree will be to leverage the base definitions for the Hard Processor System (HPS) that are up-streamed into the Linux source tree already. In fact, there is an example devicetree for the Arria 10 SoC DK that is already available in the source tree. If we look for the top-level devicetree file for the Arria 10 SoC DK we should find it here:

[]$ find -name socfpga_arria10_socdk_sdmmc.dts
./arch/arm/boot/dts/socfpga_arria10_socdk_sdmmc.dts

Or in your web browser you can look here.

This socfpga_arria10_socdk_sdmmc.dts file is the top-level devicetree file for the Arria 10 SoC DK board and we will want to create something that looks just like this for our own example, but we will need to add the FPGA specific devicetree requirements to our example. We may want to use this file as a starting reference point, but ultimately we will need to create our own top-level devicetree file. This default devicetree example for the Arria 10 SoC DK is only concerned about the HPS hardened peripherals, which do not ever change, so this devicetree can be defined in such a way that it can apply to any other Arria 10 SoC design, and that is what this default example demonstrates. This top-level socfpga_arria10_socdk_sdmmc.dts file simply includes other more fundamental devicetree include files which define more of the lower-level details of the HPS core itself. In this top-level file we see only the top-level enabling of the resources defined in the lower level include files as well as any board level details that interact with the HPS peripherals that are enabled.

This file socfpga_arria10_socdk_sdmmc.dts includes another Arria 10 SoC specific devicetree include file called socfpga_arria10_socdk.dtsi here:

[]$ find -name socfpga_arria10_socdk.dtsi
./arch/arm/boot/dts/socfpga_arria10_socdk.dtsi

Or in your web browser you can look here.

This socfpga_arria10_socdk.dtsi file is generic enough to the Arria 10 SoC device that we will want to simply include this file into our own example top-level devicetree when we begin building it. Even if some of the bindings defined in this include file are not appropriate for our application, we can adjust them in our own top-level file, so there is really no need to modify any of these devicetree include files directly.

The socfpga_arria10_socdk.dtsi file includes the lowest level definition of the HPS for the Arria 10 SoC device in a file called socfpga_arria10.dtsi here:

[]$ find -name socfpga_arria10.dtsi
./arch/arm/boot/dts/socfpga_arria10.dtsi

Or in your web browser you can look here.

This socfpga_arria10.dtsi file contains the definition of all the low-level hardware built into the Arria 10 SoC HPS core. It carries the required clocking structure for the Linux clock framework as well as the devicetree bindings for all the HPS IO peripherals. If you look at this devicetree include file closely you will see that the peripherals that are internal to the HPS core are all enabled by default, i.e., they have no status binding which means they default to enabled. But all the IO peripherals that interact through device pins are marked as disabled, i.e., they all have a status binding that is set to disabled in this devicetree include file. If you look at the include file that includes this file, socfpga_arria10_socdk.dtsi you can see that one of the things it does is redefine the status binding for all the HPS IO peripherals that it wants to enable.

At the socfpga_arria10.dtsi level of the devicetree definition, they primarily try to define the bindings for all the peripherals that are not board specific, so you will see compatible, reg, interrupts, clocks and any other well-defined bindings that are unlikely to change for any implementation of the Arria 10 SoC HPS core. Then at the top-level devicetree file, for example in socfpga_arria10_socdk_sdmmc.dts you would need to enable the peripherals that you require and add any bindings to peripherals that are board specific parameters, and you can even override settings for bindings that are defined in the socfpga_arria10.dtsi level of the devicetree if needed.

You should familiarize yourself with the layout and contents of the Arria 10 SoC DK example devicetree top-level file and all the include files that it leverages. Our own devicetree example will begin by leveraging all that existing material.

Build and test the default Arria 10 SoC DK example devicetree

Build the default example for the Arria 10 SoC DK board that is in the kernel source tree. Make a copy of the original to modify and preserve the original example file.

Start by configuring the Linux kernel with the socfpga_defconfig:

[]$ make socfpga_defconfig

Make a copy of the socfpga_arria10_socdk_sdmmc.dts file for our own use:

[]$ cp \
./arch/arm/boot/dts/socfpga_arria10_socdk_sdmmc.dts \
./arch/arm/boot/dts/my_a10_top.dts

Edit this top-level devicetree source file to create a unique value for the model binding so that we can identify this devicetree when we run it on the target:

[]$ cat << EOF | base64 -d -i | xz -d >> ./arch/arm/boot/dts/my_a10_top.dts
/Td6WFoAAATm1rRGAgAhARwAAAAQz1jMAQAlCi8gewoJbW9kZWwgPSAiRFQgVEVTVCBBMTAgU1gg
REsiOwp9OwoAAACy0qVhKwpxBQABPiarK06zH7bzfQEAAAAABFla
EOF

/ {
        model = "DT TEST A10 SX DK";
};

To build the devicetree, simply call make with the name of the DTB file that you want to compile:

[]$ make my_a10_top.dtb

This works because the default Linux Makefile infrastructure has recipes for building devicetree sources and producing binary devicetree blobs. The Linux Makefile architecture passes all the devicetree sources through the GNU C preprocessor to preprocess macros and other syntax, and then it passes the preprocessed results through the DTC compiler to produce the resultant binary devicetree blob. You could do this on your own without leveraging the Linux kernel build environment if you wanted to, you would do something like this:

[]$ ${CROSS_COMPILE}gcc \
        -E \
        -nostdinc \
        -I./arch/arm/boot/dts \
        -I./include \
        -undef -D__DTS__ \
        -x assembler-with-cpp \
        -o arch/arm/boot/dts/my_a10_top.dts.tmp \
        arch/arm/boot/dts/my_a10_top.dts

[]$ ./scripts/dtc/dtc \
        -O dtb \
        -o arch/arm/boot/dts/my_a10_top.dtb \
        -i arch/arm/boot/dts \
        -@ \
        arch/arm/boot/dts/my_a10_top.dts.tmp

You should be able to locate the DTB that was just built:

[]$ find -name my_a10_top.dtb
./arch/arm/boot/dts/my_a10_top.dtb

Move this DTB file onto the Arria 10 SoC DK target. There are several ways to do this, we will demonstrate moving the file over Ethernet using scp to our target board and then positioning the new DTB where it needs to go.

Start by copying the file to the target:

[]$ scp ./arch/arm/boot/dts/my_a10_top.dtb root@<TARGET-IP-ADDR>:/home/root/

We need to get the new DTB onto the FAT partition of the SD card, so we mount the FAT partition:

root@arria10:~# mount /dev/mmcblk0p1 /mnt

We should preserve the original DTB that came on the SD card:

root@arria10:~# cp /mnt/socfpga_arria10_socdk_sdmmc.dtb \
/mnt/socfpga_arria10_socdk_sdmmc.dtb.orig

We copy our new DTB into the proper location, renaming it appropriately:

root@arria10:~# mv my_a10_top.dtb /mnt/socfpga_arria10_socdk_sdmmc.dtb

Before we try out our new DTB, look at the model string that was defined in the original DTB that is running on the target:

root@arria10:~# (echo ""; cat /proc/device-tree/model; echo "" ;)

Altera SOCFPGA Arria 10

We can reboot the target to have Linux load our new example DTB:

root@arria10:~# reboot

The target should boot back into the Linux environment just as it did before, however none of the FPGA peripherals are defined in this default example devicetree. We will demonstrate how to add the FPGA peripherals into the devicetree next.

Once the target boots up to the Linux environment again, check the model string of the devicetree and make sure that it has updated to the value stored in the example that we just created and loaded onto the target:

root@arria10:~# (echo ""; cat /proc/device-tree/model; echo "" ;)

DT TEST A10 SX DK

What should the devicetree enable in the HPS?

We should be running the Arria 10 SoC DK example devicetree from the kernel source tree that we copied into the my_a10_top.dts file and compiled into a DTB to load onto the target and run. In this devicetree that we copied from socfpga_arria10_socdk_sdmmc.dts, we can see that the mmc HPS IO peripheral has been enabled. The include file socfpga_arria10_socdk.dtsi enables gmac0, gpio1, spi1, i2c1, uart1, and usb0. The include file socfpga_arria10.dtsi enables usbphy0.

There are a few ways to determine what HPS peripherals have been enabled in our hardware project and therefore should be enabled in the devicetree. One way to determine this is to open the HPS peripheral configuration in the Platform Designer system that the component is instantiated in, then you can manually look at the parameterization that selected the peripherals in your design. Another way to determine this is to look for the *_PinMuxing parameters that get output in the SOPCINFO file generated by Platform Designer. Here is an example sed parsing pattern to show us what HPS IO peripherals were enabled in the Arria 10 SoC GHRD design which is what we are running in the SD card image that we programmed into the board:

[]$ cat ../a10_soc_devkit_ghrd/qsys_top/qsys_top.sopcinfo | \
sed -E -e "/<parameter name=\".+_PinMuxing\">/,/<\/parameter>/P" -e "D" | \
sed -E -e "/parameter/P" -e "/value/P" -e "D" | \
sed -n -E -e "/^.*<parameter.*>.*$/h" \
-e "s/^.*<\/parameter>.*$//;T noprint;g;s/^.*<parameter name=\"(.+)_PinMuxing\">.*$/\1/;\
T noprint;P;: noprint;" \
-e "s/^.*<value>Unused<\/value>.*$//;T nodel;h;: nodel"
EMAC0
SDMMC
USB0
SPIM1
UART1
I2C1
TRACE

As you can see, the peripheral list that was enabled in Platform Designer for our HPS matches the list that we saw in the example devicetree, which makes sense. A couple of exceptions worth noting are the TRACE port mentioned in the SOPCINFO output which does not really have a device driver, so we do not need to enable that in the devicetree. Also, the devicetree enables the gpio* peripherals, but those do not have specific pin muxing that shows up in the SOPCINFO file.

If you would like to locate the Linux device drivers and Linux documentation for the HPS peripherals, you can grep the Documentation and drivers directories in the kernel source tree for the compatibility strings that you observe in the HPS devicetree nodes. For Arria 10 SoC, you could for instance run this bash command sequence to do just that:

[]$ grep "compatible" ./arch/arm/boot/dts/socfpga_arria10.dtsi | \
sort -u | \
sed -e "s/^\s*\(.*\)/\\1/" | \
while read NEXT ; do \
echo $NEXT ; \
echo $NEXT | \
sed -e 's/[^"]*["]\([^"]*\)["][^"]*/\1\n/g' | \
while read NEXT1 ; do \
if [ "$NEXT1" != "syscon" ] ; then \
if [ -n "$NEXT1" ] ; then \
grep -Rl "$NEXT1" Documentation/* ; \
grep -Rl "$NEXT1" drivers/* ; \
fi ; \
fi ;
done | sort -u ; \
echo "" ; \
done

What should the devicetree enable in the FPGA?

The primary value of the devicetree is to inform kernel drivers and modules of the peripheral implementation parameters that the hardware design contains. If you are putting your own custom hardware into the FPGA, then you will be the one to decide how you plan to implement the software to interact with that hardware. If you plan to write a user space device driver for your hardware, you may find no need whatsoever in having devicetree entries that define your hardware configuration. Even if you plan to write a kernel mode driver for your hardware, you may or may not want to have your driver configured by parameters stored in a devicetree. A software driver only needs to have devicetree entries if it is built to use them and there are ways to build a driver such that it does not use devicetree entries. Your personal preferences and deployment goals for your product should dictate if and how you use the devicetree to configure your driver. On the other hand, there is no reason you cannot stuff the devicetree full of arbitrary information that no drivers or modules care about. The kernel exposes all the devicetree structure in the procfs and sysfs, so you can observe all the devicetree information from user space which may be useful for some implementations.

If you decide that you would prefer to use devicetree entries to inform your driver of your hardware configuration, then you need to know how to implement them properly in the devicetree. You may also use other standard components in the FPGA which have software device drivers that will rely on devicetree parameters to configure themselves at run time, so you need to ensure that you have properly configured those as well.

In the GHRD example FPGA hardware design that we are currently running on the Arria 10 SoC DK there are a few peripherals which have device drivers that are configured via devicetree. How can we identify what FPGA peripherals we have? And which of those need to be entered in our devicetree?

Again, we could open our Platform Designer system up and manually inspect it to see what peripherals we have instantiated in the FPGA, but we are going to use a utility called sopc-create-header-files to help us decode the data that is generated into the SOPCINFO file and extract the relevant information that we need into C formatted header files.

Start by creating a directory to capture the headers and generate the headers:

[]$ cd ..
[]$ mkdir pd_headers
[]$ sopc-create-header-files \
./a10_soc_devkit_ghrd/qsys_top/qsys_top.sopcinfo \
--output-dir pd_headers
[]$ cd pd_headers

That command should have produced several header files for our GHRD hardware system from the perspective of each master in the system, as well as some system wide perspectives:

[]$ ls
a10_hps_arm_a9_0.h  a10_hps_bridges.h  f2sdram0_m.h  fpga_m.h  pb_lwh2f.h
a10_hps_arm_a9_1.h  a10_hps.h          f2sdram2_m.h  hps_m.h   qsys_top.h

We can use a few grep patterns to extract the base address of the FPGA peripherals in our hardware design:

[]$ cat qsys_top.h | \
grep -E -e "#define A10_HPS_ARM_A9_0_" | \
grep -v -E -e "A10_HPS_ARM_A9_0_A10_HPS_" | \
grep -E -e "_BASE\s"
#define A10_HPS_ARM_A9_0_OCM_0_BASE 0xc0000000
#define A10_HPS_ARM_A9_0_SYS_ID_BASE 0xff200000
#define A10_HPS_ARM_A9_0_LED_PIO_BASE 0xff200010
#define A10_HPS_ARM_A9_0_BUTTON_PIO_BASE 0xff200020
#define A10_HPS_ARM_A9_0_DIPSW_PIO_BASE 0xff200030
#define A10_HPS_ARM_A9_0_ILC_BASE 0xff200100

From this output we can see that there are six peripherals in the FPGA. There is an on-chip memory peripheral, but that does not have a device driver that we care about, so we do not need any devicetree entries for that one. The other five peripherals, the system ID, three pios and the interrupt latency counter peripherals all have Linux drivers that we may choose to enable in the devicetree.

Each peripheral in the devicetree is going to require certain fundamental bindings like the compatible, reg, and interrupts bindings. And some of the peripherals may require additional bindings that are unique to that peripheral. Here is how we find some of the basic information that each peripheral will require for the fundamental bindings.

We can find the base address and span of each peripheral required by the reg binding by looking at the general parameters exposed in the Platform Designer header data, a broad filter like this will expose much of it:

[]$ cat qsys_top.h | \
grep -E -e "#define A10_HPS_ARM_A9_0_" | \
grep -v -E -e "A10_HPS_ARM_A9_0_A10_HPS_"

Output not shown.

One thing that does not show up in that filter is the interrupt values associated with the peripherals in the FPGA. We can use a different filter to extract the interrupt information like this:

[]$ cat qsys_top.h | grep -E -e "_IRQ\s"
#define A10_HPS_BUTTON_PIO_IRQ 0
#define A10_HPS_DIPSW_PIO_IRQ 1

We can see from this that we have an interrupt driven by the jtag uart and two of the pio peripherals. These interrupt values indicate the position of these interrupts on the FPGA-to-HPS interrupt receiver which is a 64-bit vector. These interrupts are assigned to bits 0, 1, and 2 of that vector. On Arria 10 SoC devices the 0th bit of that vector represents interrupt 51 into the GIC of the ARM processor. In the devicetree we must subtract off the first 32 interrupt locations that represent inter-processor interrupts. We can define an equation like this to represent these FPGA driven interrupts in the devicetree, FPGA-interrupt-vector + 51 - 32. And when you observe the devicetree examples that we create below you will see that we implement this equation for the interrupt entries.

For more information on how the ARM GIC expects us to format interrupt entries in the devicetree, you can look at this document:

[]$ find ../linux-socfpga/ -name arm,gic.yaml
../linux-socfpga/Documentation/devicetree/bindings/interrupt-controller/arm,gic.yaml

Or in your web browser you can look here.

The pio peripherals will need some additional information provided in their devicetree bindings, so while we are filtering the Platform Designer header, we can extract that information like this:

[]$ cat qsys_top.h | \
grep -E -e "#define A10_HPS_ARM_A9_0_" | \
grep -v -E -e "A10_HPS_ARM_A9_0_A10_HPS_" | \
grep -E -e "PIO_DATA_WIDTH\s" -e "PIO_EDGE_TYPE\s" -e "PIO_IRQ_TYPE\s"
#define A10_HPS_ARM_A9_0_LED_PIO_DATA_WIDTH 4
#define A10_HPS_ARM_A9_0_LED_PIO_EDGE_TYPE NONE
#define A10_HPS_ARM_A9_0_LED_PIO_IRQ_TYPE NONE
#define A10_HPS_ARM_A9_0_BUTTON_PIO_DATA_WIDTH 4
#define A10_HPS_ARM_A9_0_BUTTON_PIO_EDGE_TYPE FALLING
#define A10_HPS_ARM_A9_0_BUTTON_PIO_IRQ_TYPE EDGE
#define A10_HPS_ARM_A9_0_DIPSW_PIO_DATA_WIDTH 4
#define A10_HPS_ARM_A9_0_DIPSW_PIO_EDGE_TYPE ANY
#define A10_HPS_ARM_A9_0_DIPSW_PIO_IRQ_TYPE EDGE

How did we know that the pio would require some additional binding information? And what other bindings might be needed by any of these peripherals? We can figure out what standard Altera peripherals may have drivers and require devicetree bindings by grep'ing for the string "altr," in the Documentation and drivers directories in the Linux source tree, like this:

[]$ grep -Rl "altr," ../linux-socfpga/Documentation/*

NOTE: with the Intel acquisition of Altera, you are now starting to see new drivers for Intel FPGA devices which carry the "intel," prefix rather than the "altr," prefix that the legacy Altera components were created with.

Out of the list created by the grep command above, we are interested in these three documents that cover the peripherals that we have in our GHRD hardware design:

[]$ find ../linux-socfpga/Documentation/ \
-name altera_sysid.txt -o \
-name gpio-altera.txt -o \
-name altera-interrupt-latency-counter.txt
../linux-socfpga/Documentation/devicetree/bindings/gpio/gpio-altera.txt
../linux-socfpga/Documentation/devicetree/bindings/misc/altera-interrupt-latency-counter.txt
../linux-socfpga/Documentation/devicetree/bindings/misc/altera_sysid.txt

These files can be viewed in a web browser here:

• gpio-altera.txt
• altera-interrupt-latency-counter.txt
• altera_sysid.txt

The one thing that each of these files will provide is the compatibility string that the driver expects. The pio and ILC peripherals have several other bindings that are required and optional that you can include in the devicetree.

With this information about where we can find the details for peripherals that exist inside our FPGA Platform Designer system and how to locate software driver documentation for existing Altera peripherals, we can now proceed to add the FPGA peripherals to our existing devicetree example.

Add the FPGA peripherals to the Arria 10 SoC devicetree

There are several ways to add the FPGA peripherals into the main devicetree, this example will demonstrate two practical and popular ways of doing this. First, we demonstrate how to create a devicetree overlay which can be dynamically applied to and removed from the main system devicetree at run-time. Then we demonstrate how to just embed our FPGA peripherals into the main system devicetree so that it loads at boot with the rest of the devicetree. Since we left the Arria 10 SoC DK in a state where it is running the base example devicetree with no FPGA contents, we will begin with the overlay example first.

Copy the qsys_top.h header into the devicetree source directory in the kernel source tree and change into the kernel source tree directory:

[]$ cp qsys_top.h ../linux-socfpga/arch/arm/boot/dts/
[]$ cd ../linux-socfpga

Devicetree overlay method

Create a new file called arch/arm/boot/dts/my_a10_fpga_overlay.dts to store our FPGA peripheral definition as a devicetree overlay:

[]$ cat << EOF | base64 -d -i | xz -d > arch/arm/boot/dts/my_a10_fpga_overlay.dts
/Td6WFoAAATm1rRGAgAhARwAAAAQz1jM4AtZA1RdABeKfUvNK1NbzTI+B3OUEJMYagjnn0bslkyF
7xuB8nrKCzWcgqNMVnytO8kU434lb6O/lVpXis+nN95L3vIYy31eBXri2sCU9X79+IjTe9hFFxeb
b/i8nsi6sFXtowq6GQ417Joh/X54CNKU1H1hyeJjBgq69gDouzJEXtPlGLEEqxpEJiBy5tE6kWSB
cPqcpP68iOcnCT8tVS9xCCSoMCoCy890ERI/g/J0mO+uRIeUgkk+K2Vhr9hu/+GMn7ExGKxtQDZD
3zPpEqX+R37uTQsZkX/zqrERZde2enP9zrYN9hI9NsUN6ZynWzYZ5CBr5PkdEZih3/NjWKQc4LZn
yRSbItVdj/0uxixraIiDuh2+mHjaC31CDGeBO+vqcvC+4OpBSAlxN4U+E+64OPPsZo64wsIic5GL
aXEBDBTXZW/jN06KWPnBG0mNHpBoElmpXlR2muAUvVo1jciwREirlRej7EyLToQxTQWcobZA93n2
I+dnuLsaWwyiTCJ/KVqi1lFSi9u/srJB5Vawo8Dd+UhU+9uGKPV2UT3CT9wmAsCwutdHdqjlQA6C
aHPVnMdRP+1oC+M91aDOA6hDqmaeLe5z8uccHnzI075/BHMkkMk3qS7Li05XkfY01xkxGu95TfQm
IkmwDmZK4JI8nskgAA3vCsIf67dKeNHPkqqxznYIVxbjzca0QXt95+tu3SpGeExOkskf002lwCeJ
JZEdeJ3RxDM9wa91v4dJEQWHUqaALjDt2LES1NFTCtP4KY6DCkrINej7Xoua+xt1ufnN49iNrfck
dGWAbRw3Ta38yQwq6jhIC5oQ7I4b1BURSxt244vkzulEwkC8U1tC9tHRcYgQCuI0jTepEkCczVcp
zUvcPOLaROleyITxxVO44L4TaxrUMneMXJqArCsoHI2sxP/ZR5d4f+Te6+F2sy9wMDEuH7UBMvol
srGQDZ0rlkX5mOmAcTOe895v+wYaCfLx4D0sfF0sbtSl804mBq1rMl+7UoFMtScUNJPSssoz8WDM
E+8zbIHs/vIwyuFm2fEmtXP42XefFN7WBn0MmYpKm9C/B9LZhj+VbOtm1FyVUB/fS6+m+tIySCn5
50pl6jDACAnCb64cd4aoQse6OF848mwoLUA8TwC9CqLb1mnjOwAB8AbaFgAAW77FCLHEZ/sCAAAA
AARZWg==
EOF

/*
 * SPDX-License-Identifier: MIT-0
 * Copyright (c) 2017-2022 Intel Corporation
 */

/dts-v1/;
/plugin/;

#include "qsys_top.h"
#include "dt-bindings/interrupt-controller/irq.h"

/*
 * Redefine the macros from qsys_top.h into shorter macros and more useful
 * values that we can use directly in the device tree definition.
 */
#define SYSID_QSYS_BASE         A10_HPS_ARM_A9_0_SYS_ID_BASE
#define SYSID_QSYS_SPAN         A10_HPS_ARM_A9_0_SYS_ID_SPAN

#define LED_PIO_BASE            A10_HPS_ARM_A9_0_LED_PIO_BASE
#define LED_PIO_SPAN            A10_HPS_ARM_A9_0_LED_PIO_SPAN
#define LED_PIO_WIDTH           A10_HPS_ARM_A9_0_LED_PIO_DATA_WIDTH

#define BUTTON_PIO_BASE         A10_HPS_ARM_A9_0_BUTTON_PIO_BASE
#define BUTTON_PIO_SPAN         A10_HPS_ARM_A9_0_BUTTON_PIO_SPAN
#define BUTTON_PIO_IRQ          (A10_HPS_BUTTON_PIO_IRQ + 51 - 32)
#define BUTTON_PIO_WIDTH        A10_HPS_ARM_A9_0_BUTTON_PIO_DATA_WIDTH

#define DIPSW_PIO_BASE          A10_HPS_ARM_A9_0_DIPSW_PIO_BASE
#define DIPSW_PIO_SPAN          A10_HPS_ARM_A9_0_DIPSW_PIO_SPAN
#define DIPSW_PIO_IRQ           (A10_HPS_DIPSW_PIO_IRQ + 51 - 32)
#define DIPSW_PIO_WIDTH         A10_HPS_ARM_A9_0_DIPSW_PIO_DATA_WIDTH

#define ILC_BASE                A10_HPS_ARM_A9_0_ILC_BASE
#define ILC_SPAN                A10_HPS_ARM_A9_0_ILC_SPAN

&{/soc/base_fpga_region} {

        external-fpga-config;

        #address-cells = <0x1>;
        #size-cells = <0x1>;

        ranges;

        SYSID_QSYS: SYSID_QSYS@SYSID_QSYS_BASE {
                compatible = "altr,sysid-1.0";
                reg = <SYSID_QSYS_BASE SYSID_QSYS_SPAN>;
        };

        LED_PIO: LED_PIO@LED_PIO_BASE {
                compatible = "altr,pio-1.0";
                reg = <LED_PIO_BASE LED_PIO_SPAN>;
                altr,ngpio = <LED_PIO_WIDTH>;
                #gpio-cells = <2>;
                gpio-controller;
        };

        BUTTON_PIO: BUTTON_PIO@BUTTON_PIO_BASE {
                compatible = "altr,pio-1.0";
                reg = <BUTTON_PIO_BASE BUTTON_PIO_SPAN>;
                interrupt-parent = <&intc>;
                interrupts = <0 BUTTON_PIO_IRQ IRQ_TYPE_LEVEL_HIGH>;
                altr,ngpio = <BUTTON_PIO_WIDTH>;
                #gpio-cells = <2>;
                gpio-controller;
                #interrupt-cells = <1>;
                interrupt-controller;
                altr,interrupt-type = <IRQ_TYPE_EDGE_FALLING>;
        };

        DIPSW_PIO: DIPSW_PIO@DIPSW_PIO_BASE {
                compatible = "altr,pio-1.0";
                reg = <DIPSW_PIO_BASE DIPSW_PIO_SPAN>;
                interrupt-parent = <&intc>;
                interrupts = <0 DIPSW_PIO_IRQ IRQ_TYPE_LEVEL_HIGH>;
                altr,ngpio = <DIPSW_PIO_WIDTH>;
                #gpio-cells = <2>;
                gpio-controller;
                #interrupt-cells = <1>;
                interrupt-controller;
                altr,interrupt-type = <IRQ_TYPE_EDGE_BOTH>;
        };

        ILC: ILC@ILC_BASE {
                compatible = "altr,ilc-1.0";
                reg = <ILC_BASE ILC_SPAN>;
                interrupt-parent = <&intc>;
                interrupts = <
                        0       BUTTON_PIO_IRQ  IRQ_TYPE_LEVEL_HIGH
                        0       DIPSW_PIO_IRQ   IRQ_TYPE_LEVEL_HIGH
                        >;
                altr,sw-fifo-depth = <32>;
        };

        leds {

                compatible = "gpio-leds";

                fpga0 {
                        label = "fpga_led0";
                        gpios = <&LED_PIO 0 1>;
                };

                fpga1 {
                        label = "fpga_led1";
                        gpios = <&LED_PIO 1 1>;
                };

                fpga2 {
                        label = "fpga_led2";
                        gpios = <&LED_PIO 2 1>;
                };

                fpga3 {
                        label = "fpga_led3";
                        gpios = <&LED_PIO 3 1>;
                };
        };

}; // base_fpga_region

Build this devicetree overlay file using the kernel build environment just like we built the main system devicetree example above:

[]$ make my_a10_fpga_overlay.dtb

Note that these warnings are expected and benign for our example:

arch/arm/boot/dts/my_a10_fpga_overlay.dts:43.2-9:
Warning (ranges_format): /fragment@0/__overlay__:ranges: empty "ranges" property
but its #address-cells (1) differs from /fragment@0 (2)

arch/arm/boot/dts/my_a10_fpga_overlay.dts:36.26-120.3:
Warning (avoid_default_addr_size): /fragment@0/__overlay__: Relying on default
#address-cells value

arch/arm/boot/dts/my_a10_fpga_overlay.dts:36.26-120.3:
Warning (avoid_default_addr_size): /fragment@0/__overlay__: Relying on default
#size-cells value

You should be able to locate the DTB that was just built:

[]$ find -name my_a10_fpga_overlay.dtb
./arch/arm/boot/dts/my_a10_fpga_overlay.dtb

To test this devicetree overlay, copy it over to the target that is running the my_a10_top.dtb example devicetree:

[]$ scp ./arch/arm/boot/dts/my_a10_fpga_overlay.dtb root@<TARGET-IP-ADDR>:/home/root/

Place the my_a10_fpga_overlay.dtb overlay file in the /lib/firmware directory, you may need to create that directory:

root@arria10:~# mkdir -p /lib/firmware
root@arria10:~# mv my_a10_fpga_overlay.dtb /lib/firmware/

With the devicetree overlay DTB in the firmware directory, you can now apply it to the system devicetree. Do that by creating a directory under /sys/kernel/config/device-tree/overlays/, and then write the name of the devicetree overlay to the resultant path file that gets created in that new directory. There is a status file that gets created in that directory as well that informs you of the overlay status:

root@arria10:~# mkdir /sys/kernel/config/device-tree/overlays/my-a10-fpga-overlay
root@arria10:~# ls /sys/kernel/config/device-tree/overlays/my-a10-fpga-overlay
dtbo    path    status
root@arria10:~# cat /sys/kernel/config/device-tree/overlays/my-a10-fpga-overlay/status
unapplied
root@arria10:~# echo my_a10_fpga_overlay.dtb \
> /sys/kernel/config/device-tree/overlays/my-a10-fpga-overlay/path
root@arria10:~# cat /sys/kernel/config/device-tree/overlays/my-a10-fpga-overlay/status
applied

Once this overlay is applied to the main system devicetree, you should see the FPGA LEDs on the Arria 10 SoC DK turn off if they were in the uninitialized state after the FPGA was programmed at boot. In this version of the GSRD, the scroll_server application is running which means that the FPGA LEDs should scroll back and forth now that the FPGA peripherals are enabled. Even with the scroll server running, you should be able to toggle an FPGA LED at this point like this:

root@arria10:~# echo 1 > /sys/class/leds/fpga_led0/brightness
root@arria10:~# echo 0 > /sys/class/leds/fpga_led0/brightness

You should also be able to read the sysid values like this:

root@arria10:~# cat /sys/devices/platform/soc/soc:base_fpga_region/fpga_region/region0/\
ff200000.SYSID_QSYS/sysid/id
3221768204
root@arria10:~# cat /sys/devices/platform/soc/soc:base_fpga_region/fpga_region/region0/\
ff200000.SYSID_QSYS/sysid/timestamp
1657736414 (2022-7-13 18:20:14 UTC)

If you investigate the sysfs and procfs, as shown in the section below, you should be able to see all the new devicetree entries that were applied with the overlay. If you want to remove the overlay, just remove the directory that you created in /sys/kernel/config/device-tree/overlays/:

root@arria10:~# rmdir /sys/kernel/config/device-tree/overlays/my-a10-fpga-overlay

Main system devicetree integration method

Create a new file called arch/arm/boot/dts/my_a10_fpga.dtsi to store our FPGA peripheral definition as part of the main system devicetree:

[]$ cat << EOF | base64 -d -i | xz -d > arch/arm/boot/dts/my_a10_fpga.dtsi
/Td6WFoAAATm1rRGAgAhARwAAAAQz1jM4AxGA3ldABeKfUvNK1NbzTI+B3OUEJMYagjnn0bslkyF
7xuB8nrKCzWcgqNMVnytO8kU434lb6O/lVpXis+nN95L3vIYy31eBXri2sCU9X79+IjTe9hFFxeb
b5e8rZBgRatgpj/aj2KB8A6D+4vVsTW1swTKdsoQnleasgxkruiZDsLBiKBL2nqQwFsWZJ8NyQhq
kU4YRUEg2HnbnmpG8V7dOgoeDOAtMmuONCgyx+R9IYpsugoCYIxbML7Wrw4L5BqNv+ACYNNCoa/O
BcLDOQlVbI7JSgG7Z+8jazm+U58KjgCl91CHwx9A4x4Dn9S0wzazUGJJke5PCSwSQ1lvKGR4K4GT
E4YmfHbyzLcc9ySoJROEKY1q/sG2v6kp4rmZm7uPn+gJwSbkccuKG1grQAUdMce87lHs0lCQXf8G
+nHo0/75tnHh/65rPK7p2wa5jx9Ef8XiXXz2RRbPho1rlm2gPqoTqheBEvPZNNu2qZ3Cksb1plTs
RRkXmpsgG6BkWz1PJGe5LrncFz08uflhPT6oO+FTQKClXKH/AQ4b/EfLXKRV5Wzoe87DFbxMn6o5
HFZkycteFSC1i15LYalnqV1bm965fYpcRgETy49G/Ad/Rnen9+QYWT2dR91DQ7q43OXEwf8yrpk5
66SY8cuafxlEeUL7BnkOVa1GwAU6WVux+pKTDECkDaUPMvo2UqVRwCeEeNxGNZ6kH+bjxp1LfFfq
THofi+zifXFiNeVTGqmNZQqkIdJm71k6N/ZChQtkCSNItNNtIbR/rRAWhWkLcu19poB4HjeP4n+p
h4qMZEM7bqJZfYnSZvr3lKWahEwhWOrWg3KCGGzK9qvwFNxTKqhIelEvecK86clofCQtnsJfnGXh
Qv3TuUoH8SWjF2fMbsfxYA8C4uChTWGzKSoai6bPSZtgncQ1aUJLsdgTzJkivxDqtXjydWhx6C8U
gdKC/X8ohbD+4CKgej2qa8mB5LFkhyehU0u7Il3o+SLEyK4NS4O6/lsk0kr/3ldhS36u23H7GtPY
8vd6qMcY+fuF9iihgFnmWK3S3YvgKh/p3PiFikXupmJ3n0IFT7aY6Q1C4iPld89R8BNlam+UEmZx
oQd/u55+eJRZE+vgOAbE21nr+cnKgd/Jc3MZ0KYkR3Hrrf3Xe/CfLATpN6Mxvb7hCvHV+CcFPUVk
kfL9myPfw/0AAAAA5nH1v1z2SGMAAZUHxxgAAEqrccWxxGf7AgAAAAAEWVo=
EOF

/*
 * SPDX-License-Identifier: MIT-0
 * Copyright (c) 2017-2022 Intel Corporation
 */

#include "qsys_top.h"
#include "dt-bindings/interrupt-controller/irq.h"

/*
 * Redefine the macros from qsys_top.h into shorter macros and more useful
 * values that we can use directly in the devicetree definition.
 */
#define SYSID_QSYS_BASE         A10_HPS_ARM_A9_0_SYS_ID_BASE
#define SYSID_QSYS_SPAN         A10_HPS_ARM_A9_0_SYS_ID_SPAN

#define LED_PIO_BASE            A10_HPS_ARM_A9_0_LED_PIO_BASE
#define LED_PIO_SPAN            A10_HPS_ARM_A9_0_LED_PIO_SPAN
#define LED_PIO_WIDTH           A10_HPS_ARM_A9_0_LED_PIO_DATA_WIDTH

#define BUTTON_PIO_BASE         A10_HPS_ARM_A9_0_BUTTON_PIO_BASE
#define BUTTON_PIO_SPAN         A10_HPS_ARM_A9_0_BUTTON_PIO_SPAN
#define BUTTON_PIO_IRQ          (A10_HPS_BUTTON_PIO_IRQ + 51 - 32)
#define BUTTON_PIO_WIDTH        A10_HPS_ARM_A9_0_BUTTON_PIO_DATA_WIDTH

#define DIPSW_PIO_BASE          A10_HPS_ARM_A9_0_DIPSW_PIO_BASE
#define DIPSW_PIO_SPAN          A10_HPS_ARM_A9_0_DIPSW_PIO_SPAN
#define DIPSW_PIO_IRQ           (A10_HPS_DIPSW_PIO_IRQ + 51 - 32)
#define DIPSW_PIO_WIDTH         A10_HPS_ARM_A9_0_DIPSW_PIO_DATA_WIDTH

#define ILC_BASE                A10_HPS_ARM_A9_0_ILC_BASE
#define ILC_SPAN                A10_HPS_ARM_A9_0_ILC_SPAN

/ {
soc {

base_fpga_region {

        external-fpga-config;

        #address-cells = <0x2>;
        #size-cells = <0x1>;

        ranges = <
                SYSID_QSYS_BASE 0       SYSID_QSYS_BASE SYSID_QSYS_SPAN
                LED_PIO_BASE    0       LED_PIO_BASE    LED_PIO_SPAN
                BUTTON_PIO_BASE 0       BUTTON_PIO_BASE BUTTON_PIO_SPAN
                DIPSW_PIO_BASE  0       DIPSW_PIO_BASE  DIPSW_PIO_SPAN
                ILC_BASE        0       ILC_BASE        ILC_SPAN
                >;

        SYSID_QSYS: SYSID_QSYS@SYSID_QSYS_BASE,0 {
                compatible = "altr,sysid-1.0";
                reg = <SYSID_QSYS_BASE 0 SYSID_QSYS_SPAN>;
        };

        LED_PIO: LED_PIO@LED_PIO_BASE,0 {
                compatible = "altr,pio-1.0";
                reg = <LED_PIO_BASE 0 LED_PIO_SPAN>;
                altr,ngpio = <LED_PIO_WIDTH>;
                #gpio-cells = <2>;
                gpio-controller;
        };

        BUTTON_PIO: BUTTON_PIO@BUTTON_PIO_BASE,0 {
                compatible = "altr,pio-1.0";
                reg = <BUTTON_PIO_BASE 0 BUTTON_PIO_SPAN>;
                interrupt-parent = <&intc>;
                interrupts = <0 BUTTON_PIO_IRQ IRQ_TYPE_LEVEL_HIGH>;
                altr,ngpio = <BUTTON_PIO_WIDTH>;
                #gpio-cells = <2>;
                gpio-controller;
                #interrupt-cells = <1>;
                interrupt-controller;
                altr,interrupt-type = <IRQ_TYPE_EDGE_FALLING>;
        };

        DIPSW_PIO: DIPSW_PIO@DIPSW_PIO_BASE,0 {
                compatible = "altr,pio-1.0";
                reg = <DIPSW_PIO_BASE 0 DIPSW_PIO_SPAN>;
                interrupt-parent = <&intc>;
                interrupts = <0 DIPSW_PIO_IRQ IRQ_TYPE_LEVEL_HIGH>;
                altr,ngpio = <DIPSW_PIO_WIDTH>;
                #gpio-cells = <2>;
                gpio-controller;
                #interrupt-cells = <1>;
                interrupt-controller;
                altr,interrupt-type = <IRQ_TYPE_EDGE_BOTH>;
        };

        ILC: ILC@ILC_BASE,0 {
                compatible = "altr,ilc-1.0";
                reg = <ILC_BASE 0 ILC_SPAN>;
                interrupt-parent = <&intc>;
                interrupts = <
                        0       BUTTON_PIO_IRQ  IRQ_TYPE_LEVEL_HIGH
                        0       DIPSW_PIO_IRQ   IRQ_TYPE_LEVEL_HIGH
                        >;
                altr,sw-fifo-depth = <32>;
        };

        fpga_leds {
                compatible = "gpio-leds";

                fpga0 {
                        label = "fpga_led0";
                        gpios = <&LED_PIO 0 1>;
                };

                fpga1 {
                        label = "fpga_led1";
                        gpios = <&LED_PIO 1 1>;
                };

                fpga2 {
                        label = "fpga_led2";
                        gpios = <&LED_PIO 2 1>;
                };

                fpga3 {
                        label = "fpga_led3";
                        gpios = <&LED_PIO 3 1>;
                };
        };
};

}; // soc
}; // /

Edit the arch/arm/boot/dts/my_a10_top.dts file to include our new FPGA devicetree definition:

[]$ cat << EOF | base64 -d -i | xz -d | bash
/Td6WFoAAATm1rRGAgAhARwAAAAQz1jM4ACFAGxdADmZSuojhxSi3Mv8MfjO12CEtsMK+7liVcns
z5YLtM3IyUrqx0d48jihm/tdVeyGQZeXitbgU/cmF1i0lEd6+ZNveQckWa+x3eZvzwfWphIlLb0f
wXpxlicusOTIvBTLOAEi8o6GqFoIEXAAAAC41+hmJEhfywABiAGGAQAACOgmxbHEZ/sCAAAAAARZ
Wg==
EOF

set -x
sed \
-i.bak \
-e '/#include "socfpga_arria10_socdk.dtsi"/a #include "my_a10_fpga.dtsi"' \
./arch/arm/boot/dts/my_a10_top.dts

Build the devicetree:

[]$ make my_a10_top.dtb

You should be able to locate the DTB that was just built:

[]$ find -name my_a10_top.dtb
./arch/arm/boot/dts/my_a10_top.dtb

Copy the new system DTB over to the target:

[]$ scp ./arch/arm/boot/dts/my_a10_top.dtb root@<TARGET-IP-ADDR>:/home/root/

Move the DTB onto the FAT partition with the proper name to be loaded at start-up:

root@arria10:~# mount /dev/mmcblk0p1 /mnt
root@arria10:~# mv my_a10_top.dtb /mnt/socfpga_arria10_socdk_sdmmc.dtb

Now reboot the target:

root@arria10:~# reboot

When the kernel boots you should again see the FPGA LEDs turn off as the drivers are loaded based on the devicetree configuration and the scroll server should scroll them back and forth. If you investigate the sysfs and procfs, as shown in the section below, you should be able to see all the new devicetree entries that were added to the main system devicetree.

Observing devicetree evidence in the sysfs and procfs

If you would like to observe the devicetree evidence in the sysfs, you can search for the names that we used in our FPGA section and see where various entries are maintained in the sysfs that reference them:

root@arria10:~# find /sys \
-name "*SYSID*" -o \
-name "*PIO*" -o \
-name "*ILC*" | \
sort
/sys/bus/platform/devices/ff200000.SYSID_QSYS
/sys/bus/platform/devices/ff200010.LED_PIO
/sys/bus/platform/devices/ff200020.BUTTON_PIO
/sys/bus/platform/devices/ff200030.DIPSW_PIO
/sys/bus/platform/devices/ff200100.ILC
/sys/bus/platform/drivers/altera_gpio/ff200010.LED_PIO
/sys/bus/platform/drivers/altera_gpio/ff200020.BUTTON_PIO
/sys/bus/platform/drivers/altera_gpio/ff200030.DIPSW_PIO
/sys/bus/platform/drivers/altera_ilc/ff200100.ILC
/sys/bus/platform/drivers/altera_sysid/ff200000.SYSID_QSYS
/sys/devices/platform/soc/soc:base_fpga_region/fpga_region/region0/ff200000.SYSID_QSYS
/sys/devices/platform/soc/soc:base_fpga_region/fpga_region/region0/ff200010.LED_PIO
/sys/devices/platform/soc/soc:base_fpga_region/fpga_region/region0/ff200020.BUTTON_PIO
/sys/devices/platform/soc/soc:base_fpga_region/fpga_region/region0/ff200030.DIPSW_PIO
/sys/devices/platform/soc/soc:base_fpga_region/fpga_region/region0/ff200100.ILC
/sys/firmware/devicetree/base/__symbols__/BUTTON_PIO
/sys/firmware/devicetree/base/__symbols__/DIPSW_PIO
/sys/firmware/devicetree/base/__symbols__/ILC
/sys/firmware/devicetree/base/__symbols__/LED_PIO
/sys/firmware/devicetree/base/__symbols__/SYSID_QSYS
/sys/firmware/devicetree/base/soc/base_fpga_region/BUTTON_PIO@0xff200020,0
/sys/firmware/devicetree/base/soc/base_fpga_region/DIPSW_PIO@0xff200030,0
/sys/firmware/devicetree/base/soc/base_fpga_region/ILC@0xff200100,0
/sys/firmware/devicetree/base/soc/base_fpga_region/LED_PIO@0xff200010,0
/sys/firmware/devicetree/base/soc/base_fpga_region/SYSID_QSYS@0xff200000,0

You can find similar evidence in the procfs as well:

root@arria10:~# find /proc/device-tree/soc/base_fpga_region/ -maxdepth 1 | sort
/proc/device-tree/soc/base_fpga_region/
/proc/device-tree/soc/base_fpga_region/#address-cells
/proc/device-tree/soc/base_fpga_region/#size-cells
/proc/device-tree/soc/base_fpga_region/BUTTON_PIO@0xff200020,0
/proc/device-tree/soc/base_fpga_region/DIPSW_PIO@0xff200030,0
/proc/device-tree/soc/base_fpga_region/ILC@0xff200100,0
/proc/device-tree/soc/base_fpga_region/LED_PIO@0xff200010,0
/proc/device-tree/soc/base_fpga_region/SYSID_QSYS@0xff200000,0
/proc/device-tree/soc/base_fpga_region/compatible
/proc/device-tree/soc/base_fpga_region/external-fpga-config
/proc/device-tree/soc/base_fpga_region/fpga-mgr
/proc/device-tree/soc/base_fpga_region/fpga_leds
/proc/device-tree/soc/base_fpga_region/name
/proc/device-tree/soc/base_fpga_region/ranges

Notes about peripherals in this Arria 10 SoC GSRD example

The SYSID_QSYS, LED_PIO, DIPSW_PIO, and BUTTON_PIO peripherals should all work as expected.

In this version of the GSRD, the ILC peripheral will report errors as the driver loads. This is because the ILC driver does not support the new GPIO IRQ framework that is implemented in the modern kernel. The current ILC driver expects to be able to share IRQs with the peripherals that it monitors, and the modern GPIO framework no longer supports that:

root@arria10:~# dmesg | grep ilc
[    5.291385] altera_ilc ff200100.ILC: Failed to register interrupt handler
[    5.298291] altera_ilc ff200100.ILC: Failed to register interrupt handler
[    5.305168] altera_ilc ff200100.ILC: Driver successfully loaded