OSDev.wiki

Limine Bare Bones: Difference between revisions

Page Discussion

Limine Bare Bones (view source)

Revision as of 04:04, 3 July 2024

6,232 bytes added ,  2 days ago
→‎Compiling the kernel on macOS: Correct make variable names
[unchecked revision][unchecked revision]
VisualWikitext
(Created page with "{{BeginnersWarning}} {{Rating|1}} {{Template:Kernel designs}} The Limine Boot Protocol is the flagship boot protocol provided by the Limine bootloader. Like the [[stivale...")
 
(→‎Compiling the kernel on macOS: Correct make variable names)
(69 intermediate revisions by 8 users not shown)
Line 3:
{{Template:Kernel designs}}
 
The Limine Boot Protocol is the flagshipnative boot protocol provided by the [[Limine]] bootloader. Like the [[stivale]] protocols it supersedes, itIt is a designed to overcome shortcomings of common boot protocols used by hobbyist OS developers, such as [[Multiboot]], and [[stivale]] itself.
 
It provides cutting edge features such as 5-level paging support, 64-bit [[Long Mode]] support, and direct higher half kernel loading.
 
The Limine boot protocol is firmware and architecture agnostic. The Limine bootloader supports x86-64, IA-32, aarch64, and riscv64.
 
This article will demonstrate how to write a small 64-bit higher half Limine-compliant x86-64 kernel in (GNU) [[C]], and boot it using the [[Limine]] bootloader.
 
ItAdditionally, it is alsohighly recommended to check out [https://github.com/limine-bootloader/limine-barebonesc-template this template project] as it provides example buildable code to go along with this guide.
 
===Overview===
 
For this example, we will create these 2 files andto place them increate the samebasic directory tree of our project:
* kernelsrc/main.c
* linker.ld
 
As one may notice, there is no "entry point" assembly stub, as one is not necessary with the Limine protocol when using a language which can make use of a standard SysV x86 [[Calling Conventions|calling convention]].
 
Furthermore, we will download the header file '''limine.h''' which defines structures and constants that we will use to interact with the bootloader from [https://raw.githubusercontentgithub.com/limine-bootloader/limine/raw/trunk/limine.h here], and place it in the same'''src''' directory as the other files.
 
Obviously, this is just a bare bones example, and one should always refer to the [https://github.com/limine-bootloader/limine/blob/trunk/PROTOCOL.md Limine protocol specification] for more details and information.
 
===kernelsrc/main.c===
 
This is the kernel "main".
 
<sourcesyntaxhighlight lang="c">
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include <limine.h>
 
// Set the base revision to 2, this is recommended as this is the latest
// base revision described by the Limine boot protocol specification.
// See specification for further info.
 
__attribute__((used, section(".requests")))
static volatile LIMINE_BASE_REVISION(2);
 
// The Limine requests can be placed anywhere, but it is important that
// the compiler does not optimise them away, so, usually, they should
// be made volatile or equivalent., _and_ they should be accessed at least
// once or marked as used with the "used" attribute as done here.
 
__attribute__((used, section(".requests")))
static volatile struct limine_terminal_request terminal_request = {
static volatile struct limine_framebuffer_request framebuffer_request = {
.id = LIMINE_TERMINAL_REQUEST,
.id = LIMINE_FRAMEBUFFER_REQUEST,
.revision = 0
};
 
// Finally, define the start and end markers for the Limine requests.
static void done(void) {
// These can also be moved anywhere, to any .c file, as seen fit.
 
__attribute__((used, section(".requests_start_marker")))
static volatile LIMINE_REQUESTS_START_MARKER;
 
__attribute__((used, section(".requests_end_marker")))
static volatile LIMINE_REQUESTS_END_MARKER;
 
// GCC and Clang reserve the right to generate calls to the following
// 4 functions even if they are not directly called.
// Implement them as the C specification mandates.
// DO NOT remove or rename these functions, or stuff will eventually break!
// They CAN be moved to a different .c file.
 
void *memcpy(void *dest, const void *src, size_t n) {
uint8_t *pdest = (uint8_t *)dest;
const uint8_t *psrc = (const uint8_t *)src;
 
for (size_t i = 0; i < n; i++) {
pdest[i] = psrc[i];
}
 
return dest;
}
 
void *memset(void *s, int c, size_t n) {
uint8_t *p = (uint8_t *)s;
 
for (size_t i = 0; i < n; i++) {
p[i] = (uint8_t)c;
}
 
return s;
}
 
void *memmove(void *dest, const void *src, size_t n) {
uint8_t *pdest = (uint8_t *)dest;
const uint8_t *psrc = (const uint8_t *)src;
 
if (src > dest) {
for (size_t i = 0; i < n; i++) {
pdest[i] = psrc[i];
}
} else if (src < dest) {
for (size_t i = n; i > 0; i--) {
pdest[i-1] = psrc[i-1];
}
}
 
return dest;
}
 
int memcmp(const void *s1, const void *s2, size_t n) {
const uint8_t *p1 = (const uint8_t *)s1;
const uint8_t *p2 = (const uint8_t *)s2;
 
for (size_t i = 0; i < n; i++) {
if (p1[i] != p2[i]) {
return p1[i] < p2[i] ? -1 : 1;
}
}
 
return 0;
}
 
// Halt and catch fire function.
static void hcf(void) {
asm ("cli");
for (;;) {
__asm__asm ("hlt");
}
}
 
// The following will be our kernel's entry point.
// If renaming _start() to something else, make sure to change the
// linker script accordingly.
void _start(void) {
// Ensure wethe gotbootloader aactually terminalunderstands our base revision (see spec).
if (terminal_request.responseLIMINE_BASE_REVISION_SUPPORTED == NULLfalse) {
hcf();
|| terminal_request.response->terminal_count < 1) {
done();
}
 
// Ensure we got a framebuffer.
// We should now be able to call the Limine terminal to print out
if (framebuffer_request.response == NULL
// a simple "Hello World" to screen.
|| framebuffer_request.response->framebuffer_count < 1) {
struct limine_terminal *terminal = terminal_request.response->terminals[0];
hcf();
terminal_request.response->write(terminal, "Hello World", 11);
}
 
// Fetch the first framebuffer.
struct limine_framebuffer *framebuffer = framebuffer_request.response->framebuffers[0];
 
// Note: we assume the framebuffer model is RGB with 32-bit pixels.
for (size_t i = 0; i < 100; i++) {
volatile uint32_t *fb_ptr = framebuffer->address;
fb_ptr[i * (framebuffer->pitch / 4) + i] = 0xffffff;
}
 
// We're done, just hang...
donehcf();
}
 
</syntaxhighlight>
</source>
 
'''Note:''' Using the Limine terminal requires that the kernel maintains some state as described in the specification (https://github.com/limine-bootloader/limine/blob/trunk/PROTOCOL.md#x86_64-1).
 
===linker.ld===
Line 74 ⟶ 161:
This is going to be our linker script describing where our sections will end up in memory.
 
<sourcesyntaxhighlight lang="c">
/* Tell the linker that we want an x86_64 ELF64 output file */
OUTPUT_FORMAT(elf64-x86-64)
Line 86 ⟶ 173:
PHDRS
{
nulltext PT_NULL PT_LOAD FLAGS(00x05) ; /* NullExecute + segmentRead */
text rodata PT_LOAD FLAGS((1 << 00x04) | (1 << 2)) ; /* ExecuteRead + Readonly */
rodatadata PT_LOAD FLAGS((1 << 20x06)) ; /* Write /*+ Read only */
data PT_LOAD dynamic PT_DYNAMIC FLAGS((1 << 10x06) | (1 << 2)) ; /* WriteDynamic PHDR +for Readrelocations */
}
 
Line 105 ⟶ 192:
 
/* Move to the next memory page for .rodata */
. += ALIGN(CONSTANT(MAXPAGESIZE));
 
.rodata : {
Line 112 ⟶ 199:
 
/* Move to the next memory page for .data */
. += ALIGN(CONSTANT(MAXPAGESIZE));
 
.data : {
*(.data .data.*)
 
/* Place the sections that contain the Limine requests as part of the .data */
/* output section. */
KEEP(*(.requests_start_marker))
KEEP(*(.requests))
KEEP(*(.requests_end_marker))
} :data
 
/* Dynamic section for relocations, both in its own PHDR and inside data PHDR */
.dynamic : {
*(.dynamic)
} :data :dynamic
 
/* NOTE: .bss needs to be the last thing mapped to :data, otherwise lots of */
/* unnecessary zeros will be written to the binary. */
/* If you need, for example, .init_array and .fini_array, those should be placed */
/* above this. */
.bss : {
*(COMMON)
*(.bss .bss.*)
*(COMMON)
} :data
 
/* Discard .note.* and .eh_frame* since they may cause issues on some hosts. */
/* Also discard the program interpreter section since we do not need one. This is */
/* more or less equivalent to the --no-dynamic-linker linker flag, except that it */
/* works with ld.gold. */
/DISCARD/ : {
*(.eh_frame*)
*(.note .note.*)
*(.interp)
}
}
 
</syntaxhighlight>
</source>
 
==Building the kernel and creating an image==
Line 134 ⟶ 246:
GNU make will process it.
 
<sourcesyntaxhighlight lang="make">
# Nuke built-in rules and variables.
override MAKEFLAGS += -rR
 
# This is the name that our final kernel executable will have.
# Change as needed.
override KERNEL := myos.elf
 
# Convenience macro to reliably declare user overridable variables.
define DEFAULT_VAR =
ifeq ($(origin $1),default)
override $(1) := $(2)
endif
ifeq ($(origin $1),undefined)
override $(1) := $(2)
endif
endef
 
# It is highly recommendedsuggested to use a custom built cross toolchain to build a kernel.
# We are only using the standard "cc" as a placeholder here., Itit may work by using
# the host system's toolchain, but this is not guaranteed.
override DEFAULT_KCC := cc
ifeq ($(origin CC), default)
$(eval $(call DEFAULT_VAR,KCC,$(DEFAULT_KCC)))
CC := cc
endif
 
# Same thing for "ld" (the linker).
# Likewise, "ld" here is just a placeholder and your mileage may vary if using the
override DEFAULT_KLD := ld
# host's "ld".
$(eval $(call DEFAULT_VAR,KLD,$(DEFAULT_KLD)))
ifeq ($(origin LD), default)
LD := ld
endif
 
# User controllable CFLAGSC flags.
override DEFAULT_KCFLAGS := -g -O2 -pipe
CFLAGS ?= -O2 -g -Wall -Wextra -Wpedantic -pipe
$(eval $(call DEFAULT_VAR,KCFLAGS,$(DEFAULT_KCFLAGS)))
 
# User controllable C preprocessor flags. We set none by default.
override DEFAULT_KCPPFLAGS :=
$(eval $(call DEFAULT_VAR,KCPPFLAGS,$(DEFAULT_KCPPFLAGS)))
 
# User controllable nasm flags.
override DEFAULT_KNASMFLAGS := -F dwarf -g
$(eval $(call DEFAULT_VAR,KNASMFLAGS,$(DEFAULT_KNASMFLAGS)))
 
# User controllable linker flags. We set none by default.
override DEFAULT_KLDFLAGS :=
LDFLAGS ?=
$(eval $(call DEFAULT_VAR,KLDFLAGS,$(DEFAULT_KLDFLAGS)))
 
# Internal C flags that should not be changed by the user.
override INTERNALCFLAGSKCFLAGS :+= \
-I. -Wall \
-Wextra \
-std=c11 \
-std=gnu11 \
-ffreestanding \
-ffreestanding \
-fno-stack-protector \
-fno-stack-check protector \
-fno-stack-check \
-fno-pic \
-fno-lto \
-mabi=sysv \
-mno-80387 -fPIE \
-mno-mmx -m64 \
-march=x86-64 \
-mno-3dnow \
-mno-80387 \
-mno-sse \
-mno-mmx \
-mno-sse2 \
-mno-sse \
-mno-red-zone \
-mno-sse2 \
-mcmodel=kernel \
-mno-red-zone
-MMD
 
# Internal C preprocessor flags that should not be changed by the user.
override KCPPFLAGS := \
-I src \
$(KCPPFLAGS) \
-MMD \
-MP
 
# Internal linker flags that should not be changed by the user.
override INTERNALLDFLAGSKLDFLAGS :+= \
-m elf_x86_64 \
-Tlinker.ld \
-nostdlib \
-nostdlib \
-pie \
-zmax-page-size=0x1000 \
-z text \
-static
-z max-page-size=0x1000 \
-T linker.ld
 
# Internal nasm flags that should not be changed by the user.
# Use find to glob all *.c files in the directory and extract the object names.
override CFILESKNASMFLAGS :+= $(shell find ./ -type f -name '*.c')\
-Wall \
override OBJ := $(CFILES:.c=.o)
-f elf64
override HEADER_DEPS := $(CFILES:.c=.d)
 
# Use "find" to glob all *.c, *.S, and *.asm files in the tree and obtain the
# object and header dependency file names.
override CFILES := $(shell cd src && find -L * -type f -name '*.c')
override ASFILES := $(shell cd src && find -L * -type f -name '*.S')
override NASMFILES := $(shell cd src && find -L * -type f -name '*.asm')
override OBJ := $(addprefix obj/,$(CFILES:.c=.c.o) $(ASFILES:.S=.S.o) $(NASMFILES:.asm=.asm.o))
override HEADER_DEPS := $(addprefix obj/,$(CFILES:.c=.c.d) $(ASFILES:.S=.S.d))
 
# Default target.
.PHONY: all
all: bin/$(KERNEL)
 
# Link rules for the final kernel executable.
# The magic printf/dd command is used to force the final ELF file type to ET_DYN.
$(KERNEL): $(OBJ)
# GNU binutils, for silly reasons, forces the ELF type to ET_EXEC even for
$(LD) $(OBJ) $(LDFLAGS) $(INTERNALLDFLAGS) -o $@
# relocatable PIEs, if the base load address is non-0.
# See https://sourceware.org/bugzilla/show_bug.cgi?id=31795 for more information.
bin/$(KERNEL): GNUmakefile linker.ld $(OBJ)
mkdir -p "$$(dirname $@)"
$(KLD) $(OBJ) $(KLDFLAGS) -o $@
printf '\003' | dd of=$@ bs=1 count=1 seek=16 conv=notrunc
 
# Include header dependencies.
# Compilation rules for *.c files.
-include $(HEADER_DEPS)
 
%.o: %.c
# Compilation rules for *.c files.
$(CC) $(CFLAGS) $(INTERNALCFLAGS) -c $< -o $@
obj/%.c.o: src/%.c GNUmakefile
mkdir -p "$$(dirname $@)"
$(KCC) $(KCFLAGS) $(KCPPFLAGS) -c $< -o $@
 
# Compilation rules for *.S files.
obj/%.S.o: src/%.S GNUmakefile
mkdir -p "$$(dirname $@)"
$(KCC) $(KCFLAGS) $(KCPPFLAGS) -c $< -o $@
 
# Compilation rules for *.asm (nasm) files.
obj/%.asm.o: src/%.asm GNUmakefile
mkdir -p "$$(dirname $@)"
nasm $(KNASMFLAGS) $< -o $@
 
# Remove object files and the final executable.
.PHONY: clean
clean:
rm -rf $(KERNEL)bin $(OBJ) $(HEADER_DEPS)obj
</syntaxhighlight>
</source>
 
===limine.cfg===
Line 211 ⟶ 379:
This file is parsed by Limine and it describes boot entries and other bootloader configuration variables. Further information [https://github.com/limine-bootloader/limine/blob/trunk/CONFIG.md here].
 
<sourcesyntaxhighlight lang="ini">
# Timeout in seconds that Limine will use before automatically booting.
TIMEOUT=5
 
# The entry name that will be displayed in the boot menu.
:myOS
# We use the Limine boot protocol.
PROTOCOL=limine
 
# Disable KASLR (it is enabled by default for relocatable kernels)
# Change the protocol line depending on the used protocol.
KASLR=no
PROTOCOL=limine
 
# Path to the kernel to boot. boot:/// represents the partition on which limine.cfg is located.
KERNEL_PATH=boot:///boot/myos.elf
 
</source>
# Same thing, but with KASLR.
:myOS (with KASLR)
PROTOCOL=limine
 
KERNEL_PATH=boot:///boot/myos
</syntaxhighlight>
 
===Compiling the kernel===
 
We can now build our example kernel by running '''make'''. This command, if successful, should generate, inside the '''bin''' directory, a file called '''myos.elf''' (or the chosen kernel name). This is our Limine protocol-compliant kernel executable.
 
===Compiling the kernel on macOS===
 
''If you are not using macOS, you can skip this section.''
 
The macOS Xcode toolchain uses Mach-O binaries, and not the ELF binaries required for this Limine-compliant kernel. A solution is to build a [[GCC Cross-Compiler]], or to obtain one from [https://brew.sh homebrew] by installing the '''x86_64-elf-gcc''' package. After one of these is done, build using '''make KCC=x86_64-elf-gcc KLD=x86_64-elf-ld'''.
 
===Creating the image===
Line 241 ⟶ 423:
These are shell commands. They can also be compiled into a script or Makefile.
 
<sourcesyntaxhighlight lang="bash">
# Download the latest Limine binary release for the 7.x branch.
git clone https://github.com/limine-bootloader/limine.git --branch=v3v7.0-branchx-binary --depth=1
 
# Build "limine-deploy" utility.
make -C limine
 
Line 252 ⟶ 434:
 
# Copy the relevant files over.
mkdir -p iso_root/boot
cp -v myos.elf limine.cfg limine/limine.sys \
cp -v limine/limine-cd.bin limine/limine-cd-efi.binmyos iso_root/boot/
mkdir -p iso_root/boot/limine
cp -v limine.cfg limine/limine-bios.sys limine/limine-bios-cd.bin \
limine/limine-uefi-cd.bin iso_root/boot/limine/
 
# Create the EFI boot tree and copy Limine's EFI executables over.
mkdir -p iso_root/EFI/BOOT
cp -v limine/BOOTX64.EFI iso_root/EFI/BOOT/
cp -v limine/BOOTIA32.EFI iso_root/EFI/BOOT/
 
# Create the bootable ISO.
xorriso -as mkisofs -b boot/limine/limine-bios-cd.bin \
-no-emul-boot -boot-load-size 4 -boot-info-table \
--efi-boot boot/limine/limine-cduefi-eficd.bin \
-efi-boot-part --efi-boot-image --protective-msdos-label \
iso_root -o image.iso
 
# Install Limine stage 1 and 2 for legacy BIOS boot.
./limine/limine bios-deployinstall image.iso
</syntaxhighlight>
</source>
 
====Creating a hard disk/USB drive image====
 
In this example, we'll create a [[GPT]] partition table using '''partedsgdisk''', containing a single FAT partition, also known as the ESP in EFI terminology, which will store our kernel, configs, and bootloader.
 
This example is more involved and is made up of more steps than creating an ISO image.
Line 274 ⟶ 464:
These are shell commands. They can also be compiled into a script or Makefile.
 
<sourcesyntaxhighlight lang="bash">
# Create an empty zeroed -out 64MiB image file.
dd if=/dev/zero bs=1M count=0 seek=64 of=image.hdd
 
# Create a GPT partition table.
parted -ssgdisk image.hdd mklabel-n 1:2048 -t gpt1:ef00
 
# Download the latest Limine binary release for the 7.x branch.
# Create an ESP partition that spans the whole disk.
git clone https://github.com/limine-bootloader/limine.git --branch=v7.x-binary --depth=1
parted -s image.hdd mkpart ESP fat32 2048s 100%
parted -s image.hdd set 1 esp on
 
# Build "limine" utility.
# Download the latest Limine binary release.
git clone https://github.com/limine-bootloader/limine.git --branch=v3.0-branch-binary --depth=1
 
# Build limine-deploy.
make -C limine
 
# Install the Limine BIOS stages onto the image.
./limine/limine bios-deployinstall image.hdd
 
# MountFormat the loopbackimage deviceas fat32.
USED_LOOPBACK=$(sudomformat losetup -Pf --showi image.hdd)@@1M
 
# Make relevant subdirectories.
# Format the ESP partition as FAT32.
mmd -i image.hdd@@1M ::/EFI ::/EFI/BOOT ::/boot ::/boot/limine
sudo mkfs.fat -F 32 ${USED_LOOPBACK}p1
 
# Mount the partition itself.
mkdir -p img_mount
sudo mount ${USED_LOOPBACK}p1 img_mount
 
# Copy the relevant files over.
sudo mkdir -p img_mount/EFI/BOOT
sudo cp -v myos.elf limine.cfg limine/limine.sys img_mount/
sudo cp -v limine/BOOTX64.EFI img_mount/EFI/BOOT/
 
# Copy over the relevant files.
# Sync system cache and unmount partition and loopback device.
mcopy -i image.hdd@@1M bin/myos ::/boot
sync
mcopy -i image.hdd@@1M limine.cfg limine/limine-bios.sys ::/boot/limine
sudo umount img_mount
mcopy -i image.hdd@@1M limine/BOOTX64.EFI ::/EFI/BOOT
sudo losetup -d ${USED_LOOPBACK}
mcopy -i image.hdd@@1M limine/BOOTIA32.EFI ::/EFI/BOOT
</source>
</syntaxhighlight>
 
==Conclusions==
 
If everything above has been completed successfully, you should now have a bootable ISO or hard drive/USB image containing your 64-bit higher half Limine protocol-compliant kernel and Limine to boot it. Once the kernel is successfully booted, you should see "Helloa World"line printed on screen from the top left corner.
 
== See Also ==
Line 324 ⟶ 502:
 
* [[Limine]]
* [[stivale]]
* [[Multiboot]]
 
Line 330 ⟶ 507:
 
* [https://github.com/limine-bootloader/limine/blob/trunk/PROTOCOL.md Limine protocol specification]
* [https://github.com/limine-bootloader/limine-c-template Buildable Limine protocol based kernel project template in C]
 
[[Category:Bare bones tutorials]]
[[Category:Bootloaders]]
[[Category:C]]
Qookie
1

edit

Retrieved from "https://osdev.wiki/wiki/Special:MobileDiff/6139...28134"