Refactor + linker update (#13)

* update README

* [FIX] fix param name in gettime

* [UPDATE] updated printf param to const

* [ADD] kernel halt and panic for unexpected behaviors

* refactor + added discard commands + reserve spaces for page table

* [REFACTOR] consolidate irq files to interrupt file

* [refactor] updated the way we handled irq testing

* update function documentation

* [ADD] custom division operation

* added more macros + moved the irq handlers from irq file to interrupt file

* added mapping file for  linker instruction address mapping

* fix documentation mismatch + add .data init

* move the attribute noreturn order

* updated panic to use more modern C standard (C23)

* Updated stack start and end + added proper heap start and end

* enforce std=C23

* update mapping with no debu mode

* updated doc with updated stack name

* Updated header documentation for Doxygen auto generated docs

* Updated implementation documentation for Doxygen auto generated documentation.

* Added config file for Doxygen.

* remove MAN generated documentation from Doxygen config

* Added Doxygen documentation generator to makefile

* added README as main page

Author: chrisdedman

Doxyfile

@@ -0,0 +1,72 @@
+#----------------------------------------------------------
+# Project Identity
+#----------------------------------------------------------
+PROJECT_NAME           = "AstraKernel"
+PROJECT_NUMBER         = "v0.1.0"
+PROJECT_BRIEF          = "A minimalist experimental ARM kernel"
+OUTPUT_DIRECTORY       = docs
+
+#----------------------------------------------------------
+# Input
+#----------------------------------------------------------
+# Scan both source and header files + markdown pages
+INPUT                  = kernel user include docs/pages README.md
+FILE_PATTERNS          = *.c *.h *.md *.s *.ld
+RECURSIVE              = YES
+EXCLUDE_PATTERNS       = */tests/* */build/* */literature/*
+
+#----------------------------------------------------------
+# Documentation Extraction
+#----------------------------------------------------------
+# Merge header + source comments for the same function
+JAVADOC_AUTOBRIEF      = YES
+MULTILINE_CPP_IS_BRIEF = YES
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+INTERNAL_DOCS          = YES
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO    # Set to YES if you want code in docs
+
+#----------------------------------------------------------
+# Preprocessing / Macros
+#----------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = NO
+PREDEFINED             = __attribute__(x)= \
+                         asm(x)= \
+                         __asm__= \
+                         KERNEL=1
+
+#----------------------------------------------------------
+# Warnings
+#----------------------------------------------------------
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO
+QUIET                  = NO
+
+#----------------------------------------------------------
+# Output Formats
+#----------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+GENERATE_LATEX         = NO
+GENERATE_MAN           = NO
+GENERATE_XML           = NO
+
+#----------------------------------------------------------
+# Diagrams / Graphs
+#----------------------------------------------------------
+HAVE_DOT               = YES
+DOT_IMAGE_FORMAT       = svg
+CALL_GRAPH             = YES
+CALLER_GRAPH           = YES
+DOT_MULTI_TARGETS      = YES
+
+#----------------------------------------------------------
+# Markdown / Main Page
+#----------------------------------------------------------
+USE_MDFILE_AS_MAINPAGE = ./README.md
+MARKDOWN_SUPPORT       = YES

Makefile

@@ -16,7 +16,7 @@ OBJCOPY       := $(CROSS_COMPILE)objcopy
 INC_DIRS   := -I./include
 ARCH_FLAGS := -mcpu=cortex-a8 -marm
 
-CFLAGS := -ffreestanding -nostdlib -nostartfiles \
+CFLAGS := -std=c23 -ffreestanding -nostdlib -nostartfiles \
           $(ARCH_FLAGS) -O2 -Wall -Wextra \
           -fno-builtin \
           $(INC_DIRS)
@@ -40,7 +40,7 @@ $(OUT_DIR)%.o: %.c
 
 # Link everything
 $(OUT_DIR)kernel.elf: $(OUT_DIR)start.o $(OBJS) kernel.ld
-	$(LD) $(LDFLAGS) $(OUT_DIR)start.o $(OBJS) -o $@
+	$(LD) $(LDFLAGS) $(OUT_DIR)start.o $(OBJS) -o $@ -Map=map_file.map
 
 # Binary and others unchanged
 kernel.bin: $(OUT_DIR)kernel.elf
@@ -61,4 +61,8 @@ docker-dev:
 	docker build -f Dockerfile.dev -t "astra-kernel-dev" .
 	docker run -it --rm "astra-kernel-dev"
 
-.PHONY: all clean qemu docker
+docs:
+	mkdir -p docs
+	doxygen Doxyfile
+
+.PHONY: all clean qemu docker docs

README.md

@@ -3,9 +3,10 @@
 [![GitHub release (including pre-releases)](https://img.shields.io/github/v/release/sandbox-science/AstraKernel?include_prereleases)](https://github.com/sandbox-science/AstraKernel/releases)
 
 AstraKernel is a minimal experimental kernel written in modern C and ARM assembly, designed to run on
-**QEMU's VersatileAB (Cortex-A8)** platform. The purpose is educational, showing the fundamental
-steps of bringing up a bare-metal system, from low-level bootstrapping to higher-level interactive features
-to explore kernel development concepts.
+**QEMU’s Versatile AB/PB board with a Cortex‑A8 CPU override (-cpu cortex-a8)**. This setup keeps the
+simple Versatile peripheral map while enabling **ARMv7‑A** features for experimentation. 
+The purpose is educational, showing the fundamental steps of bringing up a bare-metal system, from 
+low-level bootstrapping to higher-level interactive features to explore kernel development concepts.
 
 ```bash
 ========================================
@@ -25,6 +26,19 @@ Press Ctrl-A and then X to exit QEMU.
 AstraKernel >
 ```
 
+## Target platform and configuration
+
+- Machine (board): `versatilepb` (or `versatileab`)
+- CPU model: `cortex-a8` (via `-cpu cortex-a8`)
+- Key peripherals (Versatile map):
+  - UART0 (PL011): 0x101F1000
+  - Timers (SP804): 0x101E2000
+  - Interrupt controller: VIC at 0x10140000
+  - SDRAM base: 0x00000000
+- Exception vectors: initially at 0x00000000 (32-byte aligned).
+  
+Later, the kernel may relocate vectors using VBAR once the MMU is enabled.
+
 ## Features so far
 
 - [x] **Bootstrapping**: stack setup, BSS clearing, entry into the kernel main.
@@ -44,7 +58,7 @@ make
 
 Developers also have the option to run the kernel with custom flags, such as:
 ```sh
-make KFLAGS="-USE_KTESTS -MY_DEFFLAG"
+make KFLAGS="-DUSE_KTESTS -MY_DEFFLAG"
 ```
 
 > [!IMPORTANT]
@@ -63,7 +77,7 @@ make docker
 > [!IMPORTANT]
 > 
 > `make docker` will pull from the most recent `main` commit from the upstream repository
-> `https://github.com/sanbox-science/AstraKernel.git`.
+> `https://github.com/sandbox-science/AstraKernel.git`.
 > If you wish to use a local copy, you can run `make docker-dev`, which will copy all
 > local build files into the repository.
 
@@ -89,4 +103,4 @@ By using AstraKernel, you acknowledge that you understand these limitations.
 
 ## License
 
-This project is licensed under the GNU GENERAL PUBLIC License. See the [LICENSE](LICENSE) file for details.
+This project is licensed under the GNU General Public License. See the [LICENSE](LICENSE) file for details.

doc/AstraKernelManual.pdf

@@ -18,7 +18,7 @@ \section{Getting Started}
 
 _start:
     // Set up the stack pointer
-    LDR sp, =_estack
+    LDR sp, =__stack_top__
     BIC sp, sp, #7
 
     // Zero the .bss section

doc/contents/introduction.tex

@@ -24,7 +24,7 @@ extern "C"
     } dateval;
 
     uint32_t getdate(dateval *date);
-    uint32_t gettime(timeval *time);
+    uint32_t gettime(timeval *time_struct);
 
 #ifdef __cplusplus
 }

include/datetime.h

@@ -13,10 +13,14 @@ extern "C"
 #define VIC_BASE        0x10140000u
 #define VIC_INTSELECT   (*(volatile uint32_t *)(VIC_BASE + 0x00C)) // 0=IRQ,1=FIQ
 #define VIC_INTENABLE   (*(volatile uint32_t *)(VIC_BASE + 0x010)) // set bit=enable
-#define VIC_INT_ENCLR   (*(volatile utin32_t *)(VIC_BASE + 0x014))
+#define VIC_INTENCLR    (*(volatile utin32_t *)(VIC_BASE + 0x014)) // clear bit=disable
 #define VIC_SOFT_INT    (*(volatile uint32_t *)(VIC_BASE + 0x018))
 #define VIC_SOFT_INTCLR (*(volatile uint32_t *)(VIC_BASE + 0x01C))
 
+#define VIC_IRQSTATUS   (*(volatile uint32_t *)(VIC_BASE + 0x000))
+#define VIC_VECTADDR    (*(volatile uint32_t *)(VIC_BASE + 0x030))
+#define VIC_DEFVECTADDR (*(volatile uint32_t *)(VIC_BASE + 0x034))
+
 // SP804 Timer0 in the 0/1 block
 // ref: ARM Dual-Time Module (SP804) TRM (Page 3-2)
 #define T01_BASE    0x101E2000u
@@ -36,6 +40,12 @@ extern "C"
 // VIC line number for Timer0/1 on Versatile
 #define IRQ_TIMER01 4
 
+    void irq_handler(void);
+    void irq_enable(void);
+    void irq_disable(void);
+
+    void interrupts_init_timer0(uint32_t tick_hz, uint32_t timer_clk_hz);
+
     static inline void timer0_start_periodic(uint32_t load)
     {
         T0_CONTROL  = 0;        // disable while reconfig

include/interrupt.h

@@ -0,0 +1,39 @@
+#pragma once
+
+#include <stdint.h>
+#include "panic.h"
+
+/**
+ * @brief Unsigned 32-bit integer division: n / d
+ *
+ * @param n Numerator.
+ * @param d Denominator.
+ * 
+ * @return uint32_t Quotient, discards remainder.
+ *
+ * @note If d == 0: kernel panic.
+ *       Otherwise, returns the quotient and discards the remainder.
+ */
+static inline uint32_t _udiv32(uint32_t n, uint32_t d)
+{
+    if (d == 0)
+    {
+        kernel_panic("Error: Division by zero in udiv32.\n");
+    }
+
+    uint32_t quotient  = 0;
+    uint32_t remainder = 0;
+    for (int i = 31; i >= 0; --i)
+    {
+        remainder = (remainder << 1) | ((n >> i) & 1u);
+        if (remainder >= d)
+        {
+            remainder -= d;
+            quotient  |= (1u << i);
+        }
+    }
+    return quotient;
+}
+// Note: This is a simple implementation and may not be the most efficient.
+// It is intended for educational purposes and may be replaced with
+// architecture-specific optimizations if needed.

include/irq.h

@@ -0,0 +1,30 @@
+/**
+ * @file panic.h
+ * @brief Kernel panic and halt routines.
+ *
+ * This module provides mechanisms to halt the system or 
+ * stop execution in response to critical errors.
+ */
+#pragma once
+
+/**
+ * @brief Halt the CPU indefinitely.
+ *
+ * Disables interrupts and places the processor in an infinite 
+ * low-power wait state.
+ *
+ * @note This function never returns.
+ */
+[[noreturn]] void kernel_halt(void);
+
+/**
+ * @brief Print a panic message and halt the CPU.
+ *
+ * Used to stop the kernel when an unrecoverable error occurs.
+ *
+ * @param message A human-readable string describing the reason 
+ *        for the panic.
+ *
+ * @note This function never returns.
+ */
+[[noreturn]] void kernel_panic(const char *message);