Skip to content

Latest commit

 

History

History
305 lines (284 loc) · 17.4 KB

README.md

File metadata and controls

305 lines (284 loc) · 17.4 KB

Software for Gigatron ROM

Important files

gigatron-rom
 +--- LICENSE                   2-Clause BSD License
 +--- Makefile                  Marcel's Makefile
 +--- Core/                     Gigatron kernel and build tools
 |     +--- dev.asm.py          Development ROM (type 'make' to build):
 |     |                        Video/audio/io/kernel loops and cold storage
 |     |                        for applications and data ("kernel + ROM disk")
 |     +--- ROMv6.asm.py        Source for release ROM v6 (most recent release)
 |     `--- 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/Blinky.gcl   Very simple GCL program
 |     `--- HelloWorld/         Program that draws "Hello world" on screen
 +--- BASIC/                    Example BASIC programs
 +--- Utils/
 |     +--- BabelFish/          Generic Arduino sketch for talking with Gigatron
 |     +--- gt1dump.py          Dump or disassemble GT1 files
 |     +--- lcc/                LCC compiler with vCPU backend (NOT YET STABLE)
 |     `--- sendFile.py         Send GT1 or BASIC file from laptop/PC
 +--- Libs/                     C libraries for Gigatron programs
 |     `--- Example.c           Example C program
 +--- Docs/
 |     +--- GCL-language.txt    Gigatron Control Language and vCPU explanation
 |     +--- GT1-files.txt       vCPU object file format and ROM versioning
 |     +--- gtemu.c             Instruction set definition (as executable code)
 |     +--- vCPU-summary.txt    Overview of 16-bit virtual CPU instruction set
 |     `--- ...                 All on video, audio, native code, versioning...
 `--- Contrib/                  Contributions outside the kit's ROM and tooling:
       +--- at67/               BASIC compiler, emulator, 8-bit/16-bit
       |                        assembler/disassembler, debugger, MIDI music,
       |                        demos and games
       +--- Crouze/             TinyBASIC scripts (including graphclock.gtb)
       +--- Cwiiis/             Gigatris game
       +--- delpozzo/           VideoPoker game; Tools (CustomFish, sendFile)
       +--- dhkolf/             Fast emulator; Demos (SprPaint, PianoBeep,...)
       +--- flok99/             Simple (and slow) visualizer using SDL2
       +--- gigawalt/           Walter's script
       +--- kervinck/           Ramblings (all work in progress)
       +--- makerspace48/       C examples, Prime.c and ASCII-mandelbrot.c
       +--- PhilThomas/         Javascript-based Gigatron emulator
       +--- pkupper/            Pluggy Reloaded's Babelfish (to be merged back)
       +--- tbraun-de/          Gigatron Mac; Python port of gtemu.c; maze.gt1
       +--- xopr/               NetTerm: Terminal program for SPI interface
       `--- xxxbxxx/            Bricks game; RPi port of BabelFish; frogstroll

Files generated by ROMv6.asm.py

See Makefile for how to make these.

ROMv6.lst                       Generated listing with disassembly, labels,
                                comments and source (large!)
ROMv6.rom                       ROM file for 27C1024 (PCB versions)

Memory map (RAM)

              0 1          53 54     127 128 129         (vSP)       255
             +-+-------------+-----------+-+-------------+--------------+
page 0       |0| System vars | User vars |1| User vars <-| Stack/Loader |
             +-+-------------+-----------+-+------+------+--+-----------+
page 1       | Video table                        | vReset  | Channel 1 |
             +------------------------------------+---------+-----------+ ---
page 2       |0                                239 240   249| Channel 2 |  ^
             |                                              +-----------+  |  Also see
page 3       |                                              | Channel 3 |  |  channelMask
             |                                              +-----------+  |
page 4       |            User vCPU code and/or data        | Channel 4 |  v
             |                                              +-----------+ ---
page 5-6     |                                               250     255|
             |                                                          |
             |                                               <- C stack |
             +----------------------------------------------------------+
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 | - Gigatron 32K: mirrors pages 0-127                      |
             | - Gigatron 64K: additional 32KB or RAM                   |
	     | - Gigatron with RAM&IO expansion: banked memory          |
	     |   | bank 0       mirrors page 0-127                      |
             |   | banks 1,2.3  three additional banks of 32K RAM       |
             +----------------------------------------------------------+
              0                                                      255

[Note: In the next section, names in parentheses refer to *internal*
variables that are subject to change between ROM versions. See for a
more detailed explanation on compatibility the file Docs/GT1-files.txt]

Address   Name          Description
--------- ------------- -----------
0000      zeroConst     Constant value 0 (for arithmetic carry)
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      (reserved)    Reserved (Video extensions? MMU? v8808? ...?)
0005      (vCpuSelect)  Entry page of active interpreter (offset fixed to 255)
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 (used for edge detection)
0011      buttonState   Edge-triggered and resettable input bits
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
0018      v6502_A       [v6502] Accumulator
0019      (v6502_BI)    [v6502] B Input Register (used by SBC)
001a-001b vLR           Return address, for returning after CALL
001a-001b v6502_PC      [v6502] Program Counter
001c      vSP           Stack pointer
001c      (v6502_S)     [v6502] Stack Pointer (kept as "S+1")
001d      (vTmp)        Scratch storage location for vCPU and v6502
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       ROM v1:$1c v2:$20 v3:$28 v4:$38 v5a:0x40 v6:0x48 DEV:$f8
0021      channelMask   Low bits set active channels (x011->4, x001->2, x000->1)
0022-0023 sysFn         Address for SYS function call
0024-002b sysArgs       Arguments for SYS functions
0024      (v6502_ADL)   [v6502] Low Address Register
0025      (v6502_ADH)   [v6502] High Address Register
0026      (v6502_IR)    [v6502] Instruction Register
0027-0029 (v6502_P)     [v6502] Processor Status Register
002a      v6502_X       [v6502] Index Register X
002b      v6502_Y       [v6502] Index Register Y
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 (ROM<=v4)
0030-0035 (vIrqSave)    (v5+) vIRQ saved registers
0036-007f userVars_v5   Program variables (ROM v5)
0036-007f userVars_v6   Program variables (ROM v6)
0080      oneConst      Constant value 1 (for arithmetic carry)
0081-.... userVars2     More space for program variables
....-00ff <stack>       Call and value stack for vCPU (also used by ROM loader)
0100-01ef videoTable    Video indirection table (Y0,dX0,Y1,dX1,Y2,...,dX119)
01f0-01f5 vReset        vCPU routine to load and start Reset sequence
01f6-01f7 vIRQ_v5       (v5) Pointer to vCPU vIRQ handler
01f8      ctrlBits_v5   (v5) RAM and IO expansion control word
01f9      videoTop_v5   (v5) Blank top of screen. Must be even in [0..238].
01fa      wavA[1]       Sound channel 1: Waveform modulation with `adda'
01fb      wavX[1]       ...............: Waveform modulation with `xora'
01fc      keyL[1]       ...............: Frequency low 7 bits (bit7 == 0)
01fd      keyH[1]       ...............: Frequency high 8 bits
01fe      oscL[1]       ...............: Phase low 7 bits
01ff      oscH[1]       ...............: Phase high 8 bits
0200-02f9 userCode      vCPU code/data (default start of user code)
02fa      wavA[2]       Sound channel 2: Waveform modulation with `adda'
02fb      wavX[2]       ...............: Waveform modulation with `xora'
02fc      keyL[2]       ...............: Frequency low 7 bits (bit7 == 0)
02fd      keyH[2]       ...............: Frequency high 8 bits
02fe      oscL[2]       ...............: Phase low 7 bits
02ff      oscH[2]       ...............: Phase high 8 bits
0300-03f9 -             vCPU code/data
03fa      wavA[3]       Sound channel 3: Waveform modulation with `adda'
03fb      wavX[3]       ...............: Waveform modulation with `xora'
03fc      keyL[3]       ...............: Frequency low 7 bits (bit7 == 0)
03fd      keyH[3]       ...............: Frequency high 8 bits
03fe      oscL[3]       ...............: Phase low 7 bits
03ff      oscH[3]       ...............: Phase high 8 bits
0400-04f9 -             vCPU code/data
04fa      wavA[4]       Sound channel 4: Waveform modulation with `adda'
04fb      wavX[4]       ...............: Waveform modulation with `xora'
04fc      keyL[4]       ...............: Frequency low 7 bits (bit7 == 0)
04fd      keyH[4]       ...............: Frequency high 8 bits
04fe      oscL[4]       ...............: Phase low 7 bits
04ff      oscH[4]       ...............: Phase high 8 bits
0500-05ff -             vCPU code/data
0600-06ff -             vCPU code/data
0700-07ff soundTable    Interlaced waveforms (metal, triangle, pulse, sawtooth)
0800-7fff screenMemory  Default pages for screen memory
0800-089f -             Pixel line 0
08a0-08ff -             vCPU code/data
.........
7f00-7f9f -             Pixel line 119
7fa0-7fff -             vCPU code/data
--------- ------------- -----------

Memory map (ROM)

             +----------------------------------------------------------+  ---
$0000        | Boot and reset sequences                                 |   ^
             +----------------------------------------------------------+   |
$0100        | Video and audio loop (vertical blank lines)              |   |
             |                                                          |   |
$0200        | Video and audio loop (visible lines)                     |   |
             +----------------------------------------------------------+   |
$0300        | vCPU interpreter loop (primary page)                     |   |
             |                                                          |   |
$0400        | vCPU extended instructions (and some SYS functions)      |   |
             +----------------------------------------------------------+   |
$0500        | Shift tables                                             |   |
             |                                                          |   |  Core system
$0600        | SYS functions (LSRW and others)                          |   |  Kernel and drivers
             +----------------------------------------------------------+   |
$0700        | Font table (ASCII 32..81)                                |   |
             |                                                          |   |
$0800        | Font table (ASCII 82..126 and symbols 127-131)           |   |
             |                                                          |   |
$0900        | Notes table (C-0..A#7)                                   |   |
             |                                                          |   |
$0a00        | Inversion table                                          |   |
             +----------------------------------------------------------+   |
$0b00        | SYS functions (SendSerial, Sprites, SPI, ...)            |   |
             |                                                          |   |
$0d80-$11ff  | v6502 secondary interpreter                              |   |
             |                                                          |   |
$1200-$1241  | More proceesing during vertical blank lines              |   |
             |                                                          |   |
$1242-$14ff  | More SYS functions                                       |   |
             |                                                          |   v
             +==========================================================+  ---
             |                                                          |   ^
             | ROM tables: Embedded high-resolution images (packed)     |   |
             |                                                          |   |  Applications /
$1500-$ffff  | Include files: application-specific SYS functions        |   |  cold storage
             |                                                          |   |
             | ROM files: Embedded vCPU/v6502 applications (serialized) |   |
             |                                                          |   v
             +----------------------------------------------------------+  ---
              0                                                      255

SYS functions (ROM)

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 port

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

Added in ROM v4:

0b09    SYS_ExpanderControl_v4_40       Set register in I/O and RAM expander
0b0c    SYS_Run6502_v4_80               Execute MOS 6502 code until BRK
0b0f    SYS_ResetWaveforms_v4_50        Setup sound tables in page 7
0b12    SYS_ShuffleNoise_v4_46          Shuffle noise table in page 7
0b15    SYS_SpiExchangeBytes_v4_134     Send and receive bytes

Added in ROM v5a:

00ef    SYS_ReadRomDir_v5_80            Navigate ROM directory

Added in ROM v6:

009e    SYS_Multiply_s16_v6_66          16 bits multiplication (from at67)
00a1    SYS_Divide_s16_v6_80            15 bits unsigned division (from at67)
00e6    SYS_ScanMemory_v6_50            Search byte in memory region
00e9    SYS_CopyMemory_v6_80            Copy memory region
00ec    SYS_CopyMemoryExt_v6_100        Copy memory across RAM extension banks
0b18    SYS_ReceiveSerial1_v6_32        Receive byte on input port (for the loader)