:: commit 3c909c017b2e63b683d3c097fe6bb26854c7b72b

mintsuki <mintsuki@protonmail.com> — 2022-03-26 00:31

parents: 21f8640510

docs: limine: More documentation work

diff --git a/PROTOCOL.md b/PROTOCOL.md
index 44ed6a15..70d6b2f6 100644
--- a/PROTOCOL.md
+++ b/PROTOCOL.md
@@ -2,7 +2,7 @@
 
 The Limine boot protocol is a modern, minimal, fast, and extensible boot
 protocol, with a focus on backwards and forwards compatibility,
-created from the experienced gained by working on the
+created from the experience gained by working on the
 [stivale boot protocols](https://github.com/stivale).
 
 This file serves as the official centralised collection of features that
@@ -10,6 +10,10 @@ the Limine boot protocol is composed of. Other bootloaders may support extra
 unofficial features, but it is strongly recommended to avoid fragmentation
 and submit new features by opening a pull request to this repository.
 
+The [limine.h](/limine.h) file provides an implementation of all the
+structures and constants described in this document, for the C and C++
+languages.
+
 ## General Notes
 
 All pointers are 64-bit wide. All pointers point to the object with the
@@ -121,7 +125,8 @@ with at least the following entries, starting at offset 0:
 
 The IDT is in an undefined state. Kernel must load its own.
 
-IF flag, VM flag, and direction flag are cleared on entry. Other flags undefined.
+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`).
@@ -204,6 +209,46 @@ struct limine_hhdm_response {
 * `offset` - the virtual address offset of the beginning of the higher half
 direct map.
 
+### Terminal Feature
+
+ID:
+```c
+#define LIMINE_TERMINAL_REQUEST { LIMINE_COMMON_MAGIC, 0x0785a0aea5d0750f, 0x1c1936fee0d6cf6e }
+```
+
+Request:
+```c
+typedef void (*limine_terminal_callback)(uint64_t, uint64_t, uint64_t, uint64_t);
+
+struct limine_terminal_request {
+    uint64_t id[4];
+    uint64_t revision;
+    struct limine_terminal_response *response;
+    limine_terminal_callback callback;
+};
+```
+
+* `callback` - Pointer to the callback function.
+
+Response:
+```c
+typedef void (*limine_terminal_write)(const char *, uint64_t);
+
+struct limine_terminal_response {
+    uint64_t revision;
+    uint32_t columns;
+    uint32_t rows;
+    limine_terminal_write write;
+};
+```
+
+* `columns` and `rows` - Columns and rows provided by the terminal.
+* `write` - Physical pointer to the terminal write() function.
+
+Note: Omitting this request will cause the bootloader to not initialise
+the terminal service. The terminal is further documented in the stivale2
+specification.
+
 ### Framebuffer Feature
 
 ID:
@@ -344,6 +389,62 @@ processor. This field is unused for the structure describing the bootstrap
 processor.
 * `extra_argument` - A free for use field.
 
+### Memory Map Feature
+
+ID:
+```c
+#define LIMINE_MEMMAP_REQUEST { LIMINE_COMMON_MAGIC, 0x67cf3d9d378a806f, 0xe304acdfc50c3c62 }
+```
+
+Request:
+```c
+struct limine_memmap_request {
+    uint64_t id[4];
+    uint64_t revision;
+    struct limine_memmap_response *response;
+};
+```
+
+Response:
+```c
+struct limine_memmap_response {
+    uint64_t revision;
+    uint64_t entry_count;
+    struct limine_memmap_entry **entries;
+};
+```
+
+* `entry_count` - How many memory map entries are present.
+* `entries` - Pointer to an array of `entry_count` pointers to
+`struct limine_memmap_entry` structures.
+
+```c
+// Constants for `type`
+#define LIMINE_MEMMAP_USABLE                 0
+#define LIMINE_MEMMAP_RESERVED               1
+#define LIMINE_MEMMAP_ACPI_RECLAIMABLE       2
+#define LIMINE_MEMMAP_ACPI_NVS               3
+#define LIMINE_MEMMAP_BAD_MEMORY             4
+#define LIMINE_MEMMAP_BOOTLOADER_RECLAIMABLE 5
+#define LIMINE_MEMMAP_KERNEL_AND_MODULES     6
+#define LIMINE_MEMMAP_FRAMEBUFFER            7
+
+struct limine_memmap_entry {
+    uint64_t base;
+    uint64_t length;
+    uint64_t type;
+};
+```
+
+Note: The kernel and modules loaded are not marked as usable memory.
+They are marked as Kernel/Modules. The entries are guaranteed to be sorted by
+base address, lowest to highest. Usable and bootloader reclaimable entries
+are guaranteed to be 4096 byte aligned for both base and length. Usable and
+bootloader reclaimable entries are guaranteed not to overlap with any other
+entry. To the contrary, all non-usable entries (including kernel/modules) are
+not guaranteed any alignment, nor is it guaranteed that they do not overlap
+other entries.
+
 ### Entry Point Feature
 
 ID:
@@ -442,7 +543,8 @@ struct limine_file_location {
 * `revision` - Revision of the `struct limine_file_location` structure.
 * `partition_index` - 1-based partition index of the volume from which the
 module was loaded. If 0, it means invalid or unpartitioned.
-* `tftp_ip` - If non-0, this is the IP of the TFTP server the file was loaded from.
+* `tftp_ip` - If non-0, this is the IP of the TFTP server the file was loaded
+from.
 * `tftp_port` - Likewise, but port.
 * `mbr_disk_id` - If non-0, this is the ID of the disk the module was loaded
 from as reported in its MBR.
diff --git a/common/GNUmakefile b/common/GNUmakefile
index f3c2d11e..afab553a 100644
--- a/common/GNUmakefile
+++ b/common/GNUmakefile
@@ -66,6 +66,7 @@ override INTERNAL_CFLAGS := \
 	-I../freestanding_headers \
 	-I'$(call SHESCAPE,$(BUILDDIR))/..' \
 	-I. \
+	-I.. \
 	-I../stivale \
 	-I'$(call SHESCAPE,$(BUILDDIR))/tinf'
 
diff --git a/common/limine.h b/limine.h
similarity index 96%
rename from common/limine.h
rename to limine.h
index f591856b..c6a9048e 100644
--- a/common/limine.h
+++ b/limine.h
@@ -3,7 +3,7 @@
 
 #include <stdint.h>
 
-// Misc
+/* Misc */
 
 #ifdef LIMINE_NO_POINTERS
 #  define LIMINE_PTR(TYPE) uint64_t
@@ -31,7 +31,7 @@ struct limine_file_location {
     struct limine_uuid part_uuid;
 };
 
-// Boot info
+/* Boot info */
 
 #define LIMINE_BOOTLOADER_INFO_REQUEST { LIMINE_COMMON_MAGIC, 0xf55038d8e2a1202f, 0x279426fcf5f59740 }
 
@@ -47,7 +47,7 @@ struct limine_bootloader_info_request {
     LIMINE_PTR(struct limine_bootloader_info_response *) response;
 };
 
-// HHDM
+/* HHDM */
 
 #define LIMINE_HHDM_REQUEST { LIMINE_COMMON_MAGIC, 0x48dcf1cb8ad2b852, 0x63984e959a98244b }
 
@@ -62,7 +62,7 @@ struct limine_hhdm_request {
     LIMINE_PTR(struct limine_hhdm_response *) response;
 };
 
-// Framebuffer
+/* Framebuffer */
 
 #define LIMINE_FRAMEBUFFER_REQUEST { LIMINE_COMMON_MAGIC, 0xcbfe81d7dd2d1977, 0x063150319ebc9b71 }
 
@@ -98,7 +98,7 @@ struct limine_framebuffer_request {
     LIMINE_PTR(struct limine_framebuffer_response *) response;
 };
 
-// Terminal
+/* Terminal */
 
 #define LIMINE_TERMINAL_REQUEST { LIMINE_COMMON_MAGIC, 0x0785a0aea5d0750f, 0x1c1936fee0d6cf6e }
 
@@ -119,7 +119,7 @@ struct limine_terminal_request {
     LIMINE_PTR(limine_terminal_callback) callback;
 };
 
-// 5-level paging
+/* 5-level paging */
 
 #define LIMINE_5_LEVEL_PAGING_REQUEST { LIMINE_COMMON_MAGIC, 0x94469551da9b3192, 0xebe5e86db7382888 }
 
@@ -133,7 +133,7 @@ struct limine_5_level_paging_request {
     LIMINE_PTR(struct limine_5_level_paging_response *) response;
 };
 
-// SMP
+/* SMP */
 
 #define LIMINE_SMP_REQUEST { LIMINE_COMMON_MAGIC, 0x95a67b819a1b857e, 0xa0b61b723b6a73e0 }
 
@@ -164,7 +164,7 @@ struct limine_smp_request {
     uint64_t flags;
 };
 
-// Memory map
+/* Memory map */
 
 #define LIMINE_MEMMAP_REQUEST { LIMINE_COMMON_MAGIC, 0x67cf3d9d378a806f, 0xe304acdfc50c3c62 }
 
@@ -195,7 +195,7 @@ struct limine_memmap_request {
     LIMINE_PTR(struct limine_memmap_response *) response;
 };
 
-// Entry point
+/* Entry point */
 
 #define LIMINE_ENTRY_POINT_REQUEST { LIMINE_COMMON_MAGIC, 0x13d86c035a1cd3e1, 0x2b0caa89d8f3026a }
 
@@ -212,7 +212,7 @@ struct limine_entry_point_request {
     LIMINE_PTR(limine_entry_point) entry;
 };
 
-// Module
+/* Module */
 
 #define LIMINE_MODULE_REQUEST { LIMINE_COMMON_MAGIC, 0x3e7e279702be32af, 0xca1c4f3bd1280cee }
 
@@ -236,7 +236,7 @@ struct limine_module_request {
     LIMINE_PTR(struct limine_module_response *) response;
 };
 
-// RSDP
+/* RSDP */
 
 #define LIMINE_RSDP_REQUEST { LIMINE_COMMON_MAGIC, 0xc5e77b6b397e7b43, 0x27637845accdcf3c }
 
@@ -251,7 +251,7 @@ struct limine_rsdp_request {
     LIMINE_PTR(struct limine_rsdp_response *) response;
 };
 
-// SMBIOS
+/* SMBIOS */
 
 #define LIMINE_SMBIOS_REQUEST { LIMINE_COMMON_MAGIC, 0x9e9046f11e095391, 0xaa4a520fefbde5ee }
 
@@ -267,7 +267,7 @@ struct limine_smbios_request {
     LIMINE_PTR(struct limine_smbios_response *) response;
 };
 
-// EFI system table
+/* EFI system table */
 
 #define LIMINE_EFI_SYSTEM_TABLE_REQUEST { LIMINE_COMMON_MAGIC, 0x5ceba5163eaaf6d6, 0x0a6981610cf65fcc }
 
@@ -282,7 +282,7 @@ struct limine_efi_system_table_request {
     LIMINE_PTR(struct limine_efi_system_table_response *) response;
 };
 
-// Boot time
+/* Boot time */
 
 #define LIMINE_BOOT_TIME_REQUEST { LIMINE_COMMON_MAGIC, 0x502746e184c088aa, 0xfbc5ec83e6327893 }
 
@@ -297,7 +297,7 @@ struct limine_boot_time_request {
     LIMINE_PTR(struct limine_boot_time_response *) response;
 };
 
-// Kernel address
+/* Kernel address */
 
 #define LIMINE_KERNEL_ADDRESS_REQUEST { LIMINE_COMMON_MAGIC, 0x71ba76863cc55f63, 0xb2644a48c516a487 }
 
diff --git a/test/GNUmakefile b/test/GNUmakefile
index 4aa3098a..d4910af4 100644
--- a/test/GNUmakefile
+++ b/test/GNUmakefile
@@ -31,7 +31,7 @@ INTERNAL_LD_FLAGS_MULTIBOOT1 := \
 INTERNALCFLAGS  :=       \
 	-I../stivale         \
 	-I.                  \
-	-I../common          \
+	-I..                 \
 	-std=c11             \
 	-ffreestanding       \
 	-fno-stack-protector \
tab: 248 wrap: offon