On Thu, 14 Apr 2011 23:58:25 +0000 Michael Witten wrote:
> I did some copyediting whilst looking through Documentation/x86/boot.txt;
> this email contains a pull request as well as the inlined diff of all the
> changes squashed together.
>
> Documentation/x86/boot.txt | 396 ++++++++++++++++++++++----------------------
> 1 files changed, 202 insertions(+), 194 deletions(-)
>
> If you don't want to read through all of the changes, then my advice is
> to commit them and wait for somebody to complain :-) After all, Wikipedia
> gets by all right with such a model.
>
> The changes apply cleanly to commit a6360dd37e1a144ed11e6548371bade559a1e4df:
>
> Linux 2.6.39-rc3 (2011-04-11 17:21:51 -0700)
>
> and are available here:
>
> git://github.com/mfwitten/linux-2.6.git trivial/docs/boot
>
> Squash them as desired:
>
> [00] Docs: boot.txt: `syssize' -> `sys_size'
> [01] Docs: Consistently use 2 spaces between sentences
> [02] Docs: Use the subjunctive mood
> [03] Docs: Clean up sentences
> [04] Docs: Add parentheses and a comma to improve flow
> [05] Docs: Remove bizarrely embedded tabs
> [06] Docs: Make protocol version descriptions consistent.
> [07] Docs: Remove commas
> [08] Docs: Use present tense
> [09] Docs: Remove awkward infinitive
> [10] Docs: Add periods to have consistent diagrams
> [11] Docs: Move definition of `X' upwards
> [12] Docs: Remove details described later
> [13] Docs: Better heap_end_ptr description
> [14] Docs: Clarify the meaning of a 0 value for setup_sects
> [15] Docs: Streamline introduction of `read' and `write' fields
> [16] Docs: Put `(obligatory)' in double quotes
> [17] Docs: `who' is reserved for humans; `that' should be used.
> [18] Docs: Put `(reloc)' in double quotes
> [19] Docs: `can' -> `may'
> [20] Docs: `littleendian' -> `little-endian'
> [21] Docs: Offset each modifier with a comma
> [22] Docs: `device device' is a little silly
> [23] Docs: Move period outside of parentheses
> [24] Docs: Add a subject to make a full sentence
> [25] Docs: `id' -> `ID'
> [26] Docs: Clarify code32_start description
> [27] Docs: `;' -> `,'
> [28] Docs: `uncompress' -> `decompress'
> [29] Docs: Remove superfluous `linear'
> [30] Docs: Add `;' to end of pseudo-code lines
> [31] Docs: Streamline discussion of the kernel command line
> [32] Docs: Streamline the real-mode allocation requirement
> [33] Docs: Use ISO units and consistent language
> [34] Docs: Use `neither...nor...'
> [35] Docs: Use `[Rr]eal-mode' consistently
> [36] Docs: Use quotes for grouping
> [37] Docs: `32-bit (non-real-mode)' -> `protected-mode'
> [38] Docs: Clean up discussion of the 32-bit protocol
>
> diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt
> index 9b7221a..7696e20 100644
> --- a/Documentation/x86/boot.txt
> +++ b/Documentation/x86/boot.txt
> -Protocol 2.07: (Kernel 2.6.24) Added paravirtualised boot protocol.
> - Introduced hardware_subarch and hardware_subarch_data
> - and KEEP_SEGMENTS flag in load_flags.
> +Protocol 2.07: (Kernel 2.6.24) Added paravirtualized boot protocol,
We accept UK or US spellings.
> + introduced hardware_subarch and hardware_subarch_data
> + fields, and added the KEEP_SEGMENTS flag in load_flags.
>
> @@ -153,7 +151,7 @@ Offset Proto Name Meaning
>
> 01F1/1 ALL(1 setup_sects The size of the setup in sectors
> 01F2/2 ALL root_flags If set, the root is mounted readonly
> -01F4/4 2.04+(2 syssize The size of the 32-bit code in 16-byte paras
> +01F4/4 2.04+(2 sys_size The size of the 32-bit code
Why drop the "in 16-byte paragraphs" part?
> 01F8/2 ALL ram_size DO NOT USE - for bootsect.S use only
> 01FA/2 ALL vid_mode Video mode control
> 01FC/2 ALL root_dev Default root device number
> @@ -328,7 +326,7 @@ Type: read
> Offset/size: 0x20e/2
> Protocol: 2.00+
>
> - If set to a nonzero value, contains a pointer to a NUL-terminated
> + If set to a nonzero value, it contains a pointer to a NUL-terminated
non-zero ?
> 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).
> @@ -442,7 +441,7 @@ Protocol: 2.00+
> 1. as a boot loader hook (see ADVANCED BOOT LOADER HOOKS below.)
>
> 2. if a bootloader which does not install a hook loads a
> - relocatable kernel at a nonstandard address it will have to modify
> + relocatable kernel at a nonstandard address, it must modify
non-standard
> this field to point to the load address.
>
> Field name: ramdisk_image
> Field name: relocatable_kernel
> Type: read (reloc)
> Offset/size: 0x234/1
> Protocol: 2.05+
>
> - If this field is nonzero, the protected-mode part of the kernel can
> + If this field is nonzero, the protected-mode part of the kernel may
non-zero,
> be loaded at any address that satisfies the kernel_alignment field.
> After loading, the boot loader must set the code32_start field to
> - point to the loaded code, or to a boot loader hook.
> + point to the loaded code or to a boot loader hook.
>
> Field name: min_alignment
> Type: read (reloc)
> @@ -638,10 +637,9 @@ Type: write (special)
> Offset/size: 0x250/8
> Protocol: 2.09+
>
> - The 64-bit physical pointer to NULL terminated single linked list of
> - struct setup_data. This is used to define a more extensible boot
> - parameters passing mechanism. The definition of struct setup_data is
> - as follow:
> + A 64-bit physical pointer to point to a NULL-terminated singly-linked list of
> + struct setup_data. This is used to define a more extensible mechanism for
> + passing boot parameters. The definition of struct setup_data is as follows:
Some places in the text use NUL-terminated while this one uses NULL-terminated.
Would be good to be consistent. Oh, also just found "null-terminated".
>
> struct setup_data {
> u64 next;
> @@ -731,16 +732,15 @@ command line is entered using the following protocol:
> covered by setup_move_size, so you may need to adjust this
> field.
>
> -
> **** MEMORY LAYOUT OF THE REAL-MODE CODE
>
> -The real-mode code requires a stack/heap to be set up, as well as
> -memory allocated for the kernel command line. This needs to be done
> -in the real-mode accessible memory in bottom megabyte.
> +The real-mode code requires that memory be allocated for both a stack/heap
> +and the kernel command line; the allocated memory needs to be accessible
> +while in real mode (basically, it needs to be within the bottom mebibyte).
mebibyte. ugh. oh well.
>
> It should be noted that modern machines often have a sizable Extended
> BIOS Data Area (EBDA). As a result, it is advisable to use as little
> -of the low megabyte as possible.
> +of the bottom mebibyte as possible.
That changes seems unnecessary/unhelpful.
>
> Unfortunately, under the following circumstances the 0x90000 memory
> segment has to be used:
> Such a boot loader should enter the following fields in the header:
>
> - unsigned long base_ptr; /* base address for real-mode segment */
> + unsigned long base_ptr; /* base address for real-mode segment */
changing tab to space. does not matter.
> if ( setup_sects == 0 ) {
> setup_sects = 4;
> @@ -829,7 +829,7 @@ Such a boot loader should enter the following fields in the header:
> if ( base_ptr != 0x90000 ) {
> /* Copy the real-mode kernel */
> memcpy(0x90000, base_ptr, (setup_sects+1)*512);
> - base_ptr = 0x90000; /* Relocated */
> + base_ptr = 0x90000; /* Relocated */
ditto
> }
>
> strcpy(0x90000+cmd_line_offset, cmdline);
> @@ -842,21 +842,21 @@ Such a boot loader should enter the following fields in the header:
>
> **** LOADING THE REST OF THE KERNEL
>
> -The 32-bit (non-real-mode) kernel starts at offset (setup_sects+1)*512
> -in the kernel file (again, if setup_sects == 0 the real value is 4.)
> -It should be loaded at address 0x10000 for Image/zImage kernels and
> +The protected-mode kernel starts at offset "(setup_sects+1)*512"
> +in the kernel file (again, if (setup_sects == 0) { setup_sects = 4; }).
The C code isn't especially better than what it is replacing IMO.
But Peter can merge any/all of this if he chooses to.
> +It should be loaded at address 0x10000 for Image/zImage kernels and at
> 0x100000 for bzImage kernels.
>
Thanks.
---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
