Three methods applicable to the task of creating and editing Linux device trees targeting Altera® ( Intel® ) SoC FPGAs are presented.
Introduction.
The SoC FPGA Embedded Development Suite (SoC EDS) includes a dedicated tool for generating Linux device trees (device tree generator (sopc2dts)). If you do not meet the requirements for using sopc2dts, you will need to use a general method instead of using the supplied tool.
The documentation issued by the manufacturer also notes the following.
" Warning: The Linux Device Tree Generator is tested with and supports only the Linux
kernel version targeted by the associated GSRD. not recommended to use the
Linux Device Tree Generator if your design targets a different Linux kernel version.
Instead, it is recommended to manage theDevice Tree manually by using the Device
Tree files provided by the kernel as a baseline, and by adding the FPGA IP and board
information manually.. " [Adapted from Intel® SoC FPGA Embedded Development Suite User Guide ].
There are three applicable methods, including the common method used in Linux development.
- Method 1: Use the sopc2dts tool to create it.
- Method 2: Use the Linux source tree and create it with the make command.
- Method 3: Create and edit using dtc
Below are the steps and additional information for each method.
Method 1: Creation using the sopc2dts tool
First, we describe how to use the device tree generator (sopc2dts) included with SoC EDS. As stated at the beginning of this section, this method is not universal. Please understand the following requirements before using this method.
- Only the Linux kernel version applicable to the Linux reference environment (GSRD) provided with SoC EDS is applicable (for other versions, operation has not been confirmed. (Other versions have not been tested. Not all Linux versions are supported.)
- Only Cyclone® V / Arria® V / Arria® 10 ( Stratix® 10 and Agilex™ are not supported).
One advantage of this method is that device definitions for IP components on the FPGA side can be generated, but it should be noted that not all IP component definitions can be generated.
IP components that do not support device tree generation will generate device definitions with "compatible = "unknown, unknown-1.0";". If a driver for an unknown device requires a device tree, you must manually write a device tree source to accommodate it.
Reference: For more information on how to use sopc2dts, please also refer to the following page on Rocketboards.org.
Generating the Device Tree (for Cyclone® V / Arria® V)
Generating the Linux Device Tree (for Arria® 10)
1-1: Input File Preparation
There are two types of input files: .sopcinfo files generated by Platform Designer and .xml files containing board information. Prepare the required set of input files in a working directory.
The .sopcinfo file is generated under the target Quartus project.
The .xml file is not generated by the Quartus tool. Copy and use the .xml file in the Hardware Reference (GHRD) that shipped with your SoC EDS for the Development Kit. Depending on your device family, copy the appropriate .xml from the following location:
C:\intelFPGA\18.1\embedded\examples\hardware\cv_soc_devkit_ghrd
C:\intelFPGA\18.1\embedded\examples\hardware\av_soc_devkit_ghrd
C:\intelFPGA\18.1\embedded\examples\hardware\a10_soc_devkit_ghrd
The corresponding .xml file is as follows
| Device Family | Board Information (Board XML) |
| Cyclone® V SoC | soc_system_board_info.xml hps_common_board_info.xml |
| Arria® V SoC | ghrd_5astfd5k3_board_info.xml hps_common_board_info.xml |
| Arria® 10 SoC | hps_a10_common_board_info.xml hps_a10_devkit_board_info.xml ghrd_10as066n2_board_info.xml |
1-2: How to run sopc2dts
The work is done on the Embedded Command Shell; after launching the Shell, simply move the set of input files to the working directory provided and execute the sopc2dts command (also available on Windows).
To start the Shell, run embedded_command_shell.sh as shown in the example below on a Linux host, or click SoC EDS Command Shell from the Start menu on a Windows host.
$ ~/intelFPGA/18.1/embedded/embedded_command_shell.sh
1-3: sopc2dts Execution Example
The following are command line examples for generating device tree sources (.dts) and device tree blobs (.dtb), respectively. The .sopcinfo file specified in the --input option and the .xml file specified in the --board option vary depending on the project and device family, but the rest can be executed with similar specifications.
.dts and .dtb files are generated with the file name specified in --output.
Generate device tree source (.dts)
$ sopc2dts --input soc_system.sopcinfo\
--output socfpga.dts\
--type dts\
--board soc_system_board_info.xml\
--board hps_common_board_info.xml\
--bridge-removal all\
--clocks
Generate device tree blob (.dtb)
$ sopc2dts --input soc_system.sopcinfo\
--output socfpga.dtb\
--type dtb\
--board soc_system_board_info.xml\
--board hps_common_board_info.xml\
--bridge-removal all\
--clocks
Method 2: Using the Linux source tree and create it with the make command
The next method is to use the make command commonly used in Linux development. This method is most recommended because it generates the device tree based on the Linux source tree, so there is no need to worry about incompatibility between the generated device tree and the Linux kernel version.
This method is standard for Stratix® 10 SoC.
2-1: Prepare the cross-compiler (first time only)
To use this method, you must have a Linux source tree build environment. Specifically, install a cross-compiler for Arm target . This procedure is not necessary if the environment has already been built.
The following is an example of installing the cross compiler for arm linux published by Linaro (linaro.org).
$ cd ~
$ wget https://releases.linaro.org/components/toolchain/binaries/7.3-2018.05/arm-linux-gnueabihf/gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabihf.tar.xz
$ tar Jxf gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabihf.tar.xz
2-2: Preparation and configuration of Linux source tree
Prepare the Linux source tree separately. The following example assumes that the source tree has been extracted to sources/linux-socfpga-4.14.73-ltsi under the home directory.
After moving to the Top directory of the source tree, set up environment variables to specify the cross compiler (CROSS_COMPILE) and the architecture to be built (ARCH) (the cross compiler is described by the path as in the installation example in 2-1).
Then, run make clean and make socfpga_defconfig to have the default configuration for SoC FPGAs applied.
$ cd ~/sources/linux-socfpga-socfpga-4.14.73-ltsi
$ export CROSS_COMPILE=~/gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf-
$ export ARCH=arm
$ make clean
$ make socfpga_defconfig
2-3: make execution
The Linux source tree contains device tree sources (.dts and .dtsi) under the arch/arm/boot/dts directory. The difference between .dts and .dtsi is as follows
- .dts ... Device tree source body (device tree source for a specific board)
- .dtsi ... A partial definition of a device tree source. A file that is assumed to be included from other .dts/.dtsi files (often contains common definitions for a specific device).
The specified device tree blob (.dtb) is generated by executing make with a file name that replaces the extension of the specific .dts file with .dtb, as shown below.
Without specifying a specific file name You can also run make dtbs to generate device tree blobs (.dtb) for all device tree sources (.dts) targeting SoC FPGA devices.
Device trees with pre-sourced sources can be generated using either of the above methods.
2-4: (Supplemental) Creating an original device tree
By creating an original device tree source (.dts) based on the files provided under the Linux source tree (arch/arm/boot/dts), an original .dtb can also be created in the manner described in 2-3.
If you add the original .dts, you will also need to edit arch/arm/boot/dts/Makefile. Add the .dtb file generated from the newly added device tree source to the list of .dtb files listed in the red box below.
Method 3: Create and edit using dtc
The last method described uses the device tree compiler (dtc) included with SoC EDS. dtc allows inter-conversion of device tree sources (.dts) and device tree blobs (.dtb).
It can be used for the following purposes
- Converting .dts created/edited in text format to a format recognized by Linux (.dtb).
- Convert existing .dtb to .dts and check the contents (it is also possible to edit .dts and then convert it back to .dtb).
Notes:
This method is not applicable to multi-file device tree sources that include .dtsi. Please use Method 2 for sources with multiple file configurations.
3-1: Preparation
This method can be used by launching Embedded Command Shell; after launching Shell, simply navigate to the directory containing the device tree file (.dts or .dtb) and execute the dtc command (can also be used on Windows).
To launch the Shell, run embedded_command_shell.sh as shown in the example below in a Linux host environment, or click SoC EDS Command Shell from the Start menu in a Windows host environment.
$ ~/intelFPGA/18.1/embedded/embedded_command_shell.sh
3-2: dtc execution
Basically, dtc can be executed by specifying only three options and an input file. In the following format, specify the input/output file format (dts or dtb) in the -I and -O options and the output file name in the -o option.
$ dtc -I <input format> -O <output format> -o <output file> <input file>
Example command line for generating .dtb from .dts:
$ dtc -I dts -O dtb -o soc_system.dtb soc_system.dts
Example command line for generating .dts from .dtb:
$ dtc -I dtb -O dts -o soc_system.dts soc_system.dtb
3-3: (Supplemental) dtc help display
The dtc help display is also included for reference . Basically, you can use the two options listed in 3-2, but it seems that many other options are available in addition to the ones listed in 3-2. Please try them if necessary.
Conclusion
We have introduced three ways to generate/edit the device tree, The recommended method is to create a device tree based on the Linux source tree described in Method 2. It is up to the user to decide which method to use, but we recommend using Method 2 if you are unsure of your choice.