[PATCH -mm -v3 2/2] i386/x86_64 boot: document for 32 bit boot protocol
This patch defines a 32-bit boot protocol and adds corresponding
document. It is based on the proposal of Peter Anvin.
Known issues:
- The fields in zero page are fairly complex (such as struct
edd_info). Is it necessary to document every field inside the first
level fields, until the primary data type? Or is it sufficient to
provide the C struct name only?
ChangeLog:
-- v3 --
- Move hd0_info and hd1_info back to zero page for compatibility.
-- v2 --
- Revise zero page description according to the source code and move
them to zero-page.txt.
Signed-off-by: Huang Ying <[EMAIL PROTECTED]>
---
boot.txt | 70 +++
zero-page.txt | 129 +-
2 files changed, 99 insertions(+), 100 deletions(-)
Index: linux-2.6.23-rc6/Documentation/i386/boot.txt
===
--- linux-2.6.23-rc6.orig/Documentation/i386/boot.txt 2007-09-19
16:45:23.0 +0800
+++ linux-2.6.23-rc6/Documentation/i386/boot.txt2007-09-19
16:45:27.0 +0800
@@ -2,7 +2,7 @@
H. Peter Anvin <[EMAIL PROTECTED]>
- Last update 2007-05-23
+ Last update 2007-09-18
On the i386 platform, the Linux kernel uses a rather complicated boot
convention. This has evolved partially due to historical aspects, as
@@ -42,6 +42,9 @@
Protocol 2.06: (Kernel 2.6.22) Added a field that contains the size of
the boot command line
+Protocol 2.07: (kernel 2.6.23) Added a field of 64-bit physical
+ pointer to single linked list of struct setup_data.
+ Added 32-bit boot protocol.
MEMORY LAYOUT
@@ -168,6 +171,9 @@
0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not
0235/3 N/A pad2Unused
0238/4 2.06+ cmdline_sizeMaximum size of the kernel command line
+023c/4 N/A pad3Unused
+0240/8 2.07+ setup_data 64-bit physical pointer to linked list
+ of struct setup_data
(1) For backwards compatibility, if the setup_sects field contains 0, the
real value is 4.
@@ -480,6 +486,36 @@
cmdline_size characters. With protocol version 2.05 and earlier, the
maximum size was 255.
+Field name:setup_data
+Type: write (obligatory)
+Offset/size: 0x240/8
+Protocol: 2.07+
+
+ 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:
+
+ struct setup_data {
+ u64 next;
+ u32 type;
+ u32 len;
+ u8 data[0];
+ } __attribute__((packed));
+
+ Where, the next is a 64-bit physical pointer to the next node of
+ linked list, the next field of the last node is 0; the type is used
+ to identify the contents of data; the len is the length of data
+ field; the data holds the real payload.
+
+ With this field, to add a new boot parameter written by bootloader,
+ it is not needed to add a new field to real mode header, just add a
+ new setup_data type is sufficient. But to add a new boot parameter
+ read by bootloader, it is still needed to add a new field.
+
+ TODO: Where is the safe place to place the linked list of struct
+ setup_data?
+
THE KERNEL COMMAND LINE
@@ -753,3 +789,35 @@
After completing your hook, you should jump to the address
that was in this field before your boot loader overwrote it
(relocated, if appropriate.)
+
+
+ SETUP DATA TYPES
+
+
+ 32-bit BOOT PROTOCOL
+
+For machine with some new BIOS other than legacy BIOS, such as EFI,
+LinuxBIOS, etc, and kexec, the 16-bit real mode setup code in kernel
+based on legacy BIOS can not be used, so a 32-bit boot protocol need
+to be defined.
+
+In 32-bit boot protocol, the first step in loading a Linux kernel
+should still be to load the real-mode code and then examine the kernel
+header at offset 0x01f1. But, it is not necessary to load all
+real-mode code, just first 4K bytes traditionally known as "zero page"
+is needed.
+
+In addition to read/modify/write kernel header of the zero page as
+that of 16-bit boot protocol, the boot loader should also fill the
+additional fields of the zero page as that described in zero-page.txt.
+
+After loading and setuping the zero page, the boot loader can load the
+32/64-bit kernel in the same way as that of 16-bit boot protocol.
+
+In 32-bit boot protocol, the kernel is started by jumping to the
+32-bit kernel entry point, which is the start address of loaded
+32/64-bit kernel.
+
+At entry, the CPU must be in 32-bit protected mode with paging
+disabled; the CS and DS must be 4G flat segments; %esi holds the base
+address of the "zero page"; %esp, %ebp, %edi should be zero.
Index:
[PATCH -mm -v3 2/2] i386/x86_64 boot: document for 32 bit boot protocol
This patch defines a 32-bit boot protocol and adds corresponding
document. It is based on the proposal of Peter Anvin.
Known issues:
- The fields in zero page are fairly complex (such as struct
edd_info). Is it necessary to document every field inside the first
level fields, until the primary data type? Or is it sufficient to
provide the C struct name only?
ChangeLog:
-- v3 --
- Move hd0_info and hd1_info back to zero page for compatibility.
-- v2 --
- Revise zero page description according to the source code and move
them to zero-page.txt.
Signed-off-by: Huang Ying [EMAIL PROTECTED]
---
boot.txt | 70 +++
zero-page.txt | 129 +-
2 files changed, 99 insertions(+), 100 deletions(-)
Index: linux-2.6.23-rc6/Documentation/i386/boot.txt
===
--- linux-2.6.23-rc6.orig/Documentation/i386/boot.txt 2007-09-19
16:45:23.0 +0800
+++ linux-2.6.23-rc6/Documentation/i386/boot.txt2007-09-19
16:45:27.0 +0800
@@ -2,7 +2,7 @@
H. Peter Anvin [EMAIL PROTECTED]
- Last update 2007-05-23
+ Last update 2007-09-18
On the i386 platform, the Linux kernel uses a rather complicated boot
convention. This has evolved partially due to historical aspects, as
@@ -42,6 +42,9 @@
Protocol 2.06: (Kernel 2.6.22) Added a field that contains the size of
the boot command line
+Protocol 2.07: (kernel 2.6.23) Added a field of 64-bit physical
+ pointer to single linked list of struct setup_data.
+ Added 32-bit boot protocol.
MEMORY LAYOUT
@@ -168,6 +171,9 @@
0234/1 2.05+ relocatable_kernel Whether kernel is relocatable or not
0235/3 N/A pad2Unused
0238/4 2.06+ cmdline_sizeMaximum size of the kernel command line
+023c/4 N/A pad3Unused
+0240/8 2.07+ setup_data 64-bit physical pointer to linked list
+ of struct setup_data
(1) For backwards compatibility, if the setup_sects field contains 0, the
real value is 4.
@@ -480,6 +486,36 @@
cmdline_size characters. With protocol version 2.05 and earlier, the
maximum size was 255.
+Field name:setup_data
+Type: write (obligatory)
+Offset/size: 0x240/8
+Protocol: 2.07+
+
+ 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:
+
+ struct setup_data {
+ u64 next;
+ u32 type;
+ u32 len;
+ u8 data[0];
+ } __attribute__((packed));
+
+ Where, the next is a 64-bit physical pointer to the next node of
+ linked list, the next field of the last node is 0; the type is used
+ to identify the contents of data; the len is the length of data
+ field; the data holds the real payload.
+
+ With this field, to add a new boot parameter written by bootloader,
+ it is not needed to add a new field to real mode header, just add a
+ new setup_data type is sufficient. But to add a new boot parameter
+ read by bootloader, it is still needed to add a new field.
+
+ TODO: Where is the safe place to place the linked list of struct
+ setup_data?
+
THE KERNEL COMMAND LINE
@@ -753,3 +789,35 @@
After completing your hook, you should jump to the address
that was in this field before your boot loader overwrote it
(relocated, if appropriate.)
+
+
+ SETUP DATA TYPES
+
+
+ 32-bit BOOT PROTOCOL
+
+For machine with some new BIOS other than legacy BIOS, such as EFI,
+LinuxBIOS, etc, and kexec, the 16-bit real mode setup code in kernel
+based on legacy BIOS can not be used, so a 32-bit boot protocol need
+to be defined.
+
+In 32-bit boot protocol, the first step in loading a Linux kernel
+should still be to load the real-mode code and then examine the kernel
+header at offset 0x01f1. But, it is not necessary to load all
+real-mode code, just first 4K bytes traditionally known as zero page
+is needed.
+
+In addition to read/modify/write kernel header of the zero page as
+that of 16-bit boot protocol, the boot loader should also fill the
+additional fields of the zero page as that described in zero-page.txt.
+
+After loading and setuping the zero page, the boot loader can load the
+32/64-bit kernel in the same way as that of 16-bit boot protocol.
+
+In 32-bit boot protocol, the kernel is started by jumping to the
+32-bit kernel entry point, which is the start address of loaded
+32/64-bit kernel.
+
+At entry, the CPU must be in 32-bit protected mode with paging
+disabled; the CS and DS must be 4G flat segments; %esi holds the base
+address of the zero page; %esp, %ebp, %edi should be zero.
Index:
