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

@@ -1,15 +1,32 @@
-/*  asm.h
+/**
-*   Assembly wrappers
+ * @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 <stdint.h>
 
-
+/**
+ * @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

include/idt.h

@@ -1,6 +1,8 @@
-/* IDT.h
+/**
-*   Interrupt Descriptor Table
+ * @file idt.h
-*   
+ * @brief Interrupt Descriptor Table
+ * @author Jake "lordtet" Holtham
+ * @date 2025
  * IDT related structures, globals and functions
  */
 #ifndef IDT_H
@@ -8,25 +10,53 @@
 
 #include <stdint.h>
 
+/**
+ * @brief IDT Entry
+ */
 typedef struct InterruptDescriptor_s {
-    uint16_t offset_lo;
+    uint16_t offset_lo;     /**< Lower 16 bits of ISR ptr  */
-    uint16_t selector;
+    uint16_t selector;      /**<  */
-    uint8_t reserved;
+    uint8_t reserved;       /**< Nothing */
-    uint8_t attributes;
+    uint8_t attributes;     /**< */
-    uint16_t offset_hi;
+    uint16_t offset_hi;     /**< Upper 16 bits of ISR ptr  */
 } InterruptDescriptor_t;
 
+/**
+ * @brief 
+ */
 typedef struct IDTR_s {
-    uint16_t size;
+    uint16_t size;                      /**< IDT Length */
-    InterruptDescriptor_t* IDT;
+    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

include/interrupt_handlers.h

@@ -1,21 +1,31 @@
-/*  interrupt_handlers.h
+/**
-*   Interrupt Handlers
+ * @file interrupt_handlers.h
-*   
+ * @brief Interrupt Handlers
-*   Functions and structs for the C side of handling interrupts.
+ * @details Functions and structs for the C side of handling interrupts.
  */
 #ifndef INTERRUPTHANDLERS_H
 #define INTERRUPTHANDLERS_H
 #include <stdint.h>
 
+/**
+ * @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 edi, esi, ebp, esp, ebx, edx, ecx, eax;    /**< @brief  */
-    uint32_t interrupt_id, error_code;
+    uint32_t interrupt_id, error_code;                  /**< @brief  */
-    uint32_t eip, cs, eflags;
+    uint32_t eip, cs, eflags;                           /**< @brief  */
 } StateSnapshot_t;
 
+/**
+ * @brief 
+ * @param cpu_state 
+ */
 void generic_isr_handler(StateSnapshot_t* cpu_state);
 
 #endif

include/io.h

@@ -1,26 +1,78 @@
-/*  io.h
+/**
-*   In/Out
+ * @file io.h
-*
+ * @brief In/Out
-*   Common library for handling user i/o. Aims to be mechanic agnostic, and instead 
+ * @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 <stdint.h>
 
+/**
+ * @brief 
+ */
 typedef struct char_writer_s char_writer_t;
+
+/**
+ * @brief 
+ */
 struct char_writer_s {
-    int (*putChar)(void* ctx, char out);
+    int (*putChar)(void* ctx, char out);    /**< @brief  */
-    void* ctx;
+    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

include/kmultiboot.h

@@ -1,35 +1,47 @@
-/*  kmultiboot.h
+/**
-*   Kernel Multiboot
+ * @file kmultiboot.h
-*   
+ * @brief Kernel Multiboot
-*   Data needed for multiboot compatibility.
+ * @details Data needed for multiboot compatibility.
  */
 #ifndef KMULTIBOOT_H
 #define KMULTIBOOT_H
 
 #include <stdint.h>
+
+/**
+ * @brief 
+ */
 typedef struct multiboot_mmap_entry {
-    uint32_t entry_size; //size of this struct entry
+    uint32_t entry_size;    /**< @brief size of this struct entry */
-    uint64_t addr; //physical location of memory
+    uint64_t addr;          /**< @brief physical location of memory */
-    uint64_t mem_size; //size of the memory block
+    uint64_t mem_size;      /**< @brief size of the memory block */
-    uint32_t type;
+    uint32_t type;          /**< @brief  */
 } __attribute__((packed)) mb_mmap_entry_t;
 
-
+/**
+ * @brief 
+ */
 typedef struct mb_info_s {
-    uint32_t flags;
+    uint32_t flags;         /**< @brief  */
-    uint32_t mem_lower;
+    uint32_t mem_lower;     /**< @brief  */
-    uint32_t mem_upper;
+    uint32_t mem_upper;     /**< @brief  */
-    uint32_t boot_device;
+    uint32_t boot_device;   /**< @brief  */
-    uint32_t cmdline;
+    uint32_t cmdline;       /**< @brief  */
-    uint32_t mods_count;
+    uint32_t mods_count;    /**< @brief  */
-    uint32_t mods_addr;
+    uint32_t mods_addr;     /**< @brief  */
-    uint32_t syms[4];
+    uint32_t syms[4];       /**< @brief  */
-    uint32_t mmap_length;
+    uint32_t mmap_length;   /**< @brief  */
-    uint32_t mmap_addr;
+    uint32_t mmap_addr;     /**< @brief  */
 } mb_info_t;
 
-
+/**
+ * @brief 
+ */
 extern uint8_t _kernel_start;
+
+/**
+ * @brief 
+ */
 extern uint8_t _kernel_end;
 
 #endif

include/kttools.h

@@ -1,7 +1,7 @@
-/*  kttools.h
+/**
-*   Kernel Type Tools
+ * @file kttools.h
-*   
+ * @brief Kernel Type Tools
-*   Library for converting types and transcribing data.
+ * @details Library for converting types and transcribing data.
  */
 #ifndef KTTOOLS_H
 #define KTTOOLS_H

include/physmem.h

@@ -1,11 +1,29 @@
+/**
+ * @file physmem.h
+ * @brief 
+ * @details 
+ */
 #ifndef PHYSMEM_H
 #define PHYSMEM_H
 #include <stdint.h>
 #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

include/tss.h

@@ -1,44 +1,64 @@
-/*  tss.h
+/**
-*   Task State Segment
+ * @file tss.h
+ * @brief Task State Segment (TSS) definitions and structures
+ * @author Jake Holtham
+ * @date 2025
  * 
-*   Structure definitions for the TSS
+ * This header file contains the structure definitions for the x86 Task State Segment (TSS). 
 */
+
 #ifndef TSS_H
 #define TSS_H
+
 #include <stdint.h>
 
-// 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 LINK;    /**< Previous TSS selector*/
-    uint32_t ESP0;
+    uint32_t ESP0;    /**< Stack pointer for privilege level0*/
-    uint32_t SS0;
+    uint32_t SS0;     /**< Stack segment for privilege level0*/
-    uint32_t ESP1;
+    uint32_t ESP1;    /**< Stack pointer for privilege level1*/
-    uint32_t SS1;
+    uint32_t SS1;     /**< Stack segment for privilege level1*/
-    uint32_t ESP2;
+    uint32_t ESP2;    /**< Stack pointer for privilege level2*/
-    uint32_t SS2;
+    uint32_t SS2;     /**< Stack segment for privilege level2*/
-    uint32_t CR3;
+    uint32_t CR3;     /**< Page Directory register */
-    uint32_t EIP;
+    uint32_t EIP;     /**< Instruction pointer */
-    uint32_t EFLAGS;
+    uint32_t EFLAGS;  /**< Flags register */
-    uint32_t EAX;
+    uint32_t EAX;     /**< General purpose */
-    uint32_t ECX;
+    uint32_t ECX;     /**< General purpose */
-    uint32_t EDX;
+    uint32_t EDX;     /**< General purpose */
-    uint32_t EBX;
+    uint32_t EBX;     /**< General purpose */
-    uint32_t ESP;
+    uint32_t ESP;     /**< Stack pointer */
-    uint32_t ESI;
+    uint32_t ESI;     /**< Source index register */
-    uint32_t EDI;
+    uint32_t EDI;     /**< Destination index register */
-    uint32_t ES;
+    uint32_t ES;      /**< Extra segment register */
-    uint32_t CS;
+    uint32_t CS;      /**< Code segment register */
-    uint32_t SS;
+    uint32_t SS;      /**< Stack segment register */
-    uint32_t DS;
+    uint32_t DS;      /**< Data segment register */
-    uint32_t FS;
+    uint32_t FS;      /**< Extra segment register FS */
-    uint32_t GS;
+    uint32_t GS;      /**< Extra segment register GS */
-    uint32_t LDTR;
+    uint32_t LDTR;    /**< Local descriptor table register */
-    uint32_t IOPB;
+    uint32_t IOPB;    /**< I/O permission bitmap offset */
-    uint32_t SSP;
+    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 /* TSS_H */
-
-#endif

include/vga.h

@@ -1,42 +1,71 @@
-/*  vga.h
+/**
- *  VGA
+ * @file vga.h
- *
+ * @brief VGA
- *  Responsible for VGA buffer control.
+ * @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 <stdint.h>
 #include <stdarg.h>
 #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_col;         /**< @brief  */
-    int cursor_row;
+    int cursor_row;         /**< @brief  */
-    uint16_t attributes;
+    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);
 
 

include/virtmem.h

@@ -1,11 +1,40 @@
+/**
+ * @file virtmem.h
+ * @brief 
+ * @details 
+ */
 #ifndef VIRTMEM_H
 #define VIRTMEM_H
 #include <stdint.h>
 
-
+/**
+ * @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

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);
+}