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' \ TICABLES_LIBS='-L -lticables2' where is the path to ticables.h, and 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 Portions copyright (C) 2004 Benjamin Moody 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.