mielin-kernel

The Myelin Sheath - Core Unikernel (Layer 1)

A lightweight no_std unikernel providing the foundation for autonomous agent execution across heterogeneous hardware platforms—from microcontrollers to cloud servers.

Overview

The MielinOS kernel is a minimalist unikernel designed for extreme efficiency and portability. It eliminates traditional kernel-space/user-space boundaries, operating in a single memory address space to provide essential OS services (memory management, task scheduling, tensor awareness) without the overhead of traditional operating systems.

Current Status: v0.1.0-rc.1 "Oligodendrocyte" (Released 2026-01-18)

Key Features

• no_std Environment: Runs on bare metal without standard library dependencies
• Page-based Memory Management: Efficient 4KB page allocation with bitmap tracking
• Async/Await Cooperative Scheduling: Priority-based scheduler with near-zero context switch overhead
• TensorLogic Integration: Kernel-level awareness of matrix operations for AI workloads
• Minimal Footprint: Target <100KB kernel binary size (currently <10KB for embedded)
• Zero-copy Operations: Direct memory access for maximum performance
• Multi-architecture: Supports Arm (Cortex-A/M), RISC-V, x86_64

Architecture

MielinOS kernel provides Layer 1 of the 5-layer neural architecture:

┌─────────────────────────────────────────────────────────────┐
│ Layer 1: MielinOS Core (The Myelin Sheath)                 │
│          • Memory Manager (Page-based allocator)            │
│          • Task Scheduler (Async cooperative)               │
│          • TensorLogic (AI-aware scheduling)                │
│          • Syscall Interface (Capability-based)             │
└─────────────────────────────────────────────────────────────┘

File Structure

mielin-kernel/
├── src/
│   ├── boot.rs       # Boot sequence initialization
│   ├── memory.rs     # Page-based memory allocator
│   ├── scheduler.rs  # Cooperative task scheduler
│   ├── tensor.rs     # TensorLogic context management
│   └── lib.rs        # Kernel entry points and error types
└── Cargo.toml

Components

Memory Manager

Manages physical memory using a page-based allocation scheme optimized for agent migration.

use mielin_kernel::memory;

// Initialize memory subsystem
memory::init()?;

// Allocate a 4KB page
let page_addr = memory::allocate_page().expect("Out of memory");

// Free the page when done
memory::free_page(page_addr)?;

Characteristics:

• Page size: 4096 bytes (configurable)
• Maximum pages: 1024 (4MB total, expandable)
• Allocation time: O(n) worst case (bitmap scan)
• Deallocation time: O(1) (bitmap clear)
• Safety: All allocations tracked, double-free detected

Task Scheduler

Priority-based cooperative scheduler for concurrent agent execution with async/await support.

use mielin_kernel::scheduler;

// Initialize scheduler
scheduler::init()?;

// Spawn a task with priority 10
let task_id = scheduler::spawn_task(10)?;

// Schedule next task (returns task index)
let next_task = scheduler::schedule();

// Yield current task back to ready queue
scheduler::yield_current();

Characteristics:

• Maximum tasks: 64 (configurable up to 256)
• Priority range: 0-255 (higher = more priority)
• Scheduling: Highest priority first, round-robin within priority
• Context switch: <100 CPU cycles
• Preemption: Cooperative (yielding required)

TensorLogic Context

Kernel-level tensor operation management for AI workloads, enabling intelligent resource allocation.

use mielin_kernel::tensor::TensorContext;

// Create tensor context with memory budget
let ctx = TensorContext::new(1024 * 1024); // 1MB budget

// Context provides:
// - Memory allocation tracking for tensor ops
// - Resource limits enforcement
// - Priority scheduling hints

Features:

• Memory budget tracking
• Operation size estimation
• OOM prevention for large tensors
• Integration with scheduler for AI workload prioritization

Running MielinOS

Prerequisites

Install required tools:

# Install Rust nightly (required for bootimage)
rustup default nightly

# Install bootimage tool
cargo install bootimage

# Install QEMU (for x86_64)
# Ubuntu/Debian:
sudo apt install qemu-system-x86

# macOS:
brew install qemu

# Windows:
# Download from https://www.qemu.org/download/

Building and Running

Quick Start

Run MielinOS in QEMU:

# From project root
./scripts/run-qemu.sh

Or with graphical display:

./scripts/run-qemu-gui.sh

Manual Build

# Build the bootable kernel image
cargo bootimage --target x86_64-unknown-none

# Run in QEMU
qemu-system-x86_64 -drive format=raw,file=target/x86_64-unknown-none/debug/bootimage-mielin-kernel.bin

QEMU Controls

• Exit QEMU: Press Ctrl+A then X (in terminal mode)
• Switch to monitor: Press Ctrl+A then C
• Pause/Resume: Press Ctrl+A then S

Debugging

Run with GDB support:

# Terminal 1: Start QEMU with GDB server
qemu-system-x86_64 \
  -drive format=raw,file=target/x86_64-unknown-none/debug/bootimage-mielin-kernel.bin \
  -s -S

# Terminal 2: Connect GDB
gdb target/x86_64-unknown-none/debug/mielin-kernel
(gdb) target remote :1234
(gdb) continue

View serial output:

qemu-system-x86_64 \
  -drive format=raw,file=target/x86_64-unknown-none/debug/bootimage-mielin-kernel.bin \
  -serial mon:stdio

Usage

As a Dependency

Add to your Cargo.toml:

[dependencies]
mielin-kernel = { path = "../mielin-kernel" }

Creating a Bootable Application

#![no_std]
#![no_main]

use bootloader::{BootInfo, entry_point};
use mielin_kernel;

entry_point!(kernel_main);

fn kernel_main(boot_info: &'static BootInfo) -> ! {
    // Initialize kernel subsystems
    if let Err(e) = mielin_kernel::kernel_init(boot_info) {
        panic!("Kernel init failed: {:?}", e);
    }

    // Your application code here
    loop {
        // Main event loop
        // Agents execute here
    }
}

Configuration

The kernel can be configured at compile time:

// In memory.rs
const PAGE_SIZE: usize = 4096;    // Page size in bytes
const MAX_PAGES: usize = 1024;    // Maximum allocatable pages (4MB)

// In scheduler.rs
const MAX_TASKS: usize = 64;      // Maximum concurrent tasks

Error Handling

All kernel operations return Result<T, KernelError>:

pub enum KernelError {
    MemoryInitFailed,      // Memory subsystem init failed
    SchedulerInitFailed,   // Scheduler init failed
    HardwareNotSupported,  // Unsupported hardware platform
    OutOfMemory,           // No free pages available
    InvalidTask,           // Task ID invalid
}

Testing

Run the comprehensive test suite:

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_memory_allocation

Test Coverage:

• Memory allocation/deallocation
• Task creation and scheduling
• Priority-based scheduling
• Edge cases and error conditions
• TensorContext creation
• Concurrent task execution

Performance

Benchmarks on x86_64 (3.5 GHz):

Target metrics for v1.0:

• Boot time: <50ms (Cortex-A), <100ms (x86_64)
• Memory overhead: <50MB for kernel
• Task switch: <50ns (optimized)

Safety Considerations

The kernel uses unsafe code for:

• Global mutable state (memory manager, scheduler)
• Direct memory access for page management
• Panic handler implementation
• Hardware register access

Safety guarantees:

• All unsafe code is carefully reviewed and documented
• Minimal unsafe blocks (prefer safe abstractions)
• #![allow(static_mut_refs)] used for necessary global state
• Memory safety maintained through Rust's ownership system

Limitations

Current limitations (intentional design choices):

• No dynamic heap allocation: Page-based only (simplicity)
• No preemptive multitasking: Cooperative only (predictability)
• No virtual memory/paging: Physical addressing (performance)
• Single-core only: Multi-core support planned for Phase 2
• No interrupt handling: Cooperative scheduling (embedded-friendly)

These constraints enable:

• Predictable performance
• Small code size
• Easy reasoning about behavior
• Suitable for real-time and embedded systems

Roadmap

Phase 1 (v0.1 "Ranvier") ✅ Complete

• ✅ Basic memory allocator
• ✅ Cooperative scheduler
• ✅ TensorContext foundation
• ✅ Multi-architecture support

Phase 2 (v0.2 "Oligodendrocyte") - Q1-Q2 2026

• Async/await executor integration
• Real QUIC networking stack
• Multi-core support (per-core schedulers)
• Lock-free data structures

Phase 3 (v0.3 "Schwann") - Q2-Q3 2026

• Embedded optimization (<32KB flash)
• Power-aware scheduling
• Interrupt-driven event system

Phase 4 (v1.0 "Saltatory") - Q4 2026

• Production hardening
• Security audit
• TensorLogic full integration
• Memory pool allocator

See TODO.md for detailed roadmap.

Best Practices

1. Initialize Early: Call kernel_init() before any other operations
2. Check Results: Always handle KernelError properly
3. Yield Often: Cooperative scheduling requires explicit yields
4. Minimize State: Keep task state small for fast context switching
5. Profile Memory: Monitor page allocation patterns

Contributing

See CONTRIBUTING.md for guidelines.

Key areas for contribution:

• Lock-free data structures
• Multi-core scheduler design
• Memory allocator optimizations
• Architecture-specific optimizations
• Documentation and examples

Resources

• Main Documentation - Complete technical whitepaper
• TODO & Roadmap - Development plan
• Examples - Reference implementations

Contact

• Repository: https://github.com/cool-japan/mielin
• Issues: https://github.com/cool-japan/mielin/issues
• Email: contact@cooljapan.tech

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

MielinOS Kernel - The myelin sheath that enables saltatory conduction of AI agents across the computational nervous system 🧠⚡

Current Version: v0.1.0-rc.1 "Oligodendrocyte" | Released 2026-01-18