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 preserves complete trap context with 33 words for
register state and control registers, plus 12 bytes of padding to maintain
16-byte alignment, totaling 144 bytes. This 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 varies between modes. Cooperative mode uses lightweight
context structures containing only callee-saved registers for voluntary
yielding. Preemptive mode builds complete interrupt frames with all registers
initialized to zero, global and thread pointers configured, and processor state
set for proper privilege transitions. The frame is positioned with a 256-byte
initial stack reserve below the stack top to accommodate startup requirements.

The dispatcher initialization process differs for each scheduling mode.
Cooperative tasks transfer control through standard calling conventions with
global interrupts enabled before execution. Preemptive tasks restore interrupt
frames and execute trap return instructions, allowing hardware to transition to
the configured privilege level and enable interrupts based on the saved
processor state.

The system call interface operates through the RISC-V trap mechanism for
privilege boundary crossing. User mode tasks invoke kernel services using
environment call instructions that trigger synchronous exceptions. The trap
handler preserves all registers except the return value, maintaining standard
calling convention semantics across the privilege boundary while the kernel
validates parameters and mediates access to protected resources.

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-143: padding (12 bytes for 16-byte alignment)
 ```
 
 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,58 @@ 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)(void),
+                              int user_mode)
+{
+    /* Place frame in stack with initial reserve below for proper startup */
+    uint32_t *frame = (uint32_t *) ((uint8_t *) stack_top - 256 -
+                                    ISR_STACK_FRAME_SIZE);
+
+    /* Initialize all general purpose registers to zero */
+    for (int i = 0; i < 32; i++)
+        frame[i] = 0;
+
+    /* Compute thread pointer: aligned to 64 bytes from _end */
+    uint32_t tp_val = ((uint32_t) &_end + 63) & ~63U;
+
+    /* Set essential pointers */
+    frame[FRAME_GP] = (uint32_t) &_gp;  /* Global pointer */
+    frame[FRAME_TP] = 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 +223,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