osmk 0.1.0__py3-none-any.whl

osmk/__init__.py

@@ -0,0 +1,619 @@
+"""
+osmk — Write x86 operating systems in Python, one instruction at a time.
+
+Usage:
+    import osmk
+    from osmk import ax, bx
+
+    osmk.start("hello.img")
+    osmk.ax(5)
+    osmk.bx(5)
+    osmk.add(ax, bx)
+    osmk.writehex()
+    osmk.build()
+
+Every function call emits x86 assembly. build() assembles it into
+a bootable disk image you can run in QEMU.
+"""
+
+__version__ = "0.1.0"
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Union
+
+from osmk.registers import (
+    Register,
+    ax, bx, cx, dx,
+    si, di, sp, bp,
+    al, ah, bl, bh, cl, ch, dl, dh,
+    eax, ebx, ecx, edx, esi, edi, esp, ebp,
+    cs, ds, es, fs, gs, ss,
+)
+from osmk.engine import (
+    _Program, _require_started, _get_program, _set_program,
+    _operand, OSMKError, BuildError, StateError,
+)
+
+# Re-export registers at package level so users can do:
+#   from osmk import ax, bx
+#   osmk.add(ax, bx)
+
+Operand = Union[Register, int, str]
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  LIFECYCLE
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+def start(output: str = "os.img", bits: int = 16, org: int = 0x7C00) -> None:
+    """
+    Begin a new OS program.
+
+    Args:
+        output: Output filename (.img or .iso).
+        bits:   CPU mode — 16 (real mode) or 32 (protected mode).
+        org:    Origin address (default 0x7C00 for MBR boot).
+
+    Example:
+        osmk.start("hello.img")
+    """
+    prog = _Program(output)
+    prog.bits = bits
+    prog.org = org
+    _set_program(prog)
+
+
+def build() -> str:
+    """
+    Assemble everything and create the bootable image.
+
+    Returns the path to the generated image file.
+    Requires NASM to be installed on the system.
+
+    Example:
+        osmk.build()  # creates the .img file
+    """
+    prog = _require_started()
+
+    if not shutil.which("nasm"):
+        raise BuildError(
+            "NASM not found. Install it:\n"
+            "  Ubuntu/Debian: sudo apt install nasm\n"
+            "  macOS:         brew install nasm\n"
+            "  Windows:       https://nasm.us"
+        )
+
+    asm_source = prog.generate_asm()
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        asm_path = os.path.join(tmpdir, "program.asm")
+        bin_path = os.path.join(tmpdir, "program.bin")
+
+        with open(asm_path, "w") as f:
+            f.write(asm_source)
+
+        # Assemble with NASM
+        result = subprocess.run(
+            ["nasm", "-f", "bin", asm_path, "-o", bin_path],
+            capture_output=True, text=True,
+        )
+        if result.returncode != 0:
+            raise BuildError(f"NASM assembly failed:\n{result.stderr}")
+
+        # Copy to output path
+        output_path = os.path.abspath(prog.output)
+        shutil.copy2(bin_path, output_path)
+
+    size = os.path.getsize(output_path)
+    print(f"✓ Built {output_path} ({size} bytes)")
+    _set_program(None)
+    return output_path
+
+
+def dump_asm() -> str:
+    """
+    Return the generated NASM source code (without building).
+    Useful for debugging or learning what your Python code produces.
+
+    Example:
+        print(osmk.dump_asm())
+    """
+    prog = _require_started()
+    return prog.generate_asm()
+
+
+def run(memory: int = 128) -> None:
+    """
+    Build (if needed) and launch in QEMU.
+
+    Args:
+        memory: VM RAM in MB.
+    """
+    prog = _require_started()
+    output = prog.output
+
+    if not os.path.exists(output):
+        build()
+    else:
+        # Already built; prog may be cleared, just run
+        pass
+
+    qemu = "qemu-system-i386" if prog.bits <= 16 else "qemu-system-x86_64"
+    if not shutil.which(qemu):
+        qemu = "qemu-system-x86_64" if qemu == "qemu-system-i386" else "qemu-system-i386"
+    if not shutil.which(qemu):
+        raise BuildError("QEMU not found. Install: sudo apt install qemu-system-x86")
+
+    print(f"🚀 Launching {output} in QEMU...")
+    subprocess.run([
+        qemu, "-drive", f"format=raw,file={output}",
+        "-m", str(memory), "-no-reboot", "-no-shutdown",
+    ])
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  REGISTER SETTERS  (mov reg, value)
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+def _set_reg(reg: Register, val: Union[int, Register]) -> None:
+    """Emit: mov <reg>, <val>"""
+    prog = _require_started()
+    prog.emit(f"mov {reg.name}, {_operand(val)}")
+
+
+# Wire every register's __call__ to _set_reg
+# so that osmk.ax(5) calls ax.__call__(5) → _set_reg(ax, 5)
+for _robj in [
+    ax, bx, cx, dx, si, di, sp, bp,
+    al, ah, bl, bh, cl, ch, dl, dh,
+    eax, ebx, ecx, edx, esi, edi, esp, ebp,
+]:
+    _robj._emit_fn = _set_reg
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  MOV (explicit)
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+def mov(dest: Operand, src: Operand) -> None:
+    """
+    MOV instruction.  →  mov dest, src
+
+    Example:
+        osmk.mov(ax, 0x0E)
+        osmk.mov(bx, ax)
+    """
+    prog = _require_started()
+    prog.emit(f"mov {_operand(dest)}, {_operand(src)}")
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  ARITHMETIC
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+def add(dest: Operand, src: Operand) -> None:
+    """ADD instruction.  →  add dest, src"""
+    prog = _require_started()
+    prog.emit(f"add {_operand(dest)}, {_operand(src)}")
+
+
+def sub(dest: Operand, src: Operand) -> None:
+    """SUB instruction.  →  sub dest, src"""
+    prog = _require_started()
+    prog.emit(f"sub {_operand(dest)}, {_operand(src)}")
+
+
+def mul(src: Operand) -> None:
+    """MUL instruction (unsigned AX = AL * src).  →  mul src"""
+    prog = _require_started()
+    prog.emit(f"mul {_operand(src)}")
+
+
+def div(src: Operand) -> None:
+    """DIV instruction (unsigned AX / src → AL=quotient, AH=remainder).  →  div src"""
+    prog = _require_started()
+    prog.emit(f"div {_operand(src)}")
+
+
+def inc(dest: Operand) -> None:
+    """INC instruction.  →  inc dest"""
+    prog = _require_started()
+    prog.emit(f"inc {_operand(dest)}")
+
+
+def dec(dest: Operand) -> None:
+    """DEC instruction.  →  dec dest"""
+    prog = _require_started()
+    prog.emit(f"dec {_operand(dest)}")
+
+
+def neg(dest: Operand) -> None:
+    """NEG instruction (two's complement).  →  neg dest"""
+    prog = _require_started()
+    prog.emit(f"neg {_operand(dest)}")
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  BITWISE / LOGIC
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+def and_(dest: Operand, src: Operand) -> None:
+    """AND instruction.  →  and dest, src"""
+    prog = _require_started()
+    prog.emit(f"and {_operand(dest)}, {_operand(src)}")
+
+
+def or_(dest: Operand, src: Operand) -> None:
+    """OR instruction.  →  or dest, src"""
+    prog = _require_started()
+    prog.emit(f"or {_operand(dest)}, {_operand(src)}")
+
+
+def xor(dest: Operand, src: Operand) -> None:
+    """XOR instruction.  →  xor dest, src"""
+    prog = _require_started()
+    prog.emit(f"xor {_operand(dest)}, {_operand(src)}")
+
+
+def not_(dest: Operand) -> None:
+    """NOT instruction.  →  not dest"""
+    prog = _require_started()
+    prog.emit(f"not {_operand(dest)}")
+
+
+def shl(dest: Operand, count: Operand) -> None:
+    """Shift left.  →  shl dest, count"""
+    prog = _require_started()
+    prog.emit(f"shl {_operand(dest)}, {_operand(count)}")
+
+
+def shr(dest: Operand, count: Operand) -> None:
+    """Shift right.  →  shr dest, count"""
+    prog = _require_started()
+    prog.emit(f"shr {_operand(dest)}, {_operand(count)}")
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  COMPARE / JUMP / CONTROL FLOW
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+def cmp(a: Operand, b: Operand) -> None:
+    """CMP instruction.  →  cmp a, b"""
+    prog = _require_started()
+    prog.emit(f"cmp {_operand(a)}, {_operand(b)}")
+
+
+def label(name: str) -> None:
+    """
+    Define a label at the current position.
+
+    Example:
+        osmk.label("loop")
+        osmk.dec(cx)
+        osmk.jnz("loop")
+    """
+    prog = _require_started()
+    # Labels go at column 0 (no indent) — we mark them specially
+    prog.instructions.append(f"\n{name}:")
+
+
+def jmp(target: str) -> None:
+    """Unconditional jump.  →  jmp target"""
+    prog = _require_started()
+    prog.emit(f"jmp {target}")
+
+
+def je(target: str) -> None:
+    """Jump if equal (ZF=1).  →  je target"""
+    prog = _require_started()
+    prog.emit(f"je {target}")
+
+
+def jne(target: str) -> None:
+    """Jump if not equal.  →  jne target"""
+    prog = _require_started()
+    prog.emit(f"jne {target}")
+
+
+def jl(target: str) -> None:
+    """Jump if less (signed).  →  jl target"""
+    prog = _require_started()
+    prog.emit(f"jl {target}")
+
+
+def jg(target: str) -> None:
+    """Jump if greater (signed).  →  jg target"""
+    prog = _require_started()
+    prog.emit(f"jg {target}")
+
+
+def jle(target: str) -> None:
+    """Jump if less or equal.  →  jle target"""
+    prog = _require_started()
+    prog.emit(f"jle {target}")
+
+
+def jge(target: str) -> None:
+    """Jump if greater or equal.  →  jge target"""
+    prog = _require_started()
+    prog.emit(f"jge {target}")
+
+
+def jz(target: str) -> None:
+    """Jump if zero.  →  jz target"""
+    prog = _require_started()
+    prog.emit(f"jz {target}")
+
+
+def jnz(target: str) -> None:
+    """Jump if not zero.  →  jnz target"""
+    prog = _require_started()
+    prog.emit(f"jnz {target}")
+
+
+def jc(target: str) -> None:
+    """Jump if carry.  →  jc target"""
+    prog = _require_started()
+    prog.emit(f"jc {target}")
+
+
+def call(target: str) -> None:
+    """CALL a subroutine.  →  call target"""
+    prog = _require_started()
+    prog.emit(f"call {target}")
+
+
+def ret() -> None:
+    """Return from subroutine.  →  ret"""
+    prog = _require_started()
+    prog.emit("ret")
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  STACK
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+def push(src: Operand) -> None:
+    """PUSH to stack.  →  push src"""
+    prog = _require_started()
+    prog.emit(f"push {_operand(src)}")
+
+
+def pop(dest: Operand) -> None:
+    """POP from stack.  →  pop dest"""
+    prog = _require_started()
+    prog.emit(f"pop {_operand(dest)}")
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  INTERRUPTS
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+def interrupt(num: int) -> None:
+    """
+    Software interrupt.  →  int <num>
+
+    Common BIOS interrupts:
+        0x10 — Video services
+        0x13 — Disk services
+        0x16 — Keyboard services
+    """
+    prog = _require_started()
+    prog.emit(f"int 0x{num:02X}")
+
+
+def cli() -> None:
+    """Clear interrupt flag (disable interrupts)."""
+    prog = _require_started()
+    prog.emit("cli")
+
+
+def sti() -> None:
+    """Set interrupt flag (enable interrupts)."""
+    prog = _require_started()
+    prog.emit("sti")
+
+
+def hlt() -> None:
+    """Halt the CPU until next interrupt."""
+    prog = _require_started()
+    prog.emit("hlt")
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  OUTPUT — HIGH-LEVEL HELPERS
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+def writehex() -> None:
+    """
+    Print AX as a 4-digit hex string (e.g. "000A").
+    Uses BIOS int 0x10 teletype output.
+
+    Example:
+        osmk.ax(255)
+        osmk.writehex()   # prints "00FF"
+    """
+    prog = _require_started()
+    prog._has_writehex = True
+    prog.emit("call __writehex__")
+
+
+def writechar(char: Union[str, int, None] = None) -> None:
+    """
+    Print a single character.
+
+    - No arg: prints whatever is currently in AL.
+    - str:    prints that character.
+    - int:    prints the ASCII character for that code.
+
+    Example:
+        osmk.writechar("A")
+        osmk.writechar(0x41)   # also prints 'A'
+    """
+    prog = _require_started()
+    prog._has_writechar = True
+    if char is not None:
+        if isinstance(char, str):
+            prog.emit(f"mov al, '{char[0]}'")
+        else:
+            prog.emit(f"mov al, {char}")
+    prog.emit("call __writechar__")
+
+
+def prints(text: str) -> None:
+    """
+    Print a string to the screen.
+
+    Defines the string in the data section and calls
+    the built-in print subroutine.
+
+    Example:
+        osmk.prints("Hello, World!")
+    """
+    prog = _require_started()
+    prog._has_print = True
+    lbl = prog.unique_label("str")
+    # Escape for NASM
+    safe = text.replace("'", "',0x27,'")
+    prog.emit_data(f"{lbl}: db '{safe}', 0")
+    prog.emit(f"mov si, {lbl}")
+    prog.emit("call __print__")
+
+
+def newline() -> None:
+    """Print a CR+LF newline."""
+    prog = _require_started()
+    prog._has_newline = True
+    prog.emit("call __newline__")
+
+
+def readchar() -> None:
+    """
+    Wait for a keypress. The ASCII code goes into AL.
+
+    Example:
+        osmk.readchar()     # AL now has the key
+        osmk.writechar()    # echo it back
+    """
+    prog = _require_started()
+    prog._has_readchar = True
+    prog.emit("call __readchar__")
+
+
+def halt() -> None:
+    """
+    Halt the CPU in an infinite loop (cli + hlt).
+    If you don't call this, osmk adds one automatically at the end.
+    """
+    prog = _require_started()
+    prog._has_halt = True
+    prog.emit("cli")
+    prog.emit(".__halt_user:")
+    prog.emit("hlt")
+    prog.emit("jmp .__halt_user")
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  CUSTOM / ESCAPE HATCH
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+def asm(code: str) -> None:
+    """
+    Inject raw NASM assembly. One or more lines.
+
+    Example:
+        osmk.asm("mov ah, 0x0E")
+        osmk.asm("int 0x10")
+
+        # Multi-line:
+        osmk.asm(\"\"\"
+            mov ah, 0x0E
+            mov al, 'X'
+            int 0x10
+        \"\"\")
+    """
+    prog = _require_started()
+    for line in code.strip().splitlines():
+        stripped = line.strip()
+        if stripped:
+            # If it's a label (ends with ':'), don't indent
+            if stripped.endswith(":"):
+                prog.instructions.append(f"\n{stripped}")
+            else:
+                prog.emit(stripped)
+
+
+def raw(data: bytes) -> None:
+    """
+    Inject raw bytes into the binary.
+
+    Example:
+        osmk.raw(b"\\xEB\\xFE")  # infinite loop: jmp $
+    """
+    prog = _require_started()
+    hex_str = ", ".join(f"0x{b:02X}" for b in data)
+    prog.emit(f"db {hex_str}")
+
+
+def data(name: str, value: str) -> None:
+    """
+    Define a named data variable.
+
+    Example:
+        osmk.data("greeting", "db 'Hello!', 0")
+        osmk.asm("mov si, greeting")
+    """
+    prog = _require_started()
+    prog.emit_data(f"{name}: {value}")
+
+
+def function(name: str) -> "_FunctionBuilder":
+    """
+    Define a callable subroutine.
+
+    Example:
+        with osmk.function("beep") as fn:
+            fn.asm("mov ah, 0x0E")
+            fn.asm("mov al, 0x07")
+            fn.asm("int 0x10")
+
+        osmk.call("beep")
+    """
+    prog = _require_started()
+    return _FunctionBuilder(prog, name)
+
+
+class _FunctionBuilder:
+    """Context manager for building subroutines."""
+
+    def __init__(self, prog: _Program, name: str):
+        self.prog = prog
+        self.name = name
+        self.body: list[str] = []
+
+    def __enter__(self) -> "_FunctionBuilder":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.prog.subroutines[self.name] = self.body
+
+    def asm(self, code: str) -> None:
+        """Add raw assembly to this function."""
+        for line in code.strip().splitlines():
+            stripped = line.strip()
+            if stripped:
+                self.body.append(stripped)
+
+    def emit(self, instruction: str) -> None:
+        """Add a single instruction."""
+        self.body.append(instruction)
+
+
+def comment(text: str) -> None:
+    """Add a comment to the assembly output."""
+    prog = _require_started()
+    prog.emit(f"; {text}")

osmk/engine.py

@@ -0,0 +1,261 @@
+"""
+Core assembly engine — collects instructions and builds bootable images.
+
+This is the heart of osmk. It accumulates x86 assembly instructions
+from Python calls and compiles them into a bootable disk image or ISO.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional, Union
+
+from osmk.registers import Register
+
+
+class OSMKError(Exception):
+    """Base error for osmk."""
+    pass
+
+
+class BuildError(OSMKError):
+    """Raised when NASM assembly or image creation fails."""
+    pass
+
+
+class StateError(OSMKError):
+    """Raised when calling instructions before start()."""
+    pass
+
+
+def _operand(val: Union[Register, int, str]) -> str:
+    """Convert a Python value to a NASM operand string."""
+    if isinstance(val, Register):
+        return val.name
+    if isinstance(val, int):
+        if val < 0:
+            return str(val)
+        return f"0x{val:X}" if val > 9 else str(val)
+    if isinstance(val, str):
+        return val  # label name or raw operand
+    raise TypeError(f"Invalid operand: {val!r}")
+
+
+class _Program:
+    """
+    Internal program state.
+    
+    Tracks all emitted assembly lines, data, labels,
+    and the output filename.
+    """
+
+    def __init__(self, output: str):
+        self.output = output
+        self.bits = 16                # default: 16-bit real mode
+        self.org = 0x7C00             # default: MBR boot origin
+        self.instructions: list[str] = []
+        self.data_section: list[str] = []
+        self.label_counter = 0
+        self.subroutines: dict[str, list[str]] = {}
+        self._has_writehex = False
+        self._has_writechar = False
+        self._has_print = False
+        self._has_newline = False
+        self._has_readchar = False
+        self._has_halt = False
+
+    def emit(self, line: str) -> None:
+        """Add an assembly instruction."""
+        self.instructions.append(line)
+
+    def emit_data(self, line: str) -> None:
+        """Add a data definition."""
+        self.data_section.append(line)
+
+    def unique_label(self, prefix: str = "L") -> str:
+        """Generate a unique label name."""
+        self.label_counter += 1
+        return f"__{prefix}_{self.label_counter}__"
+
+    def generate_asm(self) -> str:
+        """Produce the full NASM source file."""
+        lines: list[str] = []
+        lines.append(f"; Generated by osmk")
+        lines.append(f"[BITS {self.bits}]")
+        lines.append(f"[ORG 0x{self.org:X}]")
+        lines.append("")
+
+        # ── Setup ──
+        lines.append("_start:")
+        lines.append("    xor ax, ax")
+        lines.append("    mov ds, ax")
+        lines.append("    mov es, ax")
+        lines.append("")
+
+        # ── User instructions ──
+        for inst in self.instructions:
+            lines.append(f"    {inst}")
+        lines.append("")
+
+        # If user never explicitly halted, add a halt
+        if not self._has_halt:
+            lines.append("    ; --- end of program ---")
+            lines.append("    cli")
+            lines.append(".__halt:")
+            lines.append("    hlt")
+            lines.append("    jmp .__halt")
+            lines.append("")
+
+        # ── Built-in subroutines (only if used) ──
+        if self._has_writehex:
+            lines.extend(self._sub_writehex())
+        if self._has_writechar:
+            lines.extend(self._sub_writechar())
+        if self._has_print:
+            lines.extend(self._sub_print())
+        if self._has_newline:
+            lines.extend(self._sub_newline())
+        if self._has_readchar:
+            lines.extend(self._sub_readchar())
+
+        # ── User subroutines ──
+        for name, body in self.subroutines.items():
+            lines.append(f"{name}:")
+            for inst in body:
+                lines.append(f"    {inst}")
+            lines.append("    ret")
+            lines.append("")
+
+        # ── Data section ──
+        if self.data_section:
+            lines.append("; --- data ---")
+            for d in self.data_section:
+                lines.append(d)
+            lines.append("")
+
+        # ── Boot signature ──
+        lines.append("; --- boot signature ---")
+        lines.append("times 510 - ($ - $$) db 0")
+        lines.append("dw 0xAA55")
+        lines.append("")
+
+        return "\n".join(lines)
+
+    # ── Built-in subroutines ──
+
+    def _sub_writehex(self) -> list[str]:
+        """Print AX as a 4-digit hex number using BIOS int 0x10."""
+        return [
+            "",
+            "; --- writehex: print AX as hex ---",
+            "__writehex__:",
+            "    pusha",
+            "    mov cx, 4          ; 4 hex digits",
+            ".__wh_loop:",
+            "    rol ax, 4          ; rotate left to get next nibble",
+            "    mov bx, ax",
+            "    and bx, 0x0F       ; mask nibble",
+            "    cmp bl, 10",
+            "    jl .__wh_digit",
+            "    add bl, 'A' - 10   ; A-F",
+            "    jmp .__wh_print",
+            ".__wh_digit:",
+            "    add bl, '0'        ; 0-9",
+            ".__wh_print:",
+            "    mov ah, 0x0E",
+            "    mov al, bl",
+            "    int 0x10",
+            "    dec cx",
+            "    jnz .__wh_loop",
+            "    popa",
+            "    ret",
+            "",
+        ]
+
+    def _sub_writechar(self) -> list[str]:
+        """Print character in AL using BIOS int 0x10."""
+        return [
+            "",
+            "; --- writechar: print AL as char ---",
+            "__writechar__:",
+            "    pusha",
+            "    mov ah, 0x0E",
+            "    int 0x10",
+            "    popa",
+            "    ret",
+            "",
+        ]
+
+    def _sub_print(self) -> list[str]:
+        """Print null-terminated string pointed to by SI."""
+        return [
+            "",
+            "; --- print: print string at SI ---",
+            "__print__:",
+            "    pusha",
+            ".__pr_loop:",
+            "    lodsb",
+            "    test al, al",
+            "    jz .__pr_done",
+            "    mov ah, 0x0E",
+            "    int 0x10",
+            "    jmp .__pr_loop",
+            ".__pr_done:",
+            "    popa",
+            "    ret",
+            "",
+        ]
+
+    def _sub_newline(self) -> list[str]:
+        """Print CR+LF."""
+        return [
+            "",
+            "; --- newline ---",
+            "__newline__:",
+            "    pusha",
+            "    mov ah, 0x0E",
+            "    mov al, 13",
+            "    int 0x10",
+            "    mov al, 10",
+            "    int 0x10",
+            "    popa",
+            "    ret",
+            "",
+        ]
+
+    def _sub_readchar(self) -> list[str]:
+        """Read a key into AL using BIOS int 0x16."""
+        return [
+            "",
+            "; --- readchar: wait for key, result in AL ---",
+            "__readchar__:",
+            "    mov ah, 0x00",
+            "    int 0x16",
+            "    ret",
+            "",
+        ]
+
+
+# ── Module-level singleton ──
+
+_current: Optional[_Program] = None
+
+
+def _require_started() -> _Program:
+    """Ensure start() has been called."""
+    if _current is None:
+        raise StateError("Call osmk.start('output.img') before using instructions.")
+    return _current
+
+
+def _get_program() -> Optional[_Program]:
+    return _current
+
+
+def _set_program(prog: Optional[_Program]) -> None:
+    global _current
+    _current = prog

osmk/registers.py

@@ -0,0 +1,85 @@
+"""x86 register representations for the osmk DSL."""
+
+from __future__ import annotations
+
+
+class Register:
+    """
+    Represents an x86 CPU register.
+    
+    Registers are both objects and callable:
+        osmk.add(ax, bx)   # use ax as operand
+        osmk.ax(5)         # call ax to set it: mov ax, 5
+    """
+
+    def __init__(self, name: str, size: int = 16):
+        self.name = name
+        self.size = size  # 8, 16, or 32 bits
+        self._emit_fn = None  # set by engine after init
+
+    def __call__(self, val):
+        """Set this register: ax(5) → mov ax, 5"""
+        if self._emit_fn is None:
+            raise RuntimeError(
+                "Register setter not wired. Use osmk.ax(5) instead of bare ax(5), "
+                "or make sure osmk is imported."
+            )
+        self._emit_fn(self, val)
+
+    def __repr__(self) -> str:
+        return self.name
+
+    def __str__(self) -> str:
+        return self.name
+
+
+# ── 16-bit General Purpose Registers ──
+ax = Register("ax", 16)
+bx = Register("bx", 16)
+cx = Register("cx", 16)
+dx = Register("dx", 16)
+
+# ── 16-bit Index / Pointer Registers ──
+si = Register("si", 16)
+di = Register("di", 16)
+sp = Register("sp", 16)
+bp = Register("bp", 16)
+
+# ── 8-bit Registers ──
+al = Register("al", 8)
+ah = Register("ah", 8)
+bl = Register("bl", 8)
+bh = Register("bh", 8)
+cl = Register("cl", 8)
+ch = Register("ch", 8)
+dl = Register("dl", 8)
+dh = Register("dh", 8)
+
+# ── 32-bit Extended Registers ──
+eax = Register("eax", 32)
+ebx = Register("ebx", 32)
+ecx = Register("ecx", 32)
+edx = Register("edx", 32)
+esi = Register("esi", 32)
+edi = Register("edi", 32)
+esp = Register("esp", 32)
+ebp = Register("ebp", 32)
+
+# ── Segment Registers ──
+cs = Register("cs", 16)
+ds = Register("ds", 16)
+es = Register("es", 16)
+fs = Register("fs", 16)
+gs = Register("gs", 16)
+ss = Register("ss", 16)
+
+# All registers for easy import
+ALL_REGISTERS = {
+    "ax": ax, "bx": bx, "cx": cx, "dx": dx,
+    "si": si, "di": di, "sp": sp, "bp": bp,
+    "al": al, "ah": ah, "bl": bl, "bh": bh,
+    "cl": cl, "ch": ch, "dl": dl, "dh": dh,
+    "eax": eax, "ebx": ebx, "ecx": ecx, "edx": edx,
+    "esi": esi, "edi": edi, "esp": esp, "ebp": ebp,
+    "cs": cs, "ds": ds, "es": es, "fs": fs, "gs": gs, "ss": ss,
+}

osmk-0.1.0.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: osmk
+Version: 0.1.0
+Summary: Write x86 operating systems in Python — one instruction at a time
+Author-email: Your Name <you@example.com>
+License: MIT
+Keywords: os,assembly,x86,bootloader,osdev,low-level
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Operating System Kernels
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# osmk
+
+**Write x86 operating systems in Python — one instruction at a time.**
+
+Every function call maps to an x86 assembly instruction. `build()` assembles it into a bootable 512-byte disk image.
+
+## Install
+
+```bash
+pip install osmk
+```
+
+You also need **NASM** (the assembler) and optionally **QEMU** (to run your OS):
+
+```bash
+# Ubuntu/Debian
+sudo apt install nasm qemu-system-x86
+
+# macOS
+brew install nasm qemu
+```
+
+## Quick Start
+
+```python
+import osmk
+from osmk import ax, bx
+
+osmk.start("hello.img")    # begin a new OS
+
+osmk.ax(5)                 # mov ax, 5
+osmk.bx(5)                 # mov bx, 5
+osmk.add(ax, bx)           # add ax, bx  →  ax = 0x000A
+osmk.writehex()             # print AX as hex → "000A"
+
+osmk.build()                # assemble → hello.img (512 bytes)
+```
+
+Run it:
+```bash
+qemu-system-i386 -drive format=raw,file=hello.img
+```
+
+## API Reference
+
+### Lifecycle
+
+| Function | Description |
+|----------|-------------|
+| `start(filename, bits=16, org=0x7C00)` | Begin a new OS program |
+| `build()` | Assemble and create the bootable image |
+| `dump_asm()` | Return the generated NASM source (for debugging) |
+| `run(memory=128)` | Build and launch in QEMU |
+
+### Register Setters
+
+Every register is callable. `osmk.ax(5)` → `mov ax, 5`.
+
+```python
+osmk.ax(5)          # mov ax, 5
+osmk.bx(ax)         # mov bx, ax
+osmk.al(0x41)       # mov al, 0x41
+osmk.eax(0x1000)    # mov eax, 0x1000
+```
+
+Available: `ax bx cx dx si di sp bp` · `al ah bl bh cl ch dl dh` · `eax ebx ecx edx esi edi esp ebp`
+
+### Instructions
+
+```python
+# Arithmetic
+osmk.add(ax, bx)       osmk.sub(ax, 1)
+osmk.mul(bx)            osmk.div(cx)
+osmk.inc(ax)            osmk.dec(cx)
+osmk.neg(ax)
+
+# Bitwise
+osmk.and_(ax, 0xFF)    osmk.or_(ax, bx)
+osmk.xor(ax, ax)       osmk.not_(ax)
+osmk.shl(ax, 4)        osmk.shr(ax, 1)
+
+# Compare & Jump
+osmk.cmp(ax, 0)
+osmk.je("done")        osmk.jne("loop")
+osmk.jl("less")        osmk.jg("greater")
+osmk.jz("zero")        osmk.jnz("nonzero")
+osmk.jmp("start")      osmk.jc("carry")
+
+# Stack
+osmk.push(ax)           osmk.pop(bx)
+
+# Subroutines
+osmk.call("myfunc")     osmk.ret()
+
+# Interrupts
+osmk.interrupt(0x10)    # int 0x10
+osmk.cli()              osmk.sti()
+osmk.hlt()
+
+# Labels
+osmk.label("loop")
+```
+
+### Output Helpers
+
+```python
+osmk.writehex()         # print AX as 4-digit hex (e.g. "000A")
+osmk.writechar("A")     # print character 'A'
+osmk.writechar()        # print whatever's in AL
+osmk.prints("Hello!")   # print a string
+osmk.newline()          # print CR+LF
+osmk.readchar()         # wait for keypress → AL
+osmk.halt()             # halt CPU (cli + hlt loop)
+```
+
+### Custom / Escape Hatch
+
+When osmk doesn't cover what you need:
+
+```python
+# Inject raw NASM assembly
+osmk.asm("mov ah, 0x0E")
+osmk.asm("""
+    mov ah, 0x00
+    mov al, 0x03
+    int 0x10
+""")
+
+# Inject raw bytes
+osmk.raw(b"\x90\x90\x90")   # 3x NOP
+
+# Define data
+osmk.data("my_var", "dw 0x1234")
+
+# Define a subroutine
+with osmk.function("beep") as fn:
+    fn.asm("mov ah, 0x0E")
+    fn.asm("mov al, 0x07")  # BEL character
+    fn.asm("int 0x10")
+
+osmk.call("beep")
+
+# Add comments
+osmk.comment("this sets up video mode")
+```
+
+### Explicit MOV
+
+```python
+osmk.mov(ax, 0x0E)     # same as osmk.ax(0x0E)
+osmk.mov(bx, ax)       # same as osmk.bx(ax)
+```
+
+## Examples
+
+### Hello World
+```python
+import osmk
+
+osmk.start("hello.img")
+osmk.prints("Hello, World!")
+osmk.newline()
+osmk.prints("My first OS!")
+osmk.halt()
+osmk.build()
+```
+
+### Keyboard Echo
+```python
+import osmk
+from osmk import cx
+
+osmk.start("echo.img")
+osmk.prints("Type anything:")
+osmk.newline()
+
+osmk.label("loop")
+osmk.readchar()        # key → AL
+osmk.writechar()       # echo it
+osmk.jmp("loop")
+
+osmk.build()
+```
+
+### Counter
+```python
+import osmk
+from osmk import ax, cx
+
+osmk.start("counter.img")
+
+osmk.ax(0)
+osmk.cx(16)
+
+osmk.label("count")
+osmk.writehex()
+osmk.prints(" ")
+osmk.inc(ax)
+osmk.dec(cx)
+osmk.jnz("count")
+
+osmk.halt()
+osmk.build()
+```
+
+## How It Works
+
+1. Each `osmk.*` call appends an x86 assembly instruction to an internal list
+2. `build()` wraps them in a bootloader template (16-bit real mode, MBR)
+3. NASM assembles it into a flat binary
+4. The binary is exactly 512 bytes with the `0xAA55` boot signature
+
+The generated code runs in **16-bit real mode** using BIOS interrupts for I/O. Use `dump_asm()` to see exactly what assembly your Python generates.
+
+## Resources
+
+- [OSDev Wiki](https://wiki.osdev.org/) — OS development reference
+- [NASM Documentation](https://nasm.us/doc/) — assembler docs
+- [x86 Instruction Reference](https://www.felixcloutier.com/x86/) — complete instruction set
+- [Writing a Simple OS](https://www.cs.bham.ac.uk/~exr/lectures/opsys/10_11/lectures/os-dev.pdf) — Nick Blundell's guide
+- [BIOS Interrupt List](https://en.wikipedia.org/wiki/BIOS_interrupt_call) — int 0x10, 0x13, 0x16, etc.
+
+## License
+
+MIT

osmk-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+osmk/__init__.py,sha256=mPM3acC0Gwm-ivuWMIFOpwc-gevH38EvrKKhzJTt_gc,17319
+osmk/engine.py,sha256=Nqn7CKRHOahhAqsTzuXsgAyoqQZeON2PmL899VP77Fc,7462
+osmk/registers.py,sha256=jbDosSWkUjxOZOMMFH6_COQaAEFZlaCLQwPhanW8obw,2273
+osmk-0.1.0.dist-info/METADATA,sha256=JvkmTIlki-W6Z36LWuV20srddjik7fG4gVqf0QA8drA,5709
+osmk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+osmk-0.1.0.dist-info/top_level.txt,sha256=80_Iz5bMuRgmgHIm6jLSM_R8CXhwhpnkfo97QI-oyHQ,5
+osmk-0.1.0.dist-info/RECORD,,

osmk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

osmk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+osmk