Python Support Implementation Plan for MayteraOS

Version: 1.0 Date: January 2026 Status: Planning

Executive Summary

This document outlines a comprehensive plan for implementing Python support in MayteraOS. After analyzing the kernel's capabilities and researching available options, we recommend porting MicroPython as the most practical approach. This document covers options analysis, requirements, implementation phases, challenges, and complexity estimates.

Table of Contents

1. Options Analysis
2. Requirements Assessment
3. Implementation Phases
4. Challenges and Mitigations
5. Estimated Complexity
6. Appendix: MayteraOS Kernel Capabilities

1. Options Analysis

Option A: Port MicroPython (RECOMMENDED)

Description: MicroPython is a lean and efficient implementation of Python 3 designed specifically for microcontrollers and constrained systems. It includes a Python compiler to bytecode and a runtime interpreter.

Minimum Requirements:

• 256KB code space
• 16KB RAM (minimal), 128KB RAM (full-featured)
• C99 compiler

Advantages:

• Purpose-built for embedded/constrained environments
• No external dependencies for core VM
• Modular architecture - features can be enabled/disabled
• Well-documented porting guide
• Active community and maintenance
• Provides "minimal" and "bare-arm" reference ports
• Supports setjmp/longjmp for exception handling (no assembly required)
• Python 3.4+ syntax support including async/await

Disadvantages:

• Limited standard library compared to CPython
• Some CPython libraries not compatible
• Performance lower than native code (but offers Viper compiler for near-C speed)

Assessment: MicroPython is the ideal choice for MayteraOS. Its minimal footprint, embedded focus, and lack of external dependencies align perfectly with our kernel's architecture.

Option B: Port CPython

Description: CPython is the reference implementation of Python, providing the full Python language and standard library.

Minimum Requirements:

• 4-8MB code space (full installation ~100MB+)
• 32MB+ RAM minimum
• POSIX-compatible libc
• Dynamic linking support
• Full file system with /usr/lib/python* hierarchy

Advantages:

• Full Python compatibility
• Complete standard library
• All third-party packages work

Disadvantages:

• Massive code size (~25MB for interpreter alone)
• Heavy memory requirements
• Requires extensive POSIX compatibility layer
• Needs dynamic linking (dlopen, dlsym)
• Complex build system (autoconf, Make, Python bootstrap)
• Threading model requires pthreads
• Not designed for bare-metal environments

Assessment: Not feasible for MayteraOS in the near term. Would require implementing a POSIX compatibility layer, dynamic linker, and significant infrastructure that doesn't exist in the current kernel.

Option C: Custom Minimal Interpreter

Description: Build a custom Python-like interpreter from scratch, implementing only essential features.

Potential Implementation Approaches:

1. Subset interpreter (Python-like syntax, limited features)
2. Bytecode interpreter only (pre-compile on host)
3. REPL-only with minimal built-ins

Advantages:

• Full control over implementation
• Can be optimized specifically for MayteraOS
• No external code dependencies
• Minimal footprint possible

Disadvantages:

• Massive development effort (person-years of work)
• No existing ecosystem compatibility
• Must implement lexer, parser, AST, bytecode compiler, VM
• Documentation and maintenance burden
• Likely to have bugs/incompatibilities

Assessment: Not recommended. The development effort would be enormous, and MicroPython already provides a battle-tested solution with similar goals.

Recommendation: Option A - MicroPython

Justification:

MicroPython is specifically designed for exactly our use case: a custom OS with limited resources and no POSIX layer. The porting guide provides clear steps, and reference implementations (bare-arm, minimal) serve as templates.

2. Requirements Assessment

2.1 Kernel Features Required

Memory Management

Status: FULLY AVAILABLE

File I/O

Status: READ OPERATIONS COMPLETE, WRITE OPERATIONS NEED IMPLEMENTATION

Console/Terminal I/O

Status: FULLY AVAILABLE

Standard Library Functions

Status: FULLY AVAILABLE (but will need expansion)

Time Keeping

Status: AVAILABLE (may need wrapper functions)

Exception Handling

Status: NEEDS IMPLEMENTATION (setjmp/longjmp functions)

2.2 Features to be Added

Priority 1: Essential for MicroPython Port

1. setjmp/longjmp Implementation

• Required for MicroPython's NLR (non-local return) exception handling
• Can use C implementation or assembly for x86_64
• Estimated effort: 1-2 days

1. Standard Math Functions

• Basic: abs, div, ldiv
• Floating point: sin, cos, sqrt, pow, log, exp (if float support enabled)
• Estimated effort: 3-5 days (can use software implementations)

1. Time Functions Wrapper

• mp_hal_ticks_ms() - milliseconds since boot
• mp_hal_ticks_us() - microseconds since boot
• mp_hal_delay_ms() - delay function
• Estimated effort: 1 day

Priority 2: Standard Library Support

1. String Formatting Enhancements

• snprintf(), vsnprintf()
• Floating-point formatting (if enabled)
• Estimated effort: 2-3 days

1. Extended Memory Functions

• calloc() - already have kzalloc, need wrapper
• Memory statistics for GC tuning
• Estimated effort: 1 day

Priority 3: Full-Featured Port

1. File System Write Operations

• fat_create(), fat_write(), fat_delete()
• Required for saving .py files, persistent storage
• Estimated effort: 5-7 days

1. Random Number Generator

• Required for random module
• Can use RDRAND instruction on x86_64
• Estimated effort: 1 day

3. Implementation Phases

Phase 1: Core Interpreter (Weeks 1-4)

Goal: Get MicroPython REPL running with basic Python operations

Week 1: Infrastructure Setup

• [ ] Create kernel/python/ directory structure
• [ ] Download MicroPython source (v1.22 or latest stable)
• [ ] Create mpconfigport.h with minimal feature set
• [ ] Create mphalport.h with MayteraOS-specific HAL functions
• [ ] Set up Makefile integration with kernel build

Deliverables:

• Build system configured
• MicroPython source integrated into kernel tree

Week 2: HAL Implementation

• [ ] Implement setjmp/longjmp for x86_64
• [ ] Implement mp_hal_stdin_rx_chr() using keyboard driver
• [ ] Implement mp_hal_stdout_tx_strn() using console/serial
• [ ] Implement time functions (ticks_ms, ticks_us, delay_ms)
• [ ] Implement gc_collect() stack scanning

Deliverables:

• Basic I/O working
• Time functions operational
• GC can run

Week 3: Memory and Core VM

• [ ] Configure GC heap (start with 256KB allocation)
• [ ] Implement memory allocation wrappers
• [ ] Disable file system imports initially (MICROPY_READER_POSIX = 0)
• [ ] Disable floating point initially (MICROPY_FLOAT_IMPL = NONE)
• [ ] Build and test core VM initialization

Deliverables:

• MicroPython VM initializes successfully
• Basic memory management working

Week 4: REPL Integration

• [ ] Create Python shell application (gui/python.c)
• [ ] Integrate REPL into kernel shell (via python command)
• [ ] Test basic operations: arithmetic, strings, lists
• [ ] Test function definitions and calls
• [ ] Test class definitions and instances

Deliverables:

• Working Python REPL in MayteraOS
• Basic Python programs execute correctly

Phase 1 Configuration (mpconfigport.h):

// Minimal MicroPython configuration for MayteraOS
#define MICROPY_CONFIG_ROM_LEVEL        (MICROPY_CONFIG_ROM_LEVEL_MINIMUM)
#define MICROPY_ENABLE_GC               (1)
#define MICROPY_HELPER_REPL             (1)
#define MICROPY_ERROR_REPORTING         (MICROPY_ERROR_REPORTING_TERSE)
#define MICROPY_FLOAT_IMPL              (MICROPY_FLOAT_IMPL_NONE)
#define MICROPY_LONGINT_IMPL            (MICROPY_LONGINT_IMPL_LONGLONG)
#define MICROPY_ENABLE_SOURCE_LINE      (0)
#define MICROPY_STREAMS                 (0)
#define MICROPY_READER_POSIX            (0)
#define MICROPY_PY_BUILTINS_BYTEARRAY   (1)
#define MICROPY_PY_BUILTINS_DICT_FROMKEYS (0)
#define MICROPY_PY_BUILTINS_SET         (0)
#define MICROPY_PY_SYS                  (0)
#define MICROPY_PY_IO                   (0)

Estimated Complexity: Medium Estimated Effort: 80-120 hours

Phase 2: Standard Library Subset (Weeks 5-8)

Goal: Enable essential Python modules for practical programming

Week 5: Math and Core Modules

• [ ] Enable floating-point support (software float)
• [ ] Implement/port math functions (sin, cos, sqrt, etc.)
• [ ] Enable math module
• [ ] Enable sys module (partial)
• [ ] Enable collections module

Deliverables:

• Floating-point arithmetic working
• Math operations available

Week 6: Data Structures

• [ ] Enable array module
• [ ] Enable struct module
• [ ] Enable json module (parser only initially)
• [ ] Enable re module (basic regex)

Deliverables:

• Binary data manipulation working
• JSON parsing available

Week 7: File System Integration

• [ ] Implement mp_import_stat() using FAT driver
• [ ] Implement mp_lexer_new_from_file()
• [ ] Enable importing .py files from disk
• [ ] Test import statement with local modules

Deliverables:

• Can import Python files from FAT filesystem
• Module loading functional

Week 8: Time and OS Basics

• [ ] Enable time module
• [ ] Implement time.sleep(), time.ticks_ms()
• [ ] Create basic maytera module (OS-specific)
• [ ] Add version info, system info functions

Deliverables:

• Time operations available
• MayteraOS-specific module started

Phase 2 Additional Configuration:

// Phase 2 additions to mpconfigport.h
#define MICROPY_FLOAT_IMPL              (MICROPY_FLOAT_IMPL_DOUBLE)
#define MICROPY_PY_MATH                 (1)
#define MICROPY_PY_CMATH                (0)
#define MICROPY_PY_SYS                  (1)
#define MICROPY_PY_SYS_EXIT             (1)
#define MICROPY_PY_COLLECTIONS          (1)
#define MICROPY_PY_ARRAY                (1)
#define MICROPY_PY_STRUCT               (1)
#define MICROPY_PY_JSON                 (1)
#define MICROPY_PY_RE                   (1)
#define MICROPY_PY_TIME                 (1)
#define MICROPY_PY_TIME_GMTIME          (0)
#define MICROPY_READER_VFS              (1)
#define MICROPY_VFS                     (1)
#define MICROPY_VFS_FAT                 (1)

Estimated Complexity: Medium-High Estimated Effort: 120-160 hours

Phase 3: MayteraOS-Specific Modules (Weeks 9-16)

Goal: Expose MayteraOS features to Python programs

Weeks 9-10: GUI Module (maytera.gui)

Functions to implement:

# maytera.gui module API
import maytera.gui as gui

# Window management
win = gui.create_window("My App", x=100, y=100, width=400, height=300)
win.show()
win.hide()
win.close()
win.title = "New Title"

# Drawing primitives
win.fill_rect(x, y, width, height, color)
win.draw_rect(x, y, width, height, color)
win.draw_line(x1, y1, x2, y2, color)
win.draw_text(x, y, "Hello", color)

# Widgets
button = gui.Button(win, x, y, width, height, "Click Me")
button.on_click = my_callback
label = gui.Label(win, x, y, "Status:")
textbox = gui.TextBox(win, x, y, width, height)

# Events
event = gui.poll_event()
if event.type == gui.EVENT_CLICK:
    handle_click(event)

Implementation approach:

• Create C module: python/modgui.c
• Wrap existing window.c functions
• Create Python object types for Window, Widget
• Use callbacks for event handling

Weeks 11-12: Networking Module (maytera.net)

Functions to implement:

# maytera.net module API
import maytera.net as net

# Network status
info = net.status()  # Returns dict with IP, MAC, gateway, etc.
net.configure(ip="198.51.100.20", gateway="198.51.100.1", netmask="255.255.255.0")

# ICMP
result = net.ping("198.51.100.1", count=4, timeout=1000)

# UDP (if available)
sock = net.UDPSocket()
sock.bind(port=5000)
sock.sendto(data, ("198.51.100.1", 5000))
data, addr = sock.recvfrom()

# DNS (future)
ip = net.resolve("example.com")

Implementation approach:

• Create C module: python/modnet.c
• Wrap net/net.c, net/udp.c, net/icmp.c functions
• Implement basic socket-like API

Weeks 13-14: System Module (maytera.sys)

Functions to implement:

# maytera.sys module API
import maytera.sys as sys

# Memory info
mem = sys.memory()  # {"total": 1024*1024*1024, "used": ..., "free": ...}

# Process info
procs = sys.processes()  # List of process info dicts

# Hardware info
info = sys.hardware()  # CPU, etc.

# Power management
sys.reboot()
sys.shutdown()

# File system
fs = sys.filesystem()  # FAT info

Weeks 15-16: File I/O Module (maytera.fs)

Functions to implement:

# maytera.fs module API
import maytera.fs as fs

# Directory operations
contents = fs.listdir("/")
fs.mkdir("/mydir")
fs.chdir("/mydir")
cwd = fs.getcwd()

# File operations
data = fs.read_file("/path/to/file.txt")
# fs.write_file("/path/to/file.txt", data)  # When write support added

# File info
exists = fs.exists("/path/to/file")
size = fs.size("/path/to/file")
is_dir = fs.isdir("/path")

Implementation approach:

• Create C module: python/modfs.c
• Wrap FAT filesystem functions
• Provide Pythonic file handling

Phase 3 Module Structure:

kernel/python/
    modules/
        modgui.c          # maytera.gui
        modnet.c          # maytera.net
        modsys.c          # maytera.sys
        modfs.c           # maytera.fs
    mpconfigport.h        # Updated config
    mphalport.c           # HAL implementation
    mphalport.h           # HAL declarations
    qstrdefsport.h        # QSTR definitions for modules

Estimated Complexity: High Estimated Effort: 200-300 hours

4. Challenges and Mitigations

4.1 Memory Constraints

Challenge: MayteraOS heap is capped at 256MB, and MicroPython's GC can be memory-hungry for complex programs.

Mitigations:

• Start with conservative GC heap (256KB-1MB)
• Implement memory limit configuration
• Add GC threshold tuning
• Monitor memory usage during development
• Provide gc.collect() in Python for manual GC

Risk Level: Medium

4.2 No Dynamic Linking

Challenge: MicroPython's native emitter and some advanced features expect dynamic code generation. MayteraOS has no dynamic linker.

Mitigations:

• Disable native emitter (MICROPY_EMIT_NATIVE = 0)
• Disable Viper emitter (MICROPY_EMIT_VIPER = 0)
• Use bytecode interpreter only (still fast enough for most uses)
• If needed later, implement JIT in-memory (requires W^X handling)

Risk Level: Low (bytecode is sufficient)

4.3 Limited libc Equivalent

Challenge: MicroPython expects certain libc functions. MayteraOS has a minimal string.c.

Missing Functions (need implementation):

Mitigations:

• Implement required functions in kernel/stdlib/ directory
• Use MicroPython's built-in fallbacks where available
• Prioritize implementation based on build errors

Risk Level: Medium (well-defined scope)

4.4 File System Write Operations

Challenge: FAT write operations are not implemented, limiting Python's ability to save files.

Mitigations:

• Phase 1-2 work without file writes (REPL-only, import from read-only FS)
• Implement FAT write before Phase 3 file I/O module
• Consider RAM-based "virtual filesystem" for intermediate solution

Risk Level: Medium (deferred to later phase)

4.5 Threading

Challenge: MicroPython supports threading on some platforms. MayteraOS has basic process support but no pthreads.

Mitigations:

• Disable threading (MICROPY_PY_THREAD = 0)
• Use single-threaded model (MicroPython works fine this way)
• Each Python "app" can be separate process if needed

Risk Level: Low

4.6 Floating-Point ABI

Challenge: x86_64 uses SSE for floating-point. Need to ensure FPU state is handled correctly.

Mitigations:

• MayteraOS already runs on x86_64 with UEFI (FPU should be available)
• Test floating-point early in Phase 2
• If issues, use software float (MICROPY_FLOAT_IMPL_FLOAT)

Risk Level: Low

5. Estimated Complexity

Summary by Phase

Detailed Breakdown

Phase 1 Tasks

Phase 2 Tasks

Phase 3 Tasks

Appendix: MayteraOS Kernel Capabilities

Current Kernel Features (v1.0+)

Based on source code analysis of the kernel/ source tree:

Memory Management (mm/)

• PMM (pmm.c): Bitmap-based physical page allocator, supports up to 64GB RAM
• VMM (vmm.c): 4-level paging for x86_64, page mapping/unmapping
• Heap (heap.c): Linked-list allocator with coalescing, 16-byte alignment
• Functions: kmalloc, kfree, krealloc, kzalloc, kmalloc_aligned
• Initial size: 16MB, max: 256MB
• Thread-safe with spinlock

File System (fs/)

• FAT (fat.c): FAT12/FAT16/FAT32 support
• Read operations: complete
• Write operations: stubs only
• Long filename support: partial (LFN entries skipped)

Networking (net/)

• Drivers: E1000 is the network driver actually initialized at boot. A VirtIO-net driver exists in the tree and builds, but has no caller wiring it up, so it is not active on a running system.
• Protocols: Ethernet, ARP, IP, ICMP, UDP, DHCP
• TCP: Implementation exists (tcp.c)

GUI (gui/)

• Window Manager (window.c): Full windowing system
• Widgets (widget.c): Buttons, labels, text fields, etc.
• Applications: Calculator, Editor, Terminal, Settings, File Browser

Process Management (proc/)

• Scheduler: Priority-based preemptive scheduling
• Processes: Creation, termination, yield, sleep
• Max processes: Configurable (MAX_PROCESSES)

Hardware Drivers

• ATA/IDE disk
• PS/2 keyboard and mouse
• PCI enumeration
• Sound (basic)
• ACPI (shutdown/reboot)

Required Additions for Python

References

• MicroPython Official Site
• MicroPython GitHub Repository
• MicroPython Porting Guide
• MicroPython GitHub Discussions - Porting to New Processor
• MicroPython Wiki FAQ

Document History