Emulator configuration
Xep128 is not a GUI oriented emulator. Its only GUI element is the window of the emulated Enterprise computer itself, except:
- OSD (On-Screen Display) is used to give feedback on important information
- Message boxes are used to note important or fatal conditions
- Also, some hot-keys can be used
Otherwise, any configuration possibility uses non-GUI solutions. Xep128 does the following steps to configure itself:
- It has a built-in config, Xep128 can run even without any pre-existing configuration file or such, if default ROM (ROM-set, combined.rom) can be loaded at least
- Then, Xep128 tries to load the default configuration file named @config (more about the '@' later). It can override the built-in configuration of course.
- Optionally, Xep128 ignores loading even the default configuration file if "-config none" command line switch is used (-config must be the first parameter)
- Optionally, Xep128 can be directed to use other configuration file instead of the default one with "-config path" option (-config must be the first parameter)
- Then, command line is parsed, given options overrides both of built-in and configuration file statements.
Both of command line and configuration file has two forms of option names. Some options are the simple ones, not having '@' in its name. These options can be specified only once, otherwise the last one will be used only!
Option names having '@' in its name are different ones. After the '@' mark, there is a two digit (even for eg 00, 0 won't work!) hexadecimal number. Here, of course, you can have more options if that number are different at least. Two important usage of this syntax is rom@xy (loads ROM image from segment XY, see later) and epkey@xy (defines keyboard mapping, see later).
Available options can be viewed with using the "-help", "-h" or "-?" option. Basic syntax of command line switches:
-optionName1 optionValue1 -optionName2 optionValue2 ...
Note, that even options seems to be "logical" having no parameter, command line parser expects that. For example "-fullscreen" does not mean too much, but "-fullscreen 1".
Configuration file uses the same options (with some exceptions, like "-config" does not have "config" variant in configuration file) as the command line, only the syntax is different:
optionName1 = optionValue1
optionName2 = optionValue2
Empty lines are ignored, hash mark (#) starts a comment, which is ignored by the parser.
Xep128 has its built-in ROM to accept various emulation related commands. If you are in IS-BASIC, you can type things like :XEP HELP. In EXDOS window, the ":" is not needed, thus it would be XEP HELP.
See later the summary at "Summary of options" which also mentions the :XEP commands. However there are some special commands important to note here:
-
:XEP HELPdisplays some version information about the emulator, and also the list of available commands -
:XEP EMUdisplays run-time information about the emulator, including the preferences directory -
:XEP EXITinstructs the emulator to ... guess ... exit :) -
:XEP CPUallows to query and set CPU type and clock in run-time
Note, that 80 column display is preferable, as printings are hard to be read on 40 column (default) screen. Use TEXT 80 BASIC command to switch into 80 column mode.
Xep128 has special interpretation of file names used with options:
- If file name seems to be an absolute path (that is: it begins with '/' in Linux, or '' in Windows, or having the syntax of 'X:' in Windows) Xep128 will use as-is, with the given path
- If file name starts with '@' the file is tried to be used from the preferences directory, so "@config" means file name "config" inside the preferences directory (no need for '' to separate)
- Otherwise, Xep128 tries various differnt paths to "guess" where the file is:
- It tries from the current directory (maybe it's hard to predict if you launch Xep128 from GUI, and not from a console window)
- It tries from the same directory, where the executable is
- It tries the "data directory" (Linux-only)
- It also tries the preferences directory
Note, that letting Xep128 to guess can be dangerous, if there are files with the same names in directories Xep128 searches. In this case, you can't be sure which one is used.
Thus, the advice: always use absolute file names, or the "@..." syntax for preference directory (even sub-directories can be used easily eg "@subdir/file" on Linux, or "@subdir\file" on Windows, it means a file in a sub-directory of the preferences directory, named "file").
Preferences directory is a platform dependent directory, its value can be known:
- In the emulator, type
:XEP EMU, 'pref path' will be the setting you are interested in - Xep128 also tells it at the first run, when it displays a dialog box about creation of sample configuration file
- In console window, use the
-hswitch to get help, and look for the lines near the beginning starting with "PATH: ", you need the "SDL pref path" value.
Xep128 at the first time (or any time, if it does not exist yet) writes a default configuration file "template" or "sample" into the preferences directory with the name of "config-sample", thus its name with the Xep128 file name notion is "@config-sample". It can be used to view available options, or you can even copy it, and customize, so you can use it with your own options. If you want Xep128 to load and use it, it should have the name of "@config" (that is, a file named config, in the preferences directory).
Sometimes, it's a good idea to delete this sample file, so Xep128 can re-create it. It can be useful in case of a new Xep128 version, so you can see new options, etc, as well.
| Commmand Line | Configuration file | :XEP command | Meaning, comments |
|---|---|---|---|
| -audio 1 | audio = 1 | :XEP AUDIO 1 | Enables sound emulation (0 disables it). |
| -config PATH | Use the given configuration file, "none" disables even the default "@config". Must be the first option if used! | ||
| -debug PATH | debug = PATH | Enables writing [["debug" file | |
| -fullscreen 1 | fullscreen = 1 | Starts Xep128 in full screen mode (0 disables it). You can toogle fullscreen/windowed mode by F11 (if key is not redefined) | |
| -mousemode 1 | mousemode = 1 | :XEP MOUSE 1 | Sets mouse emulation mode, 1-6 (1-3 = J-column 2,4,8 bytes protocol, 4-6 = same for K-column) |
| -primo PATH | primo = PATH | :XEP PRIMO PATH | Starts primo emulation if PATH is not "none". Not so much usable currently, PATH will be the (Primo) program to be loaded, it does only "boot" now ... |
| -printfile PATH | printfile = PATH | Sets the file name/path for printer emulation, bytes sent will be written here. | |
| -ram 512 | ram = 512 | :XEP RAM !512 | Sets amount of RAM (minimum: 64K, always decimal), continuously from downwards. |
| -ram @E0,E2-E3 | ram = @E0,E2-E3 | :XEP RAM !@E0,E2-E3 | Sets RAM segments "by hand" (always hex), even ranges (E0 and E2-E3 here) |
| check output | :XEP RAM | Displays the [[memory layout | |
| -rom@0C PATH | rom@0C = PATH | ROM image from "PATH" to segment (hex) 0C. :XEP cannot be used for this | |
| -sdimg PATH | sdimg = PATH | Sets SD card cartridge SD card image (VHD) path to be used | |
| -epkey@XY NAME | epkey@XY = NAME | Configure one key for EP / emulator. [[See here |
- all options in configuration file and command line needs a parameter, even "fullscreen" which can be thought that just mentioning it in command line is enough, but the parser expects a parameter
- -rom@XX options can be specified more times with different XX values for different segments, of course
- ROM images can be any size (which fits, course) even concatenated sets of ROMs, but must be at least 16K and size should be multiple of 16K (segment size)
- -ram option can be specified only once thus you must include all segments within one option
- -ram option has the ability to assign SRAM segment with '=' prefix, ie @E0,=E2,E8-EF where E2 is SRAM segment
- SRAM segments are loaded/saved by the emulator automatically, in the preferences directory with names sram-XX.seg for segment XX. Otherwise SRAM behaves like RAM.
- :XEP RAM statements are given with '!' this is a safety task, because runtime configuration causes rebooting of EP
- VRAM is always 64K and always defined even without mentioning in the @ syntax of "ram" option
