From 655a6da8a8cffe6270659938139e6192598e5e06 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Tue, 4 Nov 2025 13:31:19 +0100
Subject: [PATCH] nxp: document flash procedure and expose images in flake

---
 compulab/README.md | 31 +++++++++++++++++++++++++++++--
 flake.nix          | 10 +++++++++-
 nxp/README.md      | 38 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 76 insertions(+), 3 deletions(-)

diff --git a/compulab/README.md b/compulab/README.md
index aa3c253a..d90e7b20 100644
--- a/compulab/README.md
+++ b/compulab/README.md
@@ -23,7 +23,34 @@ Boot ROM initializes the SoC and loads OEI, which runs in TCM to perform early s
 }
 ```
 
+### Building Boot Images
+
+The boot image for flashing to SD cards can be built directly from the flake:
+
+```bash
+# Build boot image for UCM-iMX95
+nix build github:NixOS/nixos-hardware#packages.aarch64-linux.ucm-imx95-boot
+
+# Or from a local checkout
+nix build .#packages.aarch64-linux.ucm-imx95-boot
+```
+
+The boot image will be available at `./result/image/flash.bin`.
+
+**Note:** These packages target `aarch64-linux`. If you're on a different architecture (e.g., x86_64-linux), you'll need remote builders configured for aarch64-linux.
+
+### Flashing to SD Card
+
+Once built, you can flash the boot image to an SD card:
+
+```bash
+# Write boot image to SD card at 32KB offset (adjust /dev/sdX to your SD card device)
+sudo dd if=./result/image/flash.bin of=/dev/sdX bs=1k seek=32 conv=fsync
+```
+
+**Warning:** Double-check the device path to avoid overwriting the wrong disk!
+
 ### Notes
-- The configuration, including device-tree, kernel, and bootloader components, is optimized for the UCM-iMX95 SoM and EVK.  
-- The generated NixOS image supports booting from SD card or eMMC, depending on the hardware configuration.  
+- The configuration, including device-tree, kernel, and bootloader components, is optimized for the UCM-iMX95 SoM and EVK.
+- The generated NixOS image supports booting from SD card or eMMC, depending on the hardware configuration.
 - The boot components (OEI in TCM/DDR, SM, ATF, U-Boot) follow the standard NXP release layout for i.MX95 platforms.
diff --git a/flake.nix b/flake.nix
index 8f32fbbf..1fbed53c 100644
--- a/flake.nix
+++ b/flake.nix
@@ -462,11 +462,19 @@
 
       # Add packages
       packages = eachSystem (
-        pkgs: _system: {
+        pkgs: system:
+        {
           run-tests = pkgs.callPackage ./tests/run-tests.nix {
             inherit self;
           };
         }
+        // pkgs.lib.optionalAttrs (system == "aarch64-linux") {
+          # Boot images for NXP i.MX boards (aarch64-linux only)
+          ucm-imx95-boot = (pkgs.callPackage ./compulab/ucm-imx95/bsp/ucm-imx95-boot.nix { }).imx95-boot;
+          imx93-boot = (pkgs.callPackage ./nxp/imx93-evk/bsp/imx93-boot.nix { }).imx93-boot;
+          imx8mp-boot = (pkgs.callPackage ./nxp/imx8mp-evk/bsp/imx8mp-boot.nix { }).imx8m-boot;
+          imx8mq-boot = (pkgs.callPackage ./nxp/imx8mq-evk/bsp/imx8mq-boot.nix { }).imx8m-boot;
+        }
       );
 
       # Add checks for `nix run .#run-tests`
diff --git a/nxp/README.md b/nxp/README.md
index cf1f5d2a..fc8fac60 100644
--- a/nxp/README.md
+++ b/nxp/README.md
@@ -38,3 +38,41 @@ Code snippet example that enables 'imx8mp-evk/imx8mq-evk/imx93-evk' configuratio
 }
 ```
 
+### 2.3 Building Boot Images
+
+Boot images for flashing to SD cards can be built directly from the flake:
+
+```bash
+# Build boot image for i.MX8MP EVK
+nix build github:NixOS/nixos-hardware#packages.aarch64-linux.imx8mp-boot
+
+# Build boot image for i.MX8MQ EVK
+nix build github:NixOS/nixos-hardware#packages.aarch64-linux.imx8mq-boot
+
+# Build boot image for i.MX93 EVK
+nix build github:NixOS/nixos-hardware#packages.aarch64-linux.imx93-boot
+
+# Or from a local checkout
+nix build .#packages.aarch64-linux.imx8mp-boot
+```
+
+The boot image will be available at `./result/image/flash.bin`.
+
+**Note:** These packages target `aarch64-linux`. If you're on a different architecture (e.g., x86_64-linux), you'll need remote builders configured for aarch64-linux.
+
+### 2.4 Flashing to SD Card
+
+Once built, you can flash the boot image to an SD card:
+
+```bash
+# For i.MX8MP and i.MX93 (32KB offset):
+sudo dd if=./result/image/flash.bin of=/dev/sdX bs=1k seek=32 conv=fsync
+
+# For i.MX8MQ (33KB offset):
+sudo dd if=./result/image/flash.bin of=/dev/sdX bs=1k seek=33 conv=fsync
+```
+
+**Note:** Different i.MX processors require different offsets. i.MX8MP and i.MX93 use 32KB (seek=32), while i.MX8MQ uses 33KB (seek=33).
+
+**Warning:** Double-check the device path to avoid overwriting the wrong disk!
+