diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/arch.rst | 9 | ||||
| -rw-r--r-- | docs/briefs.rst | 9 | ||||
| -rw-r--r-- | docs/briefs/tb0001-pic-in-32-bit-x86-assembly.rst | 161 | ||||
| -rw-r--r-- | docs/briefs/tb0002-x86_64_bootstrap.rst | 154 | ||||
| -rw-r--r-- | docs/conf.py | 8 | ||||
| -rw-r--r-- | docs/cross.rst | 9 | ||||
| -rw-r--r-- | docs/index.rst | 3 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64.rst (renamed from docs/arch/x86_64.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/boot.rst (renamed from docs/arch/x86_64/boot.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/boot/pointers.rst (renamed from docs/arch/x86_64/boot/pointers.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching.rst (renamed from docs/arch/x86_64/context_switching.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table.rst (renamed from docs/arch/x86_64/context_switching/interrupt_descriptor_table.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/gate_descriptor.rst (renamed from docs/arch/x86_64/context_switching/interrupt_descriptor_table/gate_descriptor.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/idt_flags.rst (renamed from docs/arch/x86_64/context_switching/interrupt_descriptor_table/idt_flags.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/interrupt_descriptor_table copy.rst (renamed from docs/arch/x86_64/context_switching/interrupt_descriptor_table/interrupt_descriptor_table copy.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/interrupt_descriptor_table_pointer copy.rst (renamed from docs/arch/x86_64/context_switching/interrupt_descriptor_table/interrupt_descriptor_table_pointer copy.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/ist_offset.rst (renamed from docs/arch/x86_64/context_switching/interrupt_descriptor_table/ist_offset.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/segment_selector.rst (renamed from docs/arch/x86_64/context_switching/interrupt_descriptor_table/segment_selector.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/main.rst (renamed from docs/arch/x86_64/context_switching/main.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/segment_descriptor_table.rst (renamed from docs/arch/x86_64/context_switching/segment_descriptor_table.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/segment_descriptor_table/access_byte.rst (renamed from docs/arch/x86_64/context_switching/segment_descriptor_table/access_byte.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/segment_descriptor_table/gdt_flags.rst (renamed from docs/arch/x86_64/context_switching/segment_descriptor_table/gdt_flags.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/segment_descriptor_table/global_descriptor_table.rst (renamed from docs/arch/x86_64/context_switching/segment_descriptor_table/global_descriptor_table.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/segment_descriptor_table/global_descriptor_table_pointer.rst (renamed from docs/arch/x86_64/context_switching/segment_descriptor_table/global_descriptor_table_pointer.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_base.rst (renamed from docs/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_base.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_extension.rst (renamed from docs/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_extension.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_type.rst (renamed from docs/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_type.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/segment_descriptor_table/task_state_segment.rst (renamed from docs/arch/x86_64/context_switching/segment_descriptor_table/task_state_segment.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/syscall.rst (renamed from docs/arch/x86_64/context_switching/syscall.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/syscall/main.rst (renamed from docs/arch/x86_64/context_switching/syscall/main.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/syscall/syscall_enable.rst (renamed from docs/arch/x86_64/context_switching/syscall/syscall_enable.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/context_switching/syscall/syscall_handler.rst (renamed from docs/arch/x86_64/context_switching/syscall/syscall_handler.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/exception_handling.rst (renamed from docs/arch/x86_64/exception_handling.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/exception_handling/assert.rst (renamed from docs/arch/x86_64/exception_handling/assert.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/exception_handling/panic.rst (renamed from docs/arch/x86_64/exception_handling/panic.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/interrupt_handling.rst (renamed from docs/arch/x86_64/interrupt_handling.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/interrupt_handling/generic_interrupt_handler.rst (renamed from docs/arch/x86_64/interrupt_handling/generic_interrupt_handler.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/io.rst (renamed from docs/arch/x86_64/io.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/io/port_io.rst (renamed from docs/arch/x86_64/io/port_io.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel.rst (renamed from docs/arch/x86_64/kernel.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel/cpu.rst (renamed from docs/arch/x86_64/kernel/cpu.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel/cpu/call.rst (renamed from docs/arch/x86_64/kernel/cpu/call.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel/cpu/control_register.rst (renamed from docs/arch/x86_64/kernel/cpu/control_register.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel/cpu/gdtr.rst (renamed from docs/arch/x86_64/kernel/cpu/gdtr.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel/cpu/idtr.rst (renamed from docs/arch/x86_64/kernel/cpu/idtr.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel/cpu/if.rst (renamed from docs/arch/x86_64/kernel/cpu/if.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel/cpu/msr.rst (renamed from docs/arch/x86_64/kernel/cpu/msr.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel/cpu/segment_register.rst (renamed from docs/arch/x86_64/kernel/cpu/segment_register.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel/cpu/tlb.rst (renamed from docs/arch/x86_64/kernel/cpu/tlb.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel/cpu/tr.rst (renamed from docs/arch/x86_64/kernel/cpu/tr.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel/halt.rst (renamed from docs/arch/x86_64/kernel/halt.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/kernel/main.rst (renamed from docs/arch/x86_64/kernel/main.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory.rst (renamed from docs/arch/x86_64/memory.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/allocator.rst (renamed from docs/arch/x86_64/memory/allocator.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/allocator/area_frame_allocator.rst (renamed from docs/arch/x86_64/memory/allocator/area_frame_allocator.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/allocator/concept.rst (renamed from docs/arch/x86_64/memory/allocator/concept.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/allocator/physical_frame.rst (renamed from docs/arch/x86_64/memory/allocator/physical_frame.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/allocator/tiny_frame_allocator.rst (renamed from docs/arch/x86_64/memory/allocator/tiny_frame_allocator.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/cpu.rst (renamed from docs/arch/x86_64/memory/cpu.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/heap.rst (renamed from docs/arch/x86_64/memory/heap.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/heap/bump_allocator.rst (renamed from docs/arch/x86_64/memory/heap/bump_allocator.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/heap/global_heap_allocator.rst (renamed from docs/arch/x86_64/memory/heap/global_heap_allocator.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/heap/heap_allocator.rst (renamed from docs/arch/x86_64/memory/heap/heap_allocator.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/heap/linked_list_allocator.rst (renamed from docs/arch/x86_64/memory/heap/linked_list_allocator.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/heap/memory_block.rst (renamed from docs/arch/x86_64/memory/heap/memory_block.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/heap/user_heap_allocator.rst (renamed from docs/arch/x86_64/memory/heap/user_heap_allocator.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/main.rst (renamed from docs/arch/x86_64/memory/main.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/multiboot.rst (renamed from docs/arch/x86_64/memory/multiboot.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/multiboot/elf_symbols_section.rst (renamed from docs/arch/x86_64/memory/multiboot/elf_symbols_section.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/multiboot/info.rst (renamed from docs/arch/x86_64/memory/multiboot/info.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/multiboot/memory_map.rst (renamed from docs/arch/x86_64/memory/multiboot/memory_map.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/multiboot/reader.rst (renamed from docs/arch/x86_64/memory/multiboot/reader.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/paging.rst (renamed from docs/arch/x86_64/memory/paging.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/paging/active_page_table.rst (renamed from docs/arch/x86_64/memory/paging/active_page_table.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/paging/inactive_page_table.rst (renamed from docs/arch/x86_64/memory/paging/inactive_page_table.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/paging/kernel_mapper.rst (renamed from docs/arch/x86_64/memory/paging/kernel_mapper.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/paging/page_entry.rst (renamed from docs/arch/x86_64/memory/paging/page_entry.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/paging/page_table.rst (renamed from docs/arch/x86_64/memory/paging/page_table.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/paging/temporary_page.rst (renamed from docs/arch/x86_64/memory/paging/temporary_page.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/memory/paging/virtual_page.rst (renamed from docs/arch/x86_64/memory/paging/virtual_page.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/stl.rst (renamed from docs/arch/x86_64/stl.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/stl/container.rst (renamed from docs/arch/x86_64/stl/container.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/stl/contiguous_pointer_iterator.rst (renamed from docs/arch/x86_64/stl/contiguous_pointer_iterator.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/stl/forward_value_iterator.rst (renamed from docs/arch/x86_64/stl/forward_value_iterator.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/stl/mutex.rst (renamed from docs/arch/x86_64/stl/mutex.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/stl/shared_pointer.rst (renamed from docs/arch/x86_64/stl/shared_pointer.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/stl/stack.rst (renamed from docs/arch/x86_64/stl/stack.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/stl/unique_pointer.rst (renamed from docs/arch/x86_64/stl/unique_pointer.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/stl/vector.rst (renamed from docs/arch/x86_64/stl/vector.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/user.rst (renamed from docs/arch/x86_64/user.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/user/main.rst (renamed from docs/arch/x86_64/user/main.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/video.rst (renamed from docs/arch/x86_64/video.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/video/vga.rst (renamed from docs/arch/x86_64/video/vga.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/video/vga/io.rst (renamed from docs/arch/x86_64/video/vga/io.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/arch/x86_64/video/vga/text.rst (renamed from docs/arch/x86_64/video/vga/text.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/cross/memory.rst (renamed from docs/cross/memory.rst) | 0 | ||||
| -rw-r--r-- | docs/pre/cross/memory/asm_pointer.rst (renamed from docs/cross/memory/asm_pointer.rst) | 0 | ||||
| -rw-r--r-- | docs/requirements.txt | 2 |
98 files changed, 331 insertions, 24 deletions
diff --git a/docs/arch.rst b/docs/arch.rst deleted file mode 100644 index 495d309..0000000 --- a/docs/arch.rst +++ /dev/null @@ -1,9 +0,0 @@ -Platform-Specific Infrastructure -================================ - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - :glob: - - arch/* diff --git a/docs/briefs.rst b/docs/briefs.rst new file mode 100644 index 0000000..1931345 --- /dev/null +++ b/docs/briefs.rst @@ -0,0 +1,9 @@ +Technical Briefs +================ + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + :glob: + + briefs/* diff --git a/docs/briefs/tb0001-pic-in-32-bit-x86-assembly.rst b/docs/briefs/tb0001-pic-in-32-bit-x86-assembly.rst new file mode 100644 index 0000000..503ff43 --- /dev/null +++ b/docs/briefs/tb0001-pic-in-32-bit-x86-assembly.rst @@ -0,0 +1,161 @@ +Technical Brief 0001: Position-Independent Code (PIC) in 32-bit x86 Assembly for PIE Kernels +============================================================================================ + +The design of a modern x86-64 kernel, compiled as a Position-Independent Executable (PIE), necessitates a 32-bit assembly bootstrap stage for initial hardware setup. +This architectural requirement, however, introduces significant challenges during the linking phase. +A linker error may manifest during this process, presenting the following diagnostic: + +.. code-block:: text + + relocation R_X86_64_32 against symbol `...' can not be used when making a PIE object; recompile with -fPIE + +This error arises despite the explicit use of the ``-fPIE`` compilation flag for the object file in question. +Its occurrence indicates a fundamental incompatibility between the linking model of a PIE and the machine code generated from conventional 32-bit assembly instructions that reference symbolic addresses. +This scenario reveals a critical distinction between compiler-generated position independence and the manual implementation required for hand-written assembly in a mixed-mode, relocatable binary. + +Root Cause Analysis +------------------- + +The cause of this issue is a conflict between the linking model mandated by a Position-Independent Executable and the addressing capabilities inherent to the 32-bit x86 instruction set architecture (ISA). + +- **Position-Independent Executable (PIE) Constraints:** + A PIE is a variant of the Executable and Linkable Format (ELF) [#1]_ designed to be loaded at an arbitrary virtual address and function correctly without modification. + A strict prerequisite for this functionality is the complete absence of absolute virtual addresses within the binary's code and data sections. + Consequently, all internal data and function references must be encoded relative to the instruction pointer. + In the x86-64 ISA, this is typically accomplished through the native ``IP``-relative addressing mode (e.g., ``mov symbol(%rip), %rax``), which generates relocations of type ``R_X86_64_PC32``. + These PC-relative relocations are resolved by the linker based on the distance between the instruction and the symbol, a value that is constant regardless of the final load address. + +- **32-bit Addressing Limitations:** + The 32-bit x86 ISA lacks a native mechanism for instruction-pointer-relative addressing. + When an assembly instruction references a symbol by its name (e.g., ``movl $symbol, %eax``), the assembler's default behavior is to generate a relocation entry of type ``R_X86_64_32``. + This entry serves as a directive for the linker to substitute the symbol's final, 32-bit absolute virtual address into the machine code during the linking phase. + This process fundamentally embeds a hardcoded address into the instruction, making the code position-dependent. + +- **Mismatch:** + During the final link stage, the linker encounters these requests for absolute addresses within the 32-bit object code. + However, the linker's output target is a PIE, a format that explicitly forbids such absolute relocations because they would violate its defining characteristic of being relocatable. + The ``-fPIE`` flag, being a directive for a *compiler*, influences the code generation strategy for high-level languages like C++ but has no semantic effect on hand-written assembly that utilizes instructions which inherently produce absolute address relocations. + The linker, therefore, correctly identifies this violation of the PIE contract and terminates with an error. + +Solution: Runtime Address Calculation +------------------------------------- + +Resolution of this conflict necessitates the manual implementation of position-independent code within the 32-bit assembly module. +The core principle of this technique is the elimination of all instructions that would otherwise generate absolute address relocations. +Instead, the absolute address of any required symbol must be calculated at runtime relative to the current instruction pointer. + +- **The ``call``/``pop`` Idiom:** + The canonical technique for obtaining the value of the 32-bit instruction pointer (``EIP``) involves a ``call`` to the immediately subsequent instruction. + The ``call`` instruction pushes its return address—which is the address of the next instruction—onto the stack. + A ``pop`` instruction can then retrieve this value into a general-purpose register. + + .. code-block:: gas + + call .Lget_eip + .Lget_eip: + popl %ebx + + Upon completion of this sequence, the ``%ebx`` register contains the absolute virtual address of the ``.Lget_eip`` label at runtime. + This address serves as a reliable anchor from which other symbols' addresses can be calculated. + +- **Establishing a Base Register:** + By convention, specifically within the i386 System V ABI, the ``%ebx`` register is designated for this purpose. + It is classified as a "callee-saved" register, which obligates any conforming function to preserve its value across calls. + By establishing ``%ebx`` as a base register at the commencement of the bootstrap sequence, its value can be reliably utilized for all subsequent address calculations within that scope, even after calling external C or C++ functions. + Using a "caller-saved" register like ``%eax`` would be incorrect, as its value would have to be considered invalid after every function call. + +Representative Implementations +------------------------------ + +The subsequent examples provide canonical implementations for converting common position-dependent assembly instructions into their PIE-compliant equivalents. +These examples assume that a base register, ``%ebx``, has been initialized with the current location counter via the ``call``/``pop`` idiom at a label which, for the purpose of these examples, is designated ``.Lbase``. + +Accessing a Symbol's Address +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This pattern is applicable when passing a pointer to a symbol as a function argument. + +- Problematic Code: + + .. code-block:: gas + + pushl $message_prefix_panic + +- PIE-Compatible Solution: + + .. code-block:: gas + + // Calculate the address: base_address + (symbol_address - base_address). + // The term (message_prefix_panic - .Lbase) is a link-time constant offset. + leal (message_prefix_panic - .Lbase)(%ebx), %eax + pushl %eax + +Accessing a Symbol's Content +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This pattern is employed when reading from or writing to a global variable. + +- Problematic Code: + + .. code-block:: gas + + movl (vga_buffer_pointer), %esi + +- PIE-Compatible Solution: + + .. code-block:: gas + + // First, calculate the address of the pointer variable into a register. + leal (vga_buffer_pointer - .Lbase)(%ebx), %edi + // Then, dereference the pointer via the register to access its content. + movl (%edi), %esi + +Complex Addressing Modes +~~~~~~~~~~~~~~~~~~~~~~~~ + +This pattern is frequently used for array access. + +- Problematic Code: + + .. code-block:: gas + + movl %eax, page_map_level_2(,%ecx,8) + +- PIE-Compatible Solution: + + .. code-block:: gas + + // Calculate the base address of the array into a register. + leal (page_map_level_2 - .Lbase)(%ebx), %edx + // Utilize the register as the base in the complex addressing mode. + movl %eax, (%edx, %ecx, 8) + +Far Jumps +~~~~~~~~~ + +This technique is required for critical operations such as loading a new Global Descriptor Table (GDT) and transitioning to 64-bit mode. + +- Problematic Code: + + .. code-block:: gas + + jmp $global_descriptor_table_code, $_transition_to_long_mode + +- PIE-Compatible Solution (using ``lret``): + + .. code-block:: gas + + // Calculate the absolute virtual address of the 64-bit entry point. + leal (_transition_to_long_mode - .Lbase)(%ebx), %eax + + // Push the new segment selector and the calculated address onto the stack. + pushl $global_descriptor_table_code + pushl %eax + + // lret performs a far return, using the values from the stack, + // thereby achieving an indirect, position-independent far jump. + lret + +.. rubric:: References + +.. [#1] M. Matz, J. Hubička, A. Jaeger, and M. Mitchell, “System V Application Binary Interface AMD64 Architecture Processor Supplement Draft Version,” 2012. Available: https://refspecs.linuxfoundation.org/elf/x86_64-abi-0.99.pdf diff --git a/docs/briefs/tb0002-x86_64_bootstrap.rst b/docs/briefs/tb0002-x86_64_bootstrap.rst new file mode 100644 index 0000000..b7a6c2a --- /dev/null +++ b/docs/briefs/tb0002-x86_64_bootstrap.rst @@ -0,0 +1,154 @@ +Technical Brief 0002: x86-64 Bootstrap Subsystem +================================================ + +System Requirements and Constraints +----------------------------------- + +The design of a clean-slate, C++23-based operating system kernel necessitates a low-level bootstrap subsystem. +This subsystem manages the transition from the machine's power-on state to a controlled 64-bit execution environment. +It must operate under several architectural and toolchain constraints: + +1. **Bootloader Conformance:** The kernel is loaded by a bootloader adhering to the Multiboot2 Specification. + This conformance establishes a critical contract between the bootloader and the kernel. + The bootstrap code must therefore correctly identify the Multiboot2 magic number (``0x36d76289``) passed in the ``%eax`` register. + It must also interpret the pointer to the boot information structure passed in ``%ebx`` [1]_. + Adhering to this standard decouples the kernel from any specific bootloader implementation, ensuring portability across compliant environments like GRUB 2. + +2. **CPU Mode Transition:** The CPU is assumed to be in 32-bit protected mode upon entry to the bootstrap code. + The subsystem is responsible for all requisite steps to enable 64-bit long mode. + This is a non-trivial process. + It involves enabling Physical Address Extension (PAE) via the ``%cr4`` control register, setting the Long Mode Enable (LME) bit in the Extended Feature Enable Register (EFER) MSR (``0xC0000080``), and finally enabling paging via the ``%cr0`` control register. + +3. **Position-Independent Executable (PIE):** The kernel is compiled and linked as a PIE to allow it to be loaded at an arbitrary physical address. + This imposes a strict constraint on the 32-bit assembly code: it must not contain any absolute address relocations. + While a C++ compiler can generate position-independent code automatically, in hand-written assembly this requires the manual calculation of all symbol addresses at runtime. + This is a significant departure from simpler, absolute-addressed code. + +Architectural Overview +---------------------- + +The bootstrap architecture is partitioned into three distinct components. +This enforces a modular and verifiable transition sequence. +The components are: a shared C++/assembly interface (``boot.hpp``), a 32-bit PIE transition stage (``boot32.S``), and a minimal 64-bit entry stage (``entry64.s``). +This separation is a deliberate design choice to manage complexity. +It ensures that mode-specific logic is isolated, preventing subtle bugs that could arise from mixing 32-bit and 64-bit concerns. +Furthermore, it makes the state transition between each stage explicit and auditable. +This is critical for both debugging and for the educational utility of the codebase. + +Component Analysis +------------------ + +C++/Assembly Interface (``boot.hpp``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A single header file serves as the definitive interface between assembly code and C++. +This is achieved through the use of the ``__ASSEMBLER__`` preprocessor macro. +This is a standard feature of the GNU toolchain that allows a single file to serve a dual purpose. + +* **Shared Constants:** The header defines all magic numbers (e.g., ``MULTIBOOT2_MAGIC``), GDT flags, and other constants required by both the assembly and C++ code. + This ensures a single source of truth, eliminating the risk of inconsistencies that could arise from maintaining parallel definitions in different language domains. + +* **Conditional Declarations:** C++-specific declarations, such as ``extern "C"`` variable declarations using the ``teachos::arch::asm_pointer`` wrapper, are confined within an ``#ifndef __ASSEMBLER__`` block. + This prevents the assembler from attempting to parse C++ syntax—which would result in a compilation error—while making the full, type-safe interface available to the C++ compiler. + The ``asm_pointer`` class is particularly important. + It encapsulates a raw address and prevents its unsafe use as a standard pointer within C++, forcing any interaction to be explicit and controlled. + +32-bit Transition Stage (``boot32.S``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This file contains all code and data necessary to prepare the system for long mode. +Its logic is fundamentally incompatible with the 64-bit environment due to differences in stack width, calling conventions, and instruction encoding. + +* **Position-Independent Execution (PIE):** The 32-bit x86 ISA lacks a native instruction-pointer-relative addressing mode. + To satisfy the PIE constraint, all symbol addresses are calculated at runtime. + This is achieved via the ``call/pop`` idiom to retrieve the value of the instruction pointer (``%eip``) into a base register (``%esi``). + All subsequent memory accesses are then performed by calculating a link-time constant offset from this runtime base (e.g., ``leal (symbol - .Lbase)(%esi), %eax``). + This manual implementation of position independence is critical to avoid linker errors related to absolute relocations (``R_X86_64_32``) in a PIE binary. + +* **System State Verification:** The first actions are a series of assertions. + The code first verifies the Multiboot2 magic number (``0x36d76289``) passed in ``%eax`` [1]_. + It then uses the ``CPUID`` instruction to verify that the processor supports long mode. + This is done by checking for the LM bit (bit 29) in ``%edx`` after executing ``CPUID`` with ``0x80000001`` in ``%eax`` [2]_. + Failure of any assertion results in a call to a panic routine that halts the system. + This "fail-fast" approach is crucial; proceeding in an unsupported environment would lead to unpredictable and difficult-to-debug faults deep within the kernel. + +* **Formal Transition via ``lret``:** The stage concludes with a ``lret`` (long return) instruction. + This is the architecturally mandated method for performing an inter-segment control transfer. + This is required to load a new code segment selector and change the CPU's execution mode. + A simple ``jmp`` is insufficient as it cannot change the execution mode. + The choice of ``lret`` over other far-control transfer instructions like ``ljmp`` or ``lcall`` is a direct consequence of the PIE constraint. + The direct forms of ``ljmp`` and ``lcall`` require their target address to be a link-time constant. + This would embed an absolute address into the executable and violate the principles of position independence. + In contrast, ``lret`` consumes its target selector and offset from the stack. + This mechanism is perfectly suited for a PIE environment. + It allows for a dynamically calculated, position-independent address to be pushed onto the stack immediately before the instruction is executed. + Furthermore, ``lcall`` is architecturally inappropriate. + It would push a 32-bit return address onto the stack before the mode switch, corrupting the 64-bit stack frame for a transition that should be strictly one-way. + ``lret`` correctly models this one-way transfer and is therefore the only viable and clean option. + +64-bit Entry Stage (``entry64.s``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This file provides a minimal, clean entry point into the 64-bit world. +It ensures the C++ kernel begins execution in a pristine environment. + +* **Final State Setup:** Its sole responsibilities are to initialize the 64-bit data segment registers (``%ss``, ``%ds``, etc.) with the correct selector from the new GDT. + It then transfers control to the C++ kernel's ``main`` function via a standard ``call``. + Setting the segment registers is the first action performed. + Any memory access in 64-bit mode—including the stack operations performed by the subsequent ``call``—depends on these selectors being valid. + Failure to do so would result in a general protection fault. + +* **Halt State:** Should ``main`` ever return—an event that signifies a critical kernel failure—execution falls through to an infinite ``hlt`` loop. + This is a crucial fail-safe. + It prevents the CPU from executing beyond the end of the kernel's code, which would lead to unpredictable behavior as the CPU attempts to interpret non-executable data as instructions. + +Key Implementation Decisions +---------------------------- + +``lret`` Stack Frame Construction +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The transition to 64-bit mode is initiated by executing an ``lret`` instruction from 32-bit protected mode. +The behavior of this instruction is determined by the characteristics of the destination code segment descriptor referenced by the selector on the stack. + +The stack is prepared as follows: + +1. ``leal (_entry64 - .Lbase)(%esi), %eax``: The PIE-compatible virtual address of the 64-bit entry point is calculated and placed in ``%eax``. + +2. ``pushl $global_descriptor_table_code``: The 16-bit selector for the 64-bit code segment is pushed onto the stack as a 32-bit value. + +3. ``pushl %eax``: The 32-bit address of the entry point is pushed onto the stack. + +When ``lret`` is executed in 32-bit mode, it pops a 32-bit instruction pointer and a 16-bit code selector from the stack [3]_. +The processor then examines the GDT descriptor referenced by the new code selector. +Because this descriptor has its L-bit (Long Mode) set to 1, the processor transitions into 64-bit long mode. +It then begins executing at the 64-bit address specified by the popped instruction pointer [2]_. + +Memory Virtualization and GDT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A four-level page table hierarchy (PML4) is constructed to enable paging, a prerequisite for long mode. +An initial identity map of 32 MiB of physical memory is created using 2 MiB huge pages. +This reduces the number of required page table entries for the initial kernel image. +A recursive mapping in the PML4 at a conventional index (511) is also established. +This powerful technique allows the C++ kernel's memory manager to access and modify the entire page table hierarchy as if it were a linear array at a single, well-known virtual address. +This greatly simplifies the logic required for virtual memory operations. + +A new GDT is defined containing the necessary null, 64-bit code, and 64-bit data descriptors. +The first entry in the GDT must be a null descriptor, as the processor architecture reserves selector value 0 as a special "null selector." +Loading a segment register with this null selector is valid. +However, any subsequent memory access using it (with the exception of CS or SS) will generate a general-protection exception. +This provides a fail-safe mechanism against the use of uninitialized segment selectors [2]_. +The selector for the data descriptor is exported as a global symbol (``global_descriptor_table_data``). +This design choice was made to prioritize explicitness and debuggability. +The dependency is clearly visible in the source code, over the alternative of passing the selector value in a register. +This would create an implicit, less obvious contract between the two stages that could complicate future maintenance. + +References +---------- + +.. [1] Free Software Foundation, "The Multiboot2 Specification, version 2.0," Free Software Foundation, Inc., 2016. `Online <https://www.gnu.org/software/grub/manual/multiboot2/multiboot.html>`_. + +.. [2] Intel Corporation, *Intel® 64 and IA-32 Architectures Software Developer’s Manual, Combined Volumes 1, 2A, 2B, 2C, 2D, 3A, 3B, 3C, 3D and 4*, Order No. 325462-081US, July 2025. `Online <https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html>`_. + +.. [3] AMD, Inc., *AMD64 Architecture Programmer’s Manual, Volume 3: General-Purpose and System Instructions*, Publication No. 24594, Rev. 3.42, June 2025. `Online <https://www.amd.com/en/support/tech-docs/amd64-architecture-programmers-manual-volumes-1-5>`_. diff --git a/docs/conf.py b/docs/conf.py index 90ed3dc..b8cfe69 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,16 +13,16 @@ author = "Felix Morgner" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ["breathe"] +#extensions = ["breathe"] templates_path = ["_templates"] -exclude_patterns = [] +exclude_patterns = ["pre/**"] # -- Options Breathe --------------------------------------------------------- # https://breathe.readthedocs.io/en/stable/directives.html#config-values -breathe_projects = {"kernel": "../build/doxygen/xml"} -breathe_default_project = "kernel" +#breathe_projects = {"kernel": "../build/doxygen/xml"} +#breathe_default_project = "kernel" # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/docs/cross.rst b/docs/cross.rst deleted file mode 100644 index 542d76a..0000000 --- a/docs/cross.rst +++ /dev/null @@ -1,9 +0,0 @@ -Platform-Independent Infrastructure -=================================== - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - :glob: - - cross/* diff --git a/docs/index.rst b/docs/index.rst index e3a749f..649e6de 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,8 +5,7 @@ Welcome to TeachOS Kernel's documentation! :maxdepth: 2 :caption: Contents: - arch - cross + briefs Indices and tables ================== diff --git a/docs/arch/x86_64.rst b/docs/pre/arch/x86_64.rst index dc432f1..dc432f1 100644 --- a/docs/arch/x86_64.rst +++ b/docs/pre/arch/x86_64.rst diff --git a/docs/arch/x86_64/boot.rst b/docs/pre/arch/x86_64/boot.rst index 8be2a57..8be2a57 100644 --- a/docs/arch/x86_64/boot.rst +++ b/docs/pre/arch/x86_64/boot.rst diff --git a/docs/arch/x86_64/boot/pointers.rst b/docs/pre/arch/x86_64/boot/pointers.rst index 3ec626a..3ec626a 100644 --- a/docs/arch/x86_64/boot/pointers.rst +++ b/docs/pre/arch/x86_64/boot/pointers.rst diff --git a/docs/arch/x86_64/context_switching.rst b/docs/pre/arch/x86_64/context_switching.rst index c3b3b03..c3b3b03 100644 --- a/docs/arch/x86_64/context_switching.rst +++ b/docs/pre/arch/x86_64/context_switching.rst diff --git a/docs/arch/x86_64/context_switching/interrupt_descriptor_table.rst b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table.rst index dd6e478..dd6e478 100644 --- a/docs/arch/x86_64/context_switching/interrupt_descriptor_table.rst +++ b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table.rst diff --git a/docs/arch/x86_64/context_switching/interrupt_descriptor_table/gate_descriptor.rst b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/gate_descriptor.rst index 29e7586..29e7586 100644 --- a/docs/arch/x86_64/context_switching/interrupt_descriptor_table/gate_descriptor.rst +++ b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/gate_descriptor.rst diff --git a/docs/arch/x86_64/context_switching/interrupt_descriptor_table/idt_flags.rst b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/idt_flags.rst index 60e8c37..60e8c37 100644 --- a/docs/arch/x86_64/context_switching/interrupt_descriptor_table/idt_flags.rst +++ b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/idt_flags.rst diff --git a/docs/arch/x86_64/context_switching/interrupt_descriptor_table/interrupt_descriptor_table copy.rst b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/interrupt_descriptor_table copy.rst index a2b8997..a2b8997 100644 --- a/docs/arch/x86_64/context_switching/interrupt_descriptor_table/interrupt_descriptor_table copy.rst +++ b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/interrupt_descriptor_table copy.rst diff --git a/docs/arch/x86_64/context_switching/interrupt_descriptor_table/interrupt_descriptor_table_pointer copy.rst b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/interrupt_descriptor_table_pointer copy.rst index 3a8c259..3a8c259 100644 --- a/docs/arch/x86_64/context_switching/interrupt_descriptor_table/interrupt_descriptor_table_pointer copy.rst +++ b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/interrupt_descriptor_table_pointer copy.rst diff --git a/docs/arch/x86_64/context_switching/interrupt_descriptor_table/ist_offset.rst b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/ist_offset.rst index ddba6ee..ddba6ee 100644 --- a/docs/arch/x86_64/context_switching/interrupt_descriptor_table/ist_offset.rst +++ b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/ist_offset.rst diff --git a/docs/arch/x86_64/context_switching/interrupt_descriptor_table/segment_selector.rst b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/segment_selector.rst index 2da142e..2da142e 100644 --- a/docs/arch/x86_64/context_switching/interrupt_descriptor_table/segment_selector.rst +++ b/docs/pre/arch/x86_64/context_switching/interrupt_descriptor_table/segment_selector.rst diff --git a/docs/arch/x86_64/context_switching/main.rst b/docs/pre/arch/x86_64/context_switching/main.rst index e9e8a35..e9e8a35 100644 --- a/docs/arch/x86_64/context_switching/main.rst +++ b/docs/pre/arch/x86_64/context_switching/main.rst diff --git a/docs/arch/x86_64/context_switching/segment_descriptor_table.rst b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table.rst index 449622d..449622d 100644 --- a/docs/arch/x86_64/context_switching/segment_descriptor_table.rst +++ b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table.rst diff --git a/docs/arch/x86_64/context_switching/segment_descriptor_table/access_byte.rst b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/access_byte.rst index f2e7d67..f2e7d67 100644 --- a/docs/arch/x86_64/context_switching/segment_descriptor_table/access_byte.rst +++ b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/access_byte.rst diff --git a/docs/arch/x86_64/context_switching/segment_descriptor_table/gdt_flags.rst b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/gdt_flags.rst index faa2ffc..faa2ffc 100644 --- a/docs/arch/x86_64/context_switching/segment_descriptor_table/gdt_flags.rst +++ b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/gdt_flags.rst diff --git a/docs/arch/x86_64/context_switching/segment_descriptor_table/global_descriptor_table.rst b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/global_descriptor_table.rst index 35403db..35403db 100644 --- a/docs/arch/x86_64/context_switching/segment_descriptor_table/global_descriptor_table.rst +++ b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/global_descriptor_table.rst diff --git a/docs/arch/x86_64/context_switching/segment_descriptor_table/global_descriptor_table_pointer.rst b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/global_descriptor_table_pointer.rst index 41ceffd..41ceffd 100644 --- a/docs/arch/x86_64/context_switching/segment_descriptor_table/global_descriptor_table_pointer.rst +++ b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/global_descriptor_table_pointer.rst diff --git a/docs/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_base.rst b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_base.rst index 952ab2a..952ab2a 100644 --- a/docs/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_base.rst +++ b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_base.rst diff --git a/docs/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_extension.rst b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_extension.rst index 874d1cb..874d1cb 100644 --- a/docs/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_extension.rst +++ b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_extension.rst diff --git a/docs/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_type.rst b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_type.rst index e45b0a5..e45b0a5 100644 --- a/docs/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_type.rst +++ b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/segment_descriptor_type.rst diff --git a/docs/arch/x86_64/context_switching/segment_descriptor_table/task_state_segment.rst b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/task_state_segment.rst index 731d7bb..731d7bb 100644 --- a/docs/arch/x86_64/context_switching/segment_descriptor_table/task_state_segment.rst +++ b/docs/pre/arch/x86_64/context_switching/segment_descriptor_table/task_state_segment.rst diff --git a/docs/arch/x86_64/context_switching/syscall.rst b/docs/pre/arch/x86_64/context_switching/syscall.rst index 28acf28..28acf28 100644 --- a/docs/arch/x86_64/context_switching/syscall.rst +++ b/docs/pre/arch/x86_64/context_switching/syscall.rst diff --git a/docs/arch/x86_64/context_switching/syscall/main.rst b/docs/pre/arch/x86_64/context_switching/syscall/main.rst index 6be577b..6be577b 100644 --- a/docs/arch/x86_64/context_switching/syscall/main.rst +++ b/docs/pre/arch/x86_64/context_switching/syscall/main.rst diff --git a/docs/arch/x86_64/context_switching/syscall/syscall_enable.rst b/docs/pre/arch/x86_64/context_switching/syscall/syscall_enable.rst index e9162f1..e9162f1 100644 --- a/docs/arch/x86_64/context_switching/syscall/syscall_enable.rst +++ b/docs/pre/arch/x86_64/context_switching/syscall/syscall_enable.rst diff --git a/docs/arch/x86_64/context_switching/syscall/syscall_handler.rst b/docs/pre/arch/x86_64/context_switching/syscall/syscall_handler.rst index 0e86780..0e86780 100644 --- a/docs/arch/x86_64/context_switching/syscall/syscall_handler.rst +++ b/docs/pre/arch/x86_64/context_switching/syscall/syscall_handler.rst diff --git a/docs/arch/x86_64/exception_handling.rst b/docs/pre/arch/x86_64/exception_handling.rst index 3bf2770..3bf2770 100644 --- a/docs/arch/x86_64/exception_handling.rst +++ b/docs/pre/arch/x86_64/exception_handling.rst diff --git a/docs/arch/x86_64/exception_handling/assert.rst b/docs/pre/arch/x86_64/exception_handling/assert.rst index 053cf66..053cf66 100644 --- a/docs/arch/x86_64/exception_handling/assert.rst +++ b/docs/pre/arch/x86_64/exception_handling/assert.rst diff --git a/docs/arch/x86_64/exception_handling/panic.rst b/docs/pre/arch/x86_64/exception_handling/panic.rst index 50b6284..50b6284 100644 --- a/docs/arch/x86_64/exception_handling/panic.rst +++ b/docs/pre/arch/x86_64/exception_handling/panic.rst diff --git a/docs/arch/x86_64/interrupt_handling.rst b/docs/pre/arch/x86_64/interrupt_handling.rst index d4ff94a..d4ff94a 100644 --- a/docs/arch/x86_64/interrupt_handling.rst +++ b/docs/pre/arch/x86_64/interrupt_handling.rst diff --git a/docs/arch/x86_64/interrupt_handling/generic_interrupt_handler.rst b/docs/pre/arch/x86_64/interrupt_handling/generic_interrupt_handler.rst index 6099170..6099170 100644 --- a/docs/arch/x86_64/interrupt_handling/generic_interrupt_handler.rst +++ b/docs/pre/arch/x86_64/interrupt_handling/generic_interrupt_handler.rst diff --git a/docs/arch/x86_64/io.rst b/docs/pre/arch/x86_64/io.rst index 7082bd5..7082bd5 100644 --- a/docs/arch/x86_64/io.rst +++ b/docs/pre/arch/x86_64/io.rst diff --git a/docs/arch/x86_64/io/port_io.rst b/docs/pre/arch/x86_64/io/port_io.rst index 18a9f6a..18a9f6a 100644 --- a/docs/arch/x86_64/io/port_io.rst +++ b/docs/pre/arch/x86_64/io/port_io.rst diff --git a/docs/arch/x86_64/kernel.rst b/docs/pre/arch/x86_64/kernel.rst index 650e3a6..650e3a6 100644 --- a/docs/arch/x86_64/kernel.rst +++ b/docs/pre/arch/x86_64/kernel.rst diff --git a/docs/arch/x86_64/kernel/cpu.rst b/docs/pre/arch/x86_64/kernel/cpu.rst index da3dfc0..da3dfc0 100644 --- a/docs/arch/x86_64/kernel/cpu.rst +++ b/docs/pre/arch/x86_64/kernel/cpu.rst diff --git a/docs/arch/x86_64/kernel/cpu/call.rst b/docs/pre/arch/x86_64/kernel/cpu/call.rst index 33d15ec..33d15ec 100644 --- a/docs/arch/x86_64/kernel/cpu/call.rst +++ b/docs/pre/arch/x86_64/kernel/cpu/call.rst diff --git a/docs/arch/x86_64/kernel/cpu/control_register.rst b/docs/pre/arch/x86_64/kernel/cpu/control_register.rst index a45c6d9..a45c6d9 100644 --- a/docs/arch/x86_64/kernel/cpu/control_register.rst +++ b/docs/pre/arch/x86_64/kernel/cpu/control_register.rst diff --git a/docs/arch/x86_64/kernel/cpu/gdtr.rst b/docs/pre/arch/x86_64/kernel/cpu/gdtr.rst index 41c0f6b..41c0f6b 100644 --- a/docs/arch/x86_64/kernel/cpu/gdtr.rst +++ b/docs/pre/arch/x86_64/kernel/cpu/gdtr.rst diff --git a/docs/arch/x86_64/kernel/cpu/idtr.rst b/docs/pre/arch/x86_64/kernel/cpu/idtr.rst index b4c4bb0..b4c4bb0 100644 --- a/docs/arch/x86_64/kernel/cpu/idtr.rst +++ b/docs/pre/arch/x86_64/kernel/cpu/idtr.rst diff --git a/docs/arch/x86_64/kernel/cpu/if.rst b/docs/pre/arch/x86_64/kernel/cpu/if.rst index 2dd07b4..2dd07b4 100644 --- a/docs/arch/x86_64/kernel/cpu/if.rst +++ b/docs/pre/arch/x86_64/kernel/cpu/if.rst diff --git a/docs/arch/x86_64/kernel/cpu/msr.rst b/docs/pre/arch/x86_64/kernel/cpu/msr.rst index 75c4f47..75c4f47 100644 --- a/docs/arch/x86_64/kernel/cpu/msr.rst +++ b/docs/pre/arch/x86_64/kernel/cpu/msr.rst diff --git a/docs/arch/x86_64/kernel/cpu/segment_register.rst b/docs/pre/arch/x86_64/kernel/cpu/segment_register.rst index 8159369..8159369 100644 --- a/docs/arch/x86_64/kernel/cpu/segment_register.rst +++ b/docs/pre/arch/x86_64/kernel/cpu/segment_register.rst diff --git a/docs/arch/x86_64/kernel/cpu/tlb.rst b/docs/pre/arch/x86_64/kernel/cpu/tlb.rst index 1ceec1d..1ceec1d 100644 --- a/docs/arch/x86_64/kernel/cpu/tlb.rst +++ b/docs/pre/arch/x86_64/kernel/cpu/tlb.rst diff --git a/docs/arch/x86_64/kernel/cpu/tr.rst b/docs/pre/arch/x86_64/kernel/cpu/tr.rst index a2b234b..a2b234b 100644 --- a/docs/arch/x86_64/kernel/cpu/tr.rst +++ b/docs/pre/arch/x86_64/kernel/cpu/tr.rst diff --git a/docs/arch/x86_64/kernel/halt.rst b/docs/pre/arch/x86_64/kernel/halt.rst index c425e81..c425e81 100644 --- a/docs/arch/x86_64/kernel/halt.rst +++ b/docs/pre/arch/x86_64/kernel/halt.rst diff --git a/docs/arch/x86_64/kernel/main.rst b/docs/pre/arch/x86_64/kernel/main.rst index 194bd85..194bd85 100644 --- a/docs/arch/x86_64/kernel/main.rst +++ b/docs/pre/arch/x86_64/kernel/main.rst diff --git a/docs/arch/x86_64/memory.rst b/docs/pre/arch/x86_64/memory.rst index 58d12e9..58d12e9 100644 --- a/docs/arch/x86_64/memory.rst +++ b/docs/pre/arch/x86_64/memory.rst diff --git a/docs/arch/x86_64/memory/allocator.rst b/docs/pre/arch/x86_64/memory/allocator.rst index 6ce0a74..6ce0a74 100644 --- a/docs/arch/x86_64/memory/allocator.rst +++ b/docs/pre/arch/x86_64/memory/allocator.rst diff --git a/docs/arch/x86_64/memory/allocator/area_frame_allocator.rst b/docs/pre/arch/x86_64/memory/allocator/area_frame_allocator.rst index 422f33c..422f33c 100644 --- a/docs/arch/x86_64/memory/allocator/area_frame_allocator.rst +++ b/docs/pre/arch/x86_64/memory/allocator/area_frame_allocator.rst diff --git a/docs/arch/x86_64/memory/allocator/concept.rst b/docs/pre/arch/x86_64/memory/allocator/concept.rst index 734a2ce..734a2ce 100644 --- a/docs/arch/x86_64/memory/allocator/concept.rst +++ b/docs/pre/arch/x86_64/memory/allocator/concept.rst diff --git a/docs/arch/x86_64/memory/allocator/physical_frame.rst b/docs/pre/arch/x86_64/memory/allocator/physical_frame.rst index c5d0fd2..c5d0fd2 100644 --- a/docs/arch/x86_64/memory/allocator/physical_frame.rst +++ b/docs/pre/arch/x86_64/memory/allocator/physical_frame.rst diff --git a/docs/arch/x86_64/memory/allocator/tiny_frame_allocator.rst b/docs/pre/arch/x86_64/memory/allocator/tiny_frame_allocator.rst index 27401b2..27401b2 100644 --- a/docs/arch/x86_64/memory/allocator/tiny_frame_allocator.rst +++ b/docs/pre/arch/x86_64/memory/allocator/tiny_frame_allocator.rst diff --git a/docs/arch/x86_64/memory/cpu.rst b/docs/pre/arch/x86_64/memory/cpu.rst index 4cb5af0..4cb5af0 100644 --- a/docs/arch/x86_64/memory/cpu.rst +++ b/docs/pre/arch/x86_64/memory/cpu.rst diff --git a/docs/arch/x86_64/memory/heap.rst b/docs/pre/arch/x86_64/memory/heap.rst index 409d93a..409d93a 100644 --- a/docs/arch/x86_64/memory/heap.rst +++ b/docs/pre/arch/x86_64/memory/heap.rst diff --git a/docs/arch/x86_64/memory/heap/bump_allocator.rst b/docs/pre/arch/x86_64/memory/heap/bump_allocator.rst index b20916e..b20916e 100644 --- a/docs/arch/x86_64/memory/heap/bump_allocator.rst +++ b/docs/pre/arch/x86_64/memory/heap/bump_allocator.rst diff --git a/docs/arch/x86_64/memory/heap/global_heap_allocator.rst b/docs/pre/arch/x86_64/memory/heap/global_heap_allocator.rst index 60ec0b5..60ec0b5 100644 --- a/docs/arch/x86_64/memory/heap/global_heap_allocator.rst +++ b/docs/pre/arch/x86_64/memory/heap/global_heap_allocator.rst diff --git a/docs/arch/x86_64/memory/heap/heap_allocator.rst b/docs/pre/arch/x86_64/memory/heap/heap_allocator.rst index b410e41..b410e41 100644 --- a/docs/arch/x86_64/memory/heap/heap_allocator.rst +++ b/docs/pre/arch/x86_64/memory/heap/heap_allocator.rst diff --git a/docs/arch/x86_64/memory/heap/linked_list_allocator.rst b/docs/pre/arch/x86_64/memory/heap/linked_list_allocator.rst index d156852..d156852 100644 --- a/docs/arch/x86_64/memory/heap/linked_list_allocator.rst +++ b/docs/pre/arch/x86_64/memory/heap/linked_list_allocator.rst diff --git a/docs/arch/x86_64/memory/heap/memory_block.rst b/docs/pre/arch/x86_64/memory/heap/memory_block.rst index 8ed6566..8ed6566 100644 --- a/docs/arch/x86_64/memory/heap/memory_block.rst +++ b/docs/pre/arch/x86_64/memory/heap/memory_block.rst diff --git a/docs/arch/x86_64/memory/heap/user_heap_allocator.rst b/docs/pre/arch/x86_64/memory/heap/user_heap_allocator.rst index d0febb6..d0febb6 100644 --- a/docs/arch/x86_64/memory/heap/user_heap_allocator.rst +++ b/docs/pre/arch/x86_64/memory/heap/user_heap_allocator.rst diff --git a/docs/arch/x86_64/memory/main.rst b/docs/pre/arch/x86_64/memory/main.rst index d9a9f39..d9a9f39 100644 --- a/docs/arch/x86_64/memory/main.rst +++ b/docs/pre/arch/x86_64/memory/main.rst diff --git a/docs/arch/x86_64/memory/multiboot.rst b/docs/pre/arch/x86_64/memory/multiboot.rst index 22ec3f2..22ec3f2 100644 --- a/docs/arch/x86_64/memory/multiboot.rst +++ b/docs/pre/arch/x86_64/memory/multiboot.rst diff --git a/docs/arch/x86_64/memory/multiboot/elf_symbols_section.rst b/docs/pre/arch/x86_64/memory/multiboot/elf_symbols_section.rst index bbd6dfb..bbd6dfb 100644 --- a/docs/arch/x86_64/memory/multiboot/elf_symbols_section.rst +++ b/docs/pre/arch/x86_64/memory/multiboot/elf_symbols_section.rst diff --git a/docs/arch/x86_64/memory/multiboot/info.rst b/docs/pre/arch/x86_64/memory/multiboot/info.rst index 847870d..847870d 100644 --- a/docs/arch/x86_64/memory/multiboot/info.rst +++ b/docs/pre/arch/x86_64/memory/multiboot/info.rst diff --git a/docs/arch/x86_64/memory/multiboot/memory_map.rst b/docs/pre/arch/x86_64/memory/multiboot/memory_map.rst index 9c77331..9c77331 100644 --- a/docs/arch/x86_64/memory/multiboot/memory_map.rst +++ b/docs/pre/arch/x86_64/memory/multiboot/memory_map.rst diff --git a/docs/arch/x86_64/memory/multiboot/reader.rst b/docs/pre/arch/x86_64/memory/multiboot/reader.rst index fac98e2..fac98e2 100644 --- a/docs/arch/x86_64/memory/multiboot/reader.rst +++ b/docs/pre/arch/x86_64/memory/multiboot/reader.rst diff --git a/docs/arch/x86_64/memory/paging.rst b/docs/pre/arch/x86_64/memory/paging.rst index 10cd976..10cd976 100644 --- a/docs/arch/x86_64/memory/paging.rst +++ b/docs/pre/arch/x86_64/memory/paging.rst diff --git a/docs/arch/x86_64/memory/paging/active_page_table.rst b/docs/pre/arch/x86_64/memory/paging/active_page_table.rst index 5710131..5710131 100644 --- a/docs/arch/x86_64/memory/paging/active_page_table.rst +++ b/docs/pre/arch/x86_64/memory/paging/active_page_table.rst diff --git a/docs/arch/x86_64/memory/paging/inactive_page_table.rst b/docs/pre/arch/x86_64/memory/paging/inactive_page_table.rst index 5732e64..5732e64 100644 --- a/docs/arch/x86_64/memory/paging/inactive_page_table.rst +++ b/docs/pre/arch/x86_64/memory/paging/inactive_page_table.rst diff --git a/docs/arch/x86_64/memory/paging/kernel_mapper.rst b/docs/pre/arch/x86_64/memory/paging/kernel_mapper.rst index 9948e4e..9948e4e 100644 --- a/docs/arch/x86_64/memory/paging/kernel_mapper.rst +++ b/docs/pre/arch/x86_64/memory/paging/kernel_mapper.rst diff --git a/docs/arch/x86_64/memory/paging/page_entry.rst b/docs/pre/arch/x86_64/memory/paging/page_entry.rst index 8900b0e..8900b0e 100644 --- a/docs/arch/x86_64/memory/paging/page_entry.rst +++ b/docs/pre/arch/x86_64/memory/paging/page_entry.rst diff --git a/docs/arch/x86_64/memory/paging/page_table.rst b/docs/pre/arch/x86_64/memory/paging/page_table.rst index c5ab8c7..c5ab8c7 100644 --- a/docs/arch/x86_64/memory/paging/page_table.rst +++ b/docs/pre/arch/x86_64/memory/paging/page_table.rst diff --git a/docs/arch/x86_64/memory/paging/temporary_page.rst b/docs/pre/arch/x86_64/memory/paging/temporary_page.rst index 0c63899..0c63899 100644 --- a/docs/arch/x86_64/memory/paging/temporary_page.rst +++ b/docs/pre/arch/x86_64/memory/paging/temporary_page.rst diff --git a/docs/arch/x86_64/memory/paging/virtual_page.rst b/docs/pre/arch/x86_64/memory/paging/virtual_page.rst index dd42f47..dd42f47 100644 --- a/docs/arch/x86_64/memory/paging/virtual_page.rst +++ b/docs/pre/arch/x86_64/memory/paging/virtual_page.rst diff --git a/docs/arch/x86_64/stl.rst b/docs/pre/arch/x86_64/stl.rst index bb21f9a..bb21f9a 100644 --- a/docs/arch/x86_64/stl.rst +++ b/docs/pre/arch/x86_64/stl.rst diff --git a/docs/arch/x86_64/stl/container.rst b/docs/pre/arch/x86_64/stl/container.rst index 19c735b..19c735b 100644 --- a/docs/arch/x86_64/stl/container.rst +++ b/docs/pre/arch/x86_64/stl/container.rst diff --git a/docs/arch/x86_64/stl/contiguous_pointer_iterator.rst b/docs/pre/arch/x86_64/stl/contiguous_pointer_iterator.rst index 47f88c4..47f88c4 100644 --- a/docs/arch/x86_64/stl/contiguous_pointer_iterator.rst +++ b/docs/pre/arch/x86_64/stl/contiguous_pointer_iterator.rst diff --git a/docs/arch/x86_64/stl/forward_value_iterator.rst b/docs/pre/arch/x86_64/stl/forward_value_iterator.rst index 72270de..72270de 100644 --- a/docs/arch/x86_64/stl/forward_value_iterator.rst +++ b/docs/pre/arch/x86_64/stl/forward_value_iterator.rst diff --git a/docs/arch/x86_64/stl/mutex.rst b/docs/pre/arch/x86_64/stl/mutex.rst index 2098113..2098113 100644 --- a/docs/arch/x86_64/stl/mutex.rst +++ b/docs/pre/arch/x86_64/stl/mutex.rst diff --git a/docs/arch/x86_64/stl/shared_pointer.rst b/docs/pre/arch/x86_64/stl/shared_pointer.rst index 46ddb65..46ddb65 100644 --- a/docs/arch/x86_64/stl/shared_pointer.rst +++ b/docs/pre/arch/x86_64/stl/shared_pointer.rst diff --git a/docs/arch/x86_64/stl/stack.rst b/docs/pre/arch/x86_64/stl/stack.rst index a554387..a554387 100644 --- a/docs/arch/x86_64/stl/stack.rst +++ b/docs/pre/arch/x86_64/stl/stack.rst diff --git a/docs/arch/x86_64/stl/unique_pointer.rst b/docs/pre/arch/x86_64/stl/unique_pointer.rst index f508763..f508763 100644 --- a/docs/arch/x86_64/stl/unique_pointer.rst +++ b/docs/pre/arch/x86_64/stl/unique_pointer.rst diff --git a/docs/arch/x86_64/stl/vector.rst b/docs/pre/arch/x86_64/stl/vector.rst index b60023a..b60023a 100644 --- a/docs/arch/x86_64/stl/vector.rst +++ b/docs/pre/arch/x86_64/stl/vector.rst diff --git a/docs/arch/x86_64/user.rst b/docs/pre/arch/x86_64/user.rst index 3be32bb..3be32bb 100644 --- a/docs/arch/x86_64/user.rst +++ b/docs/pre/arch/x86_64/user.rst diff --git a/docs/arch/x86_64/user/main.rst b/docs/pre/arch/x86_64/user/main.rst index 0f641b2..0f641b2 100644 --- a/docs/arch/x86_64/user/main.rst +++ b/docs/pre/arch/x86_64/user/main.rst diff --git a/docs/arch/x86_64/video.rst b/docs/pre/arch/x86_64/video.rst index bbae5ed..bbae5ed 100644 --- a/docs/arch/x86_64/video.rst +++ b/docs/pre/arch/x86_64/video.rst diff --git a/docs/arch/x86_64/video/vga.rst b/docs/pre/arch/x86_64/video/vga.rst index 2c32bb2..2c32bb2 100644 --- a/docs/arch/x86_64/video/vga.rst +++ b/docs/pre/arch/x86_64/video/vga.rst diff --git a/docs/arch/x86_64/video/vga/io.rst b/docs/pre/arch/x86_64/video/vga/io.rst index 39609c9..39609c9 100644 --- a/docs/arch/x86_64/video/vga/io.rst +++ b/docs/pre/arch/x86_64/video/vga/io.rst diff --git a/docs/arch/x86_64/video/vga/text.rst b/docs/pre/arch/x86_64/video/vga/text.rst index 592cdd5..592cdd5 100644 --- a/docs/arch/x86_64/video/vga/text.rst +++ b/docs/pre/arch/x86_64/video/vga/text.rst diff --git a/docs/cross/memory.rst b/docs/pre/cross/memory.rst index 3a2c1c4..3a2c1c4 100644 --- a/docs/cross/memory.rst +++ b/docs/pre/cross/memory.rst diff --git a/docs/cross/memory/asm_pointer.rst b/docs/pre/cross/memory/asm_pointer.rst index 70f5c01..70f5c01 100644 --- a/docs/cross/memory/asm_pointer.rst +++ b/docs/pre/cross/memory/asm_pointer.rst diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..733e873 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +Sphinx~=8.2.0 +sphinx_book_theme~=1.1.0 |
