* Introduction

This repository provides two utilities for the [[https://github.com/MiSTer-devel/TI-99_4A_MiSTer][TI-99/4a core]] 
which is part of the [[https://github.com/MiSTer-devel][MiSTer]] FPGA project. 

Currently the TI core requires loading roms in the correct order which is a
tedious process. The Python program createImage.py takes care of this job.
It checks the respective C, D and G roms for availability and 
packs them into a single memory image (aka "full rom") file with
the necessary padding applied. The utility works with the latest version of the
TI core (Ti994a.rbf) and Python (Python 3.6 or newer).

While this is fast and easy for testing a small number of rom files, converting a larger
number (or even hundreds) of files is still a lengthy task.
Here the program convertArchive.py comes in handy. It takes a whole directory
of rom files and batch converts them into memory images. To be processed
correctly the file names have to comply with one of the specific formats 
used in the rom archives available (e.g. Timrad or Tosec).

* Usage

** createImage

Usage of createImage is quite simple: Specify the OutputFile and the optional 
Crom, Drom and Grom parameter. Support for disk I/O is enabled with -d,
for speech with -s. More verbose messages are generated with -v, MD5 checksums
are generated with -c and help is available with -h. See the section Tests for examples.

The easiest way to start is with an empty image. Besides the python utilities
in this repository you'll need two files ("994AGROM.BIN" and "994AROM.BIN") 
containing the TI-99/4a firmware. These files are not open-sourced but some
people provide them for download. Just google - but make sure to get the right
versions:

#+BEGIN_SRC sh
994AROM.BIN, MD5 Checksum: 6cc4bc2b6b3b0c33698e6a03759a4cab
994AGROM.BIN, MD5 Checksum: ed8ff714542ba850bdec686840a79217
#+END_SRC

To use disk I/O or the speech synthesizer additional rom files are
needed:

#+BEGIN_SRC sh
Disk.Bin, MD5 Checksum: 3169cfe66687d5b9ed45a69da5a12817
Spchrom.bin, MD5 Checksum: 7adcaf64272248f7a7161cfc02fd5b3f 
#+END_SRC

Note the correct case of the file names.

** convertArchive

Once createImage is set up correctly, convertArchive can be used
to convert a full directory of C, D and G roms. The necessary parameters
are almost the same except for imagePath,  the directory where the memory image
files are created. This defaults to romPath but it's a good idea to create a
directory upfront to store the newly created files in. The scheme used
in the archive for naming the files can be specified with the -n option.
The following schemes are currently supported:

    |----------+------------------------------------------------------------+----------------|
    | Scheme   | Input File Name                                            | Cartridge Name |
    |----------+------------------------------------------------------------+----------------|
    | None     | Ant-eater.C                                                | Ant-eater      |
    | Standard | A-Maze-Ing (1980)(Texas Instruments)[PHM 3030].G           | A-Maze-Ing     |
    | Timrad   | TunDoomG.Bin                                               | TunDoom        |
    | Tosec    | Parsec (1982)(Texas Instruments)(File 1 of 2)(Parsecc).bin | Parsec         |
    |----------+------------------------------------------------------------+----------------|

An output listing can be generated with -l output.txt. The process to
convert several hundred files usually takes less than a second.

So a sample usage would be

#+BEGIN_SRC sh
convertArchive.py --systemromPath sysRom --romPath romArchive --imagePath images  -v 
#+END_SRC

* Tests

The script was successfully tested with the following roms:

    |------------------------+-----------------------------------------------------------------------------------------------|
    | Cartridge Name         | Command                                                                                       |
    |------------------------+-----------------------------------------------------------------------------------------------|
    | Standard, no Cartridge | createImage.py -v defaultRom.bin                                                              |
    | Diagnostic Tests       | createImage.py -v --Grom=DiagnosG.Bin diagnosticTests.bin                                     |
    | Extended Basic         | createImage.py -v --Crom=TIEXTC.BIN --Drom=TIEXTD.BIN --Grom=TIEXTG.BIN extendedBasic.bin     |
    | TI Logo II             | createImage.py -v --Crom=LOGOC.BIN --Grom=LOGOG.BIN Logo.bin                                  |
    | Hunt the Wumpus        | createImage.py -v --Grom=WUMPUSG.BIN HuntTheWumpus.bin                                        |
    | Parsec                 | createImage.py -v --Crom=PARSECC.BIN --Grom=PARSECG.BIN Parsec.bin                            |
    | Tunnels of Doom        | createImage.py -v --Grom=TunDoomG.Bin TunnelsOfDoom.bin                                       |
    | Fathom                 | createImage.py -v --Crom=FATHOMC.BIN --Drom=FATHOMD.BIN --Grom=FATHOMG.BIN Fathom.bin         |
    | Mini Memory            | createImage.py -v --Crom=MiniMemC.Bin --Grom=MiniMemG.Bin MiniMemory.bin                      |
    | Home Finance           | createImage.py -v --Grom=HomFDecG.Bin HomeFinance.bin                                         |
    | Hustle                 | createImage.py -v --Grom=HustleG.Bin Hustle.bin                                               |
    | TI-Editor-Assembler    | createImage.py -v --Grom=TIEAG.BIN TI-Editor-Assembler.bin                                    |
    | A-Maze-ing             | createImage.py -v --Grom=AMAZEG.BIN a-maze-ing.bin                                            |
    |------------------------+-----------------------------------------------------------------------------------------------|

To make debugging easier I've also added MD5 checksums for all input and the output file.
The checksums are enabled with -c (which also enables -v to make any sense).

* Limits

Currently there is support for DiskIO and for Speech - but only in theory, i.e. it is completely untested
since the TI-99 core doesn't support it yet (as of May 2021).

* Updates

- 20.05.2021  Version 2.2  Converted to pathlib, refactoring
- 16.10.2019  Version 2.1  Support for different naming schemes and simulation
- 30.09.2019  Version 2.0  Enabled disk I/O and speech support
- 26.09.2019  Version 1.95 Standard file names and experimental diskIO support
- 25.09.2019  Version 1.9  Generate listing of cartridges (txt and csv format)
- 25.09.2019  Version 1.85 Removed 'holeX' files, more verbose output
- 24.09.2019  Version 1.8  Byte precise padding, more flexible naming scheme for input files
- 07.08.2019  Version 1.7  Removed Python 2 support due to end-of-life
- 27.07.2018  Version 1.6  Code refactoring: Allow use as a library
- 25.07.2018  Version 1.5  Support for romPath, systemromPath and MD5 checksums
- 21.07.2018  Version 1.1  Added Python 2 Support and Updated ROM List