gigatron-rom
+--- LICENSE 2-Clause BSD License
+--- Makefile Marcel's Makefile
+--- Core/ Gigatron kernel and build tools
| +--- ROMv3.py Video/audio/io/interpreter loops, built-in vCPU
| | applications and data ("kernel + ROM disk")
| | Execute this to build ROM files
| `--- compilegcl.py Stand-alone GCL to vCPU compiler (GT1 files)
+--- interface.json Formal bindings interface to ROM for programs
+--- Apps/ Built-in and example applications (GCL and GT1)
| +--- Blinky.gcl Very simple GCL program
| +--- HelloWorld.gcl Program that draws "Hello world" on screen
| +--- WozMon.gt1 Port of Apple-1 monitor program
| `--- TinyBASIC.gt1 Integer BASIC interpreter
+--- BASIC/ Example BASIC programs
+--- Images/ Built-in images
+--- Utils/
| +--- sendFile.py Send a GT1 or BASIC file from laptop/PC to Gigatron
| `--- BabelFish/ Generic Arduino sketch for interfacing with
| Gigatron. Used for transferring GT1 files into
| the computer and/or hooking up an keyboard.
+--- Docs/
| +--- GT1-files.txt vCPU object file format and ROM versioning
| +--- GCL-language.txt Gigatron Control Language and vCPU explanation
| +--- gtemu.c An executable instruction set definition
| +--- TinyBASIC.ebnf Formal definition of Gigatron TinyBASIC syntax
| `--- TinyBASIC.xhtml Railroad diagram of Gigatron TinyBASIC syntax
|
`--- Contrib/ Contributions outside the kit's ROM and tooling
+--- at67/ Emulator/visualizer (SDL2), 8-bit/16-bit
| assembler, debugger, MIDI music, demos (sprites,
| lines, game of life, tetris game...)
+--- flok99/ Simple (and slow) visualizer using SDL2
+--- kervinck/ Ramblings (all work in progress)
| +--- gcl1.ebnf Formal definition of GCL1 syntax
| `--- EBNF.xhtml Railroad diagram of GCL1 syntax
`--- xxxbxxx/ Bricks game; RPi port of BabelFish.ino
ROMv3.asm Annotated disassembly, with labels and comments (large!)
ROMv3.rom ROM file for 27C1024 (PCB versions)
0 1 47 48 127 128 129 (vSP) 255
+-+-------------+-----------+-+-------------+--------------+
page 0 |0| System vars | User vars |1| User vars <-| Stack/Loader |
+-+-------------+-----------+-+------+------+--+-----------+
page 1 | Video table 239| vReset | Channel 1 |
+------------------------------------+---------+-----------+
page 2 |0 240 249| Channel 2 |
| +-----------+
page 3 | User vCPU code and/or data | Channel 3 |
| +-----------+
page 4 | | Channel 4 |
| +-----------+
page 5-6 | 250 255|
| |
| |
+----------------------------------------------------------+
page 7 | Sound tables |
+--------------------------------+-------------------------+
page 8-127 |0 159|160 255|
| 120 lines of 160 pixels | Extra space for user |
| Default video memory | code and/or data |
= = =
| | |
+--------------------------------+-------------------------+
page 128-255 | Not used in the 32K system: mirror of page 0-127 |
+----------------------------------------------------------+
0 255
[Note: In the next section, names in parentheses refer to *internal*
variables that are subject to change between versions. See for a
more detailed explanation on compatibility the file Docs/GT1-files.txt]
Address Name Description
-------- ------------- -----------
0000 0 Constant
0001 memSize Number of RAM pages detected at hard reset (64kB=0)
0002 (channel) Sound channel update on current scanline
0003 (sample) Accumulator for synthesizing next sound sample
0004 (bootCount) 0 for cold boot, >0 for warm boot
0005 (bootCheck) Checksum of bootCount
0006-0008 entropy Randomness from SRAM boot and input, updated each frame
0009 videoY Counts up from 0 to 238 in steps of 2 (odd in vBlank)
000a (frameX) Starting byte within page for pixel burst
000b (frameY) Page of current pixel row (updated by videoA)
000c (nextVideo) Jump offset to scan line handler (videoA, B, C...)
000d (videoModeD) Handler for every 4th line (pixel burst or vCPU)
000e frameCount Continuous video frame counter
000f serialRaw New raw serial read
0010 (serialLast) Previous serial read
0011 buttonState Clearable button state (can be convenient in user code)
0012 (resetTimer) After 2 seconds of holding 'Start', do a soft reset
0013 (xout) Memory cache for XOUT register
0014 xoutMask The blinkenlights and sound on/off state
0015 (vTicks) Remaining interpreter ticks (=units of 2 CPU cycles)
0016-0017 vPC Interpreter program counter, points into RAM
0018-0019 vAC Interpreter accumulator, 16-bits
001a-001b vLR Return address, for returning after CALL
001c vSP Stack pointer
001d (vTmp) Scratch storage location for vCPU
001e (vReturn) Return address (L) from vCPU into the loop (H is fixed)
001f (videoModeB) ROMv2: Handler for every 2nd line (pixel burst or vCPU)
0020 (videoModeC) ROMv2: Handler for every 3rd line (pixel burst or vCPU)
0021 romType ROMv1=0x1c, ROMv2=0x20, ROMv3=0x28
0022-0023 sysFn Address for SYS function call
0024-002b sysArgs Arguments for SYS functions
002c soundTimer Countdown timer for playing sound
002d ledTimer Number of frames until next LED change
002e ledState Current LED state machine value (branch offset)
002f ledTempo Next value for ledTimer after LED state change
0030-007f userVars Program variables
0080 1 Constant
0081-.... - More space for program variables
....-00ff <stack>
0100-01ef videoTable Video indirection table (Y0,dX0,Y1,dX1,Y2,...,dX119)
01f0-01f9 vReset vCPU routine to load and start Reset sequence
01fa wavA[1] Sound channel 1
01fb wavX[1]
01fc keyL[1]
01fd keyH[1]
01fe oscL[1]
01ff oscH[1]
0200-02f9 userCode vCPU code/data (default start of user code)
02fa wavA[2] Sound channel 2
02fb wavX[2]
02fc keyL[2]
02fd keyH[2]
02fe oscL[2]
02ff oscH[2]
0300-03f9 - vCPU code/data
03fa wavA[3] Sound channel 3
03fb wavX[3]
03fc keyL[3]
03fd keyH[3]
03fe oscL[3]
03ff oscH[3]
0400-04f9 - vCPU code/data
04fa wavA[4] Sound channel 4
04fb wavX[4]
04fc keyL[4]
04fd keyH[4]
04fe oscL[4]
04ff oscH[4]
0500-05ff - vCPU code/dat
0600-06ff - vCPU code/data
0700-07ff soundTable
0800-7fff screenMemory
0800-089f pixel line 0
08a0-08ff - vCPU code/data
...
7f00-7f9f pixel line 119
7fa0-7fff - vCPU code/data
-------- ------------- -----------
+----------------------------------------------------------+
page 0 | Boot and reset sequences |
+----------------------------------------------------------+
page 1 | Video and audio loop (visible lines) |
| |
page 2 | Video and audio loop (vertical blank) |
+----------------------------------------------------------+
page 3 | vCPU interpreter loop (primary page) |
| |
page 4 | vCPU extended instructions and SYS functions |
+----------------------------------------------------------+
page 5 | Shift tables |
| |
page 6 | SYS functions (LSRW and others) |
+----------------------------------------------------------+
page 7-8 | Font table (ASCII 32..81 and 82..127) |
+----------------------------------------------------------+
page 9 | Notes table (C-0..A#7) |
+----------------------------------------------------------+
page 10 | Inversion table |
+----------------------------------------------------------+
page 11-214 | SYS functions |
| |
| ROM tables: Embedded high-resolution images (packed) |
| |
page 215-255 | ROM files: Embedded vCPU applications (serial) |
+----------------------------------------------------------+
0 255
Available since ROM v1:
00ad SYS_Exec_88 Load serialized vCPU code from ROM and execute
04a7 SYS_Random_34 Get random number and update entropy
0600 SYS_LSRW1_48 Shift right 1 bit
0619 SYS_LSRW2_52 Shift right 2 bits
0636 SYS_LSRW3_52 Shift right 3 bits
0652 SYS_LSRW4_50 Shift right 4 bits
066d SYS_LSRW5_50 Shift right 5 bits
0687 SYS_LSRW6_48 Shift right 6 bits
04b9 SYS_LSRW7_30 Shift right 7 bits
04c6 SYS_LSRW8_24 Shift right 8 bits
06a0 SYS_LSLW4_46 Shift left 4 bits
04cd SYS_LSLW8_24 Shift left 8 bits
04e1 SYS_VDrawBits_134 Draw 8 vertical pixels
06c0 SYS_Unpack_56 Unpack 3 bytes into 4 pixels
04d4 SYS_Draw4_30 Copy 4 pixels to screen memory
00f4 SYS_Out_22 Write byte to hardware OUT register
00f9 SYS_In_24 Read byte from hardware IN register
02e9 SYS_NextByteIn_32 Receive next byte and put in load buffer
06e7 SYS_PayloadCopy_34 Copy byte from load buffer to RAM destination
Added in ROM v2:
0b00 SYS_SetMode_v2_80 Set video mode 0..3
0b03 SYS_SetMemory_v2_54 Set 1..256 bytes of memory to value
Added in ROM v3:
0b06 SYS_SendSerial1_v3_80 Send data out over game controller port
0c00 SYS_Sprite6_v3_64 Draw sprite of 6 pixels wide and N pixels high
0c40 SYS_Sprite6x_v3_64 Draw sprite mirrored in X direction
0c80 SYS_Sprite6y_v3_64 Draw sprite upside down
0cc0 SYS_Sprite6xy_v3_64 Draw sprite mirrored and upside down