forked from libretro/ep128emu-core
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
1106 lines (916 loc) · 46.7 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
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)