Rewrite documentation in markdown

Documentation/build-system.md

@@ -0,0 +1,138 @@
+# Build System
+
+This document describes the internal workings of the F9 microkernel build system.
+
+## Directory Structure
+
+The build entry point is the top-level `Makefile`. The build system performs the following tasks:
+- Reads platform-related information to set include paths and platform-specific source files
+- Sets the output directory
+- Determines which source files to compile
+- Sets toolchain compile flags
+- Loads F9 microkernel configurations from `.config` (generated via `make config`)
+- Includes `build.mk` files from subdirectories to determine compilation targets
+- Builds and optionally flashes the image
+
+The source tree layout:
+
+```
+$topdir/
+├── board/
+│   └── $(BOARD)/
+├── kernel/
+│   └── lib/
+├── loader/
+│   └── elf/
+├── platform/
+│   └── $(CHIP)/
+└── user/
+```
+
+## Configuration Process
+
+F9 uses [Kconfiglib](https://github.com/sysprog21/Kconfiglib), a Python-based Kconfig implementation, for build configuration. Kconfiglib provides the same functionality as the Linux kernel's Kconfig tools but with no compilation step and better portability.
+
+### Kconfiglib Tools
+
+| Tool | Purpose |
+|------|---------|
+| `menuconfig.py` | Interactive configuration menu |
+| `genconfig.py` | Generate `include/autoconf.h` from `.config` |
+| `defconfig.py` | Apply default configuration |
+| `oldconfig.py` | Update `.config` with new options |
+| `savedefconfig.py` | Save minimal configuration |
+
+### Configuration Sequence
+
+Running `make config` (or `make menuconfig`) triggers:
+
+1. Kconfiglib is cloned from the repository if not present in `tools/kconfig/`
+2. `menuconfig.py` runs with the root `Kconfig` file
+3. User selections are saved to `.config`
+4. `genconfig.py` generates `include/autoconf.h` with `CONFIG_*` macros
+
+### Board-Specific Defaults
+
+Each board has a default configuration in `board/$(BOARD)/defconfig`:
+
+```bash
+make discoveryf4_defconfig    # Apply STM32F4-Discovery defaults
+make discoveryf429_defconfig  # Apply STM32F429I-Discovery defaults
+```
+
+## Build System Components
+
+The `mk/` directory contains the core build logic:
+
+```
+mk/
+├── config.mk
+├── generic.mk
+├── loader.mk
+├── rules/
+│   └── symmap.mk
+├── target.mk
+└── toolchain.mk
+```
+
+### config.mk
+
+Legacy configuration helper. Configuration is now handled by Kconfiglib in `tools/kconfig/`. This file remains for compatibility notes.
+
+### generic.mk
+
+The primary build orchestrator that handles:
+- Configuration generation
+- Source file compilation
+- Image building (when `CONFIG_LOADER` is disabled)
+- Image flashing
+- Build rules for different file types (`.c`, `.s`, `.bin`)
+- Clean targets
+
+### loader.mk
+
+Active only when `CONFIG_LOADER` is enabled. Handles image building for configurations that use a separate loader stage.
+
+### target.mk
+
+Entry point for `make all`. Selects the appropriate linker script based on whether `CONFIG_LOADER` is set.
+
+### toolchain.mk
+
+Configures the cross-compilation toolchain and sets compiler flags for the target architecture.
+
+### rules/symmap.mk
+
+Generates symbol map code for the KDB sampling command when `CONFIG_SYMMAP` is enabled. This allows runtime symbol resolution for debugging purposes.
+
+## Build Options
+
+### Verbose Output
+
+Enable detailed build output:
+
+```bash
+make V=1
+```
+
+### Platform Selection
+
+Configure the target board in the top-level `Makefile`:
+- `BOARD`: Target board identifier (e.g., `discoveryf4`, `discoveryf429`)
+- `PROJECT`: Project-specific configuration
+
+### Toolchain Configuration
+
+Modify `mk/toolchain.mk` to adjust:
+
+- Cross-compiler prefix
+- Compiler flags
+- Linker flags
+- Architecture-specific options
+
+## Output Artifacts
+
+Build outputs are placed in `build/$(BOARD)/`:
+- `f9.elf`: ELF executable with debug symbols
+- `f9.bin`: Raw binary for flashing
+- Object files and dependency files

Documentation/init-hooks.md

@@ -0,0 +1,59 @@
+# Init Hooks
+
+The init hook mechanism provides a global initialization framework that allows code anywhere in the kernel to register functions called at specific initialization levels during system startup.
+
+## Overview
+
+Init hooks enable modular initialization where subsystems can register their setup routines without requiring centralized coordination. The kernel guarantees that hooks are called in order of their init level. Within a single init level, the execution order of hooks is not guaranteed.
+
+This design allows platform-specific code, device drivers, and kernel subsystems to initialize themselves at the appropriate time during boot without modifying the core boot sequence.
+
+## Init Levels
+
+The following init levels are defined in ascending order of execution:
+
+| Level | Constant | Purpose |
+|-------|----------|---------|
+| 0 | `INIT_LEVEL_EARLIEST` | Very early initialization |
+| 1 | `INIT_LEVEL_PLATFORM_EARLY` | Early platform setup |
+| 2 | `INIT_LEVEL_PLATFORM` | Platform initialization |
+| 3 | `INIT_LEVEL_KERNEL` | Core kernel subsystems |
+| 4 | `INIT_LEVEL_KERNEL_LATE` | Late kernel initialization |
+
+## Usage
+
+To register an init hook, use the `INIT_HOOK` macro with a function and the desired init level:
+
+```c
+#include <init_hook.h>
+#include <debug.h>
+
+void my_subsystem_init(void)
+{
+    dbg_printf(DL_EMERG, "Initializing my subsystem\n");
+    /* Perform initialization */
+}
+INIT_HOOK(my_subsystem_init, INIT_LEVEL_PLATFORM)
+```
+
+### Specifying Relative Priority
+
+To ensure a hook runs before a specific level, subtract from the level constant:
+
+```c
+/* Run just before platform initialization */
+INIT_HOOK(early_setup, INIT_LEVEL_PLATFORM - 1)
+```
+
+To run after a level, add to the constant:
+
+```c
+/* Run just after kernel initialization */
+INIT_HOOK(late_setup, INIT_LEVEL_KERNEL + 1)
+```
+
+## Implementation Details
+
+Init hooks are implemented using linker sections. The `INIT_HOOK` macro places function pointers into a sorted section that the boot code iterates through during startup. The linker script ensures hooks are ordered by their level value.
+
+The hook execution occurs in `kernel/start.c` after basic hardware initialization but before the scheduler starts. All hooks run in privileged mode with interrupts disabled.