Add sleep and delay for task handling

Cargo.toml

@@ -1,14 +1,14 @@
 [package]
 name = "lrnrtos"
-version = "0.4.2"
+version = "0.4.3"
 edition = "2024"
 
 [[bin]]
-name= "lrnrtos"
+name = "lrnrtos"
 test = false
 
 [dependencies]
-arrayvec = {version = "0.7.6", default-features = false}
+arrayvec = { version = "0.7.6", default-features = false }
 
 [features]
 default = ["logs", "kprint"]

Documentation/kernel/data_structure.md

@@ -0,0 +1,39 @@
+# Kernel data structure
+
+<!--toc:start-->
+- [Kernel data structure](#kernel-data-structure)
+  - [Description](#description)
+    - [RingBuffer](#ringbuffer)
+      - [Invariants](#invariants)
+    - [AlignedStack16](#alignedstack16)
+      - [Invariants](#invariants-1)
+<!--toc:end-->
+
+## Description
+
+The kernel as multiple data structure implementation inside the codebase, they are useful to store and manipulate data inside the kernel.
+These are all the data structure implemented inside the kernel.
+
+### RingBuffer
+
+A simple Ring buffer, used as an FIFO. If the RingBuffer is full and you try to push anyways, it will be abort.
+It's like a close RingBuffer, you can't push if it's full and you don't pop before.
+
+#### Invariants
+
+- Length is always in [0, capacity].
+- The length is len - 1; there's always an empty slot in the array.
+- Head and tail always remain within the backing array bounds.
+- Push is only valid when the buffer is not full; violating this is a logic error (abort).
+- Pop is only valid when the buffer is not empty; violating this is a logic error (abort).
+
+### AlignedStack16
+
+This is just a structure wrapping a buffer of bytes, but the structure use the `#[repr(align(16))]`.
+This type is used when you need a stack on a buffer, and the `sp` must be aligned on `16 bytes`.
+
+#### Invariants
+
+- The backing storage is always 16-byte aligned.
+- Any stack pointer derived from this type must remain 16-byte aligned at all call boundaries.
+- This type provides a memory-layout guarantee only; it does not validate stack usage correctness.

Documentation/kernel/primitives.md

@@ -0,0 +1,78 @@
+# Kernel primitives types and functions
+
+<!--toc:start-->
+- [Kernel primitives types and functions](#kernel-primitives-types-and-functions)
+  - [Description](#description)
+    - [Primitive type](#primitive-type)
+      - [Description](#description-1)
+    - [Task primitive](#task-primitive)
+      - [Description](#description-2)
+      - [yield](#yield)
+      - [sleep](#sleep)
+      - [task_awake_blocked](#taskawakeblocked)
+      - [Invariants](#invariants)
+<!--toc:end-->
+
+## Description
+
+This document describes the kernel primitives.
+
+In the context of this kernel, a *primitive* is defined as a low-level construct that
+**directly affects kernel state or execution context**.
+If using a type or function can change global kernel behavior, scheduling state,
+or execution flow, it is considered a primitive.
+
+Two categories of primitives are documented here:
+
+- **Primitive types**: low-level types whose correct usage is required to preserve
+  kernel invariants. These types are not mere data structures; they encode execution,
+  synchronization, or memory-layout guarantees that the kernel relies on.
+  Examples include synchronization objects such as mutexes or types enforcing
+  strict alignment or execution constraints.
+
+- **Task primitives**: execution control operations that may only be used from
+  task context. These primitives modify the scheduling or blocking state of the
+  current task and therefore have observable effects on global kernel execution.
+
+Pure data structures that do not alter kernel state or execution context are
+documented separately and are not considered primitives, even if they are used
+internally by primitive implementations.
+You can find data structure type here: `Documentation/kernel/data_structure.md`.
+
+### Primitive type
+
+#### Description
+
+There are currently no primitive type implemented in the kernel.
+
+### Task primitive
+
+#### Description
+
+To handle task correctly, the kernel need some primitives but only used in a task context.
+These type can't and must not be used anywhere else than inside a task.
+
+#### yield
+
+Used in cooperative scheduling, when a task use `yield`, it will save it's context, and call a re-schedule.
+It is used when you want a task to let another task take the control.
+
+#### sleep
+
+Put the task using the `sleep` primitive function to sleep for the given time.
+It blocked the task until the kernel `GLOBAL_TICK` is equal or superior to the current tick + the given tick.
+You can consider the given tick as `1ms`.
+
+#### task_awake_blocked
+
+Awake the oldest blocked task if it can.
+This primitive is called from a timer interrupt, and only from a timer interrupt.
+The timer interrupt will give the primitive `task_awake_blocked` the current `GLOBAL_TICK`, after updating it from the current interrupt.
+The primitive will get the `oldest blocked task`, from the `BLOCKED_QUEUE`, then it'll check the reason why this task is blocked, and awake it if possible.
+
+#### Invariants
+
+- Task primitives must only be called from task context.
+- The scheduler must be initialized before any task primitive is used.
+- Time-based primitives rely on a functional timer subsystem.
+- Principal data structure such as `RUN_QUEUE` and `BLOCKED_QUEUE` must be initialized before any task primitive is used.

Documentation/kernel/timing_helpers.md

@@ -0,0 +1,22 @@
+# Kernel timing helpers
+
+<!--toc:start-->
+- [Kernel timing helpers](#kernel-timing-helpers)
+  - [Description](#description)
+    - [delay](#delay)
+    - [Invariants](#invariants)
+<!--toc:end-->
+
+## Description
+
+The kernel sometimes need to use some helpers to handle or manage timing. Here's a list of some helpers to help with that.
+
+### delay
+
+Block the CPU for the given time, in `ms`.
+This is not really recommended to use, it will not put the CPU to sleep, just waiting for the next timer interrupt.
+If you need a task to wait or something else, prefer the use of `yield`.
+
+### Invariants
+
+- The scheduler must be initialized before any timing helpers is used.

linkers/linker_test_mode.ld

@@ -3,7 +3,7 @@ ENTRY(kstart)
 MEMORY {
   RAM (rwx) : ORIGIN = 0x80200000, LENGTH = 128K
   /* Not real ROM or flash from qemu virt machine, just use another RAM reg for now */
-  ROM (rx) : ORIGIN = 0x80000000, LENGTH = 200K
+  ROM (rx) : ORIGIN = 0x80000000, LENGTH = 210K
 }
 
 SECTIONS {

src/arch/riscv32/asm/mod.rs

@@ -10,6 +10,8 @@ global_asm! {
     include_str!("set_kernel_sp.S"),
     // Yield function for context switch and scheduling
     include_str!("yield.S"),
+    // Sleep function for task and scheduling
+    include_str!("sleep.S"),
     // Scheduler context switch
     include_str!("sched_context.S"),
     // All task context offsets

src/arch/riscv32/asm/sleep.S

@@ -0,0 +1,18 @@
+.global sleep
+.type sleep, @function
+sleep:
+  # Move tick to another reg, a0 is used in save_context
+  mv t5, a0
+  # Get current task ptr
+  la t0, TASK_HANDLER # Address in RAM
+  lw t1, 0(t0) # Get the value behind the ref
+  mv a0, t1
+  # Save current ra
+  mv a1, ra
+  # Save current sp
+  mv a2, sp
+  # Call the save context function
+  call save_context
+  # Once save_context return, call the task_set_wake_tick fn
+  mv a0, t5
+  call task_set_wake_tick

src/arch/riscv32/asm/trap_entry.S

@@ -38,8 +38,8 @@ trap_entry:
   csrr	a2, mcause
   csrr	a3, mhartid
   csrr	a4, mstatus
-  # Move trap frame structure into a3 function argument register
-  mv a3, t6
+  # Move trap frame structure into a5 function argument register
+  mv a5, t6
   # Call trap_handler rust function
   call trap_handler 
   # Load all register back to previous state

src/arch/riscv32/task/mod.rs

@@ -2,8 +2,6 @@ pub mod task_context;
 
 // Asm function for task context switch
 unsafe extern "C" {
-    // Yield function for cooperative scheduling
-    pub fn r#yield();
     // Restore the task context
     pub fn restore_context(context: usize);
     // Save the current task context

src/arch/riscv32/traps/handler.rs

@@ -21,7 +21,11 @@ Tests files:
 
 use crate::{
     config::TICK_DURATION,
-    ktime::{set_ktime_ms, tick::increment_tick},
+    ktime::{
+        set_ktime_ms,
+        tick::{get_tick, increment_tick},
+    },
+    task::primitives::task_awake_blocked,
 };
 
 use super::trap_frame::TrapFrame;
@@ -90,5 +94,7 @@ fn timer_interrupt(hart: usize) {
     if hart == 0 {
         increment_tick();
     }
+    let tick = get_tick();
+    task_awake_blocked(tick);
     set_ktime_ms(TICK_DURATION);
 }

src/info.rs

@@ -1,4 +1,4 @@
 // The kernel exposes build-time version information at runtime.
 // This information is immutable and reflects the exact binary currently running.
 // It is intended for debugging, logging, and diagnostic purposes.
-pub static KERNEL_VERSION: &str = "0.4.2";
+pub static KERNEL_VERSION: &str = "0.4.3";

src/main.rs

@@ -62,6 +62,8 @@ use primitives::ring_buff::RingBuffer;
 
 // Static buffer to use as a ready queue for task.
 pub static mut BUFFER: RingBuffer<u16, 3> = RingBuffer::init();
+// Queue containing all blocked task.
+pub static mut BLOCKED_QUEUE: RingBuffer<u16, 3> = RingBuffer::init();
 
 #[unsafe(no_mangle)]
 unsafe extern "C" fn main() -> ! {

src/primitives/ring_buff.rs

@@ -23,7 +23,6 @@ References:
 
 use crate::{log, logs::LogLevel};
 
-#[derive(Debug)]
 pub struct RingBuffer<T, const N: usize> {
     buff: [Option<T>; N],
     // Oldest element in the buffer
@@ -34,7 +33,7 @@ pub struct RingBuffer<T, const N: usize> {
     count: usize,
 }
 
-impl<T: Copy + core::fmt::Debug, const N: usize> RingBuffer<T, N> {
+impl<T: Copy, const N: usize> RingBuffer<T, N> {
     pub const fn init() -> Self {
         RingBuffer {
             buff: [None; N],

src/scheduler/mod.rs

@@ -36,13 +36,15 @@ use crate::{
 pub fn dispatch() {
     // Current running task
     let mut current_task = unsafe { *TASK_HANDLER };
-    current_task.state = TaskState::Ready;
-    let pid = task_pid(&current_task);
-    task_list_update_task_by_pid(pid, current_task);
-    #[allow(static_mut_refs)]
-    unsafe {
-        BUFFER.push(pid)
-    };
+    if current_task.state != TaskState::Blocked {
+        current_task.state = TaskState::Ready;
+        let pid = task_pid(&current_task);
+        task_list_update_task_by_pid(pid, current_task);
+        #[allow(static_mut_refs)]
+        unsafe {
+            BUFFER.push(pid)
+        };
+    }
     // Update and load next task
     #[allow(static_mut_refs)]
     let get_next_task = unsafe { BUFFER.pop() };

src/task/mod.rs

@@ -22,6 +22,7 @@ use list::task_list_add_task;
 use crate::{arch::task::task_context::TaskContext, log, logs::LogLevel, mem::mem_task_alloc};
 
 pub mod list;
+pub mod primitives;
 
 // Mutable static to keep track of the current task
 // Only relevant on a monocore CPU.
@@ -36,21 +37,30 @@ pub static mut TASK_HANDLER: *mut Task = core::ptr::null_mut();
 #[repr(u8)]
 // Allow unused for now because this issue doesn't need to handle all task state
 #[allow(unused)]
-#[derive(Copy, Clone)]
+#[derive(Copy, Clone, PartialEq)]
 pub enum TaskState {
     New,
     Running,
     Ready,
     Waiting,
+    Blocked,
     Terminated,
 }
 
+#[derive(Copy, Clone)]
+pub enum TaskBlockControl {
+    AwakeTick(usize),
+    None,
+}
+
 #[derive(Copy, Clone)]
 #[repr(C)]
 pub struct Task {
     // Arch dependant context, don't handle this field in task, only use struct method when
     // interacting with it.
     pub context: TaskContext,
+    // Task block control, define the reason the task is blocked.
+    pub block_control: TaskBlockControl,
     // Fn ptr to task entry point, this must never return.
     pub func: fn() -> !,
     pid: u16,
@@ -89,6 +99,7 @@ impl Task {
                 mem_reg.expect("Error: failed to get the task memory region"),
                 func,
             ),
+            block_control: TaskBlockControl::None,
             func,
             pid: 0,
             name: buf,