learn something about grub finding grub.cfg during boot with ai agent

AGENTS.md

GRUB2 Bootloader

This is the GRUB 2 bootloader (v2.14), maintained by the Free Software Foundation.

Architecture: how grub.cfg is discovered

The boot sequence for finding grub.cfg:

1. grub_main() (grub-core/kern/main.c:304) — kernel entry
2. grub_machine_init() — platform init (console, memory, disks)
3. grub_load_modules() — load modules embedded in the core image
4. grub_set_prefix_and_root() (grub-core/kern/main.c:118) — determine boot device:
   • Reads embedded OBJ_TYPE_PREFIX from core image (set by grub-install)
   • Falls back to grub_machine_get_bootlocation() (platform-specific):
     • EFI: grub-core/kern/efi/init.c:130 — from image->device_handle / image->file_path
     • BIOS: grub-core/kern/i386/pc/init.c:68 — from boot drive + partition encoded at install time
   • Sets env vars prefix (e.g. (hd0,1)/boot/grub) and root
5. Embedded config executed (if any, set via grub-mkimage -c)
6. grub_load_normal_mode() (grub-core/kern/main.c:232) — loads normal module, runs normal command
7. grub_cmd_normal() (grub-core/normal/main.c:320) — constructs $prefix/grub.cfg
8. For PXE/netboot: grub_net_search_config_file() (grub-core/net/net.c:1976) tries these in order:
   • grub.cfg-<UUID> (client UUID from DHCP)
   • grub.cfg-01-<MAC> (MAC address with hyphens)
   • grub.cfg-<IP> (hex IP, shrinking suffix)
   • grub.cfg
   • Disable via feature_net_search_cfg=n in embedded config
9. grub_normal_execute(config) → read_config_file(config) opens and parses the file, sets config_file / config_directory env vars, then shows the menu

Key source files

File	Purpose
grub-core/kern/main.c	Kernel grub_main(), prefix/root setup, normal mode loading
grub-core/normal/main.c	normal module: grub_cmd_normal(), read_config_file(), menu display
grub-core/kern/efi/init.c	EFI boot location (device path → grub_efidisk_get_device_name())
grub-core/kern/i386/pc/init.c	BIOS boot location (boot drive / partition)
grub-core/net/net.c	grub_net_search_config_file(): PXE config file discovery
grub-core/commands/configfile.c	configfile, source commands
grub-core/commands/search.c	search.file, search.fs_uuid, search.label commands
grub-core/kern/rescue_reader.c	Rescue shell (grub rescue>)
grub-core/kern/rescue_parser.c	Rescue mode parser
grub-core/kern/corecmd.c	Core built-in commands (set, unset, ls, insmod)
grub-core/kern/fs.c	Filesystem probing + auto-load
grub-core/kern/disk.c	Disk I/O with caching
grub-core/kern/file.c	grub_file_open(): parses (device)/path syntax
util/grub-install.c	Writes core image with embedded prefix and optional load.cfg

Documentation

Primary docs: docs/grub.texi (build into info grub).

Key sections for config discovery:

• "Embedded configuration" (docs/grub.texi:2000) — how grub-mkimage -c and load.cfg work
• "Network" (docs/grub.texi:2570) — PXE config file search order
• "GRUB only offers a rescue shell" (docs/grub.texi:10570) — troubleshooting prefix issues

Building

./autogen.sh
./configure --target=i386 --with-platform=pc
make

Tests: make check (many require root or specific hardware; check-native / check-nonnative split available).

Key conventions

• Device naming: (hd0,msdos1) or (hd0,gpt2), path is (device)/path/to/file
• Most functionality is in loadable modules under grub-core/, not in the kernel
• Modules are auto-loaded on demand via grub_dl_load() when a command is first used
• Env vars: root, prefix, cmdpath, config_file, config_directory
• Platform identifiers: grub_cpu (e.g. x86_64) and grub_platform (e.g. efi, pc)
• Ubuntu/Debian patches in debian/patches/ (74 patches, including secure boot, ZFS, resilient boot)