Mainline u-Boot for SoCFPGA

Building and customizing mainline u-Boot for SoCFPGA Platforms

General Info

u-Boot is an opensource bootloader with support for many platforms including the various SoCFPGA platforms which are in various stages of the mainlining process. For the most part, the Cyclone5/Arria5 and Arria10 platforms have been fully mainlined, but officially supported versions of u-boot are still hosted *HERE*. You can find documentation for officially supported u-boot versions in the Documentation section, or in the various Golden System Reference Design (GSRD) User Manuals documents.

Objectives

The objective of this guide is to walk through the process of customizing and building u-Boot for your hardware.

*Prerequisites *

• Some working knowledge of Git.
• Compiled Quartus project for your target hardware.
• A toolchain appropriate for the Cortex A9 or Cortex A53 processors
• A linux devicetree for your custom board

Documentation

• Denx u-Boot Documentation
• Denx u-Boot git source
• U-Boot mailing list
• HOWTO Create a Device Tree

Getting the source

Both linux and u-boot use git as a source control / development tool. The source is available either through git directly, or via http should you have firewall issues.

• git://git.denx.de/u-boot.git
• http://git.denx.de/u-boot.git

Using git directly is generally faster.

Clone u-Boot repo and select an appropriate tag

First we clone the repo

git clone git://git.denx.de/u-boot.git

Now we need to find an appropriate release tag to use.

cd u-boot
git tag
....
v2018.09-rc1
v2018.09-rc2
v2018.09-rc3
v2018.11
v2018.11-rc1
v2018.11-rc2
v2018.11-rc3
v2019.01
v2019.01-rc1
v2019.01-rc2
v2019.01-rc3
v2019.04
v2019.04-rc1
v2019.04-rc2
v2019.04-rc3
v2019.04-rc4
v2019.07-rc1
v2019.07-rc2
v2019.07-rc3
v2019.07-rc4
....

From the above we see that v2019.04 is the latest release and v2019.07 is on it's forth release candidate.

For this walk through we will use v2019.07-rc4 as it happens that the 2019.07 release includes support for Arria10.

git checkout -b v2019.07-rc4 v2019.07-rc4

Creating a Custom board

Although it is possible to modify the existing SoCFPGA board configurations in u-boot, a better approach is to add your own custom board configuration, The easiest method is to start with an existing board configuration that closely matches your own. Each device type (Cyclone5/Arria5, Arria10, Stratix10) will require different modifications for your specific board configuration, these are discussed in the device specific tabs.

The basic setup will require:

• Board specific defconfig
• Board specific header in include/configs
• Board specific devicetree (normally just copied from the linux devicetree with some u-boot additions)
• A directory and associated files in the boards directory
• Various modifications to Kconfig files

Aside from the Kconfig modifications, these can be copied off of existing boards.

For this example, we will create a new board called foo-board based on the cyclone5 socdk.

Imitating an existing board

We are copying from the cyclone5 socdk:

cp -a configs/socfpga_cyclone5_defconfig configs/socfpga_foo_board_defconfig
cp -a board/altera/cyclone5-socdk/ board/foo_board
cp -a arch/arm/dts/socfpga_cyclone5_socdk.dts arch/arm/dts/socfpga_cyclone5_foo_board.dts
cp arch/arm/dts/socfpga_cyclone5_socdk-u-boot.dtsi arch/arm/dts/socfpga_cyclone5_foo_board-u-boot.dtsi
cp -a include/configs/socfpga_cyclone5_socdk.h include/configs/socfpga_foo_board.h

Modifications for defconfig

Now we modify the defconfig to specify our new board and the new files we created.

vi configs/socfpga_foo_board_defconfig

We need to change the defconfig to match our new target and files:

CONFIG_ARM=y
CONFIG_ARCH_SOCFPGA=y
CONFIG_TARGET_SOCFPGA_CYCLONE5_SOCDK=y
CONFIG_DISTRO_DEFAULTS=y
CONFIG_FIT=y
# CONFIG_USE_BOOTCOMMAND is not set
CONFIG_SYS_CONSOLE_IS_IN_ENV=y
CONFIG_SYS_CONSOLE_OVERWRITE_ROUTINE=y
CONFIG_SYS_CONSOLE_ENV_OVERWRITE=y
CONFIG_DEFAULT_FDT_FILE="socfpga_cyclone5_socdk.dtb"
CONFIG_VERSION_VARIABLE=y
# CONFIG_DISPLAY_BOARDINFO is not set
CONFIG_DISPLAY_BOARDINFO_LATE=y
CONFIG_SPL_TEXT_BASE=0xFFFF0000
CONFIG_SPL_SPI_LOAD=y
CONFIG_CMD_ASKENV=y
CONFIG_CMD_GREPENV=y
CONFIG_CMD_DFU=y
# CONFIG_CMD_FLASH is not set
CONFIG_CMD_GPIO=y
CONFIG_CMD_I2C=y
CONFIG_CMD_MMC=y
CONFIG_CMD_SF=y
CONFIG_CMD_SPI=y
CONFIG_CMD_USB=y
CONFIG_CMD_USB_MASS_STORAGE=y
CONFIG_CMD_CACHE=y
CONFIG_CMD_EXT4_WRITE=y
CONFIG_MTDIDS_DEFAULT="nor0=ff705000.spi.0"
CONFIG_MTDPARTS_DEFAULT="mtdparts=ff705000.spi.0:1m(u-boot),256k(env1),256k(env2),14848k(boot),16m(rootfs),-@1536k(UBI)0"
CONFIG_CMD_UBI=y
# CONFIG_ISO_PARTITION is not set
# CONFIG_EFI_PARTITION is not set
CONFIG_DEFAULT_DEVICE_TREE="socfpga_cyclone5_socdk"
CONFIG_ENV_IS_IN_MMC=y
CONFIG_SPL_DM_SEQ_ALIAS=y
CONFIG_DFU_MMC=y
CONFIG_DM_GPIO=y
CONFIG_DWAPB_GPIO=y
CONFIG_DM_I2C=y
CONFIG_SYS_I2C_DW=y
CONFIG_DM_MMC=y
CONFIG_MMC_DW=y
CONFIG_MTD_DEVICE=y
CONFIG_SPI_FLASH=y
CONFIG_SPI_FLASH_MACRONIX=y
CONFIG_SPI_FLASH_SPANSION=y
CONFIG_SPI_FLASH_STMICRO=y
# CONFIG_SPI_FLASH_USE_4K_SECTORS is not set
CONFIG_PHY_MICREL=y
CONFIG_PHY_MICREL_KSZ90X1=y
CONFIG_DM_ETH=y
CONFIG_ETH_DESIGNWARE=y
CONFIG_MII=y
CONFIG_DM_RESET=y
CONFIG_SPI=y
CONFIG_CADENCE_QSPI=y
CONFIG_DESIGNWARE_SPI=y
CONFIG_USB=y
CONFIG_DM_USB=y
CONFIG_USB_DWC2=y
CONFIG_USB_GADGET=y
CONFIG_USB_GADGET_MANUFACTURER="altera"
CONFIG_USB_GADGET_VENDOR_NUM=0x0525
CONFIG_USB_GADGET_PRODUCT_NUM=0xa4a5
CONFIG_USB_GADGET_DWC2_OTG=y
CONFIG_USB_GADGET_DOWNLOAD=y

so from the above we change:

CONFIG_TARGET_SOCFPGA_CYCLONE5_SOCDK=y
CONFIG_DEFAULT_FDT_FILE="socfpga_cyclone5_socdk.dtb"
CONFIG_DEFAULT_DEVICE_TREE="socfpga_cyclone5_socdk"

to:

CONFIG_TARGET_SOCFPGA_FOO_BOARD=y
CONFIG_DEFAULT_FDT_FILE="socfpga_cyclone5_foo_board.dtb"
CONFIG_DEFAULT_DEVICE_TREE="socfpga_cyclone5_foo_board"

Modifying the mach-socfpga Kconfig

We now need to add the target to the SOCFPGA Kconfig, again we can just copy existing entries.

vi arch/arm/mach-socfpga/Kconfig

We need to make entries for board target, sys_board, sys_config_name, and optionally sys_vendor if a vendor directory was used in the board directory (IE: board/altera/cyclone5_socdk), which in our case it is not.

In the "Altera SOCFPGA board select" choice section add:

config TARGET_SOCFPGA_FOO_BOARD
        bool "Foo Board (Cyclone V)"
        select TARGET_SOCFPGA_CYCLONE5

In the SYS_BOARD section add:

default "socfpga_foo_board" if TARGET_SOCFPGA_FOO_BOARD

and in the SYS_CONFIG_NAME section add:

default "foo_board" if TARGET_SOCFPGA_FOO_BOARD

Add your board devicetree to the devicetree makefile

The Makefile in arch/arm/dts lists devicetrees to be compiled for each architecture. For SOCFPGA this list is in dtb-$(CONFIG_ARCH_SOCFPGA). Add our new boards devicetree to that list.

vi arch/arm/dts/Makefile

Add

      socfpga_cyclone5_foo_board.dtb                  \

Please note the trailing escape "\" and place it appropriately!

u-Boot Devicetree

The devicetree used in u-boot requires minimal additions to that in the linux devicetree. The modifications required are to indicate drivers that need Pre-Relocation Support as described in the driver-model README, and provide any u-boot specific configurations. The best method of doing this is using a dtsi file that the u-boot build flow will automatically add to your existing linux devicetree which we already copied from our Cyclone5 SoCDK reference (socfpga_cyclone5_socdk-u-boot.dtsi).

Please note that the devicetrees in use in u-boot are from the kernel source, and not output from sopc2dts. I will not cover the required changes to a sopc2dts generated devicetree and suggest following HOWTO Create a Device Tree for your devicetree creation. The HOWTO Create a Device Tree uses devicetree includes that are part of the kernel source, which is kept up to date with any changes in compatibility strings or parameters.

Devicetree modifications for u-boot

Devicetree bindings for u-boot are documented in the doc directory of the devicetree. Please refer to that documentation.

First, copy your linux devicetree over the devicetree copied from our mimic'ed board (in our case socfpga_cyclone5_foo_board.dtb in arch/arm/dts).

Modifications will only be to the {board devicetree name}-u-boot.dtsi we previously copied, and the likelihood is that very minimal changes will be required for your device. Please look at the *-u-boot.dtsi files from devices similar to yours.

Cyclone5/Arria5 u-boot.dtsi

For C5/A5, the u-boot devicetree include simply adds "u-boot,dm-pre-reloc;" to device nodes in the top level devicetree to ensure they are available in u-boot-spl. In addition to this, any configuration pertinent to u-boot-spl is added, such as flash layout, etc.

These are separated into a common devicetree include:

arch/arm/dts/socfpga-common-u-boot.dts

Which is included in the board specific devicetree includes: Cyclone5

arch/arm/dts/socfpga_cyclone5_de0_nano_soc-u-boot.dtsi  arch/arm/dts/socfpga_cyclone5_sockit-u-boot.dtsi
arch/arm/dts/socfpga_cyclone5_socrates-u-boot.dtsi      arch/arm/dts/socfpga_cyclone5_mcvevk-u-boot.dtsi
arch/arm/dts/socfpga_cyclone5_vining_fpga-u-boot.dtsi   arch/arm/dts/socfpga_cyclone5_socdk-u-boot.dtsi

Arria5

arch/arm/dts/socfpga_arria5_socdk-u-boot.dtsi

Arria10 u-boot.dtsi

In Arria10, data regarding PLL configuration, pin mux configuration, and various other configurations as passed to u-boot-spl via the devicetree. This is in addition to the general u-boot devicetree modifications required for cyclone5/arria5.

Arria10 has not as of yet been setup as nicely as cyclone5/arria5 and the u-boot dtsi is just included in the top level devicetree.

Stratix10 u-boot.dtsi

In Stratix10, u-boot-spl still requires handoff data for pin mux and clock configuration, however the SDM passes this to u-boot-spl in a shared data structure at boot.

arch/arm/dts/socfpga_stratix10_socdk-u-boot.dtsi

Looking over the various examples listed above, modify the your u-boot.dtsi to ensure resources needed during u-boot-spl are enabled appropriately. Typically, these include a uart, boot media such as qspi, etc. More device specific requirements are listed in the device specific sections.

Cyclone5 / Arria5

Overview of C5/A5 configuration

In C5/A5 pin mux, clock, and ddr configuration are NOT devicetree driven, as a result, headers and configuration of the source is required for board / quartus project specific settings. This is documented in the socfpga README in the u-Boot source.

• README.socfpga

During FPGA compilation, the hps_isw_handoff data is generated. This contains code for sdram calibration and configuration, PLL settings, and IO Pin Mux configurations.the bsp-create-settings (part of SoCEDS and ARM Development Studio) is used to generate further headers by parsing xml data in the hps_isw_handoff tool.

The qts-filter.sh script in the u-boot source is then used to generate mainline appropriate headers for your board specific settings.

Update Foo Board with pertinent hps_isw_handoff data

As previously mentioned, for the C5/A5 SoCFPGAs we need to update header and source information for settings and configurations specific to the FPGA design. The first step is to use the bsp-editor or bsp-create-settings both of which are installed in the SoCEDNoneS tools. Please refer the aforementioned README.socfpga.

From the readme, bsp-create-settings is called as follows:

  $ /path/to/bsb/tools/bsp-create-settings --type spl --bsp-dir build \
      --preloader-settings-dir hps_isw_handoff/soc_system_hps_0/ \
      --settings build/settings.bsp

So, if you use the cyclone5 ghrd as an example:

[dwesterg@dwesterg-mobl1 cv_soc_devkit_ghrd]$ bsp-create-settings --type spl --bsp-dir build --preloader-settings-dir hps_isw_handoff/soc_system_hps_0/ --settings build/settings.bsp
INFO: Creating BSP settings file...
INFO: nios2-bsp-create-settings --type spl --bsp-dir build --preloader-settings-dir hps_isw_handoff/soc_system_hps_0/ --settings build/settings.bsp 
INFO: Searching for BSP components with category: driver_element
INFO: Searching for BSP components with category: software_package_element
INFO: Generated file "/tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build/settings.bsp"
INFO: BSP settings file was created at location "/tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build/settings.bsp".
INFO: Generating BSP files...
INFO: Generating BSP files in "/tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build"
INFO: Generated file "/tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build/settings.bsp"
INFO: Tcl message: "Reading preloader settings dir: /tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/hps_isw_handoff/soc_system_hps_0"
INFO: Tcl message: "Generating file: /tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build/generated/sdram//sdram_config.h..."
INFO: Tcl message: "Generating file: /tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build/generated/pinmux_config.h..."
INFO: Tcl message: "Generating file: /tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build/generated/pinmux_config_cyclone5.c..."
INFO: Tcl message: "Generating file: /tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build/generated/reset_config.h.template..."
INFO: Tcl message: "Generating file: /tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build/generated/Makefile.template..."
INFO: Tcl message: "Generating file: /tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build/generated/pll_config.h"
INFO: Tcl message: "Reading file: /tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/hps_isw_handoff/soc_system_hps_0/soc_system_hps_0.hiof..."
INFO: Tcl message: "Generating file: /tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build/generated/iocsr_config_cyclone5.h..."
INFO: Tcl message: "Generating file: /tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build/generated/iocsr_config_cyclone5.c..."
INFO: Finished generating BSP files. Total time taken = 2 seconds
INFO: BSP files generated in "/tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build"

And we see the results in the newly created build directory:

[dwesterg@dwesterg-mobl1 cv_soc_devkit_ghrd]$ ls build/
generated  Makefile  preloader.ds  settings.bsp  uboot.ds
[dwesterg@dwesterg-mobl1 cv_soc_devkit_ghrd]$

The final step is to use the hps_isw_handoff data and the generated output in the build directory to update the quartus settings in the qts folder of our new board. From README.socfpga we see how the command is run:

  $ ./arch/arm/mach-socfpga/qts-filter.sh \
        <soc_type> \
        <input_qts_dir> \
        <input_bsp_dir> \
        <output_dir>

Process QTS-generated files into U-Boot compatible ones.

    soc_type      - Type of SoC, either 'cyclone5' or 'arria5'.
    input_qts_dir - Directory with compiled Quartus project
                    and containing the Quartus project file (QPF).
    input_bsp_dir - Directory with generated bsp containing
                    the settings.bsp file.
    output_dir    - Directory to store the U-Boot compatible
                    headers.

So back in our u-boot source tree:

[dwesterg@dwesterg-mobl1 u-boot]$ ./arch/arm/mach-socfpga/qts-filter.sh cyclone5 /tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/ /tools/soceds/19.1std/647/linux64/examples/hardware/cv_soc_devkit_ghrd/build/ board/foo_board/qts/
[dwesterg@dwesterg-mobl1 u-boot]$ 

as a result of which we have freshly minted files in our foo_board/qts folder:

[dwesterg@dwesterg-mobl1 u-boot]$ ls -lah board/foo_board/qts/
total 36K
drwxrwxr-x. 1 dwesterg dwesterg  110 Jun  6 19:45 .
drwxrwxr-x. 1 dwesterg dwesterg  178 Jun 12 17:04 ..
-rw-rw-r--. 1 dwesterg dwesterg 8.7K Jun 13 06:40 iocsr_config.h
-rw-rw-r--. 1 dwesterg dwesterg 4.3K Jun 13 06:40 pinmux_config.h
-rw-rw-r--. 1 dwesterg dwesterg 3.2K Jun 13 06:40 pll_config.h
-rw-rw-r--. 1 dwesterg dwesterg 9.1K Jun 13 06:40 sdram_config.h
[dwesterg@dwesterg-mobl1 u-boot]$ 

Devicetree C5/A5 specific u-boot modifications

Cyclone5/Arria5 u-boot lacks a proper clock driver, as a result, it is important to ensure that the reference clock frequency is added to the uart devicetree nodes. Ensure that the appropriate UART is enabled, and if USB gadget devices are required, ensure that the proper alias is added. No other modifications for device initialization are required.

Arria10

Mainline Arria10 u-boot differs from u-boot-socfpga in that it moves back to the u-boot-spl followed by u-boot boot model. u-Boot-socfpga (2014.09) did not enable or use u-boot-spl and instead ran a slim u-boot out of the 256K onchip RAM.

u-Boot-spl is responsible for device initialization and uses handoff data provided in the devicetree to do so.

Devicetree A10 specific u-boot modifications

Stratix10

All handoff data for device initialization is passed to u-boot from the SDM.

Devicetree S10 specific u-boot modifications

None, aside from basic enabling of resources needed by u-boot.