From 7b4e4afd431bdef063527384068ae6f08f1affe1 Mon Sep 17 00:00:00 2001 From: lordtet Date: Thu, 17 Jul 2025 07:36:45 -0400 Subject: [PATCH] Defined a couple of functions, added documentation templates Didn't feel the need to make a new branch for this one, but i added some doxygen documentation templates to all of the headers. It's a bit overdue. --- include/asm.h | 29 +++++++++--- include/idt.h | 54 +++++++++++++++++----- include/interrupt_handlers.h | 28 ++++++++---- include/io.h | 68 ++++++++++++++++++++++++---- include/kmultiboot.h | 54 +++++++++++++--------- include/kttools.h | 10 ++-- include/physmem.h | 18 ++++++++ include/tss.h | 88 ++++++++++++++++++++++-------------- include/vga.h | 67 +++++++++++++++++++-------- include/virtmem.h | 31 ++++++++++++- src/virtmem.c | 10 ++++ 11 files changed, 342 insertions(+), 115 deletions(-) create mode 100644 src/virtmem.c diff --git a/include/asm.h b/include/asm.h index 0a3a6ea..c5fa822 100644 --- a/include/asm.h +++ b/include/asm.h @@ -1,15 +1,32 @@ -/* asm.h -* Assembly wrappers -* -* Wrapper functions for using assembly files. -*/ +/** + * @file asm.h + * @brief Assembly wrappers + * @author Jake "lordtet" Holtham + * @date 2025 + * Wrapper functions for using assembly files. + */ #ifndef ASM_H #define ASM_H #include - +/** + * @brief Wrapper for asm instruction `out` that feeds a byte. + * @param port I/O Address for the port to send to + * @param data Data to send + */ void outb(uint16_t port, uint8_t data); + +/** + * @brief Wrapper for asm instruction "in" that receives bytewise. + * @param port I/O Address for the port to listen from + * @return (uint8_t) The received byte. + */ uint8_t inb(uint16_t port); + +/** + * @brief Refresh the CR3 register. + * Moves CR3 into a scratch register and back into CR3. Usually used to nuke the TLB. + */ void cr3_reload(); #endif diff --git a/include/idt.h b/include/idt.h index 5aeb41f..ed66688 100644 --- a/include/idt.h +++ b/include/idt.h @@ -1,32 +1,62 @@ -/* IDT.h -* Interrupt Descriptor Table -* -* IDT related structures, globals and functions -*/ +/** + * @file idt.h + * @brief Interrupt Descriptor Table + * @author Jake "lordtet" Holtham + * @date 2025 + * IDT related structures, globals and functions + */ #ifndef IDT_H #define IDT_H #include +/** + * @brief IDT Entry + */ typedef struct InterruptDescriptor_s { - uint16_t offset_lo; - uint16_t selector; - uint8_t reserved; - uint8_t attributes; - uint16_t offset_hi; + uint16_t offset_lo; /**< Lower 16 bits of ISR ptr */ + uint16_t selector; /**< */ + uint8_t reserved; /**< Nothing */ + uint8_t attributes; /**< */ + uint16_t offset_hi; /**< Upper 16 bits of ISR ptr */ } InterruptDescriptor_t; +/** + * @brief + */ typedef struct IDTR_s { - uint16_t size; - InterruptDescriptor_t* IDT; + uint16_t size; /**< IDT Length */ + InterruptDescriptor_t* IDT; /**< Pointer to the IDT Entry array */ } __attribute__((packed)) IDTR_t; +/** + * @brief The IDTR in memory. + */ extern IDTR_t idtr; + +/** + * @brief First IDT Entry + */ extern InterruptDescriptor_t idt_start; + +/** + * @brief Amount of ISRs implemented + */ extern unsigned char num_interrupts; +/** + * @brief Call setup and write to construct and load the IDT. + */ void setup_idt(); + +/** + * @brief Write the IDT and IDTR + */ void write_descriptors(); + +/** + * @brief LIDT call + */ extern void load_idt(); #endif diff --git a/include/interrupt_handlers.h b/include/interrupt_handlers.h index 06308ba..3a4e4fe 100644 --- a/include/interrupt_handlers.h +++ b/include/interrupt_handlers.h @@ -1,21 +1,31 @@ -/* interrupt_handlers.h -* Interrupt Handlers -* -* Functions and structs for the C side of handling interrupts. -*/ +/** + * @file interrupt_handlers.h + * @brief Interrupt Handlers + * @details Functions and structs for the C side of handling interrupts. + */ #ifndef INTERRUPTHANDLERS_H #define INTERRUPTHANDLERS_H #include +/** + * @brief + */ extern void (*isr_ptrs[])(void); -//Struct is built "backwards" since it is pushed in this order. +/** + * @brief + * @details Struct is built "backwards" since it is pushed in this order. + */ typedef struct StateSnapshot_s { - uint32_t edi, esi, ebp, esp, ebx, edx, ecx, eax; - uint32_t interrupt_id, error_code; - uint32_t eip, cs, eflags; + uint32_t edi, esi, ebp, esp, ebx, edx, ecx, eax; /**< @brief */ + uint32_t interrupt_id, error_code; /**< @brief */ + uint32_t eip, cs, eflags; /**< @brief */ } StateSnapshot_t; +/** + * @brief + * @param cpu_state + */ void generic_isr_handler(StateSnapshot_t* cpu_state); #endif diff --git a/include/io.h b/include/io.h index 16cf5a5..0f731b8 100644 --- a/include/io.h +++ b/include/io.h @@ -1,26 +1,78 @@ -/* io.h -* In/Out -* -* Common library for handling user i/o. Aims to be mechanic agnostic, and instead -* focus on implementing generic functions to format and manipulate data. -*/ +/** + * @file io.h + * @brief In/Out + * @details Common library for handling user i/o. Aims to be mechanic agnostic, and instead + * focus on implementing generic functions to format and manipulate data. + */ #ifndef IO_H #define IO_H #include +/** + * @brief + */ typedef struct char_writer_s char_writer_t; + +/** + * @brief + */ struct char_writer_s { - int (*putChar)(void* ctx, char out); - void* ctx; + int (*putChar)(void* ctx, char out); /**< @brief */ + void* ctx; /**< @brief */ }; +/** + * @brief + */ extern char_writer_t* default_output; +/** + * @brief + * @param + * @param + * @return int + */ int putc(char_writer_t*, char); + +/** + * @brief + * @param + * @param + * @return int + */ int print(char_writer_t*, const char*); + +/** + * @brief + * @param + * @param + * @return int + */ int println(char_writer_t*, const char*); + +/** + * @brief + * @param + * @param + * @return int + */ int printhex(char_writer_t*, uint64_t); + +/** + * @brief + * @param + * @param out + * @return int + */ int prindec(char_writer_t*, uint64_t out); + +/** + * @brief + * @param + * @param fmt + * @param ... + * @return int + */ int printf(char_writer_t*, const char* fmt, ...); #endif diff --git a/include/kmultiboot.h b/include/kmultiboot.h index 8e10641..a7fc003 100644 --- a/include/kmultiboot.h +++ b/include/kmultiboot.h @@ -1,35 +1,47 @@ -/* kmultiboot.h -* Kernel Multiboot -* -* Data needed for multiboot compatibility. -*/ +/** + * @file kmultiboot.h + * @brief Kernel Multiboot + * @details Data needed for multiboot compatibility. + */ #ifndef KMULTIBOOT_H #define KMULTIBOOT_H #include + +/** + * @brief + */ typedef struct multiboot_mmap_entry { - uint32_t entry_size; //size of this struct entry - uint64_t addr; //physical location of memory - uint64_t mem_size; //size of the memory block - uint32_t type; + uint32_t entry_size; /**< @brief size of this struct entry */ + uint64_t addr; /**< @brief physical location of memory */ + uint64_t mem_size; /**< @brief size of the memory block */ + uint32_t type; /**< @brief */ } __attribute__((packed)) mb_mmap_entry_t; - +/** + * @brief + */ typedef struct mb_info_s { - uint32_t flags; - uint32_t mem_lower; - uint32_t mem_upper; - uint32_t boot_device; - uint32_t cmdline; - uint32_t mods_count; - uint32_t mods_addr; - uint32_t syms[4]; - uint32_t mmap_length; - uint32_t mmap_addr; + uint32_t flags; /**< @brief */ + uint32_t mem_lower; /**< @brief */ + uint32_t mem_upper; /**< @brief */ + uint32_t boot_device; /**< @brief */ + uint32_t cmdline; /**< @brief */ + uint32_t mods_count; /**< @brief */ + uint32_t mods_addr; /**< @brief */ + uint32_t syms[4]; /**< @brief */ + uint32_t mmap_length; /**< @brief */ + uint32_t mmap_addr; /**< @brief */ } mb_info_t; - +/** + * @brief + */ extern uint8_t _kernel_start; + +/** + * @brief + */ extern uint8_t _kernel_end; #endif diff --git a/include/kttools.h b/include/kttools.h index cbdd3a0..b0be310 100644 --- a/include/kttools.h +++ b/include/kttools.h @@ -1,8 +1,8 @@ -/* kttools.h -* Kernel Type Tools -* -* Library for converting types and transcribing data. -*/ +/** + * @file kttools.h + * @brief Kernel Type Tools + * @details Library for converting types and transcribing data. + */ #ifndef KTTOOLS_H #define KTTOOLS_H #include diff --git a/include/physmem.h b/include/physmem.h index 72a6226..858d7d0 100644 --- a/include/physmem.h +++ b/include/physmem.h @@ -1,11 +1,29 @@ +/** + * @file physmem.h + * @brief + * @details + */ #ifndef PHYSMEM_H #define PHYSMEM_H #include #include "kmultiboot.h" +/** + * @brief + */ #define PAGE_SIZE 0x1000 + +/** + * @brief + */ extern uint8_t* pmem_bitmap; +/** + * @brief + * @param mmap + * @param mmap_size + * @return unsigned int + */ unsigned int build_bitmap(mb_mmap_entry_t* mmap, int mmap_size); #endif diff --git a/include/tss.h b/include/tss.h index 81e52b4..6cc794c 100644 --- a/include/tss.h +++ b/include/tss.h @@ -1,44 +1,64 @@ -/* tss.h -* Task State Segment -* -* Structure definitions for the TSS +/** + * @file tss.h + * @brief Task State Segment (TSS) definitions and structures + * @author Jake Holtham + * @date 2025 + * + * This header file contains the structure definitions for the x86 Task State Segment (TSS). */ + #ifndef TSS_H #define TSS_H + #include -// TSS +/** + * @brief Task State Segment structure + * + * Data structure that contains information about a task, + * including the state of the processor registers, stack pointers, and other task-specific + * information. It is used by the x86 architecture for task switching and interrupt handling. + * + * Packed to make sure it's aligned and the correct size. + * + * @note This structure must be aligned on a 4byte boundary + */ typedef struct tss_s { - uint32_t LINK; - uint32_t ESP0; - uint32_t SS0; - uint32_t ESP1; - uint32_t SS1; - uint32_t ESP2; - uint32_t SS2; - uint32_t CR3; - uint32_t EIP; - uint32_t EFLAGS; - uint32_t EAX; - uint32_t ECX; - uint32_t EDX; - uint32_t EBX; - uint32_t ESP; - uint32_t ESI; - uint32_t EDI; - uint32_t ES; - uint32_t CS; - uint32_t SS; - uint32_t DS; - uint32_t FS; - uint32_t GS; - uint32_t LDTR; - uint32_t IOPB; - uint32_t SSP; + uint32_t LINK; /**< Previous TSS selector*/ + uint32_t ESP0; /**< Stack pointer for privilege level0*/ + uint32_t SS0; /**< Stack segment for privilege level0*/ + uint32_t ESP1; /**< Stack pointer for privilege level1*/ + uint32_t SS1; /**< Stack segment for privilege level1*/ + uint32_t ESP2; /**< Stack pointer for privilege level2*/ + uint32_t SS2; /**< Stack segment for privilege level2*/ + uint32_t CR3; /**< Page Directory register */ + uint32_t EIP; /**< Instruction pointer */ + uint32_t EFLAGS; /**< Flags register */ + uint32_t EAX; /**< General purpose */ + uint32_t ECX; /**< General purpose */ + uint32_t EDX; /**< General purpose */ + uint32_t EBX; /**< General purpose */ + uint32_t ESP; /**< Stack pointer */ + uint32_t ESI; /**< Source index register */ + uint32_t EDI; /**< Destination index register */ + uint32_t ES; /**< Extra segment register */ + uint32_t CS; /**< Code segment register */ + uint32_t SS; /**< Stack segment register */ + uint32_t DS; /**< Data segment register */ + uint32_t FS; /**< Extra segment register FS */ + uint32_t GS; /**< Extra segment register GS */ + uint32_t LDTR; /**< Local descriptor table register */ + uint32_t IOPB; /**< I/O permission bitmap offset */ + uint32_t SSP; /**< Stack segment pointer */ } __attribute__((packed)) tss_t; +/** + * @brief Global TSS instance + * + * This is the main TSS instance used by the kernel for task management. + * It contains the current task's state information. + * Defined in assembly. + */ extern tss_t tss; - - -#endif +#endif /* TSS_H */ diff --git a/include/vga.h b/include/vga.h index 139ec66..de8f62a 100644 --- a/include/vga.h +++ b/include/vga.h @@ -1,42 +1,71 @@ -/* vga.h - * VGA - * - * Responsible for VGA buffer control. +/** + * @file vga.h + * @brief VGA + * @details Responsible for VGA buffer control. */ #ifndef VGA_H #define VGA_H + +/** + * @brief + */ #define VGA_GRID_COLS 80 + +/** + * @brief + */ #define VGA_GRID_ROWS 25 + +/** + * @brief + */ #define DEFAULT_ATTRIBUTES 0x0F00 + #include #include #include "io.h" -/* - * CONSTANTS AND VARIABLES - */ -//Information on the VGA buffer +/** + * @brief Information on the VGA buffer + */ extern volatile uint16_t* const vga_buffer; +/** + * @brief + */ typedef struct vga_ctx_s { - int cursor_col; - int cursor_row; - uint16_t attributes; + int cursor_col; /**< @brief */ + int cursor_row; /**< @brief */ + uint16_t attributes; /**< @brief */ } vga_ctx_t; -//grid is top left origin. This is our cursor! -extern uint16_t vga_attributes; // Black background, White foreground +/** + * @brief grid is top left origin. This is our cursor! Black background, White foreground + */ +extern uint16_t vga_attributes; + +/** + * @brief + */ extern char_writer_t* default_vga; -/* - * Functions +/** + * @brief Clear the VGA buffer, context optional + * @param ctx */ - -//Clear the VGA buffer, context optional void vga_clear_ctx(vga_ctx_t* ctx); + +/** + * @brief + */ void vga_clear(); -//Write character c to cursor -//Implements IO generic ASCII output + +/** + * @brief Write character c to cursor. Implements IO generic ASCII output + * @param ctx + * @param c + * @return int + */ int vga_out(void* ctx, char c); diff --git a/include/virtmem.h b/include/virtmem.h index ea445ae..4295b88 100644 --- a/include/virtmem.h +++ b/include/virtmem.h @@ -1,11 +1,40 @@ +/** + * @file virtmem.h + * @brief + * @details + */ #ifndef VIRTMEM_H #define VIRTMEM_H #include - +/** + * @brief + */ extern uint32_t global_page_dir; + +/** + * @brief + */ extern uint32_t kernel_pagetable; +/** + * @brief + * @param page_dir + * @param phys_loc + * @param virtual_loc + * @param page_opts + * @return int + */ +int map(uint32_t* page_dir, uint32_t phys_loc, uint32_t virtual_loc, uint8_t page_opts); + +/** + * @brief + * @param phys_loc + * @param virtual_loc + * @param page_opts + * @return int + */ +int kmap(uint32_t phys_loc, uint32_t virtual_loc, uint8_t page_opts); #endif diff --git a/src/virtmem.c b/src/virtmem.c new file mode 100644 index 0000000..4708aef --- /dev/null +++ b/src/virtmem.c @@ -0,0 +1,10 @@ +#include "virtmem.h" + + +int map(uint32_t* page_dir, uint32_t phys_loc, uint32_t virtual_loc, uint8_t page_opts) { + +} + +int kmap(uint32_t phys_loc, uint32_t virtual_loc, uint8_t page_opts){ + return map(&global_page_dir, phys_loc, virtual_loc, page_opts); +}