uSD Image Builder

Scripts to build uSD images for NDI demo platforms based on Debian.

File

Description

README.md

This file

CHANGELOG.md

List of notable changes

a10-socdk.conf

Config file for Arria-10 SoC Development Kit

sockit.conf

Config file for SoCKit image

zcu104.conf

Config file for ZCU104

zybo.conf

Config file for Zybo-Z7-20 and Arty-Z7-20

build.sh

Main image build script

common.sh

Functions common to several scripts

boot.sh

Extracts boot files from a PetaLinux project

debootstrap.sh

Creates a Debian root filesystem from scratch

second-stage.sh

The debootstrap second-stage and rootfs customizations

mk.uSD.sh

Creates a uSD image from boot files and a rootfs

part.txt

Partion table for the uSD

part.a2.txt

Partion table for uSD images with Altera A2 partition

update.*.tgz.sh

Example to generate optional tgz files

The build scripts are based on a config script which provides details needed to create an image. The main details required are a pointer to the boot files and various architecture specific information (eg: the Debian architecture name and the qemu static binary to use for an emulated chroot environment). Various other settings may be tweaked as well, including the uSD target size, system host name, etc. Refer to the existing *.conf files for details.

Build Dependencies

debootstrap
Used to create a root filesystem image. Currently using version 1.0.128nmu2 with Debian 12 (bullseye). Many operating systems ship with an older version of debootstrap that is available through their package managers. It is recommended that a more recent version be installed from a preexisting .deb package. See for more details.
qemu-static
Required to run debootstrap second-stage. Currently tested with version 4.2.1. Note that transparent emulation needs to be set up on the host system. See the QEMU documentation for more details on how to configure this.

Build an image

To build an image from scratch, simply run the build.sh script with the desired configuration specified:

./build.sh zcu104.conf

Rebuild an image

It is often not necessary to run all steps from scratch. Once an initial build has created the required bootfs and rootfs directories, each component of the uSD image may be updated independently. The components that makeup the uSD image are:

bootfs.<board>/
This directory contains the Xilinx boot files and linux kernel modules extracted from the PetaLinux project. This directory is created and updated by running the boot.sh script.
../linux_kernel/<board>/boot
This directory contains the Altera boot files and linux kernel modules. This directory is created and updated by running make in the ../linux_kernel/<board> directory.
root.<deb_arch>.tgz
This file is manually generated and if present will be extracted to the root directory of the target file-system by the root user. This is currently used to install pre-compiled NDI example binaries to /usr/local/bin and the required shared libraries to /usr/local/lib.
This file is processed by the second-stage.sh script, so any changes require re-running debootstrap.sh or manually applying the changes to the rootfs directory.
Note this file should include full paths preceded by a leading ./ eg: ./usr/local/lib/file.so. Below is one example of how to properly create this file:
```
# Start at the root directory
cd /

# Create a tar archive with a leading ./ and put it in /tmp
tar -czvf /tmp/root.armhf.tgz ./usr/local/bin/*
```
user.<deb_arch>.tgz
This file is similar to the root.<deb_arch>.tgz file, above, except it is extracted into the default user's home directory by the default user. This file is used to install the HDMI start and stop scripts for the ZCU104, and is unused by the Zybo-Z7-20 example. Place any files that need to be owned by the default user and thus cannot be placed in the root archive (since the default username, uid/gid, and home directory may change) into this archive.
This file is processed by the second-stage.sh script, so any changes require re-running debootstrap.sh or manually applying the changes to the rootfs directory.
rootfs.<deb_arch>/
This directory contains a stock Debian install generated by debootstrap along with some modifications required to make a usable image (eg: create /etc/fstab and enable networking) and tweaks required for this example (eg: build and install the libuio package). This directory is generated by running the debootstrap.sh script, while most of the customizations to the rootfs occur in the second-stage.sh script.
Running debootstrap.sh deletes any existing rootfs and recreates it from scratch, which is a lengthy process and does not allow for modifications other than editing the second-stage.sh script. Once created, however, the rootfs directory may be edited manually, just be careful with file-system permissions and user ids. It is also possible to chroot to the rootfs and execute native commands, eg:
```
# Setup shell variables for our configuration
source zcu104.conf

# Open a native shell in the rootfs
sudo LANG=C.UTF-8 chroot $ROOTFS /bin/bash
```

Once any desired changes have been made to the above components, a new image can be created by running:

sudo ./mk.uSD.sh <config>.conf

Last updated 5 months ago

Was this helpful?

Build Dependencies

debootstrap

Used to create a root filesystem image. Currently using version 1.0.128nmu2 with Debian 12 (bullseye). Many operating systems ship with an older version of debootstrap that is available through their package managers. It is recommended that a more recent version be installed from a preexisting .deb package. See for more details.

qemu-static

Required to run debootstrap second-stage. Currently tested with version 4.2.1. Note that transparent emulation needs to be set up on the host system. See the QEMU documentation for more details on how to configure this.

Rebuild an image

bootfs.<board>/

This directory contains the Xilinx boot files and linux kernel modules extracted from the PetaLinux project. This directory is created and updated by running the boot.sh script.

../linux_kernel/<board>/boot

This directory contains the Altera boot files and linux kernel modules. This directory is created and updated by running make in the ../linux_kernel/<board> directory.

root.<deb_arch>.tgz

This file is manually generated and if present will be extracted to the root directory of the target file-system by the root user. This is currently used to install pre-compiled NDI example binaries to /usr/local/bin and the required shared libraries to /usr/local/lib.

This file is processed by the second-stage.sh script, so any changes require re-running debootstrap.sh or manually applying the changes to the rootfs directory.

Note this file should include full paths preceded by a leading ./ eg: ./usr/local/lib/file.so. Below is one example of how to properly create this file:

# Start at the root directory
cd /

# Create a tar archive with a leading ./ and put it in /tmp
tar -czvf /tmp/root.armhf.tgz ./usr/local/bin/*

user.<deb_arch>.tgz

This file is similar to the root.<deb_arch>.tgz file, above, except it is extracted into the default user's home directory by the default user. This file is used to install the HDMI start and stop scripts for the ZCU104, and is unused by the Zybo-Z7-20 example. Place any files that need to be owned by the default user and thus cannot be placed in the root archive (since the default username, uid/gid, and home directory may change) into this archive.

This file is processed by the second-stage.sh script, so any changes require re-running debootstrap.sh or manually applying the changes to the rootfs directory.

rootfs.<deb_arch>/

This directory contains a stock Debian install generated by debootstrap along with some modifications required to make a usable image (eg: create /etc/fstab and enable networking) and tweaks required for this example (eg: build and install the libuio package). This directory is generated by running the debootstrap.sh script, while most of the customizations to the rootfs occur in the second-stage.sh script.

Running debootstrap.sh deletes any existing rootfs and recreates it from scratch, which is a lengthy process and does not allow for modifications other than editing the second-stage.sh script. Once created, however, the rootfs directory may be edited manually, just be careful with file-system permissions and user ids. It is also possible to chroot to the rootfs and execute native commands, eg:

# Setup shell variables for our configuration
source zcu104.conf

# Open a native shell in the rootfs
sudo LANG=C.UTF-8 chroot $ROOTFS /bin/bash

Once any desired changes have been made to the above components, a new image can be created by running:

sudo ./mk.uSD.sh <config>.conf