z80_monitor/apps/README.md

ROM applications

Applications in this directory execute directly from ROM; the reset bootstrap does not copy them. Each application must have its own non-overlapping ORG below 8000 and should include bios.inc from the project's include directory instead of accessing the UART hardware directly.

The current allocation is:

• 1400-1C0C: Tiny BASIC
• 1C0D-2FFF: available
• 3000-301D: tape loader
• 301E-7FFF: available for more applications (3100 is the next convenient aligned origin)

The resident BIOS and monitor own high RAM at C000-FFFF. Tiny BASIC owns 8000-BFFF for its workspace and stack. Applications may reuse this lower-RAM allocation because they run one at a time, but they must leave C000-FFFF untouched.

Applications using the interrupt-driven console must leave interrupt mode 2, the I register, and the BIOS UART/CTC configuration intact. They may return normally if they preserve the caller's stack, or jump to BIOS_MONITOR for a non-returning monitor warm start after replacing the stack pointer.

Use BIOS_BANK, BIOS_ROM_DISABLE, and BIOS_ROM_ENABLE for the write-only banking latch rather than writing port 00 directly. The BIOS keeps the ROM-disable state when the RAM bank selection changes. A ROM application must not expect a normal RET after it maps out the ROM containing its return address.

Application origins and the resident-memory layout are defined centrally in rom_layout.mk. The build turns that file into C and assembly includes. To add an application, add its address there, add its build and overlay rules to the Makefile, and add a monitor command or use G address to launch it.