Better docs and structure

2026-02-26 21:33:16 +00:00
parent d449150169
commit 13a281fa4f
18 changed files with 892 additions and 387 deletions
--- a/191
+++ b/191
@@ -1,45 +1,56 @@
-# Makefile for UEFI Operating System
+# ==============================================================================
+# Makefile for Simple UEFI Operating System
+# ==============================================================================

-# Architecture
+# ---- Architecture -----------------------------------------------------------
 ARCH = x86_64

-# Compiler and tools
-CC = gcc
-LD = ld
+# ---- Tools ------------------------------------------------------------------
+CC      = gcc
+LD      = ld
 OBJCOPY = objcopy

-# Directories
-SRC_DIR = .
+# ---- Directories ------------------------------------------------------------
+SRC_DIR   = .
 BUILD_DIR = build
-EFI_DIR = $(BUILD_DIR)/EFI/BOOT
+EFI_DIR   = $(BUILD_DIR)/EFI/BOOT
 IMAGE_DIR = $(BUILD_DIR)/image

-# GNU-EFI paths (common locations)
-EFI_INC = /usr/include/efi
-EFI_INCLUDES = -I$(EFI_INC) -I$(EFI_INC)/$(ARCH) -I$(EFI_INC)/protocol
-EFI_LDS = /usr/lib/elf_$(ARCH)_efi.lds
-EFI_CRT_OBJS = /usr/lib/crt0-efi-$(ARCH).o
+# ---- GNU-EFI paths ---------------------------------------------------------
+EFI_INC       = /usr/include/efi
+EFI_INCLUDES  = -I$(EFI_INC) -I$(EFI_INC)/$(ARCH) -I$(EFI_INC)/protocol
+EFI_LDS       = /usr/lib/elf_$(ARCH)_efi.lds
+EFI_CRT_OBJS  = /usr/lib/crt0-efi-$(ARCH).o
 EFI_LIB_PATHS = -L/usr/lib

-# Compiler flags
-CFLAGS = -ffreestanding -fno-stack-protector -fpic \
-         -fshort-wchar -mno-red-zone -Wall -Wextra \
-         $(EFI_INCLUDES) -DEFI_FUNCTION_WRAPPER
+# ---- Compiler / linker flags ------------------------------------------------
+
+# Flags shared by both the UEFI loader and the kernel
+COMMON_CFLAGS = -ffreestanding -fno-stack-protector -fshort-wchar \
+                -mno-red-zone -Wall -Wextra $(EFI_INCLUDES)
+
+# UEFI loader: position-independent (shared object → PE32+ conversion)
+LOADER_CFLAGS = $(COMMON_CFLAGS) -fpic -DEFI_FUNCTION_WRAPPER
+
+# Kernel: position-dependent static ELF
+KERNEL_CFLAGS = $(COMMON_CFLAGS) -fno-pic

-# Linker flags
 LDFLAGS = -nostdlib -znocombreloc -T $(EFI_LDS) -shared \
          -Bsymbolic $(EFI_LIB_PATHS) $(EFI_CRT_OBJS)

-# Libraries
 LIBS = -lefi -lgnuefi

-# Target
-TARGET = BOOTX64.EFI
-TARGET_SO = bootx64.so
-OBJ = $(BUILD_DIR)/main.o
+# ---- Targets / objects ------------------------------------------------------
+TARGET        = BOOTX64.EFI
+TARGET_SO     = bootx64.so
+LOADER_OBJ    = $(BUILD_DIR)/main.o
+
 KERNEL_TARGET = kernel.elf
-KERNEL_OBJS = $(BUILD_DIR)/kernel.o $(BUILD_DIR)/string_utils.o $(BUILD_DIR)/commands.o $(BUILD_DIR)/idt.o $(BUILD_DIR)/isr.o $(BUILD_DIR)/memory.o $(BUILD_DIR)/task.o $(BUILD_DIR)/context_switch.o
-KERNEL_LD = kernel.ld
+KERNEL_LD     = kernel.ld
+KERNEL_C_SRCS = kernel.c string_utils.c commands.c idt.c memory.c task.c
+KERNEL_S_SRCS = isr.S context_switch.S
+KERNEL_OBJS   = $(patsubst %.c,$(BUILD_DIR)/%.o,$(KERNEL_C_SRCS)) \
+                $(patsubst %.S,$(BUILD_DIR)/%.o,$(KERNEL_S_SRCS))

 # QEMU settings
 QEMU = qemu-system-x86_64
@@ -76,17 +87,23 @@ QEMU_FLAGS = -machine q35 \
             -drive if=pflash,format=raw,file=$(BUILD_DIR)/OVMF_VARS.fd \
             -drive format=raw,file=fat:rw:$(BUILD_DIR) \
             -net none \
-			 -no-reboot
+             -no-reboot

- # Phony targets
-.PHONY: all clean run setup install-deps iso runiso
+# ==============================================================================
+#  Phony targets
+# ==============================================================================
+
+.PHONY: all clean run setup install-deps iso runiso help
+
+# ---- Default ----------------------------------------------------------------

- # Default target
 all: setup $(EFI_DIR)/$(TARGET) $(BUILD_DIR)/$(KERNEL_TARGET)
-# ISO target
-ISO_FILE = $(IMAGE_DIR)/os.iso
+# ==============================================================================
+#  ISO image
+# ==============================================================================

-ESP_IMG = $(IMAGE_DIR)/staging/esp.img
+ISO_FILE = $(IMAGE_DIR)/os.iso
+ESP_IMG  = $(IMAGE_DIR)/staging/esp.img

 iso: all
 	@echo "Creating FAT ESP image for UEFI boot..."
@@ -107,6 +124,10 @@ iso: all
 		$(IMAGE_DIR)/staging
 	@echo "ISO image created: $(ISO_FILE)"

+# ==============================================================================
+#  Run targets
+# ==============================================================================
+
 # Run from ISO with QEMU
 runiso: iso
 	@echo "Starting QEMU from ISO..."
@@ -124,77 +145,62 @@ runiso: iso
 		-nographic \
 		-no-reboot

-# Create necessary directories
+# ==============================================================================
+#  Directory setup
+# ==============================================================================
+
 setup:
 	@mkdir -p $(BUILD_DIR)
 	@mkdir -p $(EFI_DIR)
 	@mkdir -p $(IMAGE_DIR)

-# Compile source files
+# ==============================================================================
+#  Compilation rules
+# ==============================================================================
+
+# ---- UEFI loader object (PIC, linked as shared object → PE32+) ----
+
+$(BUILD_DIR)/main.o: $(SRC_DIR)/main.c
+	@echo "  CC    $<"
+	@$(CC) $(LOADER_CFLAGS) -c $< -o $@
+
+# ---- Kernel objects (position-dependent, linked into static ELF) ----
+# Pattern rules replace the per-file rules for every kernel source.
+
 $(BUILD_DIR)/%.o: $(SRC_DIR)/%.c
-	@echo "Compiling $<..."
-	$(CC) $(CFLAGS) -c $< -o $@
+	@echo "  CC    $<"
+	@$(CC) $(KERNEL_CFLAGS) -c $< -o $@

-# Compile kernel source
-$(BUILD_DIR)/kernel.o: $(SRC_DIR)/kernel.c
-	@echo "Compiling kernel.c..."
-	$(CC) -ffreestanding -fno-stack-protector -fno-pic -fshort-wchar \
-		-mno-red-zone -Wall -Wextra $(EFI_INCLUDES) -c $< -o $@
+$(BUILD_DIR)/%.o: $(SRC_DIR)/%.S
+	@echo "  AS    $<"
+	@$(CC) $(KERNEL_CFLAGS) -c $< -o $@

-$(BUILD_DIR)/string_utils.o: $(SRC_DIR)/string_utils.c
-	@echo "Compiling string_utils.c..."
-	$(CC) -ffreestanding -fno-stack-protector -fno-pic -fshort-wchar \
-		-mno-red-zone -Wall -Wextra $(EFI_INCLUDES) -c $< -o $@
+# ==============================================================================
+#  Linking
+# ==============================================================================

-$(BUILD_DIR)/commands.o: $(SRC_DIR)/commands.c
-	@echo "Compiling commands.c..."
-	$(CC) -ffreestanding -fno-stack-protector -fno-pic -fshort-wchar \
-		-mno-red-zone -Wall -Wextra $(EFI_INCLUDES) -c $< -o $@
+# ---- Kernel ELF ----

-$(BUILD_DIR)/idt.o: $(SRC_DIR)/idt.c
-	@echo "Compiling idt.c..."
-	$(CC) -ffreestanding -fno-stack-protector -fno-pic -fshort-wchar \
-		-mno-red-zone -Wall -Wextra $(EFI_INCLUDES) -c $< -o $@
-
-$(BUILD_DIR)/isr.o: $(SRC_DIR)/isr.S
-	@echo "Compiling isr.S..."
-	$(CC) -ffreestanding -fno-stack-protector -fno-pic -fshort-wchar \
-		-mno-red-zone -Wall -Wextra $(EFI_INCLUDES) -c $< -o $@
-
-$(BUILD_DIR)/memory.o: $(SRC_DIR)/memory.c
-	@echo "Compiling memory.c..."
-	$(CC) -ffreestanding -fno-stack-protector -fno-pic -fshort-wchar \
-		-mno-red-zone -Wall -Wextra $(EFI_INCLUDES) -c $< -o $@
-
-$(BUILD_DIR)/task.o: $(SRC_DIR)/task.c
-	@echo "Compiling task.c..."
-	$(CC) -ffreestanding -fno-stack-protector -fno-pic -fshort-wchar \
-		-mno-red-zone -Wall -Wextra $(EFI_INCLUDES) -c $< -o $@
-
-$(BUILD_DIR)/context_switch.o: $(SRC_DIR)/context_switch.S
-	@echo "Assembling context_switch.S..."
-	$(CC) -ffreestanding -fno-stack-protector -fno-pic -fshort-wchar \
-		-mno-red-zone -Wall -Wextra -c $< -o $@
-
-# Link kernel ELF
 $(BUILD_DIR)/$(KERNEL_TARGET): $(KERNEL_OBJS) $(KERNEL_LD)
-	@echo "Linking kernel ELF..."
-	$(LD) -nostdlib -T $(KERNEL_LD) $(KERNEL_OBJS) -o $@
+	@echo "  LD    $@"
+	@$(LD) -nostdlib -T $(KERNEL_LD) $(KERNEL_OBJS) -o $@

-# Link to create shared object
-$(BUILD_DIR)/$(TARGET_SO): $(OBJ)
-	@echo "Linking $@..."
-	$(LD) $(LDFLAGS) $(OBJ) -o $@ $(LIBS)
+# ---- UEFI loader shared object ----
+
+$(BUILD_DIR)/$(TARGET_SO): $(LOADER_OBJ)
+	@echo "  LD    $@"
+	@$(LD) $(LDFLAGS) $(LOADER_OBJ) -o $@ $(LIBS)
+
+# ---- Convert to PE32+ EFI application ----

-# Convert to EFI application
 $(EFI_DIR)/$(TARGET): $(BUILD_DIR)/$(TARGET_SO)
-	@echo "Creating EFI application..."
-	$(OBJCOPY) -j .text -j .sdata -j .data -j .dynamic \
-	           -j .dynsym -j .rel -j .rela -j .reloc \
-	           --target=efi-app-$(ARCH) $< $@
+	@echo "  OBJCOPY $@"
+	@$(OBJCOPY) -j .text -j .sdata -j .data -j .dynamic \
+	            -j .dynsym -j .rel -j .rela -j .reloc \
+	            --target=efi-app-$(ARCH) $< $@
 	@echo "Build complete: $@"

-# Run with QEMU
+# Run with QEMU (FAT directory)
 run: all
 	@echo "Starting QEMU..."
 	@echo "Using OVMF firmware: $(OVMF_CODE)"
@@ -210,20 +216,27 @@ run: all
 	@echo "================================================"
 	$(QEMU) $(QEMU_FLAGS)

+# ==============================================================================
+#  Maintenance
+# ==============================================================================
+
 # Clean build artifacts
 clean:
 	@echo "Cleaning build directory..."
 	rm -rf $(BUILD_DIR)
 	@echo "Clean complete."

-# Install dependencies (for Debian/Ubuntu)
+# Install dependencies (Debian/Ubuntu)
 install-deps:
 	@echo "Installing dependencies..."
 	sudo apt-get update
 	sudo apt-get install -y gnu-efi qemu-system-x86 ovmf gcc binutils make xorriso mtools
 	@echo "Dependencies installed."

- # Help target
+# ==============================================================================
+#  Help
+# ==============================================================================
+
 help:
 	@echo "UEFI Operating System Makefile"
 	@echo ""