Skip to content

HPS GSRD User Guide for the Stratix® 10 SX SoC Development Kit

NOTE: This page is not available in this release. The latest release in which this page is supported corresponds to 25.3. Please refer to the following page to access the latest documentation: HPS GSRD User Guide for the Stratix® 10 SX SoC Development Kit.

The kernel.itb file is a Flattattened Image Tree (FIT) file that includes the following components:

  • Linux kernel.
  • Several board configurations that indicate what components from the kernel.itb (Linux kernel, device tree and 2nd Phase fabric design) should be used for a specific board.
  • Linux device tree*.
  • 2nd Phase Fabric Design*.

* One or more of these components to support the different board configurations.

The kernel.itb is created from a .its (Image Tree Source file) that describes its structure. In the GSRD, the kernel.itb file is located in the following directory, where you can find also all the components needed to create it, including the .its file:

  • $TOP_FOLDER/gsrd-socfpga/<device-devkit>-gsrd-rootfs/tmp/work/<device-devkit>-poky-linux/linux-socfpga-lts/<linux branch>+git/linux-<device devkit>-standard-build/

If you want to modify the kernel.itb by replacing one of the component or modifying any board configuration, you can do the following:

  1. Install mtools package in your Linux machine. 

    $ sudo apt update
$ sudo apt install mtools

  2. Go to the folder in which the kernel.itb is being created under the GSRD. 

    $ cd $TOP_FOLDER/gsrd-socfpga/<device-devkit>-gsrd-rootfs/tmp/work/<device-devkit>-poky-linux/linux-socfpga-lts/<linux branch>+git/linux-<device-devkit>-standard-build/
$ ls *.its
fit_kernel_<device-devkit>.its

  3. In the .its file, observe the components that integrates the kernel.itb identifying the nodes as indicated next:

    images node:
    - kernel node - Linux kernel defined with the data parameter in the node.
    - fdt-X node - Device tree X defined with the data parameter in the node.
    - fpga-X node - 2nd Phase FPGA Configuration .rbf defined with the data parameter in the node.

    configurations node:
    - board-X node - Board configuration with the name defined with the description parameter. The components for a specific board configuration are defined with the kernel, fdt and fpga parameters.

  4. In this directory, you can replace any of the files corresponding to any of the components that integrate the kernel.itb, or you can also modify the .its to change the name/location of any of the components or change the board configuration.

  5. Finally, you need to re-generate the new kernel.itb as indicated next. 

    $ rm kernel.itb
$ mkimage -f fit_kernel_<device-devkit>.its kernel.itb

At this point you can use the new kernel.itb as needed. Some options could be:

  • Use U-Boot to bring it to your SDRAM board through TFTP to boot Linux or to write it to a SD Card device
  • Update the flash image (QSPI, SD Card, eMMC or NAND) from your working machine.

How to Manually Update the Content of the SD Card Image

As part of the Yocto GSRD build flow, the SD Card image is built for the SD Card boot flow. This image includes a couple of partitions. One of these partition (a FAT32) includes the U-Boot proper, a Distroboot boot script and the Linux .itb - which includes the Linux kernel image, , the Linux device tree, the phase 2 FPGA configuration bitstream and board configuration (there may be several versions of these last 3 components). The 2nd partition (an EXT3 or EXT4 ) includes the Linux file system.

If you want to replace any the components or add a new item in any of these partitions, without having to run again the Yocto build flow.

This can be done through the wic application available on the Poky repository that is included as part of the GSRD build directory: $TOP_FOLDER/gsrd-socfpga/poky/scripts/wic

This command requires to be run in the Yocto build environment that can be setup as shown next in a Linux terminal: 

cd $TOP_FOLDER/gsrd-socfpga/
source poky/oe-init-build-env build
You can verify that the Yocto environment has been setup using the which bitbake command, which will respond with the path of the bitbake command located at poky/bitbake/bin/bitbake.

The wic command allows you to inspect the content of a SD Card image, delete, add or replace any component inside of the image. This command is also provided with help support:

$ $TOP_FOLDER/gsrd-socfpga/poky/scripts/wic help

Creates a customized OpenEmbedded image.

Usage:  wic [--version]
        wic help [COMMAND or TOPIC]
        wic COMMAND [ARGS]

    usage 1: Returns the current version of Wic
    usage 2: Returns detailed help for a COMMAND or TOPIC
    usage 3: Executes COMMAND

COMMAND:

 list   -   List available canned images and source plugins
 ls     -   List contents of partitioned image or partition
 rm     -   Remove files or directories from the vfat or ext* partitions
 help   -   Show help for a wic COMMAND or TOPIC
 write  -   Write an image to a device
 cp     -   Copy files and directories to the vfat or ext* partitions
 create -   Create a new OpenEmbedded image
 :
 :
The following steps show you how to replace the kernel.itb file inside of the fat32 partition in a .wic image.

  1. The wic ls command allows you to inspect or navigate over the directory structure inside of the SD Card image. For example you can observe the partitions in the SD Card image in this way:

    # Here you can inspect the content a wic image see the 2 partitions inside of the SD Card image
$ $TOP_FOLDER/gsrd-socfpga/poky/scripts/wic ls my_image.wic
Num     Start        End          Size      Fstype
1       1048576    525336575    524288000  fat32    
2     525336576   2098200575   1572864000  ext4   

# Here you can naviagate inside of the partition 1
$ $TOP_FOLDER/gsrd-socfpga/poky/scripts/wic ls my_image.wic:1
Volume in drive : is boot       
Volume Serial Number is 9D2B-6341
Directory for ::/

BOOTSC~1 UIM      2431 2011-04-05  23:00  boot.scr.uimg
kernel   itb  15160867 2011-04-05  23:00 
u-boot   itb   1052180 2011-04-05  23:00 
     3 files          16 215 478 bytes
                     506 990 592 bytes free

  2. The wic rm command allows you to delete any of the components in the selected partition. For example, you can delete the kernel.itb image from the partition 1(fat32 partition).

    $ $TOP_FOLDER/gsrd-socfpga/poky/scripts/wic rm my_image.wic:1/kernel.itb

  3. The wic cp command allows you to copy any new item or file from your Linux machine to a specific partition and location inside of the SD Card image. For example, you can copy a new kernel.itb to the partition 1.

    $ $TOP_FOLDER/gsrd-socfpga/poky/scripts/wic cp <path_new_kernel.itb> my_image.wic:1/kernel.itb

NOTE: The wic application also allows you to modify any image with compatible vfat and ext* type partitions which also covers images used for eMMC boot flow.

Notices & Disclaimers

Altera® Corporation technologies may require enabled hardware, software or service activation. No product or component can be absolutely secure. Performance varies by use, configuration and other factors. Your costs and results may vary. You may not use or facilitate the use of this document in connection with any infringement or other legal analysis concerning Altera or Intel products described herein. You agree to grant Altera Corporation a non-exclusive, royalty-free license to any patent claim thereafter drafted which includes subject matter disclosed herein. No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document, with the sole exception that you may publish an unmodified copy. You may create software implementations based on this document and in compliance with the foregoing that are intended to execute on the Altera or Intel product(s) referenced in this document. No rights are granted to create modifications or derivatives of this document. The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. Altera disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade. You are responsible for safety of the overall system, including compliance with applicable safety-related requirements or standards. © Altera Corporation. Altera, the Altera logo, and other Altera marks are trademarks of Altera Corporation. Other names and brands may be claimed as the property of others.

OpenCL* and the OpenCL* logo are trademarks of Apple Inc. used by permission of the Khronos Group™.

--->

Last update: April 8, 2026
Created: November 27, 2024
Ask in the Forum