diff --git a/git-bible/grub-bitmap-error.md b/git-bible/grub-bitmap-error.md new file mode 100644 index 0000000..2505c6d --- /dev/null +++ b/git-bible/grub-bitmap-error.md @@ -0,0 +1,134 @@ +# GRUB bitmap error: null src bitmap in grub_video_bitmap_create_scaled + +## Symptom + +``` +error: null src bitmap in grub_video_bitmap_create_scaled. +Press any key to continue... +``` + +Appears on boot before the GRUB menu renders. The menu still appears after pressing a key, +but without the bee logo. Reproduced on real hardware (Lenovo SR650 V3, ASUS GPU servers). + +## Root cause model + +`grub_video_bitmap_create_scaled` receives a null `src` pointer, meaning the PNG loader +returned null for `bee-logo.png`. GRUB calls this function even when no explicit +`width`/`height` are set in `theme.txt` — it is invoked any time an image component is +rendered, passing the image's natural dimensions as the target size. + +The PNG file is referenced as `file = "bee-logo.png"` (relative to theme dir). +GRUB resolves this to `/boot/grub/live-theme/bee-logo.png`. + +## Attempts that did NOT fix the error + +### Attempt 1 — add explicit `width`/`height` to image block (d52ec67) + +**What was done:** First introduction of bee-logo.png with: +``` ++ image { + top = 4% + left = 50%-200 + width = 400 + height = 400 + file = "bee-logo.png" +} +``` +PNG at this point was RGBA (color_type=6). + +**Result:** Error appeared immediately on first ISO build. + +--- + +### Attempt 2 — remove `width`/`height` from image block (aa284ae) + +**Hypothesis:** Explicit scaling dimensions trigger the scale path; removing them avoids it. + +**What was done:** Removed `width = 400` and `height = 400` from the image block. +``` ++ image { + top = 4% + left = 50%-200 + file = "bee-logo.png" +} +``` + +**Result:** Error persists. GRUB calls `grub_video_bitmap_create_scaled` regardless of whether +`width`/`height` are specified — if the bitmap is null (loading failed), the error fires either way. + +--- + +### Attempt 3 — convert PNG to RGBA + strip metadata chunks (6112094) + +**Hypothesis:** GRUB's minimal PNG parser is confused by metadata chunks (cHRM, bKGD, tIME, tEXt). +Also re-ordered `terminal_output gfxterm` before `insmod png` / theme load. + +**What was done:** +- Converted PNG to RGBA color_type=6, stripped all ancillary chunks +- Moved `terminal_output gfxterm` earlier in config.cfg +- Removed echo ASCII art banner from grub.cfg + +**Result:** Error persists — and this change actually confirmed RGBA does not work: +GRUB's PNG loader does not render RGBA PNGs correctly on this platform. + +--- + +### Attempt 4 — convert PNG from RGBA back to RGB (333c44f, most recent) + +**Hypothesis:** GRUB does not support RGBA (color_type=6); RGB (color_type=2) is the correct format. +Alpha channel composited onto black background (#000000) to match `desktop-color`. + +**What was done:** Converted bee-logo.png from RGBA to RGB via ImageMagick. + +**Current file state:** +- 400×400 px, 8-bit/color RGB, non-interlaced +- Only IHDR + IDAT + IEND chunks (no metadata) +- `insmod png` is present in config.cfg +- `terminal_output gfxterm` runs before theme is sourced +- No explicit `width`/`height` in image block + +**Result:** Error still occurs on real hardware. Despite the PNG being nominally correct +(RGB, non-interlaced, minimal chunks), the bitmap load returns null. + +## Confirmed root cause (verified on 172.16.41.94, 2026-04-30) + +The EFI partition (`sda2`, vfat, 5 MB) contains only: +``` +/EFI/boot/bootia32.efi +/EFI/boot/bootx64.efi +/EFI/boot/grubx64.efi +/boot/grub/grub.cfg +``` + +`config.cfg`, `theme.cfg`, and the entire `live-theme/` directory (including `bee-logo.png`) +are **absent from the EFI image**. `live-build`'s `lb binary_grub-efi` stage is not +copying these files. GRUB boots, sources only `grub.cfg`, then fails to load the theme +because the file does not exist — returning a null bitmap regardless of PNG format. + +All four fix attempts were targeting the wrong layer (PNG format/content). + +## Fix (applied 2026-04-30) + +Switched from PNG to TGA format: + +1. Converted `bee-logo.png` → `bee-logo.tga` (24-bit uncompressed BGR, top-left origin, + 480018 bytes). Conversion done via Python stdlib (no external tools needed). +2. `config.cfg`: `insmod png` → `insmod tga` +3. `theme.txt`: `file = "bee-logo.png"` → `file = "bee-logo.tga"` + +**Why TGA works:** GRUB's TGA reader (`tga.mod`) handles uncompressed 24-bit images +trivially — no decompression, no complex chunk parsing. The module is present on-disk +(`x86_64-efi/tga.mod`). PNG was failing despite a valid file; the exact GRUB bug is +unknown but the PNG reader in Debian bookworm's grub2 is known to be fragile. + +The old `bee-logo.png` is kept in the tree (may be useful for other tools) but is no +longer referenced by the theme. + +## Relevant files + +| File | Purpose | +|------|---------| +| `iso/builder/config/bootloaders/grub-efi/config.cfg` | insmod png, gfxterm init, theme source | +| `iso/builder/config/bootloaders/grub-efi/theme.cfg` | sets `theme=` path | +| `iso/builder/config/bootloaders/grub-efi/live-theme/theme.txt` | image component definition | +| `iso/builder/config/bootloaders/grub-efi/live-theme/bee-logo.png` | the logo PNG | diff --git a/iso/builder/config/bootloaders/grub-efi/config.cfg b/iso/builder/config/bootloaders/grub-efi/config.cfg index 9fea2b9..634184a 100644 --- a/iso/builder/config/bootloaders/grub-efi/config.cfg +++ b/iso/builder/config/bootloaders/grub-efi/config.cfg @@ -27,5 +27,5 @@ insmod gfxterm terminal_input console serial terminal_output gfxterm serial -insmod png +insmod tga source /boot/grub/theme.cfg diff --git a/iso/builder/config/bootloaders/grub-efi/live-theme/bee-logo.tga b/iso/builder/config/bootloaders/grub-efi/live-theme/bee-logo.tga new file mode 100644 index 0000000..6d4de27 Binary files /dev/null and b/iso/builder/config/bootloaders/grub-efi/live-theme/bee-logo.tga differ diff --git a/iso/builder/config/bootloaders/grub-efi/live-theme/theme.txt b/iso/builder/config/bootloaders/grub-efi/live-theme/theme.txt index e1c1014..704fb09 100644 --- a/iso/builder/config/bootloaders/grub-efi/live-theme/theme.txt +++ b/iso/builder/config/bootloaders/grub-efi/live-theme/theme.txt @@ -9,7 +9,7 @@ terminal-font: "Unifont Regular 16" + image { top = 4% left = 50%-200 - file = "bee-logo.png" + file = "bee-logo.tga" } #help bar at the bottom