Thingamajig/readme.md

Thingamajig v1.1-dev
====================

Thingamajig v1.1 is a RISC/MISC homebrew computer architecture. Its git
repository can be found at
https://ahti.space/git/crazyettin/Thingamajig.

Included Software
-----------------

The repository includes an emulator implementation of Thingamajig with
storage device control programs, and an assembler and a disassembler,
all written in FreePascal. It also includes couple of simple example
programs for Thingamajig written in assembly.

Registers and Memory
--------------------

  * 24-bit instruction register IR
  * 16-bit instruction and return pointers IP and RP
  * 8-bit general-purpose registers R0-R3
  * 8-bit memory locations 0-FFFF

Multi-byte values are big-endian. Memory locations 0-FFEF are used for
RAM while FFF0-FFFF are reserved for memory mapped devices.

Input and output are mapped to address FFFF, while arbitrary devices can
be mapped to the other reserved addresses. When interacting with memory
mapped devices Thingamajig will stop processing to wait for the device
to be ready if needed.

Instructions
------------

Instructions without an immediate or address argument are 8-bit, those
with an immediate one 16-bit, and those with an address one 24-bit. The
instruction pointer is incremented before being accessed or modified.

0   HALT
1   RET                    IP = *RP; RP += 2

2   SHL     RX, N          RX <<= N (logical)     Shifts of 1-4 steps,
3   SHR     RX, N          RX >>= N (logical)     with 4 encoded as 0
4   ROL     RX, N          RX <<= N (rotating)    in machine code.
5   ROR     RX, N          RX >>= N (rotating)

6   NAND    RX, RY         RX = ~(RX & RY)
7   AND     RX, RY         RX &= RY
8   OR      RX, RY         RX |= RY
9   XOR     RX, RY         RX ^= RY

A   LOAD    RX, ~0, IMM    RX = IMM      Written as "LOAD RX, #IMM"
                 0, ADDR   RX = *ADDR    Written as "LOAD RX, ADDR"
B   STORE       RY, ADDR   *ADDR = RY    Written as "STORE ADDR, RY"

C   BREQ    RX, RY, ADDR   if (RX == RY) IP = ADDR
D   BRNEQ   RX, RY, ADDR   if (RX != RY) IP = ADDR
E   CLEQ    RX, RY, ADDR   if (RX == RY) {RP -= 2; *RP = IP; IP = ADDR}
F   CLNEQ   RX, RY, ADDR   if (RX != RY) {RP -= 2; *RP = IP; IP = ADDR}

Assembly Language
-----------------

Lines of assembly are of the following form:

LABEL: OPER ARG1, ARG2, ARG3 ;Comment

The language is case-insensitive and uses hexadecimal numbers. A label
can consist of any alphanumeric characters as long as it is not
interpretable as a hexadecimal number. The label, instruction, and
comment elements are all optional, as is spacing between the arguments.
For the arguments of each instruction see the previous section.

Address arguments can be either absolute addresses or references to or
relative to a label. Relative references are of the form LABEL +/- N;
the spacing is optional.

In addition to the true instructions there are three
pseudo-instructions. ORG sets the location of the following code and
data; as it has no direct equivalent in machine code it cannot have a
label. The default starting address of 0 does not need to be indicated
with ORG. DATA introduces a byte of data. ADDR introduces two bytes of
data containing the address of a reference to or relative to a label.

Boot
----

At boot the initial program loader (IPL) loads a program to RAM starting
at address 0 after which is cedes control to the CPU. If an
implementation has a front panel the IPL is optional. The instruction
and return pointers are initialised as 0 and the first address after RAM
respectively, while other registers and RAM are uninitialised.

Emulator and Storage Device Control Programs
--------------------------------------------

Usage:
  * emulator (-v) program (2> verbose_output)
  * tapectl (-r tape) (-p tape)
  * floppyctl (-0 disc) (-1 disc)

By default the emulator runs at roughly 500 KIPS and has 2 KiB of RAM.
The arguments -dRAM4, -dRAM8, -dRAM16, -dRAM32, and -dRAM64 can be used
to compile the emulator with 4, 8, 16, 32, or 64 KiB (minus the reserved
addresses) of RAM respectively instead and the speed limitations can be
removed with the argument -dfast. When run with the argument -v the
current state of the registers is output to stderr before each
instruction.

Input and output are handled by an emulated roughly 1000 CPS
ASCII-compatible glass teletype terminal with local echo on by default.
Of the control characters bell (^G), backspace (^H), line feed (^J),
carriage return (^M), and device control characters two (^R) and four
(^T) are used by the terminal: the device control characters are used to
turn the local echo on and off respectively while the rest have their
standard uses. The backspace and delete keys input their respective
characters and non-character keys null.

In Linux the emulator can be compiled with support for a character
printer, an emulated high speed (roughly 500 CPS in and 50 CPS out)
8-bit paper tape reader and punch, and an emulated two-drive 8" floppy
disc system with the arguments -dprinter, -dtape, and -dfloppy
respectively. The printer is mapped to address FFFE, the tape reader and
punch to FFFD, and the disc system to FFFB and FFFC. The printer prints
into /dev/usb/lp0. The tape files read from and punched to are (re)set
using the program tapectl with the arguments -r and -p respectively and
the disc files in drives 0 and 1 using the program floppyctl with the
arguments -0 and -1 respectively. The disc system uses hard sectored
single-sided discs with 77 tracks of 32 sectors of 137 bytes, or 337568
bytes in total: the disc files must be of this size.

The floppy disc system uses two ports: command at FFFB and data at FFFC.
Only the low nibble of the command port is used, consisting of a
three-bit command followed by a one-bit drive number used as an argument
by instructions 1 and 4-7. The track or sector to be accessed is input
to and the buffer accessed sequentially through the data port after the
relevant command is input to the command port. New commands other than
resetting the system are ignored until the current command is fully
executed. Note that each sector begins with a synchronisation bit that
must always be set.

The commands for the disc system are:
 0: Reset the system.
 1: Format a disc.
 2: Read a sector from the buffer to the computer.
 3: Write a sector from the computer to the buffer.
 4: Set the track to be accessed.
 5: Set the sector to be accessed.
 6: Read a sector from a disc to the buffer.
 7: Write a sector from the buffer to a disc.

The IPL loads the program specified as an argument when running the
emulator.

Assembler and Disassembler
--------------------------

Usage:
  * assembler program (< input)
  * disassembler program (> output)

Both the assembler and the disassembler are run with a program as their
sole argument: they take their input from and print their output to
stdin and stdout respectively.

An initial gap created with ORG is not included in an assembled program.
All possible interpretations of a disassembled program are included in
its listing, resulting in overlapping information.