Add build-dtb-image.sh for combined DTB FAT image generation

[bjordiscollaku]

Summary

Introduce build-dtb-image.sh, a standalone tool to generate a
FAT-formatted image containing a single combined DTB for Qualcomm-based
ARM64 platforms. The tool consumes a manifest of DTBs, validates and
concatenates them into a single combined-dtb.dtb, and packages that
artifact into a minimal FAT image suitable for boot flows and CI
pipelines.

Details

Inputs and manifest handling

The script is driven by two required inputs:

• -dtb-src: DTB source directory (e.g. arch/arm64/boot/dts/qcom)
• -manifest: manifest file listing DTB filenames (one per line)

Key behaviors:

• Manifest entries may be:
  • Absolute paths to .dtb files, or
  • Relative paths resolved against -dtb-src.
• Blank lines and lines starting with # are ignored.
• Entries are normalized into a temporary sanitized list:
  • Stored in a mktemp-generated file.
  • Used as the single source of truth for subsequent validation and
    concatenation.

Validation performed:

• The manifest file must exist and produce at least one valid DTB entry
  (non-empty, non-comment).
• Every DTB path in the sanitized list must exist on disk.
• The -size argument, if provided, must be a positive integer (MB).

Combined DTB generation

After sanitization and validation, the script:

• Concatenates all DTBs in manifest order into:
  • <DTB_SRC>/combined-dtb.dtb
• Uses xargs -a to preserve ordering and avoid unnecessary subshells.
• Logs the resulting file (size and path) for traceability.

This keeps a deterministic combined DTB artifact in the DTB source tree
while providing a single binary blob for downstream consumers.

FAT image creation and layout

The tool then creates a FAT filesystem image and deploys the combined
DTB:

• Image size:
  • Configurable via -size (MB).
  • Defaults to 4 MB.
• Implementation details:
  • Uses dd to create a zeroed image file of the requested size.
  • Attaches it to a loop device via losetup --show -fP.
  • Formats the loop device with mkfs.vfat.
  • Mounts the device on a mktemp-generated mount directory.
  • Copies combined-dtb.dtb into the root of the FAT filesystem.

Resulting layout inside the FAT image:

• /combined-dtb.dtb only (no additional files or directories).

This keeps the on-image structure minimal and unambiguous for boot
firmware or test infrastructure.

Robust cleanup and error handling

To avoid leaking loop devices or mountpoints and to make the tool safe
for CI and repeated local use, the script:

• Installs a global EXIT trap at startup.
• Implements a cleanup() routine that:
  • Preserves and re-uses the original process exit status.
  • Runs sync best-effort before teardown.
  • Unmounts the temporary mountpoint only if it exists and is
    currently mounted (mountpoint -q).
  • Detaches the loop device only if it was successfully created.
  • Removes the temporary mount directory and sanitized manifest file
    if present.

With set -euo pipefail and these guards in place, the script:

• Fails fast on invalid input or failed system calls.
• Leaves the system in a clean state (no dangling loop devices or
  stale mountpoints) even on error paths.

Usage

Basic example:

./build-dtb-image.sh \
  -dtb-src arch/arm64/boot/dts/qcom \
  -manifest dtb-manifest \
  -size 4 \
  -out dtb.bin