Struct DeviceSpec

pub struct DeviceSpec {

    pub id: String,
    pub aliases: Option<Vec<String>>,
    pub distro: Distro,
    pub vendor: String,
    pub arch: DeviceArch,
    pub soc_vendor: Option<String>,
    pub name: String,
    pub model: Option<String>,
    pub of_compatible: Option<String>,
    pub bsp_packages: Vec<String>,
    pub initrdless: bool,
    pub kernel_cmdline: Option<Vec<String>>,
    pub partition_map: PartitionMapType,
    pub num_partitions: u32,
    pub size: ImageVariantSizes,
    pub partitions: Vec<PartitionSpec>,
    pub bootloaders: Option<Vec<BootloaderSpec>>,
    pub file_path: PathBuf,
}

Device Specification

A device specification represents a specific model of device in the form of a specification file named device.toml. Most information defined in the device specification are used to build OS images for this device.

It describes various aspects of the device:

• How many partition the image of this device may contain, their sizes, filesystems.
• How many BSP packages for this device should be installed in addition to the standard system distribution.
• Whether the image of the device must have bootloaders applied, and how to apply them.
• Basic information, like its ID, vendor and model name.

It must be placed under the device-level directory of the device registry.

An optional post-installation script can be placed in the device-level directory to finalize the installation. This script runs after all BSP packages are installed, in the target OS.

One or more optional bootloader scripts can be placed in the device-level directory. Bootloader scripts run after the post-installation script, and also in the target OS.

Syntax

The device specification uses the TOML format.

Fields

id - Device ID

A string which identifies a specific device. Must be unique across the entire registry. It can be a combination of letters (a-z, A-Z), digits (0-9), hyphens (-) and underscores (_).

id = "rpi-9"

aliases - Device Aliases (Optional)

A list of strings that can also identify this specific device. Must be unique across the entire registry. Aliases follows the same naming restrictions.

alias = ["pi9", "pi9b"]

vendor - Device Vendor

A string that identifies the vendor of the device. Should be as same as the vendor-level directory name.

vendor = "raspberrypi"

arch - Device CPU Architecture

A string defines the architecture of the CPU used by this device.

Possible values:

• "amd64": x86-64 CPU.
• "arm64": ARM AArch64 CPU.
• "loongarch64": LoongArch64 CPU.
• "riscv64": 64-Bit RISC-V CPU.
• "ppc64el": IBM POWER 8 and up, little-endian.
• "loongson3": MIPS Loongson-III CPU.

arch = "arm64"

name - Name of the device

The human-friendly name of the device.

name = "Raspberry Pi 9 Model B"

of_compatible - compatible Property in the Device Tree (Optional)

The most relevant string in the /compatible property defined in the root of the device tree file. Typically it is the first value of the entry.

If this device does not have a device tree, or the device tree file does not have compatible property defined in its root, this field can be skipped.

For example, suppose the device tree file of the “Raspberry Pi 9 Model B” has the following definition:

/ {
compatible = "raspberrypi,9-model-b", "brcm,bcm9999";
}

The value used here would be "raspberrypi,9-model-b".

of_compatible = "raspberrypi,9-model-b"

bsp_packages - List of mandatory BSP packages

A list of package names to be installed in addition to the standard system distribution.

Installation of BSP packages will be performed after all mountable partitions in this device are mounted, so that scripts in the packages can access these partitions.

The package names can not be checked for validity. Please make sure all of the names are correct.

bsp_packages = ["linux+kernel+rpi64+rpi9", "rpi-firmware-boot"]

initrdless - Booting without Init Ramdisk (Optional)

A boolean value describes whether the device boots without an init ramdisk. Typically this is useful for a variety of embedded devices.

Default is false, can be skipped. If set to true, then the following thing will happen:

• The filesystem table /etc/fstab will be generated using the unique identifiers of the partition (PARTUUID), rather than unique identifiers of the filesystem (UUID).

initrdless = true

kernel_cmdline - Kernel command line (Optional)

List of strings representing the kernel command line. Can not contain white spaces, and cannot contain root= argument.

The root= command line is automatically generated using either PARTUUID or UUID, depending on whether the device boots without an initrd image.

The final kernel command line will be root= argument concatenated with rest of the arguments.

If this field is defined, the post installation script and any bootloader scripts will be able to reference it with $KERNEL_CMDLINE.

If you want to generate the kernel command line yourself with a script, please skip this field.

# The final command line $KERNEL_CMDLINE:
# "root=PARTUUID=01234567-89ab-cdef-0123-456789abcdef console=ttyS0,115200 console=tty0 rw fsck.repair=yes"
kernel_cmdline = ["console=ttyS0,115200", "console=tty0", "rw", "fsck.repair=yes"]

[sizes] - Image sizes for each variant

An object describes the image size for each distribution variant: base, desktop and server.

Make sure the sizes defined are large enough to contain the OS and installed BSP packages.

The images will be automatically expanded to the size of the medium during the first boot.

[sizes]
base = 6144
desktop = 22500
server = 6144

partition_map - Partition Table Type

Type of the partition table used in the OS image.

Possible values:

• mbr or dos: MBR Partition Table. Can have up to 4 partitions.
• gpt: GUID Partition Table. Can have up to 128 partitions. Most bootloaders supports GPT.

partition_map = "gpt"

num_partitions - Number of the partitions

A positive integer. Defines the number of the partitions in the OS image.

num_partitions: 2

[[partition]] - List of Partitions

A list of objects describes the partitions in the OS image. Refer to the PartitionSpec for details.

[[partition]]
no = 1
type = "esp"
usage = "boot"
size = 614400
mountpoint = "/efi"
filesystem = "fat32"
label = "Boot"
fs_label = "Boot"

[[partition]]
no = 2
type = "linux"
size = 0
mountpoint = "/"
filesystem = "ext4"
usage = "rootfs"
fs_label = "AOSC OS"

[[bootloader]] - List of Bootloaders to be embedded (Optional)

A list of objects describes bootloaders to be applied onto the OS image. Refer to BootloaderSpec for details.

[[bootloader]]
type = "flash_partition"
path = "/usr/lib/u-boot/rk3588-orange-pi-4-ultra-idbloader.img"
partition = 1

[[bootloader]]
type = "flash_partition"
path = "/usr/lib/u-boot/rk3588-orange-pi-4-ultra-u-boot.itb"
partition = 2

[[bootloader]]
type = "script"
name = "finish-bootloaders.sh"

Process of building images

1. This device gets selected in the registry.
2. An OS image is created with specified size, and is attached to a loop device.
3. The image is partitioned.
4. Partitions with filesystem assigned to them is formatted.
5. Filesystems with a mountpoint will be mounted.
6. The standard system distribution is installed to the target filesystem, and /etc/fstab is generated.
7. BSP packages is installed.
8. The post-installation script is run.
9. The bootloaders will be applied, if defined in the spec file.
10. The image is unmounted, detached from the loop device, and is compressed to the output directory.

Post Installation

An optional post installation script can be run after:

• All of the filesystems with a mount point are mounted.
• The standard system distribution is installed.
• All of the BSP packages gets installed.
• /etc/fstab is generated.
• A user is set up.

The post installation script will be run within the target OS image. The script name must be one of:

• postinst.bash
• postinst.sh
• postinst (The shebang is not interpreted, thus must be a shell script)

Available defined variables

There are a few variables pre-defined in the environment to aid your setup process:

• DEVICE_ID: Device ID.

• DEVICE_COMPATIBLE: of_compatible field defined in the device specification. Empty if not defined.

• LOOPDEV: The loop device this OS image is attached on.

• NUM_PARTITIONS: Number of the partitions.

• ROOTPART: The index of the root partition.

• DISKLABEL: Either mbr or gpt.

• DISKUUID: UUID of the partition table.

  Either a 32-bit hexadecimal integer or an UUID (Same as the output of blkid).

• KERNEL_CMDLINE: Full kernel command line with root= argument. Empty if not defined in the spec file.

• PARTx_PARTUUID: Partition UUID of the xth partition.

  Same as the output of blkid, can be used directly with root=PARTUUID= argument.

• PARTx_FSUUID: Filesystem UUID of the xth partition.

  Same as the output of blkid, can be used directly with root=UUID= argument. Empty if this partition does not contain a filesystem.

• BOOT_PARTUUID, BOOT_FSUUID: Partition and Filesystem UUID for the boot partition, if one is found.

• ROOT_PARTUUID, ROOT_FSUUID: Partition and Filesystem UUID for the root partition.

Examples

Please refer to the device registry directory in the project for examples.

Fields

id: String

Unique ID of the device. Can be any combination of letters, digits, hyphen "-" and underscore ("_").

aliases: Option<Vec<String>>

Optional aliases to identify the exact device. Can be any combination of letters, digits, hyphen "-" and underscore ("_").

distro: Distro

The distribution wich will be installed on this device.

Possible values:

• aosc: AOSC OS.

vendor: String

Vendor of the device. Can be any combination of letters, digits, hyphen "-" and underscore ("_").

arch: DeviceArch

CPU Architecture of the device.

Possible values:

• amd64
• arm64
• loongarch64
• loongson3
• ppc64el
• riscv64
• mips64r6el

soc_vendor: Option<String>

Vendor of the SoC platform, optional, currently not used. The name must present in arch/$ARCH/boot/dts in the kernel tree.

name: String

Full name of the device for humans.

model: Option<String>

Model name of the device, if it is different than the full name.

of_compatible: Option<String>

The most relevant value of the `compatible`` property defined in the root of the device tree, if present. Otherwise just skip this.

For example, the device tree file of Raspberry Pi 5B defines the following:

/ {
	compatible = "raspberrypi,5-model-b", "brcm,bcm2712";
}

In this case, the value would be "raspberrypi,5-model-b".

bsp_packages: Vec<String>

List of BSP packages to be installed. Must be a list of valid package names, no checks are performed.

initrdless: bool

Whether the device boots without an initrd image. Useful for embedded systems (most of devices targeted by this project are embedded systems, aren’t they).

If set to true, the following thing(s) will happen:

• Generated fstab will use PARTUUID instead of filesystem UUID, since the kernel does not support using UUID= to specify root device if initrd is not being used.

kernel_cmdline: Option<Vec<String>>

Kernel command line. Must be a list of strings, and root= must not present in this list (it is automatically generated).

partition_map: PartitionMapType

The partition map used for the image.

Possible values:

• mbr or dos
• gpt

num_partitions: u32

Number of the partitions.

size: ImageVariantSizes

Size of the image for each variant, in MiB.

Example

[size]
base = 6144
desktop = 22528
server = 6144

partitions: Vec<PartitionSpec>

Partitions in the image. Refer to PartitionSpec for details.

Due to how lists of objects are represented in TOML, the singular “partition” is explicitly allowed.

Example

[[partition]]
num = 1
size = 614400
type = "esp"
filesystem = "fat32"
...

[[partition]]
num = 2
size = 0
type = "linux"
filesystem = "ext4"
...

bootloaders: Option<Vec<BootloaderSpec>>

Actions to apply bootloaders. Refer to BootloaderSpec for details.

Due to how lists of objects are represented in TOML, the singular “bootloader” is explicitly allowed.

Example

[[bootloader]]
type = "script"
script = "apply-bootloader.sh"

[[bootloader]]
type = "script"
script = "apply-bootloader2.sh"

file_path: PathBuf

Path to the device.toml.

This field is ignored during deserialization, and is automatically filled.

Implementations

impl DeviceSpec

pub fn from_path(file: &Path) -> Result<Self>

pub fn check(&self) -> Result<()>

pub fn gen_kernel_cmdline(&self, pm_data: &PartitionMapData) -> Result<String>

Trait Implementations

impl Clone for DeviceSpec

fn clone(&self) -> DeviceSpec

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DeviceSpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for DeviceSpec

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.