TI86EMU version .5
Copyright (C) 1998 Steve Gordon (sgordon@mich.com)

------------------------------------------------------------------------------
 INTRO
------------------------------------------------------------------------------

TI86EMU is a free MS Windows based program that emulates your TI-86 calculator
in a window. What separates TI86EMU from other emulators is its full featured
monitor/debugger. These features make it perfect for debugging TI-86 ASM and
BASIC programs on your PC. TI86EMU requires a WIN32 platform (WIN95 or
WINNT) although I havent tested it on WINNT. Source code will probably be
released at version 1.0. TI86EMU Does not work with "LARGE TEXT" option 
in windows.

Features include:

-Almost Perfect TI-86 emulation
-Works with every TI86 Game and BASIC program I have tried
-2 to 8 times as fast as TI86 (on P200MMX)
-Load .86P BASIC and ASM programs, 86I pictures, and 86S strings from
 PC right into calculator's TI86 variables.
-Save/load emulator machine state to your PC
-Save/load raw memory to you PC
-Save/load workspace to your PC
-Run multiple TI-86s at once
-Controllable though keyboard or virtual TI86 keypad
-Speed control

Debugger:

-Register window
-Disassembly window
-Memory dump window showing ASCII and hex values
-Breakpoints
-Animation (Watch your program run in slomotion, updating memory,
 registers, disassembly window, ect.)
-Single step
-Interrupt and debug program anytime
-Modify memory
-Modify registers
-Inport/Outport 
-Search memory for bytes or strings

------------------------------------------------------------------------------
 NOTIFICATION LIST
------------------------------------------------------------------------------

-Please e-mail me if you want to be notified about future versions of this
 product.

------------------------------------------------------------------------------
 HISTORY
------------------------------------------------------------------------------

 NEW IN VERSION .5 (2/12/98)

-Total overhaul of the Key emulation system, this fixes games like sqrxz and
 boulderdash that depend on a realistic emulation of the keypad.
  -Added support for multiple keys
  -Changed key layout so that now arrow keys are used plus remapped a couple
   other keys
  -Now two keyboard emulation modes:
    -Realistic mode: An exact emulation of the TI86 Keyboard hardware.
    -Typing mode: This mode works with most games and programs, plus lets you
     type ALOT faster than you can in Realistic mode. Multiple keys are not
     supported in this mode, so if a game doesnt work, choose realistic mode
     instead.

 NEW IN VERSION .4 (2/10/98)

-Improved game/program compatiblility, now EVERY BASIC and ASM program I've
 tried works
-Load 86P BASIC or ASM files right into calculator variables
-Load 86I image files right into calculator variables
-Load 86S string files right into calculator variables
-Large LCD option (4x standard size)
-Virtual keypad
-Search memory for bytes or strings
-Improved keyboard emulation
-Custom colors for background and foreground
-Load/Save workspace
-DEFAULT.WKS (if it exists) is loaded when emulator starts
-DEFAULT.STA (if it exists) is loaded when emulator starts
-Tested on Version 1.2 and 1.3 ROMs

 NEW IN VERSION .3 (1/30/98)

-Dramatic speed increase
-Added optional wait states so you can adjust the speed of emulation
-Fixed minus key bug
-Figured out how to stop auto-shutoff (see section)
-Can now write to ROM with "set mem"
-Can now save/load variable length raw emulator memory images
-Fixed bug where animate didnt stop at breakpoint
-Fixed .86P loading bug, this enables a LOT more assembly programs to run,
 now the majority of .86P programs run.
-Added some key debouncing. This fixes some games that worked, but missed
 keystrokes.

 VERSION .1 (1/26/98)

-Original release
-Slow
-Lots of bugs
-Most programs dont work

 CONCEPTION/START DATE (1/24/98)

------------------------------------------------------------------------------
 FUTURE FEATURES
------------------------------------------------------------------------------

-C-Compiler and assembler, which would make TI86EMU a complete IDE
-DirectX for faster graphics
-Optimize for more speed 
-Linkport emulation
-Multiple/Conditional breakpoints
-Contrast control emulation
-Bug fixes
-Graphics viewport emulation
-Joystick support, yes thats right, play TI86 games with a joystick!
-Realistic mode (I will scan the TI86 with a scanner and make an option 
 for a realistic looking TI86)
-Support for other file types if theres a demand for it

------------------------------------------------------------------------------
 LIMITATIONS
------------------------------------------------------------------------------

-Movable graphics viewport not implemeted (yet), this means that some games
 and all greyscale image viewers wont work.
-Does not work with "Large text" setting in windows
-No linkport
-No support for file types other than 86P,86I,and 86S (but these are the
 important ones)
-As part of the variable loading mechanism, a variable called DUMMY973 is
 created, and will exist in your emulator memory. Consequently, you cannot
 load any TI86 variable named DUMMY973 (shouldnt be a problem). You can
 delete this variable from memory if you want but it will be re-created next
 time you load any variable into the TI86.

------------------------------------------------------------------------------
 ROM IMAGE
------------------------------------------------------------------------------

TI86EMU requires you to download your calculator's ROM image to your PC. You
will need a TI linkport and a program named ROM86 (www.ticalc.org) to do this.
There is probably also a way to download the ROM with a homemade link, but Im
not aware of this.

DO NOT ASK ME TO SEND YOU A ROM IMAGE, I WONT EVEN RESPOND.

IT IS ILLIGAL TO USE TI86EMU WITHOUT OWNING A TI-86 CALCULATOR

------------------------------------------------------------------------------
 INSTALLATION
------------------------------------------------------------------------------

TI86EMU is a standalone program and requires no special installation program,
just make a directory called TI86EMU, copy TI86EMU.EXE to it, copy your ROM
image named: "TI86.ROM" to it, and set up a shortcut to TI86EMU.EXE. No .INI,
.DLL,.VBX,.OCX,.HLP, runtime librarys, or anything else is required. TI86EMU
does not use the registry, nor does it make or use any files in your
windows\system directory (other than SYSTEM DLLs).

------------------------------------------------------------------------------
 REQUIREMENTS
------------------------------------------------------------------------------

-WIN95 or WINNT(not tested on WINNT)
-Pentium or more for normal TI86 speed
-24bit color mode on desktop (may or may not work with 8bit color)
 Sorry to do this, but I did it so I could do realistic contrast control
 in the future. Most newer computers have fast 24 bit color anyways.

------------------------------------------------------------------------------
 USE
------------------------------------------------------------------------------

KEY LAYOUT:

<F1-F5>	Same as on calculator
<Ctrl>	2nd
<Esc>	Exit
<Ins>	More
<Del>   Delete
<Up>    Up
<Left>  Left
<BkSpc> Left
<Down>  Down
<Right> Right
`	Alpha
<PgDn>  x-var
<F6>	Graph
<F7>	Table
<F8>	Prgm
<F9>	Custom
\	Clear
A-Z: 	Same as on calculator
0-9: 	Same as on calculator
<Space> Ans
<Enter> Enter
<F12>   Exit run mode to Debug mode
<F11>   Go to run mode
<PgUp>  Reset keyboard

TI86EMU has two modes of operation:

-RUN MODE: Runs in a small window, only displaying calculator graphic.
 Use this mode if you dont want to do any debugging. It is the faster
 and easier mode to use. To quit to DEBUG mode, press <F12>

-DEBUG MODE: Runs in a bigger window and shows all the debugging stuff.
 A control panel is present on the left side of the screen to help you
 debug:

        -Options        Options

                -Wait states    Set number of wait states. Use this to slow
                                TI86EMU down if you have a fast computer.
                                0 is the fastest, 2^32-1 is the slowest

		-Large screen	Makes screen 4x bigger (256*128)
		
		-Start run mode Makes TI86EMU startup in run mode.

		-Foreground color Foreground color.

		-Background color Background color.

                -Key emulation mode:

                    -Realistic mode: An exact emulation of the TI86 Keyboard
                     hardware.

                    -Typing mode: This mode works with most games and
                     programs, plus lets you type ALOT faster than you can
                     in Realistic mode. Multiple keys are not supported in
                     this mode, so if a game doesnt work, choose realistic
                     mode instead.

        -Load           Load a .86P (program) or
                        Load a .86S (string file) or
                        Load a .86I (image file) or
                        Load a .STA (Emulator state) file or
                        Load a .BIN (Variable length raw memory image) file or
                        Load a .WKS (Emulator workspace ie colors, settings,
                         ect) file

                        *NOTE If, during startup, TI86EMU finds a file called
                        DEFAULT.STA or DEFAULT.WKS, it will automatically load
                        them

                        *NOTE The calculator must be running in DEBUG mode 
                        with just a cursor (no programs running) to load any
                        TI86 variable (.86P,.86S,or .86I)

                        *NOTE When saving the Emulator state, the ROM and RAM
                        is saved in the .STA file

        -Save           Save a .STA (emulator state) file or
                        Save a .WKS (emulator workspace) file or
			Save a .BIN (Variable length raw memory image) file

                        *NOTE: You MUST specify the correct file extension
                        when TYPING in a filename or TI86EMU wont know what
                        kind of file you are talking about.
			
	-Help		Help

	-Inport		Read inport. Preceed hex values with "$"

	-Outport	Set outport. Preceed hex values with "$"

	-Disassem at 	Set disassembly address. Preceed hex values 
			with "$"

	-Dump mem at	Set dump address. Preceed hex values with "$"

        -Search         Search TI86 memory. Will initiate another window with
                        the following options:

                -Search for
                        Type in here what you want to search for. You can
                        search for a single byte, a list of bytes separated
                        by commas or a string surrounded by double quotes.
                        Preceed hex values with "$"

                -Start address
                        Start address of search
                        Preceed hex values with "$"

                -End address
                        End address of search
                        Preceed hex values with "$"

                -Addressing system. See section on addressing systems
                        -Z80 address space 
                        -Virtual address space

        -Set mem        Set memory. You can type in a string surrounded by
                        double quotes, a list of bytes separated with commas,
                        or a single byte. Preceed hex values with "$".

        -Run            Run calculator in DEBUG mode, its little
                        slower than in RUN mode, because it has to 
			look for breakpoints. Also, you wont be able
			to use all the calculator keys.

	-Animate	Run the calculator in animate mode. This runs
			the system in slow motion, updating all the 
			registers, disassembly, stack, and flags
			as it goes.

	-Break		Stop (pause) the emulator

	-Step		Execute one instruction

	-Reset		Reset the emulator

	-Virtual keypad	Enables the virtual keypad

	-Exit		Quit the emulator

	
-Disassembly window: Shows dissasembly at current address, double click
 a line to set a breakpoint.

-Register window: Displays and lets you set Z80 registers. To change a
 register, just click on it and enter a value, then press <Enter>. If 
 you want a hex value, type a "$" first.

-Memory dump window, displays the system memory. Double click to change
 a byte. Remember to preceed hex values with a "$"

-Stack dump window, displays the system stack.

------------------------------------------------------------------------------
 PROGRAMS THAT DONT WORK WITH TI86EMU
------------------------------------------------------------------------------

Almost Everything I've thrown at TI86EMU (all popular ASM games, lots of 
BASIC progs) work fine, Programs that dont work are:

-Penguins (Something to do with multiple files and maybe my variable loader)
 The starting screen comes up fine, but then I get an "undefined" error.

-Gray scale viewers (These programs use a movable graphics viewport which I 
 havent implemented yet).

Id be happy to work with authors of these programs to get them working on the
emulator.

------------------------------------------------------------------------------
 ABOUT MEMORY ADDRESSING SYSTEMS
------------------------------------------------------------------------------

When hacking around in TI86EMU, you should understand 3 memory addressing
systems, as well as the way that the TI86 memory banking system works. I
wont describe banking here, but there are many documents available on it.

-Z80 space addressing

Simply the 16 bit address space of the Z80 with bank values at ports 5 and
6 accounted for.

-Virtual addressing

Virtual memory addressing is an addressing system used internally by
TI86EMU to address all 384K of the TI86 memory contiguosly. Its pretty simple,
the first 256K (0-$3ffff) is ROM, the next 128K ($40000-$5ffff) is RAM.
The 4K ROM/RAM banks are all sequentually mapped into this virtual address
space. The Virtual system is only apparent to the user of TI86EMU when
saving/loading raw memory images and searching.

Heres an example: the TI86 screen memory is at Virtual address:
$43c00 ($40000 + Bank0 of RAM) and physical address $fc00. (Bank 0 is mapped
to c000-ffff)

-Absolute addressing

This is an addressing scheme developed by TI and used in their documentation
and in the TI86. I didnt use it internally in TI86EMU because it only
addresses RAM, not ROM, plus its a little confusing, but it would be helpful
to know because it is used internally by some ROM routines on the TI86, info
on it is available on TI's web site.

------------------------------------------------------------------------------
 HOW TO SHUT OFF AUTO SHUTOFF
------------------------------------------------------------------------------

If you have a version 1.3 ROM its easy. Write a $c9 (return opcode) to ROM
address $184, save the file: ROM.BIN as a raw memory image from virtual
address $00000, len $40000, then rename ROM.BIN to TI86.ROM (backup your
original ROM first). If you dont have a 1.3 ROM, you have to figure it out
yourself unless the addresses are the same (I dont know, I dont have a 1.2
ROM). I figured this out as follows:

1) Start emulator fresh (no state files or 86Ps)
2) Save state
3) Wait a couple seconds and DONT DO ANYTHING
4) Save state again
5) Use the DOS program FC to find differences in files. (.STA files are a dump
   of register information (84 bytes) then the whole virtual memory, so
   subtract 84 from any file based address, then take the banking subsystem of
   the TI86 into acount.
6) Narrow it down and find the memory location that the calculator is using to 
   countdown to shutoff (on the 1.3 ROM, it was a 16 bit counter at $c009)
7) Find out where in the ROM that address is accessed, then "fix" the ROM :) 
   and save it

* NOTE I've since found out that the same procedure used on the 1.3 ROM can
 also be used on the 1.2 ROM.

------------------------------------------------------------------------------
 ACKNOWLEGEMENTS
------------------------------------------------------------------------------

- Marcel De Kogel for the excellent Z80 emulator code without which TI86EMU 
  would probably not exist (at least not for quite a while).
- Randy Gluvna for ROM86
- Thomas N. Anderson Maker of TASM
- Sean young, for z80 opcode list
- Alan Bailey Maker of asm86 and sample programs
- TI for the lovable little TI86

------------------------------------------------------------------------------
 AUTHOR
------------------------------------------------------------------------------

Im 28 and employed as a software/electrical engineer. I work on magnetic
instrumentation equipment. I write control, filtering, data acquisition,
data presentation, and communication software under windows, embedded micro,
and embedded DSP platforms. This is my first emulator.

------------------------------------------------------------------------------
 POSSIBLE FUTURE PROJECTS
------------------------------------------------------------------------------

-TIxxEMU for other TI calculators. Id love to do a TI92EMU. Anyone
 want to donate me some calculators? :)

-Maybe a game or two sometime

------------------------------------------------------------------------------
 OTHER TI86 RELATED PROGRAMS BY ME
------------------------------------------------------------------------------

-TI86MON, a full featured montitor/disassembler that runs on the TI86.
 Available at www.ticalc.org.

------------------------------------------------------------------------------
 LEGAL STUFF
------------------------------------------------------------------------------

IT IS ILLIGAL TO USE TI86EMU WITHOUT OWNING A TI-86 CALCULATOR

-TI86EMU is Copyright (C) 1998 Steve Gordon
-TI86EMU is free
-I am not responsible for support of TI86EMU. (duh, its free)
-You can use TI86EMU for as long as you want
-You can Distribute TI86EMU FOR FREE as long as the following documents are
 included and not modified:
        -ti86emu.txt (this file)
        -ti86emu.exe (program file)
-You can email me (sgordon@mich.com) with any problems or comments concerning
 TI86EMU or other products of mine. I make no promises to respond.
-You CANNOT blame me for _ANYTHING_ that you screw up using TI86EMU
-You CANNOT sell TI86EMU or any package containing TI86EMU without my
 permission
