gigatron/rom/Contrib/at67

gtemuAT67

gtemuAT67 is an emulator, a cross assembler for both vCPU and Native asm code, a debugger, a monitor
and a real time controller for Gigatron TTL hardware; written in C++ using SDL2.
This project provides support for Microsoft Windows and should be compatible with Linux, MacOS
and possibly even Android. As of v0.8.17 it has been tested on Microsoft Windows10, some flavours of Linux and MacOS.

Features

• Can control real Gigatron hardware through an Arduino interface.
  
• Can upload vCPU, GCL and GT1 files to real Gigatron hardware through an Arduino interface.
  
• Emulates a PS2 Keyboard for vCPU, GCL code that can use PS2 hardware, such as WozMon.gt1
  
• Variable timing from a minimum of 60FPS up to whatever your PC can handle.
  
• Synchronisation of audio with video at any FPS at or above 60FPS.
  
• Gigatron TTL emulator using SDL2, tested on Windows 10 x64, compiled with VS2017.
  
• Supports fullscreen optimised rendering.
  
• Supports Gigatron TTL input buttons.
  
• Supports Gigatron TTL LED display.
  
• Supports Gigatron TTL audio channels.
  
• Supports Gigatron TTL loading of external vCPU code with a file browser.
  
• Displays Gigatron TTL IN and XOUT registers.
  
• Displays memory monitor of RAM, (RAM is editable), ROM0 and ROM1 at any start address.
  
• Displays read only contents of vCPU variable space.
  
• Can execute hand crafted code within the Hex Editor.
  
• Three separate editable start addresses are provided; memory display address,
  vCPU vars display address and load start address.
  
• A built in assembler can now assemble vCPU as well as Native mnemonics.
  
• A preprocessor that is able to include files and expand parameterised macros.
  
• A debugging mode that lets you pause the simulation or single step through vCPU code.
  
• Upload assembled vCPU code to RAM.
  
• Upload assembled Native code to ROM, (emulation only).
  
• Supports the Gigatron TTL's .gt1 object file format.
  
• An inbuilt file and directory browser for uploading.
  
• Multiple scanline disable options, (default key F3, emulation only), will disable scanlines
  offering large amounts of extra processor time for vCPU code.
  
• Input keys easily configurable through an INI file.
  
• On screen help menu, (accessible with 'H/h' by default), that fully explains each key and it's function.
  
• Optional configuration files, "graphics_config.ini", "input_config.ini", "loader_config.ini" and
  "high_scores.ini".
  
• You may now start the executable anywhere, the default ROM file and default font are now built into the
  executable.
  

YouTube

https://www.youtube.com/channel/UCIDqjK ... ewAtLbfwQ/

References

• Gigatron TTL Home: https://gigatron.io/
  
• Gigatron TTL Forums: https://forum.gigatron.io/index.php
  
• Gigatron TTL Repo: https://github.com/kervinck/gigatron-rom
  
• SDL2 graphics: https://github.com/kervinck/gigatron-rom/pull/1
  
• Early Gigatron emulation: http://talkchess.com/forum/viewtopic.php?t=65944&start=11
  
• Dirent for Windows: https://github.com/tronkko/dirent
  
• Recursive Descent Parser: https://stackoverflow.com/questions/9329406/evaluating-arithmetic-expressions-from-string-in-c
  
• INI Not Invented Here: https://github.com/jtilly/inih
  
• rs232: https://github.com/Marzac/rs232
  

Contributors

• at67 https://github.com/at67
  
• kervinck https://github.com/kervinck
  
• Cwiiis https://github.com/Cwiiis
  
• xxxbxxx https://github.com/xxxbxxx
  

Building

• CMake 3.7 or higher is required for building, has been tested on Windows with Visual Studio and gcc/mingw32
  and also built and tested under Linux.
  
• A C++ compiler that supports modern STL.
  
• Requires the latest version of SDL2 and it's appropriate include/library/shared files.
  
• For detailed instructions for Windows, Linux and macOS, see this thread in the Gigatron forum:
  https://forum.gigatron.io/viewtopic.php?p=368#p368
  

Windows

  Download and install cmake
  Download sdl2 development libraries https://www.libsdl.org/download-2.0.php
  Clone or download https://github.com/kervinck/gigatron-rom
  cd gigatron-rom\Contrib\at67
  cmake .

• Open gtemuAT67.sln into Visual Studio, compile and execute.
  
• Optional: if you want to be able to develop using SDL2 without having to configure the include and lib variables
  for each new project, then add an environment variable SDL2DIR pointing to the directory you installed SDL2 into.
  

Linux

  sudo apt-get -y install cmake libsdl2-dev
  git clone https://github.com/kervinck/gigatron-rom
  cd gigatron-rom/Contrib/at67
  cmake .
  make
  ./gtemuAT67 &

Installation

• After building, copy the executable and SDL2 shared library/DLL to an appropriate directory;
  run the executable from there.
  
• The default ROM file and default font are now built into the executable., (thanks to Cwiiis for
  the idea). The only dependency is the shared library/DLL from SDL2 that either must be in the current
  working directory path or in the appropriate system directory.
  

Configuration

• The emulator may be placed anywhere in any directory as long as it has access to the SDL2 shared library.
  
• The emulator will search for and use a file named "graphics_config.ini" in it's current
  working directory. This file allows the emulator's graphics and video options to be completely user
  configured:
  

  Fullscreen = 1, will create a full sized screen that minimises when it loses focus
  Fullscreen = 0, will create a window that does not minimise when it loses focus

• The emulator will search for and use a file named "input_config.ini" in it's current
  working directory. This file allows the emulator's keys to be completely user configured. The on
  screen help menu also uses this file to display help instructions. See the file for help on input
  configuration.
  

• The emulator will search for and use a file named "loader_config.ini" in it's current
  working directory. This file allows the emulator's com port to be user configured for communicating
  with real Gigatron hardware through an Arduino adapter. Custom ROM's are also supported:
  

  BaudRate    = 115200   ; arduino software stack doesn't like > 115200
  ComPort     = COM3     ; can be an index or a name, eg: ComPort = 0 or ComPort = COM5
  Timeout     = 5.0      ; maximum seconds to wait for Gigatron to respond
  GclBuild    = D:/Projects/Gigatron TTL/gigatron-rom ; must be an absolute path, can contain spaces
  RomName     = ROMv1.rom  

• The emulator will search for and use an optional file named "high_scores.ini" in it's current
  working directory. This file allows the emulator to load and save segments of memory and have them
  regularly updated, (can be used for debugging, replays, high scores, etc), see the file for help.
  Files ending in .dat will be created in the current working directory of the emulator for
  every entry that is made and successfully parsed within "high_scores.ini". These .dat
  files contain the individual memory segments loaded and saved to disk for each game/application.
  

Controls

Key	Function
CTRL + H	Displays a help screen showing the currently configured keys.
CTRL + Q	Quits the application.
CTRL + R	Switches between ROM types, (v1 to v4 are built in).
L or l	Loads external vCPU files within the vCPU directory, this code is uploaded to
	an editable load address. Loading user vCPU code to system critical addresses
	can cause the emulator to hang, 0x0200 is guaranteed to be safe.
R or r	Switches Hex Editor between RAM, ROM(0) and ROM(1).
CTRL + F1	Fast reset, performs the same action as a long hold of Start.
ALT + F1	Fast reset of real Gigatron hardware, if connected to an Arduino interface.
CTRL + F3	Toggles scanline modes between, Normal, VideoB and VideoBC, only for ROMv1.
CTRL + F5	Executes whatever code is present at the load address.
CTRL + F6	Toggles debug mode, simulation will pause and allow you to single step using F7.
CTRL + F7	Only functions in debug mode, will single step the simulation based on a memory
	location changing it's value.
CTRL + F9	switches to Hex mode from any other mode
CTRL + F10	Toggles PS2 keyboard emulation on and off.
CTRL + F11	Toggles Gigatron input between emulator and hardware.
CTRL + F12	Toggles PS2 keyboard emulation between emulator and hardware
CTRL + CR	Loads vCPU code if editor is in file browse mode, otherwise switches to edit mode.
ALT + CR	Uploads vCPU code to real Gigatron hardware, if connected to an Arduino interface.
-/+	Decrease/increase the speed of the emulation, from a minimum of 60FPS to a
	maximum determined by your PC's CPU.
Left	Navigate the Hex editor one byte at a time or the file browser one file at a time.
Right
Up/Down
PgUp	Scroll the hex editor and file browser one page at a time.
PgDn
Mouse Wheel	Scroll the hex editor and file browser one line/file at a time.
D or d	Right.
A or a	Left.
W or w	Up.
S or s	Down.
SPACE	Start.
Z or z	Select.
/	B.
.	A.

Assembler

• The assembler is built into the executable, there are no makefiles or command line programs to
  run. All you have to do is load the .vasm file within the file browser, (press L to enable
  the browser), upon loading your file will automatically be assembled and any errors printed to
  stderr. If there are no errors then a .gt1 file will automatically be produced as long as there is
  no native code within the .vasm file; the code is then executed within the Gigatron CPU emulator.
  
• The assembler is able to assemble vCPU as well as native code.
  
• GCL code is now able to be compiled and uploaded to the emulator or real hardware as long as you have Python 2.7
  installed, see README.md in Contrib/at67/gcl for details.
  
• vCPU code is assembly code that is variable length Von Neumann instructions supporting 16bit operations
  that are executed by the inbuilt interpreter of the Gigatron TTL firmware and are stored in RAM.
  
• Native code is based on a Harvard Architecture that exists only in ROM on both the Gigatron TTL
  hardware and within the emulator.
  
• The ROM code on the Gigatron TTL hardware is currently not modifiable without an EPROM programmer,
  but the ROM within the emulator is able to be modified and experimented with, which this assembler
  lets you do very easily.
  
• The Assembler differentiates between the two instruction sets, (vCPU and Native), by preceding
  Native instructions with a period '.'
  
• The Assembler supports Labels, Equates, Expressions and self modifying code.
  
• The Assembler recognises the following reserved words:
  
  • _startAddress_ : entry point for the code, if this is missing defaults to 0x0200.
    
  • _callTable_ : grows downwards as you use more CALL's, it must exist in page 0 RAM.
    
  • _singleStepWatch_ : the single step debugger watches this variable location to decide when to step.
    
  • _disableUpload_ : disables all writes to RAM/ROM, used for testing and verification.
    
  • _cpuUsageAddressA_ : the start of a vCPU exclusion zone for measuring vCPU load, (emulation only).
    
  • _cpuUsageAddressB_ : the end of a vCPU exclusion zone for measuring vCPU load, (emulation only).
    
• The Assembler recognises the following reserved opcodes:
  
  • DB : Define Byte, a string of 8bit bytes declared within the source code that are written to RAM.
    
  • DW : Define Word, a string of 16bit words declared within the source code that are written to RAM.
    
  • DBR : Define Byte, a string of 8bit bytes declared within the source code that are written to ROM.
    
  • DWR : Define Word, a string of 16bit words declared within the source code that are written to ROM.
    
• Numeric literals can be of any of the following format:
  
  • hex : 0x0000 or $0000
    
  • dec : 1234
    
  • oct : 0o777 or 0q777
    
  • bin : 0b01011111
    
• Comments can go anywhere on a line and commence with ';' or '#'
  
• You can include files into your projects using the %include command.
  
• A fully parameterised macro system has been added that can expand in place code using the %MACRO and
  %ENDM commands.
  

Debugger

• The debugger allows you to single step through your vCPU code based on a variable changing
  its value. This variable by default is videoY located at address 0x0009, it counts horizontal
  scan lines and thus should give decent resolution for most .vasm and .gt1 files.
  
• The variable can be altered within a .vasm file like this:
  

_singleStepWatch_   EQU     xyPos

• In this example xyPos is a pointer into zero page memory, pointing to a variable that changes
  its value often.
  
• F6 toggles debugging on and off and may be used as a pause or freeze.
  
• F10 single steps the currently loaded code based on the singleStepWatch variable.
  
• All other keys function normally as in the main editor mode, except for L, F1
  and F5 which are ignored.
  
• Real time logging with the gprintf command, (similar syntax to the standard printf); this feature
  allows you to print any variable, label or expression to stderr whilst the emulator is running vCPU
  code. The vPC address of the current instruction that the gprintf aligns with is used to decide when to
  send the logging information to the console as the vCPU code is interpreted in real time.
  

  gprintf("%c %d $%04x $%04x $%04x b%016b b%08b o%04o $%04x %s", 48, 45000, 0xDEAD, 0xBEEF,
                                                                 resetLevel, frameCountPrev, 
                                                                 *frameCounter, maxTicks + 1,
                                                                 vBlank, *level_string)

• Indirection is specified using '*' to access and print the variable's data.
  
• You can specify field width, fill chars and use the same numeric literals as the rest of the Assembler. e.g:
  
  • %c will print a char.
    
  • %d will print an int.
    
  • %04x will print a zero padded four digit hex number.
    
  • %016b will print a zero padded 16 digit binary number.
    
  • %04o will print a zero padded 4 digit octal number.
    
  • %s will print a maximum 255 sequence of chars, with the first byte of the string expected to be the length.
    

MIDI

• See gtmidi and README.md in the Contrib/at67/midi directory.
  

Tools

• The following command line tools that break out some of the functionality of the emulator are contained within
  the following folder, Contrib/at67/tools, see their respective README.md files for detailed documentation:
  
  • gtasm: can assemble .vasm assembly code into a .gt1 file.
    
  • gt1torom: splits a .gt1 file into two separate .rom files, one for data and one for instructions.
    
  • gtmakerom: takes a normal 16bit Gigatron ROM and merges split .gt1 roms into it.
    
  • gtsplitrom: takes a normal 16bit Gigatron ROM and splits it into data and instruction .rom files.
    

Memory and State saving

• Real time saving of Gigatron and applications/games memory and state without any involvement of software
  on the Gigatron, (it's firmware or it's applications). This generic interface is controlled with INI
  files, (see "high_scores.ini" for an example.

Errors

• All error reporting is sent to stderr, under Windows a separate console is opened, (that is
  probably hiding under the main display), that will contain any error messages.
  

Limitations

• RAM is modifiable between 32K and 64K, any other value causes the simulation to fail.
  
• Controls and VSync are modifiable in the code, VSync currently seems to have little value
  as an option as the main loop is synchronised using the performance counters.
  

TODO

• Build and test on Android.