2.9 KiB
AGENTS.md
Project Documentation
docs/SPEC.md
Contains the design and architecture specification for VirtualXT. Covers the emulator's guiding principles (simplicity, minimalism, transparency), system overview with the four-layer diagram, runtime flow, bus dispatch mechanism (flat lookup tables for memory and I/O), peripheral vtable interface, CPU decode-dispatch loop with cycle accounting and prefetch queue, timers, interrupt routing through the PIC, disk emulation via BIOS INT 0x13/0x19 and the VXTX extension ROM, build modes, testing infrastructure, and the optional debug server.
When useful: Reference this file to understand the project's design philosophy, how components interact, or what conventions to follow when implementing or modifying hardware modules.
Do not modify this file unless explicitly instructed to do so.
docs/REFERENCES.md
Contains a curated list of external technical references for PC/XT hardware emulation. Includes links to the VirtualXT repository history, the MartyPC emulation book, Minus Zero Degrees hardware reference, x86 opcode tables, Felix Cloutier's instruction reference, the OSDev Wiki, 8086 microcode disassembly, and the 8088 bus logic article.
When useful: Reference this file when implementing or debugging specific hardware components and you need authoritative technical documentation on chip behavior, instruction encoding, bus timing, or other low-level PC/XT details.
Do not modify this file unless explicitly instructed to do so.
docs/STATUS.md
Contains the current state of the project: known bugs, unimplemented features, and active todo items.
Before making changes to the project, always read this file first to understand what is done, what is in progress, and what known issues exist.
After applying changes to the project, always update this file to reflect the new state. Keep the file below 200 lines.
Build System
CI
Check build status in Codeberg CI at https://ci.codeberg.org/repos/15480 or
via the API with a Codeberg CI personal access token in
Authorization: Bearer $WOODPECKER_TOKEN.
Latest pipeline status:
curl -H "Authorization: Bearer $WOODPECKER_TOKEN" \
https://ci.codeberg.org/api/repos/15480/pipelines/latest
Recent failed pipelines on develop:
curl -H "Authorization: Bearer $WOODPECKER_TOKEN" \
"https://ci.codeberg.org/api/repos/15480/pipelines?branch=develop&status=failure"
Failed step logs:
curl -H "Authorization: Bearer $WOODPECKER_TOKEN" \
https://ci.codeberg.org/api/repos/15480/logs/<pipeline_number>/<step_id>
Get step_id from the pipeline page in the CI UI or from
/api/repos/15480/pipelines/<pipeline_number>.
Generated Headers
Files in src/frontend/generated/ are committed to the repo and not regenerated
automatically. Use make bios-data (needs nasm) or make samples (needs
ffmpeg) to regenerate manually when source inputs change.