HOWTO Create a Devicetree for Cyclone V 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 21.1std. 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 Cyclone V 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 Cyclone V SoC DK board setup, tools setup, and other setup

Start by getting the Cyclone V 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 cv_soc_example
[]$ cd cv_soc_example

Download the SD card image and the GHRD project image for the Cyclone V SoC DK. At the time of this writing the latest version is the 2021.11 release:

[]$ wget https://releases.rocketboards.org/2021.11/gsrd/c5_gsrd/sdimage.tar.gz
[]$ wget https://releases.rocketboards.org/2021.11/gsrd/c5_gsrd/cv_soc_devkit_ghrd.tar.gz

Extract the SD card image:

[]$ tar xf sdimage.tar.gz

Extract the GHRD project image into a new directory:

[]$ mkdir cv_soc_devkit_ghrd
[]$ tar -C cv_soc_devkit_ghrd -xf cv_soc_devkit_ghrd.tar.gz

Program the SD image onto a micro-SD card:

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

Plug the micro-SD card into the Cyclone V 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:

cyclone5 login: root
root@cyclone5:~# uname -a
Linux cyclone5 5.10.60-altera #1 SMP Tue Nov 16 08:56:52 UTC 2021 armv7l GNU/Linux

In this case you can see that this version of the pre-built SD card contains a 5.10.60 kernel version, and it was built in November 2021. 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.10.60
rel_socfpga-5.10.60-lts_21.10.01_pr
rel_socfpga-5.10.60-lts_21.10.02_pr
rel_socfpga-5.10.60-lts_21.10.03_pr
rel_socfpga-5.10.60-lts_21.11.01_pr
rel_socfpga-5.10.60-lts_21.11.02_pr
rel_socfpga-5.10.60-lts_21.11.03_pr
rel_socfpga-5.10.60-lts_21.12.01_pr
rel_socfpga-5.10.60-lts_21.12.02_pr
rel_socfpga-5.10.60-lts_21.12.03_pr
rel_socfpga-5.10.60-lts_22.01.01_pr
rel_socfpga-5.10.60-lts_22.01.03_pr
rel_socfpga-5.10.60-lts_22.02.01_pr

We can see that the "socfpga-5.10.60-lts" kernel tags are present, and we see that there are three releases that were tagged in November of 2021. We will use the 21.11.03_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.10.60-lts_21.11.03_pr \
rel_socfpga-5.10.60-lts_21.11.03_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

Cyclone V 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 Cyclone V SoC DK that is already available in the source tree. If we look for the top-level devicetree file for the Cyclone V SoC DK we should find it here:

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

Or in your web browser you can look here.

This socfpga_cyclone5_socdk.dts file is the top-level devicetree file for the Cyclone V 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 Cyclone V 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 Cyclone V SoC design, and that is what this default example demonstrates. This top-level socfpga_cyclone5_socdk.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_cyclone5_socdk.dts includes another Cyclone V SoC specific devicetree include file called socfpga_cyclone5.dtsi here:

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

Or in your web browser you can look here.

This socfpga_cyclone5.dtsi file is generic enough to the Cyclone V 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_cyclone5.dtsi file includes the lowest level definition of the HPS for the Cyclone V SoC device in a file called socfpga.dtsi here:

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

Or in your web browser you can look here.

This socfpga.dtsi file contains the definition of all the low-level hardware built into the Cyclone V 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 top-level devicetree file, socfpga_cyclone5_socdk.dts 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.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 Cyclone V SoC HPS core. Then at the top-level devicetree file, for example in socfpga_cyclone5_socdk.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.dtsi level of the devicetree if needed.

You should familiarize yourself with the layout and contents of the Cyclone V 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 Cyclone V SoC DK example devicetree

Build the default example for the Cyclone V 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_cyclone5_socdk.dts file for our own use:

[]$ cp \
./arch/arm/boot/dts/socfpga_cyclone5_socdk.dts \
./arch/arm/boot/dts/my_cv_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:

[]$ sed -i "s/Altera SOCFPGA Cyclone V SoC Development Kit/DT TEST CV SX DK/" \
./arch/arm/boot/dts/my_cv_top.dts

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

[]$ make my_cv_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_cv_top.dts.tmp \
        arch/arm/boot/dts/my_cv_top.dts

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

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

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

Move this DTB file onto the Cyclone V 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_cv_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@cyclone5:~# mount /dev/mmcblk0p1 /mnt

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

root@cyclone5:~# cp /mnt/socfpga_cyclone5_socdk.dtb \
/mnt/socfpga_cyclone5_socdk.dtb.orig

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

root@cyclone5:~# mv my_cv_top.dtb /mnt/socfpga_cyclone5_socdk.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@cyclone5:~# (echo ""; cat /proc/device-tree/model; echo "" ;)

Altera SOCFPGA Cyclone V SoC Development Kit

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

root@cyclone5:~# 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@cyclone5:~# (echo ""; cat /proc/device-tree/model; echo "" ;)

DT TEST CV SX DK

What should the devicetree enable in the HPS?

We should be running the Cyclone V SoC DK example devicetree from the kernel source tree that we copied into the my_cv_top.dts file and compiled into a DTB to load onto the target and run. In this devicetree that we copied from socfpga_cyclone5_socdk.dts, we can see that the following HPS IO peripherals have been enabled, can0, gmac1, gpio0, gpio1, gpio2, i2c0, mmc0, qspi, spi0 and usb1. The include file socfpga.dtsi enables uart0 and uart1.

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 Cyclone V SoC GHRD design which is what we are running in the SD card image that we programmed into the board:

[]$ cat ../cv_soc_devkit_ghrd/soc_system.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"
EMAC1
QSPI
SDIO
USB1
SPIM0
UART0
I2C0
CAN0
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 Cyclone V SoC, you could for instance run this bash command sequence to do just that:

[]$ grep "compatible" ./arch/arm/boot/dts/socfpga.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 Cyclone V 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 \
./cv_soc_devkit_ghrd/soc_system.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
f2sdram_only_master.h  hps_0_arm_a9_1.h  hps_only_master.h
fpga_only_master.h     hps_0_bridges.h   mm_bridge_0.h
hps_0_arm_a9_0.h       hps_0.h           soc_system.h

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

[]$ cat soc_system.h | \
grep -E -e "#define HPS_0_ARM_A9_0_" | \
grep -v -E -e "HPS_0_ARM_A9_0_HPS_0_" | \
grep -E -e "_BASE\s"
#define HPS_0_ARM_A9_0_ONCHIP_MEMORY2_0_BASE 0xc0000000
#define HPS_0_ARM_A9_0_JTAG_UART_BASE 0xff260000
#define HPS_0_ARM_A9_0_SYSID_QSYS_BASE 0xff260008
#define HPS_0_ARM_A9_0_LED_PIO_BASE 0xff260040
#define HPS_0_ARM_A9_0_DIPSW_PIO_BASE 0xff260080
#define HPS_0_ARM_A9_0_BUTTON_PIO_BASE 0xff2600c0
#define HPS_0_ARM_A9_0_ILC_BASE 0xff270000

From this output we can see that there are seven 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 six peripherals, the jtag uart, 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 soc_system.h | \
grep -E -e "#define HPS_0_ARM_A9_0_" | \
grep -v -E -e "HPS_0_ARM_A9_0_HPS_0_"

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 soc_system.h | grep -E -e "_IRQ\s"
#define HPS_0_JTAG_UART_IRQ 2
#define HPS_0_DIPSW_PIO_IRQ 0
#define HPS_0_BUTTON_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 Cyclone V SoC and AV SoC devices the 0th bit of that vector represents interrupt 72 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 + 72 - 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 soc_system.h | \
grep -E -e "#define HPS_0_ARM_A9_0_" | grep -v -E -e "HPS_0_ARM_A9_0_HPS_0_" | \
grep -E -e "PIO_DATA_WIDTH\s" -e "PIO_EDGE_TYPE\s" -e "PIO_IRQ_TYPE\s"
#define HPS_0_ARM_A9_0_LED_PIO_DATA_WIDTH 4
#define HPS_0_ARM_A9_0_LED_PIO_EDGE_TYPE NONE
#define HPS_0_ARM_A9_0_LED_PIO_IRQ_TYPE NONE
#define HPS_0_ARM_A9_0_DIPSW_PIO_DATA_WIDTH 4
#define HPS_0_ARM_A9_0_DIPSW_PIO_EDGE_TYPE ANY
#define HPS_0_ARM_A9_0_DIPSW_PIO_IRQ_TYPE EDGE
#define HPS_0_ARM_A9_0_BUTTON_PIO_DATA_WIDTH 2
#define HPS_0_ARM_A9_0_BUTTON_PIO_EDGE_TYPE FALLING
#define HPS_0_ARM_A9_0_BUTTON_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 four documents that cover the peripherals that we have in our GHRD hardware design:

[]$ find ../linux-socfpga/Documentation/ \
-name altera_jtaguart.txt -o \
-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
../linux-socfpga/Documentation/devicetree/bindings/serial/altera_jtaguart.txt

These files can be viewed in a web browser here:

• gpio-altera.txt
• altera_jtaguart.txt
• altera_sysid.txt
• altera-interrupt-latency-counter.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 Cyclone V 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 Cyclone V 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 soc_system.h header into the devicetree source directory in the kernel source tree and change into the kernel source tree directory:

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

Devicetree overlay method

Create a new file called arch/arm/boot/dts/my_cv_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_cv_fpga_overlay.dts
/Td6WFoAAATm1rRGAgAhARwAAAAQz1jM4AzTA3xdABeKfUvNK1NbzTI+B3OUEJMYagjnn0bslkyF
7xuB8nrKCzWcgqNMVnytO8kU434lb6O/lVpXis+nN95L3vIYy31eBXri2sCU9X79+IjTe9hFFxeb
b/i8nsi6sFXtowq6GQ417Joh/X54CNKU1H1hyhGkaFyzyZ8qwEKzCmx3GoQ4YrRQ8j0fe7TL4eOI
xnK7Df3U+ntg4qXUT5V6ymrk7+kWb+M4q4W/Tiy2ZEtoSEghZz7QBCBq2IAHqr7KHWFKRN56BVYo
WjYIFUeqq+6aJI5c8Q+lkDBZlXE72UTM/XTkl3JrF7cvBSQ/qFYOosWOH5qi8nZWAYLCvW3rG/z7
41AIHY3IT6UlbtJI8TcskqqVE9AkeFozz27A7ZLGAIbd5xPyCi3AS2hYULkEfOqFBz7VdtTUfBHF
ZZJ2abUwndsMMzq5b70Waw7oeZTQepXrzXIQ0BAjbGoYOVBNcfnKwB7Eln+BXpRvHi3Fcu76cQL6
GZtsZkdybbj1wFBG5MNhzsDo3gz5p22Ml/0r/w9Yfa9MfZzeMBZUzK3OGronDMrnlSVVBvDhTnsm
x6nVo5qydsFJcQT0Yv0cP/X90PlkN05g/5PS8mVVNtZAObxhS9ZBDpnr0Fk4e9PmLI4IkVUnH907
/siSsyEZD3s+866DPvk5GE2drK0Fu7SDWNbMjHruyI3Pez5ZOi3oHBJteINHfmYQ63JRr1Yb0l1C
8yhKbSt18i5DHahpatFozZBhgVlzpYTamjBO6Ip7koSsynoLN++9eZQVQ7uNU7pHEYqplzSYfApe
xkve4bCk/yfiBhsDMNuMAnNuT0DsHbwHIajuxhdfu9WWmnhNQrYZJleaq+55c38+YboMREDbWPBF
n46SdfHbZsdFwfBrUwxEZtrQHNLnlOP/JnZERUzMcRKnVc5oriKbeY+n3b3euAknX4FFvkqtNP3l
ILJx+PTPQuvCbH5YzEuGdGm8rx1GQhVMcohExcBPcMcyeHr2/zoaimJBoZLpNss89M4rUPZpI3iY
0vbh5BSMziNO/ptF4tC1bO6dh6kIWI/Mh74dN+TAXSZMyl2Xuqv50kFefKcOVBAWBENvXyTSgLZs
JKxbR4wechOy87FMxM/iPEnDiWya4LXZ/9imP6gx64U4xmd10iuDG9WWVkYT3gqwHvDNUJpBTiiK
bVmPtLfV/DJW0uoAPKdnZZ+l++EAAZgH1BkAANIqgTqxxGf7AgAAAAAEWVo=
EOF

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

/dts-v1/;
/plugin/;

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

/*
 * Redefine the macros from soc_system.h into shorter macros and more useful
 * values that we can use directly in the devicetree definition.
 */
#define JTAG_UART_BASE          HPS_0_ARM_A9_0_JTAG_UART_BASE
#define JTAG_UART_SPAN          HPS_0_ARM_A9_0_JTAG_UART_SPAN
#define JTAG_UART_IRQ           (HPS_0_JTAG_UART_IRQ + 72 - 32)

#define SYSID_QSYS_BASE         HPS_0_ARM_A9_0_SYSID_QSYS_BASE
#define SYSID_QSYS_SPAN         HPS_0_ARM_A9_0_SYSID_QSYS_SPAN

#define LED_PIO_BASE            HPS_0_ARM_A9_0_LED_PIO_BASE
#define LED_PIO_SPAN            HPS_0_ARM_A9_0_LED_PIO_SPAN
#define LED_PIO_WIDTH           HPS_0_ARM_A9_0_LED_PIO_DATA_WIDTH

#define DIPSW_PIO_BASE          HPS_0_ARM_A9_0_DIPSW_PIO_BASE
#define DIPSW_PIO_SPAN          HPS_0_ARM_A9_0_DIPSW_PIO_SPAN
#define DIPSW_PIO_IRQ           (HPS_0_DIPSW_PIO_IRQ + 72 - 32)
#define DIPSW_PIO_WIDTH         HPS_0_ARM_A9_0_DIPSW_PIO_DATA_WIDTH

#define BUTTON_PIO_BASE         HPS_0_ARM_A9_0_BUTTON_PIO_BASE
#define BUTTON_PIO_SPAN         HPS_0_ARM_A9_0_BUTTON_PIO_SPAN
#define BUTTON_PIO_IRQ          (HPS_0_BUTTON_PIO_IRQ + 72 - 32)
#define BUTTON_PIO_WIDTH        HPS_0_ARM_A9_0_BUTTON_PIO_DATA_WIDTH

#define ILC_BASE                HPS_0_ARM_A9_0_ILC_BASE
#define ILC_SPAN                HPS_0_ARM_A9_0_ILC_SPAN

&base_fpga_region {

        external-fpga-config;

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

        JTAG_UART: JTAG_UART@JTAG_UART_BASE {
                compatible = "altr,juart-1.0";
                reg = <JTAG_UART_BASE JTAG_UART_SPAN>;
                interrupt-parent = <&intc>;
                interrupts = <0 JTAG_UART_IRQ IRQ_TYPE_LEVEL_HIGH>;
        };

        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;
        };

        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>;
        };

        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>;
        };

        ILC: ILC@ILC_BASE {
                compatible = "altr,ilc-1.0";
                reg = <ILC_BASE ILC_SPAN>;
                interrupt-parent = <&intc>;
                interrupts = <
                        0       DIPSW_PIO_IRQ   IRQ_TYPE_LEVEL_HIGH
                        0       BUTTON_PIO_IRQ  IRQ_TYPE_LEVEL_HIGH
                        0       JTAG_UART_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_cv_fpga_overlay.dtb

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

arch/arm/boot/dts/my_cv_fpga_overlay.dts:46.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_cv_fpga_overlay.dts:40.19-131.3:
Warning (avoid_default_addr_size): /fragment@0/__overlay__: Relying on default
#address-cells value

arch/arm/boot/dts/my_cv_fpga_overlay.dts:40.19-131.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_cv_fpga_overlay.dtb
./arch/arm/boot/dts/my_cv_fpga_overlay.dtb

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

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

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

root@cyclone5:~# mkdir -p /lib/firmware
root@cyclone5:~# mv my_cv_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@cyclone5:~# mkdir /sys/kernel/config/device-tree/overlays/my-cv-fpga-overlay
root@cyclone5:~# ls /sys/kernel/config/device-tree/overlays/my-cv-fpga-overlay
dtbo    path    status
root@cyclone5:~# cat /sys/kernel/config/device-tree/overlays/my-cv-fpga-overlay/status
unapplied
root@cyclone5:~# echo my_cv_fpga_overlay.dtb \
> /sys/kernel/config/device-tree/overlays/my-cv-fpga-overlay/path
root@cyclone5:~# cat /sys/kernel/config/device-tree/overlays/my-cv-fpga-overlay/status
applied

Once this overlay is applied to the main system devicetree, you should see the FPGA LEDs on the Cyclone V 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@cyclone5:~# echo 1 > /sys/class/leds/fpga_led0/brightness
root@cyclone5:~# echo 0 > /sys/class/leds/fpga_led0/brightness

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

root@cyclone5:~# cat /sys/devices/platform/soc/soc:base-fpga-region/fpga_region/region0/\
ff260008.SYSID_QSYS/sysid/id
2899645696
root@cyclone5:~# cat /sys/devices/platform/soc/soc:base-fpga-region/fpga_region/region0/\
ff260008.SYSID_QSYS/sysid/timestamp
1634937165 (2021-10-22 21:12:45 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@cyclone5:~# rmdir /sys/kernel/config/device-tree/overlays/my-cv-fpga-overlay

Main system devicetree integration method

Create a new file called arch/arm/boot/dts/my_cv_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_cv_fpga.dtsi
/Td6WFoAAATm1rRGAgAhARwAAAAQz1jM4AzFA29dABeKfUvNK1NbzTI+B3OUEJMYagjnn0bslkyF
7xuB8nrKCzWcgqNMVnytO8kU434lb6O/lVpXis+nN95L3vIYy31eBXri2sCU9X79+IjTe9hFFxeb
b5e8rZBgRatgpk5FffiRkOT0gv5u0ZDQ6J+oWnFo3At5rq3su9QrhQLRGqbE8LdF0F6U5DtRFg5Z
jMR6QB7HIpWH7Dj7I4s97sVUDU+BqXAXJUIpBaB900l8ymiDbIoY5KAtR0Sor/UQQa+J/9dPfYsA
zjzBOgi9D8o0NoEc6OZ3Z1y2JVD4LMP910g2mivpyUzf55BmQYPqEGgEJkKSge5PlC2EFhkzgK2w
KgMfShVrfshvCg7QPTt+4xZNEGaYVedYT7ayVp0IZirFtvzazKI3WyZdziRdLo20MkgXlmH7uGAK
sfbuRb7HB8U3buGCRvwUPLbICSry6SLrBHTFrAEBJRRbjy4HMYiBcTutkSDeeVT0wQ+zbu8NqBs0
4+zThajblIq4bS4SS6f7LtsT8XOUNBmzkIAQqq0WHJSS6KDUrdq/GdhPCjiy4RybjRMLg1r+JhTm
1pr27exH0adwXXz4nRGBu87veFCjLmefjJdES8M7KE9qm1UZ98OUQ3C3IswWwzkUyLsrkrRX4tjY
nn/2Y+Cj9JA1hShOMvzyCuDxw86U2aJKe8ZHt4uwiNctEyZhyW3MzHD7/Z+wTSsgTxk7CHxCAsTt
eATWZbFBYbYNr6j4/R9Pw2IBt5WxpkB4STlyYspRC8Zu856qdVTK4uF1T/VzOmPg6hCyGMdClxBE
jJd9h06zNgAqv4OFQQewJuat63AlCH8qSQr/+oCCgyGlQ2KIK2x3LeJFV4cSrsFurw2tPy1pqnSO
GuGaEAoLiuB8mso1Xm7mJa6WrInoagE5Z0ddRoc/Dn6m1/wXQzelGYoxpGM0DSbPXVCyTsWBZZLE
ogA5IywNF4pNloL37Gy1amCJ2AlQOHAr0MpZkWMJIVarxcEwHtfmctQv3X4B+l7OFytHJYUMvVdx
e9Foc6KVoimSMxIbWYVaPW2lfZcnPpuAU9uqyQk/OAsOBROmEHFHDjBiXgEPNhuqKrD7K+KpwM8p
HH8PS/xFOQfkMMY/zR1LRpRed+Mnyy63HxAmbYxjVRBD+wsjg/5sB2pKb9ajaU+ZW3puQkXO7AAA
bSU3YA6xxfUAAYsHxhkAAPPF00WxxGf7AgAAAAAEWVo=
EOF

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

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

/*
 * Redefine the macros from soc_system.h into shorter macros and more useful
 * values that we can use directly in the devicetree definition.
 */
#define JTAG_UART_BASE          HPS_0_ARM_A9_0_JTAG_UART_BASE
#define JTAG_UART_SPAN          HPS_0_ARM_A9_0_JTAG_UART_SPAN
#define JTAG_UART_IRQ           (HPS_0_JTAG_UART_IRQ + 72 - 32)

#define SYSID_QSYS_BASE         HPS_0_ARM_A9_0_SYSID_QSYS_BASE
#define SYSID_QSYS_SPAN         HPS_0_ARM_A9_0_SYSID_QSYS_SPAN

#define LED_PIO_BASE            HPS_0_ARM_A9_0_LED_PIO_BASE
#define LED_PIO_SPAN            HPS_0_ARM_A9_0_LED_PIO_SPAN
#define LED_PIO_WIDTH           HPS_0_ARM_A9_0_LED_PIO_DATA_WIDTH

#define DIPSW_PIO_BASE          HPS_0_ARM_A9_0_DIPSW_PIO_BASE
#define DIPSW_PIO_SPAN          HPS_0_ARM_A9_0_DIPSW_PIO_SPAN
#define DIPSW_PIO_IRQ           (HPS_0_DIPSW_PIO_IRQ + 72 - 32)
#define DIPSW_PIO_WIDTH         HPS_0_ARM_A9_0_DIPSW_PIO_DATA_WIDTH

#define BUTTON_PIO_BASE         HPS_0_ARM_A9_0_BUTTON_PIO_BASE
#define BUTTON_PIO_SPAN         HPS_0_ARM_A9_0_BUTTON_PIO_SPAN
#define BUTTON_PIO_IRQ          (HPS_0_BUTTON_PIO_IRQ + 72 - 32)
#define BUTTON_PIO_WIDTH        HPS_0_ARM_A9_0_BUTTON_PIO_DATA_WIDTH

#define ILC_BASE                HPS_0_ARM_A9_0_ILC_BASE
#define ILC_SPAN                HPS_0_ARM_A9_0_ILC_SPAN

/ {
soc {

base-fpga-region {

        external-fpga-config;

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

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

        JTAG_UART: JTAG_UART@JTAG_UART_BASE,0 {
                compatible = "altr,juart-1.0";
                reg = <JTAG_UART_BASE 0 JTAG_UART_SPAN>;
                interrupt-parent = <&intc>;
                interrupts = <0 JTAG_UART_IRQ IRQ_TYPE_LEVEL_HIGH>;
        };

        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;
        };

        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>;
        };

        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>;
        };

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

};

}; // soc
}; // /

Edit the arch/arm/boot/dts/my_cv_top.dts file to include our new FPGA devicetree definition and add the FPGA LEDs to the existing leds node:

[]$ cat << EOF | base64 -d -i | xz -d | bash
/Td6WFoAAATm1rRGAgAhARwAAAAQz1jM4AHFAM5dADmZSuojhxSi3Mv8MfjO12CEtsMK+7liVcns
z5YLtM3IyUrqx0d48jihm/tdVvlUyR6grFm5a+mltdg1MSvyq/mmKzkEi8I2mPVYZRTtf/C6KIlJ
NVnVjJmXDmM+tyTqC2LZ+YvcFgYv0Ga4nev3Tz/IUKQNCsHpZaRIeA3wxXyux6Aq1+aBo3ZG608u
c3dmmnQvkKHbwwBMQ0nGuCcOiclQjwEWReS/LVbQav+6v/PS+RNwJ3yMnM2kCPImsR94Zmp38lxq
WrrrwUZ+M90AAAAApncUa296PRIAAeoBxgMAAArKihixxGf7AgAAAAAEWVo=
EOF

set -x
sed \
-i.bak \
-e '/#include "socfpga_cyclone5.dtsi"/a #include "my_cv_fpga.dtsi"' \
-e '/compatible = "gpio-leds";/a \
\
                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>;\
                };\
' \
./arch/arm/boot/dts/my_cv_top.dts

Build the devicetree:

[]$ make my_cv_top.dtb

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

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

Copy the new system DTB over to the target:

[]$ scp ./arch/arm/boot/dts/my_cv_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@cyclone5:~# mount /dev/mmcblk0p1 /mnt
root@cyclone5:~# mv my_cv_top.dtb /mnt/socfpga_cyclone5_socdk.dtb

Now reboot the target:

root@cyclone5:~# 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@cyclone5:~# find /sys \
-name "*SYSID*" -o \
-name "*PIO*" -o \
-name "*JTAG*" -o \
-name "*ILC*" | \
sort
/sys/bus/platform/devices/ff260000.JTAG_UART
/sys/bus/platform/devices/ff260008.SYSID_QSYS
/sys/bus/platform/devices/ff260040.LED_PIO
/sys/bus/platform/devices/ff260080.DIPSW_PIO
/sys/bus/platform/devices/ff2600c0.BUTTON_PIO
/sys/bus/platform/devices/ff270000.ILC
/sys/bus/platform/drivers/altera_gpio/ff260040.LED_PIO
/sys/bus/platform/drivers/altera_gpio/ff260080.DIPSW_PIO
/sys/bus/platform/drivers/altera_gpio/ff2600c0.BUTTON_PIO
/sys/bus/platform/drivers/altera_ilc/ff270000.ILC
/sys/bus/platform/drivers/altera_sysid/ff260008.SYSID_QSYS
/sys/devices/platform/soc/soc:base-fpga-region/fpga_region/region0/ff260000.JTAG_UART
/sys/devices/platform/soc/soc:base-fpga-region/fpga_region/region0/ff260008.SYSID_QSYS
/sys/devices/platform/soc/soc:base-fpga-region/fpga_region/region0/ff260040.LED_PIO
/sys/devices/platform/soc/soc:base-fpga-region/fpga_region/region0/ff260080.DIPSW_PIO
/sys/devices/platform/soc/soc:base-fpga-region/fpga_region/region0/ff2600c0.BUTTON_PIO
/sys/devices/platform/soc/soc:base-fpga-region/fpga_region/region0/ff270000.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__/JTAG_UART
/sys/firmware/devicetree/base/__symbols__/LED_PIO
/sys/firmware/devicetree/base/__symbols__/SYSID_QSYS
/sys/firmware/devicetree/base/soc/base-fpga-region/BUTTON_PIO@0xff2600c0,0
/sys/firmware/devicetree/base/soc/base-fpga-region/DIPSW_PIO@0xff260080,0
/sys/firmware/devicetree/base/soc/base-fpga-region/ILC@0xff270000,0
/sys/firmware/devicetree/base/soc/base-fpga-region/JTAG_UART@0xff260000,0
/sys/firmware/devicetree/base/soc/base-fpga-region/LED_PIO@0xff260040,0
/sys/firmware/devicetree/base/soc/base-fpga-region/SYSID_QSYS@0xff260008,0

You can find similar evidence in the procfs as well:

root@cyclone5:~# 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@0xff2600c0,0
/proc/device-tree/soc/base-fpga-region/DIPSW_PIO@0xff260080,0
/proc/device-tree/soc/base-fpga-region/ILC@0xff270000,0
/proc/device-tree/soc/base-fpga-region/JTAG_UART@0xff260000,0
/proc/device-tree/soc/base-fpga-region/LED_PIO@0xff260040,0
/proc/device-tree/soc/base-fpga-region/SYSID_QSYS@0xff260008,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/name
/proc/device-tree/soc/base-fpga-region/phandle
/proc/device-tree/soc/base-fpga-region/ranges

Notes about peripherals in this Cyclone V SoC GSRD example

In this version of the GSRD, the JTAG_UART driver is not enabled so you cannot expect to interact with that device even after we enable it in the devicetree:

root@cyclone5:~# cat /proc/config.gz | gunzip | grep JTAGUART
# CONFIG_SERIAL_ALTERA_JTAGUART is not set

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@cyclone5:~# dmesg | grep ilc
[    5.982297] altera_ilc ff270000.ILC: Failed to register interrupt handler
[    5.989089] altera_ilc ff270000.ILC: Failed to register interrupt handler
[    5.996044] altera_ilc ff270000.ILC: Driver successfully loaded