TilEm 0.973
-----------

Welcome to the world of TilEm!  TilEm is an emulator and debugger for
the Texas Instruments Z80 line of graphing calculators.  Its interface
is through GTK+/GDK and should thus be portable across many platforms.

As of this writing (December 2004), TilEm is the only such emulator to
support:

- Operating systems other than Microsoft Windows

- All Z80 TI calculators except the TI-81, and all known ROM/OS
  versions

- Virtual linking via all physical and virtual cables except direct
  USB

- Automatic certificate patching for dumped 73/83+/84+ ROMs

- Emulation of certain "security" features on the 83+

- Flexible keyboard handling, with both key macros and manual
  make/break support


Installation
------------

From Binary (Windows)

The 'tilem-X.XXX-win32-bin.zip' file contains everything you need
except the GTK+ libraries.  You can get these from
http://www.gimp.org/~tml/gimp/win32/.  You will need the following
runtime packages: glib, libiconv, gtk+, pango, atk, libjpeg.
Alternatively, you can install the complete GTK+ runtime package from
http://gladewin32.sourceforge.net/

Sources for GTK+ are available from the above site; sources for
libticables2 are available from http://tilp.sourceforge.net/.

The default fonts seem not to work on some systems.  If you receive an
error such as the following:

** WARNING **: Couldn't load font "MS Sans Serif 8" falling back to "Sans 8"
** ERROR **: file shape.c line 75: assertion failed: (glyphs->num_glyphs > 0)

you need to add the following lines to C:\Program Files\Shared
Files\Gtk\2.0\etc\gtk-2.0\gtkrc:

style "user-font"
{
font_name="Arial"
}
widget_class "*" style "user-font"


From Source (Unix)

You will need the GTK+ library (http://www.gtk.org/) version 2.4 or
newer.  GTK+ 1.2 is no longer supported.

In addition, for the full experience, you'll also need libticables2
version 0.0.3 or newer, which you can get from the TiLP project:
http://tilp.sourceforge.net/

Having installed the above, go to the main TilEm directory and run:

	./configure

to configure TilEm for your system.  Then run:

	make

to compile it, and finally (as root):

	make install

TilEm will install into /usr/local/bin by default, with data and
images stored in /usr/local/share.  If you want to install in a
different location, you must specify "--prefix" when you run
configure.  Run "./configure --help" for more information.


From Source (Windows)

I use and recommend the Cygwin development tools
(http://www.cygwin.com/.)  You can of course use any compiler you
like, but I cannot guarantee that it will work.

To compile against the native Windows GTK libraries
(http://www.gimp.org/~tml/gimp/win32/) you must use the -mno-cygwin
and -mms-bitfields flags.  You may also want to use -mwindows to
compile as a GUI program rather than a console one.  From the Cygwin
bash shell, use

 ./configure CFLAGS="-mno-cygwin -mms-bitfields -mwindows"

to configure TilEm.  If you want to use libticables, you must manually
specify the compiler flags; for example:

 ./configure CFLAGS='-mno-cygwin -mms-bitfields -mwindows' \
	TICABLES_CFLAGS='-I<include>' \
	TICABLES_LIBS='-L<lib> -lticables2'

where <include> is the path to ticables.h, and <lib> is the path to
ticables2.lib.

If you prefer, you can install the Cygwin X server and standard GTK+
libraries (which are available as Cygwin packages) in which case you
should follow the standard Unix instructions instead.  Note, however,
that the Unix version of libticables probably will not work with most
cables under Cygwin.


Obtaining a ROM image
---------------------

In order to use TilEm, you will need a ROM image for the calculator(s)
in question.  These ROM images are copyrighted by TI and should not be
distributed.

Several tools are available for dumping the ROM from your calculator;
probably the best option is TiLP-II (again, http://tilp.sourceforge.net.)
Other ROM dumpers of various sorts can be found at ticalc.org.

You may need to install an assembly shell in order to run the ROM
dumping program; which shell you need depends on the dumping program
you use.  The TiLP-II dumpers require Mallard for the 73, SNG for the
82, and ZShell (or any compatible shell) for the 85.  You can find
these shells at ticalc.org.

An alternative to dumping the complete ROM is Andree Chea's rom8x,
which allows you to dump one or two small segments of the ROM, and
combine these with an OS upgrade file to create a complete ROM image.
rom8x supports the TI-83+, 83+ SE, 84+ and 84+ SE, and works with any
linking program, including TI-Connect.  You can get rom8x from
http://www.ticalc.org/archives/files/fileinfo/373/37341.html.

For the 73, 83+, and 83+ SE, TI has also provided ROM images with
their SDK.  You can download it from:
http://education.ti.com/educationportal/sites/US/productDetail/us_sdk_73_83_84.html

Unfortunately, the SDK is only distributed as a self-extracting
Windows installer (it was at one time a self-extracting zip, but no
longer.)  So users of other OS's are stuck.  Your options in this case
are:

(a) Wine

(b) a friend with Windows

(c) email TI-Cares and ask (politely!) for the files, which they may
    be willing to send you.

Anyhow, the files are "TI73.clc," "TI83Plus.clc," and "TI83ps.clc."
(These files actually contain the full state of the calculator, but
TilEm just uses the ROM.)

Older versions of the SDK included the complete ROM in hex form; you
can use the included "tcc" program to convert these files into binary
ROM images.

TilEm ROM images are stored within the directory ".TilEm" in your home
directory on Unix, or in the main package directory on Windows.  Each
ROM image must be placed in the correct subdirectory, "ti73", "ti82",
"ti83", "ti83p", "ti83pse", "ti84p", "ti84pse", "ti85", or "ti86".
ROM images must be named with a ".rom", ".bin", or ".clc" suffix.

The old ROM naming scheme is still supported, but not recommended.


Using TilEm
-----------

When TilEm starts up, assuming you've installed a valid ROM image, you
will see a picture of the calculator.  Left click to press a key.
Right-clicking brings up the menu, which allows you to perform various
useful operations.

- Load a file into the emulated calculator.  The following
  file formats can be used:

    - Standard program/variable and backup files as produced by the
      various Graph-Link programs.
    - .hex or .app Flash Apps in plain hex format.
    - .8xk or .73k Flash Apps with header.
    - .8xu or .73u Operating Systems with header.

  Certificates, headerless OS's, and old self-extracting App
  installers are not supported.

  Remember that the 82 and 85 must be in link receive mode to receive
  files.

  Also note that you must reset the calculator in order for it to
  recognize an app that has just been loaded.

- Pause the calculator and start the debugger.

- Switch to a different calculator model.

- Configure the external linking (see below).

- Toggle the autosave mode.  This determines whether the state of the
  calculator will be saved when you change models or use your window
  manager to quit.

- Toggle the window between showing the full calculator and just the
  screen.

- Toggle the speed control mode.  When speed control is active, TilEm
  will slow itself down to try to simulate the speed of an actual
  calculator.  When disabled, TilEm will run as fast as it can, which
  on any current computer is blindingly fast.

- Reset the virtual calculator (usually clears its RAM.)

- Reload the virtual calculator's RAM from the last saved state.


The Debugger
------------

Pressing F11 enters the TilEm debugger.  This allows you to view and
edit the current state of the virtual calculator.

The main debugger window contains two panes: the top pane shows the
disassembly of the code being run, and the bottom pane shows the
current contents of memory.  At right you can inspect the current CPU
registers and the hardware stack.

You can change any value in RAM by left-clicking in the memory view;
similarly you can click on any register value to change it.  Click on
the address in the memory pane to look at a different area of memory.

In the disassembler, a yellow arrow indicates the current location of
the Z80 Program Counter.  A gray arrow indicates that the next
instruction is a conditional jump which will not be taken; a green
arrow is one which will be taken.  A red circle is an execution
breakpoint.

You can load a list of symbols to be used in disassembly.  Each line
of the file should consist of a symbol name followed by a hex value,
separated by whitespace and optionally by an = sign.  Most assemblers
can generate a symbol file in this format, so you can load your
symbols into TilEm for easier debugging.  Once you have loaded your
symbols, they will appear in the disassembly where appropriate, and
you can also use them as addresses, register and memory values.

The emulator also "traces" the Z80 PC as the calculator runs, so you
can see what the CPU was doing just before it reached the current
point.  You can trace backwards up to 256 steps.  Note that only the
PC is traced, not the memory or any other registers.


Linking
-------

Regardless of how you configure TilEm, it will support "internal"
linking.  This allows you to send files to the calculator, as
described earlier.  You can also receive files from the calculator
(with the exception of memory backups and Flash) simply by using the
calculator's link menu to send a file.

If you configured TilEm to use libticables, it will also support
"external" linking.  You can connect your emulated calculator to a
real one through a GraphLink cable, or to another emulator or linking
program through a "virtual cable."

To enable external linking, right click and select "Linking..."  Then
"Enable external link," and choose your settings.  Note that when
external linking is enabled, internal linking will no longer work,
since data sent by the calculator is diverted to the external cable.

The virtual cables are a special case worth mentioning.  Each has two
"ports" which you can connect to.  If you want two calculators (or a
calculator and TiLP) to talk to each other through a virtual link, you
must set one to virtual port #1, and the other to virtual port #2.


About this program
------------------

Copyright (C) 2001-2002 Solignac Julien <x1cygnus@xcalc.org>
Portions copyright (C) 2004 Benjamin Moody <benjamin@ecg.mit.edu>

TilEm is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the
Free Software Foundation; either version 2.1 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA.

The Z80Em emulation core is NOT considered part of TilEm for licensing
purposes.  It is copyright (C) 1996-97 Marcel de Kogel.  Please refer
to his website, http://www.komkon.org/~dekogel/, for more information.
