The Enclustra Build Environment (EBE) uses U-Boot as the bootloader for Linux. Apart from booting Linux, some additional features were added to U-Boot to support active storage device selection for modules that share the same pins on the SoC for several memory devices (for example Mercury ZX1, Mars ZX3, Mercury ZX5, Mars MA3, Mercury+ AA1, Mercury SA1), or to support configuration of certain on-board circuits (for example configuration of the MGT multiplexers on the Cosmos XZQ10 system board). U-Boot provides a command line interface which allows access to all memory devices and peripherals. Note that this section is not valid for Mercury+ AA1 modules because it uses the U-Boot bootloader generated by Intel tools, configured to include additional commands to switch the active storage.
The following trees show the folder structure starting from top level directory (bsp-xilinx or bsp-altera) of the Enclustra Build Environment (EBE). All paths and files mentioned in this U-Boot section are shown below.
└── bsp-altera/
└── sources
├── altera-linux
├── buildroot-rootfs
└── altera-uboot
└── configs
│ ├── socfpga_cyclone5_mars_ma3_defconfig
│ ├── socfpga_cyclone5_mercury_sa1_defconfig
│ ├── socfpga_cyclone5_mercury_sa1_rev3_defconfig
│ ├── socfpga_env_on_sd.appendix
│ ├── socfpga_env_on_emmc.appendix
│ └── socfpga_env_on_qspi.appendix
├── arch
│ └── arm
│ └── dts
│ ├── socfpga_cyclone5_mars_ma3.dts
│ └── socfpga_cyclone5_mercury_sa1.dts
├── tools
│ └── mkimage
├── Makefile
├── Kconfig
└── u-boot
└── bsp-xilinx/
└── sources
├── xilinx-linux
├── buildroot-rootfs
└── xilinx-uboot
└── configs
│ ├── zynq_cosmos_xzq10_defconfig
│ ├── zynq_mars_zx2_defconfig
│ ├── zynq_mars_zx3_defconfig
│ ├── zynq_mercury_defconfig
│ ├── enclustra_zynqmp_mars_xu3_defconfig
│ ├── enclustra_zynqmp_mercury_xu1_defconfig
│ ├── enclustra_zynqmp_mercury_xu5_defconfig
│ ├── enclustra_zynqmp_mercury_xu7_defconfig
│ ├── enclustra_zynqmp_mercury_xu8_defconfig
│ ├── enclustra_zynqmp_mercury_xu9_defconfig
│ ├── enclustra_env_on_nand.appendix
│ ├── enclustra_env_on_sd_zynq.appendix
│ ├── enclustra_env_on_sd_zynqmp.appendix
│ ├── enclustra_env_on_emmc.appendix
│ └── enclustra_env_on_qspi.appendix
├── arch
│ └── arm
│ └── dts
│ ├── zynqmp_enclustra_common.dtsi
│ ├── zynqmp_enclustra_mars_eb1.dtsi
│ ├── zynqmp_enclustra_mars_st3.dtsi
│ ├── zynqmp_enclustra_mars_xu3.dtsi
| ├── MA-XU3-2CG-1E-D10.dtsi
| ├── MA-XU3-2EG-1I-D10.dtsi
| ├── MA-XU3-3EG-2I-D11.dtsi
│ ├── zynqmp_enclustra_mercury_pe1.dtsi
│ ├── zynqmp_enclustra_mercury_st1.dtsi
│ ├── zynqmp_enclustra_mercury_xu1.dtsi
| ├── ME-XU1-15EG-1E-D12E-G1.dtsi
| ├── ME-XU1-15EG-2I-D12E.dtsi
| ├── ME-XU1-15EG-2I-D12E-G1.dtsi
| ├── ME-XU1-6CG-1E-D11E.dtsi
| ├── ME-XU1-6CG-1E-D11E-G1.dtsi
| ├── ME-XU1-6EG-1I-D11E.dtsi
| ├── ME-XU1-6EG-1I-D11E-G1.dtsi
| ├── ME-XU1-9EG-1E-D11E-G1.dtsi
| ├── ME-XU1-9EG-2I-D12E.dtsi
| ├── ME-XU1-9EG-2I-D12E-G1.dtsi
| ├── ME-XU1-9EG-3E-D12E.dtsi
│ ├── zynqmp_enclustra_mercury_xu5.dtsi
| ├── ME-XU5-2CG-1E-D10H.dtsi
| ├── ME-XU5-2EG-1I-D11E.dtsi
| ├── ME-XU5-3EG-2I-D11E.dtsi
| ├── ME-XU5-4CG-1E-D11E-G1.dtsi
| ├── ME-XU5-4EV-1I-D11E.dtsi
| ├── ME-XU5-4EV-1I-D11E-G1.dtsi
| ├── ME-XU5-5EV-1E-D11E.dtsi
| ├── ME-XU5-5EV-2I-D12E.dtsi
| ├── ME-XU5-5EV-2I-D12E-G1.dtsi
| ├── ME-XU5-5EV-3E-D13E.dtsi
│ ├── zynqmp_enclustra_mercury_xu7.dtsi
| ├── ME-XU7-15EG-2I-D12E.dtsi
| ├── ME-XU7-6EG-1I-D11E.dtsi
| ├── ME-XU7-9EG-2I-D12E.dtsi
│ ├── zynqmp_enclustra_mercury_xu8.dtsi
| ├── ME-XU8-4CG-1E-D11E.dtsi
| ├── ME-XU8-5EV-1I-D12E.dtsi
| ├── ME-XU8-7EV-1E-D11E.dtsi
| ├── ME-XU8-7EV-2I-D12E.dtsi
│ ├── zynqmp_enclustra_mercury_xu9.dtsi
| ├── ME-XU9-4CG-1E-D11E.dtsi
| ├── ME-XU9-5EV-1I-D12E-L11.dtsi
| ├── ME-XU9-7EV-2I-D12E-L11.dtsi
│ ├── zynqmp-enclustra-qspi-15.dtsi
│ ├── zynqmp-enclustra-qspi-2_3_4_5.dtsi
│ ├── zynqmp-enclustra-qspi-6_9.dtsi
│ ├── zynqmp-enclustra-qspi-7.dtsi
│ ├── zynq_enclustra_common.dtsi
│ ├── zynq_enclustra_cosmos_xzq10.dtsi
│ ├── CO-XZQ10-111-I.dtsi
│ ├── CO-XZQ10-262-I.dtsi
│ ├── CO-XZQ10-740-I.dtsi
│ ├── CO-XZQ10-750-I.dtsi
│ ├── zynq_enclustra_mars_eb1.dtsi
│ ├── zynq_enclustra_mars_pm3.dtsi
│ ├── zynq_enclustra_mars_st3.dtsi
│ ├── zynq_enclustra_mars_zx2.dtsi
| ├── MA-ZX2-10-2I-D9.dtsi
| ├── MA-ZX2-20-2I-D9.dtsi
│ ├── zynq_enclustra_mars_zx3.dtsi
| ├── MA-ZX3-20-1C-D9.dtsi
| ├── MA-ZX3-20-2I-D10.dtsi
│ ├── zynq_enclustra_mercury_pe1.dtsi
│ ├── zynq_enclustra_mercury_st1.dtsi
│ ├── zynq_enclustra_mercury_zx1.dtsi
| ├── ME-ZX1-30-2I-D10.dtsi
| ├── ME-ZX1-35-1I-D10.dtsi
| ├── ME-ZX1-45-2I-D10-P.dtsi
│ ├── zynq_enclustra_mercury_zx5.dtsi
| ├── ME-ZX5-15-2I-D10.dtsi
| ├── ME-ZX5-30-1I-D10.dtsi
| ├── ME-ZX5-30-3C-D10.dtsi
│ ├── zynq_enclustra_nand_parts.dtsi
│ ├── zynq-enclustra-qspi-10_15_20.dtsi
│ ├── zynq-enclustra-qspi-30.dtsi
│ ├── zynq-enclustra-qspi-35_45.dtsi
│ └── zynq_enclustra_qspi_parts.dtsi
├── tools
│ └── mkimage
├── Makefile
├── Kconfig
└── u-boot
U-Boot can be customized similarly to the Linux kernel (see section 3.2) or Buildroot (see section 4.3). The U-Boot sources can be found in the <path_to_build_environment>/sources/xilinx-uboot/ or <path_to_build_environment>/sources/altera-uboot/ directory depending on the vendor of the SoC present on the target module. The configuration menu can be started by navigating to the U-Boot source directory and typing the following line:
make menuconfig
See section 3.2 for more information about the configuration menu. After the configuration was saved, the entire U-Boot configuration is stored in the .config file located in the U-Boot source directory.
The initial configuration for U-Boot is stored in defconfig files. All defconfig files can be found in the <path_to_build_environment>/sources/xilinx-uboot/configs directory or the <path_to_build_environment>/sources/altera-uboot/configs directory. The following list shows all defconfig files used in the Enclustra build environment for the Enclustra SoC modules. In case of the Xilinx modules, EBE will generate a config file by combining several config files into one (enclustra_ebe_generated_defconfig) depending on the boot mode and module settings. The basis is the default Xilinx U-Boot config, xilinx_zynqmp_virt_defconfig and xilinx_zynq_virt_defconfig respectively.
| Xilinx Zynq-7000 SoC | |
|---|---|
| zynq_cosmos_xzq10_defconfig | Default settings for Cosmos XZQ10 |
| zynq_mars_zx2_defconfig | Default settings for Mars ZX2 |
| zynq_mars_zx3_defconfig | Default settings for Mars ZX3 |
| zynq_mercury_defconfig | Default settings for Mercury ZX1 and ZX5 |
| Xilinx Zynq Ultrascale+ MPSoC | |
|---|---|
| enclustra_zynqmp_mars_xu3_defconfig | Default settings for Mars XU3 |
| enclustra_zynqmp_mercury_xu1_defconfig | Default settings for Mercury+ XU1 |
| enclustra_zynqmp_mercury_xu5_defconfig | Default settings for Mercury XU5 |
| enclustra_zynqmp_mercury_xu7_defconfig | Default settings for Mercury+ XU7 |
| enclustra_zynqmp_mercury_xu8_defconfig | Default settings for Mercury+ XU8 |
| enclustra_zynqmp_mercury_xu9_defconfig | Default settings for Mercury+ XU9 |
| Intel SoC | |
|---|---|
| socfpga_cyclone5_mars_ma3_defconfig | Default settings for Mars MA3 |
| socfpga_cyclone5_mercury_sa1_defconfig | Default settings for Mercury SA1 R1-R2 and Mercury+ SA2 |
| socfpga_cyclone5_mercury_sa1_rev3_defconfig | Default settings for Mercury SA1 R3 |
Starting with release 1.8 of the EBE, the U-Boot environment is stored on the same storage as the target boot device. In order to be able to store the U-Boot environment on the selected boot memory, additional configuration parameters were added to the above mentioned defconfig files. These parameters are stored in the following files, which can be found in the same directory as the defconfig files.
| Xilinx SoC | |
|---|---|
| enclustra_env_on_nand.appendix | Settings to store environment on NAND flash |
| enclustra_env_on_sd_zynq.appendix | Settings to store environment on SD card for zynq |
| enclustra_env_on_sd_zynqmp.appendix | Settings to store environment on SD card for zynqmp |
| enclustra_env_on_emmc.appendix | Settings to store environment on eMMC memory |
| enclustra_env_on_qspi.appendix | Settings to store environment on QSPI flash |
| Intel SoC | |
|---|---|
| socfpga_env_on_sd.appendix | Settings to store environment on SD card |
| socfpga_env_on_emmc.appendix | Settings to store environment on eMMC memory |
| socfpga_env_on_qspi.appendix | Settings to store environment on QSPI flash |
If needed, new files containing the desired configuration can be created. Because U-Boot keeps a specific order for the settings in the defconfig files, it should be avoided to modify a defconfig file by hand. The following command can be used to generate a defconfig file using the current U-Boot configuration.
make savedefconfig
This section explains how to build the U-Boot binary files without using the build script of the Enclustra build environment.
Prepare environment
Before the binary can be built, the environment needs to be prepared accordingly. The following code shows the needed preparation depending on the architecture of the target module.
For Intel SoC or Xilinx Zynq-7000 SoC:
cd <path_to_build_environment>
export PATH=$PATH:$(pwd)/bin/arm−none−linux−gnueabi−static/bin/
export ARCH=arm
export CROSS_COMPILE=arm−none−linux−gnueabi−
For Xilinx Zynq Ultrascale+ MPSoC:
cd <path_to_build_environment>
export PATH=$PATH:$(pwd)/bin/aarch64−none−linux−gnueabi/bin/
export PATH=$PATH:$(pwd)/bin/arm−none−linux−gnueabi−static/bin/
export ARCH=arm64
export CROSS_COMPILE=aarch64−none−linux−gnueabi−
export CROSS32CC=arm−none−linux−gnueabi−gcc
Generate defconfig
If the defconfig files mentioned in section 2.3.1 are used, the storage target for the environment needs to be added to the modules defconfig file before building the U-Boot binary. The following commands can be used to generate the new defconfig file enclustra_defconfig, which is used in the next step below.
For Intel SoC
cd <path_to_build_environment>/sources/altera−uboot/configs
cat <name_of_corresponding_defconfig_file> socfpga_env_on_<boot_target>.appendix > enclustra_defconfig
For Xilinx SoC
cd <path_to_build_environment>/sources/xilinx−uboot/configs
cat <name_of_corresponding_defconfig_file> enclustra_env_on_<boot_target>.appendix > enclustra_defconfig
Build U-Boot binary
To build the U-Boot binary, the following command needs to be executed in the U-Boot source directory.
For Intel Cyclone V SoC:
cd <path_to_build_environment>/sources/altera−uboot
make enclustra_defconfig
make
For Xilinx SoC
cd <path_to_build_environment>/sources/xilinx−uboot
make enclustra_defconfig
make
If the build was successful, the newly generated U-Boot binary can be found in the U-Boot source directory.
U-Boot provides the option to configure its devices using a device tree instead of a static configuration. The used device tree source files use the same syntax as the device tree files used for the Linux kernel (see section 3.5).
In contrast to the Linux kernel, U-Boot embeds the device tree binary in its image (CONFIG_OF_EMBED setting). The used device tree source file is set in the U-Boot configuration in CONFIG_DEFAULT_DEVICE_TREE setting.
The following lists show the device tree source files of all Enclustra SoC modules that are currently supported in the Enclustra build environment. All device tree source files are located in <path_to_build_environment>/sources/xilinx-uboot/arch/arm/dts or <path_to_build_environment>/sources/altera-uboot/arch/arm/dts directory depending on the SoC vendor.
In case of the Xilinx modules a final device tree is generated during the build from several seperate dtsi files. After the build a file called enclustra_generated.dts is in the <path_to_build_environment>/sources/xilinx-uboot/arch/arm/dts together with the corresponding dtb. The reason behind this is to seperate module specific and baseboard specific device tree entries to simplify the usage of Enclustra device trees with custom baseboards.
| Intel SoC | |
|---|---|
| Mars MA3 | socfpga_cyclone5_mars_ma3.dts |
| Mercury SA1 | socfpga_cyclone5_mercury_sa1.dts |
| Mercury+ SA2 | socfpga_cyclone5_mercury_sa1.dts |
| Xilinx Zynq-7000 SoC | |
|---|---|
| Common file for all SoC | zynq_enclustra_common.dtsi |
| Mars ZX2 | zynq_enclustra_mars_zx2.dtsi MA-ZX2-10-2I-D9.dtsi MA-ZX2-20-2I-D9.dtsi |
| Mars ZX3 | zynq_enclustra_mars_zx3.dtsi MA-ZX3-20-1C-D9.dtsi MA-ZX3-20-2I-D10.dtsi |
| Mercury ZX1 | zynq_enclustra_mercury_zx1.dtsi ME-ZX1-30-2I-D10.dtsi ME-ZX1-35-1I-D10.dtsi ME-ZX1-45-2I-D10-P.dtsi |
| Mercury ZX5 | zynq_enclustra_mercury_zx5.dtsi ME-ZX5-15-2I-D10.dtsi ME-ZX5-30-1I-D10.dtsi ME-ZX5-30-3C-D10.dtsi |
| Cosmos XZQ10 | zynq_enclustra_cosmos_xzq10.dtsi CO-XZQ10-111-I.dtsi CO-XZQ10-262-I.dtsi CO-XZQ10-740-I.dtsi CO-XZQ10-750-I.dtsi |
| Baseboard specific dtsi | |
|---|---|
| Mars EB1 | zynq_enclustra_mars_eb1.dtsi |
| Mars PM3 | zynq_enclustra_mars_pm3.dtsi |
| Mars ST3 | zynq_enclustra_mars_st3.dtsi |
| Mars ST3 | zynq_enclustra_mars_st3.dtsi |
| Mercury ST1 | zynq_enclustra_mercury_st1.dtsi |
| Mercury PE1 | zynq_enclustra_mercury_pe1.dtsi |
| Xilinx Zynq Ultrascale+ MPSoC | |
|---|---|
| Common file for all MPSoC | zynqmp_enclustra_common.dtsi |
| Mars XU3 | zynqmp_enclustra_mars_xu3.dtsi MA-XU3-2CG-1E-D10.dtsi MA-XU3-2EG-1I-D10.dtsi MA-XU3-3EG-2I-D11.dtsi |
| Mercury+ XU1 | zynqmp_enclustra_mercury_xu1.dtsi ME-XU1-15EG-1E-D12E-G1.dtsi ME-XU1-15EG-2I-D12E.dtsi ME-XU1-15EG-2I-D12E-G1.dtsi ME-XU1-6CG-1E-D11E.dtsi ME-XU1-6CG-1E-D11E-G1.dtsi ME-XU1-6EG-1I-D11E.dtsi ME-XU1-6EG-1I-D11E-G1.dtsi ME-XU1-9EG-1E-D11E-G1.dtsi ME-XU1-9EG-2I-D12E.dtsi ME-XU1-9EG-2I-D12E-G1.dtsi ME-XU1-9EG-3E-D12E.dtsi |
| Mercury XU5 | zynqmp_enclustra_mercury_xu5.dtsi ME-XU5-2CG-1E-D10H.dtsi ME-XU5-2EG-1I-D11E.dtsi ME-XU5-3EG-2I-D11E.dtsi ME-XU5-4CG-1E-D11E-G1.dtsi ME-XU5-4EV-1I-D11E.dtsi ME-XU5-4EV-1I-D11E-G1.dtsi ME-XU5-5EV-1E-D11E.dtsi ME-XU5-5EV-2I-D12E.dtsi ME-XU5-5EV-2I-D12E-G1.dtsi ME-XU5-5EV-3E-D13E.dtsi |
| Mercury+ XU7 | zynqmp_enclustra_mercury_xu7.dtsi ME-XU7-15EG-2I-D12E.dtsi ME-XU7-6EG-1I-D11E.dtsi ME-XU7-9EG-2I-D12E.dtsi |
| Mercury+ XU8 | zynqmp_enclustra_mercury_xu8.dtsi ME-XU8-4CG-1E-D11E.dtsi ME-XU8-5EV-1I-D12E.dtsi ME-XU8-7EV-1E-D11E.dtsi ME-XU8-7EV-2I-D12E.dtsi |
| Mercury+ XU9 | zynqmp_enclustra_mercury_xu9.dtsi ME-XU9-4CG-1E-D11E.dtsi ME-XU9-5EV-1I-D12E-L11.dtsi ME-XU9-7EV-2I-D12E-L11.dtsi |
| Baseboard specific dtsi | |
|---|---|
| Mars EB1 | zynqmp_enclustra_mars_eb1.dtsi |
| Mars ST3 | zynqmp_enclustra_mars_st3.dtsi |
| Mars ST3 | zynqmp_enclustra_mars_st3.dtsi |
| Mercury ST1 | zynqmp_enclustra_mercury_st1.dtsi |
| Mercury PE1 | zynqmp_enclustra_mercury_pe1.dtsi |
After a valid boot image has been created and loaded to the desired storage device for the Enclustra module, the user can have access to the U-Boot command line interface on the module.
The U-Boot command line interface can be entered during booting by pressing any key while Hit any key to stop autoboot is output. By default the wait time is set to 2 seconds. To disable command line interface access and to decrease boot time, the wait time can be set to zero. This can be changed either by changing the environment variable bootdelay or in the configuration menu by changing the setting delay in seconds before automatically booting.
The available commands in the command line interface depend on the configuration. To see all enabled commands, check the Command line interface submenu in the configuration menu (see section 2.3).
Environment variables are used to store various settings. For example the IP address of the module is stored in the ipaddr variable. Furthermore, U-Boot provides the ability to store commands in environment variables. The environment is always stored on the boot partition of the selected boot memory or at a certain offset of the selected boot memory. If no stored environment is present, U-Boot loads its default configuration.
The following command can be used to store the current environment if additional variables were added or existing variables were changed:
saveenv
The following command can be used to load the default configuration. Note that the stored environment is not affected by this command:
env default
To print the content of an environment variable, the following command needs to be used. If only printenv is executed without any option, all existing variables are printed:
printenv <variable>
An environment variable can be set by:
setenv <variable> <value>
To delete an existing environment variable:
setenv <variable>
Multiple commands can be stored in a variable, separated by a ;. To set the commands and run them use:
setenv <variable> <command1>\;<command2>\;<command3>
run <variable>
The commands for booting Linux are always stored in the bootcmd environment variable. In the Enclustra build environment this executes the boot script (see section 2.7). To boot Linux from the command line interface, the following command can be used:
run bootcmd
To boot Linux, U-Boot executes the script uboot.scr located on the boot partition. This script contains all needed commands for booting. To be able to execute the script in U-Boot, the script source file must be converted to an image file using the mkimage tool. The mkimage tool is built during the U-Boot build and can be found in the <path_to_build_environment>/sources/xilinx-uboot/tools or the <path_to_build_environment>/sources/altera-uboot/tools directory. It can also be installed independently (e.g. it is included in u-boot-tools package in Ubuntu).
All used boot script sources can be found in the <path_to_build_environment>/sources/xilinx-uboot/bscripts or the <path_to_build_environment>/sources/altera-uboot/additional_bootscripts directory depending on the SoC vendor of the target module.
The following lists show all used boot scripts and their application. The boot scripts can be modified if additional commands need to be executed before Linux is booting. Section 2.7.1 shows how the boot script can be built outside of the Enclustra build environment or how additional U-Boot scripts can be generated.
| Modules equipped with Xilinx Zynq-7000 SoC | |
|---|---|
| mmcboot-ramdisk | MMC boot with rootfs only in RAM |
| mmcboot-rootfs | MMC boot with persistent rootfs |
| nandboot-rootfs | NAND boot with persistent rootfs |
| netboot-rootfs | NET boot with persistent rootfs |
| qspiboot-persistent | QSPI boot with persistent rootfs |
| qspiboot-ramdisk | QSPI boot with rootfs only in RAM |
| usbboot-ramdisk | USB boot with rootfs only in RAM |
| Modules equipped with Xilinx Zynq Ultrascale+ MPSoC | |
|---|---|
| mmcboot-ramdisk-us | MMC/eMMC boot with rootfs only in RAM |
| mmcboot-rootfs-us | MMC/eMMC boot with persistent rootfs |
| netboot-rootfs-us | NET boot with persistent rootfs |
| qspiboot-mmc-us | QSPI boot with persistent rootfs |
| qspiboot-ramdisk-us | QSPI boot with rootfs only in RAM |
| usbboot-ramdisk-us | USB boot with rootfs only in RAM |
| Modules equipped with Intel Cyclone V SoC | |
|---|---|
| ma3-qspiboot | QSPI boot with persistent rootfs, only for Mars MA3 |
| ma3-qspiramdiskboot | QSPI boot with rootfs only in RAM, only for Mars MA3 |
| mmcboot | MMC/eMMC boot with persistent rootfs |
| mmcboot-ramdisk | MMC/eMMC boot with rootfs only in RAM |
| netboot | NET boot with persistent rootfs |
| qspiboot | QSPI boot with persistent rootfs |
| qspiramdiskboot | QSPI boot with rootfs only in RAM |
| usbboot | USB boot with persistent rootfs |
If custom commands need to be executed before Linux is booting, the boot scripts shown in section 2.7 can be modified. It is also possible to generate a script from scratch and execute it in U-Boot.
The following command can be used to generate an executable script custom_script.scr from the source file script_source.txt:
mkimage −T script −C none −n ”Custom script” −d script_source.txt custom_script.scr
As alternative to the default boot script, a script can be stored on the boot partition of the SD card and executed with following commands:
load mmc 0 <loadaddr> custom_script.scr
source <loadaddr>
If a script is stored in QSPI flash, it can be copied to RAM and executed with following commands:
sf probe
sf read <loadaddr> <customscript_qspi_address_offset> <customscript_size>
source <loadaddr>
Please continue reading Chapter 3 - Linux kernel.