Difference between revisions of "EP128Emu manual"

From Enterprise Wiki
Jump to: navigation, search
m (Windows: have -> has)
(Page 2)
Line 115: Line 115:
 
Three windows can be seen here:
 
Three windows can be seen here:
  
* Into the left-upper window, different commands can be typed. List of commands available can be listed by '''?'''. After '''?''' the name of a command can also be given (eg. '''? l''') thus more information can be read about a certain command. If you want to modify the content of a memory address, type '''>''' character, then the memory address desired, the a space, then the value desired. If you want to set eg. 0 to address 94b8, you should type: '''>94b8 0'''.
+
===Monitor===
 +
Into the left-upper window, different commands can be typed. List of commands available can be listed by '''?'''. After '''?''' the name of a command can also be given (eg. '''? l''') thus more information can be read about a certain command. If you want to modify the content of a memory address, type '''>''' character, then the memory address desired, the a space, then the value desired. If you want to set eg. 0 to address 94b8, you should type: '''>94b8 0'''.
 
Values here can be given in both binary, octogonal, decimal and hexadecimal numeral systems, eg.  '''%10101010''', '''252o''', '''170L''', '''AA''', and '''AAH''' are all 170.
 
Values here can be given in both binary, octogonal, decimal and hexadecimal numeral systems, eg.  '''%10101010''', '''252o''', '''170L''', '''AA''', and '''AAH''' are all 170.
* In the right-upper window, '''breakpoint/watchpoint''' can be given (obtaining certain memory addresses or I/O addresses the debugger window will appear). If you want to set a breakpoint to the writing of eg. ''db7a'' address, ''db7aw'' should be typed here.
+
 
* Into the lower window Lua script can be written. You can read about it in the [http://ep128emu.cvs.sourceforge.net/viewvc/*checkout*/ep128emu/ep128emu2/README README] file and in the [http://www.lua.org/manual/5.1/ documentation] of Lua language.
+
===Breakpoints===
 +
In the right-upper window, '''breakpoints/watchpoints''' can be given (on access to certain memory addresses or I/O addresses the debugger window will appear). If you want to set a breakpoint to the writing of eg. ''db7a'' address, ''db7aw'' should be typed here. Any number of breakpoint definitions can be specified, separated by space, tab, or newline characters. 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
 +
* '''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 on 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''': watch read accesses
 +
* '''w''': watch write accesses
 +
* '''x''': watch 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===
 +
Into the lower window Lua script can be written. You can read about it in the [http://ep128emu.cvs.sourceforge.net/viewvc/*checkout*/ep128emu/ep128emu2/README README] file and in the [http://www.lua.org/manual/5.1/ documentation] of Lua language.
  
 
From the debugger you can return to the emulation by pressing ''ESC'' or by clicking the ''Continue'' button below.
 
From the debugger you can return to the emulation by pressing ''ESC'' or by clicking the ''Continue'' button below.

Revision as of 21:13, 20 October 2010

Introduction

Actually EP128Emu is the most accurate Enterprise emulator for PC, provided with the most options as it might seem complicated to use for beginners. This manual has been made for them. We hope that after reading this manual anybody will be able to use this lovely emulator. Alternative is the EP32 being also a great emulator, with less options though but ideal for beginners because of its easy usability. Recent version of EP128Emu is 2.0.8.1. This is the rewritten version in C++ of the earlier EP128Emu v1.x.x written in C, with much more options to be set, with a better built-in debugger and with a more accurate emualtion. EP128Emu is the work of István Varga.

Installation

Windows

Installing the emulator Source code and Download old ROMs don't need to be ticked for novice users.

Source code is needed only for developping the emulator, old ROMs are needed 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.

Possessing ROM files you can also untick Download ROM images however it is recommended to download the ROM package because of the eventual upgrades. ROMs are stored in the \Program Files\ep128emu2\roms directory. Individual ROMs to be used should be put here. While installing the emulator the next ROMs are downloaded from the net:

  • asmon15.rom
  • basic20.rom
  • basic21.rom
  • brd.rom (German extension: BRD, UK, VLOAD, VSAVE, VDUMP)
  • cyrus.rom (Cyrus Chess II)
  • epd19hft.rom (EPDOS 1.9 beta / Hungarian)
  • epd19uk.rom (EPDOS 1.9 beta / English)
  • epdos_z.rom (EPDOS 1.7Z)
  • epfileio.rom
  • ep-plus.rom (Enterprise Plus BASIC extension, "a" Studio)
  • esp.rom (Spanish extension: ESP, UK, VLOAD, VSAVE, VDUMP)
  • exdos10.rom
  • exdos13isdos10esp.rom (EXDOS 1.3 Spanish + IS-DOS 1.0)
  • exdos13isdos10hun.rom (EXDOS 1.3 Hungarian + IS-DOS 1.0)
  • exdos13.rom
  • exos20.rom
  • exos21.rom
  • exos22.rom
  • exos231esp.rom (EXOS 2.31 Spanish)
  • exos231hun.rom (EXOS 2.31 Hungarian)
  • exos231uk.rom (EXOS 2.31 English)
  • exos23.rom
  • fenas12.rom
  • forth.rom (IS-FORTH 1.0)
  • genmon.rom (HiSoft GEN assembler + MON monitor 1.1)
  • heass10hfont.rom (HEASS 1.0 for Hungarian character set)
  • heass10uk.rom (HEASS 1.0 English)
  • heassekn.rom (HEASS 1.0 Hungarian, without accents)
  • hun.rom (Hungarian extension: HUN, UK, VLOAD, VSAVE, VDUMP)
  • ide.rom
  • iview.rom (IVIEW 0.4, CVIEW 0.42c, IPLAY 1.04, SNDPLAY 0.99, UNCOMPRESS 1.02, DTM; see: Iview manual)
  • lisp.rom (IS-LISP 0.6)
  • pascal11.rom (HiSoft Pascal 1.1)
  • pasians.rom (PASZIANSZ, KASZINO (HSoft))
  • tpt.rom (Enterprise Turbo Pack Tape 1.1, HSoft)
  • zt18ekn.rom (ZozoTools 1.8 Hungarian, without accents)
  • zt18hfnt.rom (ZozoTools 1.8 for Hungarian character set)
  • zt18hun.rom (ZozoTools 1.8 Hungarian)
  • zt18uk.rom (ZozoTools 1.8 English)
  • zx41.rom

Most of them are familiar for those who already used Enterprise but there are a number of new ROMs due to the developers' team being active even in the early years of the 21st century. EPFileIO.rom is not used for real Enterprise machines, it only makes it easier to load files into the emulator - see below how.

Having Hungarian PC keyboard Use Hungarian keyboard map has to be ticked otherwise you won't be able to use the keyboard properly. Reinstall ep128emu configuration files? question must be answered OK at 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. It's needed because certain video card drivers might cause problems in OpenGL mode. In this case the emulator must be run in software mode. Though using software mode picture refresh rate is slower and some effects in the "Display/Configure..." window cannot be enabled, software mode is compatible with all the video card drivers.

Loading Enterprise programs into the emulator

We have more possibilities to load programs. Loading from tape is cute because it has the same tape sound as real Enterprise machines. Thanks István for that!!

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

EPFileIO.rom

This is an extension made straight for the emulator which enables the emulator to access files directly from a directory in the PC. It works only if epfileio.rom is placed on segment 10 (or higher) (It can be set in Machine|Configure|Memory window) and Enable virtual file I/O also has to be turned on in the Machine|Configure|General window. The directory can be set in the Options menu Set working directory. If e.g. a "bruce.com" file can be found here, you 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 the 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 also can save to the hard drive referring to the FILE: device (if FILE: is the default device it doesn't have to be referred to). E.g. 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 floppy disk drive also can be set as default by typing the command :def_dev_disk in IS-BASIC of the emulator. To set FILE: device as default again, type :def_dev_file command.


Tips:

  • If the emulator happens to read only the first file of a program, type :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 the EPFileIO.rom being attached to a segment (number 10 or higher) and the Enable virtual file I/O being turned on.
  • If the epfileio.rom is attached to a segment of higher number than the EXDOS, DISK: will always be default.

Tape

First of all some background information is needed. When Enterprise loads from tape, it decodes the "twitter" recorded to the cassette. Thus if you want to use an emulated cassette tape player for the emulated Enterprise you will need this "twitter" somehow. Tape Editor utility has been made for this purpose. If you want to load any program from tape to the emulated Enterprise, Tape Editor utility has to be used first. (About how to use it see in a later document) Using Tape Editor a sound file can be generated in the base of any file stored in the PC. This sound file can be picked 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. Using an emulator we can speak about a virtual cassette only. You can edit a virtual cassette like this, using the Tape Editor. Note that Tape Editor however saves virtual cassettes with .tap extension, the structure of this .tap file is totally different from the one used by EPTE or TAPir utilities. In turn, Tape Editor is able to load EPTE/TAPir .tap files, they can be used in the emulator at once. Thus having such a virtual cassette, select Machine|Tape|Select Image menu and browse it. Then, press F9 to play your virtual cassette placed in the virtual tape recorder. Now a P letter will appear in front of the counter in the right-top corner which indicates that playing has been started. Why has the counter not started? Because the virtual tape recorder works with remote control like the real one thus it starts only if EP needs it. You can easily check it by pressing F4 in IS-BASIC but it rather worths pressing F1 to start loading. Now "twitter" can be heard. If the files are placed in order, loading will be finished within some minutes and the game will run.

Tape Editor

This utility converts from any files on your PC into sound files that EP128Emu needs to load from tape. These sound files will be now referred to as virtual cassette. Put the files of your favourite game (now we will show Alien 8 as example) into a separate directory. Run Tape Editor. In the left a big black area will be seen, in 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 also have to put the files in order (sequentially). The right sequence is generally easy to invent reviewing the list of files (.com, .scr, .prg, .rom). In some cases however you will give more tries to find out the right sequence. Fortunately file sequence is easy to modify in Tape Editor using the up and down arrows. Modifying the sequence the virtual cassette has to be saved again. The file sequence of Alien 8 is: alien_8.com, alien.scr and alien.prg. The ready virtual cassette can be saved to the PC by clicking Save button after picking the destination directory. It's practitcal to save them to the emulator's "tape" directory in order to load them with ease.

Floppy disk and floppy image

In 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 file name and tracks, heads, sectors should be set -1 (it's also the default setting which generally doesn't need changing).

Debugger

You can enter debugger selecting Debug menu and clicking Start debugger. In the window above 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 looked at. Modifying them is only possible under the Page 2 tab.

I/O registers

Disassembler

Page 2

Three windows can be seen here:

Monitor

Into the left-upper window, different commands can be typed. List of commands available can be listed by ?. After ? the name of a command can also be given (eg. ? l) thus more information can be read about a certain command. If you want to modify the content of a memory address, type > character, then the memory address desired, the a space, then the value desired. If you want to set eg. 0 to address 94b8, you should type: >94b8 0. Values here can be given in both binary, octogonal, decimal and hexadecimal numeral systems, eg. %10101010, 252o, 170L, AA, and AAH are all 170.

Breakpoints

In the right-upper window, breakpoints/watchpoints can be given (on access to certain memory addresses or I/O addresses the debugger window will appear). If you want to set a breakpoint to the writing of eg. db7a address, db7aw should be typed here. Any number of breakpoint definitions can be specified, separated by space, tab, or newline characters. 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
  • 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 on 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: watch read accesses
  • w: watch write accesses
  • x: watch 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

Into the lower window Lua script can be written. You can read about it in the README file and in the documentation of Lua language.

From the debugger you can return to the emulation by pressing ESC or by clicking the Continue button below.

Using ROM files

You can attach or remove ROM files to the segments in the Machine/Configure/Memory page. EXOS can be used starting at the segment "0", BASIC at the segment 4, epfileio.rom at the segment 10, EXDOS at the segment 20. Other extension ROMs (eg. ZozoTools) are supposed to attach to segment 10h, 20h or 30h or where's actually room.

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