The UEFI bootloader of PatchworkOS. More...

Collaboration diagram for Bootloader:

Detailed Description

The UEFI bootloader of PatchworkOS.

PatchworkOS UEFI Bootloader.

Warning: UEFI is exceptionally finicky as such to simpify the linking process which can have machine specific issues, the bootloader should be compiled into a single object file.

Modules
	Boot Information
	Boot information.

Macros
#define	GOP_WIDTH 1920
	Ignored if `GOP_USE_DEFAULT_RES` is set to 1.

#define	GOP_HEIGHT 1080
	Ignored if `GOP_USE_DEFAULT_RES` is set to 1.

#define	GOP_USE_DEFAULT_RES 1

#define	MEM_BASIC_ALLOCATOR_RESERVE_PERCENTAGE 10

#define	MEM_BASIC_ALLOCATOR_MIN_PAGES 8192

#define	EXIT_BOOT_SERVICES_MAX_RETRIES 5

Enumerations
enum	panic_code_t { PANIC_ALLOCATOR_EXHAUSTED = 0 , PANIC_PAGE_TABLE_INIT = 1 , PANIC_IDENTITY_MAP = 2 , PANIC_HIGHER_HALF_INVALID = 3 , PANIC_HIGHER_HALF_MAP = 4 , PANIC_KERNEL_MAP = 5 , PANIC_GOP_MAP = 6 }
	Panic error codes for debugging when boot services are unavailable. More...

Functions
static void *	rsdp_locate (EFI_SYSTEM_TABLE *systemTable)
	Locates the ACPI RSDP from the EFI configuration table.

static UINT32	gop_find_best_mode (EFI_GRAPHICS_OUTPUT_PROTOCOL *gop, int64_t requestedWidth, int64_t requestedHeight)
	Finds the best matching graphics mode for the requested resolution.

static EFI_STATUS	gop_set_mode (EFI_GRAPHICS_OUTPUT_PROTOCOL *gop, int64_t requestedWidth, int64_t requestedHeight)
	Sets the graphics mode to best match the requested resolution.

static EFI_STATUS	gop_init (boot_gop_t *buffer)
	Initializes the GOP buffer structure with framebuffer information.

static _NORETURN void	panic_halt (panic_code_t code)
	Halts the system with a colored screen indicating the error.

static EFI_STATUS	mem_map_init (boot_memory_map_t *map)
	Initializes the EFI memory map structure.

static void	mem_map_cleanup (boot_memory_map_t *map)
	Free the memory map structure.

static size_t	mem_count_available_pages (boot_memory_map_t *map)
	Calculates the total available conventional memory.

static EFI_STATUS	mem_allocator_init (void)
	Initializes the basic page allocator.

static uint64_t	basic_allocator_alloc_pages (pfn_t *pfns, size_t amount)
	Allocate pages from the basic allocator.

static void	mem_page_table_init (page_table_t table, boot_memory_map_t map, boot_gop_t gop, boot_kernel_t kernel)
	Initializes the kernel page table with all required mappings.

static bool	wstr_to_str (char dest, size_t destSize, const CHAR16 src)
	Copies a wide character string to a narrow character buffer.

static void	boot_file_free (boot_file_t *file)
	Frees a boot file structure and its data.

static void	boot_dir_free (boot_dir_t *dir)
	Recursively frees a directory tree.

static boot_file_t *	disk_load_file (EFI_FILE parentDir, const CHAR16 fileName)
	Loads a single file from an EFI file handle.

static boot_dir_t *	disk_load_dir (EFI_FILE dirHandle, const CHAR16 dirName)
	Recursively loads a directory and its contents.

static EFI_STATUS	disk_init (boot_disk_t disk, EFI_FILE rootHandle)
	Loads the initial RAM disk from the boot volume.

static EFI_STATUS	kernel_load (boot_kernel_t kernel, EFI_FILE rootHandle)
	Loads and validates the kernel ELF file.

static void	splash_screen_display (void)
	Displays the bootloader splash screen.

static EFI_STATUS	volume_open_root (EFI_FILE **rootFile, EFI_HANDLE imageHandle)
	Opens the root volume of the boot device.

static EFI_STATUS	boot_info_populate (EFI_HANDLE imageHandle, EFI_SYSTEM_TABLE systemTable, boot_info_t bootInfo)
	Populates the boot information structure.

static EFI_STATUS	boot_services_exit (EFI_HANDLE imageHandle, boot_info_t *bootInfo)
	Exits UEFI boot services and prepares for kernel handoff.

EFI_STATUS	efi_main (EFI_HANDLE imageHandle, EFI_SYSTEM_TABLE *systemTable)
	UEFI entry point.

Variables
struct {

EFI_PHYSICAL_ADDRESS buffer

size_t maxPages

size_t pagesAllocated

boot_gop_t * gop

boot_memory_map_t * map

}	basicAllocator
	Basic page allocator state.

static const uint32_t	PANIC_COLORS []
	Color values for panic display.

Macro Definition Documentation

◆ GOP_WIDTH

#define GOP_WIDTH 1920

Ignored if GOP_USE_DEFAULT_RES is set to 1.

Definition at line 30 of file main.c.

◆ GOP_HEIGHT

#define GOP_HEIGHT 1080

Ignored if GOP_USE_DEFAULT_RES is set to 1.

Definition at line 31 of file main.c.

◆ GOP_USE_DEFAULT_RES

#define GOP_USE_DEFAULT_RES 1

Definition at line 32 of file main.c.

◆ MEM_BASIC_ALLOCATOR_RESERVE_PERCENTAGE

#define MEM_BASIC_ALLOCATOR_RESERVE_PERCENTAGE 10

Definition at line 34 of file main.c.

◆ MEM_BASIC_ALLOCATOR_MIN_PAGES

#define MEM_BASIC_ALLOCATOR_MIN_PAGES 8192

Definition at line 35 of file main.c.

◆ EXIT_BOOT_SERVICES_MAX_RETRIES

#define EXIT_BOOT_SERVICES_MAX_RETRIES 5

Definition at line 37 of file main.c.

Enumeration Type Documentation

◆ panic_code_t

enum panic_code_t

Panic error codes for debugging when boot services are unavailable.

Enumerator
PANIC_ALLOCATOR_EXHAUSTED
PANIC_PAGE_TABLE_INIT
PANIC_IDENTITY_MAP
PANIC_HIGHER_HALF_INVALID
PANIC_HIGHER_HALF_MAP
PANIC_KERNEL_MAP
PANIC_GOP_MAP

Definition at line 247 of file main.c.

Function Documentation

◆ rsdp_locate()

static void * rsdp_locate ( EFI_SYSTEM_TABLE * systemTable )

static

Locates the ACPI RSDP from the EFI configuration table.

Parameters

systemTable Pointer to the EFI system table.

Returns: Pointer to the RSDP if found, NULL otherwise.

Definition at line 45 of file main.c.

Here is the caller graph for this function:

◆ gop_find_best_mode()

static UINT32 gop_find_best_mode	(	EFI_GRAPHICS_OUTPUT_PROTOCOL *	gop,
		int64_t	requestedWidth,
		int64_t	requestedHeight
	)

static

Finds the best matching graphics mode for the requested resolution.

Parameters

gop	Pointer to the GOP protocol.
requestedWidth	Desired horizontal resolution.
requestedHeight	Desired vertical resolution.

Returns: The index of the best matching mode.

Definition at line 111 of file main.c.

Here is the caller graph for this function:

◆ gop_set_mode()

static EFI_STATUS gop_set_mode	(	EFI_GRAPHICS_OUTPUT_PROTOCOL *	gop,
		int64_t	requestedWidth,
		int64_t	requestedHeight
	)

static

Sets the graphics mode to best match the requested resolution.

Parameters

gop	Pointer to the GOP protocol.
requestedWidth	Desired horizontal resolution.
requestedHeight	Desired vertical resolution.

Returns: On success, EFI_SUCCESS. On failure, an EFI error code.

Definition at line 154 of file main.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ gop_init()

static EFI_STATUS gop_init ( boot_gop_t * buffer )

static

Initializes the GOP buffer structure with framebuffer information.

Locates the Graphics Output Protocol, optionally sets the desired resolution, and populates the boot_gop_t structure with framebuffer details.

Parameters

buffer Pointer to the boot_gop_t structure to populate.

Returns: On success, EFI_SUCCESS. On failure, an EFI error code.

Definition at line 171 of file main.c.

Here is the call graph for this function:

◆ panic_halt()

static _NORETURN void panic_halt ( panic_code_t code )

static

Halts the system with a colored screen indicating the error.

Parameters

code	The panic code indicating the type of error.

Definition at line 276 of file main.c.

Here is the caller graph for this function:

◆ mem_map_init()

static EFI_STATUS mem_map_init ( boot_memory_map_t * map )

static

Initializes the EFI memory map structure.

Parameters

map	Pointer to the memory map structure to initialize.

Returns: On success, EFI_SUCCESS. On failure, an EFI error code.

Definition at line 304 of file main.c.

Here is the caller graph for this function:

◆ mem_map_cleanup()

static void mem_map_cleanup ( boot_memory_map_t * map )

static

Free the memory map structure.

Parameters

map	Pointer to the memory map structure to free.

Definition at line 331 of file main.c.

Here is the caller graph for this function:

◆ mem_count_available_pages()

static size_t mem_count_available_pages ( boot_memory_map_t * map )

static

Calculates the total available conventional memory.

Parameters

map	Pointer to the memory map.

Returns: Total number of available pages.

Definition at line 347 of file main.c.

Here is the caller graph for this function:

◆ mem_allocator_init()

static EFI_STATUS mem_allocator_init ( void )

static

Initializes the basic page allocator.

Returns: On success, EFI_SUCCESS. On failure, an EFI error code.

Definition at line 368 of file main.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ basic_allocator_alloc_pages()

static uint64_t basic_allocator_alloc_pages	(	pfn_t *	pfns,
		size_t	amount
	)

static

Allocate pages from the basic allocator.

Parameters

pfns	Pointer to store allocated page PFNs.
amount	Number of pages to allocate.

Returns: Always returns 0.

Definition at line 411 of file main.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mem_page_table_init()

static void mem_page_table_init	(	page_table_t *	table,
		boot_memory_map_t *	map,
		boot_gop_t *	gop,
		boot_kernel_t *	kernel
	)

static

Initializes the kernel page table with all required mappings.

Parameters

table	Pointer to the page table structure.
map	Pointer to the memory map.
gop	Pointer to the GOP information.
kernel	Pointer to the kernel information.

Definition at line 435 of file main.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ wstr_to_str()

static bool wstr_to_str	(	char *	dest,
		size_t	destSize,
		const CHAR16 *	src
	)

static

Copies a wide character string to a narrow character buffer.

Parameters

dest	Destination buffer.
destSize	Size of the destination buffer.
src	Source wide string.

Returns: true if the string was fully copied, false if truncated.

Definition at line 504 of file main.c.

Here is the caller graph for this function:

◆ boot_file_free()

static void boot_file_free ( boot_file_t * file )

static

Frees a boot file structure and its data.

Parameters

file	Pointer to the file structure to free.

Definition at line 526 of file main.c.

Here is the caller graph for this function:

◆ boot_dir_free()

static void boot_dir_free ( boot_dir_t * dir )

static

Recursively frees a directory tree.

Parameters

dir	Pointer to the directory structure to free.

Definition at line 543 of file main.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ disk_load_file()

static boot_file_t * disk_load_file	(	EFI_FILE *	parentDir,
		const CHAR16 *	fileName
	)

static

Loads a single file from an EFI file handle.

Parameters

parentDir	The parent directory handle.
fileName	The name of the file to load.

Returns: On success, pointer to the loaded file structure. On failure, NULL.

Definition at line 574 of file main.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ disk_load_dir()

static boot_dir_t * disk_load_dir	(	EFI_FILE *	dirHandle,
		const CHAR16 *	dirName
	)

static

Recursively loads a directory and its contents.

Parameters

dirHandle	The directory handle to read from.
dirName	The name of the directory.

Returns: On success, pointer to the loaded directory structure. On failure, NULL.

Definition at line 645 of file main.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ disk_init()

static EFI_STATUS disk_init	(	boot_disk_t *	disk,
		EFI_FILE *	rootHandle
	)

static

Loads the initial RAM disk from the boot volume.

Parameters

disk	Pointer to the disk structure to populate.
rootHandle	Handle to the root of the boot volume.

Returns: EFI_SUCCESS on success, error code otherwise.

Definition at line 748 of file main.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ kernel_load()

static EFI_STATUS kernel_load	(	boot_kernel_t *	kernel,
		EFI_FILE *	rootHandle
	)

static

Loads and validates the kernel ELF file.

Parameters

kernel	Pointer to the kernel structure to populate.
rootHandle	Handle to the root of the boot volume.

Returns: On success, EFI_SUCCESS. On failure, an EFI error code.

Definition at line 786 of file main.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ splash_screen_display()

static void splash_screen_display ( void )

static

Displays the bootloader splash screen.

Definition at line 919 of file main.c.

Here is the caller graph for this function:

◆ volume_open_root()

static EFI_STATUS volume_open_root	(	EFI_FILE **	rootFile,
		EFI_HANDLE	imageHandle
	)

static

Opens the root volume of the boot device.

Parameters

rootFile	Output pointer to receive the root file handle.
imageHandle	The loaded image handle.

Returns: On success, EFI_SUCCESS. On failure, an EFI error code.

Definition at line 936 of file main.c.

Here is the caller graph for this function:

◆ boot_info_populate()

static EFI_STATUS boot_info_populate	(	EFI_HANDLE	imageHandle,
		EFI_SYSTEM_TABLE *	systemTable,
		boot_info_t *	bootInfo
	)

static

Populates the boot information structure.

Initializes all boot data including GOP, RSDP, disk, and kernel.

Parameters

imageHandle	The loaded image handle.
systemTable	Pointer to the EFI system table.
bootInfo	Pointer to the boot info structure to populate.

Returns: EFI_SUCCESS on success, error code otherwise.

Definition at line 982 of file main.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ boot_services_exit()

static EFI_STATUS boot_services_exit	(	EFI_HANDLE	imageHandle,
		boot_info_t *	bootInfo
	)

static

Exits UEFI boot services and prepares for kernel handoff.

Parameters

imageHandle	The loaded image handle.
bootInfo	Pointer to the boot info structure.

Returns: On success, EFI_SUCCESS. On failure, an EFI error code.

Definition at line 1047 of file main.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ efi_main()

EFI_STATUS efi_main	(	EFI_HANDLE	imageHandle,
		EFI_SYSTEM_TABLE *	systemTable
	)

UEFI entry point.

Parameters

imageHandle	Handle to the loaded image.
systemTable	Pointer to the EFI system table.

Returns: Will not return if successful. On failure, an EFI error code.

Definition at line 1115 of file main.c.

Here is the call graph for this function:

Variable Documentation

◆ [struct]

struct { ... } basicAllocator

Basic page allocator state.

This allocator is used after exiting boot services when UEFI memory allocation is no longer available.

◆ []

EFI_PHYSICAL_ADDRESS { ... } ::buffer

Definition at line 237 of file main.c.

◆ []

size_t { ... } ::maxPages

Definition at line 238 of file main.c.

◆ []

size_t { ... } ::pagesAllocated

Definition at line 239 of file main.c.

◆ []

boot_gop_t* { ... } ::gop

Definition at line 240 of file main.c.

◆ []

boot_memory_map_t* { ... } ::map

Definition at line 241 of file main.c.

◆ PANIC_COLORS

const uint32_t PANIC_COLORS[]

static

Initial value:

= {
    0xFFFF0000, 
    0xFF00FF00, 
    0xFFFFFF00, 
    0xFF0000FF, 
    0xFFFF00FF, 
    0xFF00FFFF, 
    0xFFFFFFFF, 
}

Color values for panic display.

Definition at line 261 of file main.c.

Detailed Description

Modules

Macros

Enumerations

Functions

Variables

Macro Definition Documentation

◆ GOP_WIDTH

◆ GOP_HEIGHT

◆ GOP_USE_DEFAULT_RES

◆ MEM_BASIC_ALLOCATOR_RESERVE_PERCENTAGE

◆ MEM_BASIC_ALLOCATOR_MIN_PAGES

◆ EXIT_BOOT_SERVICES_MAX_RETRIES

Enumeration Type Documentation

◆ panic_code_t

Function Documentation

◆ rsdp_locate()

◆ gop_find_best_mode()

◆ gop_set_mode()

◆ gop_init()

◆ panic_halt()

◆ mem_map_init()

◆ mem_map_cleanup()

◆ mem_count_available_pages()

◆ mem_allocator_init()

◆ basic_allocator_alloc_pages()

◆ mem_page_table_init()

◆ wstr_to_str()

◆ boot_file_free()

◆ boot_dir_free()

◆ disk_load_file()

◆ disk_load_dir()

◆ disk_init()

◆ kernel_load()

◆ splash_screen_display()

◆ volume_open_root()

◆ boot_info_populate()

◆ boot_services_exit()

◆ efi_main()

Variable Documentation

◆ [struct]

◆ []

◆ []

◆ []

◆ []

◆ []

◆ PANIC_COLORS