Author: Marc Rousseau

TI-99/Sim

a Texas Instruments Home Computer Emulator

NOTE: This page designed to use CSS styles - you may want to upgrade your browser.

Introduction

Getting Started

Building

Installation

Overview

General Features

Graphics Support

Sound Support

Speech Synthesis

Joystick Support

Disk Support

Included Programs

convert-ctg

decode

disk

dumpcpu

dumpgrom

mkspch

ti99sim-console

ti99sim-sdl

# Introduction

This is the latest incarnation of an emulator for the TI-99/4A that I've been working on for a few years. At first it was a simple text-based simulation of the TI (ti99sim-console) running under DOS™. Then I added graphical support for the OS/2 Presentation Manager. Later, I ported it to Windows and added sound support. Now I'm porting it to Linux and hope to add a few more features along the way.

DISCLAIMER: I'm not one for writing a lot of documentation, so you're encouraged to look at the code to see how some things work if they're not described here. If you're interested in writing documentation, let me know.

NOTE: In order to run the emulator, you need to create a cartridge that contains the console ROM & GROMs from the TI-99/4A. Texas Instruments will not allow these to be distributed, so you'll need to find a way to get them yourself. If you have a working copy of v9t9, instructions are included to help you create the required cartridge. If you don't, I would suggest you download it as it contains documentation on how to get the files you need to do this.

# Getting Started

Before building or running TI-99/Sim you must install the SDL library. The latest version is available at http://www.libsdl.org/download-1.2.html. If you are planning on building TI-99/Sim, you will need to install the Development Runtime version otherwise, the Binary Runtime package is sufficient.

NOTE: For the time being, if you are going to build the Win32 version, you will need to extract SDL_main.o from libSDLmain.a (type: ar -x libSDLmain.a SDL_main.o) as well (until I can figure out why libSDLmain.a isn't linking correctly with the mingw tools).

## Building

If you downloaded the binary-only version, you can skip straight to Installation. If you're building the Win32 version, you'll need either a GNU-type environment (GNU make, g++, ld, rm, ...) or Microsoft Visual C++ v6.0. The only GNU-type environment that I've tested is the mingw package, but others may work as well. You will also need to make sure you define the WIN32 environment variable before building (type set WIN32=1 at the command prompt). When you're ready, just type make in the directory where you placed the emulator.

              set WIN32=1 # For Win32 builds only
              make

If everything is installed properly, this will build all the executables found in the binary-only package.

NOTE: When building from the source, all the executables are left in their corresponding directories.

## Installation

### The Directories

Installing the emulator is easy. Make sure you have sufficient priveledges to create/write to the installation directories and type:

                make install

This will create the default directories and install the binaries. The binaries will be installed in /usr/local/games/ti99sim and the directory /usr/local/share/games/ti99sim will be created. When loading files (ROMs, cartridges, disk images, …), ti99sim will look in the current directory, ~/.ti99sim, and finally, /usr/local/share/games/ti99sim. Under Windows, the search is limited to the current directory followed by the directory specified in the environment variable HOME (if it is defined at all). In each of the directories searched, the following sub-directories may exist:

                ─┬─ cartridges
                 ├─ disks
                 └─ roms

When looking for a file, the appropriate sub-directory for that file type will be searched. If there is no logical directory for a given file, only the base directory will be searched.

### The Console ROM & Cartridges

Once you've run make install, you will need to create the console ROM cartridge TI-994A.ctg (see convert-ctg below for instructions) in order to run the emulator. This ROM cartridge contains the operating system, the BASIC interpreter, and a description of the RAM configuration for the computer. Without it, the emulator will not do anything useful. Once you have created the console ROM cartridge, copy it to either ~/.ti99sim/roms or /usr/local/share/games/ti99sim/roms.

You should also place a copy of spchrom.bin into this directory to enable speech synthesis. If you don't have this file, you can use mkspch to create one that will keep the emulator happy.

If you want to use the disk emulation features, you will need to create another cartridge named ti-disk.ctg that contains a copy of the TI Disk Controller ROM (the section on convert-ctg contains information about creating cartridges for peripheral DSR ROMs).

### Up and Running

Once you have everything set up, you may want to create a symbolic link to ti99sim to make running it easier. On a Red Hat system, you can easily do this by creating a personal bin directory and placing the link there i.e.:

                mkdir ~/bin
                ln -s /usr/local/games/ti99sim/ti99sim-sdl ~/bin/ti99sim
                ln -s /usr/local/games/ti99sim/convert-ctg ~/bin/convert-ctg

Now you're all set to run the emulator, just type:

                ti99sim

If everything is installed correctly, you should see a window on your screen with the TI-99/4A startup screen followed by a beep. Enjoy!

# Overview

The following sections describe the basic features of the emulator. Entries in italics are items on my to-do list for a future release.

## General Features:

- Emulation of the TI-99/4A Home Computer.
- Runs under Linux or Win32 (Windows 9X, Windows NT)
- Speed is kept as close as possible to the actual speed of the TI.
- Supports banked cartridges (like TI Extended BASIC).
- 32K RAM Expansion.
- Save/Restore the complete computer state.
- Save battery-backed RAM to disk when cartridge is removed.
- Add a GUI and port menus/hot-keys/features from Windows version.

## Graphics Support:

- All modes except multi-color.
- Scaled window.
- Full screen mode.
- Multi-color support.
- Hardware sprite co-incidence.

## Sound Support:

- Three voice support using native sound device.
- Noise generation supported.

## Speech Synthesis:

- Access the built-in speech ROM (TI Extended BASIC). NOTE: Requires a speech synthesizer ROM dump (see mkspch if you don't have one).
- Modules with external speech samples (Parsec, Alpiner, Terminal Emulator II, ...).

## Joystick Support:

- Hardware joystick support.
- Emulated joystick using the numeric keypad.

## Disk Support:

- Complete read/write support for floppy disks. NOTE: Requires a TI disk controller ROM dump.
- Supports disk images created by AnaDisk, v9t9, and PC99.
- The disk utility can convert between formats and extract files.

# Included Programs

## convert-ctg

The ti99sim emulator uses special .ctg files to store the ROM and/or GROM images contained within the computer console and plug-in cartridges. The convert-ctg program allows you to create these cartridges. It will convert your existing v9t9 ROMs or create cartridges using output from a hex dump of a ROM image. A set of sample files, TI-994A.dat, Mini-Memory.dat, and Gram Kracker.dat, located in the roms directory, are supplied as examples of the format of the hex dump file. NOTE: These files do not contain complete hex dumps of their corresponding ROMs but can be used as templates if you have the required information.

To convert existing v9t9 cartridges, type convert-ctg foo.bin where foo is the base name of a set of ROM files. The base name is usually the portion of the filenames that are common between all files associated with a particular cartridge. convert-ctg understands the naming conventions used by present and past versions of v9t9, and will attempt to determine which version of files that you have installed. For example, the following command will convert the files PARSECC.BIN and PARSECG.BIN to PARSEC.ctg:

              convert-ctg /your-path-here/v9t9/v6.0/modules/PARSEC.BIN

Files to be converted can be in any directory. The new cartridge will be created in the current working directory. To create the console ROM cartridge you need to specify either 994a.bin or ti.hex (depending on your version of v9t9 or TI Emulator) as the filename. For example:

              convert-ctg /your-path-here/v9t9/v6.0/roms/994a.bin

This will create the special TI-994A.ctg file that contains the console ROM, the system GROMs, scratch-pad RAM, and 32K memory expansion RAM. Without this file, ti99sim will not run!

There are three types of cartridges. The first is the special TI-994A.ctg file, the second are DSR ROMs, and the third are normal cartridges. The first two types are expected to be found in the 'roms' directories, while the last is expected in the 'cartridges' directories.

DSR ROMs are special ROM cartridges that are associated with a particular peripheral device. These cartridges must be associated with a particular CRU address. The ROM in these cartridges is located at a different address than the ROMs normally found in a cartridge and without a CRU address, the CPU won't be able to see the ROM within the cartridge. To create a DSR ROM cartridge, simply use the --cru=xxxx option to convert-ctg. This will instruct convert-ctg to store the ROM at the special DSR memory range, and mark the cartridge with the correct CRU information. In order to use the disk emulation features, you need to create a cartridge from a TI disk ROM with the name ti-disk.ctg with the CRU address 1100.

When creating cartridges, convert-ctg will attempt to add a cartridge title by searching for valid GROM headers in the files being converted. If it doesn't find any valid names, or if you want to change the one it uses, you can specify a title on the command line after the base filename. ti99sim uses the cartridge title when saving/loading memory images to ensure that the correct cartridges are present when loading. If you intend to use this feature, please make sure that all of your cartridges have unique names.

convert-ctg will also allow you to dump the contents of a cartridge to a specially formatted hex dump file. This feature is useful if you want to see the contents of a cartridge's ROM/GROM code, or to patch the code and rebuild the cartridge with your changes.

## decode

If you have old audio tapes hanging around, decode will decode them into binary files that can be used (in some future version) by ti99sim. This code is currently in the experimental stage, and currently only decodes .wav files directly to binary files on disk. It attempts to intelligently find sections of stored data while ignoring all other sounds it finds.

## disk

The emulator allows you to use disks created by a TI-99/4A computer within the emulator. The emulator can read disks created using the dump feature of AnaDisk - with or without the optional 8-byte header for each sector. The latter is the format used by v9t9 disks. The emulator can also read disks that contain raw track data (the format used by PC99). disk can understand both single and double density disk formats.

The disk utility allows you to look at the contents of a disk image and optionally create native files from those in the disk image. This allows you to create files that can be used by convert-ctg to create cartridge files that you can use with the emulator. There are two output formats for files extracted from a disk. The first (default) format is the v9t9 FIAD format. This format contains a 128-byte header that preserves all of the original file information. The second format is a naked file. These files use only a filename extension to convey the original file format. The actual contents of the file are converted to a conventional file as best as possible. Files using this format may be readable on the host computer (normally, DISPLAY type files are readable).

The disk utility can also be used to convert disk images between formats. By specifing --output={anadisk|v9t9|PC99}, a disk image can be converted to any format.

## dumpcpu

This program will allow you to un-assemble any CPU ROM section in a cartridge file, a DISPLAY/FIXED FIAD file, or RAM from a save image file. Through the use of an external configuration file, you can assign labels and EQUs to make the disassembly more readable.

NOTE: This program is a work in progress and doesn't always create good listings.

## dumpgrom

Ever wondered what the code behind that game looks like? This program is similar to dumpcpu but disassembles the GPL code in the GROM cartridge. It uses the standard GROM headers to find starting addresses and strings.

NOTE: This program is a work in progress and doesn't always create good listings.

## mkspch

If you can't find a copy of spchrom.bin, you can use this utility to create one that can be used by the ti99sim. The spchrom.dat file located in the roms directory contains the information required to create a stripped down speech ROM. If you have your own LPC-10 coded speech samples (I have no idea how you would create them, so please don't ask), you can use this utility to create a speech ROM using your own voice samples!

## ti99sim-console

A simple text-based version of the emulator. It includes a simple interface that allows you to step through code at the assembly or GPL instruction level. While the CPU is paused, you can edit any of the register values. Since it's text-mode only, it doesn't support graphics at all. If you just want to see what the computer is doing, this is the program to do it with.

## ti99sim-sdl

The X11 based emulator. It will accept the following command-line syntax:

              ti99sim-sdl [options] [cartrigde.ctg] [memory.img]

              Options:
                 -4                        Double width/height window
                 -f --fullscreen           Fullscreen
                 -q --nosound              Turn off all sound/speech
                 --nospeech                Disable speech synthesis
                 --joystickn=i             Use system joystick i as TI joystick n
                 --dskn=filename           Use 'filename' disk image for DSKn
                 --listjoysticks           Print a list of all detected joysticks
                 --NTSC                    Emulate a NTSC display (60Hz)
                 --PAL                     Emulate a PAL display (50Hz)
                 --framerate={n/d|p}       Reduce frame rate to fraction n/d or percentage p

If you try to load a memory image, you must make sure that any cartridge(s) that were running when the image was made are currently running or the image will not load. So, if you want to load both a cartridge and an image, make sure you specify the cartridge before the image on the command line.

There is no GUI yet. The following keys are defined:

- ESC - exit
- F2 - Save memory image
- F3 - Load memory image
- F10 - Reboot

### Disk support

Using the ti-disk.ctg, the emulator is capable of reading and writing to single-density disk images. The TI disk controller is not capable of accessing double-density disks. Internally, the emulator is ready to support double-density disks, but I don't have access to a controller ROM that supports them, so I haven't been able to test them yet.

The emulator supports all operations on a disk image. When the emulator shuts down, any changes made to the disk image are saved. A disk can be made write-protected by making the file read-only.

NOTE: The disk routines can read and write files in the PC99 format, but disks formated in the emulator by routines other than those in the DSR ROM (like those formatted using a program like Miller Graphics' Advanced Diagnostics) may not be readable by PC99 or other PC99-compatible software.

### RS-232 support

Sorry, this feature is not implemented - yet.

### Gram Kracker™ emulation

If you have created the Gram Kracker cartridge properly and placed the cartridge in the roms directory (the one where you placed the TI-994A.ctg file), the following extra keys are active:

- <Ctrl>-F1 - Toggle Gram Kracker On/Off
- <Ctrl>-F2 - Toggle GROM 0/Operating System
- <Ctrl>-F3 - Toggle GROMs 1&2/TI-BASIC
- <Ctrl>-F4 - Disable write-protect/Select BANK 1
- <Ctrl>-F5 - Enable write-protect
- <Ctrl>-F6 - Disable write-protect/Select BANK 2
- <Ctrl>-F7 - Toggle loader On/Off

Consult your Gram Kracker manual for a description of each of these switches.

To create a Gram Kracker cartridge, the loader ROM must be added to the Gram Kracker.dat file supplied in the roms directory. Getting the loader ROM is left as an exercise for the reader (hints: Save it to disk, transfer it to the PC using AnaDisk, extract it using the disk utility, and a) make a hexdump after stripping off the header or b) create a normal cartridge file using the convert-ctg utility then create a .dat file using the -d option. OR Use the dump feature built into the Edit Memory option of the Gram Kracker loader to send a hex dump to the serial port and capture it on the PC to a disk file).

Homepage: http://www.mrousseau.org/programs/ti99sim/
Contact: ti99sim@mrousseau.org