Re: [PATCH] Further update of the i386 boot documentation

[Jeremy Fitzhardinge <jeremy@goop.org>]

H. Peter Anvin wrote:
> +Field name:	boot_flag
> +Type:		read
> +Offset/size:	0x1fe/2
> +Protocol:	ALL
> +
> +  Contains 0xAA55.  This is the closest thing old Linux kernels have
> +  to a magic number.
>   

Endianess?  I guess a blanket statement saying that all constants are
stored little-endian enough (which is obvious, but its always good to be
explicit).

> +
> +Field name:	jump
> +Type:		read
> +Offset/size:	0x200/2
> +Protocol:	2.00+
> +
> +  Contains an x86 jump instruction, 0xEB followed by a signed offset
> +  relative to byte 0x202.  This can be used to determine the size of
> +  the header.
> +
> +Field name:	header
> +Type:		read
> +Offset/size:	0x202/4
> +Protocol:	2.00+
> +
> +  Contains the magic number "HdrS" (0x53726448).
>   

This is a bit confusing from an endian perspective.  Does the "HdrS"
notation mean that it is a byte array containing 'H', 'd', 'r', 'S', as
the string syntax suggests?  Or is that the ascii interpretation of each
byte of a 4-byte value read as a little-endian encoding from that location?

> +
> +Field name:	version
> +Type:		read
> +Offset/size:	0x206/2
> +Protocol:	2.00+
> +
> +  Contains the boot protocol version, e.g. 0x0204 for version 2.04.
>   

So the version is in BCD?

> +
> +Field name:	readmode_swtch
> +Type:		modify (optional)
> +Offset/size:	0x208/4
> +Protocol:	2.00+
> +
> +  Boot loader hook (see separate chapter.)
>   

Chapter?  Is there a more specific reference you could make?

> +
> +Field name:	start_sys
> +Type:		read
> +Offset/size:	0x20c/4
> +Protocol:	2.00+
> +
> +  The load low segment (0x1000).  Obsolete.
> +
> +Field name:	kernel_version
> +Type:		read
> +Offset/size:	0x20e/2
> +Protocol:	2.00+
> +
> +  If set to a nonzero value, contains a pointer to a null-terminated
>   

"nil-terminated"? "\0-terminated"?

> +  human-readable kernel version number string, less 0x200.  This can
> +  be used to display the kernel version to the user.  This value
> +  should be less than (0x200*setup_sects).  For example, if this value
> +  is set to 0x1c00, the kernel version number string can be found at
> +  offset 0x1e00 in the kernel file.  This is a valid value if and only
> +  if the "setup_sects" field contains the value 14 or higher.
>   
How about something like:

    This example is only valid if "setup_sects" is greater than

        ((0x1e00 - 0x200) / 0x200) = 14.

Just to make the calculation explicit.

    J