osmk 0.1.0

Write x86 operating systems in Python — one instruction at a time

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

pip install osmk

You also need NASM (the assembler) and optionally QEMU (to run your OS):

# Ubuntu/Debian
sudo apt install nasm qemu-system-x86

# macOS
brew install nasm qemu

Quick Start

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:

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.

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

# 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

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:

# 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

osmk.mov(ax, 0x0E)     # same as osmk.ax(0x0E)
osmk.mov(bx, ax)       # same as osmk.bx(ax)

Examples

Hello World

import osmk

osmk.start("hello.img")
osmk.prints("Hello, World!")
osmk.newline()
osmk.prints("My first OS!")
osmk.halt()
osmk.build()

Keyboard Echo

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

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 — OS development reference
• NASM Documentation — assembler docs
• x86 Instruction Reference — complete instruction set
• Writing a Simple OS — Nick Blundell's guide
• BIOS Interrupt List — int 0x10, 0x13, 0x16, etc.

License

MIT