pyOS-kernel 0.2.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

pyos/__init__.py

@@ -1,22 +1,50 @@
 """
-pyOS - Build Operating Systems with Python
+pyOS - Build real operating systems with a Python DSL
 """
 
-from .kernel import Kernel
-from .drivers.screen import Screen
-from .drivers.keyboard import Keyboard
-from .memory.manager import Memory
-from .memory.gdt import GDT
-from .interrupts.handler import Interrupts
-from .syscalls.handler import SysCall
+from .api import (
+    GDT,
+    Architecture,
+    BuildTimeOnlyError,
+    COLOR_NAMES,
+    CapabilityError,
+    Color,
+    InterruptType,
+    Interrupts,
+    Kernel,
+    KernelConfig,
+    KeyCode,
+    KeyEvent,
+    Keyboard,
+    Memory,
+    Screen,
+    SysCall,
+    SysCallNumber,
+    UnsupportedOpError,
+)
+from .api.fs import File
+from .api.process import Process
 
-__version__ = "0.2.0"
+__version__ = "1.0.0"
 __all__ = [
+    "Architecture",
+    "BuildTimeOnlyError",
+    "COLOR_NAMES",
+    "CapabilityError",
+    "Color",
+    "File",
+    "GDT",
+    "InterruptType",
+    "Interrupts",
     "Kernel",
-    "Screen", 
+    "KernelConfig",
+    "KeyCode",
+    "KeyEvent",
     "Keyboard",
     "Memory",
-    "GDT",
-    "Interrupts",
+    "Process",
+    "Screen",
     "SysCall",
+    "SysCallNumber",
+    "UnsupportedOpError",
 ]

pyos/api/__init__.py

@@ -0,0 +1,38 @@
+"""Public Python DSL for building pyOS kernels."""
+
+from .errors import BuildTimeOnlyError, CapabilityError, UnsupportedOpError
+from .gdt import GDT, GDTEntry, PrivilegeLevel, SegmentType
+from .interrupts import InterruptFrame, InterruptType, Interrupts
+from .kernel import Architecture, Kernel, KernelConfig
+from .keyboard import KeyCode, KeyEvent, Keyboard
+from .memory import Memory, MemoryBlock, MemoryRegion
+from .screen import COLOR_NAMES, Color, Screen
+from .syscalls import SysCall, SysCallContext, SysCallNumber
+
+__all__ = [
+    "Architecture",
+    "BuildTimeOnlyError",
+    "COLOR_NAMES",
+    "CapabilityError",
+    "Color",
+    "GDT",
+    "GDTEntry",
+    "InterruptFrame",
+    "InterruptType",
+    "Interrupts",
+    "Kernel",
+    "KernelConfig",
+    "KeyCode",
+    "KeyEvent",
+    "Keyboard",
+    "Memory",
+    "MemoryBlock",
+    "MemoryRegion",
+    "PrivilegeLevel",
+    "Screen",
+    "SegmentType",
+    "SysCall",
+    "SysCallContext",
+    "SysCallNumber",
+    "UnsupportedOpError",
+]

pyos/api/errors.py

@@ -0,0 +1,35 @@
+"""Honest API errors for pyOS — no silent stubs."""
+
+
+class CapabilityError(Exception):
+    """Raised when a Python API feature is not available in the current kernel."""
+
+    def __init__(self, capability: str, hint: str = ""):
+        self.capability = capability
+        msg = f"Capability '{capability}' is not available in this pyOS build."
+        if hint:
+            msg = f"{msg}\n  Hint: {hint}"
+        super().__init__(msg)
+
+
+class BuildTimeOnlyError(Exception):
+    """Raised when runtime Python logic is expected but only build-time recording exists."""
+
+    def __init__(self, api: str, hint: str = ""):
+        msg = (
+            f"'{api}' cannot run arbitrary Python inside the C kernel. "
+            "Only recorded build-time operations are emitted to C glue."
+        )
+        if hint:
+            msg = f"{msg}\n  Hint: {hint}"
+        super().__init__(msg)
+
+
+class UnsupportedOpError(Exception):
+    """Raised at codegen time when an operation cannot be emitted."""
+
+    def __init__(self, op: str, hint: str = ""):
+        msg = f"Unsupported kernel operation at build time: {op}"
+        if hint:
+            msg = f"{msg}\n  Hint: {hint}"
+        super().__init__(msg)

pyos/api/fs.py

@@ -0,0 +1,46 @@
+"""Filesystem API — available when Kernel capability 'filesystem' is enabled."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Union
+
+from .errors import CapabilityError
+
+
+class File:
+    """Seed files into the OS image at build time; runtime uses syscalls."""
+
+    _seed_files: Dict[str, bytes] = {}
+    _kernel_ref = None
+
+    @classmethod
+    def bind_kernel(cls, kernel) -> None:
+        cls._kernel_ref = kernel
+
+    @classmethod
+    def _require(cls) -> None:
+        k = cls._kernel_ref
+        if k is None or not k.capabilities.get("filesystem"):
+            raise CapabilityError(
+                "filesystem",
+                "Enable with Kernel(enable_filesystem=True) once Phase 5 runtime is linked",
+            )
+
+    @classmethod
+    def write_at_build(cls, path: str, data: Union[bytes, str]) -> None:
+        cls._require()
+        if isinstance(data, str):
+            data = data.encode("ascii", errors="replace")
+        cls._seed_files[path.lstrip("/")] = data
+
+    @classmethod
+    def _reset(cls) -> None:
+        cls._seed_files = {}
+
+    @classmethod
+    def _get_seeds(cls) -> Dict[str, bytes]:
+        return dict(cls._seed_files)
+
+    @classmethod
+    def list_seeds(cls) -> List[str]:
+        return list(cls._seed_files.keys())

pyos/{memory → api}/gdt.py

@@ -235,14 +235,15 @@ class GDT:
     
     def install(self) -> None:
         """
-        Install the GDT and reload segment registers.
-        
-        This must be called after adding all segments.
-        
-        Example:
-            gdt.install()
+        GDT is installed by the C kernel when enable_user_mode/enable_paging is set.
+        Calling this from Python documents intent only.
         """
-        self._operations.append({"type": "install"})
+        from .errors import UnsupportedOpError
+
+        raise UnsupportedOpError(
+            "GDT.install",
+            "Pass Kernel(enable_user_mode=True) or enable_paging=True — C gdt_init() runs at boot",
+        )
     
     def get_selector(self, index: int, ring: int = 0) -> int:
         """

pyos/api/idt.py

@@ -0,0 +1 @@
+# pyOS package

pyos/api/interrupts.py

@@ -0,0 +1,97 @@
+"""
+pyOS Interrupt API — honest: enable/disable/mask emit to C; custom handlers unsupported.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable, Dict, Optional
+
+from .errors import UnsupportedOpError
+
+
+class InterruptType(Enum):
+    DIVIDE_ERROR = 0
+    IRQ_TIMER = 32
+    IRQ_KEYBOARD = 33
+    SYSCALL = 0x80
+
+
+@dataclass
+class InterruptFrame:
+    eip: int = 0
+    cs: int = 0
+    eflags: int = 0
+    esp: int = 0
+    ss: int = 0
+    error_code: int = 0
+    interrupt_number: int = 0
+
+
+class Interrupts:
+    _handlers: Dict[int, Callable] = {}
+    _enabled: bool = False
+    _operations: list = []
+
+    @classmethod
+    def handler(cls, interrupt: InterruptType):
+        def decorator(func: Callable) -> Callable:
+            raise UnsupportedOpError(
+                f"Interrupts.handler({interrupt.name})",
+                "Use @kernel.on_keypress / @kernel.on_timer; IDT is owned by the C kernel",
+            )
+
+        return decorator
+
+    @classmethod
+    def register(cls, interrupt_number: int, handler: Callable) -> None:
+        raise UnsupportedOpError("Interrupts.register")
+
+    @classmethod
+    def unregister(cls, interrupt_number: int) -> None:
+        raise UnsupportedOpError("Interrupts.unregister")
+
+    @classmethod
+    def enable(cls) -> None:
+        cls._enabled = True
+        cls._operations.append({"type": "irq_enable"})
+
+    @classmethod
+    def disable(cls) -> None:
+        cls._enabled = False
+        cls._operations.append({"type": "irq_disable"})
+
+    @classmethod
+    def is_enabled(cls) -> bool:
+        return cls._enabled
+
+    @classmethod
+    def send_eoi(cls, irq: int) -> None:
+        cls._operations.append({"type": "irq_eoi", "irq": int(irq)})
+
+    @classmethod
+    def mask_irq(cls, irq: int) -> None:
+        cls._operations.append({"type": "irq_mask", "irq": int(irq)})
+
+    @classmethod
+    def unmask_irq(cls, irq: int) -> None:
+        cls._operations.append({"type": "irq_unmask", "irq": int(irq)})
+
+    @classmethod
+    def trigger_software_interrupt(cls, interrupt_number: int) -> None:
+        raise UnsupportedOpError("Interrupts.trigger_software_interrupt")
+
+    @classmethod
+    def get_handler(cls, interrupt_number: int) -> Optional[Callable]:
+        return None
+
+    @classmethod
+    def _reset(cls) -> None:
+        cls._handlers = {}
+        cls._enabled = False
+        cls._operations = []
+
+    @classmethod
+    def _get_operations(cls) -> list:
+        return cls._operations.copy()

pyos/api/kernel.py

@@ -0,0 +1,271 @@
+"""
+pyOS Kernel — Python DSL that builds a real freestanding C kernel.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional
+
+from .errors import CapabilityError, UnsupportedOpError
+
+
+class Architecture(Enum):
+    X86 = "x86"
+    X86_64 = "x86_64"
+
+
+@dataclass
+class KernelConfig:
+    arch: Architecture = Architecture.X86
+    stack_size: int = 16384
+    heap_size: int = 1048576
+    heap_start: int = 0x200000
+    stack_top: int = 0x90000
+    video_mode: str = "text"
+    enable_interrupts: bool = True
+    enable_gdt: bool = True
+    enable_paging: bool = False
+    enable_user_mode: bool = False
+    enable_processes: bool = False
+    enable_filesystem: bool = False
+    debug_level: str = "lab"  # quiet | lab
+    keypress_mode: str = "echo"  # echo | custom
+
+
+@dataclass
+class KernelFunction:
+    name: str
+    func: Callable
+    event: str
+    priority: int = 0
+    key_filter: Optional[str] = None
+    interval_ms: int = 1000
+
+
+# Active kernel for Memory/Screen/Process/File binding during boot recording
+_ACTIVE_KERNEL: Optional["Kernel"] = None
+
+
+def get_active_kernel() -> Optional["Kernel"]:
+    return _ACTIVE_KERNEL
+
+
+class Kernel:
+    """
+    Build-time OS definition. Boot handlers run on the host to record ops;
+    the C kernel executes the generated glue at runtime.
+    """
+
+    def __init__(
+        self,
+        arch: str = "x86",
+        stack_size: int = 16384,
+        heap_size: int = 1048576,
+        enable_interrupts: bool = True,
+        enable_gdt: bool = True,
+        enable_paging: bool = False,
+        enable_user_mode: bool = False,
+        enable_processes: bool = False,
+        enable_filesystem: bool = False,
+        debug_level: str = "lab",
+        keypress_mode: str = "echo",
+    ):
+        if arch != "x86":
+            raise ValueError(
+                "Only arch='x86' is supported.\n"
+                "  Why: the C kernel and bootloader are 32-bit protected mode.\n"
+                "  Hint: use Kernel(arch='x86')"
+            )
+        if debug_level not in ("quiet", "lab"):
+            raise ValueError("debug_level must be 'quiet' or 'lab'")
+        if keypress_mode not in ("echo", "custom"):
+            raise ValueError("keypress_mode must be 'echo' or 'custom'")
+
+        # stack grows down from stack_top; keep classic low-memory top
+        stack_top = 0x90000
+        if stack_size < 4096 or stack_size > 0x80000:
+            raise ValueError("stack_size must be between 4096 and 524288")
+
+        self.config = KernelConfig(
+            arch=Architecture(arch),
+            stack_size=stack_size,
+            heap_size=heap_size,
+            stack_top=stack_top,
+            enable_interrupts=enable_interrupts,
+            enable_gdt=enable_gdt,
+            enable_paging=enable_paging,
+            enable_user_mode=enable_user_mode,
+            enable_processes=enable_processes,
+            enable_filesystem=enable_filesystem,
+            debug_level=debug_level,
+            keypress_mode=keypress_mode,
+        )
+
+        self.capabilities: Dict[str, bool] = {
+            "screen_text": True,
+            "heap_alloc": True,
+            "heap_free": True,
+            "keyboard_irq": True,
+            "timer": True,
+            "syscalls": True,
+            "paging": enable_paging,
+            "user_mode": enable_user_mode,
+            "processes": enable_processes,
+            "filesystem": enable_filesystem,
+            "gdt_runtime": enable_gdt,
+        }
+
+        self._boot_functions: List[KernelFunction] = []
+        self._interrupt_handlers: Dict[int, KernelFunction] = {}
+        self._syscall_handlers: Dict[int, KernelFunction] = {}
+        self._keypress_handlers: List[KernelFunction] = []
+        self._timer_handlers: List[KernelFunction] = []
+        self._custom_handlers: Dict[str, List[KernelFunction]] = {}
+        self._compiled_asm: Optional[str] = None
+        self._compiled_binary: Optional[bytes] = None
+        self._seed_files: Dict[str, bytes] = {}
+
+        from .fs import File
+        from .memory import Memory
+        from .process import Process
+
+        Memory.bind_kernel(self)
+        Process.bind_kernel(self)
+        File.bind_kernel(self)
+
+    def require_capability(self, name: str, hint: str = "") -> None:
+        if not self.capabilities.get(name):
+            raise CapabilityError(name, hint or f"Pass the matching Kernel(...) flag to enable '{name}'")
+
+    def on_boot(self, func: Callable = None, *, priority: int = 0):
+        def decorator(f: Callable) -> Callable:
+            self._boot_functions.append(
+                KernelFunction(name=f.__name__, func=f, event="boot", priority=priority)
+            )
+            self._boot_functions.sort(key=lambda x: x.priority)
+            return f
+
+        if func is not None:
+            return decorator(func)
+        return decorator
+
+    def on_keypress(self, func: Callable = None, *, key: str = None, mode: str = None):
+        def decorator(f: Callable) -> Callable:
+            handler = KernelFunction(name=f.__name__, func=f, event="keypress")
+            handler.key_filter = key
+            self._keypress_handlers.append(handler)
+            if mode:
+                self.config.keypress_mode = mode
+            return f
+
+        if func is not None:
+            return decorator(func)
+        return decorator
+
+    def on_interrupt(self, interrupt_number: int):
+        def decorator(func: Callable) -> Callable:
+            raise UnsupportedOpError(
+                f"on_interrupt({interrupt_number})",
+                "Custom IRQ handlers are reserved; use @on_keypress / @on_timer / built-in IDT",
+            )
+
+        return decorator
+
+    def on_syscall(self, syscall_number: int):
+        def decorator(func: Callable) -> Callable:
+            raise UnsupportedOpError(
+                f"on_syscall({syscall_number})",
+                "Syscall table is fixed in C (see SysCallNumber). Extend the C dispatcher to add numbers.",
+            )
+
+        return decorator
+
+    def on_timer(self, interval_ms: int = 1000):
+        def decorator(func: Callable) -> Callable:
+            self.require_capability("timer", "Timer requires enable_interrupts=True")
+            if not self.config.enable_interrupts:
+                raise CapabilityError("timer", "Set enable_interrupts=True")
+            handler = KernelFunction(name=func.__name__, func=func, event="timer")
+            handler.interval_ms = max(10, int(interval_ms))
+            self._timer_handlers.append(handler)
+            return func
+
+        return decorator
+
+    def on_event(self, event_name: str):
+        def decorator(func: Callable) -> Callable:
+            raise UnsupportedOpError(
+                f"on_event({event_name!r})",
+                "Custom event bus is not part of the C kernel; use on_boot/on_timer/on_keypress",
+            )
+
+        return decorator
+
+    def seed_file(self, path: str, data) -> None:
+        self.require_capability("filesystem")
+        if isinstance(data, str):
+            data = data.encode("ascii", errors="replace")
+        self._seed_files[path.lstrip("/")] = data
+
+    def compile(self) -> str:
+        global _ACTIVE_KERNEL
+        from ..build.codegen import CodeGenerator
+
+        _ACTIVE_KERNEL = self
+        try:
+            generator = CodeGenerator(self)
+            self._compiled_asm = generator.generate()
+            return self._compiled_asm
+        finally:
+            _ACTIVE_KERNEL = None
+
+    def assemble(self) -> bytes:
+        from pathlib import Path
+        import tempfile
+
+        from ..build.builder import OSBuilder
+
+        builder = OSBuilder(self)
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "kernel.bin"
+            builder.build_bin(str(path))
+            self._compiled_binary = path.read_bytes()
+        return self._compiled_binary
+
+    def build(self, output: str, format: str = "bin") -> str:
+        from ..build.builder import OSBuilder
+
+        builder = OSBuilder(self)
+        if format == "iso":
+            return builder.build_iso(output)
+        if format == "bin":
+            return builder.build_bin(output)
+        raise ValueError(f"Unknown format: {format}")
+
+    def run(self, image_path: str = None, debug: bool = False):
+        from ..emulator import QEMURunner
+
+        if image_path is None:
+            image_path = self.build("temp_os.bin")
+        runner = QEMURunner(self.config.arch)
+        runner.run(image_path, debug=debug)
+
+    def get_info(self) -> Dict[str, Any]:
+        return {
+            "architecture": self.config.arch.value,
+            "stack_size": self.config.stack_size,
+            "stack_top": self.config.stack_top,
+            "heap_size": self.config.heap_size,
+            "interrupts_enabled": self.config.enable_interrupts,
+            "gdt_enabled": self.config.enable_gdt,
+            "paging": self.config.enable_paging,
+            "user_mode": self.config.enable_user_mode,
+            "processes": self.config.enable_processes,
+            "filesystem": self.config.enable_filesystem,
+            "boot_functions": len(self._boot_functions),
+            "keypress_handlers": len(self._keypress_handlers),
+            "timer_handlers": len(self._timer_handlers),
+            "capabilities": dict(self.capabilities),
+        }