From 06742a21bb12bdaed056fce8f2b3966c1b9ddcbc Mon Sep 17 00:00:00 2001 From: Felix Morgner Date: Thu, 20 Aug 2026 10:33:14 +0200 Subject: chore: normalize comment format in arch --- arch/x86_64/CMakeLists.txt | 4 +- arch/x86_64/arch/boot/boot32.S | 206 ++++++++++++++++++---------------------- arch/x86_64/arch/memory/mmu.cpp | 5 +- arch/x86_64/arch/memory/mmu.hpp | 17 +--- arch/x86_64/arch/vga/crtc.hpp | 16 +--- 5 files changed, 107 insertions(+), 141 deletions(-) (limited to 'arch/x86_64') diff --git a/arch/x86_64/CMakeLists.txt b/arch/x86_64/CMakeLists.txt index fc665c15..a93f4f64 100644 --- a/arch/x86_64/CMakeLists.txt +++ b/arch/x86_64/CMakeLists.txt @@ -68,12 +68,12 @@ target_sources("x86_64" PRIVATE file(GLOB_RECURSE ARCH_HEADERS RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} CONFIGURE_DEPENDS - "include/**.hpp" + "arch/**.hpp" ) target_sources("x86_64" PUBLIC FILE_SET HEADERS - BASE_DIRS "include" + BASE_DIRS "arch" FILES ${ARCH_HEADERS} ) diff --git a/arch/x86_64/arch/boot/boot32.S b/arch/x86_64/arch/boot/boot32.S index e6fcd85a..89746a64 100644 --- a/arch/x86_64/arch/boot/boot32.S +++ b/arch/x86_64/arch/boot/boot32.S @@ -1,10 +1,13 @@ #include -/** - * @brief Uninitialized data for the bootstrapping process. - */ +//! Uninitialized data for the bootstrapping process. +//! +//! Data stored in this section is only used during early bootstrap, e.g. the +//! transition between 32-bit protected mode (as set up by the multiboot loader) +//! and 64-bit long mode. .section .boot_bss, "aw", @nobits +//! Initial page maps page_maps_start: page_map_level_4: .skip 512 * 8 page_map_level_3_high: .skip 512 * 8 @@ -13,15 +16,11 @@ page_map_level_2: .skip 512 * 8 page_maps_end = . page_maps_size = page_maps_end - page_maps_start -/** - * @brief Storage for the multiboot2 information pointer. - */ +//! Storage for the multiboot2 information pointer. .global multiboot_information_pointer multiboot_information_pointer: .skip 8 -/** - * @brief Storage for the bootstrap stack. - */ +//! Storage for the bootstrap stack. .section .boot_stack, "aw", @nobits .align 16 @@ -29,16 +28,12 @@ early_stack_bottom: .skip 1 << 8 early_stack_top: early_stack_size = early_stack_top - early_stack_bottom -/** - * @brief Constants for the bootstrapping process. - */ +//! Constants for the bootstrapping process. .section .boot_rodata, "a", @progbits .global global_descriptor_table_data -/** - * @brief A basic GDT for long mode. - */ +//! A basic GDT for long mode. global_descriptor_table: global_descriptor_table_null = . - global_descriptor_table .quad 0 @@ -54,24 +49,22 @@ message_cpuid_instruction_no_supported: .string "The 'cpuid' instruction is no message_long_mode_not_supported: .string "Long mode is not supported by this platform." message_return_from_kernel_main: .string "Execution returned from kernel main." -/** - * @brief Initialized data for the bootstrapping process. - */ +//! Initialized data for the bootstrapping process. .section .boot_data, "aw", @progbits -/** - * @brief A pointer to the current position within the VGA text buffer. - */ +//! A pointer to the current position within the VGA text buffer. .global vga_buffer_pointer vga_buffer_pointer: .quad 0xb8000 -/** - * @brief Code for the bootstrapping process. - */ +//! Code for the bootstrapping process. .section .boot_text, "ax", @progbits .align 16 .code32 +//! Establish a PIE base pointer. +//! +//! This macro sets up a PIE (IP relative) base pointer in %esi. This base +//! pointer can then be used to perform relative memory accesses. .macro pie_base push %esi call 0f @@ -79,38 +72,41 @@ vga_buffer_pointer: .quad 0xb8000 pop %esi .endm +//! Emit the function prolog .macro function_start push %ebp mov %esp, %ebp .endm +//! Emit the function epilog. .macro function_end leave ret .endm +//! Begin a function that will perform PIE (IP relative) data accesses. .macro pie_function_start function_start pie_base .endm +//! End a function that will perform PIE (IP relative) data accesses. .macro pie_function_end pop %esi function_end .endm -/** - * @brief Prepare the environment and start the kernel. - * - * This function performs all necessary checks to ensure the system was loaded - * by the expected loader and supports all features required to run the kernel. - * If successful, it prepares the system by setting up memory virtualization - * and then start the kernel proper. - * - * @param %eax The Multiboot 2 magic marker. - * @param %ebx The Multiboot 2 information pointer. - * @return void This function does not return. - */ + +//! Prepare the environment and start the kernel. +//! +//! This function performs all necessary checks to ensure the system was loaded +//! by the expected loader and supports all features required to run the kernel. +//! If successful, it prepares the system by setting up memory virtualization +//! and then start the kernel proper. +//! +//! @param %eax The Multiboot 2 magic marker. +//! @param %ebx The Multiboot 2 information pointer. +//! @return void This function does not return. .global _start _start: call 0f @@ -141,14 +137,12 @@ _start: pushl %eax lret -/** - * @brief Halt the system. - * - * This function will instruct the CPU to halt. It will try to keep the CPU - * halted, even if interrupts occur. - * - * @return This function never returns. - */ +//! @brief Halt the system. +//! +//! This function will instruct the CPU to halt. It will try to keep the CPU +//! halted, even if interrupts occur. +//! +//! @return This function never returns. _halt: function_start @@ -158,12 +152,10 @@ _halt: function_end -/** - * @brief Print a message via the VGA text buffer. - * - * @param ebp+12 The message to print. - * @param ebp+8 The color to print the message in. - */ +//! @brief Print a message via the VGA text buffer. +//! +//! @param %ebp+12 The message to print. +//! @param %ebp+8 The color to print the message in. _print: pie_function_start @@ -196,12 +188,10 @@ _print: pie_function_end -/** - * @brief Print a given panic message and then halt the machine as if by calling ::halt() - * - * @param ebp+4 A message to print. - * @return This function does not return. - */ +//! @brief Print a given panic message and then halt the machine CPU +//! +//! @param %ebp+4 A message to print. +//! @return This function does not return. _panic: pie_function_start @@ -220,13 +210,13 @@ _panic: pie_function_end -/** - * Assert that we were loaded by a Multiboot 2 compliant bootloader. - * - * This assertion will panic the system if the magic signature was not found. - * If we were loaded my an appropriate bootloader, this function also saves - * the provided MBI pointer to `multiboot_information_pointer`. - */ +//! Assert the kernel was loaded by a Multiboot2 compliant bootloader. +//! +//! This assertion will panic the system if the magic signature was not found. +//! If we were loaded my an appropriate bootloader, this function also saves +//! the provided MBI pointer to `multiboot_information_pointer`. +//! +//! @return void _assert_loaded_by_multiboot2_loader: pie_function_start @@ -238,11 +228,9 @@ _assert_loaded_by_multiboot2_loader: 1: pie_function_end -/** - * @brief Store the multiboot 2 information pointer in the global memory. - * - * @return void - */ +//! Store the Multiboot2 information pointer in global memory. +//! +//! @return void _save_multiboot_information_pointer: pie_function_start @@ -251,13 +239,13 @@ _save_multiboot_information_pointer: pie_function_end -/** - * @brief Assert that the CPU supports the CPUID instruction. - * - * The primary way to check for support of the instruction is to flip the ID - * bin in EFLAGS and then check if this changed was accepted. If so, the CPU - * supports the CPUID instruction, otherwise it most-likely doesn't. - */ +//! Assert the CPU supports the CPUID instruction. +//! +//! The primary way to check for support of the instruction is to flip the ID +//! bin in EFLAGS and then check if this changed was accepted. If so, the CPU +//! supports the CPUID instruction, otherwise it most-likely doesn't. +//! +//! @return void _assert_cpuid_instruction_is_supported: pie_function_start @@ -265,11 +253,11 @@ _assert_cpuid_instruction_is_supported: pop %eax mov %eax, %ecx - xor $(1 << 21), %eax /* Flip the ID bit */ - push %eax /* Move the new bitset on the stack for loading */ - popfl /* Load the flags with ID set back into EFLAGS */ - pushfl /* Copy the flags back onto the stack */ - pop %eax /* Load the flags for further checking */ + xor $(1 << 21), %eax // Flip the ID bit + push %eax // Move the new bitset on the stack for loading + popfl // Load the flags with ID set back into EFLAGS + pushfl // Copy the flags back onto the stack + pop %eax // Load the flags for further checking push %ecx popfl @@ -283,9 +271,9 @@ _assert_cpuid_instruction_is_supported: 1: pie_function_end -/** - * @brief Assert that the CPU supports going into long mode. - */ +//! Assert the CPU supports going into long mode. +//! +//! @return void _assert_cpu_supports_long_mode: pie_function_start @@ -305,12 +293,10 @@ _assert_cpu_supports_long_mode: 2: pie_function_end -/** - * @brief Prepare a basic page map hierarchy - * - * @param ebp+8 The number of huge pages to map - * @return void - */ +//! Prepare a basic page map hierarchy +//! +//! @param %ebp+8 The number of huge pages to map +//! @return void _prepare_page_maps: pie_function_start @@ -354,11 +340,9 @@ _prepare_page_maps: pie_function_end -/** - * @brief Clear all page map memory by filling it with 0s. - * - * @return void - */ +//! @brief Clear all page map memory by filling it with 0s. +//! +//! @return void _clear_page_map_memory: pie_function_start @@ -374,41 +358,39 @@ _clear_page_map_memory: pie_function_end -/** - * @p Enable memory virtualization via paging. - * - * Note: This routine expects for there to be a valid set of page maps already - * set up for use. - * - * @return void - */ +//! Enable memory virtualization via paging. +//! +//! This routine expects for there to be a valid set of page maps already set up +//! and ready for use. +//! +//! @return void _enable_paging: pie_function_start lea (page_map_level_4 - 0b)(%esi), %eax mov %eax, %cr3 - /* Enable Physical Address Extension */ + // Enable Physical Address Extension mov %cr4, %eax or $(1 << 5), %eax mov %eax, %cr4 - /* Enable long mode support */ + // Enable long mode support mov $0xC0000080, %ecx rdmsr or $(1 << 8), %eax wrmsr - /* Enable paging */ + // Enable paging mov %cr0, %eax or $(1 << 31), %eax mov %eax, %cr0 pie_function_end -/** - * @brief Enable use of SSE instructions. - */ +//! Enable use of SSE instructions. +//! +//! @return void _enable_sse: function_start @@ -423,11 +405,9 @@ _enable_sse: function_end -/** - * @brief Prepare a new GTD and load make it active. - * - * @return void - */ +//! @brief Prepare a new GTD and load make it active. +//! +//! @return void _reload_gdt: pie_function_start diff --git a/arch/x86_64/arch/memory/mmu.cpp b/arch/x86_64/arch/memory/mmu.cpp index 2b53fa48..f063e24b 100644 --- a/arch/x86_64/arch/memory/mmu.cpp +++ b/arch/x86_64/arch/memory/mmu.cpp @@ -8,7 +8,10 @@ namespace arch::memory { auto tlb_flush(kapi::memory::linear_address address) -> void { - asm volatile("invlpg (%[input])" : /* no output from call */ : [input] "r"(address) : "memory"); + asm volatile("invlpg (%[input])" + : // no output + : [input] "r"(address) + : "memory"); } auto tlb_flush_all() -> void diff --git a/arch/x86_64/arch/memory/mmu.hpp b/arch/x86_64/arch/memory/mmu.hpp index 64373f4a..7046f7fc 100644 --- a/arch/x86_64/arch/memory/mmu.hpp +++ b/arch/x86_64/arch/memory/mmu.hpp @@ -5,21 +5,12 @@ namespace arch::memory { - /** - * @brief Invalidates any translation lookaside buffer (TLB) entry for the page table the given address is cotained - * in. See https://www.felixcloutier.com/x86/invlpg for more information on the used x86 instruction. - * - * @param address Memory address, which will be used to determine the contained page and flush the TLB entry for - * that page. - */ + //! Invalidate a translation lookaside buffer (TLB) entry for a given address + //! + //! @param address The physical address for which to flush the TLB entries auto tlb_flush(kapi::memory::linear_address address) -> void; - /** - * @brief Invalidates the translation lookaside buffer (TLB) entry for all page tables. - * - * @note Simply reassigns the CR3 register the value of the CR3 register, causing a flush of the TLB buffer, because - * the system has to assume that the location of the level 4 page table moved. - */ + //! Invalidate all translation lookaside buffer (TLB) entries auto tlb_flush_all() -> void; } // namespace arch::memory diff --git a/arch/x86_64/arch/vga/crtc.hpp b/arch/x86_64/arch/vga/crtc.hpp index 1a794977..e57e675f 100644 --- a/arch/x86_64/arch/vga/crtc.hpp +++ b/arch/x86_64/arch/vga/crtc.hpp @@ -7,26 +7,18 @@ namespace arch::vga::crtc { - /** - * @brief The address port of the CRT Controller. - */ + //! The address port of the CRT Controller. using address = io::port<0x3d4, std::byte, io::port_write>; - /** - * @brief The data port of the CRT Controller. - */ + //! The data port of the CRT Controller. using data = io::port<0x3d5, std::byte, io::port_read, io::port_write>; namespace registers { - /** - * @brief The address of the Cursor Start register of the CRTC. - */ + //! The address of the Cursor Start register of the CRTC. [[maybe_unused]] constexpr auto cursor_start = std::byte{0x0a}; - /** - * @brief The address of the Cursor End register of the CRTC. - */ + //! The address of the Cursor End register of the CRTC. [[maybe_unused]] constexpr auto cursor_end = std::byte{0x0b}; } // namespace registers -- cgit v1.2.3