Difference between revisions of "Emulators:PindurTI"

From WikiTI
Jump to: navigation, search
(Scripting)
(Additional functions)
 
(9 intermediate revisions by 5 users not shown)
Line 1: Line 1:
PindurTI (commonly referred to as PTI) is the latest addition to the TI [[Emulators|emulator]] 'family', still in development by Patai Gergely. This page contains the up-to-date documentation.
+
[[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==
 
==Features==
Line 8: Line 11:
 
*Scripting for external tools (preliminary in the latest version), which is already used by [[LateNite]]
 
*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://www.hszk.bme.hu/~pg429/pindurti/features/ PindurTI idea box]. Repetitions and trivialities are frowned upon.
+
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==
 
==Basics==
Line 27: Line 30:
 
'''Pressing calculator keys'''
 
'''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.
+
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"
 
{| border="1" cellspacing="0" cellpadding="2"
Line 38: Line 41:
 
| Space || 0
 
| Space || 0
 
|-
 
|-
| arrows, 0..9, Enter, '.', ',', numpad +-/* || the corresponding calculator key
+
| arrows, 0..9, Enter, '.', ',', number pad +-/* || the corresponding calculator key
 
|-
 
|-
 
| [ || (
 
| [ || (
Line 102: Line 105:
 
| Tab || Start crude (9 fps) screenshot/Stop current screenshot
 
| Tab || Start crude (9 fps) screenshot/Stop current screenshot
 
|-
 
|-
| Alt || Start fine (25 fps) screenshot/Stop current screenshot
+
| Backspace || Start fine (25 fps) screenshot/Stop current screenshot
 
|-
 
|-
 
| F9 || Reset calculator in active slot (simulates pulling batteries)
 
| F9 || Reset calculator in active slot (simulates pulling batteries)
Line 111: Line 114:
 
|}
 
|}
  
Note that only crude screenshots are displayed properly everywhere. Fine screenshots are only shown at full speed by Firefox.
+
Note that only crude screenshots are displayed properly everywhere. Fine screenhots are only shown at full speed by Firefox.
  
 
==Additional functions==
 
==Additional functions==
Line 121: Line 124:
 
2. Enable/disable warp mode
 
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.
+
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.
 
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.
Line 129: Line 132:
 
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.
 
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:
+
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"
 
{| border="1" cellspacing="0" cellpadding="2"
Line 136: Line 139:
 
| F7 || Execute one instruction (or skip to the next interrupt when halted)
 
| 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, DJNZ and repeat instructions (e.g. LDIR) are executed until either the program counter hits the subsequent instruction or 10000000 clock cycles elapse
+
| 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
 
| F12 || Toggle the layout editor
Line 164: Line 167:
 
| Up/down arrows, Page Up/Down || Navigate
 
| Up/down arrows, Page Up/Down || Navigate
 
|-
 
|-
| F2 || Set/remove execution breakpoint at the cursor
+
| 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)
 
| G || Go to a specific address (enter in hexadecimal; press Escape instead of Enter to cancel)
Line 177: Line 180:
 
'''Memory view'''
 
'''Memory view'''
  
This is currently a read-only 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.
+
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'''
 
'''Registers'''
Line 185: Line 190:
 
'''Variables'''
 
'''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.
+
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'''
 
'''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.
 
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'''
 
'''Key-value modules'''
Line 250: Line 259:
  
 
==External Resources==
 
==External Resources==
[http://www.hszk.bme.hu/~pg429/pindurti/pindurti.exe Latest build of PindurTI]
+
[http://sgate.emt.bme.hu/patai/pindurti/pindurti.exe Latest build of PindurTI]
  
[http://users.hszk.bme.hu/~pg429/pindurti/changelog.txt Changelog]
+
[http://sgate.emt.bme.hu/patai/pindurti/changelog.txt Changelog]
  
[http://www.hszk.bme.hu/~pg429/pindurti/features/ PindurTI Idea box]
+
[http://sgate.emt.bme.hu/patai/pindurti/features/ PindurTI Idea box] (not active any more)
[[Category:Emulators]]
+

Latest revision as of 13:57, 8 October 2012

PindurTI (commonly referred to as PTI) is a relatively new member of the TI 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 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 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.

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,θ,n
Page Up Matrx (82/83) or Apps (83+)
Page Down Prgm
Insert Vars
Delete Del
Home Math
End Stat

Mapping of letter keys

A Math B Matrx C Prgm        
D x-1 E Sin F Cos G Tan H ^
I x2 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        

Other keys

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:

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:

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

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:

  7 6 5 4 3 2 1 0
0         up right left down
1   clear ^ / * - + enter
2   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  
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

Latest build of PindurTI

Changelog

PindurTI Idea box (not active any more)