Lib.rs

› Emulators › z80emu
#8-bit #computer #emulation #z80 #pio #called #retro

no-std ral1243

RAL 1243 is a fictional computer emulator for z80emu

by royal

3 stable releases

2.0.1 Feb 25, 2024
1.0.0 Feb 11, 2024

#153 in Emulators


Used in z80emu

LGPL-3.0-or-later

605KB
12K SLoC

Rust 10K SLoC // 0.1% comments Ruby 1.5K SLoC // 0.1% comments

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/examples, called terminal.

Memory

The memory map of RAL 1243:

  • 0x0000-0x1FFF occupies the ROM kernel.
  • 0x2000-0x3FFF occupies a swappable EX-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 page 0x2000-0x3FFF. Otherwise, the currently swapped cartridge ROM is available on this memory page.

I/O

I/O is handled by the daisy-chained devices on the system Bus where the following peripherals are present:

Memory Controller

  • IN (124) - Reads the 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-filled page appears instead.

PIO Z8420

A single PIO Z8420 chip controls the terminal input connected to its Channel A and the output from 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 via Channel A.
  • OUT (9) - PIO Channel A control.
  • OUT (10) - Outputs a character to the terminal via Channel B.
  • OUT (11) - PIO Channel B control.

PIO chip triggers interrupts signaling the terminal input and output data availability.

CTC Z8430

A single 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.

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

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

  • the 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 a countdown to 0.

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. System refuse to start if no user RAM memory is detected.

  • RST 00h - A soft system reset.
  • RST 08h - Fetches the input character into Accumulator signaling a new character with ZF=0. The A register is being modified only on new input. The HL' registers 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. The HL' registers 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 rom/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 code.

Terminal

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

Keys wired to control codes sent to PIO A:

key name data
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 ASCII printable character is forwarded as such.

Data from a PIO output (Channel B) is being forwarded to the console.

Special output control codes interpreted by the terminal:

code action
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 Moves cursor ↑ up
18 Moves cursor ← left
19 Moves cursor ↓ down
20 Moves cursor → right
21 Changes cursor appearanc; followed by a cursor shape number.

The cursor shapes:

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

Depending on the terminal capability more shapes may be available.

Dependencies

~185–405KB