Add example splash screen support

examples/splash-screen/.gitkeep

@@ -0,0 +1,5 @@
+# This directory contains the splash screen example
+# Files in this directory:
+# - config/splash-demo.yaml  - Example configuration
+# - README.adoc              - Comprehensive documentation
+# - README.md                - Quick reference

examples/splash-screen/config/splash-demo.yaml

@@ -0,0 +1,39 @@
+# Splash Screen Demo Configuration
+#
+# This example demonstrates adding a custom boot splash screen to Raspberry Pi OS.
+#
+# To build this image:
+#   ./rpi-image-gen build -c examples/splash-screen/config/splash-demo.yaml
+#
+# The image will be created at:
+#   work/image-deb13-arm64-splash/deb13-arm64-splash.img
+#
+# Before building, create your splash screen (24-bit TGA, max 1920x1080, <224 colours):
+#   ./layer/rpi/splash-screen/EXAMPLE-splash.sh "Your Text" splash.tga
+#
+# Then update the image_path below to point to your splash screen.
+
+device:
+  layer: rpi5
+
+image:
+  layer: image-rpios
+  boot_part_size: 200%
+  root_part_size: 300%
+  name: deb13-arm64-splash
+
+layer:
+  base: trixie-minbase
+  splash: rpi-splash-screen
+
+splash:
+  # Path to your custom splash screen image (24-bit TGA, max 1920x1080, <224 colours)
+  # Leave empty or comment out to skip splash screen installation
+  # Can be absolute or relative to the project root
+  image_path: examples/splash-screen/demo-splash.tga
+
+  # Skip image validation checks (not recommended for production)
+  skip_image_checks: n
+
+  # Automatically update /boot/firmware/cmdline.txt to enable splash
+  update_cmdline: y

layer/rpi/device/splash-screen/EXAMPLE-splash.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# Example script to generate a simple splash screen
+# Usage: ./EXAMPLE-splash.sh "Your Text" output.tga
+
+set -e
+
+if [ $# -lt 2 ]; then
+    echo "Usage: $0 <text> <output.tga>"
+    echo "Example: $0 'Welcome to My Pi' splash.tga"
+    exit 1
+fi
+
+TEXT="$1"
+OUTPUT="$2"
+
+# Check if ImageMagick is installed
+if ! command -v convert &> /dev/null; then
+    echo "Error: ImageMagick is required but not installed"
+    echo "Install it with: sudo apt install imagemagick"
+    exit 1
+fi
+
+echo "Creating splash screen with text: $TEXT"
+
+# Create a simple splash screen with centred text
+convert \
+    -size 1920x1080 \
+    xc:black \
+    -font DejaVu-Sans-Bold \
+    -pointsize 72 \
+    -fill white \
+    -gravity center \
+    -annotate 0 "$TEXT" \
+    -depth 8 \
+    -colors 224 \
+    -type truecolor \
+    "$OUTPUT"
+
+echo "Splash screen created: $OUTPUT"
+
+# Show file information
+file "$OUTPUT"
+identify "$OUTPUT"
+
+echo ""
+echo "To use this splash screen, update your config file:"
+echo ""
+echo "splash:"
+echo "  image_path: $(realpath "$OUTPUT")"
+

layer/rpi/device/splash-screen/splash-screen.adoc

@@ -0,0 +1,215 @@
+= rpi-splash-screen Layer
+:toc: left
+
+== Overview
+
+The `rpi-splash-screen` layer provides fullscreen splash screen support for Raspberry Pi devices. It configures the kernel and initramfs to display a custom image during boot, hiding kernel messages and providing a cleaner boot experience.
+
+== Features
+
+* **Fullscreen boot logo**: Display a custom image that covers the entire screen
+* **Early boot display**: Image appears as early as possible in the boot process
+* **Automatic configuration**: Handles initramfs and kernel command line setup
+* **Flexible validation**: Optional image checks can be skipped for testing
+* **Customisable behaviour**: Control whether cmdline.txt is automatically updated
+
+== How It Works
+
+The splash screen layer:
+
+1. Installs the `rpi-splash-screen-support` package containing the configuration tools
+2. Validates your splash image meets the technical requirements
+3. Copies the image to `/lib/firmware/logo.tga`
+4. Adds an initramfs hook to load the image early in boot
+5. Updates the kernel command line with required parameters
+6. Rebuilds the initramfs with the new configuration
+
+The splash screen uses the kernel's built-in `fullscreen_logo` functionality, which requires specific image formats and dimensions.
+
+== Technical Requirements
+
+=== Image Specifications
+
+* **Format**: TGA (Targa) image file
+* **Colour depth**: 24-bit
+* **Maximum dimensions**: 1920×1080 pixels
+* **Maximum colours**: 224 colours
+* **Compression**: Uncompressed
+
+=== Kernel Parameters
+
+The layer configures the following kernel command line parameters:
+
+* `fullscreen_logo=1`: Enable fullscreen logo display
+* `fullscreen_logo_name=logo.tga`: Specify the logo filename
+* `vt.global_cursor_default=0`: Hide the cursor
+
+== Configuration Variables
+
+The layer declares the following configuration variables with prefix `splash`:
+
+=== `image_path`
+
+* **Type**: String (path)
+* **Default**: `${DIRECTORY}/splash-screen/default-splash.tga`
+* **Required**: No (can be empty to skip installation)
+* **Description**: Path to the splash screen image file. Can be absolute or relative to the layer directory.
+
+=== `skip_image_checks`
+
+* **Type**: Boolean
+* **Default**: `n`
+* **Required**: No
+* **Description**: Skip validation of image dimensions, colour depth and colour count. Not recommended for production use.
+
+=== `update_cmdline`
+
+* **Type**: Boolean
+* **Default**: `y`
+* **Required**: No
+* **Description**: Automatically update `/boot/firmware/cmdline.txt` to enable the splash screen. Set to `n` if using custom boot configurations.
+
+== Usage Examples
+
+=== Basic Configuration
+
+[source,yaml]
+----
+layer:
+  base: trixie-minbase
+  splash: rpi-splash-screen
+
+splash:
+  image_path: /home/user/my-logo.tga
+----
+
+=== Skip Splash Installation
+
+[source,yaml]
+----
+layer:
+  base: trixie-minbase
+  splash: rpi-splash-screen
+
+splash:
+  image_path: ""  # Empty string skips installation
+----
+
+=== Custom Boot Configuration
+
+[source,yaml]
+----
+layer:
+  base: trixie-minbase
+  splash: rpi-splash-screen
+
+splash:
+  image_path: /path/to/splash.tga
+  update_cmdline: n  # Don't modify cmdline.txt automatically
+----
+
+=== Testing with Lenient Validation
+
+[source,yaml]
+----
+layer:
+  base: trixie-minbase
+  splash: rpi-splash-screen
+
+splash:
+  image_path: /path/to/test-splash.tga
+  skip_image_checks: y  # For testing only
+----
+
+== Creating Splash Images
+
+=== Using the Example Script (Quickest Method)
+
+The layer includes a helper script for quick testing:
+
+[source,bash]
+----
+# Generate a simple text-based splash screen
+./layer/rpi/splash-screen/EXAMPLE-splash.sh "Welcome to Raspberry Pi" splash.tga
+
+# The script creates a 1920×1080 black background with centred white text
+# Output is automatically in the correct TGA format
+----
+
+This is the easiest way to create a splash screen for testing or simple deployments.
+
+=== Using ImageMagick
+
+[source,bash]
+----
+# Convert and optimise an existing image
+convert input.png \
+  -resize 1920x1080 \
+  -background black \
+  -gravity center \
+  -extent 1920x1080 \
+  -depth 8 \
+  -colors 224 \
+  -type truecolor \
+  output.tga
+----
+
+=== Using GIMP
+
+1. Open your image in GIMP
+2. Scale to 1920×1080 or smaller (Image → Scale Image)
+3. Ensure RGB mode (Image → Mode → RGB)
+4. Reduce colours: Image → Mode → Indexed → Set 224 colours maximum
+5. Convert back to RGB: Image → Mode → RGB
+6. Export as TGA: File → Export As
+7. Select 24-bit, disable RLE compression
+
+== Dependencies
+
+The layer requires:
+
+* `rpi-essential-base`: Provides basic system utilities
+* `rpi-splash-screen-support`: Raspberry Pi splash screen configuration tool
+* `initramfs-tools`: For initramfs generation and hooks
+
+== Files Modified
+
+The layer modifies the following files in the target system:
+
+* `/lib/firmware/logo.tga`: The splash screen image
+* `/etc/initramfs-tools/hooks/splash-screen-hook.sh`: Initramfs hook
+* `/boot/firmware/cmdline.txt`: Kernel command line (if `update_cmdline=y`)
+* Initramfs images in `/boot/firmware/`
+
+== Troubleshooting
+
+=== Splash Screen Doesn't Appear
+
+1. Check that `/lib/firmware/logo.tga` exists in the built image
+2. Verify `/boot/firmware/cmdline.txt` contains the required parameters
+3. Ensure initramfs was rebuilt correctly
+4. Check image meets technical requirements
+
+=== Image Validation Fails
+
+1. Verify image is 24-bit TGA format
+2. Check dimensions are ≤1920×1080
+3. Reduce colour count to <224
+4. Ensure image is uncompressed
+
+=== Boot Fails After Configuration
+
+1. Set `update_cmdline: n` and configure manually
+2. Check initramfs hook installed correctly
+3. Review build logs for errors
+
+== References
+
+* https://github.com/raspberrypi/rpi-splash-screen-support[Raspberry Pi Splash Screen Support]
+* The layer includes `EXAMPLE-splash.sh` helper script for quick splash screen generation
+
+== See Also
+
+* link:../base/core-essential.adoc[Core Essential Layer]
+* link:../device/boot-firmware.adoc[Boot Firmware Layer]
+

layer/rpi/device/splash-screen/splash-screen.yaml

@@ -0,0 +1,80 @@
+# METABEGIN
+# X-Env-Layer-Name: rpi-splash-screen
+# X-Env-Layer-Desc: Raspberry Pi fullscreen splash screen support with custom image configuration.
+# X-Env-Layer-Version: 1.0.0
+#
+# X-Env-VarPrefix: splash
+#
+# X-Env-Var-image_path: ${DIRECTORY}/splash-screen/default-splash.tga
+# X-Env-Var-image_path-Desc: Path to the splash screen image file. Must be a 24-bit
+#  TGA file, smaller than 1920x1080px with fewer than 224 colours. The image will
+#  be copied to /lib/firmware/logo.tga and configured in the initramfs and kernel
+#  command line. If the path is relative, it's resolved relative to the layer
+#  directory. Set to an empty string to skip splash screen installation.
+# X-Env-Var-image_path-Required: n
+# X-Env-Var-image_path-Valid: string-or-empty
+# X-Env-Var-image_path-Set: y
+#
+# X-Env-Var-skip_image_checks: n
+# X-Env-Var-skip_image_checks-Desc: If y, skip validation of image dimensions,
+#  colour depth and colour count. This may be useful for testing or if using
+#  non-standard image formats, but the splash screen may not display correctly.
+# X-Env-Var-skip_image_checks-Required: n
+# X-Env-Var-skip_image_checks-Valid: bool
+# X-Env-Var-skip_image_checks-Set: y
+#
+# X-Env-Var-update_cmdline: y
+# X-Env-Var-update_cmdline-Desc: If y, automatically update /boot/firmware/cmdline.txt
+#  to enable the splash screen. If n, the splash screen will be installed but
+#  cmdline.txt must be manually configured. This is useful if using custom boot
+#  configurations or alternative bootloaders.
+# X-Env-Var-update_cmdline-Required: n
+# X-Env-Var-update_cmdline-Valid: bool
+# X-Env-Var-update_cmdline-Set: y
+# METAEND
+---
+mmdebstrap:
+  packages:
+    - rpi-splash-screen-support
+    - initramfs-tools
+    - file
+  customize-hooks:
+    - |-
+      set -eu
+
+      # Skip if no image path provided
+      if [ -z "${IGconf_splash_image_path:-}" ]; then
+        echo "No splash screen image specified, skipping installation" >&2
+        exit 0
+      fi
+
+      # Resolve the image path
+      SPLASH_IMAGE="$IGconf_splash_image_path"
+      if [ ! -f "$SPLASH_IMAGE" ]; then
+        echo "Error: Splash screen image not found: $SPLASH_IMAGE" >&2
+        exit 1
+      fi
+
+      # Copy the image into the chroot temporarily
+      TEMP_IMAGE="/tmp/splash-screen-source.tga"
+      cp "$SPLASH_IMAGE" "$1$TEMP_IMAGE"
+
+      # Run the configure-splash script inside the chroot
+      echo "Configuring splash screen from $SPLASH_IMAGE" >&2
+
+      # Build command arguments based on boolean config values
+      if [ "$IGconf_splash_skip_image_checks" = "y" ] && [ "$IGconf_splash_update_cmdline" != "y" ]; then
+        chroot $1 /usr/bin/configure-splash --skip-image-checks --no-cmdline $TEMP_IMAGE
+      elif [ "$IGconf_splash_skip_image_checks" = "y" ]; then
+        chroot $1 /usr/bin/configure-splash --skip-image-checks $TEMP_IMAGE
+      elif [ "$IGconf_splash_update_cmdline" != "y" ]; then
+        chroot $1 /usr/bin/configure-splash --no-cmdline $TEMP_IMAGE
+      else
+        chroot $1 /usr/bin/configure-splash $TEMP_IMAGE
+      fi
+
+      # Clean up temporary file
+      rm -f "$1$TEMP_IMAGE"
+
+      echo "Splash screen configured successfully" >&2
+