Update STIVALE2.md
This commit is contained in:
mintsuki
parent
a002f05110
commit
a223f9c308
86
STIVALE2.md
86
STIVALE2.md
@ -1,19 +1,19 @@
|
||||
# stivale boot protocol specification
|
||||
# stivale2 boot protocol specification
|
||||
|
||||
The stivale boot protocol aims to be a *simple* to implement protocol which
|
||||
The stivale2 boot protocol is an improved version of the stivale protocol which
|
||||
provides the kernel with most of the features one may need in a *modern*
|
||||
x86_64 context (although 32-bit x86 is also supported).
|
||||
|
||||
## General information
|
||||
|
||||
In order to have a stivale compliant kernel, one must have a kernel executable
|
||||
in the `elf64` or `elf32` format and have a `.stivalehdr` section (described below).
|
||||
In order to have a stivale2 compliant kernel, one must have a kernel executable
|
||||
in the `elf64` or `elf32` format and have a `.stivale2hdr` section (described below).
|
||||
Other executable formats are not supported.
|
||||
|
||||
stivale will recognise whether the ELF file is 32-bit or 64-bit and load the kernel
|
||||
stivale2 will recognise whether the ELF file is 32-bit or 64-bit and load the kernel
|
||||
into the appropriate CPU mode.
|
||||
|
||||
stivale natively supports (only for 64-bit kernels) and encourages higher half kernels.
|
||||
stivale2 natively supports (only for 64-bit kernels) and encourages higher half kernels.
|
||||
The kernel can load itself at `0xffffffff80100000` or higher (as defined in the linker script)
|
||||
and the bootloader will take care of everything, no AT linker script directives needed.
|
||||
|
||||
@ -33,7 +33,7 @@ The kernel MUST NOT request to load itself at an address lower than `0x100000`
|
||||
### 64-bit kernel
|
||||
|
||||
`rip` will be the entry point as defined in the ELF file, unless the `entry_point`
|
||||
field in the stivale header is set to a non-0 value, in which case, it is set to
|
||||
field in the stivale2 header is set to a non-0 value, in which case, it is set to
|
||||
the value of `entry_point`.
|
||||
|
||||
At entry, the bootloader will have setup paging mappings as such:
|
||||
@ -46,7 +46,7 @@ At entry, the bootloader will have setup paging mappings as such:
|
||||
```
|
||||
|
||||
If the kernel is dynamic and not statically linked, the bootloader will relocate it.
|
||||
Furthermore if bit 0 of the flags field in the stivale header is set, the bootloader
|
||||
Furthermore if bit 0 of the flags field in the stivale2 header is set, the bootloader
|
||||
will perform kernel address space layout randomisation (KASLR).
|
||||
|
||||
The kernel should NOT modify the bootloader page tables, and it should only use them
|
||||
@ -64,23 +64,23 @@ IF flag, VM flag, and direction flag are cleared on entry. Other flags undefined
|
||||
|
||||
PG is enabled (`cr0`), PE is enabled (`cr0`), PAE is enabled (`cr4`),
|
||||
LME is enabled (`EFER`).
|
||||
If the stivale header tag for 5-level paging is present, then, if available,
|
||||
If the stivale2 header tag for 5-level paging is present, then, if available,
|
||||
5-level paging is enabled (LA57 bit in `cr4`).
|
||||
|
||||
The A20 gate is enabled.
|
||||
|
||||
PIC/APIC IRQs are all masked.
|
||||
|
||||
`rsp` is set to the requested stack as per stivale header.
|
||||
`rsp` is set to the requested stack as per stivale2 header.
|
||||
|
||||
`rdi` will point to the stivale structure (described below).
|
||||
`rdi` will point to the stivale2 structure (described below).
|
||||
|
||||
All other general purpose registers are set to 0.
|
||||
|
||||
### 32-bit kernel
|
||||
|
||||
`eip` will be the entry point as defined in the ELF file, unless the `entry_point`
|
||||
field in the stivale header is set to a non-0 value, in which case, it is set to
|
||||
field in the stivale2 header is set to a non-0 value, in which case, it is set to
|
||||
the value of `entry_point`.
|
||||
|
||||
At entry all segment registers are loaded as 32 bit code/data segments.
|
||||
@ -99,21 +99,21 @@ The A20 gate is enabled.
|
||||
|
||||
PIC/APIC IRQs are all masked.
|
||||
|
||||
`esp` is set to the requested stack as per stivale header.
|
||||
`esp` is set to the requested stack as per stivale2 header.
|
||||
|
||||
A pointer to the stivale structure (described below) is pushed onto this stack
|
||||
A pointer to the stivale2 structure (described below) is pushed onto this stack
|
||||
before the entry point is called.
|
||||
|
||||
All other general purpose registers are set to 0.
|
||||
|
||||
## stivale header (.stivalehdr)
|
||||
## stivale2 header (.stivale2hdr)
|
||||
|
||||
The kernel executable shall have a section `.stivalehdr` which will contain
|
||||
The kernel executable shall have a section `.stivale2hdr` which will contain
|
||||
the header that the bootloader will parse.
|
||||
|
||||
Said header looks like this:
|
||||
```c
|
||||
struct stivale_header {
|
||||
struct stivale2_header {
|
||||
uint64_t entry_point; // If not 0, this address will be jumped to as the
|
||||
// entry point of the kernel.
|
||||
// If set to 0, the ELF entry point will be used
|
||||
@ -129,22 +129,22 @@ struct stivale_header {
|
||||
// All other bits undefined
|
||||
|
||||
uint64_t tags; // Pointer to the first of the linked list of tags.
|
||||
// see "stivale header tags" section.
|
||||
// see "stivale2 header tags" section.
|
||||
// NULL = no tags.
|
||||
} __attribute__((packed));
|
||||
```
|
||||
|
||||
### stivale header tags
|
||||
### stivale2 header tags
|
||||
|
||||
The stivale header uses a mechanism to avoid having protocol versioning, but
|
||||
The stivale2 header uses a mechanism to avoid having protocol versioning, but
|
||||
rather, feature-specific support detection.
|
||||
|
||||
The kernel executable provides the bootloader with a linked list of structures,
|
||||
the first of which is pointed to by the `tags` entry of the stivale header.
|
||||
the first of which is pointed to by the `tags` entry of the stivale2 header.
|
||||
|
||||
Each tag shall contain these 2 fields:
|
||||
```c
|
||||
struct stivale_hdr_tag {
|
||||
struct stivale2_hdr_tag {
|
||||
uint64_t identifier;
|
||||
uint64_t next;
|
||||
} __attribute__((packed));
|
||||
@ -165,13 +165,13 @@ that does not require extra parameters.
|
||||
|
||||
#### Framebuffer header tag
|
||||
|
||||
This tag asks the stivale-compliant bootloader to initialise a graphical framebuffer
|
||||
This tag asks the stivale2-compliant bootloader to initialise a graphical framebuffer
|
||||
video mode.
|
||||
Omitting this tag will make the bootloader default to a CGA-compatible text mode,
|
||||
if supported.
|
||||
|
||||
```c
|
||||
struct stivale_hdr_tag_framebuffer {
|
||||
struct stivale2_hdr_tag_framebuffer {
|
||||
uint64_t identifier; // Identifier: 0x3ecc1bc43d0f7971
|
||||
uint64_t next;
|
||||
uint16_t framebuffer_width; // If all values are set to 0
|
||||
@ -188,26 +188,26 @@ Identifier: `0x932f477032007e8f`
|
||||
|
||||
This tag does not have extra members.
|
||||
|
||||
## stivale structure
|
||||
## stivale2 structure
|
||||
|
||||
The stivale structure returned by the bootloader looks like this:
|
||||
The stivale2 structure returned by the bootloader looks like this:
|
||||
```c
|
||||
struct stivale_struct {
|
||||
struct stivale2_struct {
|
||||
char bootloader_brand[64]; // Bootloader null-terminated brand string
|
||||
char bootloader_version[64]; // Bootloader null-terminated version string
|
||||
|
||||
uint64_t tags; // Pointer to the first of the linked list of tags.
|
||||
// see "stivale structure tags" section.
|
||||
// see "stivale2 structure tags" section.
|
||||
// NULL = no tags.
|
||||
} __attribute__((packed));
|
||||
```
|
||||
|
||||
### stivale structure tags
|
||||
### stivale2 structure tags
|
||||
|
||||
These tags work *very* similarly to the header tags, with the main difference being
|
||||
that these tags are returned to the kernel by the bootloader, instead.
|
||||
|
||||
See "stivale header tags".
|
||||
See "stivale2 header tags".
|
||||
|
||||
The kernel is responsible for parsing the tags and the identifiers, and interpreting
|
||||
the tags that it supports, while handling in a graceful manner the tags it does not
|
||||
@ -219,7 +219,7 @@ This tag reports to the kernel the command line string that was passed to it by
|
||||
the bootloader.
|
||||
|
||||
```c
|
||||
struct stivale_struct_tag_cmdline {
|
||||
struct stivale2_struct_tag_cmdline {
|
||||
uint64_t identifier; // Identifier: 0xe5e76a1b4597a781
|
||||
uint64_t next;
|
||||
uint64_t cmdline; // Pointer to a null-terminated cmdline
|
||||
@ -231,21 +231,21 @@ struct stivale_struct_tag_cmdline {
|
||||
This tag reports to the kernel the memory map built by the bootloader.
|
||||
|
||||
```c
|
||||
struct stivale_struct_tag_memmap {
|
||||
struct stivale2_struct_tag_memmap {
|
||||
uint64_t identifier; // Identifier: 0x2187f79e8612de07
|
||||
uint64_t next;
|
||||
uint64_t entries; // Count of memory map entries
|
||||
struct stivale_mmap_entry memmap[]; // Array of memory map entries
|
||||
struct stivale2_mmap_entry memmap[]; // Array of memory map entries
|
||||
} __attribute__((packed));
|
||||
```
|
||||
|
||||
###### Memory map entry
|
||||
|
||||
```c
|
||||
struct stivale_mmap_entry {
|
||||
struct stivale2_mmap_entry {
|
||||
uint64_t base; // Base of the memory section
|
||||
uint64_t length; // Length of the section
|
||||
enum stivale_mmap_type type; // Type (described below)
|
||||
enum stivale2_mmap_type type; // Type (described below)
|
||||
uint32_t unused;
|
||||
} __attribute__((packed));
|
||||
```
|
||||
@ -253,7 +253,7 @@ struct stivale_mmap_entry {
|
||||
`type` is an enumeration that can have the following values:
|
||||
|
||||
```
|
||||
enum stivale_mmap_type : uint32_t {
|
||||
enum stivale2_mmap_type : uint32_t {
|
||||
USABLE = 1,
|
||||
RESERVED = 2,
|
||||
ACPI_RECLAIMABLE = 3,
|
||||
@ -283,7 +283,7 @@ is it guaranteed that they do not overlap each other (except usable RAM).
|
||||
This tag reports to the kernel the currently set up framebuffer details, if any.
|
||||
|
||||
```c
|
||||
struct stivale_struct_tag_framebuffer {
|
||||
struct stivale2_struct_tag_framebuffer {
|
||||
uint64_t identifier; // Identifier: 0x506461d2950408fa
|
||||
uint64_t next;
|
||||
uint64_t framebuffer_addr; // Address of the framebuffer and related info
|
||||
@ -299,16 +299,16 @@ struct stivale_struct_tag_framebuffer {
|
||||
This tag lists modules that the bootloader loaded alongside the kernel, if any.
|
||||
|
||||
```c
|
||||
struct stivale_struct_tag_modules {
|
||||
struct stivale2_struct_tag_modules {
|
||||
uint64_t identifier; // Identifier: 0x4b6fe466aade04ce
|
||||
uint64_t next;
|
||||
uint64_t module_count; // Count of loaded modules
|
||||
struct stivale_module modules[]; // Array of module descriptors
|
||||
struct stivale2_module modules[]; // Array of module descriptors
|
||||
} __attribute__((packed));
|
||||
```
|
||||
|
||||
```c
|
||||
struct stivale_module {
|
||||
struct stivale2_module {
|
||||
uint64_t begin; // Address where the module is loaded
|
||||
uint64_t end; // End address of the module
|
||||
char string[128]; // 0-terminated string passed to the module
|
||||
@ -320,7 +320,7 @@ struct stivale_module {
|
||||
This tag reports to the kernel the location of the ACPI RSDP structure in memory.
|
||||
|
||||
```c
|
||||
struct stivale_struct_tag_rsdp {
|
||||
struct stivale2_struct_tag_rsdp {
|
||||
uint64_t identifier; // Identifier: 0x9e1786930a375e78
|
||||
uint64_t next;
|
||||
uint64_t rsdp; // Pointer to the ACPI RSDP structure
|
||||
@ -332,7 +332,7 @@ struct stivale_struct_tag_rsdp {
|
||||
This tag reports to the kernel the current UNIX epoch, as per RTC.
|
||||
|
||||
```c
|
||||
struct stivale_struct_tag_epoch {
|
||||
struct stivale2_struct_tag_epoch {
|
||||
uint64_t identifier; // Identifier: 0x566a7bed888e1407
|
||||
uint64_t next;
|
||||
uint64_t epoch; // UNIX epoch at boot, read from system RTC
|
||||
@ -344,7 +344,7 @@ struct stivale_struct_tag_epoch {
|
||||
This tag reports to the kernel info about the firmware.
|
||||
|
||||
```c
|
||||
struct stivale_struct_tag_firmware {
|
||||
struct stivale2_struct_tag_firmware {
|
||||
uint64_t identifier; // Identifier: 0x359d837855e3858c
|
||||
uint64_t next;
|
||||
uint64_t flags; // Bit 0: 0 = UEFI, 1 = BIOS
|
||||
|
||||
Loading…
Reference in New Issue
Block a user