Release v0.9.5

.github/workflows/macos.yml

@@ -0,0 +1,93 @@
+name: macOS
+
+# Trigger the workflow on push or pull requests for main and develop branches
+on:
+  push:
+    branches:
+    - main
+    - develop
+    paths:
+    - '**/*.c'
+    - '**/*.cpp'
+    - '**/*.h'
+    - '**/*.hpp'
+    - '**/*.S'
+    - '**/*.asm'
+    - '**/CMakeLists.txt'
+    - '**/Makefile'
+    - '**/cmake/**'
+    - '**/tools/toolchain-i686-elf.cmake'
+    - '.github/workflows/macos.yml'
+  pull_request:
+    branches:
+    - main
+    - develop
+    paths:
+    - '**/*.c'
+    - '**/*.cpp'
+    - '**/*.h'
+    - '**/*.hpp'
+    - '**/*.S'
+    - '**/*.asm'
+    - '**/CMakeLists.txt'
+    - '**/Makefile'
+    - '**/cmake/**'
+    - '**/tools/toolchain-i686-elf.cmake'
+    - '.github/workflows/macos.yml'
+
+jobs:
+  build:
+    name: Build and Compile (macOS)
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # macOS runners come with clang, we test with the system clang
+          # i686-elf-gcc is installed via Homebrew for cross-compilation
+          - { os: macos-14, arch: "Intel" }
+          - { os: macos-14-large, arch: "Apple Silicon" }
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    steps:
+    - name: Clone repository
+      uses: actions/checkout@v4
+
+    - name: Install dependencies via Homebrew
+      run: |
+        # Update Homebrew
+        brew update || true
+
+        # Install required tools
+        brew install nasm cmake
+
+        # Install cross-compiler for i386 (bare-metal)
+        # This is critical - we need i686-elf-gcc, not i686-linux-gnu
+        brew install i686-elf-gcc
+
+        # Verify installation
+        echo "=== Checking installed tools ==="
+        nasm --version
+        cmake --version
+        i686-elf-gcc --version
+
+    - name: Build with cross-compilation toolchain
+      run: |
+        # Create build directory
+        mkdir -p build
+        cd build
+
+        # Configure with the i686-elf toolchain file
+        # This is essential for macOS (which is ARM-based)
+        cmake .. -DCMAKE_TOOLCHAIN_FILE=../tools/toolchain-i686-elf.cmake \
+                 -DCMAKE_BUILD_TYPE=Release
+
+        # Build all targets
+        cmake --build . --parallel $(sysctl -n hw.ncpu)
+
+    - name: Verify build artifacts
+      run: |
+        echo "=== Build artifacts ==="
+        ls -lh build/mentos/ || echo "mentos/ not found"
+        ls -lh build/*.bin 2>/dev/null || echo "*.bin files not found"
+        file build/mentos/bootloader.bin 2>/dev/null || echo "bootloader.bin not found"
+

.gitignore

@@ -124,3 +124,5 @@ iso/boot/*.bin
 
 # Wiki content (do not commit)
 WIKI/
+# Summary documentation files (do not commit)
+*.summary.md

CMakeLists.txt

@@ -8,11 +8,9 @@ cmake_minimum_required(VERSION 3.1...3.22)
 # Initialize the project.
 project(mentos C ASM)
 
-# Set the default build type to Debug.
-if(NOT CMAKE_BUILD_TYPE)
-    message(STATUS "Setting build type to 'Debug' as none was specified.")
-    set(CMAKE_BUILD_TYPE "Debug" CACHE STRING "Choose the type of build." FORCE)
-endif()
+# Add the CMAKE_BUILD_TYPE option with the full list of possible values.
+set(CMAKE_BUILD_TYPE "Debug" CACHE STRING "Choose the type of build: Debug, Release, RelWithDebInfo, MinSizeRel")
+set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release" "RelWithDebInfo" "MinSizeRel")
 
 # -----------------------------------------------------------------------------
 # ENABLE FETCH CONTENT
@@ -48,21 +46,21 @@ if((${CMAKE_HOST_SYSTEM_NAME} STREQUAL "Darwin") OR APPLE)
     # Specify the linker flags.
     set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -nostdlib")
 elseif((${CMAKE_HOST_SYSTEM_NAME} STREQUAL "Windows") OR WIN32)
-  # Windows set(EMULATOR_FLAGS ${EMULATOR_FLAGS} -sdl)
+    # Windows set(EMULATOR_FLAGS ${EMULATOR_FLAGS} -sdl)
 else()
     # Generic Unix System.
     # Find the `lsb_release` program.
     find_program(LSB_RELEASE_EXEC lsb_release HINTS /usr/bin/ /usr/local/bin/)
     mark_as_advanced(LSB_RELEASE_EXEC)
-    
+
     if(LSB_RELEASE_EXEC)
         execute_process(
             COMMAND "${LSB_RELEASE_EXEC}" --short --release
             OUTPUT_VARIABLE LSB_RELEASE_VERSION_SHORT
             OUTPUT_STRIP_TRAILING_WHITESPACE
         )
         message(STATUS "LSB version    : ${LSB_RELEASE_VERSION_SHORT}")
-        
+
         # Use GTK display for Ubuntu 19+
         if(LSB_RELEASE_VERSION_SHORT MATCHES "^(19|2[0-9])")
             set(EMULATOR_FLAGS ${EMULATOR_FLAGS} -display gtk)
@@ -105,7 +103,7 @@ set(CMAKE_ASM_COMPILER ${ASM_COMPILER})
 if(CMAKE_BUILD_TYPE STREQUAL "Debug")
     set(CMAKE_ASM_COMPILE_OBJECT "<CMAKE_ASM_COMPILER> -f elf -g -O0 -F dwarf -o <OBJECT> <SOURCE>")
 else()
-    set(CMAKE_ASM_COMPILE_OBJECT "<CMAKE_ASM_COMPILER> -f elf -g -O3 -o <OBJECT> <SOURCE>")
+    set(CMAKE_ASM_COMPILE_OBJECT "<CMAKE_ASM_COMPILER> -f elf -g -O2 -o <OBJECT> <SOURCE>")
 endif()
 
 # =============================================================================
@@ -153,7 +151,7 @@ endif()
 if(CMAKE_BUILD_TYPE STREQUAL "Debug")
     set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -g3 -ggdb -O0")
 elseif(CMAKE_BUILD_TYPE STREQUAL "Release")
-    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O3")
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O2")
 endif()
 
 # Set the assembly compiler flags.
@@ -198,9 +196,13 @@ set(EMULATOR qemu-system-i386)
 set(EMULATOR_FLAGS ${EMULATOR_FLAGS} -vga std)
 # Set the amount of memory.
 set(EMULATOR_FLAGS ${EMULATOR_FLAGS} -m 1096M)
+# Set the RTC to use local time.
+set(EMULATOR_FLAGS ${EMULATOR_FLAGS} -rtc base=localtime)
 # Disables all default devices (e.g., serial ports, network cards, VGA
 # adapters). Only devices we explicitly specify will be added.
 set(EMULATOR_FLAGS ${EMULATOR_FLAGS} -nodefaults)
+# Disable reboot and shutdown.
+set(EMULATOR_FLAGS ${EMULATOR_FLAGS} -no-reboot)
 # Set the debug type.
 if(${EMULATOR_OUTPUT_TYPE} STREQUAL OUTPUT_LOG)
     set(EMULATOR_FLAGS ${EMULATOR_FLAGS} -serial file:${CMAKE_BINARY_DIR}/serial.log)
@@ -271,11 +273,13 @@ add_custom_target(
 
 # First, we need to build the ISO for the cdrom.
 add_custom_target(
-  cdrom.iso
-  COMMAND cp -rf ${CMAKE_SOURCE_DIR}/iso .
-  COMMAND cp ${CMAKE_BINARY_DIR}/mentos/bootloader.bin ${CMAKE_BINARY_DIR}/iso/boot
-  COMMAND grub-mkrescue -o ${CMAKE_BINARY_DIR}/cdrom.iso ${CMAKE_BINARY_DIR}/iso
-  DEPENDS bootloader.bin
+    cdrom.iso
+    COMMAND ${CMAKE_COMMAND} -E rm -rf ${CMAKE_BINARY_DIR}/iso
+    COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/iso ${CMAKE_BINARY_DIR}/iso
+    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_BINARY_DIR}/mentos/bootloader.bin ${CMAKE_BINARY_DIR}/iso/boot/bootloader.bin
+    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/iso/boot/grub/grub.cfg ${CMAKE_BINARY_DIR}/iso/boot/grub/grub.cfg
+    COMMAND grub-mkrescue -o ${CMAKE_BINARY_DIR}/cdrom.iso ${CMAKE_BINARY_DIR}/iso
+    DEPENDS bootloader.bin
 )
 
 # This third target runs the emualtor, but this time, the kernel binary file is
@@ -295,11 +299,12 @@ add_custom_target(
 # First, we need to build the ISO for the cdrom. It has a slightly different
 # kernel command line including 'test'.
 add_custom_target(
-  cdrom_test.iso
-  COMMAND cp -rf ${CMAKE_SOURCE_DIR}/iso .
-  COMMAND mv ${CMAKE_BINARY_DIR}/iso/boot/grub/grub.cfg.runtests ${CMAKE_BINARY_DIR}/iso/boot/grub/grub.cfg
-  COMMAND cp ${CMAKE_BINARY_DIR}/mentos/bootloader.bin ${CMAKE_BINARY_DIR}/iso/boot
-  COMMAND grub-mkrescue -o ${CMAKE_BINARY_DIR}/cdrom_test.iso ${CMAKE_BINARY_DIR}/iso
+    cdrom_test.iso
+    COMMAND ${CMAKE_COMMAND} -E rm -rf ${CMAKE_BINARY_DIR}/iso_test
+    COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_SOURCE_DIR}/iso ${CMAKE_BINARY_DIR}/iso_test
+    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/iso/boot/grub/grub.cfg.runtests ${CMAKE_BINARY_DIR}/iso_test/boot/grub/grub.cfg
+    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_BINARY_DIR}/mentos/bootloader.bin ${CMAKE_BINARY_DIR}/iso_test/boot/bootloader.bin
+    COMMAND grub-mkrescue -o ${CMAKE_BINARY_DIR}/cdrom_test.iso ${CMAKE_BINARY_DIR}/iso_test
     DEPENDS bootloader.bin filesystem
 )
 
@@ -308,7 +313,7 @@ add_custom_target(
 # after the tests are done.
 add_custom_target(
     qemu-test
-    COMMAND ${EMULATOR} ${EMULATOR_FLAGS} -serial file:${CMAKE_BINARY_DIR}/test.log -nographic -device isa-debug-exit -boot d -cdrom ${CMAKE_BINARY_DIR}/cdrom_test.iso
+    COMMAND ${EMULATOR} ${EMULATOR_FLAGS} -nographic -device isa-debug-exit -boot d -cdrom ${CMAKE_BINARY_DIR}/cdrom_test.iso
     DEPENDS cdrom_test.iso
 )
 
@@ -356,8 +361,8 @@ endif()
 # DOCUMENTATION
 # -----------------------------------------------------------------------------
 
-if (DOXYGEN_FOUND)
-    
+if(DOXYGEN_FOUND)
+
     # FetchContent: Doxygen Awesome CSS
     FetchContent_Declare(doxygenawesome
         GIT_REPOSITORY https://github.com/jothepro/doxygen-awesome-css
@@ -431,4 +436,4 @@ if (DOXYGEN_FOUND)
         ${ALL_PROJECT_FILES}
         COMMENT "Generating Doxygen documentation"
     )
-endif (DOXYGEN_FOUND)
+endif(DOXYGEN_FOUND)

boot/src/boot.c

@@ -271,10 +271,13 @@ void boot_main(uint32_t magic, multiboot_info_t *header, uint32_t esp)
     // size of the kernel (virt_high - virt_low).
     boot_info.kernel_phy_end   = boot_info.kernel_phy_start + boot_info.kernel_size;
 
+    // Start lowmem right after the kernel end (page-aligned).
+    // DMA zone will be carved from physical memory below 16MB during zone init.
     boot_info.lowmem_phy_start  = __align_rup(boot_info.kernel_phy_end, PAGE_SIZE);
     boot_info.lowmem_phy_end    = 896 * 1024 * 1024; // 896 MB of low memory max
     boot_info.lowmem_size       = boot_info.lowmem_phy_end - boot_info.lowmem_phy_start;
-    boot_info.lowmem_virt_start = __align_rup(boot_info.kernel_end, PAGE_SIZE);
+    // Use linear mapping offset so lowmem virtual addresses match physical addresses.
+    boot_info.lowmem_virt_start = boot_info.kernel_start + (boot_info.lowmem_phy_start - boot_info.kernel_phy_start);
     boot_info.lowmem_virt_end   = boot_info.lowmem_virt_start + boot_info.lowmem_size;
 
     boot_info.highmem_phy_start = boot_info.lowmem_phy_end;

kernel/CMakeLists.txt

@@ -16,7 +16,7 @@ option(ENABLE_SCHEDULER_FEEDBACK "Enables scheduling feedback on terminal." OFF)
 
 # =============================================================================
 # Collect the kernel source files.
-file(GLOB_RECURSE KERNEL_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/src/*.c" "${CMAKE_CURRENT_SOURCE_DIR}/src/*.S")
+file(GLOB_RECURSE KERNEL_SOURCES CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/src/*.c" "${CMAKE_CURRENT_SOURCE_DIR}/src/*.S")
 # Remove the tests from the kernel sources if the tests are disabled.
 if(NOT ENABLE_KERNEL_TESTS)
     list(FILTER KERNEL_SOURCES EXCLUDE REGEX ".*/tests/.*")

kernel/inc/io/debug.h

@@ -149,6 +149,9 @@ struct pt_regs;
         dbg_fn("    EIP    = 0x%-09x\n", (frame)->eip);                                                                \
         dbg_fn("    CS     = 0x%-04x\n", (frame)->cs);                                                                 \
         dbg_fn("    EFLAGS = 0x%-09x\n", (frame)->eflags);                                                             \
-        dbg_fn("    UESP   = 0x%-09x\n", (frame)->useresp);                                                            \
-        dbg_fn("    SS     = 0x%-04x\n", (frame)->ss);                                                                 \
+        /* Only print user mode stack info if exception came from user mode (CS privilege bits = 3) */                \
+        if (((frame)->cs & 0x3) == 3) {                                                                                \
+            dbg_fn("    UESP   = 0x%-09x\n", (frame)->useresp);                                                        \
+            dbg_fn("    SS     = 0x%-04x\n", (frame)->ss);                                                             \
+        }                                                                                                               \
     } while (0)

kernel/inc/klib/stack_helper.h

@@ -1,22 +1,110 @@
 /// @file stack_helper.h
-/// @brief Couple of macros that help accessing the stack.
+/// @brief Inline functions for safe stack manipulation with proper sequencing.
 /// @copyright (c) 2014-2024 This file is distributed under the MIT License.
 /// See LICENSE.md for details.
 
 #pragma once
 
-/// @brief Access the value of the pointer.
-#define __ACCESS_PTR(type, ptr)    (*(type *)(ptr))
-/// @brief Moves the pointer down.
-#define __MOVE_PTR_DOWN(type, ptr) ((ptr) -= sizeof(type))
-/// @brief Moves the pointer up.
-#define __MOVE_PTR_UP(type, ptr)   ((ptr) += sizeof(type))
-/// @brief First, it moves the pointer down, and then it pushes the value at that memory location.
-#define PUSH_VALUE_ON_STACK(ptr, value)                                                                                \
-    (__ACCESS_PTR(__typeof__(value), __MOVE_PTR_DOWN(__typeof__(value), ptr)) = (value))
-/// @brief First, it access the value at the given memory location, and then it moves the pointer up.
-#define POP_VALUE_FROM_STACK(value, ptr)                                                                               \
-    ({                                                                                                                 \
-        (value) = __ACCESS_PTR(__typeof__(value), ptr);                                                                \
-        __MOVE_PTR_UP(__typeof__(value), ptr);                                                                         \
-    })
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+/// @brief Push a 32-bit value onto the stack, decrementing the stack pointer.
+/// @param sp Pointer to 32-bit stack pointer (will be decremented).
+/// @param value The 32-bit value to push.
+static inline void stack_push_u32(uint32_t *sp, uint32_t value)
+{
+    *sp -= sizeof(uint32_t);
+    __asm__ __volatile__("" ::: "memory");
+    *(volatile uint32_t *)(*sp) = value;
+    __asm__ __volatile__("" ::: "memory");
+}
+
+/// @brief Push a signed 32-bit value onto the stack, decrementing the stack pointer.
+/// @param sp Pointer to 32-bit stack pointer (will be decremented).
+/// @param value The signed 32-bit value to push.
+static inline void stack_push_s32(uint32_t *sp, int32_t value)
+{
+    *sp -= sizeof(int32_t);
+    __asm__ __volatile__("" ::: "memory");
+    *(volatile int32_t *)(*sp) = value;
+    __asm__ __volatile__("" ::: "memory");
+}
+
+/// @brief Push a pointer value onto the stack, decrementing the stack pointer.
+/// @param sp Pointer to 32-bit stack pointer (will be decremented).
+/// @param ptr The pointer value to push.
+static inline void stack_push_ptr(uint32_t *sp, const void *ptr)
+{
+    *sp -= sizeof(uint32_t);
+    __asm__ __volatile__("" ::: "memory");
+    *(volatile uint32_t *)(*sp) = (uint32_t)ptr;
+    __asm__ __volatile__("" ::: "memory");
+}
+
+/// @brief Push a single byte onto the stack, decrementing the stack pointer.
+/// @param sp Pointer to 32-bit stack pointer (will be decremented).
+/// @param byte The byte value to push.
+static inline void stack_push_u8(uint32_t *sp, uint8_t byte)
+{
+    *sp -= sizeof(uint8_t);
+    __asm__ __volatile__("" ::: "memory");
+    *(volatile uint8_t *)(*sp) = byte;
+    __asm__ __volatile__("" ::: "memory");
+}
+
+/// @brief Pop a 32-bit value from the stack, incrementing the stack pointer.
+/// @param sp Pointer to 32-bit stack pointer (will be incremented).
+/// @return The 32-bit value popped from the stack.
+static inline uint32_t stack_pop_u32(uint32_t *sp)
+{
+    uint32_t value = *(volatile uint32_t *)(*sp);
+    __asm__ __volatile__("" ::: "memory");
+    *sp += sizeof(uint32_t);
+    return value;
+}
+
+/// @brief Pop a signed 32-bit value from the stack, incrementing the stack pointer.
+/// @param sp Pointer to 32-bit stack pointer (will be incremented).
+/// @return The signed 32-bit value popped from the stack.
+static inline int32_t stack_pop_s32(uint32_t *sp)
+{
+    int32_t value = *(volatile int32_t *)(*sp);
+    __asm__ __volatile__("" ::: "memory");
+    *sp += sizeof(int32_t);
+    return value;
+}
+
+/// @brief Pop a pointer value from the stack, incrementing the stack pointer.
+/// @param sp Pointer to 32-bit stack pointer (will be incremented).
+/// @return The pointer value popped from the stack.
+static inline void *stack_pop_ptr(uint32_t *sp)
+{
+    void *value = (void *)*(volatile uint32_t *)(*sp);
+    __asm__ __volatile__("" ::: "memory");
+    *sp += sizeof(uint32_t);
+    return value;
+}
+
+/// @brief Push arbitrary data onto the stack, decrementing the stack pointer.
+/// @param sp Pointer to 32-bit stack pointer (will be decremented by size).
+/// @param data Pointer to data to push.
+/// @param size Number of bytes to push.
+static inline void stack_push_data(uint32_t *sp, const void *data, size_t size)
+{
+    *sp -= size;
+    __asm__ __volatile__("" ::: "memory");
+    memcpy((void *)*sp, data, size);
+    __asm__ __volatile__("" ::: "memory");
+}
+
+/// @brief Pop arbitrary data from the stack, incrementing the stack pointer.
+/// @param sp Pointer to 32-bit stack pointer (will be incremented by size).
+/// @param data Pointer to buffer where popped data will be stored.
+/// @param size Number of bytes to pop.
+static inline void stack_pop_data(uint32_t *sp, void *data, size_t size)
+{
+    memcpy(data, (void *)*sp, size);
+    __asm__ __volatile__("" ::: "memory");
+    *sp += size;
+}