How hamdannawaz582/picos works
Project Type and Purpose
• PicOS is a monolithic, microcontroller-based OS targeting the RP2040 (Raspberry Pi Pico).
• It provides basic kernel services (task scheduler, inter-task queues, exceptions, syscalls) and a filesystem (via littlefs).
• The ProjectTemplate folder shows how user applications are built on top of this kernel.
File Structure
• Top-level build files:
– CMakeLists.txt (primary build orchestrator)
– .gitmodules (pulls in external/littlefs)
• Kernel source:
– OS.c, defs.h, elf.h, proc.h, scheduler.h, queues.h, ksvc.h
– exceptions.S, exceptions.h (interrupt and fault handlers)
– SVC.h (supervisor call interface)
• External components:
– external/littlefs (filesystem library)
– pico_sdk_import.cmake (hooks the Pico SDK)
• ProjectTemplate:
– linkerscript.ld (memory layout for RP2040)
– main.c (example user application)
– SVC.h (user-side syscall stubs)
– Makefile (alternate build demo)
README for Architecture Clues
• Heavily relies on the Pico SDK (hardware abstraction layer for GPIO, UART, flash).
• Plans to replace the Pico SDK with a custom cross-compiler toolchain in the future.
• External littlefs integration provides block-device-backed storage.
Main Components
a. Hardware Layer
– RP2040 dual-core MCU, on-chip flash and RAM, peripherals (GPIO/UART/Timer).
b. Board Support Package (Pico SDK)
– Low-level drivers and runtime, imported via pico_sdk_import.cmake.
c. Kernel Core
– Startup/Reset (reset handler in exceptions.S)
– Exception vectors and IRQ handling (exceptions.S/.h)
– Supervisor Call (SVC) interface (SVC.h, ksvc.h)
– Task Management & Scheduling (proc.h, scheduler.h)
– IPC: queues and signals (queues.h)
– System call dispatcher (ksvc.c / OS.c)
d. Filesystem Service
– littlefs module under external/littlefs
– FS API wrappers in fs.h
e. User Application Layer
– ProjectTemplate/main.c (initial user code linked via linkerscript.ld)
f. Build System
– CMakeLists.txt driving compilation & linking
– ProjectTemplate/Makefile (alternative demo)
– Linker script for memory layout (linkerscript.ld)
Relationships & Data Flows
• On power-up, the reset vector (exceptions.S) initializes hardware via Pico SDK, then jumps to OS init (OS.c).
• Kernel initializes scheduler and queue structures.
• ProjectTemplate user task calls library functions → SVC triggers a trap → SVC handler dispatches into kernel syscall.
• Scheduler selects next runnable task, context switch via exceptions.S assembly stubs.
• File read/write calls in user code → FS API → littlefs functions → block reads/writes via Pico SDK flash driver.
• Build system invokes CMake → compiles C, assembly and links with linkerscript.ld into a .uf2 image for flashing.
Architectural Patterns & Principles
• Monolithic kernel with clear separation between user tasks and privileged services via SVC.
• Event-driven interrupt handling (exceptions/IRQ).
• Cooperative/preemptive scheduling (as implemented in scheduler.c).
• Modular external component (littlefs) integrated under external/ for filesystem support.