Import from the internal tree

Author: jserv

.clang-format

@@ -0,0 +1,27 @@
+BasedOnStyle: Chromium
+Language: Cpp
+MaxEmptyLinesToKeep: 3
+IndentCaseLabels: false
+AllowShortIfStatementsOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+DerivePointerAlignment: false
+PointerAlignment: Right
+SpaceAfterCStyleCast: true
+TabWidth: 4
+UseTab: Never
+IndentWidth: 4
+BreakBeforeBraces: Linux
+AccessModifierOffset: -4
+ForEachMacros:
+  - foreach
+  - Q_FOREACH
+  - BOOST_FOREACH
+  - list_for_each
+  - list_for_each_safe
+  - list_for_each_entry
+  - list_for_each_entry_safe
+  - hlist_for_each_entry
+  - rb_list_foreach
+  - rb_list_foreach_safe
+SpaceBeforeParens: ControlStatementsExceptForEachMacros

.gitignore

@@ -0,0 +1 @@
+build/

Documentation/hal-riscv-context-switch.md

@@ -0,0 +1,41 @@
+# HAL: Context Switching for RISC-V
+
+## Context Switching
+
+Context switching is essential to Linmo's preemptive multitasking kernel, facilitating smooth task transitions. In Linmo, this is managed through `setjmp` and `longjmp` functions, implemented in [arch/riscv/hal.c](../arch/riscv/hal.c) and declared in [arch/riscv/hal.h](../arch/riscv/hal.h). These functions enable the kernel to save and restore task states, supporting reliable multitasking. The process involves unique considerations due to the non-standard use of these functions, requiring careful handling to ensure system stability.
+
+### Repurposed setjmp and longjmp
+
+The `setjmp` and `longjmp` functions, typically used for exception handling, are repurposed in Linmo for context switching. They save additional states beyond standard registers, including CSRs like `mcause`, `mepc`, and `mstatus`, which may lead to unexpected behavior if not properly managed. During timer interrupts, `setjmp` must handle `mstatus.MIE` being cleared, relying on `MPIE` reconstruction, a departure from their usual role. Similarly, `longjmp` restores context without reinitializing local variables or the call stack, posing risks of resource leaks in tasks with dynamic memory. These deviations demand precise implementation to maintain task switching integrity.
+
+### Context Switch Process
+
+1. Save Current Task State: The `setjmp` function captures the current task's CPU state, storing it in a `jmp_buf` structure defined as `uint32_t jmp_buf[19]` in [arch/riscv/hal.h](../arch/riscv/hal.h). This includes callee-saved general-purpose registers (such as `s0` to `s11`), essential pointers (`gp`, `tp`, `sp`, `ra`), and CSRs (`mcause`, `mepc`, `mstatus`). The layout is defined by `CONTEXT_*` macros in [arch/riscv/hal.c](../arch/riscv/hal.c). Failing to reconstruct `mstatus` from `MPIE` during this step can cause incorrect interrupt settings, leading to missed timer interrupts or stalls, which is mitigated by ensuring proper `mstatus` reconstruction.
+
+2. Select Next Task: The scheduler, invoked via `dispatcher()` during a machine timer interrupt, selects the next task using a priority-based round-robin algorithm or a user-defined scheduler. This evaluates task priorities and readiness, ensuring system responsiveness. The process relies on accurate `mstatus` restoration to avoid timing issues.
+
+3. Restore Next Task State: The `longjmp` function restores the CPU state from the selected task’s `jmp_buf`, resuming execution where `setjmp` was called. For new tasks, `hal_context_init` initializes the `jmp_buf` with `sp`, `ra`, and `mstatus` set to `MSTATUS_MIE` and `MSTATUS_MPP_MACH`, while `hal_dispatch_init` launches the task. The `hal_interrupt_tick` function enables interrupts (`_ei()`) after the first task, ensuring a consistent environment. Premature restoration of `mstatus` can disrupt scheduling, addressed by prioritizing it before other registers.
+
+## Machine Status Management
+
+The machine status in RISC-V is managed through the `mstatus` CSR, which controls critical system states, such as the Machine Interrupt Enable (`MIE`) bit. Proper handling of `mstatus` during context switching is essential to maintain correct interrupt behavior and ensure tasks execute as expected.
+
+### Role of `mstatus`
+
+The `mstatus` register includes the `MIE` bit (bit 3), which enables or disables machine-mode interrupts globally, and the `MPIE` bit (bit 7), which preserves the previous interrupt enable state during a trap, allowing `MIE` to be reconstructed afterward. Other fields, such as those for privilege mode and memory protection, are less relevant in Linmo’s single-address-space model but must still be preserved. The `hal_interrupt_set` function in [arch/riscv/hal.h](../arch/riscv/hal.h) manipulates `MIE` using `read_csr(mstatus)` and `write_csr(mstatus, val)`, with convenience macros `_di()` (disable interrupts) and `_ei()` (enable interrupts).
+
+### Saving and Restoring `mstatus`
+
+1. Saving in `setjmp`: The `setjmp` function reads `mstatus` using the `csrr` instruction. Since `mstatus.MIE` is cleared during a trap, the previous interrupt state is reconstructed from `MPIE` by shifting bit 7 to bit 3, clearing the original `MIE`, and restoring it, then storing the result in `jmp_buf` at `CONTEXT_MSTATUS` (18). This ensures accurate interrupt context preservation, preventing issues from incorrect handling.
+
+2. Restoring in `longjmp`: The `longjmp` function loads `mstatus` from `jmp_buf` and writes it back with `csrw` before other registers, ensuring early interrupt state establishment. This prevents premature interrupt handling and maintains consistency.
+
+3. Timing and drift considerations: Incorrect `mstatus` restoration can disrupt scheduling by enabling interrupts at the wrong time, resolvable through testing with scheduler-stressing applications like message queues. Timer interrupt drift, if not handled carefully, is addressed by `do_trap` scheduling relative to the previous `mtimecmp` value, requiring `mstatus.MIE` to be enabled for effective reception.
+
+### Best Practices for Machine Status
+
+- Prioritize `mstatus` restoration: Restore `mstatus` before other registers in `longjmp` to establish the correct interrupt state early.
+
+- Use safe CSR access: Use `read_csr` and `write_csr` macros in [arch/riscv/hal.h](../arch/riscv/hal.h) for consistent CSR manipulation.
+
+- Initialize `mstatus` for new tasks: Set `MSTATUS_MIE` and `MSTATUS_MPP_MACH` in `hal_context_init` to ensure new tasks start with interrupts enabled.

Makefile

@@ -0,0 +1,115 @@
+ARCH := riscv
+
+# in-tree build
+SRC_DIR := .
+
+# Build directories
+BUILD_DIR := $(SRC_DIR)/build
+BUILD_APP_DIR := $(BUILD_DIR)/app
+BUILD_KERNEL_DIR := $(BUILD_DIR)/kernel
+BUILD_LIB_DIR := $(BUILD_DIR)/lib
+
+include mk/common.mk
+# architecture-specific settings
+include arch/$(ARCH)/build.mk
+
+# Include directories
+INC_DIRS += -I $(SRC_DIR)/include \
+            -I $(SRC_DIR)/include/lib
+
+KERNEL_OBJS := timer.o mqueue.o pipe.o semaphore.o mutex.o error.o syscall.o task.o main.o
+KERNEL_OBJS := $(addprefix $(BUILD_KERNEL_DIR)/,$(KERNEL_OBJS))
+deps += $(KERNEL_OBJS:%.o=%.o.d)
+
+LIB_OBJS := stdio.o libc.o malloc.o queue.o
+LIB_OBJS := $(addprefix $(BUILD_LIB_DIR)/,$(LIB_OBJS))
+deps += $(LIB_OBJS:%.o=%.o.d)
+
+# Applications
+APPS := coop echo hello mqueues semaphore mutex cond \
+        pipes pipes_small pipes_struct prodcons progress \
+        rtsched suspend test64 timer timer_kill \
+        cpubench
+
+# Output files for __link target
+IMAGE_BASE := $(BUILD_DIR)/image
+IMAGE_FILES := $(IMAGE_BASE).elf $(IMAGE_BASE).map $(IMAGE_BASE).lst \
+               $(IMAGE_BASE).sec $(IMAGE_BASE).cnt $(IMAGE_BASE).bin \
+               $(IMAGE_BASE).hex $(BUILD_DIR)/code.txt
+
+# Default target
+.DEFAULT_GOAL := linmo
+
+# Phony targets
+.PHONY: linmo rebuild clean distclean
+
+# Create build directories
+$(BUILD_DIR):
+	$(Q)mkdir -p $(BUILD_APP_DIR) $(BUILD_KERNEL_DIR) $(BUILD_LIB_DIR)
+
+# Pattern rules for object files
+$(BUILD_DIR)/%.o: %.c | $(BUILD_DIR)
+	$(VECHO) "  CC\t$@\n"
+	$(Q)$(CC) $(CFLAGS) -c -MMD -MF $@.d -o $@ $<
+
+# Main library target
+linmo: $(BUILD_DIR)/liblinmo.a
+
+$(BUILD_DIR)/liblinmo.a: $(HAL_OBJS) $(KERNEL_OBJS) $(LIB_OBJS)
+	$(VECHO) "  AR\t$@\n"
+	$(Q)$(AR) $(ARFLAGS) $@ $^
+
+# Application pattern rule
+$(APPS): %: rebuild $(BUILD_APP_DIR)/%.o linmo
+	$(Q)$(MAKE) --no-print-directory __link
+
+# Link target - creates all output files
+__link: $(IMAGE_FILES)
+
+$(IMAGE_BASE).elf: $(BUILD_APP_DIR)/*.o $(BUILD_DIR)/liblinmo.a
+	$(VECHO) "  LD\t$@\n"
+	$(Q)$(LD) $(LDFLAGS) -T$(LDSCRIPT) -Map $(IMAGE_BASE).map -o $@ $(BUILD_APP_DIR)/*.o -L$(BUILD_DIR) -llinmo
+
+$(IMAGE_BASE).lst: $(IMAGE_BASE).elf
+	$(VECHO) "  DUMP\t$@\n"
+	$(Q)$(DUMP) --disassemble --reloc $< > $@
+
+$(IMAGE_BASE).sec: $(IMAGE_BASE).elf
+	$(VECHO) "  DUMP\t$@\n"
+	$(Q)$(DUMP) -h $< > $@
+
+$(IMAGE_BASE).cnt: $(IMAGE_BASE).elf
+	$(VECHO) "  DUMP\t$@\n"
+	$(Q)$(DUMP) -s $< > $@
+
+$(IMAGE_BASE).bin: $(IMAGE_BASE).elf
+	$(VECHO) "  COPY\t$@\n"
+	$(Q)$(OBJ) -O binary $< $@
+
+$(IMAGE_BASE).hex: $(IMAGE_BASE).elf
+	$(VECHO) "  COPY\t$@\n"
+	$(Q)$(OBJ) -R .eeprom -O ihex $< $@
+
+$(BUILD_DIR)/code.txt: $(IMAGE_BASE).bin
+	$(VECHO) "  DUMP\t$@\n"
+	$(Q)hexdump -v -e '4/1 "%02x" "\n"' $< > $@
+	@$(SIZE) $(IMAGE_BASE).elf
+
+# Utility targets
+rebuild:
+	$(Q)find '$(BUILD_APP_DIR)' -type f -name '*.o' -delete 2>/dev/null || true
+	$(Q)mkdir -p $(BUILD_APP_DIR)
+
+clean:
+	$(VECHO) "Cleaning build artifacts...\n"
+	$(Q)find '$(BUILD_APP_DIR)' '$(BUILD_KERNEL_DIR)' -type f -name '*.o' -delete 2>/dev/null || true
+	$(Q)find '$(BUILD_DIR)' -type f \( -name '*.o' -o -name '*~' -o -name 'image.*' -o -name 'code.*' \) -delete 2>/dev/null || true
+	$(Q)find '$(SRC_DIR)' -maxdepth 1 -type f -name '*.o' -delete 2>/dev/null || true
+	@$(RM) $(deps)
+
+distclean: clean
+	$(VECHO) "Deep cleaning...\n"
+	$(Q)find '$(BUILD_DIR)' -type f -name '*.a' -delete 2>/dev/null || true
+	$(Q)rm -rf '$(BUILD_DIR)' 2>/dev/null || true
+
+-include $(deps)

README.md

@@ -0,0 +1,148 @@
+# Linmo: A Simple Multi-tasking Operating System Kernel
+```
+      ▅▅▅▅▅▅▅▅▅▅▅▅▅▅▅▖
+      ▐██████████████
+      ▐█████▜▆▆▛█████
+    ▗███▉▜██▟▀▀▙██▇███▆▖
+   ▗█████▜██▅▅▅▅██▀████▉
+   ▕███▙▇███▛▘▝████▆███▛     ▝▇▇▇▘    ▝▇▇▛▘▝▇▇▄  ▝▇▛▘     ▇▇▙    ▇▇▀  ▗▅▇▀▀▇▅▖
+    ▝████▛▀▔    ▔▀▜███▉       ▐█▋      ██▍  ▐██▙▖ ▐▌      ▐██▖  ▟██▎ ▗█▛    ██▖
+    █▔█▍▝▀▀▀╸  ━▀▀▀ █▛▜▋      ▐█▋      ██▍  ▐▋▝▜█▃▐▌      █▎▜█▖▐▛▐█▌ ██▌    ▐█▋
+    ▜▖▜▌╺▄▃▄╸ ┓╺▄▄━ █▋▟▍      ▐█▋   ▅▏ ██▍  ▐▋  ▜██▌      █▏ ███ ▐█▋ ▐█▙    ▟█▘
+    ▐▛▀▊      ▝    ▕█▀█      ▗▟██▅▅▇▛ ▅██▙▖▗▟█▖  ▝█▌     ▅█▅ ▝█▘╶▟██▖ ▝▜▇▅▄▇▀▘
+    ▝▙▅█▖   ▀━┷▘   ▟█▅▛
+    ▗██▌█▖ ╺━▇▇━  ▄▊▜█▉                 ▆▍                       ▕▆
+   ▗██▛▗█▛▅▂▝▀▀▁▃▇██▝██▙                █▍▅▛ ▗▆▀▜▅ ▇▆▀▕▇┻▀▆ ▗▇▀▇▖▕█
+  ▄███▇██▎ ▀▀▀▀▀▔ ▐█████▙▁              █▛▜▄ ▜█▀▜▉ █▎ ▕█▏ █▎▜▛▀▜▉▕█
+  ▀▀▔▔▜▄▀▜▅▄▂▁▁▃▄▆▀▚▟▀▔▀▀▘              ▀▘ ▀▘ ▀▀▀▔ ▀   ▀  ▀  ▀▀▀▔ ▀
+       ▝▀▆▄▃████▃▄▆▀▔
+```
+
+Linmo is a preemptive, multi-tasking operating system kernel built as an educational showcase for resource-constrained systems.
+It offers a lightweight environment where all tasks share a single address space,
+keeping the memory footprint to a minimum.
+
+Target Platform:
+* RISC-V (32-bit): RV32I architecture, tested with QEMU.
+
+Features:
+* Minimal kernel size.
+* Lightweight task model with a shared address space.
+* Preemptive and cooperative scheduling using a priority-based round-robin algorithm.
+* Support for a user-defined real-time scheduler.
+* Task synchronization and IPC primitives: semaphores, mutex / condition variable, pipes, and message queues.
+* Software timers with callback functionality.
+* Dynamic memory allocation.
+* A compact C library.
+
+## Getting Started
+This section guides you through building the Linmo kernel and running example applications.
+
+### Prerequisites
+* A RISC-V cross-compilation toolchain: `riscv-none-elf`, which can be download via [riscv-gnu-toolchain](https://github.com/riscv-collab/riscv-gnu-toolchain).
+* The QEMU emulator for RISC-V: `qemu-system-riscv32`.
+
+### Building the Kernel
+To build the kernel, run the following command:
+
+```bash
+make
+```
+
+This command compiles the kernel into a static library (`liblinmo.a`) located in the `build/target` directory.
+This library can then be linked against user applications.
+
+### Building and Running an Application
+To build and run an application (e.g., the `hello` example) on QEMU for 32-bit RISC-V:
+1.  Build the application:
+    ```bash
+    make hello
+    ```
+2.  Run the application in QEMU:
+    ```bash
+    make run
+    ```
+    To exit QEMU, press `Ctrl+a` then `x`.
+
+## Core Concepts
+
+### Tasks
+Tasks are the fundamental units of execution in Linmo.
+Each task is a function that typically runs in an infinite loop.
+All tasks operate within a shared memory space.
+At startup, the kernel initializes all registered tasks and allocates a dedicated stack for each.
+
+### Memory Management
+
+#### Stack Allocation
+Each task is allocated a dedicated stack from the system heap.
+The heap is a shared memory region managed by Linmo's dynamic memory allocator and is available to both the kernel and the application.
+
+A task's stack stores local variables, function call frames, and the CPU context during interrupts or context switches.
+The stack size is configurable per-task and must be specified upon task creation.
+Each target architecture defines a default stack size through the `DEFAULT_STACK_SIZE` macro in its HAL.
+It is crucial to tune the stack size for each task based on its memory requirements.
+
+#### Dynamic Memory Allocation
+Linmo provides standard dynamic memory allocation functions (`malloc`, `calloc`, `realloc`, `free`) for both the kernel and applications.
+
+### Scheduling
+Linmo supports both cooperative and preemptive multitasking.
+The scheduling mode is determined by the return value of the `app_main()` function at startup:
+* Cooperative Scheduling (return value `0`): Tasks retain control of the CPU until they explicitly yield it by calling `mo_task_yield()`.
+  This mode gives the developer full control over when a context switch occurs.
+* Preemptive Scheduling (return value `1`): The kernel automatically schedules tasks based on a periodic interrupt,
+  ensuring that each task gets a fair share of CPU time without needing to yield manually.
+
+The default scheduler uses a priority-based round-robin algorithm.
+All tasks are initially assigned `TASK_PRIO_NORMAL`, and the scheduler allocates equal time slices to tasks of the same priority.
+Task priorities can be set during initialization in `app_main()` or dynamically at runtime using the `mo_task_priority()` function.
+
+The available priority levels are:
+* `TASK_PRIO_CRIT` (Critical)
+* `TASK_PRIO_REALTIME` (Real-time)
+* `TASK_PRIO_HIGH` (High)
+* `TASK_PRIO_ABOVE` (Above Normal)
+* `TASK_PRIO_NORMAL` (Normal)
+* `TASK_BELOW_PRIO` (Below Normal)
+* `TASK_PRIO_LOW` (Low)
+* `TASK_PRIO_IDLE` (Lowest)
+
+For more advanced scheduling needs, Linmo supports a user-defined real-time scheduler.
+If provided, this scheduler overrides the default round-robin policy for tasks designated as real-time.
+Real-time tasks are configured using the `mo_task_rt_priority()` function and linked to the custom scheduler via the kernel's control block.
+
+### Inter-Task Communication (IPC)
+Linmo provides several primitives for task synchronization and data exchange, which are essential for building complex embedded applications:
+* Semaphores: Counting semaphores for mutual exclusion (mutex) and signaling between tasks.
+* Pipes: Unidirectional, byte-oriented channels for streaming data between tasks.
+* Message Queues and Event Queues: For structured message passing and event-based signaling (can be enabled in the configuration).
+
+These IPC mechanisms ensure safe and coordinated interactions between concurrent tasks in the shared memory environment.
+
+## Hardware Abstraction Layer (HAL)
+Linmo uses a Hardware Abstraction Layer (HAL) to separate the portable kernel code from the underlying hardware-specific details.
+This design allows applications to be compiled for different target architectures without modification.
+
+## C Library Support (LibC)
+Linmo includes a minimal C library to reduce the overall footprint of the system.
+The provided functions are implemented as macros that alias internal library functions.
+For applications requiring more features or full standard compliance, these macros can be overridden or removed in the HAL to link against an external C library.
+
+Functions like `printf()` are simplified implementations that provide only essential functionality, optimized for code size.
+
+The following table lists the supported C library functions:
+
+| LibC         |             |             |             |             |
+| :----------- | :---------- | :---------- | :---------- | :---------- |
+| `strcpy()`   | `strncpy()` | `strcat()`  | `strncat()` | `strcmp()`  |
+| `strncmp()`  | `strstr()`  | `strlen()`  | `strchr()`  | `strpbrk()` |
+| `strsep()`   | `strtok()`  | `strtok_r()`| `strtol()`  | `atoi()`    |
+| `itoa()`     | `memcpy()`  | `memmove()` | `memcmp()`  | `memset()`  |
+| `random_r()` | `random()`  | `srand()`   | `puts()`    | `gets()`    |
+| `fgets()`    | `getline()` | `printf()`  | `sprintf()` | `free()`    |
+| `malloc()`   | `calloc()`  | `realloc()` | `abs()`     |             |
+
+## Reference
+* [Operating System in 1000 Lines](https://operating-system-in-1000-lines.vercel.app/en/)
+* [egos-2000](https://github.com/yhzhang0128/egos-2000)