Page 1 of 1

ZeroTrap v0.1: x86 real-mode emulator in Python for OS development learning

Posted: Wed Dec 31, 2025 3:32 am
by EasonChen
Hi everyone,

I'm new to the OSDev community. As a learning exercise in understanding x86 architecture, I've implemented a real-mode x86 emulator entirely in Python.

Project: ZeroTrap
Version: 0.1.0a0 (initial release)
Goal: Create a transparent, educational tool for understanding x86 real-mode programming

Features implemented:
  • 8086 instruction set emulation
  • PIC8259A and PIT8254 simulation
  • Basic interrupt handling (INT n, hardware IRQs)
  • Step-by-step execution with register visualization
  • Modular architecture (CPU, Bus, I/O devices separated)
Sample use case for OS developers:

Code: Select all

# Debug a simple bootloader
from zerotrap.cpu import ZeroTrapCPU
from zerotrap.bus import SystemBus
from zerotrap.devices.bus.ram import RAMDevice

# init the devices
bus = SystemBus()
cpu = ZeroTrapCPU(bus=bus)
ram = RAMDevice(size=1024*1024)

# load the test code
ram.load_data(bootloader_code, 0x07C00)

# attach the components
bus.attach_device(ram, 0x00000, 0xFFFFF) # 0x00000 - 0xFFFFF physical address

def debug_callback(cpu_obj, cmd):  # define a test callback
    # Get the registers
    registers = cpu_obj.registers
    # print
    print(f'[TRACE]. registers={registers}, cmd={cmd}')

# Optional: stdout -> file
import sys
sys.stdout = open('test.log', 'w')

# set the CPU state
cpu.set_reg('CS', 0x0000)
cpu.set_reg('IP', 0x7C00)

# run the test
cpu.run(callback=debug_callback, max_steps=-1) # -1 (or None) means no limit

# cpu runs until HLT or errors occurred.
print('test passed.')
Repository:
Gitee
(Github sync coming soon)

Not claiming: This is production-ready or faster than existing emulators
Hoping for: Feedback from experienced developers or accuracy and educational value

Questions for the community:
  1. Are there specific real-mode edge cases I should test?
  2. What features would make this actually useful for OS development beginners?
  3. Any inaccuracies in the emulation you notice?
Thanks for your time and any advice!