EP128Emu manual

From Enterprise Wiki
Jump to: navigation, search

Introduction

Currently EP128Emu is the most accurate Enterprise emulator for the PC and provides the most options, though it might seem complicated to use for beginners. This manual has been produced for them. We hope that after reading this manual anybody will be able to use this lovely emulator. The alternative is the EP32, which is also a great emulator, though with less options, but ideal for beginners because of its easy usability. The most recent version of the EP128Emu is 2.0.11.2. This is a rewritten version in C++ of the earlier EP128Emu v1.x.x written in C, with many more options to be set, with a better built-in debugger and with a more accurate emulation. EP128Emu is the work of István Varga.

Installation

Windows

When installing the emulator, Source code and Download old ROMs don't need to be ticked by novice users.

Source code is needed only for developing the emulator, and old ROMs are needed only if you want to use config files for older versions. Thus, if you are installing the emulator for the first time you can untick everything except for Download ROM images.

If you have already got the ROM files, you can also untick Download ROM images. However it is recommended that you download the ROM package because there may have been upgrades. ROMs are stored in the \Program Files\ep128emu2\roms directory, and all ROMs that are to be used should be put here. While installing the emulator the following ROMs are downloaded from the net:

Enterprise

Spectrum

  • zx128.rom
  • zx48.rom
  • zx48gw03.rom

CPC

  • cpc464.rom
  • cpc6128.rom
  • cpc664.rom
  • cpc_amsdos.rom

TVC

  • tvc12_ext.rom
  • tvc12_sys.rom
  • tvc21_ext.rom
  • tvc21_sys.rom
  • tvc22_ext.rom
  • tvc22_sys.rom
  • tvc_dos11c.rom
  • tvc_dos11d.rom
  • tvc_dos12c.rom
  • tvc_dos12d.rom
  • tvcfileio.rom
  • tvc_sdext.rom
  • tvcupm_c.rom
  • tvcupm_d.rom

Most of these are familiar to those who have already used the Enterprise but there are a number of new ROMs, because the development team is still active even in the early years of the 21st century. EPFileIO.rom is not used in real Enterprise machines, but makes it easier to load files into the emulator - for instructions see below.

If you have a Hungarian PC keyboard Use Hungarian keyboard map has to be ticked - otherwise you won't be able to use the keyboard properly.

The question Reinstall ep128emu configuration files? must be answered OK for the first installation.

OpenGL and software modes

After installation two shortcuts will be found in the Start Menu: one for running in OpenGL mode, one for software mode. Certain video card drivers might cause problems in OpenGL mode, in which case the emulator must be run in software mode. The disadvantages of using software mode are that picture refresh rate is slower and some effects in the "Display/Configure..." window cannot be enabled, but software mode is compatible with all video card drivers.

Loading Enterprise programs into the emulator

There are several possible ways to load programs. Loading from tape is cute because it has the same tape sound as a real Enterprise machine. Thanks István for that!!

The easiest way to load a program is to use EPFileIO.rom, because no virtual cassette has to be edited and no floppy image has to be made. With a few clicks, programs can be loaded from the PC's hard drive.

EPFileIO.rom

This is a utility developed specifically for the emulator, to enable the emulator to access files directly from a directory in the PC. It works only if epfileio.rom is placed in segment 10 or higher. (This can be set in the Machine|Configure|Memory window). Also Enable virtual file I/O has to be turned on in the Machine|Configure|General window. The directory can be set in the Options menu Set working directory. For example, if the working directory contains a file named "bruce.com", you would load the Bruce Lee game from IS-BASIC by typing the command load "file:bruce.com". Games consisting of more files can also be loaded (except for games that use the default device to load). So EPFileIO.rom contains the FILE: device which enables the emulator to load files from the PC's hard drive. You can also save to the hard drive by referring to the FILE: device (if FILE: is the default device it doesn't have to be referred to).

For example in IS-BASIC:

100 print "Hello World!"
save "file:hello.bas"

The emulator loads files from the FILE: device (PC's hard drive) as default. Instead of FILE: device, a floppy disk drive also can be set as default by typing the command :def_dev_disk in the emulator's IS-BASIC. To set FILE: device as default again, type :def_dev_file.


Tips:

  • If the emulator happens to read only the first file of a program, type the :def_dev_file or :def_dev_disk command depending on your preferred device to load from.
  • If the emulator doesn't read files from the PC's hard drive, check that EPFileIO.rom has been placed in segment 10 or higher, and that Enable virtual file I/O has been turned on.
  • If epfileio.rom is placed in a higher numbered segment than EXDOS, then DISK: will always be default.

Tape

First of all some background information is needed. When the Enterprise loads from tape, it decodes the "twitter" recorded on the cassette. Thus if you want to use an emulated cassette tape player for the emulated Enterprise you will need to generate this "twitter" somehow, and the Tape Editor utility has been made for this purpose. If you want to load any program from tape to the emulated Enterprise, the Tape Editor utility must be used first. (For how to use it, see the next section). Using Tape Editor, a sound file can be generated in the same folder as any file stored in the PC, and this sound file can be selected in the emulator's Machine|Tape|Select image file menu. It is the same as placing a cassette into the tape recorder of a real Enterprise, but of course when using an emulator we must use a virtual cassette. You can edit a virtual cassette using the Tape Editor (see next section). Note that although Tape Editor saves virtual cassettes with the .tap extension, the structure of this .tap file is totally different from the one used by the EPTE or TAPir utilities. Nevertheless Tape Editor is able to load EPTE/TAPir .tap files, and they can be used directly in the emulator. So, to play a virtual cassette, you would use Machine|Tape|Select Image and browse the menu. Then press F9 to play the selected virtual cassette in the virtual tape recorder. Now a letter P will appear in front of the counter in the top right corner, to indicate that the virtual tape recorder is in playback mode. Why has the counter not started? Because the virtual tape recorder works by remote control like the real one, and it starts only if EP needs it. You can easily check it by pressing F4 in IS-BASIC, but it is better to press F1 and start loading. Now "twitter" can be heard. If the files are placed in order, loading will be finished within a few minutes and the game will run.

Tape Editor

This utility converts any files on your PC into sound files for EP128Emu to load from tape. These sound files will be now referred to as virtual cassettes. Put the files of your favourite game (we will use Alien 8 as example) into a separate directory. Run Tape Editor. On the left side a big black area will be seen, and on the right some buttons.

Click Import, browse the directory containing Alien 8 then pick the first file. Which is the first file? Tape file sequence means that files follow one another in the order that they are loaded so you must put the files in order (sequentially). The right sequence is generally easy to determine by reviewing the list of files (.com, .scr, .prg, .rom). In some cases however you will need several tries to find the right sequence. Fortunately file sequence is easy to modify in Tape Editor using the up and down arrows. When you modify the sequence the virtual cassette must be saved again. The file sequence for Alien 8 is: alien_8.com, alien.scr and alien.prg. The completed virtual cassette can be saved to the PC by clicking the Save button after picking the destination directory. It's practical to save them to the emulator's "tape" directory in order to load them easily.

Floppy disk and floppy image

In the Options/Disk/Configure menu you can pick the image file (.img). To use the floppy disk in drive A: of the PC, \\.\A: has to be written as the file name, and the tracks, heads and sectors should be set to -1 (this is the default setting which generally doesn't need changing).

Debugger

You can enter the debugger by selecting the Debug menu and clicking Start debugger. In the window above the debugger you can choose from two tabs: Page 1 and Page 2.

Page 1

CPU registers, Memory paging, Stack

Search, Memory dump

Values at memory addresses here can only be viewed. Modifying them is only possible under the Page 2 tab.

I/O registers

Disassembler

Page 2

Three windows can be seen here:

Monitor

In the upper left window, different commands can be typed. The available commands can be listed by typing ?. After ? the name of a command can also be entered (eg. ? l), to get more information about a certain command. If you want to modify the contents of a memory address, type the > character, then the memory address, then a space, and then the desired value. For example, if you want to put the value 0 in address 94b8, you should type: >94b8 0. Values here can be entered in binary, octal, decimal and hexadecimal formats, eg. %10101010, 252o, 170L, AA, and AAH are all 170.

Breakpoints

In the upper right window, breakpoints can be specified (causing the debugger window to appear on access to certain memory addresses or I/O addresses). For example, to set a breakpoint on write access to address db7a, you would type db7aw into this window. Any number of breakpoints can be specified, separated by space, tab, or newline characters. Comments start with the ; or # character, the rest of the line is ignored after these. You can only use hexadecimal addresses here, in the following formats (each N is a hexadecimal digit):

  • NN: I/O port address (in the case of CPC emulation, this is the upper 8 bits of the address)
  • NN-NN: a range of I/O port addresses (the end address is included)
  • NNNN: Z80 memory address
  • labelname: EQU 0000NNNNh: same as above, for compatibility with SjASM export (.exp) files
  • NNNN-NNNN: Z80 memory address range
  • NN:NNNN: physical address in segment:offset format (only the lower 14 bits of the offset are used, bits 14 and 15 are ignored)
  • NN:NNNN-NNNN: a range of physical addresses, which must be within a single segment (the range cannot cross 16K page boundaries)

It is also possible to append the following characters to the breakpoint definitions (without spaces, e.g. 1234x):

  • r: check for read accesses
  • w: check for write accesses
  • x: check for execute accesses (for memory breakpoints only); if none of these is specified, then the default is to check for any type of access (rwx, or rw for I/O ports)
  • pN: set priority (N is a number in the range 0 to 3); if the Priority threshold (0 to 4) is set to a value greater than this, then the breakpoint will be inactive - you can use this for quickly enabling or disabling groups of breakpoints. The default is p2.
  • i: this is only allowed for memory addresses, and cannot be combined with any of the previous access type or priority flags; breakpoints (including single stepping) will be ignored when the Z80 program counter (PC) points to an address at which an i (ignore) breakpoint has been set

Clicking the Apply button sets the list of breakpoints specified in the editor. This is done automatically at every change, but Lua scripts can also set, modify, or clear breakpoints (this is not reflected in the editor), sometimes making it necessary to use the Apply button after the script is stopped.

Lua script editor

Lua script can be written in the lower window. You can read about it in the README file and in the documentation for the Lua language. The editor supports the Ctrl+A (Select All), Ctrl+C (Copy), Ctrl+X (Cut), Ctrl+V (Paste), and Ctrl+Z (Undo) keyboard shortcuts, and the Insert key can be used to toggle insert/overwrite mode (actually, these keys also work in the monitor and breakpoint editor).

  • Load from file, Save to file: load or save the Lua script from/to a simple text (.txt) format file. You are recommended to edit large scripts with an external text editor.
  • Insert callback: inserts an empty breakPointCallback() function at the current cursor position.
  • Run: runs the script; if it contains a breakPointCallback() function, then that will be executed at every breakpoint or Step operation until the script is stopped or a runtime error occurs. The debugger window is not shown when this function returns false. Global variables defined by the script are preserved between running it and any later breakPointCallback() calls. The emulator waits for running the script or breakpoint callback to complete, meaning that an infinite loop in the script will freeze the emulator.
  • Stop: stops the script; this has an effect only if the script contains a breakPointCallback() function and is active.


From the debugger you can return to the emulation by pressing ESC or by clicking one of these buttons at the bottom of the debugger window:

  • Continue: continue emulation (the debugger window will not appear again until it is re-opened by the user or a breakpoint is triggered) - pressing the Esc key has similar effect (warning: repeatedly pressing Esc or holding it down continuously to close the debugger window many times quickly will sometimes quit the emulator as well)
  • Step: execute a single Z80 instruction, then return to the debugger (note: breakpoints are ignored in single step mode)
  • Step over: same as Step for most Z80 opcodes, with the exception of CALL, RST/EXOS, DJNZ, and conditional JP/JR, which will repeat the Step operation until the program counter (PC) is equal to the address of the next instruction, and only then show the debugger window again; note that this function does not currently support the conditional RET opcodes
  • Step into: similar to Step over, but the Step operation is repeated until the target address of the subroutine call or conditional jump is reached
  • Step to: this will Step until reaching the user specified address
  • Return: the target address for stepping is read from the top of the stack (i.e. it reads a 16-bit value from SP,SP+1, and then Step will be repeated until the program counter is equal to the return address that has been read)

Using ROM files

You can assign or remove ROM files to/from segments in the Machine/Configure/Memory page. EXOS can be used starting at segment "0", BASIC at segment 4, epfileio.rom at segment 10, and EXDOS at segment 20. Other extension ROMs (eg. ZozoTools) can be assigned to segment 10h, 20h or 30h or wherever there is enough space.

But the easiest way is to load configuration files created by the emulator's installer (File/Configuration/Load from ASCII file or Alt+Q) - they certainly work.