Difference between revisions of "Emulators:PindurTI"

Revision as of 02:35, 21 October 2006

PindurTI (commonly referred to as PTI) is the latest addition to the TI emulator 'family', still in development by Patai Gergely. This page contains the up-to-date documentation.

Features

• Full support for 82 and 83. 83+ support isn't complete yet, but it's already the most accurate of all emulators.
• Raw virtual linking of any number of calculators.
• Built-in (animated) screenshotting ability.
• Debugger.
• Scripting for external tools (preliminary in the latest version), which is already used by LateNite

If you have ideas you want to incorporate in the tool, you can submit your ideas at the PindurTI idea box. Repetitions and trivialities are frowned upon.

Basics

PindurTI requires no installation; it is a standalone executable you can put anywhere. It will only create a file called pti.conf in its working directory (which is by default the same as the one the executable is located in), so make sure this directory is not read-only for pindurti.exe.

At the moment of writing PindurTI has no real graphical user interface (GUI) yet, only the absolute minimum required to use all the features. Here are the steps to get going:

1. Start pindurti.exe. You will see any empty, fully cyan window. The four quarters of the window represent four slots where individual calculators can be run.

2. Drag-and-drop a ROM image to one of the quarters, preferably the top left. The quarter chosen will turn grey for the most part, and four icons will appear above the grey area.

3. Left click the grey part. This is the screen of the calculator, and the left click corresponds to the On key.

4. You can drag and drop other ROM images to the other slots. You can switch between the slots by right clicking them. (Left clicking also activates the slot, but it also causes the On key to be pressed.)

5. Files can be sent by dropping them to the appropriate slot. PTI uses silent linking, so the calculator must be on, somewhere in the TI-OS and not in receive mode in order for the transmission to succeed. You can also drop a group of files, they will be sent one after the other. Naturally, the file and the running ROM image must be for the same model, e.g. sending an 8xp file to a TI-82 won't work.

Pressing calculator keys

When interpreting keypresses for the calculators, PTI always acts as if the layout was English, so if you use an alternative layout (e.g. AZERTY or Cyrillic), 'Q' still refers to the button next to the Tab key and so on.

Mapping of letter keys

Other keys

Note that only crude screenshots are displayed properly everywhere. Fine screenshots are only shown at full speed by Firefox.

Additional functions

The icons above each calculator screen can be used for the following purposes by left clicking, from left to right:

1. Pause/unpause

2. Enable/disable warp mode

3. Plug into a link hub; plug in two calculators to open a communication line between them. Connecting more than two calculators is not supported by the TI-OS. However, the CLAP linking library allows mass linking.

4. Toggle inclusion in screenshotting. If no slot is selected, always the active one will be captured. This feature can be used to allow capturing a slot even if we activate another in the meantime (e.g. to save an animated cutscene while using another calculator) or to record multiplayer games.

Debugger

The debug window is composed of separate modules, which show the state of the calculator from a certain aspect. Note that the components are tuned to the top left slot by default, and you have to change the slots manually in the layout editor if you want to examine a different slot.

Some keys are global in the debugger, i.e. they will always have the same effect regardless of the module selected. These keys are the following:

Layout editor

This feature is still under development. Most importantly, the modified layouts are not saved. The default layout is designed not to conceal anything if the window is maximised at a resolution of at least 1024x768. The keys are the following:

Modules

Disassembly

Important: when a breakpoint is set, it affects all the slots at the same time for the time being!

Memory view

This is a view of the 64K CPU address space. You can use the arrows and the page up/down keys to navigate. The G, P, S, B, D, H, X and Y keys have the same effect as on the disassembly pane.

When you press Enter, you can edit the value currently under the cursor by simulating a memory write to that address, i.e. only RAM contents can be modified this way. The dialog accepts numbers in four bases, which can be denoted by postfixes: b - binary, o - octal, d - decimal and h - hexadecimal. If there is no postfix, the number is treated as hexadecimal. Consequently, if a hexadecimal number ends in b or d, the h prefix must be used explicitly. If you press Shift-Enter instead of just Enter after typing the number, the effect will be writing a little-endian word at the current address instead of a single byte.

Registers

The internal state of the Z80. Each value can be edited after left clicking; the values must be entered in hexadecimal. Editing can be concluded with Enter or by clicking elsewhere, and cancelled with Escape. Note that halt can have three values: 0 - normal operation, 1 - halt active, 2 - violating execution protection (if you attempt running any further, the calculator will be forced to reset).

Variables

A simple, read-only VAT viewer. It can be navigated using the up/down arrows, Page Up/Down and the mouse wheel as well.

LCD data

Graphical display of the contents of LCD memory. Note that all the 120 columns are shown here, even though all calculators emulated can only display 96. However, the memory is still there. The current X and Y addresses are shown by a bluish colour on the byte that will be accessed through the data port.

Key-value modules

The following modules are in this category: LCD physics, LCD software, Information, Time, Interrupts, Memory, Keyboard, Link. All of these display a list of characteristics. The right hand sides can be edited where the cursor turns into a hand. Editing can either mean a single click (e.g. interrupt frequencies or keyboard state) or bring up a text box for numeric values, where Escape can be used to cancel as usual.

Scripting

It is possible to run the emulator in a non-interactive mode through a pipe (communicating through stdio), just invoke the executable with the -p switch and redirect the input and the output. Do not try to run it with the keyboard on the input or a terminal on the output, because it will hang.

Each command sent must be on a separate line. All of them emit at least a line containing 'OK' as a response in case of success. Error conditions are signaled by outputs starting with 'Error:'.

The commands are the following:

• send-file <slot> <file> - send a file to the specified slot (the same as drag and drop); don't quote the filename, it's read from the first non-space after the slot number till the end of the line (the slot number must be between 0 and 15 or 0x0 and 0xf)

• activate-slot <slot> - select the current slot

• reset-calc - reset the calc in the current slot (you might need to run a few million cc's after this before pressing on)

• run <cycles> - run for the specified number of cycles (it should be a number between 1 and 2000000000); when debugging is enabled and execution stops on a breakpoint, there will be a line starting with 'Info:' output before the usual 'OK'

• step <n> - execute n instructions ignoring the breakpoints, n defaults to 1 when omitted; the firing of a possibly masked timer during a halt counts as one instruction

• draw-screen-bw - dump LCD memory — 96*64 bytes, 0 for white and 255 for black; the raw data is preceded by a line that always contains two characters: the first is '1' if the calculator is powered, '0' otherwise, and the second is '1' if the LCD is powered, '0' if it isn't (so the image should be displayed only if this line says '11')

• draw-screen-gs - dump greyscale screen (only updated 25 times per calculator second) — 96*64 bytes preceded by the same two-character line, same format but using the full range of values

• key-down <key> - press key (calc key, so the argument is a token like '2nd', 'mode' etc.)

• key-up <key> - release key

<key> must be one of the tokens below:

The on key is called 'on', surprisingly. You can also write 'apps' instead of 'matrx'.

• dump-state <type> - obtain information about the internal state of the emulated hardware; <type> must be one of the following (without quotes): 'lcd physics', 'lcd software', 'model', 'time', 'interrupt', 'pager', 'keyboard', 'link', 'cpu', 'memory'. Except for the last two the format is the following after the initial 'OK': a line containing nothing but the number of subsequent lines, and a 'key: value' pair on each line. With 'cpu' it displays the registers with a 'reg=value' pair on each line, all in hex, while 'memory' is a dump of 65536 bytes as seen in the z80 address space with the current mapping mode

• {set|remove}-breakpoint <type> <args> - add/remove a breakpoint; the arguments depend on the type given; the only type currently supported is 'code' (again, no quotes). It has only one argument: a number specifying the address. It can be base 10, 16 or 8 differentiated by the usual C prefixes. (Actually, this applies to any numeric argument in any command.) For the removal you can also specify -1 here, which removes all code breakpoints.

There is currently no way to directly manipulate the state of the calculator.

External Resources

Latest build of PindurTI

Changelog

PindurTI Idea box