vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: second-pass boot audit (D-Bus honesty, shell quality, login), archive 4 stale docs

Browse Source 
BOOT-PROCESS-SECOND-AUDIT-2026-05-03.md: deep dive into:
- D-Bus implementation honesty (15/19 login1 methods real, not stubs)
- ion shell quality matrix (vs bash/dash)
- Login prompt completeness (getty→login→ion chain)
- Per-subsystem hardware init status (storage/display/input/network/USB/audio/ACPI)
- Implementation plan Phases F1-F6

Archived 4 completed/deferred plans: GRUB, VFAT, USB-BOOT-INPUT, ZSH-PORTING
This commit is contained in:
Vasilito
2026-05-03 09:37:09 +01:00
parent 39ce0115a5
commit e586a44be6
6 changed files with 270 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
local/docs/archived/GRUB-INTEGRATION-PLAN.md
+391
View File
@@ -0,0 +1,391 @@
# GRUB Integration Plan — Red Bear OS
**Date:** 2026-04-17
**Status:** Fully implemented (build-tested, not yet runtime boot-tested). ESP formatted as FAT32
per UEFI spec. Both Phase 1 (post-build script) and Phase 2 (installer-native) are wired.
**Remaining:** Runtime UEFI boot validation in QEMU (`make all CONFIG_NAME=redbear-grub && make qemu`).
**Prerequisite:** The `grub` package is included in `redbear-grub.toml` for clean-tree builds.
**Approach:** Option A — GRUB as boot manager, chainloading Redox bootloader
## Overview
Add GNU GRUB as an optional boot manager for Red Bear OS. GRUB presents a menu
at boot and chainloads the existing Redox bootloader, which then boots the
kernel normally. This gives users:
- Multi-boot capability alongside Linux, Windows, or other OSes
- Boot menu with timeout and manual selection
- Familiar GRUB rescue shell for debugging
- No changes to the Redox kernel, RedoxFS, or existing boot flow
## Architecture
```
UEFI firmware
→ EFI/BOOT/BOOTX64.EFI (GRUB standalone image)
→ grub.cfg: default entry chainloads Redox bootloader
→ EFI/REDBEAR/redbear.efi (Redox bootloader)
→ Reads RedoxFS partition
→ Loads kernel
→ Boots Red Bear OS
```
### ESP Layout (GRUB mode)
```
EFI/
├── BOOT/
│ ├── BOOTX64.EFI ← GRUB (primary, loaded by UEFI firmware)
│ └── grub.cfg ← GRUB configuration
└── REDBEAR/
└── redbear.efi ← Redox bootloader (chainload target)
```
### ESP Layout (default, no GRUB)
```
EFI/
└── BOOT/
└── BOOTX64.EFI ← Redox bootloader (unchanged)
```
## Why GRUB?
1. **GRUB does not support RedoxFS.** Writing a GRUB filesystem module for
RedoxFS is high-risk, GPL-licensing-sensitive work. Chainloading avoids it.
2. **The Redox bootloader works.** It reads RedoxFS directly and boots the
kernel. No need to replicate that logic in GRUB.
3. **GRUB is universally understood.** System administrators know GRUB. A
`grub.cfg` is easier to customize than a custom bootloader.
4. **Multi-boot.** GRUB can boot Linux, Windows, and other OSes alongside
Red Bear OS without any changes to those systems.
## GRUB Module Set
The standalone EFI image includes these modules:
| Module | Purpose |
|--------|---------|
| `part_gpt` | GPT partition table support |
| `part_msdos` | MBR partition table support |
| `fat` | FAT32 filesystem (ESP) |
| `ext2` | ext2/3/4 filesystem |
| `normal` | Normal mode (menu, scripting) |
| `configfile` | Load configuration files |
| `search` | Search for files/volumes |
| `search_fs_uuid` | Search by filesystem UUID |
| `search_label` | Search by volume label |
| `echo` | Print messages |
| `test` | Conditional expressions |
| `ls` | List files and devices |
| `cat` | Display file contents |
| `halt` | Shut down |
| `reboot` | Reboot |
Note: `chainloader` is a built-in command in GRUB 2.12 (no separate module needed).
Red Bear policy now requires a local `redoxfs.mod` artifact for GRUB builds.
The GRUB recipe resolves it in this order:
1. `local/recipes/core/grub/modules/redoxfs.mod`
2. `${COOKBOOK_SYSROOT}/usr/lib/grub/x86_64-efi/redoxfs.mod`
If neither exists, the GRUB recipe fails fast.
## GRUB Configuration
The default `grub.cfg`:
```cfg
# Red Bear OS GRUB Configuration
set default=0
set timeout=5
menuentry "Red Bear OS" {
chainloader /EFI/REDBEAR/redbear.efi
boot
}
menuentry "Reboot" {
reboot
}
menuentry "Shutdown" {
halt
}
```
Users can customize `grub.cfg` to add entries for other operating systems,
change the timeout, or add additional Red Bear OS entries (e.g., recovery
mode with different kernel parameters, once supported).
## ESP Size Requirements
| Component | Typical Size |
|-----------|--------------|
| GRUB EFI binary (with modules) | ~500 KiB (varies with module list) |
| Redox bootloader | 100–200 KiB |
| grub.cfg | < 1 KiB |
| **Total** | **~1 MiB** |
The default ESP is 1 MiB (too small for GRUB). Configs using GRUB must set:
```toml
[general]
efi_partition_size = 16 # 16 MiB, enough for GRUB + Redox bootloader + margin
```
## Linux-Compatible CLI
Red Bear OS provides `grub-install` and `grub-mkconfig` wrappers that match GNU GRUB
command-line conventions. Users migrating from Linux can use familiar switches.
| Linux Command | Red Bear OS Location |
|---------------|---------------------|
| `grub-install` | `local/scripts/grub-install` |
| `grub-mkconfig` | `local/scripts/grub-mkconfig` |
Add to PATH for convenience:
```bash
export PATH="$PWD/local/scripts:$PATH"
```
### grub-install
```bash
# Install GRUB into a disk image
grub-install --target=x86_64-efi --disk-image=build/x86_64/harddrive.img
# Verbose mode
grub-install --target=x86_64-efi --disk-image=build/x86_64/harddrive.img --verbose
# Show help
grub-install --help
```
Supported options: `--target=`, `--efi-directory=`, `--bootloader-id=`, `--removable`,
`--disk-image=`, `--modules=`, `--no-nvram`, `--verbose`, `--help`, `--version`.
Unsupported Linux options are accepted and ignored silently for script compatibility.
### grub-mkconfig
```bash
# Preview generated config
grub-mkconfig
# Write to file
grub-mkconfig -o local/recipes/core/grub/grub.cfg
# Custom timeout
grub-mkconfig --timeout=10 -o /boot/grub/grub.cfg
```
Supported options: `-o`/`--output=`, `--timeout=`, `--set-default=`, `--help`, `--version`.
## Implementation — Phase 1: Post-Build Script
Phase 1 uses a post-build script to modify the ESP in an existing disk image.
This approach requires **no changes to the installer** and works immediately.
### Files
| File | Purpose |
|------|---------|
| `local/recipes/core/grub/recipe.toml` | Build GRUB from source, produce `grub.efi` |
| `local/recipes/core/grub/grub.cfg` | Default GRUB configuration |
| `local/recipes/core/grub/modules/redoxfs.mod` | Mandatory local GRUB RedoxFS module artifact |
| `local/scripts/install-grub.sh` | Post-build ESP modification script |
| `local/scripts/fat_tool.py` | Python FAT32 tool (no mtools dependency) |
| `recipes/core/grub → local/recipes/core/grub` | Symlink for recipe discovery |
### Workflow
```bash
# 1. Build GRUB recipe
make r.grub
# 2. Build Red Bear OS (with larger ESP)
make all CONFIG_NAME=redbear-full # Must have efi_partition_size = 16
# 3. Install GRUB into disk image
./local/scripts/install-grub.sh build/x86_64/harddrive.img
# 4. Test
make qemu
```
### Requirements
- Python 3 (for `fat_tool.py` — no mtools dependency)
- GRUB build dependencies: `gcc`, `make`, `bison`, `flex`, `autoconf`, `automake`
- ESP must be ≥ 8 MiB (set `efi_partition_size = 16` in config)
## Implementation — Phase 2: Installer-Native Support
Phase 2 adds GRUB awareness directly to the Redox installer, eliminating the
post-build script step. The installer reads `bootloader = "grub"` from config,
fetches the GRUB package alongside the bootloader, and writes the chainload
ESP layout automatically.
### Changes Made
1. **`GeneralConfig`** (`config/general.rs`): Added `bootloader: Option<String>`
field (`"redox"` default, `"grub"` for GRUB), with merge support.
2. **`DiskOption`** (`installer.rs`): Added `grub_efi: Option<&[u8]>` and
`grub_config: Option<&[u8]>` fields for optional GRUB data.
3. **`fetch_bootloaders`**: When `bootloader = "grub"`, installs the `grub`
package alongside `bootloader` and returns `grub.efi` + `grub.cfg` data.
Return type extended to `(bios, efi, grub_efi, grub_cfg)`.
4. **`with_whole_disk` / `with_whole_disk_ext4`**: When `grub_efi` and
`grub_config` are both present, writes the GRUB chainload layout:
- `EFI/BOOT/BOOTX64.EFI` ← GRUB
- `EFI/BOOT/grub.cfg` ← GRUB configuration
- `EFI/REDBEAR/redbear.efi` ← Redox bootloader (chainload target)
5. **`install_inner`**: Passes GRUB data from `fetch_bootloaders` through
`DiskOption`.
6. **CLI** (`bin/installer.rs`): Added `--bootloader grub` flag that sets
`config.general.bootloader`.
7. **TUI** (`bin/installer_tui.rs`): Updated `DiskOption` construction with
`grub_efi: None, grub_config: None`.
### Config Usage
```toml
# config/redbear-grub.toml
include = ["redbear-full.toml"]
[general]
bootloader = "grub"
efi_partition_size = 16
```
Or via CLI (note: INSTALLER_OPTS replaces defaults, so --cookbook=. must be included):
```bash
./target/release/repo cook installer
make all CONFIG_NAME=redbear-full INSTALLER_OPTS="--cookbook=. --bootloader grub"
```
**Note:** The config file approach (`redbear-grub.toml`) is preferred over the CLI flag
because INSTALLER_OPTS completely replaces the default value (`--cookbook=.`) rather than
appending to it. Omitting `--cookbook=.` breaks local package resolution for GRUB.
## GRUB Recipe Design
The GRUB recipe uses `template = "custom"` because GRUB must be built for the
**host machine** (it's a build tool that produces EFI binaries), not for the
Redox target. The cookbook's `configure` template cross-compiles for Redox,
which is wrong for GRUB.
Key build steps:
1. Configure with `--target=x86_64 --with-platform=efi` (produces x86_64 EFI)
2. Disable unnecessary components (themes, mkfont, mount, device-mapper)
3. Run `grub-mkimage` to create standalone EFI binary with curated modules
4. Stage `grub.efi` and `grub.cfg` to `/usr/lib/boot/`
### Build Notes
The recipe uses `template = "custom"` because the cookbook's default `configure`
template sets `--host="${GNU_TARGET}"` for Redox cross-compilation, which is wrong
for GRUB (a host build tool producing EFI binaries).
Two issues required workarounds:
1. **Cross-compiler override.** The cookbook sets `CC`, `CXX`, `CFLAGS`, etc. to
the Redox cross-toolchain. GRUB must be built with the host compiler. Fix:
`unset CC CXX CPP LD AR NM RANLIB OBJCOPY STRIP PKG_CONFIG` and
`unset CFLAGS CXXFLAGS CPPFLAGS LDFLAGS` at the top of the script.
2. **Missing `extra_deps.lst`.** GRUB 2.12 release tarballs omit
`grub-core/extra_deps.lst` (normally generated by `autogen.sh` from git).
Fix: `touch "${COOKBOOK_SOURCE}/grub-core/extra_deps.lst"` before configure.
3. **grub.cfg location.** The config file lives in the recipe directory
(`${COOKBOOK_RECIPE}/grub.cfg`), not in the extracted source tarball
(`${COOKBOOK_SOURCE}/`). The copy step uses `COOKBOOK_RECIPE`.
## Security Considerations
- GRUB configuration is on the ESP (FAT32), which is readable/writable by any OS
- Secure Boot: GRUB standalone images are not signed. Users needing Secure Boot
must sign `BOOTX64.EFI` with their own key or use `shim`
- The chainload target (`EFI/REDBEAR/redbear.efi`) is also on the ESP
- No credentials or secrets are stored in the GRUB configuration
## Limitations
- GRUB cannot read RedoxFS (no module exists)
- Cannot pass kernel parameters directly (chainloading bypasses this)
- BIOS boot is not supported (only UEFI)
- ESP must be sized to ≥ 8 MiB in config (16 MiB recommended)
- GRUB bootloader is incompatible with `skip_partitions = true` (requires GPT layout with ESP)
- TUI installer does not support GRUB mode (intentional — TUI is for live disk reinstall)
- Runtime UEFI boot test has not been performed yet (requires full `make all` build, ~hours)
## Testing
### Phase 1: Post-build script (standalone)
```bash
# Build GRUB recipe
make r.grub
# Build image (any config with efi_partition_size >= 16)
make all CONFIG_NAME=redbear-full
# Install GRUB into disk image (uses fat_tool.py, no mtools needed)
./local/scripts/install-grub.sh build/x86_64/harddrive.img
# Verify ESP contents
python3 local/scripts/fat_tool.py ls build/x86_64/harddrive.img 1048576 /
# Boot in QEMU
make qemu
# Expected: GRUB menu appears, "Red Bear OS" entry boots successfully
```
### Phase 2: Installer-native (automatic)
```bash
# Build GRUB recipe (must be built before installer runs)
make r.grub
# Build image with GRUB config (installer fetches GRUB automatically)
make all CONFIG_NAME=redbear-grub
# Or via CLI flag
make all CONFIG_NAME=redbear-full INSTALLER_OPTS="--bootloader grub --cookbook=."
# Verify ESP contents
python3 local/scripts/fat_tool.py ls build/x86_64/harddrive.img 1048576 /
# Boot in QEMU
make qemu
# Expected: GRUB menu appears, "Red Bear OS" entry boots successfully
```
### Unit tests (no full build required)
```bash
# Verify GRUB recipe builds
CI=1 ./target/release/repo cook grub
# Verify host-side installer accepts --bootloader flag
build/fstools/bin/redox_installer --bootloader=grub --config=config/redbear-grub.toml --list-packages
# Verify fat_tool.py operations
python3 local/scripts/fat_tool.py --help
```
## References
- GNU GRUB Manual: https://www.gnu.org/software/grub/manual/grub/grub.html
- GRUB EFI standalone image: `grub-mkimage -O x86_64-efi ...`
- UEFI boot specification: `EFI/BOOT/BOOTX64.EFI` is the fallback boot path
- Redox bootloader source: `recipes/core/bootloader/source/`
- Installer GPT layout: `recipes/core/installer/source/src/installer.rs`