中文 | English

Note

This project is currently under actively developing and improving, some APIs and interfaces may change as the design continues to mature.

About 🚀

• MOS is a Real-Time Operating System (RTOS) project built in C++/Rust, which consists of a preemptive kernel and a command-line shell with other applications (e.g., GuiLite and FatFS).

• Renode is a virtual development tool created by Antmicro for multi-node embedded networks (both wired and wireless) and is intended to enable a scalable workflow for creating effective, tested and secure IoT systems.

Repository 🌏

• mos-core - The Kernel and the Shell, check here.
• mos-stm32 - Running on STM32 series, check here.
• mos-renode - Test on Renode emulation, check here.
• mos-rust - A "Vibe Coding" Chimera, check here.

Start 📦

• Use CMake

  • Install the CMake and the Arm GNU Toolchain
  • Run ./build.sh to call CMake Tools and build the project

• Use EIDE

  • Run git submodule init && git submodule update to pull the submodule core
  • Install EIDE extension and the Arm GNU Toolchain, then open *.code-workspace using VS Code

• Renode Emulation

  • Install the Renode platform, and add renode to the /usr/bin path or environment variables
  • Run Start Debugging or press F5 to start, open a TCP connection on localhost:3333, and observe the serial output

Manual 📚

• 用户手册(中文) | Manual(English) from DeepWiki

Architecture 🔍

.
├── 📁 emulation             // Renode emulation script
├── 📁 vendor                // Vendor HALs
├── 📁 core
│   ├── 📁 external          // External Library
│   ├── 📁 arch              // Architecture-Specific Code
│   │   └── cpu.hpp          // Initialization/Context Switch assembly code
│   │
│   ├── 📁 kernel            // Kernel Layer
│   │   ├── macro.hpp        // Kernel Constants Macro
│   │   ├── type.hpp         // Basic Types
│   │   ├── concepts.hpp     // Type Constraints
│   │   ├── data_type.hpp    // Basic Data Structures
│   │   ├── alloc.hpp        // Memory Management
│   │   ├── global.hpp       // Kernel Global Variables
│   │   ├── printf.h/.c      // Thread-Safe printf
│   │   ├── task.hpp         // Task Management
│   │   ├── sync.hpp         // Synchronization Primitives
│   │   ├── async.hpp        // Asynchronous Stackless Coroutines
│   │   ├── scheduler.hpp    // Scheduler
│   │   ├── ipc.hpp          // Inter-Process Communication
│   │   └── utils.hpp        // Other Utilities
│   │
│   ├── config.h             // System Configuration
│   ├── kernel.hpp           // Kernel Modules
│   └── shell.hpp            // Shell Command Line
│
└── 📁 app                   // User Code
    ├── main.cpp             // Entry Function
    └── test.hpp             // Test Code

Example 🍎

Shell Test

Mutex Test(Priority Ceiling Protocol)

LCD Driver & GUI Demo

Concurrent Task Period & Time Sequence

// MOS Kernel & Shell
#include "mos/kernel.hpp"
#include "mos/shell.hpp"

// HAL and Device 
#include "drivers/stm32f4xx/hal.hpp"
#include "drivers/device/led.hpp"

namespace MOS::User::Global
{
    using namespace HAL::STM32F4xx;
    using namespace Driver::Device;
    using namespace DataType::SyncUartDev_t;

    // Shell I/O UART and Buffer
    auto stdio = SyncUartDev_t<32> {USARTx};

    // LED red, green, blue
    Device::LED_t leds[] = {...};
}

namespace MOS::User::BSP
{
    using namespace Driver;
    using namespace Global;

    void LED_Config()
    {
        for (auto& led: leds) {
            led.init();
        }
    }

    void USART_Config()
    {
        stdio.init(9600-8-1-N)
             .rx_config(PXa)  // RX -> PXa
             .tx_config(PYb)  // TX -> PYb
             .it_enable(RXNE) // Enable RXNE interrupt
             .enable();       // Enable UART
    }
    ...
}

namespace MOS::User::App
{
    // Blinky by Task::delay() -> Thread Model
    void red_blink(Device::LED_t leds[])
    {
        while (true) {
            leds[0].toggle(); // red
            Task::delay(500_ms);
        }
    }

    // Blinky by Async::delay() -> Coroutine Model
    Async::Future_t<void> blue_blink(Device::LED_t leds[])
    {
        while (true) {
            leds[1].toggle(); // blue
            co_await Async::delay(500_ms);
        }
    }
    ...
}

int main()
{
    using namespace MOS;
    using namespace Kernel;
    using namespace User::Global;

    BSP::config(); // Init periphs and clocks

    Task::create( // Create a calendar with RTC
        App::time_init, nullptr, 0, "time/init"
    );

    Task::create( // Create a shell on stdio
        Shell::launch, &stdio.buf, 1, "shell"
    );

    /* User Tasks */
    Task::create(App::red_blink, &leds, 2, "blinky");
    ...

    /* Test examples */
    Test::MutexTest();
    Test::MsgQueueTest();
    Test::AsyncTest();
    ...
    
	// Launch Scheduler, never return
    Scheduler::launch();
}

Boot Up ⚡

 A_A       _   [name]  @ x.x.x(Version)
o'' )_____//   Build   @ TIME, DATE
 `_/  MOS  )   Chip    @ MCU, ARCH
 (_(_/--(_/    2023-2026 Copyright by Eplankton

<Tid> <Name> <Priority> <Status> <Mem%>
---------------------------------------
 #0    idle     15       READY     10%
 #1    shell     1       BLOCKED   21%
 #2    blinky    2       RUNNING    9%
---------------------------------------

Milestone 🧾

📦 v0.5

✅ Done：

• [Experimental] Port to ESP32-C6(RISC-V)
• [Experimental] Rewrite it in Rust

📦 v0.4

✅ Done：

• Add Hardware FPU support
• CMake Tools are now available for compiling the project
• Add external library ETL, a C++ template library for embedded applications
• Add Renode emulation platform, add stable support for Cortex-M series
• [Experimental] Add scheduler lock Scheduler::suspend()
• [Experimental] Add Asynchronous stackless coroutines Async::{Executor, Future_t, co_await/yield/return}

📌 Planned:

• Shift from FatFS to LittleFS

📦 v0.3

✅ Done:

• Mapping Tids to BitMap_t
• Message queue IPC::MsgQueue_t
• Task::create allows generic function signatures as void fn(auto argv) with type checker
• Add ESP32-C3 as a WiFi component
• Add Driver::Device::SD_t, SD card driver, porting FatFs file system
• Add Shell::usr_cmds for user-registered commands
• [Experimental] Atomic types <stdatomic.h>
• [Experimental] Utils::IrqGuard_t, nested interrupt critical sections
• [Experimental] Simple formal verification of Scheduler + Mutex

📌 Planned:

• Inter-Process Communication: pipes/channels
• FPU hardware float support
• Performance benchmarking
• Error handling with Result<T, E>, Option<T>
• DMA_t DMA Driver
• Software/hardware timers Timer
• [Experimental] Adding POSIX support
• [Experimental] More real-time scheduling algorithms

📦 v0.2

✅ Done:

• Synchronization primitives Sync::{Sema_t, Lock_t, Mutex_t<T>, CondVar_t, Barrier_t}
• Scheduler::Policy::PreemptPri with RoundRobin scheduling for same priority levels
• Task::terminate implicitly called upon task exit to reclaim resources
• Simple command-line interaction Shell::{Command, CmdCall, launch}
• HAL::STM32F4xx::SPI_t and Driver::Device::ST7735S_t, porting the GuiLite graphics library
• Blocking delay with Kernel::Global::os_ticks and Task::delay
• Refactored project organization into {kernel, arch, drivers}
• Support for GCC compilation, compatible with STM32Cube HAL
• Real-time calendar HAL::STM32F4xx::RTC_t, CmdCall::date_cmd, App::Calendar
• idle uses Kernel::Global::zombie_list to reclaim inactive pages
• Three basic page allocation policies Page_t::Policy::{POOL, DYNAMIC, STATIC}

📦 v0.1

✅ Done:

• Basic data structures, scheduler, and task control, memory management

📌 Planned:

• Timers, round-robin scheduling
• Inter-Process Communication (IPC), pipes, message queues
• Process synchronization (Sync), semaphores, mutexes
• Design a simple Shell
• Variable page sizes, memory allocator
• SPI driver, porting GuiLite/LVGL graphics libraries
• Porting to other boards/arch, e.g., ESP32-C3 (RISC-V)

References 🛸

• How to build a Real-Time Operating System(RTOS)
• PeriodicScheduler_Semaphore
• STM32F4-LCD_ST7735s
• A printf/sprintf Implementation for Embedded Systems
• GuiLite
• STMViewer
• FatFs
• The Zephyr Project
• Eclipse ThreadX
• Embassy
• Renode
• Embedded Template Library (ETL)

---

I hope the Pacific is as blue as it has been in my dreams. 
I hope.

-- Stephen King's "Rita Hayworth and the Shawshank Redemption", 1982