Update HAL documentation for dual-mode support

The hardware abstraction layer now supports both cooperative and preemptive
scheduling modes with distinct context management approaches. The documentation
has been updated to reflect these architectural differences and their
implications for task initialization and privilege management.

The interrupt frame structure has been expanded to include processor state
registers and alignment padding, increasing from the previous size to
accommodate complete trap context preservation. This larger frame supports both
interrupt handling and initial task setup for preemptive scheduling, where
tasks launch through trap return rather than standard function calls.

Task initialization documentation now distinguishes between the lightweight
context structures used for voluntary yielding in cooperative mode and the
full interrupt frames required for preemptive scheduling with privilege
transitions. The dispatcher initialization process is documented separately
for each mode, explaining how cooperative tasks use standard calling
conventions while preemptive tasks rely on trap return mechanisms.

The system call interface documentation has been updated to describe the
trap-based privilege boundary crossing mechanism. This replaces the previous
description of standard function call semantics, accurately reflecting how
user mode tasks invoke kernel services through environment call instructions
that trigger synchronous exceptions.

Author: HeatCrab

Documentation/hal-calling-convention.md

@@ -109,13 +109,14 @@ void hal_context_restore(jmp_buf env, int32_t val); /* Restore context + process
 The ISR in `boot.c` performs a complete context save of all registers:
 
 ```
-Stack Frame Layout (128 bytes, offsets from sp):
+Stack Frame Layout (144 bytes, 33 words × 4 bytes, offsets from sp):
   0: ra,   4: gp,   8: tp,  12: t0,  16: t1,  20: t2
- 24: s0,  28: s1,  32: a0,  36: a1,  40: a2,  44: a3  
+ 24: s0,  28: s1,  32: a0,  36: a1,  40: a2,  44: a3
  48: a4,  52: a5,  56: a6,  60: a7,  64: s2,  68: s3
  72: s4,  76: s5,  80: s6,  84: s7,  88: s8,  92: s9
  96: s10, 100:s11, 104:t3, 108: t4, 112: t5, 116: t6
-120: mcause, 124: mepc
+120: mcause, 124: mepc, 128: mstatus
+132-140: padding (alignment to 16 bytes)
 ```
 
 Why full context save in ISR?
@@ -128,7 +129,7 @@ Why full context save in ISR?
 
 Each task stack must reserve space for the ISR frame:
 ```c
-#define ISR_STACK_FRAME_SIZE 128  /* 32 registers × 4 bytes */
+#define ISR_STACK_FRAME_SIZE 144  /* 33 words × 4 bytes, 16-byte aligned */
 ```
 
 This "red zone" is reserved at the top of every task stack to guarantee ISR safety.
@@ -147,10 +148,20 @@ int32_t result = mo_task_spawn(task_function, 2048);
 
 ### System Call Interface
 
-Linmo uses standard function calls (not trap instructions) for system services:
-- Arguments passed in `a0-a7` registers
-- Return values in `a0`
-- No special calling convention required
+Linmo provides system calls through the RISC-V trap mechanism for privilege
+boundary crossing. User mode tasks invoke system calls using the environment
+call instruction, which triggers a synchronous exception handled by the kernel.
+
+System call convention:
+- Arguments passed in `a0-a7` registers before trap
+- System call number in `a7` register
+- Trap handler preserves all registers except return value
+- Return value delivered in `a0` register after trap return
+- Standard RISC-V calling convention maintained across privilege boundary
+
+The trap-based interface allows user mode tasks to safely access kernel
+services without requiring privileged instruction execution. The kernel
+validates all parameters and mediates access to protected resources.
 
 ### Task Entry Points
 
@@ -174,9 +185,9 @@ Each task has its own stack with this layout:
 
 ```
 High Address
-+------------------+ <- stack_base + stack_size  
-| ISR Red Zone     | <- 128 bytes reserved for ISR
-| (128 bytes)      |
++------------------+ <- stack_base + stack_size
+| ISR Red Zone     | <- 144 bytes reserved for ISR
+| (144 bytes)      |
 +------------------+ <- Initial SP (16-byte aligned)
 |                  |
 | Task Stack       | <- Grows downward
@@ -251,8 +262,8 @@ Minimal context (jmp_buf):
 - 17 × 32-bit loads/stores = 68 bytes
 - Essential for cooperative scheduling
 
-Full context (ISR):  
-- 32 × 32-bit loads/stores = 128 bytes  
+Full context (ISR):
+- 33 × 32-bit loads/stores = 144 bytes (includes padding for alignment)
 - Required for preemptive interrupts
 
 ### Function Call Overhead

Documentation/hal-riscv-context-switch.md

@@ -96,7 +96,11 @@ State Preservation:
 - Nested interrupts are handled correctly by hardware's automatic state stacking
 
 ### Task Initialization
-New tasks are initialized with proper processor state:
+Task initialization differs between cooperative and preemptive modes due to
+their distinct context management approaches.
+
+In cooperative mode, tasks use lightweight context structures for voluntary
+yielding. New tasks are initialized with execution context only:
 
 ```c
 void hal_context_init(jmp_buf *ctx, size_t sp, size_t ss, size_t ra)
@@ -109,7 +113,52 @@ void hal_context_init(jmp_buf *ctx, size_t sp, size_t ss, size_t ra)
 }
 ```
 
-This ensures new tasks start with interrupts enabled in machine mode.
+This lightweight approach uses standard calling conventions where tasks
+return control through normal function returns.
+
+Preemptive mode requires interrupt frame structures to support trap-based
+context switching and privilege mode transitions. Task initialization builds
+a complete interrupt service routine frame:
+
+```c
+void *hal_build_initial_frame(void *stack_top, void *task_entry,
+                               uint32_t tp_val, bool user_mode)
+{
+    /* Allocate ISR frame at top of stack */
+    uint32_t *frame = (uint32_t *) stack_top - ISR_FRAME_SIZE;
+
+    /* Initialize all general purpose registers to zero */
+    memset(frame, 0, ISR_FRAME_SIZE * sizeof(uint32_t));
+
+    /* Set essential pointers */
+    frame[1] = (uint32_t) &_gp;  /* Global pointer */
+    frame[2] = tp_val;            /* Thread pointer */
+
+    /* Configure processor state for task entry:
+     * - MPIE=1: Interrupts will enable when task starts
+     * - MPP: Target privilege level (user or machine mode)
+     * - MIE=0: Keep interrupts disabled during frame restoration
+     */
+    uint32_t mstatus_val =
+        MSTATUS_MPIE | (user_mode ? MSTATUS_MPP_USER : MSTATUS_MPP_MACH);
+    frame[FRAME_MSTATUS] = mstatus_val;
+
+    /* Set entry point */
+    frame[FRAME_EPC] = (uint32_t) task_entry;
+
+    return frame;  /* Return frame base as initial stack pointer */
+}
+```
+
+The interrupt frame layout reserves space for all register state, control
+registers, and alignment padding. When the scheduler first dispatches this
+task, the trap return mechanism restores the frame and transfers control to
+the entry point with the configured privilege level.
+
+Key differences from cooperative mode include full register state allocation
+rather than minimal callee-saved registers, trap return semantics rather than
+function return, support for privilege level transitions through MPP
+configuration, and proper interrupt state initialization through MPIE bit.
 
 ## Implementation Details
 
@@ -168,10 +217,19 @@ New Task Creation:
 4. Processor state initialized with interrupts enabled
 
 First Task Launch:
-1. `hal_dispatch_init` transfers control from kernel to first task
+
+**Cooperative Mode**:
+1. `hal_dispatch_init` receives lightweight context structure
 2. Global interrupts enabled just before task execution
-3. Timer interrupts activated for preemptive scheduling
-4. Task begins execution at its entry point
+3. Control transfers to first task through standard function call
+4. Task begins execution and voluntarily yields control
+
+**Preemptive Mode**:
+1. `hal_dispatch_init` receives interrupt frame pointer
+2. Timer interrupt enabled for periodic preemption
+3. Dispatcher loads frame and executes trap return instruction
+4. Hardware restores registers and transitions to configured privilege level
+5. Task begins execution and can be preempted by timer
 
 Context Switch Cycle:
 1. Timer interrupt triggers scheduler entry