Skip to content

Modify the Root Filesystem

The E31X OSP includes a Linux boot image based off the Xilinx PetaLinux Pre-build image. The image includes a minimal root filesystem which is loaded as a ramdisk at boot time. This means that any changes made during runtime are not persistent and will be cleared when the unit is reset.

To make a persistent change, the root filesystem itself must be changed. Xilinx uses Flattened uImage Tree (FIT) images to store the kernel, root filesystem, and device tree in a single file. To modify the root filesystem, it must be first extracted from the FIT image. After extraction and modification, the FIT image must be then rebuilt.

Step 1 - Extract

Examine the default image

After using ocpiadmin deploy, the default SD card files can be found in $OCPI_ROOT_DIR/exports/e31x/sdcard-xilinx19_2_aarch32/. In this directory the image.ub file is the FIT image containing the root filesystem. Change into this directory and optionally examine the FIT image using the dumpimage tool.

cd $OCPI_ROOT_DIR/exports/e31x/sdcard-xilinx19_2_aarch32/
/tools/Xilinx/git/u-boot-xlnx/tools/dumpimage -l image.ub

Extract the FIT Image

The E31X FIT image contains the kernel, root filesystem, and device tree. All of these need to be extracted.

mkdir fit_image
# Extract the Kernel
/tools/Xilinx/git/u-boot-xlnx/tools/dumpimage -T flat_dt -p 0 -i image.ub fit_image/Image
# Extract the device tree blob
/tools/Xilinx/git/u-boot-xlnx/tools/dumpimage -T flat_dt -p 1 -i image.ub fit_image/system.dtb
# Extract the ramdisk
/tools/Xilinx/git/u-boot-xlnx/tools/dumpimage -T flat_dt -p 2 -i image.ub fit_image/ramdisk.cpio.gz

Extract the root filesystem

The root filesystem is held within a compressed cpio archive. This can be decompressed using gnuzip, and extracted using cpio.

cd fit_image
gunzip ramdisk.cpio.gz
mkdir ramdisk
cd ramdisk
cpio -i -F ../ramdisk.cpio
rm ../ramdisk.cpio

Step 2 - Modify

Now that the root filesystem has been extracted, you can add, remove, and modify files as required.

One common modification is to add in a hook to automatically run a script, located on the SD card, at boot time. This can be useful to persistently apply changes to the root filesystem at boot time.

Setup an autorun script

In the Xilinx image, the root of the SD card is mounted at /run/media/mmcblk0p1/, so running the following commands will run an script at boot time.

# In root of extracted ramdisk
ln -s ../init.d/ etc/rc5.d/
ln -s /run/media/mmcblk0p1/ etc/init.d/

Remember to add an file to the root of the FAT partition on the SD card later. and make sure to chmod +x

Step 3 - Compress

Compress the root filesystem

# In root of extracted ramdisk
sh -c "find . | cpio -o -c -R root:root" | gzip -9 > ../ramdisk.cpio.gz
cd ..
rm -rf ramdisk

Generate new FIT image

In the fit_image directory created earlier, make a new file called image.its, and copy the following text inside it:


/ {
    description = "U-Boot fitImage for plnx_aarch32 kernel";
    #address-cells = <1>;

    images {
        kernel@0 {
            description = "Linux Kernel";
            data = /incbin/("./Image");
            type = "kernel";
            arch = "ARM";
            os = "linux";
            compression = "none";
            load = <0x8000>;
            entry = <0x8000>;
            hash@1 {
                algo = "sha1";
        fdt@0 {
            description = "Flattened Device Tree blob";
            data = /incbin/("./system.dtb");
            type = "flat_dt";
            arch = "ARM";
            compression = "none";
            hash@1 {
                algo = "sha1";
        ramdisk@0 {
            description = "ramdisk";
            data = /incbin/("./ramdisk.cpio.gz");
            type = "ramdisk";
            arch = "ARM";
            os = "linux";
            compression = "gzip";
            hash@1 {
                algo = "sha1";
    configurations {
        default = "conf@1";
        conf@1 {
            description = "Boot Linux kernel with FDT blob + ramdisk";
            kernel = "kernel@0";
            fdt = "fdt@0";
            ramdisk = "ramdisk@0";
            hash@1 {
                algo = "sha1";

To create the new FIT image, use the mkimage application:

# In the fit_image directory created earlier with Image, system.dtb, ramdisk.cpio.gz files in it run:
/tools/Xilinx/git/u-boot-xlnx/tools/mkimage -f image.its image.ub

Replace the original image.ub file with the newly generated one on the root of the SD card.

Create autorun script

If you have modified the root filesystem to run an autorun script on boot, you must create an file on the root of the SD card. For example to set a fixed IP address:

ifconfig eth0
Make sure the file is executable.
chmod +x