View source for Emulators:PindurTI

[[Category:Emulators]]
PindurTI (commonly referred to as PTI) is a relatively new member of the TI [[Emulators|emulator]] 'family', developed from scratch by Patai Gergely. Development has ceased, as the author has no sufficient time to continue, and the code base is not easily extended to implement calculator features that were not known at the start of the project. Users who need the emulation of newer models than the plain 83 should use [[:Emulators:Wabbitemu|WabbitEmu]] instead.

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 [http://sgate.emt.bme.hu/patai/programs/pindurti/features/ 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 key presses 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.

{| border="1" cellspacing="0" cellpadding="2"
! PC key !! Calculator key
|-
| left mouse button || On
|-
| A..Z || the button that yields the corresponding letter if alpha is on, see below
|-
| Space || 0
|-
| arrows, 0..9, Enter, '.', ',', number pad +-/* || the corresponding calculator key
|-
| [ || (
|-
| ] || )
|-
| F1 || Y=
|-
| F2 || Window
|-
| F3 || Zoom
|-
| F4 || Trace
|-
| F5 || Graph
|-
| Escape || Mode
|-
| Left Shift || 2nd
|-
| Left Control || Alpha
|-
| Right Shift || Clear
|-
| - || (-) (between the decimal point and Enter)
|-
| = || X,T,&theta;,''n''
|-
| Page Up || Matrx (82/83) or Apps (83+)
|-
| Page Down || Prgm
|-
| Insert || Vars
|-
| Delete || Del
|-
| Home || Math
|-
| End || Stat
|}

'''Mapping of letter keys'''

{| border="1" cellspacing="0" cellpadding="2"
| '''A''' || Math || '''B''' || Matrx || '''C''' || Prgm || &nbsp; || &nbsp; || &nbsp; || &nbsp;
|-
| '''D''' || x<sup>-1</sup> || '''E''' || Sin || '''F''' || Cos || '''G''' || Tan || '''H''' || ^
|-
| '''I''' || x<sup>2</sup> || '''J''' || , || '''K''' || ( || '''L''' || ) || '''M''' || Ã·
|-
| '''N''' || Log || '''O''' || 7 || '''P''' || 8 || '''Q''' || 9 || '''R''' || Ã—
|-
| '''S''' || Ln || '''T''' || 4 || '''U''' || 5 || '''V''' || 6 || '''W''' || -
|-
| '''X''' || Stoâ†’ || '''Y''' || 1 || '''Z''' || 2 || &nbsp; || &nbsp; || &nbsp; || &nbsp;
|}

==Other keys==

{| border="1" cellspacing="0" cellpadding="2"
! Key !! Effect
|-
| Tab || Start crude (9 fps) screenshot/Stop current screenshot
|-
| Backspace || Start fine (25 fps) screenshot/Stop current screenshot
|-
| F9 || Reset calculator in active slot (simulates pulling batteries)
|-
| F10 || Open debugger
|-
| F11 || Enable/disable warp mode (fastest possible emulation) of active slot
|}

Note that only crude screenshots are displayed properly everywhere. Fine screenhots 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 CALCnet 2.2 and CLAP linking libraries allow 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.

You can display a context menu by right clicking anywhere in the debug window. The menu list first the global keys, then displays all the component specific bindings after a horizontal separator. The global keys will always have the same effect regardless of the module selected. These keys are the following:

{| border="1" cellspacing="0" cellpadding="2"
! Key !! Effect
|-
| F7 || Execute one instruction (or skip to the next interrupt when halted)
|-
| F8 || Step over the next instruction; the same as F7, except that CALL, RST, DJNZ and repeat instructions (e.g. LDIR) are executed until either the program counter hits the subsequent instruction or 10000000 clock cycles elapse
|-
| F12 || Toggle the layout editor
|}

===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:

{| border="1" cellspacing="0" cellpadding="2"
! Key !! Effect
|-
| Insert || Add a component module after the selected one; the type of the component can be picked from a list
|-
| Delete || Delete the subtree starting from the currently selected node
|-
| 0..3 || Set the slot of every node in the subtree starting from the selection to the number pressed (0 - top left, 1 - top right, 2 - bottom left, 3 - bottom right)
|}

===Modules===

'''Disassembly'''

{| border="1" cellspacing="0" cellpadding="2"
! Key !! Effect
|-
| Up/down arrows, Page Up/Down || Navigate
|-
| F2 || Set/remove execution breakpoint at the cursor (it affects every byte of the instruction)
|-
| G || Go to a specific address (enter in hexadecimal; press Escape instead of Enter to cancel)
|-
| P, S, B, D, H, X, Y || Go to the address pointed by PC, SP, BC, DE, HL, IX, IY, respectively
|-
| R || Run from cursor, i.e. set PC to the address of the instruction under the cursor
|}

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 prefixes: % - binary, @ - octal, # - decimal and $ - hexadecimal. If there is no prefix, the number is treated as hexadecimal. 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. Double clicking a variable sets the address of the memory view to the address of its data.

'''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.

'''Link history'''

Link activity graph that records changes on the link port of calculators plugged into the hub. Calculators not plugged in are shown inactive even if they do manipulate their link 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:

{| border="1" cellspacing="0" cellpadding="2"
| &nbsp; || 7 || 6 || 5 || 4 || 3 || 2 || 1 || 0
|-
| 0 || &nbsp; || &nbsp; || &nbsp; || &nbsp; || up || right || left || down
|-
| 1 || &nbsp; || clear || ^ || / || * || - || + || enter
|-
| 2 || &nbsp; || vars || tan || ) || 9 || 6 || 3 || (-)
|-
| 3 || stat || prgm || cos || ( || 8 || 5 || 2 || .
|-
| 4 || x || matrx || sin || , || 7 || 4 || 1 || 0
|-
| 5 || alpha || math || x^-1 || x^2 || log || ln || sto || &nbsp;
|-
| 6 || del || mode || 2nd || y= || window || zoom || trace || graph
|}

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==
[http://sgate.emt.bme.hu/patai/pindurti/pindurti.exe Latest build of PindurTI]

[http://sgate.emt.bme.hu/patai/pindurti/changelog.txt Changelog]

[http://sgate.emt.bme.hu/patai/pindurti/features/ PindurTI Idea box] (not active any more)