plus4emu usage
plus4emu usage
Select and load an ASCII format configuration file and apply the new settings. If the configuration file does not include all the supported options, those that are omitted are left unchanged.
Load a plus4emu format binary file, which may be a previously saved snapshot or demo, a binary format configuration file, or a program file with plus4emu header.
Save the current emulator configuration to an ASCII text file, which can be edited with any text editor, and can be loaded at a later time.
Save the current emulator configuration in binary format to the default file (~/.plus4emu/plus4cfg.dat). This is also automatically done when exiting the emulator.
Reload emulator configuration from ~/.plus4emu/plus4cfg.dat, and apply the original settings.
Save a snapshot of the current state of the emulated machine to the selected file. The snapshot will also include the current memory configuration and ROM images, but clock frequency and timing settings are not restored when loading a snapshot. The file format may be subject to changes between different releases of the emulator. Note that the state of any floppy drives is currently not saved, and the drives are reset on loading a snapshot.
Load a plus4emu format binary file, which may be a previously saved snapshot or demo, a binary format configuration file, or a program file with plus4emu header.
Select file name for quick snapshots. The default is ~/.plus4emu/qs_plus4.dat. This setting is not saved on exit.
Save snapshot to the quick snapshot file (see notes above).
Load the quick snapshot file if it exists.
Save snapshot (including clock frequency and timing settings) and record keyboard events to the selected file until the recording is stopped. The events can be replayed with accurate timing when the file is loaded later. Note that the file format may change between different releases of the emulator, and the timing may also be incorrect when using a different version to play a demo file.
Stop any currently running demo playback or recording.
Load a plus4emu format binary file, which may be a previously saved snapshot or demo, a binary format configuration file, or a program file with plus4emu header.
Write 16 bit signed PCM sound output to a WAV format sound file.
Close sound output file if it is currently being written.
Open new AVI file for video recording. This increases the CPU usage
significantly, and since the data is written without compression, it
will take up a lot of disk space. If the size of the output file
reaches 2 GB, it is automatically closed, and the emulator asks for
a new file to continue the recording.
NOTE: the video and audio streams in the AVI file are not affected by
any of the display or sound configuration settings.
Stop video capture, and close any AVI file that is currently being written.
Save a screenshot in 24 bit RLE compressed TGA format. The video output is captured immediately after activating this menu item, and is saved at a resolution of 768x576 without any processing (color correction, effects, etc.).
Exit the emulator.
This has the same effect as using the reset button on the real machine.
In addition to a normal reset, make sure that the emulated machine is really restarted using the standard ROM reset routines, and do not allow programs to disable reset by setting custom (RAM) handlers; however, most of the RAM data is still preserved. This option will also turn off automatically enabled extensions that increase CPU usage, such as SID emulation and 1541/1551/1581 drives with no disk opened.
Reset clock frequency and timing settings to those specified in the machine configuration; this is normally only useful after demo playback, which may override the settings. The SID and ACIA configuration, which may be changed by snapshot or demo loading, are also reset.
Reset memory configuration (RAM size, ROM images), clock frequency, and timing settings according to the machine configuration, and clear all RAM data. Implies 'Force reset' and 'Reset clock frequencies'. Reverting the configuration can be useful after snapshot loading or demo playback, as these may change the settings.
Load the configuration file ~/.plus4emu/p4vmcfg1.cfg, and apply the new settings.
Load the configuration file ~/.plus4emu/p4vmcfg2.cfg, and apply the new settings.
Save the current clock frequency and timing settings to ~/.plus4emu/p4vmcfg1.cfg.
Save the current clock frequency and timing settings to ~/.plus4emu/p4vmcfg2.cfg.
If enabled, an MPS-801 or 1526/MPS-802 printer is emulated as device 4 on the serial bus. The MPS-802 printer emulation is implemented at the hardware level for full compatibility with a real printer. On the other hand, the IEC level MPS-801 emulation uses less CPU time, prints faster, and supports printing graphics.
Shows the printer output in real time in a window. It is also possible
to save the page as a 520x736 (MPS-801) or 700x990 (MPS-802) 8-bit RLE
compressed TGA file. When the printing reaches the bottom of the page,
it stops, and the LED will flash; you can then save the page to a
file, click the 'Clear' button, and turn on and then off 'Form feed'
to continue printing.
In the case of MPS-801 emulation, the form feed button is ignored, so
it is enough to click the 'Clear' button to continue with printing the
next page; in this mode, there is also an input buffer of 128
kilobytes - until the buffer is full, the printing (and writing the
output to a text file if enabled) is not blocked on the Plus/4.
NOTE: it is recommended to close this window while using the debugger,
since it cannot display printer output then, and may slow down the
GUI.
Emulate a Trojan Light Pen connected to the first joystick port. Light pen input is only generated when a mouse button is held down while the mouse cursor is in the emulation display area.
Turn on SID emulation, making the SID registers appear at FD40-FD5F and FE80-FE9F; this increases the CPU usage of the emulator. SID emulation is also automatically enabled when a byte is written to the above mentioned address ranges, but some programs detect if a SID card is present by only reading the registers, and in those cases using this option is needed. SID emulation remains active until the next use of 'Force reset' or 'Reset machine configuration', and snapshot data includes SID state and whether it was enabled or not at the time of saving the snapshot.
Turn off SID emulation if it is currently enabled.
Resize the emulator window to predefined width/height values; this has no effect in fullscreen mode. While the window can also be resized using the window manager, sizes that are integer multiples of the actual screen resolution of the emulated machine may look better, particularly when texture filtering is not used, and are also slightly faster when using the software video driver.
Cycle between these four display modes:
Increase sound output volume by about 2 dB.
Decrease sound output volume by about 2 dB.
Opens a dialog for setting up floppy drive emulation.
For each drive, an image file can be selected. If the file name is left
empty, that means having no disk in that particular drive. It may also
be possible to directly access a real 1581 800k disk by using the
/dev/fd* devices (on Linux) or \\.\A:
(on Windows) as the image file.
The file format must be either D64 or D81; the type is determined from
the file size. Opening a D64 file will enable 1541 or 1551 emulation
for that particular drive, while the 1581 will be emulated for D81
files.
Since these drives are emulated at the hardware level (with a 6502 CPU,
etc.), enabling them increases the CPU usage. A drive will remain
active until a different type of image file is opened, or a snapshot is
loaded or 'Force reset' (or anything that implies it) is used while
there is no disk opened.
Setting the drive type of unit 8 or unit 9 to 1551, and leaving the
image file name empty enables IEC level 1551 drive emulation instead of
true (hardware level) drive emulation. This can be used to access .PRG,
.P00, .R00, .S00, and .U00 files in the currently selected working
directory, and also has the advantage of not increasing the CPU usage.
These are just shortcuts for setting the image file name for a specific floppy drive to an empty string.
Set the image file name for a specific (or all) floppy drive to an empty string, and then set the original file name again. This is mostly useful when accessing real floppy disks, after the disk is changed.
Reset a specific (or all) floppy drive.
Turn off the emulation of all floppy drives that are currently active,
but have no disk image attached. This can be useful to reduce CPU
usage when a drive is no longer needed, without having to reset the
emulated machine.
Using this option may also be needed to enable IEC level drive
emulation, which cannot be used while hardware level emulation on the
same unit is still active.
Set the directory to be accessed by the IEC level drive emulation.
NOTE: the filesystem access is read-only by default,
but writing can be enabled in the machine configuration.
This directory is also used by monitor commands that take a file name
argument.
Shows the debugger window. Many functions in the debugger can be used either in CPU addressing mode where the 16 bit address space of the currently selected CPU can be accessed, or physical address mode that allows access to all memory in the emulated system, regardless of any memory banking or the debug context selected. The following table shows the memory map in physical address mode; the 8-bit codes on the left are used in the 'Memory paging' window:
| 00 | 000000-003FFF | Basic ROM |
| 01 | 004000-007FFF | Kernal ROM |
| 02, 03 | 008000-00FFFF | Function (3-plus-1) ROM |
| 04, 05 | 010000-017FFF | Cartridge 1 |
| 06, 07 | 018000-01FFFF | Cartridge 2 (used by p4fileio.rom) |
| 0A | 028000-02BFFF | MPS-801 printer ROM (4K, repeated 4x) |
| 0C | 030000-033FFF | 1526/MPS-802 printer ROM (8K, repeated 2x) |
| 10 | 040000-043FFF | 1541 floppy drive ROM |
| 20 | 080000-083FFF | 1551 floppy drive ROM |
| 30, 31 | 0C0000-0C7FFF | 1581 floppy drive ROM |
| 40-43 | 100000-10FFFF | Main CPU address space |
| 50-53 | 140000-14FFFF | Printer CPU address space (MPS-802 only) |
| 60-63 | 180000-18FFFF | Floppy unit 8 CPU address space |
| 64-67 | 190000-19FFFF | Floppy unit 9 CPU address space |
| 68-6B | 1A0000-1AFFFF | Floppy unit 10 CPU address space |
| 6C-6F | 1B0000-1BFFFF | Floppy unit 11 CPU address space |
| FF | 3FC000-3FFFFF | RAM (16K) |
| FE-FF | 3F8000-3FFFFF | RAM (32K) |
| FC-FF | 3F0000-3FFFFF | RAM (64K; also the default bank for >64K) |
| F0-FF | 3C0000-3FFFFF | RAM (256K) |
| C0-FF | 300000-3FFFFF | RAM (1024K) |
TED and I/O registers are not mapped into the RAM or ROM areas in physical address mode.
The monitor commands are mostly similar to those in TEDMON, although most commands - with the exception of G and TR - support CPU/physical address mode switching, and the following have some improvements:
| A | Supports undocumented opcodes (using opcode names from 64doc.txt), $ characters and leading zeros are optional, assemble offset can be used to write the code to a different area than where it will actually run |
| D | Can disassemble to a file, supports undocumented opcodes and disassemble offset |
| F | It is possible to fill memory with a pattern of any length, not just a single byte |
| H | More advanced pattern matching (specific bits or bytes can be ignored); note that strings should be enclosed within double quote characters |
| T | Allows the source and destination areas to overlap |
There are also these new commands:
| ? | Prints the list of available commands |
| ? CMD | Prints help for command 'CMD' |
| AM | Set/toggle CPU/physical address mode |
| AO | Set/clear assemble and disassemble offset |
| I | Prints the current monitor settings (address mode, etc.) |
| SR | Search for and replace pattern in memory; uses the same rules as the H command, and can also ignore (not change) bits or bytes when writing the replacement pattern |
| TR | Logs CPU instructions to a file until the debugger is opened again, or the number of instructions exceeds a specified limit |
| W | Set debug context |
| X | Same as the 'Continue' button |
| Y | Same as the 'Step over' button |
| Z | Same as the 'Step' button |
Starting from version 1.2.5, it is possible to run scripts written in Lua from the debugger. This document only describes the use of scripts in the emulator, and the new API functions added; for general information about programming in Lua, see http://www.lua.org/docs.html.
Clicking the 'Run' button will run the script, and also enable the breakpoint callback function (see below) if it is defined. If there are any syntax or runtime errors, the script is terminated, and the breakpoint callback is disabled. After making any changes to the script, you need to click 'Run' and restart the script for the changes to take effect.
It is possible to define a breakpoint callback function in the script, which will be automatically called whenever a breakpoint is triggered, and the debugger window would be shown. This function has the following syntax:
function breakPointCallback(debugContext, bpType, addr, value)
...
return showWindow
end
where 'showWindow' is a boolean value, which, if true, will allow the debugger window to be shown like normal, or have the emulated program continue without any break if it is false. The four parameters passed to the function are as follows:
debugContextbpTypeaddrvalueThe breakpoint callback function will remain active until either a new script is run which does not define one, or the 'Stop' button is clicked.
NOTE: an infinite loop in the script will hang the emulator, and a very frequently called and/or complex breakpoint callback may slow down the emulation.
The following new functions are defined by the emulator for use in the scripts:
AND(...)
OR(...)
XOR(...)
SHL(a, b)
SHR(a, b)
These simple helper functions implement bitwise operations that
are not available in the Lua language by default. AND,
OR, and XOR can take any number of
integer arguments, and return the bitwise AND, OR, and XOR of the
values, respectively. In the case of zero arguments, OR
and XOR return zero, while AND
returns -1.
SHL returns 'a' shifted to the left by 'b' bits, and
SHR returns 'a' shifted to the right by 'b' bits. If
'b' is zero, the value is not changed, while a negative 'b' will
reverse the direction of shifting. The result of shifting negative
values to the right is unspecified.
getDebugContext()
Returns the current debugging context, which can be one of the following:
setDebugContext(n)
Set the debugging context to 'n' (0 to 5, see above). It is recommended to restore the original debugging context before the script returns.
setBreakPoint(bptype, addr, priority)
Set a breakpoint or watchpoint at address 'addr' (0-0xFFFF) for the current debugging context, with priority 'priority' (0 to 3). 'bptype' can be one of the following values:
NOTE: the changes made to the breakpoint list by the script are not reflected in the breakpoint editor. To restore the previously defined breakpoints, click the 'Apply' button.
clearBreakPoints()
Deletes all breakpoints that were previously defined for the current debugging context.
getMemoryPage(n)
Returns the memory bank selected for $0000-$3FFF if 'n' is 0, $4000-$7FFF if 'n' is 1, $8000-$BFFF if 'n' is 2, or $C000-$FFFF if 'n' is 3. The returned value is a 8 bit integer, as described above at the beginning of the debugger documentation.
readMemory(addr)
Read a byte from 'addr' (0 to 0xFFFF) in the address space of the current debugging context.
writeMemory(addr, value)
Write 'value' to 'addr' (0 to 0xFFFF) in the address space of the current debugging context.
readMemoryRaw(addr)
Read a byte from 'addr' (0 to 0x3FFFFF) in the "physical" address space described above at the beginning of the debugger documentation.
writeMemoryRaw(addr, value)
Write 'value' to 'addr' (0 to 0x3FFFFF) in the "physical" address space described above at the beginning of the debugger documentation.
getPC()
getSR()
getAC()
getXR()
getYR()
getSP()
These functions return the registers of the currently selected CPU. PC is a 16 bit value, while the others are 8 bit.
setPC(n)
setSR(n)
setAC(n)
setXR(n)
setYR(n)
setSP(n)
Set registers of the currently selected CPU. 'n' should be a 16 bit value when setting PC, and 8 bit for the other registers. Note that changing the program counter only takes effect after the execution of the current instruction is completed.
loadProgram(fname)
Load PRG or P00 file 'fname', which must be a full path file name. The current debugging context is ignored, and zeropage variables at $2D-$32 and $9D-$9E are updated according to the file loaded.
saveProgram(fname)
Save the memory area defined by zeropage variables $2B-$2E to a PRG file 'fname', which must be a full path file name. The current debugging context is ignored, and the data is always read from RAM, regardless of memory paging by $FF3E/$FF3F.
mprint(...)
Prints any number of strings or numbers to the monitor. No separator characters are inserted between the arguments being printed, and a newline character is automatically added at the end of the message.
mprint("Running Lua script example...")
setDebugContext(0)
clearBreakPoints()
setBreakPoint(2, 0x0C00, 2)
setBreakPoint(2, 0x0C01, 2)
function breakPointCallback(d, t, a, v)
if (a == 0x0C00 and v == 0x00) or
(a == 0x0C01 and v == 0x01) then
return true
end
return false
end
mprint("done.")
This will break only when $00 is written to $0C00, or $01 is written to $0C01.
© Istvan Varga
<istvanv@users.sourceforge.net>, 2008