Understanding the SBXG Library

SBXG heavily relies on its own library concept. It is a finite set of directories that conform to a well-specified file hierarchy. This file hierarchy is explained in the present document.

The following directory hierarchy exposes all the different directories recognized as being part of an SBXG library. Here, we assume the library is composed of a single directory, named sbxg/lib/:

sbxg/lib/
├── toolchains/
├── configs/
├── sources/
├── bootscripts/
├── images/
└── boards/

The toolchains/ subdirectory

The toolchains/ directory contains YAML files, each one describing a toolchain:

sbxg/lib/
└── toolchains
    └── *.yml

A toolchain file may contain the following paramters:

Name	Description
url	URL where to download the toolchain from
path	Extracted (tar -xf) directory
prefix	Cross-compilation prefix
arch	Linux and U-Boot architecture code name
xen_arch	Xen architecture code name
host	Typically, the prefix without underscore

When cross-compiling, all these parameters should be mandatory. Note however that native compilation currently relies on the trick that some of these parameters may be not set or set to an empty string.

The configs/ subdirectory

The configs/ directory contains three subdirectories. Each of them contains Kconfig files that are used by Linux, U-Boot and Xen to configure their build:

sbxg/lib/
└── configs
    ├── linux
    │   └── *
    ├── uboot
    │   └── *
    └── xen
        └── *

These files may or may not have an extension. By convention, their name should self-describe their purpose. For example, a Linux 4.14 configuration file that allows to compile minimal Xen guests (domus) may be named: linux-4.14-xen-domu-minimal.

The sources/ subdirectory

The sources/ directory contains four subdirectories. Each of them contains YAML files that describe how the various components (Linux, U-Boot, Xen and genimage) may be retrieved:

sbxg/lib/
└── sources
    ├── genimage
    │   └── *.yml
    ├── linux
    │   └── *.yml
    ├── uboot
    │   └── *.yml
    └── xen
        └── *.yml

A source file must contain the following paramters:

Name	Description
url	URL where to download the component from
path	Extracted (tar -xf) directory

The bootscripts/ subdirectory

The bootscripts/ directory contains Jinja2 template files that must program the U-Boot bootloader at boot-time. These files are associated with a templating context that is described in Templating Context. To learn more about bootscripts, please refer to U-Boot’s website.

sbxg/lib/
└── bootscripts
    └── *

These files may or may not have an extension. By convention, their name should self-describe their purpose, and the extension is always .j2 (but this is not mandatory). For example a boot script allowing U-Boot to boot a sunxi board may be named: boot-sunxi-default.j2.

The images/ subdirectory

The images/ directory contains Jinja2 template files that describe how a disk image must be generated by genimage. These files are associated with a templating context that is described in Templating Context.

sbxg/lib/
└── images
    └── *

These files may or may not have an extension. By convention, their name should self-describe their purpose, and the extension is always .j2 (but this is not mandatory). For example a genimage configuration describing a simple SDcard partitioning may be named: sdcard-simple.j2.

The boards/ subdirectory

The boards/ directory contains YAML files, each one describing a board:

sbxg/lib
└── boards
    └── *.yml

A board describes what low-level components should be compiled, and what binaries from these components should be used to generate a final disk image. This file may contain the following top-level entries:

Name	Description
toolchain	Name of the toolchain to be used.
genimage	Name of the genimage source to be used
linux	Name of the Linux kernel source to be used
linux_config	Name of the Linux Kconfig to be used
linux_image	Filename of the Linux executable (e.g. zImage)
linux_dtb	Filename of the Linux DTB to be used
uboot	Name of the U-Boot source to be used
uboot_config	Name of the U-Boot Kconfig to be used
uboot_image	Filename of the U-Boot executable
boot_script	Name of the bootscript to be templated
disk_image	Name of the genimage configuration to be templated
root	In the Kernel bootargs, path to the rootfs block device
rootfs	URL to the rootfs (.ext3) to be used in the image
linux_bootargs	Additional Linux bootargs to be specified