ep128emu 2.0.11.2
=================
ep128emu is an open source, portable emulator of the Enterprise 128,
ZX Spectrum 48/128, Amstrad CPC 464/664/6128 and Videoton TVC computers,
written in C++, and supporting Windows and POSIX platforms (32 and 64
bit Windows and Linux, and MacOS X have been tested).
It implements accurate, high quality hardware emulation, however, the
system requirements are higher than that of most other emulators.
Features
========
General
-------
* graphical user interface using the FLTK library
* software (FLTK based) or OpenGL video, with resizable emulator
window, fullscreen mode, brightness, contrast, gamma, hue, and color
saturation control; additional features in OpenGL mode only: single
or double buffered (with synchronization to vertical refresh) mode,
linear texture filtering, resampling video output to the monitor
refresh rate, and some display effects: motion blur, scanline
shading, and (if OpenGL 2.0 shaders are available) PAL TV emulation
* real time audio output uses the PortAudio library (v18 or v19), with
support for many native audio APIs (MME/DirectSound/WDM-KS/WASAPI on
Windows, OSS/ALSA/JACK on Linux, and CoreAudio on MacOS X); high
quality sample rate conversion with low aliasing; volume control,
two first order highpass filters with configurable cutoff frequency,
and an optional parametric equalizer can be applied to the audio
signal
* recording audio output to a WAV format sound file
* recording video and sound output to an AVI format video file, with
768x576 RLE8 or 384x288 uncompressed YV12 video at 24 to 60 frames
per second, and 48000 Hz stereo 16-bit PCM audio
* saving screenshots as 768x576 8-bit PNG format files
* saving and loading snapshots of the state of the emulated machine
* demo recording (snapshot combined with stream of keyboard and mouse
events which can be played back with accurate timing)
* tape emulation with playback, recording, and setting tape position;
markers can be created for quick positioning to specific tape
locations (useful for tapes with multiple files); uses custom file
format which is PCM audio data with 1 to 8 bits of sample resolution
and variable sample rate, and header including the table of markers;
there is also limited (read only) support for EPTE format tape
files, as well as read-write (although without markers) support for
sound files like WAV, AIFF, etc.
* GUI tape editor utility for copying Enterprise files from/to
ep128emu tape images
* GUI debugger with support for breakpoints/watchpoints, viewing the
current state of CPU registers and memory paging, displaying memory
dump and searching for a pattern of bytes, and disassembler with
support for all documented and undocumented Z80 opcodes.
A simple monitor is also included, with commands like assemble,
disassemble (also to file), trace, memory and I/O port dump and
modify, printing and changing CPU registers, memory compare, copy,
fill, search, load and save, and more.
For most operations, addresses can be 16 bit CPU (affected by
current paging) or 22 bit physical (all ROM and RAM data can be
accessed, regardless of memory paging) addresses. Watchpoints can
also be set on I/O ports and physical addresses.
The debugger supports scripting in the Lua language, to allow for
advanced uses like breakpoints with custom defined, complex set of
conditions.
* configurable keyboard map for the emulated machine; it is also
possible to use external game controller devices like joysticks and
gamepads
Enterprise emulation
--------------------
* instruction based emulation of the Z80 CPU, supports all documented
and undocumented opcodes, and memory wait states (including
synchronization with the NICK chip when accessing video memory)
* RAM size can be set in 16 kilobyte steps in the range 64 to 3712
* ROM can be loaded from external image files to segments 0 to 7,
16 to 19 (decimal), 32 to 35, 48 to 51, and 64 to 67
* using external configuration files, it is also possible to define
any memory configuration without the above limitations
* NICK chip emulation, supporting all documented and undocumented
video modes
* DAVE emulation, including timers, interrupts, external ports for
tape and keyboard/joystick, memory paging, and sound output (all
effects are supported, and the polynomial counters generate the same
pseudo-random "noise" pattern as on the real machine)
* tape emulation (see general features for details)
* WD177x (floppy drive controller) emulation for EXDOS
* IDE hard disk emulation; supports up to 4 2 GB disks, image files
can be in raw or VHD format
* optional extension ROM (epfileio.rom) that implements a FILE: device
for direct access to files on the host system in a single user
selectable directory
* Spectrum emulator card emulation
* real time clock (at ports 7E, 7F)
* external 4-channel 8-bit DAC at ports F0 to F3
* mouse emulation, an EnterMice device with up to 5 buttons and mouse
wheel is emulated in native mode on column K of the keyboard matrix
* SD card (SDEXT) emulation, this is an experimental feature based on
code from LGB's Xep128 emulator
* SID card emulation at ports 0E (address) and 0F (data) using reSID
1.0; NOTE: this currently breaks the external DAC emulation when
active
Spectrum emulation
------------------
* instruction based emulation of the Z80 CPU, supports all documented
and undocumented opcodes, and cycle accurate synchronization with
the ULA chip when accessing video memory and I/O ports
* RAM size can be 16, 48, or 128 kilobytes
* ROM can be loaded from external image files
* ULA, AY-3-8912, keyboard, and Kempston joystick emulation
* tape emulation (see general features for details)
* Spectrum tape files in .tap format can be used as tape images for
read-only hardware level tape emulation, or loaded directly to
memory if the "Enable virtual file I/O" option is checked in the
machine configuration
* it is also possible to load .tzx format tape images, although the
support for these is not complete yet
* loading SNA and Z80 format snapshot files created by other emulators
is supported; however, snapshot saving and demo recording are only
possible in the native ep128emu format
Amstrad CPC emulation
---------------------
* instruction based emulation of the Z80 CPU, supports all documented
and undocumented opcodes, and cycle accurate synchronization with
the CRTC and gate array when accessing video memory and I/O ports
* RAM size can be 64, 128, 192, 320, or 576 kilobytes
* ROM can be loaded from external image files to the lower ROM and
expansion ROMs 0 to 7
* 6845 CRTC (currently type 0 only), gate array, AY-3-8912, 8255 PPI
(modes 1 and 2 are not supported yet), keyboard, and joystick
emulation
* tape emulation (see general features for details)
* CPC tape files in .cdt (same as Spectrum .tzx) format can be used as
tape images for read-only hardware level tape emulation, although
the support for this format is not complete yet
* uPD765 (floppy drive controller) emulation; it supports standard and
extended .DSK files, and also access to real disks (not very useful
in practice, since only PC format disks can be used this way), as
well as limited emulation of the timing of disk rotation, stepping,
and data transfers. The FORMAT TRACK (0x0D) command is not
implemented yet, and some copy protected games and .DSK files with
unusual track formats may not work correctly
* loading SNA snapshot files (v1 or v2; v3 is loaded, but the extra
information about the internal state of the hardware is currently
ignored) created by other emulators is supported; however, snapshot
saving and demo recording are only possible in the native ep128emu
format
Videoton TVC emulation
----------------------
* instruction based emulation of the Z80 CPU, supports all documented
and undocumented opcodes, and cycle level synchronization with the
CRTC and other devices when accessing video memory and I/O ports
* RAM size can be 48, 80 or 128 kilobytes (TVC 32, 64 or 64+)
* ROM can be loaded from external image files to SYS, CART and EXT
* 6845 CRTC (currently type 0 only), audio, keyboard and joystick
emulation
* tape emulation (see general features for details)
* WD1773/1793 (floppy drive controller) emulation for VT-DOS
* optional extension ROM (tvcfileio.rom) that implements a FILE device
for direct access to files on the host system in a single user
selectable directory
* SD card (SDEXT) emulation, this is an experimental feature based on
code from LGB's Xep128 emulator
Installation
============
Linux
-----
On Linux and other POSIX platforms, the emulator is installed from the
source code, available at the GitHub download page
https://github.com/istvan-v/ep128emu/releases/
or the most recent state of the code can be downloaded from Git with the
following command:
git clone https://github.com/istvan-v/ep128emu.git
In addition to the standard development tools (a recent version of the
GNU C/C++ compiler, binutils, etc.), you need the following packages:
* SCons (http://www.scons.org/)
* Python interpreter for running SCons
* FLTK 1.3.x (http://www.fltk.org/software.php?VERSION=1.3.4) or
1.1.x (http://www.fltk.org/software.php?VERSION=1.1.10)
NOTES:
* this library should be compiled with the --enable-threads
'configure' option - many Linux distributions include binaries
of FLTK 1.1 built without --enable-threads, so you may need to
compile it from sources
* on MacOS X, FLTK 1.1.7 needs to be patched with the included
fltk-1.1.7-MacOSX.patch file
* PortAudio (http://www.portaudio.com/download.html), version 18 and
19 are supported, but v19 is recommended
* libsndfile (http://www.mega-nerd.com/libsndfile/#Download)
The following packages are optional:
* OpenGL for improved video display and effects
* SDL (http://www.libsdl.org/) 1.2 for joystick input; NOTE: on Linux,
versions 1.2.10 and newer do not work if they are statically linked
and were built with video support (--enable-video)
* Lua (http://www.lua.org/ or http://www.luajit.org/) for scripting in
the debugger; version 5.1 or newer is recommended, but 5.0 is also
supported
* libcurl (https://curl.haxx.se/) for ROM download support in
epmakecfg
Once these are installed, you can edit the file 'SConstruct' in the top
level source directory for setting compiler flags etc., and run the
command 'scons -j 2' for building the emulator. The following options
can be passed to scons:
-j N
Maximum number of parallel jobs to be run by scons. It is
recommended to set N to the number of logical cores of your CPU
win64=1
Cross-compile Windows x86_64 binaries using Wine
(http://www.winehq.com/) and MinGW; complete pacakges of MinGW for
building the emulator can be downloaded from:
https://www.dropbox.com/s/ex0zxz7e6bmcb9r/mingw_w64-x64.7z?dl=1
https://www.dropbox.com/s/a336x3bs1p0gv3t/mingw_w64-x86.7z?dl=1
win32=1
Cross-compile Windows i686 binaries using Wine and MinGW
linux32=1
Build 32-bit Linux binaries on a 64-bit system without using
pkg-config
nosdl=1
Disable the use of SDL and joystick support. This option may be
needed on Linux with statically linked SDL versions 1.2.10 and
newer that were built with video support enabled
nolua=1
Build without support for Lua scripting
utils=0
Do not build the optional utilities (epimgconv and epcompress)
glshaders=0
Disable the use of OpenGL shaders
debug=1
Compile binaries for debugging: no optimization and more warnings
release=0
Do not build a release version: binaries are not stripped and are
compiled with less optimization. Implied by debug=1
luajit=1
Use LuaJIT (installed as Lua 5.1) on Windows
z80cmos=1
Emulate the CMOS version of the Z80 CPU
sdext=0
Disable SD card (SDEXT) emulation
resid=0
Disable SID card emulation
curl=0
Do not use libcurl in epmakecfg for downloading the ROM package
cflags="..."
Additional flags to be passed to the compiler or linker
nopkgconfig=1
Disable the use of pkg-config and fltk-config to automatically
configure libraries
cache=1
Enable the use of scons build cache in '.build_cache'
An 'install' target is also supported by SConstruct, this will install
the emulator binaries under ~/bin, and the configuration and data files
under ~/.local/share/ep128emu. Running 'scons -c install' will remove
most of the installed files.
Alternatively, you can copy the executables (ep128emu, epcompress,
epimgconv, epmakecfg and tapeedit) to any directory that is in the PATH;
on MacOS X, an .app package is created in 'ep128emu.app'.
When installing the first time, you also need to set up configuration
files and ROM images. If epmakecfg was built with libcurl support, the
following steps can be skipped, the configuration utility is run
automatically by ep128emu when needed, and it can download and install
the ROM images.
Before installation, download ep128emu_roms-2.0.11.bin from
https://enterpriseforever.com/letoltesek-downloads/egyeb-misc/msg61025
and copy it to:
~/.local/share/ep128emu/roms (for 'scons install')
~/.ep128emu/roms (for manual installation)
~/Library/Application Support/ep128emu/roms (on Mac OS X)
If not using 'scons install', run 'epmakecfg' and click OK to the
windows that pop up asking for the base directory of configuration and
data files, and if configuration files should be installed.
It is possible to reinstall configuration files later by running the
'epmakecfg' utility. ROM images can be installed manually by downloading
ep128emu_roms-2.0.11.7z from the above location and extracting it in the
correct directory. The .bin format ROM package can be unpacked with the
command 'epcompress -x -a ep128emu_roms-2.0.11.bin' in the current
directory, 'epmakecfg' does this automatically if it finds the package
where the ROM images need to be installed.
Windows
-------
A binary package with an installer is available at the GitHub download
page:
https://github.com/istvan-v/ep128emu/releases/
Older (pre-2.0.10) versions can be downloaded from SourceForge:
https://sourceforge.net/projects/ep128emu/files/
To install, just run the executable, and follow the instructions. The
installer can automatically download the ROM images needed for running
the emulator, but these can also be installed manually by downloading
ep128emu_roms-2.0.11.7z from
https://enterpriseforever.com/letoltesek-downloads/egyeb-misc/msg61025
and extracting it to roms\ under the selected installation folder.
When asked if configuration files should be reinstalled, click 'OK'
when installing the first time, but this step can be skipped in later
installations to preserve the configuration.
WARNING: on Windows, there may be timing problems when using some dual
core CPUs, or power management features that change the clock frequency
of the CPU while the emulator is running. These issues can result in
slow or erratic emulation speed, not running at 100% speed in real-time
mode, or temporary lockups. If you encounter such problems, forcing the
emulator to run on a single core (by setting the CPU affinity for
ep128emu.exe), and/or disabling dynamic changes to the CPU clock
frequency by power management could fix the timing issues. Installing
and using an utility like AMD Dual Core Optimizer may also solve the
problem.
Note that bad emulation performance might also be caused by display or
audio drivers, so it is recommended to check (and upgrade, if necessary)
those as well.
Usage
=====
Command line options
--------------------
-h
-help
--help
print the list of available command line options
-ep128
-zx
-cpc
-tvc
select the type of machine (Enterprise, ZX Spectrum, CPC or TVC) to
be emulated
-cfg <FILENAME>
load an ASCII format configuration file on startup, and apply
settings
-snapshot <FILENAME>
load snapshot or demo file on startup
-opengl
use OpenGL video driver (this is the default, and is recommended
when hardware accelerated OpenGL is available)
-no-opengl
use software video driver; this is slower than OpenGL when used at
high resolutions, and also disables many display effects, but should
work on all machines; however, it will use a color depth of 24 bits,
while in OpenGL mode the textures are 16 bit (R5G6B5) only, to
improve performance
-colorscheme <N>
select GUI color scheme N (0, 1, 2, or 3)
OPTION=VALUE
set configuration variable 'OPTION' to 'VALUE'; the available
variable names are the same as those used in ASCII format
configuration files
OPTION
set boolean configuration variable 'OPTION' to true
'File' menu
-----------
Configuration / Load from ASCII file (Alt + Q)
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.
Configuration / Load from binary file (Alt + L)
Load an ep128emu format binary file, which may be a previously saved
snapshot, demo, or a binary format configuration file.
Configuration / Save as ASCII file
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.
Configuration / Save
Save the current emulator configuration in binary format to the
default file (~/.ep128emu/ep128cfg.dat). This is also automatically
done when exiting the emulator.
Configuration / Revert
Reload emulator configuration from ~/.ep128emu/ep128cfg.dat, and apply
the original settings.
Save snapshot (Alt + S)
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, but new
versions of the emulator can still load old snapshots. Note that the
state of any disk drives is currently not saved, and the drives are
reset on loading a snapshot.
Starting from version 2.0.10 of ep128emu, snapshot and demo files can
optionally be saved in a compressed format, if this feature is enabled
in the machine configuration. Compressing a large snapshot can take a
few seconds on a slow PC, but the loading time is not affected
noticeably.
Load snapshot (Alt + L)
Load an ep128emu format binary file, which may be a previously saved
snapshot, demo, or a binary format configuration file.
Quick snapshot / Set file name
Select file name for quick snapshots. The default is
~/.ep128emu/qs_ep128.dat. This setting is not saved on exit, and quick
snapshots are always saved in uncompressed format.
Quick snapshot / Save (Ctrl + F9)
Save snapshot to the quick snapshot file (see notes above).
Quick snapshot / Load (Ctrl + F10)
Load the quick snapshot file if it exists.
Record demo
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 demo (Alt + K)
Stop any currently running demo playback or recording.
Load demo (Alt + L)
Load an ep128emu format binary file, which may be a previously saved
snapshot, demo, or a binary format configuration file.
Record audio / Start...
Write 16 bit signed PCM sound output to a WAV format sound file.
Record audio / Stop
Close sound output file if it is currently being written.
Record video / Start...
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. There are two
options in the machine configuration that affect the video capture:
the frame rate and the codec. It is recommended to use the defaults
(RLE8 768x576 at 50 fps) when possible, but RLE8 is not always
supported by other software, in those cases it may be necessary to use
the YV12 codec, which decreases the quality while usually increasing
the output file size and CPU usage.
Record video / Stop
Stop video capture, and close any AVI file that is currently being
written.
Save screenshot (F12, Alt + C)
Save a screenshot in 8 bit PNG 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.).
Quit (Shift + F12)
Exit the emulator.
'Machine' menu
--------------
Reset / Reset (F11)
This has the same effect as using the reset button on the real
machine.
Reset / Force reset (Ctrl + F11)
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.
Reset / Reset clock frequencies
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.
Reset / Reset machine configuration (Shift + F11)
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.
Quick configuration / Load config 1 (PageDown)
Load the configuration file ~/.ep128emu/epvmcfg1.cfg, and apply the
new settings.
Quick configuration / Load config 2 (PageUp)
Load the configuration file ~/.ep128emu/epvmcfg2.cfg, and apply the
new settings.
Quick configuration / Save config 1
Save the current clock frequency and timing settings to
~/.ep128emu/epvmcfg1.cfg.
Quick configuration / Save config 2
Save the current clock frequency and timing settings to
~/.ep128emu/epvmcfg2.cfg.
'Options' menu
--------------
Display / Set size to 384x288
Display / Set size to 768x576
Display / Set size to 1152x864
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.
Display / Cycle display mode (F9)
Cycle between these four display modes:
window with no menu bar
window with menu bar (this is the default)
fullscreen with menu bar
fullscreen with no menu bar (recommended for mouse emulation)
Sound / Increase volume
Increase sound output volume by about 2 dB.
Sound / Decrease volume
Decrease sound output volume by about 2 dB.
Disk / Configure... (Alt + D)
Opens a dialog for setting up floppy, IDE and SD card emulation.
For each floppy drive, an image file can be selected, and disk
geometry parameters can be specified. 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 disk by using the /dev/fd* devices
(on Linux) or \\.\A: (on Windows) as the image file.
Any of the geometry parameters can be zero or negative to have the
value calculated automatically from the others (if available), the
image file size, and the file system header.
The IDE and SD card emulation support image files in raw and VHD
format (the latter should have a .vhd extension), with a file size of
up to 2 GB. In the case of VHD files, the disk geometry is determined
by the VHD footer, while the geometry of raw images is calculated from
the file size. Depending on the image format, the model number string
of the emulated drive will include "(VHD)" or the automatically
assigned geometry.
The emulator package includes a 126 MB VHD format IDE disk image in
disk/ide126m.vhd.bz2, with 4 FAT12 formatted 31.5 MB partitions.
Note that with the current version of IDE.ROM, after changing IDE disk
images, a cold reset is required for the changes to be detected, and
the disk change flag is also set on snapshot or demo loading.
All data storage devices are disabled while recording or playing a
demo.
Disk / Remove floppy / Drive A
Disk / Remove floppy / Drive B
Disk / Remove floppy / Drive C
Disk / Remove floppy / Drive D
Disk / Remove floppy / All drives
These are just shortcuts for setting the image file name for a
specific floppy drive to an empty string.
Disk / Replace floppy / Drive A (Alt + H)
Disk / Replace floppy / Drive B
Disk / Replace floppy / Drive C
Disk / Replace floppy / Drive D
Disk / Replace floppy / All drives
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, and should be used
after the disk is changed.
Set working directory (Alt + F)
Set the directory to be accessed by the optional file I/O ROM
extension modules.
Memory configuration files
--------------------------
While the GUI based memory configuration is easy to use, and is
sufficient for creating the most commonly used configurations, it does
have a number of limitations. Using a configuration file - which is a
simple text file with a format described below - makes it possible to
have RAM, ROM, or no memory at any segment, and image files can also be
loaded to RAM (e.g. for emulating static RAM).
NOTE: if a memory configuration file is specified, the RAM/ROM settings
in the "Machine configuration" GUI are ignored.
A memory configuration file may contain any number of segment range
definitions, each being a line in one of the following formats for RAM
or ROM:
0xNN RAM "fileName" nSegments
0xNN ROM "fileName" nSegments
where 'NN' is the number of the first segment (hexadecimal), 'fileName'
is the name of the file to be loaded (with full path; backslash or
double quote characters in the name should be escaped with a backslash),
and 'nSegments' is the number of segments to be defined as RAM or ROM
(decimal). If 'nSegments' is not specified, then it defaults to 1 for an
empty file name, otherwise it is determined by the size of the image
file. If 'fileName' is also omitted, then it means a single empty
segment.
The configuration file may also include comments and empty lines.
A comment can begin with the semicolon or '#' character, and the rest of
the line is ignored.
Similarly to images loaded in the GUI ROM configuration, it is not
necessary for the files to have a size that is an integer multiple of
16384 bytes: the last segment is padded with FFh bytes. An empty file
name will initialize RAM segments to FFh bytes, while in the case of
ROM, it means that the segments will be empty. If the file is longer
than the size defined by 'nSegments', the data is truncated; if it is
too short, then the segments are repeated.
By default, segments 00h..FBh are empty, and FCh..FFh are RAM. The type
of the last four segments (the video memory) cannot be changed to ROM.
A simple example file, assuming that the emulator is installed to
"C:\Program Files\ep128emu2":
; EXOS 2.1 at segments 0, 1 (and repeated at segments 2, 3)
0x00 ROM "C:\\Program Files\\ep128emu2\\roms\\exos21.rom" 4
; IS-BASIC 2.1 at segment 4
0x04 ROM "C:\\Program Files\\ep128emu2\\roms\\basic21.rom"
; 128K RAM at segments F8h..FFh
0xF8 RAM "" 8
Reading I/O ports in the debugger
---------------------------------
Write-only I/O ports are readable in the monitor and Lua scripts, and
return the last value written to the port. There are also some changes
to the address decoding compared to what is seen by the emulated Z80
code, depending on the machine type:
- Spectrum:
- below port address 20H, the Kempston joystick state is read from
all addresses
- the last value written to the ULA is read from any other even
address that is less than 100H
- in Spectrum 128 mode, if the address is less than 100H, and the
lowest two bits are 01B, the memory paging register is returned
- reading any other I/O port below 100H returns FFH
- reading from ports 0xxxxxxxxxxxxx0xB does not write the data bus
state to the memory paging register
- CPC:
- when reading the gate array/RAM configuration port, the function
(pen/color/video mode/memory configuration) can be selected in
bits 6 and 7 of the address; for example, reading port 7F40H
returns the color of the currently selected pen
- in the address range 0 to 9FH, many I/O registers can be read
directly:
- 00H-1FH: 6845 CRTC registers
- 20H-2FH: gate array palette
- 30H-3FH: gate array border color
- 40H-4FH: AY-3-8912 registers
- 50H-5FH: 8255 PPI registers
0101x000B: port A current state (input or output)
0101x001B: port B current state (input or output)
0101x010B: port C current state (input or output)
0101xx11B: control register
0101x100B: last value written to port A register
0101x101B: last value written to port B register
0101x110B: last value written to port C register
- 60H-6FH: keyboard matrix state
- 70H: currently selected CRTC register
- 71H: CRTC flags
bit 0: 1 if the "display enabled" output is active
bit 1: 1 if the HSYNC output is active
bit 2: 1 if the VSYNC output is active
bit 3: 1 if the current field is odd in interlaced modes
bit 4: 1 if the "cursor enabled" output is active
- 72H: current video memory address / low
- 73H: current video memory address / high
- 74H: video mode (0 to 3)
- 75H: currently selected pen number
- 76H: gate array IRQ counter (0 to 51)
- 77H: AY-3-8912 register selected
- 78H: RAM configuration (bits 6 and 7 are RAM enable flags
for page 0 and page 3)
- 79H: currently selected expansion ROM bank
- 7AH-7FH: unused, FFH is returned
- 80H-9FH: uPD765 floppy drive controller registers and state
80H: FDC phase (0: idle, 1: command, 2: execution, 3: result)
81H: last command code
82H: motor state (last byte written to 0FA7EH & 01H)
83H: currently selected physical head (0 or 1) * 4 + drive
84H: CPU<->FDC data transfer position LSB
85H: CPU<->FDC data transfer position MSB
86H: CPU<->FDC data transfer size LSB
87H: CPU<->FDC data transfer size MSB
88H: logical cylinder ID
89H: logical head ID
8AH: logical sector ID
8BH: sector size code
8CH: last sector ID (EOT), or sector count for format track
8DH: gap length
8EH: sector data length (DTL), or STP for scan commands
8FH: filler byte (format track only)
90H: first byte in command/data/result buffer
91H: second byte in command/data/result buffer
92H: third byte in command/data/result buffer
93H: fourth byte in command/data/result buffer
94H: ST1 for read/write commands
95H: ST2 for read/write commands
96H: specify parameter 1 (step rate / head unload time)
97H: specify parameter 2 (head load time)
98H: ST3 for sense drive status on drive 0
99H: ST3 for sense drive status on drive 1
9AH: ST3 for sense drive status on drive 2
9BH: ST3 for sense drive status on drive 3
9CH: drive 0 cylinder number (PCN0)
9DH: drive 1 cylinder number (PCN1)
9EH: drive 2 cylinder number (PCN2)
9FH: drive 3 cylinder number (PCN3)
- unlike the other machine types, I/O watchpoints are set on the
upper 8 bits of the address
- Enterprise: when the SD card emulation is enabled, segment 07H is
handled in a special way, and its original contents cannot be
accessed:
- 0000H-1FFFH: a 8 KB page of the 64 KB flash ROM
- 2000H-3BFFH: 7 KB static RAM
- 3C00H-3FFFH: memory mapped I/O, 4 registers are repeated 256 times
Reading the I/O area in the debugger ignores the high speed mode
bit, and some of the registers have additional readable bits:
- xxxxxxxxxxxx01B (status):
bit 0: 1 if CS0 is active
bit 1: 1 if CS1 is active
bit 2: 1 if the card is in idle state
- xxxxxxxxxxxx10B (ROM page) is readable in the debugger
- xxxxxxxxxxxx11B (high speed read configuration):
bit 7: 1 if high speed reading is enabled
Lua scripting
-------------
Starting from version 2.0.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(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:
bpType
The type of break, one of the following:
0: breakpoint at opcode read by the CPU
1: data read from memory
2: data written to memory
3: opcode read in single step mode; this happens when 'Step' or
'Step over' are being used, and if the breakpoint callback
function returns false, breaks will continue to occur until
true is returned
5: I/O port read
6: I/O port write
addr
This is the 16 bit address where the break occured.
value
The value or CPU opcode read from or written to memory or I/O port.
The 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 versions 5.2 and older of the Lua language by
default. If the emulator is built with Lua 5.3 or newer, then using
the operators &, |, ~, <<, and >> is recommended.
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.
setBreakPoint(bptype, addr, priority)
Set a breakpoint or watchpoint at address 'addr' (0-0xFFFF), with
priority 'priority' (0 to 3). 'bptype' can be one of the following
values:
0: any memory access (read, write, or Z80 opcode read)
1: memory read
2: memory write
3: any memory access, same as bptype == 0
4: Z80 opcode read
5: I/O port read
6: I/O port write
7: I/O port read or write
For memory breakpoints, it is possible to add 8 to 'bpType' to
interpret the address as a 22 bit value in the range 0 to 0x3FFFFF,
with the segment number determined by the most significant 8 bits.
If the address is greater than 0xFFFF, it is also automatically
assumed to be in 22 bit format.
An "ignore" breakpoint can be defined by adding 16 to 'bpType', this
will disable other breakpoints when the program counter is at the
address to be ignored. It is still possible to have a normal read or
write breakpoint as well at the same address, by setting the lowest
three bits of 'bpType' to 1, 2, or 3.
A 'priority' value of -1 will delete an existing breakpoint at the
specified address.
The read, write, execute, and ignore flags are combined (bitwise OR)
if multiple breakpoints are set at the same address, while the
priority will be the highest value specified.
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 previously defined breakpoints.
getMemoryPage(n)
Returns the segment selected for page 'n' (0 to 3).
In Spectrum or CPC emulation mode, RAM is mapped starting from
segment 00H. For the CPC, segments 00H to 03H are the internal RAM,
the lower ROM is at segment 80H, and expansion ROM 'n' is at segment
C0H + 'n'; this function returns the number of the segment for read
access (i.e. ROM if it is enabled). In the case of ZX Spectrum, the
ROM is at segment 80H (Spectrum 16 and 48), or segments 80H and 81H
(Spectrum 128).
readMemory(addr)
Read a byte from 'addr' (0 to 0xFFFF) in the address space of the
CPU.
writeMemory(addr, value)
Write 'value' to 'addr' (0 to 0xFFFF) in the address space of the
CPU.
readMemoryRaw(addr)
Read a byte from 'addr' (0 to 0x3FFFFF) in the "physical" address
space; the most significant 8 bits of 'addr' select the segment
number.
writeMemoryRaw(addr, value)
Write 'value' to 'addr' (0 to 0x3FFFFF) in the "physical" address
space; the most significant 8 bits of 'addr' select the segment
number.
writeROM(addr, value)
This function is similar to writeMemoryRaw(), but it can write to
any valid segment, even if it is ROM.
readWord(addr)
writeWord(addr, value)
readWordRaw(addr)
writeWordRaw(addr, value)
writeWordROM(addr, value)
These are similar to the memory read/write functions above, but read
and write 16-bit LSB-first words instead of single bytes.
readIOPort(addr)
Read a byte from I/O port 'addr' (0 to 0xFFFF).
writeIOPort(addr, value)
Write 'value' to I/O port 'addr' (0 to 0xFFFF).
getPC() getA() getF() getAF() getB() getC()
getBC() getD() getE() getDE() getH() getL()
getHL() getSP() getIX() getIY() getAF_() getBC_()
getDE_() getHL_() getIM() getI() getR() getIFF1()
getIFF2()
These functions return the registers of the CPU.
setPC(n) setA(n) setF(n) setAF(n) setB(n) setC(n)
setBC(n) setD(n) setE(n) setDE(n) setH(n) setL(n)
setHL(n) setSP(n) setIX(n) setIY(n) setAF_(n) setBC_(n)
setDE_(n) setHL_(n) setIM(n) setI(n) setR(n) setIFF1(n)
setIFF2(n)
Set CPU registers. Note that changing the program counter only takes
effect after the execution of one instruction is completed.
getNextOpcodeAddr(addr[, cpuAddressMode])
Returns the address of the next Z80 instruction after the
instruction at 'addr'. 'cpuAddressMode' selects the use of 16 bit
CPU (if true or not specified) or 22 bit physical (if false)
addresses.
getVideoPosition()
Returns the current video position as two values (horizontal and
vertical).
In the case of Spectrum emulation, both values are in pixels, in the
range 0 to 447 and 0 to 311 for the Spectrum 48, or 0 to 455 and 0
to 310 for the Spectrum 128.
The upper left corner of the screen is at 0,0 (it is the cycle when
the byte read from 4000H appears on the floating bus), and the lower
right corner is at 255,191.
The line number is incremented 64 pixels before X=0 (X=384 or X=392
in 48K or 128K mode, respectively), but this may possibly change in
future versions.
For the Enterprise, the horizontal position is in characters, in the
range 0 to 56. The vertical position is the sum of the 8-bit line
counter within the current line parameter block (LPB), which counts
up to 255, and the video memory address of the LPB multiplied by 16.
In CPC emulation mode, the horizontal position is in characters, and
the vertical position is in raster lines, i.e. 0 to 63 and 0 to 311
with the default CRTC settings. Position 0,0 is the upper left
corner of the screen, this is the CRTC cycle when the first two
bytes of the screen memory are read. In the case of interlaced video
mode (CRTC register 8 = 3), the vertical position is in frame lines,
and is incremented by two each line (it is even or odd depending on
the current field).
getRawAddress(segment, offset)
Calculates a 22-bit physical address from the specified segment and
offset; only the 14 least significant bits of 'offset' are used.
getRawAddress(addr)
Calculates a 22-bit physical address from a 16-bit CPU address,
using the current memory paging.
loadMemory(fname, asciiMode, cpuAddressMode, startAddr[, endAddr])
Loads a file to the memory area at 'startAddr' to 'endAddr' (the
byte at 'endAddr' is still loaded). If no end address is specified,
all data is read into memory. The file is searched in the working
directory set for file I/O, and if the name is an empty string, a
file selection dialog is shown. The expected file format is binary
if 'asciiMode' is false, and hexadecimal dump (as written by
saveMemory() or the 'S' monitor command) if 'asciiMode' is true.
'cpuAddressMode' selects the use of 16 bit CPU (if true) or 22 bit
physical (if false) addresses.
The return value is the number of bytes actually read.
saveMemory(fname, asciiMode, cpuAddressMode, startAddr, endAddr)
Save the memory area at 'startAddr' to 'endAddr' (the byte at
'endAddr' is still written) to a file, in binary (if 'asciiMode' is
false) or hexadecimal dump (if 'asciiMode' is true) format.
'cpuAddressMode' selects the use of 16 bit CPU (if true) or 22 bit
physical (if false) addresses.
loadROMSegment(segment, fname, offset)
Load a file to the specified segment as ROM, skipping 'offset' bytes
at the beginning of the file. An empty file name deletes the
segment.
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.
Example:
mprint("Running Lua script example...")
clearBreakPoints()
setBreakPoint(4, 0x0040, 2) -- break on reading Z80 opcode at 0x0040
function breakPointCallback(t, a, v)
if t == 3 then -- allow stepping
return true
end
-- check for EXOS 1 call with A=102
if getPC() ~= 0x0040 or getA() ~= 1 or readMemory(0x005A) ~= 102 then
return false
end
-- read name parameter from memory
s = ""
n = readMemory(getDE())
for i = 1, n do
s = s..string.char(readMemory(getDE() + i))
end
mprint("Channel #102 is opened with name '", s, "'")
return true
end
mprint("done.")
This will break when channel 102 is opened, and print the name parameter
passed to the EXOS call.
------------------------------------------------------------------------
Copyright
=========
ep128emu is copyright © 2003-2017 by Istvan Varga
<istvanv@users.sourceforge.net>. Z80 emulation copyright © 1999-2003 by
Kevin Thacker and Vincze Béla György. dotconf 1.3 is copyright by Lukas
Schröder and William Hubbs. reSID 1.0 copyright © 2010 by Dag Lem.
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 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
General Public License for more details.
You should have received a copy of the GNU 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
Credits
-------
Thanks to:
Zozosoft - hardware testing and information, ROM packages
MrPrise - ep128emu.enterpriseforever.com web site
Attus - Linux fixes and binary packages for the UHU distribution
Martin Bantz - PCLinuxOS RPM spec file
LGB - GitHub import from SourceForge, Linux testing and fixes,
SD card emulation