docs/embedded_data.txt

NOTE that GRUB's own install functions can alter all of the significant
variables here...  look in the install.html file for details.

This file describes embedded variables in GRUB's stage1 and stage2 and
how they are meant to be used and manipulated.

The primary reason for them being in well-defined locations is to allow
changes/installation/etc. without needing to recompile the modules, just
patch the binary directly.


"stage1" :

NOTE: these are all defined in "stage1/stage1.S".

   --  at offset 0x1BC :  "major version"

	This is the major version byte (should be a 1).

   --  at offset 0x1BD :  "minor version"

	This is the minor version byte (should be a 0).

   --  at offset 0x1B8 :  "stage2 start address"

	This is the data for the "ljmp" command to the starting address
	of the component loaded by the stage1.  The format is two 2-byte
	words: the first is the IP, and the second is the CS segment
	register (remember, we're in x86 real-mode...  16-bit instruction
	pointer and segment registers shifted left by 4 bits).

	A "stage1.5" should be loaded at address 0x2000, and a "stage2"
	should be loaded at address 0x8000.  Both use a CS of 0.

   --  at offset 0x1B0 :  "firstlist"

	This is the ending address of the blocklist data area.

	The trick here is that it is actually read backward, and the first
	8-byte blocklist is not read here, but after the pointer is
	decremented 8 bytes, then after reading it, it decrements again,
	reads, decrements, reads, etc. until it is finished.  The
	terminating condition is when the number of sectors to be read
	in the next blocklist is 0.

	The format of a blocklist can be seen from the example in the
	code just before the "firstlist" label.  (note that it is
	always from the beginning of the disk, and *NOT* relative to
	the partition boundaries)

   --  at offset 0x1B0 :  "loading drive"

	This is the BIOS drive number to load the blocklists from.
	If the number is 0xFF, then load from the booting drive.


"stage1.5" and "stage2"  (same structure) :

NOTE: these are all defined at the beginning of "shared_src/asm.S".

   --  at offset 0x6 :  "major version"

	This is the major version byte (should be a 1).

   --  at offset 0x7 :  "minor version"

	This is the minor version byte (should be a 0).

   --  at offset 0x8 :  "install_partition"

	This is an unsigned long representing the partition on the currently
	booted disk which GRUB should expect to find it's data files and
	treat as the default root partition.

	The format of is exactly the same as the "partition" part (the "disk"
	part is ignored) of the data passed to an OS by a Multiboot-compliant
	bootloader in the "boot_device" data element, with one exception.

	The exception is that if the first level of disk partitioning is
	left as 0xFF (decimal 255, which is marked as no partitioning being
	used), but the second level does have a partition number, it looks
	for the first BSD-style PC partition, and finds the numbered BSD
	sub-partition in it.  The default "install_partition" 0xFF00FF,
	would then find the first BSD-style PC partition, and use the "a"
	partition in it, and 0xFF01FF would use the "b" partition, etc.

	If an explicit first-level partition is given, then no search is
	performed, and it will expect that the BSD-style PC partition is
	in the appropriate location, else a "no such partition" error will
	be returned.

   IMPORTANT NOTE:  If a "stage1.5" is being used, it will pass it's own
	"install_partition" to any "stage2" it loads, therefore overwriting
	the one present in the "stage2".

   --  at offset 0xC :  "version_string"

	This is the "stage1.5" or "stage2" version string.  It isn't
	meant to be changed, simply easy to find.

   --  after the terminating zero of "version_string" :  "config_file"

	This is the location, using the GRUB filesystem syntax, of the
	config file.  It will, by default, look in the "install_partition"
	of the disk GRUB was loaded from, though one can use any valid
	GRUB filesystem string, up to and including making it look on
	other disks.

   IMPORTANT NOTE:  The bootloader itself doesn't search for the end of
	"version_string", it simply knows where "config_file" is, so the
	beginning of the string cannot be moved after compile-time.  This
	should be OK, since the "version_string" is meant to be static.

   IMPORTANT NOTE #2:  The code of stage2 starts again at offset 0x70,
	so "config_file" string obviously can't go past there.  Also,
	remember to terminate the string with a 0.