HPS GHRD Linux Boot Examples for Cyclone® V SX Development Kit

Introduction

This page contains instructions on how to build U-Boot in the following configurations:

Device	Quartus Version	U-Boot Branch	Linux Branch
Cyclone V SoC	25.1 Std	socfpga_v2025.07	socfpga-6.12.33-lts

Note:

1. Arria® V SoC flow and Cyclone® V SoC flow are identical. The SoC flow, applicable to both device families, is presented in the next section.

2. Starting with SoC EDS Standard version 19.1 and SoC EDS Pro version 19.3, the following changes were made:

• The bootloader source code was removed from SoC Embedded Design Suite (EDS). Instead, the user needs to clone the git trees from https://github.com/altera-fpga/u-boot-socfpga.

• The same U-Boot branch is applicable to all SoC FPGA devices: Cyclone® V SoC, Arria® V SoC, Arria® 10 SoC, Stratix® 10 SoC, Agilex®.

• The bootloader generator (bsp-editor) is still required for Cyclone® V SoC, Arria® V SoC and Arria® 10 SoC, but:

  • Does not support custom user settings anymore. All customized user setting i.e. device tree, configuration and source code, must be done directly in U-Boot. All user-defined U-Boot parameters set in the new version of bsp-editor will take no effect.
  • Does not create a makefile which builds the bootloader. User shall refer to this page on the how-to instructions to build the bootloader.

3. Starting with Quartus Pro release 20.3, the SoC EDS was discontinued, and the functionality or tools which were previously part of SoC EDS are provided separately.

4. Starting with Quartus Std release 22.1std, SoC EDS is no longer required to generate the handoff folder for Cyclone® V.

U-Boot Branches

The official Altera SOCFPGA U-Boot repository is located at https://github.com/altera-fpga/u-boot-socfpga. Refer to U-Boot documentation for more details: U-boot README

Note:

Latest stable branch (no RC label) is recommended for development and production use. An "RC"-labeled branch is for internal active development use and for early access customers, hence official customer support is limited. For more information, see U-boot README.socfpga.

U-Boot Build Flows

For Cyclone V SoC, the Handoff information created by Quartus compilation and it comes in several formats: C source code, XML, and binary files. The bsp-editor consumes the handoff information and converts it into source code which is needed to build U-Boot.

The Old Flow

Previous versions of SoC EDS builds U-boot using the following flow:

• Most user options (like boot source, enabling ECC scrubbing, watchdog etc) were set through the bsp-editor GUI or the CLI equivalents.
• U-Boot source code was part of SoC EDS.
• The makefile created by the bsp-editor allowed building the bootloader with a single 'make' command.

The New Flow

Starting with the 22.1std release of SoC EDS, the new build flow is depicted below:

• All the user options defined in the bsp-editor are not applicable anymore. (The user options can be found in the GUI but setting them have no functional effect)
• All customized user settings must be done directly in U-Boot, including device tree, configuration and source code.
• The makefile generated by bsp-editor does not build U-Boot, instead it instructs the user to go to this page.
• The U-boot source code needs to be retrieved by the user from github.
• A tool called qts_filter (part of U-Boot) needs to be called to convert the handoff files and bsp-editor generated files to the format required by the new U-Boot version.

U-Boot Examples

Prerequisites

The following are required:

1. A host machine running Linux OS. Ubuntu 22.04 was used in this example.

2. Internet is required to download the U-Boot and tools from github. If you are behind a firewall you will need to disable it to access and clone the git trees.

3. Altera SoC FPGA Development Kit hardware (devkit): Cyclone® V SoC, Arria® 10 SoC, Stratix® 10 SoC or Agilex®.

• Download Quartus Standard version 25.1 installer from Quartus® Prime Standard Edition Design Software Version 25.1 for Linux

• Refer to User Guide: Quartus® Prime Pro and Standard Software User Guides

Note: The examples in this page boots the devkit to U-boot shell and further to the Linux OS. This requires the Linux kernel, device tree and root filesystem. Without the OS binaries, the devkit would boot to the U-Boot shell only (as there is no bootable OS). You may use your own Linux binaries or follow a simple way to build them as shown in Appendix 1 - Building Linux Binaries. In either case, the boot instruction below assumes that the binaries are located in the $LINUX_BIN folder.

1. Cyclone V SoC - Boot from SD Card

1.A. Setup

Create a top folder:

mkdir cv_example.sdmmc
cd cv_example.sdmmc
export TOP_FOLDER=`pwd`

Download and setup the toolchain required for Cyclone V SoC:

wget https://developer.arm.com/-/media/Files/downloads/gnu/14.3.rel1/binrel/arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz
tar xf arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz
rm arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz
export PATH=`pwd`/arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-linux-gnueabihf/bin:$PATH
export ARCH=arm
export CROSS_COMPILE=arm-none-linux-gnueabihf-

Compile Hardware Design:

Note: The Quartus® Prime Standard Edition Design Software License is required to execute the Nios® Command Shell.

cd $TOP_FOLDER
rm -rf cyclonev-ed-gsrd cv_soc_devkit_ghrd
git clone https://github.com/altera-fpga/cyclonev-ed-gsrd
cd cyclonev-ed-gsrd
git checkout QPDS25.1STD_REL_GSRD_PR
~/altera/25.1std/nios2eds/nios2_command_shell.sh \
make cyclonev-soc-devkit-baseline-all
cd $TOP_FOLDER
cp -R cyclonev-ed-gsrd/cv_soc_devkit_ghrd .

1.B. Prepare U-Boot

Clone the U-Boot source code:

cd $TOP_FOLDER/cv_soc_devkit_ghrd
mkdir -p software/bootloader && cd software/bootloader
git clone https://github.com/altera-fpga/u-boot-socfpga
cd u-boot-socfpga
git checkout QPDS25.1STD_REL_GSRD_PR

Run the cv_bsp_generator.py script with python2. The script moves the source code from the handoff folder, format and copy them to the U-Boot source code.

cd $TOP_FOLDER/cv_soc_devkit_ghrd/software/bootloader/u-boot-socfpga/arch/arm/mach-socfpga/cv_bsp_generator

python cv_bsp_generator.py -i $TOP_FOLDER/cv_soc_devkit_ghrd/hps_isw_handoff/soc_system_hps_0 \
-o ../../../../board/altera/cyclone5-socdk/qts

After running the cv_bsp_generator.py script, these files will be in "$TOP_FOLDER/cv_soc_devkit_ghrd/software/bootloader/u-boot-socfpga/board/altera/cyclone5-socdk/qts":

• iocsr_config.h
• pinmux_config.h
• pll_config.h
• sdram_config.h

Configure and build U-Boot:

cd $TOP_FOLDER/cv_soc_devkit_ghrd/software/bootloader/u-boot-socfpga
make socfpga_cyclone5_defconfig
make -j 48

The following files will be in the "$TOP_FOLDER/cv_soc_devkit_ghrd/software/bootloader/u-boot-socfpga" folder:

File	Description
spl/u-boot-spl	SPL ELF executable
u-boot	U-Boot ELF executable
u-boot-with-spl.sfp	Bootable file: four copies of SPL and one copy on U-Boot image

1.C. Prepare SD Card Image

This section presents how to prepare a bootable SD card which boots up Linux OS. If you do not need Linux, you may ommit this part, the devkit will only boot to the U-Boot shell.

Prerequisite:

The following Linux binaries are assumed to be pre-built in the "$LINUX_BIN/a9" folder, refer to Appendix 1 - Building Linux Binaries on how to get the Linux binaries ready:

File	Description
zImage	Compressed kernel image
socfpga_cyclone5_socdk.dtb	Linux device tree blob
core-image-minimal-cyclone5.rootfs.tar.gz	Linux root filesystem

Setup SD Card folder

cd $TOP_FOLDER/
sudo rm -rf sd_card && mkdir sd_card && cd sd_card
wget https://releases.rocketboards.org/2021.04/gsrd/tools/make_sdimage_p3.py
chmod +x make_sdimage_p3.py
# Uncomment the following sed command if your environment is Ubuntu 22.04, see Note below.
# sed -i 's/\"\-F 32\",//g' make_sdimage_p3.py

Note: On certain modern Linux distros (like Ubuntu 22.04), the make_sdimage_p3.py script encounters an issue with the "-F 32" parameter passed to the mkfs.vfat utility. This parameter specifies the FAT32 type, but newer versions of mkfs.vfat handle this automatically and find the explicit parameter problematic, often returning a "Bad FAT type : 32" error.

Prepare FAT partition:

cd $TOP_FOLDER/sd_card
mkdir sdfs &&  cd sdfs
cp $LINUX_BIN/a9/zImage .
cp $LINUX_BIN/a9/socfpga_cyclone5_socdk.dtb .
cp $TOP_FOLDER/cv_soc_devkit_ghrd/output_files/soc_system.rbf .
wget https://releases.rocketboards.org/2025.11/gsrd/c5_gsrd/u-boot.scr

mkdir extlinux
echo "LABEL Linux Default" > extlinux/extlinux.conf
echo "    KERNEL ../zImage" >> extlinux/extlinux.conf
echo "    FDT ../socfpga_cyclone5_socdk.dtb" >> extlinux/extlinux.conf
echo "    APPEND root=/dev/mmcblk0p2 rw rootwait earlyprintk console=ttyS0,115200n8" >> extlinux/extlinux.conf

Prepare Rootfs partition:

cd $TOP_FOLDER/sd_card
sudo rm -rf rootfs
mkdir rootfs && cd rootfs
sudo tar xf $LINUX_BIN/a9/core-image-minimal-cyclone5.rootfs.tar.gz
sudo rm -rf lib/modules/*
sudo cp -r $LINUX_BIN/a9/modules/* lib/modules

Copy the U-boot bootable binary file:

cd $TOP_FOLDER/sd_card
cp ../cv_soc_devkit_ghrd/software/bootloader/u-boot-socfpga/u-boot-with-spl.sfp .

Prepare SD card image:

cd $TOP_FOLDER/sd_card
sudo python3 ./make_sdimage_p3.py -f \
-P u-boot-with-spl.sfp,num=3,format=raw,size=10M,type=A2  \
-P sdfs/*,num=1,format=fat32,size=100M \
-P rootfs/*,num=2,format=ext3,size=300M \
-s 512M \
-n sdcard_cv.img

1.D. Board Setting to Boot from SD Card

Set the Boot Select jumpers to boot from the 3.3V SD device:

Jumper	Component Label	Position
BOOTSEL2	J30	1 (left)
BOOTSEL1	J29	0 (right)
BOOTSEL0	J28	1 (left)

1.E. Boot Up the Board

Power cycle the board - it will boot to Linux OS, use username 'root' with no password to log in:

Note: The Terminal log below is truncated and for reference only, your device's print-out may not match exactly.

U-Boot SPL 2025.07-g35abb4f1cedc (Nov 20 2025 - 02:01:21 -0600)
DDRCAL: Scrubbing ECC RAM (1024 MiB).
DDRCAL: SDRAM-ECC initialized success with 578 ms
Trying to boot from MMC1

U-Boot 2025.07-g35abb4f1cedc (Nov 20 2025 - 02:01:21 -0600)

CPU:   Altera SoCFPGA Platform
FPGA:  Altera Cyclone V, SE/A6 or SX/C6 or ST/D6, version 0x0
BOOT:  SD/MMC Internal Transceiver (3.0V)
DRAM:  1 GiB
Core:  33 devices, 18 uclasses, devicetree: separate
MMC:   dwmmc0@ff704000: 0
Loading Environment from MMC... Reading from MMC(0)... *** Warning - bad CRC, using default environment

In:    serial
Out:   serial
Err:   serial
Model: Altera SOCFPGA Cyclone V SoC Development Kit
Net:
Warning: ethernet@ff702000 (eth0) using random MAC address - 96:03:b4:d1:c3:ad
eth0: ethernet@ff702000
Hit any key to stop autoboot:  0
162 bytes read in 1 ms (158.2 KiB/s)
## Executing script at 02100000
      162   u-boot.scr
    20511   socfpga_cyclone5_socdk.dtb
  6493432   zImage
  2385856   soc_system.rbf
            extlinux/
            System Volume Information/

4 file(s), 2 dir(s)

2385856 bytes read in 118 ms (19.3 MiB/s)
switch to partitions #0, OK
mmc0 is current device
Scanning mmc 0:1...
Found /extlinux/extlinux.conf
Retrieving file: /extlinux/extlinux.conf
1:      Linux Default
Retrieving file: /extlinux/../zImage
append: root=/dev/mmcblk0p2 rw rootwait earlyprintk console=ttyS0,115200n8
Retrieving file: /extlinux/../socfpga_cyclone5_socdk.dtb
Kernel image @ 0x1000000 [ 0x000000 - 0x6314f8 ]
## Flattened Device Tree blob at 02000000
   Booting using the fdt blob at 0x2000000
Working FDT set to 2000000
   Loading Device Tree to 09ff7000, end 09fff01e ... OK
Working FDT set to 9ff7000

Starting kernel ...

Deasserting all peripheral resets
[    0.000000] Booting Linux on physical CPU 0x0
[    0.000000] Linux version 6.12.33-g3234b1ed8956-dirty (atan44@test2-linux-lab) (arm-none-linux-gnueabihf-gcc (Arm GNU Toolchain 14.3.Rel1 (Build arm-14.174)) 14.3.1 20250623, GNU ld (Arm GNU Toolchain 14.3.Rel1 (Build arm-14.174)) 2.44.0.20250616) #1 SMP Thu Nov 20 02:13:32 CST 2025
[    0.000000] CPU: ARMv7 Processor [413fc090] revision 0 (ARMv7), cr=10c5387d

..........
..........

[    7.515443] socfpga-dwmac ff702000.ethernet eth0: registered PTP clock
[    7.533640] socfpga-dwmac ff702000.ethernet eth0: configuring for phy/rgmii link mode
udhcpc: started, v1.37.0
udhcpc: broadcasting discover
udhcpc: broadcasting discover
udhcpc: broadcasting discover
udhcpc: no lease, forking to background
ip: SIOCGIFFLAGS: No such device
Starting syslogd/klogd: done

Poky (Yocto Project Reference Distro) 5.2.4 cyclone5 /dev/ttyS0

cyclone5 login: root
root@cyclone5:~#

2. Cyclone V SoC - Boot from QSPI

The methodology to boot from QSPI is similar to boot from SD card, with the following differences:

• Additional U-Boot configuration is performed, to store the environment in QSPI Flash Memory instead of an SD card
• Binaries and files are written to the QSPI Flash Memory instead of an SD card

See Appendix 1 - Building Linux Binaries for instructions on how to build the Linux binaries for this example. Similar to previous sections, this section assumes that the Linux binaries are located in the "$LINUX_BIN/a9" folder.

2.A. Setup

Create top folder:

mkdir cv_example.qspi
cd cv_example.qspi
export TOP_FOLDER=`pwd`

Download and setup the toolchain required for Cyclone V SoC:

wget https://developer.arm.com/-/media/Files/downloads/gnu/14.3.rel1/binrel/arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz
tar xf arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz
rm arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz
export PATH=`pwd`/arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-linux-gnueabihf/bin:$PATH
export ARCH=arm
export CROSS_COMPILE=arm-none-linux-gnueabihf-

Compile Hardware Design:

Note: The Quartus® Prime Standard Edition Design Software License is required to execute the Nios® Command Shell.

cd $TOP_FOLDER
rm -rf cyclonev-ed-gsrd cv_soc_devkit_ghrd
git clone https://github.com/altera-fpga/cyclonev-ed-gsrd
cd cyclonev-ed-gsrd
git checkout QPDS25.1STD_REL_GSRD_PR
~/altera/25.1std/nios2eds/nios2_command_shell.sh \
make cyclonev-soc-devkit-baseline-all
cd $TOP_FOLDER
cp -R cyclonev-ed-gsrd/cv_soc_devkit_ghrd .

2.B. Prepare U-Boot

Clone the U-Boot source code:

cd $TOP_FOLDER/cv_soc_devkit_ghrd
mkdir -p software/bootloader && cd software/bootloader
git clone https://github.com/altera-fpga/u-boot-socfpga
cd u-boot-socfpga
git checkout QPDS25.1STD_REL_GSRD_PR

Run the cv_bsp_generator.py script with python2. The script moves the source code from the handoff folder, format and copy them to the U-Boot source code.

cd $TOP_FOLDER/cv_soc_devkit_ghrd/software/bootloader/u-boot-socfpga/arch/arm/mach-socfpga/cv_bsp_generator

python cv_bsp_generator.py -i $TOP_FOLDER/cv_soc_devkit_ghrd/hps_isw_handoff/soc_system_hps_0 \
-o ../../../../board/altera/cyclone5-socdk/qts

After running the cv_bsp_generator.py script, these files will be in "$TOP_FOLDER/cv_soc_devkit_ghrd/software/bootloader/u-boot-socfpga/board/altera/cyclone5-socdk/qts":

• iocsr_config.h
• pinmux_config.h
• pll_config.h
• sdram_config.h

Configure and build U-Boot:

Note: The file "socfpga_cyclone5_qspi_defconfig" is no longer available from 25.1std onwards, use "socfpga_cyclone5_defconfig" for QPSI-enabled Single Boot method.

cd $TOP_FOLDER/cv_soc_devkit_ghrd/software/bootloader/u-boot-socfpga
make socfpga_cyclone5_defconfig
make -j 48

The following files will be built in the "$TOP_FOLDER/cv_soc_devkit_ghrd/software/bootloader/u-boot-socfpga" folder:

File	Description
spl/u-boot-spl	SPL ELF executable
u-boot	U-Boot ELF executable
u-boot-with-spl.sfp	Bootable file: four copies of SPL and one copy on U-Boot image

2.C. Prepare QSPI Binaries

This section presents how to boot from QSPI Flash Memory which boots up Linux OS. If you do not need Linux, you may ommit this part and the devkit will only boot to the U-Boot shell.

The following Linux binaries are assumed to be pre-built in the $LINUX_BIN/a9 folder:

File	Description
zImage	Compressed kernel image
socfpga_cyclone5_socdk.dtb	Linux device tree blob
core-image-minimal-cyclone5.tar.gz	Linux rootfilesystem

Create qspi_bin folder:

cd $TOP_FOLDER/
sudo rm -rf qspi_bin && mkdir qspi_bin && cd qspi_bin
cp ../cv_soc_devkit_ghrd/software/bootloader/u-boot-socfpga/u-boot-with-spl.sfp .
cp $LINUX_BIN/a9/zImage .
cp $LINUX_BIN/a9/socfpga_cyclone5_socdk.dtb .

Build the rootfs JFFS2 image:

cd $TOP_FOLDER/qspi_bin
sudo rm -rf core-image-minimal-cyclone5-rootfs
mkdir core-image-minimal-cyclone5-rootfs
cd core-image-minimal-cyclone5-rootfs
sudo tar xf $LINUX_BIN/a9/core-image-minimal-cyclone5.rootfs.tar.gz
sudo rm -rf lib/modules/*
cd ..
sudo mkfs.jffs2 -r core-image-minimal-cyclone5-rootfs -s 256 -e 64KiB --squash -o core-image-minimal-cyclone5-rootfs.jffs2
sudo chown $USER:$USER core-image-minimal-cyclone5-rootfs.jffs2
sudo rm -rf core-image-minimal-cyclone5-rootfs

The following files are built:

File	Description
u-boot-with-spl.sfp	Four SPL images and U-Boot image
socfpga_cyclone5_socdk.dtb	Linux device tree blob
zImage	Compressed linu kernel
core-image-minimal-cyclone5-rootfs.jffs2	Linux rootfs image

2.D(1). Flash the QSPI using Quartus Programmer

Set the Boot Select jumpers to boot from the 3.3V QSPI device:

Jumper	Component Label	Position
BOOTSEL2	J30	1 (left)
BOOTSEL1	J29	1 (left)
BOOTSEL0	J28	1 (left)

Flash the QSPI Flash Memory following the addresses assigned below:

Address	File	Description
0x0000000	u-boot-with-spl.sfp	Four SPL binaries and U-Boot image
0x0200000	n/a	U-Boot environment
0x0220000	socfpga_cyclone5_socdk.dtb	Linux device tree
0x0230000	zImage	Linux kernel
0x0800000	core-image-minimal-cyclone5-rootfs.jffs2	Linux rootfs

Flash the QSPI binaries:

cd $TOP_FOLDER/qspi_bin

~/altera/25.1std/nios2eds/nios2_command_shell.sh \
quartus_hps -c 1 -o pv -a 0x000000 u-boot-with-spl.sfp

~/altera/25.1std/nios2eds/nios2_command_shell.sh \
quartus_hps -c 1 -o pv -a 0x220000 socfpga_cyclone5_socdk.dtb

~/altera/25.1std/nios2eds/nios2_command_shell.sh \
quartus_hps -c 1 -o pv -a 0x230000 zImage

~/altera/25.1std/nios2eds/nios2_command_shell.sh \
quartus_hps -c 1 -o pv -a 0x800000 -s 0x3800000 core-image-minimal-cyclone5-rootfs.jffs2

2.D(2). Flash the QSPI using TFTP and U-Boot

Flashing the QSPI FLash Memory by using quartus_hps is a slow process, a faster alternative is to load U-Boot through a DS-5 debugger, download the files through TFTP, and write them with U-Boot.

1. Erase the QSPI with quartus_hps:

~/altera/25.1std/nios2eds/nios2_command_shell.sh \
quartus_hps -c 1 -o E

2. Copy the binaries to a TFTP folder on your host machine.

3. Run U-Boot from the debugger as shown in Appendix 2 - Run U-Boot with the Debugger from Command Line

4. Connnect your U-Boot to the network, and specify the IP address of you host machine:

setenv autoload no
dhcp
setenv serverip <your_server_ip>

5. In U-Boot, download binaries over TFTP, and write the to QSPI:

sf probe
tftp ${loadaddr} u-boot-with-spl.sfp;sf write ${loadaddr} 0x000000 ${filesize}
tftp ${loadaddr} socfpga_cyclone5_socdk.dtb;sf write ${loadaddr} 0x220000 ${filesize}
tftp ${loadaddr} zImage;sf write ${loadaddr} 0x230000 ${filesize}
tftp ${loadaddr} core-image-minimal-cyclone5-rootfs.jffs2;sf write ${loadaddr} 0x800000 ${filesize}

2.E. Boot Up the Board

Power cycle the board - it will boot to Linux OS, use username 'root' with no password to log in:

Note: The Terminal log below is truncated and for reference only, your device's print-out may not match exactly.

U-Boot 2025.07 (Oct 21 2025 - 07:31:19 +0000)
DDRCAL: Scrubbing ECC RAM (1024 MiB).
DDRCAL: SDRAM-ECC initialized success with 579 ms
Trying to boot from SPI

CPU:   Altera SoCFPGA Platform
FPGA:  Altera Cyclone V, SE/A6 or SX/C6 or ST/D6, version 0x0
BOOT:  QSPI Flash (3.0V)
       Watchdog enabled
DRAM:  1 GiB
Core:  33 devices, 18 uclasses, devicetree: separate
MMC:   dwmmc0@ff704000: 0
Loading Environment from MMC... Reading from MMC(0)... *** Warning - bad CRC, using default environment

In:    serial
Out:   serial
Err:   serial
Model: Altera SOCFPGA Cyclone V SoC Development Kit
Net:
Warning: ethernet@ff702000 (eth0) using random MAC address - be:28:da:b7:08:40
eth0: ethernet@ff702000
Hit any key to stop autoboot:  0
162 bytes read in 2 ms (79.1 KiB/s)
## Executing script at 02100000
            extlinux/
    22246   socfpga_cyclone5_socdk.dtb
  2357160   soc_system.rbf
      162   u-boot.scr
  6928552   zImage
            System Volume Information/

4 file(s), 2 dir(s)

2357160 bytes read in 115 ms (19.5 MiB/s)
switch to partitions #0, OK
mmc0 is current device
Scanning mmc 0:1...
Found /extlinux/extlinux.conf
Retrieving file: /extlinux/extlinux.conf
1:      Cyclone5 SOCDK SDMMC
Retrieving file: /extlinux/../zImage
append: root=/dev/mmcblk0p2 rootwait rw earlyprintk console=ttyS0,115200n8
Retrieving file: /extlinux/../socfpga_cyclone5_socdk.dtb
Kernel image @ 0x1000000 [ 0x000000 - 0x69b8a8 ]
## Flattened Device Tree blob at 02000000
  Booting using the fdt blob at 0x2000000
Working FDT set to 2000000
  Loading Device Tree to 09ff7000, end 09fff6e5 ... OK
Working FDT set to 9ff7000

Starting kernel ...

Deasserting all peripheral resets
[    0.000000] Booting Linux on physical CPU 0x0
[    0.000000] Linux version 6.12.33-altera-g2d2420ac9be1 (oe-user@oe-host) (arm-poky-linux-gnueabi-gcc (GCC) 14.3.0, GNU ld (GNU Binutils) 2.44.0.20250715) #1 SMP Thu Sep 25 06:05:32 UTC 2025
[    0.000000] CPU: ARMv7 Processor [413fc090] revision 0 (ARMv7), cr=10c5387d
[    0.000000] CPU: PIPT / VIPT nonaliasing data cache, VIPT aliasing instruction cache
[    0.000000] OF: fdt: Machine model: Altera SOCFPGA Cyclone V SoC Development Kit

..........
Welcome to Poky (Yocto Project Reference Distro) 5.2.4 (walnascar)!
..........

[  OK  ] Started Telephony service.
        Starting Connection service...
        Starting Enable Persistent Storage in systemd-networkd...
        Starting Wait for Network to be Configured...
[  OK  ] Finished Enable Persistent Storage in systemd-networkd.
[  OK  ] Started Connection service.
[  OK  ] Reached target Network.
        Starting Avahi mDNS/DNS-SD Stack...
        Starting Hostname Service...
        Starting WPA supplicant...
[  OK  ] Started Avahi mDNS/DNS-SD Stack.
[  OK  ] Started WPA supplicant.
[  OK  ] Started Hostname Service.

Poky (Yocto Project Reference Distro) 5.2.4 cyclone5 ttyS0

cyclone5 login: root
root@cyclone5:~#

Appendix 1 - Building Linux Binaries

This section details how to build the Linux binaries which are used in the boot examples above. Building Linux is beyond the scope of this page, and minimal instructions are included for reference only.

Prerequisites

This example is tested on Ubuntu 22.04LTS. The Linux libraries and packages required to be installed in order to build the Linux kernel and rootf are listed below:

sudo apt-get install gawk wget git-core diffstat unzip texinfo \
gcc-multilib  build-essential chrpath socat cpio python python3 \
python3-pip python3-pexpect  xz-utils debianutils iputils-ping \
python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev  pylint3 xterm \
libncurses-dev gawk flex bison openssl libssl-dev

Prepare a LINUX_BIN directory for the binaries.

rm -rf linux-bin && mkdir linux-bin && cd linux-bin
export set LINUX_BIN=`pwd`
mkdir -p $LINUX_BIN/a9

Building Linux Kernel

This section presents how to build the Linux kernel used for the boot examples on this page. Refer to https://rocketboards.org/foswiki/Main/GettingStarted for complete instructions.

Prepare a LINUX_TOP folder:

cd $LINUX_BIN
rm -rf linux && mkdir linux && cd linux
export set LINUX_TOP=`pwd`

Download and setup the toolchain (skip if these steps are done beforehand):

cd $LINUX_TOP
wget https://developer.arm.com/-/media/Files/downloads/gnu/14.3.rel1/binrel/arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz
tar xf arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz
rm arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz
export PATH=`pwd`/arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-linux-gnueabihf/bin:$PATH
export ARCH=arm
export CROSS_COMPILE=arm-none-linux-gnueabihf-

Clone the Linux git tree to retrieve the code:

cd $LINUX_TOP
git clone https://github.com/altera-fpga/linux-socfpga linux-socfpga.a9
cd linux-socfpga.a9
git checkout QPDS25.1STD_REL_GSRD_PR

Most Cyclone V SoC DevKits equipped with a 512MB QSPI flash device, while the Linux kernel DTS assumes the board is using a 1Gb (shown as 128MB or 120MB). If the board has the standard 512MB one, change the file "socfpga_cyclone5_socdk.dts" accordingly before building dtbs:

# Modify the dts file, change "reg = <0x800000 0x7800000>;" to "reg = <0x800000 0x3800000>;":
# Or, use the sed commands below
vi $LINUX_TOP/linux-socfpga.a9/arch/arm/boot/dts/intel/socfpga/socfpga_cyclone5_socdk.dts

         partition@qspi-rootfs {
         /* 120MB for jffs2 data. */
         label = "Flash 0 jffs2 Filesystem";
         reg = <0x800000 0x3800000>;
      };

The lines above can be modified by using the "sed" commands:

cd $LINUX_TOP/linux-socfpga.a9
sed -i 's/120MB for jffs2 data/56MB for jffs2 data/g' arch/arm/boot/dts/intel/socfpga/socfpga_cyclone5_socdk.dts
sed -i 's/<0x800000 0x7800000>;/<0x800000 0x3800000>;/g' arch/arm/boot/dts/intel/socfpga/socfpga_cyclone5_socdk.dts

Build the Linux kernel:

cd $LINUX_TOP/linux-socfpga.a9
make socfpga_defconfig
make -j 48 zImage Image dtbs modules
make -j 48 modules_install INSTALL_MOD_PATH=modules_install
rm -rf modules_install/lib/modules/*/build
rm -rf modules_install/lib/modules/*/source

Link all the relevant files to $LINUX_BIN

ln -s $LINUX_TOP/linux-socfpga.a9/arch/arm/boot/zImage $LINUX_BIN/a9/
ln -s $LINUX_TOP/linux-socfpga.a9/arch/arm/boot/Image $LINUX_BIN/a9/
ln -s $LINUX_TOP/linux-socfpga.a9/arch/arm/boot/dts/intel/socfpga/socfpga_cyclone5_socdk.dtb $LINUX_BIN/a9/
ln -s $LINUX_TOP/linux-socfpga.a9/modules_install/lib/modules $LINUX_BIN/a9/

The following items are linked in the $LINUX_BIN/a9 folder:

Item	Description
zImage	compressed kernel image
Image	uncompressed kernel image
socfpga_cyclone5_socdk.dtb	Cyclone V device tree blob for both sdmmc and qspi boot
modules	kernel loadable modules

Building Yocto Rootfs

This section presents how to build the Linux rootfs using the Yocto recipes. Note that the yocto recipes build everything by default, but only the rootfs is needed.

First, make sure the Yocto system requirements are met. Refer to supported Linux distribution in Yocto 5.2.4 release "Walnascar"

Tnstall the required packages on Ubuntu:

sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential chrpath \
socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping \
python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint3 xterm python3-subunit \
mesa-common-dev zstd liblz4-tool

Prepare a top folder:

cd $LINUX_TOP
mkdir rootfs && cd rootfs
export set ROOTFS_TOP=`pwd`

Clone and build the Yocto image:

cd $ROOTFS_TOP
rm -rf cv && mkdir cv && cd cv
git clone -b walnascar https://git.yoctoproject.org/poky
git clone -b walnascar https://git.yoctoproject.org/meta-intel-fpga

source poky/oe-init-build-env ./build
echo 'MACHINE = "cyclone5"' >> conf/local.conf
echo 'BBLAYERS += " ${TOPDIR}/../meta-intel-fpga "' >> conf/bblayers.conf
echo 'IMAGE_BOOT_FILES = " socfpga_cyclone5_socdk.dtb socfpga_cyclone5_sockit.dtb socfpga_cyclone5_socrates.dtb socfpga_cyclone5_de0_nano_soc.dtb socfpga_cyclone5_mcvevk.dtb socfpga_cyclone5_sodia.dtb socfpga_cyclone5_vining_fpga.dtb ${KERNEL_IMAGETYPE} extlinux.conf;extlinux/extlinux.conf "' >> conf/bblayers.conf
echo 'CORE_IMAGE_EXTRA_INSTALL += "openssh gdbserver"' >> conf/local.conf

bitbake core-image-minimal
ln -s $ROOTFS_TOP/cv/build/tmp/deploy/images/cyclone5/core-image-minimal-cyclone5.rootfs.tar.gz $LINUX_BIN/a9/

The following files will be added in the $LINUX_BIN/a9 folder:

File	Description
core-image-minimal-cyclone5.rootfs.tar.gz	Cyclone V rootfs tarball

Note: You can also use a Docker container to build the Yocto recipes, refer to Docker Yocto Build for details. When using a Docker container, it does not matter what Linux distribution or packages you have installed on your host, as all dependencies are provided by the Docker container.

Appendix 2 - Run U-Boot with the Debugger from Command Line

This section presents examples on how to run U-Boot with the Arm Development Studio from command line. This offers a simple and convenient way to run U-Boot and use it for example to program onboard flash.

Use the binaries built for Cyclone V - SoC Boot from SD Card example:

cd cv_example.sdmmc

1. Create debugger script:

cat <<EOT > cv_soc_devkit_ghrd/software/bootloader/run-u-boot.ds
# initialize system
stop
wait 5s
reset
stop
wait 5s
set trust-ro-sections-for-opcodes off

# load and run SPL
loadfile u-boot-socfpga/spl/u-boot-spl 0x0
start
wait
restore u-boot-socfpga/spl/u-boot-spl-dtb.bin binary 0xffff0000
tbreak spl_boot_device
# <- stop script here if you need to debug SPL
continue
wait 60s

# load and run U-Boot
delete
loadfile u-boot-socfpga/u-boot
start 
wait
restore u-boot-socfpga/u-boot.dtb binary &_end
# tbreak relocate_code
# continue
# wait 60s
# symbol-file "\$sdir/u-boot-socfpga/u-boot" ((gd_t*)\$r9)->reloc_off
# thbreak board_init_r
# continue
# wait 60s
# <- stop script here if you need to debug U-Boot
continue
EOT

2. Run jtagconfig to determine the connection parameters:

~/altera/25.1std/nios2eds/nios2_command_shell.sh jtagconfig
1) USB-BlasterII [3-3.1.3]
  4BA00477   SOCVHPS
  02D020DD   5CSEBA6(.|ES)/5CSEMA6/..

3. Run the debugger from command line, using the connection parameters reported above by jtagconfig (In this example: USB-BlasterII 3-3.1.3):

cd cv_soc_devkit_ghrd/software/bootloader
~/altera/25.1std/nios2eds/nios2_command_shell.sh \
/opt/arm/developmentstudio-2025.0-1/bin/armdbg  \
--cdb-entry="Altera SoC FPGA::Cyclone V SoC (Dual Core)::Bare Metal Debug::Bare Metal Debug::Debug Cortex-A9_0::USB-Blaster" \
--cdb-entry-param="rvi_address=USB-BlasterII on localhost [3-3.1.3]:USB-BlasterII 3-3.1.3" \
--continue_on_error=true \
--stop_on_connect=false \
-s run-u-boot.ds

4. The serial console will show SPL then U-Boot being run:

U-Boot 2025.07 (Oct 21 2025 - 07:31:19 +0000)
DDRCAL: Scrubbing ECC RAM (1024 MiB).
DDRCAL: SDRAM-ECC initialized success with 579 ms
Trying to boot from SPI

CPU:   Altera SoCFPGA Platform
FPGA:  Altera Cyclone V, SE/A6 or SX/C6 or ST/D6, version 0x0
BOOT:  QSPI Flash (3.0V)
       Watchdog enabled
DRAM:  1 GiB
Core:  33 devices, 18 uclasses, devicetree: separate
MMC:   dwmmc0@ff704000: 0
Loading Environment from MMC... Reading from MMC(0)... *** Warning - bad CRC, using default environment

In:    serial
Out:   serial
Err:   serial
Model: Altera SOCFPGA Cyclone V SoC Development Kit
Net:
Warning: ethernet@ff702000 (eth0) using random MAC address - be:28:da:b7:08:40
eth0: ethernet@ff702000
Hit any key to stop autoboot:  0
=> 

Appendix 3 - Debugging U-Boot with Arm DS Eclipse

This section presents examples of how to debug U-Boot with the Arm Development Studio Eclipse-based GUI.

1. Use the binaries built for Cyclone V SoC Boot from SD Card example:

cd cv_example.sdmmc/software/bootloader

2. Start the Arm Development Studio Eclipse-based GUI:

~/altera/25.1std/nios2eds/nios2_command_shell.sh \
/opt/arm/developmentstudio-2025.0-1/bin/armds_ide -data workspace &

Note: the above creates a new workspace in the cv_example.sdmmc/software/bootloader folder.

3. In Eclipse GUI, Go to Run > Debug Configurations to open the Debug Configurations window.

4. In the Debug Configurations window

• Select the Generic Arm C/C++ Application on the left panel and right-click it. From the menu that appears, select New Configuration.
• Edit the Name field from "New_configuration" to something more descriptive, such as "Debug Cyclone V Bootloader"

5. In the Connection tab:

• Go to Select target section and select Altera® SoC FPGA > Cyclone V SoC (Dual Core) > Bare Metal Debug > Debug Cortex-A9_0
• Select the Target Connection to be USB Blaster
• Click the Bare Metal Debug > Connection > Browse button and select your cable.

The Debug Configurations window should now look like this:

6. Go to the Debugger tab, and do the following

• Select Connect Only
• Check Execute debugger commands and enter the following commands:

# initialize system
stop
wait 5s
reset
stop
wait 5s
set trust-ro-sections-for-opcodes off

# load and start SPL
loadfile u-boot-socfpga/spl/u-boot-spl 0x0
start
wait
restore u-boot-socfpga/spl/u-boot-spl-dtb.bin binary 0xffff0000

• Uncheck Host working directory > Use default and edit the value to add "/../" so that it looks in the parent folder of the workspace

The Debug Configurations window should now look like this:

7. Click the Debug button. Arm Development Studio will run the debug commands, therefore downloading the SPL to board and starting it. The Eclipse window should now look like this:

8. At this point you can use standard debug techniques to debug U-Boot SPL: viewing registers, variables, putting breakpoints, running step-by-step, etc.

9. Debugging U-Boot is similiar to debugging SPL, just that a different script is used, as shown below:

# initialize system
stop
wait 5s
reset
stop
wait 5s
set trust-ro-sections-for-opcodes off

# load SPL and run up until spl_boot_device
loadfile u-boot-socfpga/spl/u-boot-spl 0x0
start
wait
restore u-boot-socfpga/spl/u-boot-spl.dtb binary &__bss_end
thbreak spl_boot_device
continue
wait 60s

# load and start U-Boot
delete
loadfile u-boot-socfpga/u-boot
start 
wait
restore u-boot-socfpga/u-boot.dtb binary &_end

# run until relocation, and adjust symbols accordingly
thbreak relocate_code
cont
wait 60s
symbol-file u-boot-socfpga/u-boot ((gd_t*)$r9)->reloc_off
thbreak board_init_r
continue
wait 60s

---

Last update: December 2, 2025
Created: July 7, 2025