# Brain (i.MX28) Linux boot flow notes

This is a consolidated boot-flow summary based on local sources:
- buildbrain (boot image scripts, BrainLILO, u-boot-brain)
- linux-brain kernel tree
- brainux wiki pages (build + USB gadget)

## 1) Boot chain overview
1. i.MX28 ROM loads Windows CE from internal storage (vendor default).
2. Windows CE launches the BrainLILO app from the SD card.
3. BrainLILO selects a model-specific U-Boot binary from the SD card
   and jumps to it (soft reset / memory remap).
4. U-Boot loads the Linux kernel (zImage) + DTB from SD/eMMC
   and boots Linux with `bootz`.

Key locations:
- BrainLILO loads from `\\Storage Card\\loader\\<model>.bin`
  (see `sources/buildbrain/brainlilo/models.h`).
- Boot image creation logic is in `sources/buildbrain/image/build_image.sh`.

## 2) SD card layout (buildbrain convention)
From `sources/buildbrain/image/build_image.sh`:
- Partition 1: FAT32 (~64 MiB)
  - `zImage` and DTBs (`imx28-pwsh*.dtb`)
  - `nk/` and `loader/` containing U-Boot binaries
  - BrainLILO app directory (Windows CE): `アプリ/Launch Linux`
    - `AppMain.exe` (exeopener)
    - `AppMain_.exe` (BrainLILO.exe)
    - `*.dll`, `index.din`, `AppMain.cfg`
- Partition 2: ext4 rootfs

## 3) U-Boot behavior (brain_mx28_common.h)
`sources/buildbrain/u-boot-brain/include/configs/brain_mx28_common.h`:
- `bootorder=emmc sd`, `sddev=1` (SD), `emmcdev=0` (eMMC)
- Loads `zImage` + `fdt_file` from FAT (`fatload`), then `bootz`
- Optional `uEnv.txt` import on SD/eMMC via `preboot`
- Default DTB is set by defconfig, e.g. `CONFIG_DEFAULT_FDT_FILE=imx28-pwsh5.dtb`

## 4) Kernel/DTB
`linux-brain` provides the kernel and DTBs:
- Kernel: `arch/arm/boot/zImage`
- DTB: `arch/arm/boot/dts/imx28-pwsh{1..7}.dtb`, `imx28-pwa7200.dtb`, etc.
- Base DTS: `arch/arm/boot/dts/imx28-brain.dtsi`

Kernel version in this tree: `5.4.149` (see `sources/linux-brain-brain/Makefile`).

## 5) USB gadget (RNDIS)
Default `imx28-brain.dtsi` sets USB controller to host mode:
- `usb@80080000 { dr_mode = "host"; }`

Brainux wiki describes switching to gadget mode by changing
`dr_mode = "peripheral"` and then enabling RNDIS via configfs.
A reference script/service exists in:
- `sources/buildbrain/os-brainux/override/usr/bin/enable_rndis_gadget`
- `sources/buildbrain/os-brainux/override/lib/systemd/system/rndis_gadget.service`

## 6) Recovery / USB boot
Buildbrain uses `u-boot.sb` for i.MX28 USB recovery mode (`uuu`).
See `sources/buildbrain/README.md` and `sources/buildbrain/Makefile`.
