RAL 1243

RAL 1243 is a fictional computer brought into its virtual existence to provide an example on how to implement emulators based on z80emu Z80 CPU emulator.

The computer has no graphics or a keyboard interface but instead communicates with the user via the PIO onboard chipset.

Library

The RAL 1243 computer is a library. Ready for embedded.

Usage

An example using this library can be found in z80emu repository, called terminal.

To run the emulator with the built-in ex-ROMs and default 16kb of user RAM and with the CPU clocked at 4MHz:

cargo run -r --example terminal

To run the emulator with 48kb RAM, the CPU at 8MHz and externally loaded ex-ROMs:

cargo run -r --example terminal -- examples/ral1243/exroms -m 48 -c 8000

... so you may enjoy "Sssshnake", the only game written for RAL 1243.

Memory

The memory map of RAL 1243:

• 0x0000-0x1FFF occupies the ROM kernel.
• 0x2000-0x3FFF occupies a swappable ROM cardridges with user programs or a kernel only accessible RAM page.
• 0x4000-RAMTOP Random Access Memory available for user programs.

Traps:

If the program counter is between 0x0000 and 0x1FFF (inclusive) the RAM page is being swapped into memory area 0x2000 to 0x3FFF (inclusive). Otherwise, the currently swapped cartridge ROM is available on this memory page.

I/O

I/O is handled by the BUS devices on the system bus where the following devices are being installed:

Memory controller

• IN (124) - Reads currently swapped in cartridge number.
• OUT (124) - Selects one of 256 swappable cartridges to be mapped at the memory page 0x2000-0x3FFF. If the cartridge doesn't exist a 0xFF byte value-filled page appears instead.

PIO Z8420

One PIO Z8420 chip controls terminal input connected to its Channel A and terminal output to its Channel B.

NOTE: The implementation of the PIO chip emulates only input and output channel modes. The bi-directional and control modes are not currently supported.

• IN (8) - Reads a character from the terminal (PIO A).
• OUT (9) - PIO A channel control.
• OUT (10) - Outputs a character to the terminal (PIO B).
• OUT (11) - PIO B channel control.

The terminal input and output availability are controlled by interrupts generated by the PIO chip.

CTC Z8430

One CTC Z8430 chip controls 4 timers/counters.

• CLK/TRG lines of channels 0 and 2 are connected to a (CPU clock independent) 100µs pulse (10 kHz) clock.

• ZT/CO line of Channel 0 is connected to the CLK/TRG line of channel 1.

• ZT/CO line of Channel 1 is currently not connected to anything.

• ZT/CO line of Channel 2 is connected to the CLK/TRG line of channel 3.

• IN (4) - CTC channel 0 current counter value.

• OUT (4) - CTC channel 0 control.

• IN (5) - CTC channel 1 current counter value.

• OUT (5) - CTC channel 1 control.

• IN (6) - CTC channel 2 current counter value.

• OUT (6) - CTC channel 2 control.

• IN (7) - CTC channel 3 current counter value.

• OUT (7) - CTC channel 3 control.

The CTC chip may trigger interrupts on 0 countdowns.

Interrupts

IM 2 interrupt mode must be always on.

System

The RAM memory area mapped between 0x2000 and 0x3FFF is for exclusive use by the ROM kernel only.

The machine stack occupies the last bytes of RAM memory. SP is initiated to the last address of available RAM + 1 after boot.

• RST 00h - A soft system reset.
• RST 08h - Fetches the input character in Accumulator signaling a new character with ZF=0. Register A is being modified only on new input. Registers HL' are being modified. When called with CF=1 waits until the next character is available, always succeeds. When called with CF=0 returns immediately, signalling a possible failure with ZF=1.
• RST 10h - Outputs a single character given in Accumulator signalling the success with ZF=1. Registers HL' are being modified. When called with CF=0 waits until the character could be buffered, always succeeds. When called with CF=1 returns immediately, signalling a possible failure with ZF=0.
• RST 18h - Forwards a call to an address in IX.
• RST 20h - Forwards a call to an address in IY.
• RST 28h - Forwards to one of the syslib functions identified as an 8-bit function vector in the accumulator. Modifies A and HL'. Functions may alter more registers. For a list of system library routines consult the rom kernel source ral1243/ral1243_rom.rb.
• RST 30h - Forwards a call to an address in HL.
• RST 38h - Back to system menu.
• NMI - Back to system menu if running the ex-ROM/user code.

Terminal

The terminal forwards any user input to the RAL 1243 PIO input device.

Some of the function keys are special:

• F1 key generates a Z80 NMI signal.
• F4 key generates a Z80 RESET signal.
• F10 key exits the emulator.

Keys wired to input control codes:

• PgUp: 1
• Home: 2
• End: 3
• PgDn: 4
• Ins: 5
• Backspace: 8
• Tab: 9
• Up: 17
• Left: 18
• Down: 19
• Right: 20
• Esc: 27
• Del: 127

Any message from a PIO output device is being forwarded to the console.

Special output control terminal I/O codes:

• 8 - moves the cursor back left.
• 10 - moves the cursor to the next line.
• 12 - clears the terminal.
• 13 - moves the cursor to the first column.
• 16 - moves the cursor to an absolute position; followed by a row index, followed by a column index.
• 17 - cursor ↑ up
• 18 - cursor ← left
• 19 - cursor ↓ down
• 20 - cursor → right

21 changes cursor appearance, followed by a cursor shape number:

• 0 - hidden
• 1 - underscore
• 2 - block

Depending on the terminal capability more shapes may be available.