flexemu - an MC6809 emulator running FLEX
SYNOPSIS
On Unix like OS
flexemu [-i] [-h] [-f path] [-p path] [-c color] [-0 path] [-1 path] [-2 path] [-3 path] [-t] [-T (scroll|curses)] [-r <two_hex_digits>] [-V] [-u] [-j screen_factor] [-C startup_command] [-O cccc] [-L path]
On Windows
flexemu [-i] [-h] [-f path] [-p path] [-c color] [-0 path] [-1 path] [-2 path] [-3 path] [-V] [-u] [-j screen_factor] [-C startup_command] [-O cccc] [-L path]
DESCRIPTION
flexemu supports the following features:
- running on Unix like OS and Windows.
- using Qt framework as platform independent user interface
- Emulate
Eurocom II/V5 with digital cassette drives or
Eurocom II/V7 with floppy disk drives.
- supporting all MC6809 instructions incl. CWAI and SYNC
- CPU monitor with start/stop/step/next/reset, two breakpoints
- continuous display of CPU frequency, cycle count and disassembly.
- disassembler supports configurable label names.
- full interrupt support
- stop processor and pop up dialog at unimplemented processor instructions
- Optionally support
undocumented processor instructions
- Configurable frequency control to emulate with fixed, maximum possible
or original frequency
- mouse pointer support
- 512 x 256 pixel, 1, 3 or 6 bit plane
video graphics display with 2, 8 or
64 colors
- MC146818 real time clock
-
MMU for extension of the 64K address range
-
2 x 96 KByte RAM extension or
2 x 288 KByte RAM extension
- MC6850 serial line used for terminal I/O
- terminal only mode without graphical user interface (Unix like OS only)
- two different terminal types are supported.
- WD1793 floppy disk controller support with up to 4 disk drives
- support of DSK or FLX disk image files
- support of virtual disks based on a host directory
- MC6809 CPU emulation is running in a separate thread
for maximum performance
- 0% host CPU load during MC6809 CPU emulation is stopped
- 0% host CPU load during CWAI and SYNC Instruction
- minimum host CPU load if emulated CPU is running with original frequency
- On Unix like OS Signal SIGINT, SIGUSR1 and SIGUSR2 generate NMI,
IRQ or FIRQ
- Configurable CPU Instruction logging within address range
and/or Start/Stop trigger address, optional CPU register logging and
loop optimization.
- Support different monitor programs.
- dynamic mount/unmount of disks possible
- file conversion from/to FLEX ASCII file format
- ELTEC full screen editor e.cmd included
- command for exiting emulator
- command to dynamically mount/update/umount drives
- command to send a reset/irq/firq/nmi to CPU
- command to display processor frequency/cycle count
- command to switch between terminal and graphical mode
- command to format a disk
- HTML-documents with full description of FLEX API
OPTIONS
In general there are command line options and preferences editable in the flexemu
preferences dialog. Command line options supersede preferences and makes the
corresponding preferences together with its dependent preferences read-only.
Command line options on Unix like OS and Windows
- -f <hexfile>
-
Specifies the name of a program read during startup, usually a system
monitor. Intel Hex, Motorola S-record and FLEX binary file format is supported.
The default is
neumon54.hex
The file will be looked for in the working directory or in the directory
specified as -p option or as Disk/Monitor directory.
Flexemu can be used with other monitor programs as long as they support the
special hardware needs of the Eurocom II/V7.
- -c <color>
-
Specifies the foreground color. The default is
green. The background color is always black.
- -i
-
Inverse video display (foreground and background colors exchanged).
- -p <path>
-
Specifies a path in which disk image files or virtual disks (directory disks)
will be looked
for.
Defaults:
Windows: |
<INSTDIR>\data |
Unix like OS: |
/usr/share/flexemu |
- -0|1|2|3 <path>
-
Specifies a disk image file or a directory path for drive 0, 1, 2 or 3.
The default is
system.dsk
for drive 0. The file or directory will be looked for in the actual
directory. If nothing is found the directory specified with the
-p option used for Disk/Monitor files will be looked for.
- -j <screen_factor>
-
Specifies a factor to multiply the size of the flexemu video display. Default is 2.
Valid values are 1, 2, 3, 4 and 5. It depends on the host screen size where flexemu is executed which screen_factor is supported.
- -u
-
Enables the support of undocumented MC6809 Instructions. See Chapter
Undocumented Instructions
for details.
- -C <startup_command>
-
When starting flexemu a startup command can be specified. Multiple commands
can be separated by the FLEX end-of-line character, which by default is a colon.
The emulator will be exited when specifying exit as the last
command.
Example: "list 0.termcon.txt:dir 0:exit" will print the file
contents of 0.termcon.txt, make a directory listing of drive #0
and immediately exits the emulator. The startup command accepts a maximum of
128 characters.
- -m
-
Use
2 x 288 KByte RAM extension.
Only for Eurocom II/V7.
- -F <frequency>
-
Set frequency value in MHz. 0.0 runs CPU with maximum frequency. -1.0 runs CPU
with the original hardware frequency which is the default.
- -n <number_of_colors>
-
Number of shades or colors. Default is 2. Valid values are 2, 8 and 64.
- -O <cccc>
-
Support formatting disk in drive 0..3 (Overwrite format). This option enables
or disables the write track command on the floppy disk controller.
c represents drive 0..3 in this order. All drives have to be specified. Only
disk image files (not virtual disk images) support formatting a disk.
Supported values:
0 | Do not allow to format drive. |
1 | Allow to format drive. |
- | Keep drive unchanged. |
Only disk image files which do not have a valid file format are allowed to be formatted this way.
Example: -O 001-
Drive 2 allows format, drive 0 and 1 not, drive 3 is kept unchanged.
- -L <path>
-
Enable CPU instruction logging. File extension: *.log or *.txt logs to a text file; *.csv logs to a csv file.
- -h
-
Print a command line parameter description and exit.
- -V
-
Print version number and exit.
Command line options only on Unix like OS
- -t
-
Terminal only mode. All input/output is redirected to the terminal from
which flexemu is started.
Hint: Montior program neumnt54.hex is NOT needed for this any
more.
neumon54.hex can be used for both terminal and GUI mode.
- -T
-
Terminal type. There are two different terminal types available: scroll
and curses. See Terminal Preferences
for details.
- -r <two_hex_digits>
-
Define a reset key for terminal mode specified as two hex digits. The
default is
1E
, means Ctrl+^.
Flexemu Preferences
In flexemu menu Edit->Preferences opens the preferences dialog.
The following preferences can be modified.
Name |
Description |
Eurocom II |
Default |
V5 |
V7 |
Emulated Hardware |
Emulated hardware |
flexemu can either emulate an Eurocom II/V5 or Eurocom II/V7. |
|
|
Eurocom II/V7 |
CPU frequency |
The CPU frequency can be set to:
- The original frequency of the emulated hardware, which is 1.3396 MHz.
- To be emulated as fast as possible.
- Set to a static frequency in the range of 0.1 ... 10000 MHz.
|
✓ |
✓ |
Original frequency |
MC146818 Realtime Clock |
Optionally emulate a
MC146818 real time clock,
which is a hardware extension.
|
- |
✓ |
Emulate realtime clock |
User Interface |
Screen size |
The screen size can be set to default, double, triple, quadruple or
quintuple size.
|
✓ |
✓ |
Double size (1024x512 pixel) |
Number of shades or colors |
Depending on the available RAM extension 2, 8 or 64 shades can be supported.
Only if a RAM extension is selected, 8 or 64 shades are available.
|
2/8/64 ✓/-/- |
2/8/64 ✓/✓/✓ |
2 |
Monochromatic color |
A monochromatic color like green or orange can be selected.
|
✓ |
✓ |
green |
Multi color scheme |
Displaying multiple colors (not only shades of a monochromatic color).
Only if 8 or 64 shades are selected.
|
- |
✓ |
off |
Display Inverse |
Display video normal or inverse. |
- |
✓ |
off |
Display Smooth |
When enabled the video screen is display with a smooth effect. When
disabled the video screen displays pixels. |
✓ |
✓ |
off |
Memory |
RAM extension |
|
✓ - - |
✓ ✓ ✓ |
2 x 96 KByte |
Files and Directories |
Disk/Monitor directory |
A Directory Path containing FLEX disk images and monitor program. |
✓ |
✓ |
Windows: <INSTDIR>\data
Unix like OS: /usr/share/flexemu |
Monitor program |
A Filename or Directory Path for the monitor program. |
✓ |
✓ |
neumon54.hex |
Disk Drive 0 |
A filename or directory Path for disk drive 0. |
- |
✓ |
system.dsk |
Disk Drive 1 |
A filename or directory path for disk drive 1. |
- |
✓ |
Not set |
Disk Drive 2 |
A filename or directory path for disk drive 2. |
- |
✓ |
Not set |
Disk Drive 3 |
A filename or directory path for disk drive 3. |
- |
✓ |
Not set |
Cassette Drive 0 |
A filename for cassette drive 0. |
✓ |
- |
system.mdcr |
Cassette Drive 1 |
A filename for cassette drive 1. |
✓ |
- |
Not set |
Virtual Disk |
Active |
Enable or disable support of
directory disks, also called virtual
disks. |
- |
✓ |
on |
Default Format |
Choose the default format used when first time using a directory disk.
It is stored in the directory in the file .flexdiskrc |
- |
✓ |
80 tracks, 36 sectors |
Tracks |
When choosing "[Set Tracks and Sectors]" as default format the number of tracks can be set individually. |
- |
✓ |
80 |
Sectors |
When choosing "[Set Tracks and Sectors]" as default format the number of sectors can be set individually. |
- |
✓ |
36 |
Terminal (Unix like OS only) |
Terminal Type |
If terminal only mode is active, there are
different terminal types available:
- Simple Scrolling Terminal: Any input or output is simply
redirected to the controlling terminal. It's scrolling can be used
to see the input and output history. It is also possible to redirect
the output stream into a file using Unix builtin output redirection
support. This example creates a log-file of the whole flexemu session:
flexemu -t -T scroll | tee inout.log
The escape sequences of the controlling terminal can be used (which
obviously creates a dependency between the executed flexemu command and
the controlling terminal).
- Enhanced Terminal Emulation: This terminal type provides
an enhanced terminal emulation exactly as provided by the monitor program
neumon54.hex with 25 lines and 84 columns.
All control characters and escape sequences are emulated (except for
CTRL-], ESC A, ESC F and ESC G).
This terminal type is useful for example for screen editors like
CEDRIC or DynaStar
which depend on specific escape sequences. This terminal emulation is
based on the
ncurses library.
This example starts flexemu in this terminal mode without visible user
interface:
flexemu -t -T curses
On the FLEX prompt it is also possible to switch between graphical user
interface and terminal mode.
See corresponding EMU commands
for details.
|
✓ |
✓ |
Simple Scrolling Terminal |
Ignore output of NUL (0x00) characters |
In terminal only mode the output of NUL characters can be ignored.
Their initial
usage to wait until the teleprinter returns to the first printing position
is not needed any more. There are terminals which incorrectly display it as
a space. For details see:
Wikipedia Null character. Some terminals also use NUL characters in
escape sequences.
|
✓ |
✓ |
on |
Ignore output of ESC (0x1B) characters |
Using simple scrolling terminal type the output of ESC characters can be
ignored. This option
has to be switched off, to send escape sequences to the terminal. When doing
this it is recommended to change TTYESC
to a different character than ESC using
TTYSET DOS Utility.
This can avoid the terminal to stick in an escape sequence.
|
✓ |
✓ |
on |
Expert Preferences |
Undocumented instructions |
Optionally emulate MC6809 with
undocumented instructions.
|
✓ |
✓ |
off |
More flexible MMU |
Optionally emulate a
more flexible MMU. Only if
2 x 288 KByte RAM extension is
selected.
|
- |
✓ |
off |
Enable formatting disk in drive 0 |
This option enables or disables the write track command on the floppy
disk controller for drive 0.
|
[1] |
|
- |
✓ |
off |
Enable formatting disk in drive 1 |
This option enables or disables the write track command on the floppy
disk controller for drive 1.
|
[1] |
|
- |
✓ |
off |
Enable formatting disk in drive 2 |
This option enables or disables the write track command on the floppy
disk controller for drive 2.
|
[1] |
|
- |
✓ |
off |
Enable formatting disk in drive 3 |
This option enables or disables the write track command on the floppy
disk controller for drive 3.
|
[1] |
|
- |
✓ |
off |
Use file time |
This is a flexemu extension to the FLEX filesystem. If enabled a
directory entry also contains the hour and minute of the file creation.
This feature is only partially implemented. FLEX does not yet support it.
|
- |
✓ |
off |
[1] When this option is enabled a floppy disk can be formatted from within the
emulator. Only disk image files (not virtual disk images) support formatting a
disk. When this option is on, the corresponding disk image file can be an empty
or non existent file. NEWDISK.CMD distributed on system.dsk for example can be
used to format a disk.
Breakpoint support
With the menu CPU->Breakpoints up to two breakpoints
can be set. They have to be input as a one to four digit hexadecimal
address. Execution automatically stops when the PC register contains one
of the breakpoint addresses.
MC6809 Disassembler
flexemu has an integrated disassembler. It displays the currently to be
executed instruction. Configuring the
CPU Instruction Logging
allows to log all executed instructions.
Addresses having a special meaning in the FLEX Operating System can be
displayed as label instead of the hex-address. These labels are defined in
the file
flexlabl.conf. On Unix like OS the file get's installed in path
/etc/flexlabl.conf. On Windows it is located in the installation
directory.
CPU Instruction Logging
With the menu CPU->Logging the logging of each executed CPU
instruction can be enabled. The Instruction Logging Dialog contains
the following entry fields. Addresses have to be input as a one to
four digit hexadecimal address:
Fieldname |
Default value |
Description |
Enable logging |
off |
Enable or disable logging. |
Min Address |
0000 |
Only log instructions on an address higher or equal to this address. |
Max Address |
FFFF |
Only log instructions on an address lower or equal to this address. |
Start Address |
<not set> |
Start Instruction logging when the value of the PC
is equal to the Start Address.
|
Stop Address |
<not set> |
Stop Instruction logging when the value of the PC is equal to the Stop
Address.
|
Log cycle count |
off |
Log the number of cycles the CPU executed since the last reset.
|
Log register values |
all off |
Log a combination of CPU register values. The PC address is always logged.
Register values are logged before executing the instruction on the current
PC address.
|
Loop optimization |
off |
Loop optimization detects repeated instruction sequences and prints them
using an optimized syntax. Within a loop no cycle count or register
contents are logged. The first loop execution is always logged outside
the loop to still see the cycle count and register contents when entering
the loop. All following loop executions are surrounded by a "DO" and
"REPEAT" pseudo instruction. "REPEAT" is followed by the number of
repetitions. Source code analysis has shown that this saves a tremendous
amount of logging file capacity while providing the exact same information.
[2]
|
Format |
Text |
The format of the logging file can be selected.
- Text: Logs into a text based format. The data is arranged in columns separated by one or multiple spaces.
- CSV Text: Logs into a text based format. The first line is a column header. The data is arranged in columns separated by a selectable separater character.
|
CSV Separator |
Semicolon |
Only enabled if log format is CSV Text. The separator character can be selected. [1]
- Semicolon (hex
3B )
- Space (hex
20 )
TAB (hex 09 )
|
Filename |
<not set> |
Filename to be used for the instruction logging. Independant of the Start
and Stop Address this file remains open as long as Flexemu keeps running
until another Filename is set or logging is disabled.
|
[1] Comma is not available as separator character because it is used to separate operands in the MC6809 assembler syntax.
[2] Loop optimization example with displaying loop register A contents:
0100 |
LDA |
#6 |
A=XX |
0102 |
DECA |
|
A=06 |
0103 |
BNE |
$0102 |
A=05 |
|
DO |
|
|
0102 |
DECA |
|
|
0103 |
BNE |
$0102 |
|
|
REPEAT |
#5 |
|
0105 |
CLRB |
|
A=00 |
CPU Frequency control
With the toggle menu item "CPU->Original Frequency" 1.3396 MHz the CPU
frequency can be switched between the maximum possible frequency
(depending on the available host CPU performance) and the original
CPU frequency which exactly is 1.3396 MHz. With the command
emu freq
other frequencies can be specified. See
FLEX Utilities for details.
KEYBOARD
Eurocom PAT09 keyboard
The preferred keyboard for the Eurocom II/V7 was the PAT09 keyboard:
PAT09 can emit the whole ASCII character set (hex code 00
..
7F
) together with some additional keys codes
(hex code > 7F
). flexemu emulates almost all keys available on
PAT09 as discribed in the following chapters. Eurocom II/V5 strips off the
most significant bit from the keyboard input with the concequence of only
supporting the ASCII character set.
Hotkeys
The following table summarizes the hotkeys available in flexemu.
Hotkey |
Description |
Ctrl+Shift+Q |
Exit application |
Ctrl+1 |
Set default screen size |
Ctrl+2 |
Set double screen size |
Ctrl+3 |
Set triple screen size |
Ctrl+4 |
Set quadruple screen size |
Ctrl+5 |
Set quintuple screen size |
Ctrl+F12 |
Toggle smooth display |
Pause |
Toggle CPU to stop or run |
Shift+Pause |
Send non maskable interrupt (NMI) to CPU |
Shift+Alt+Pause |
Reset and run CPU |
There is also a hotkey for toggling full screen and window mode. It depends on
the user interface.
User Interface |
Hotkeys |
Windows |
F11 or Alt+Enter |
macOS |
Ctrl+Meta+F |
KDE |
F11 or Ctrl+Shift+F |
GNOME |
Ctrl+F11 |
Others |
F11 |
Function keys
All PAT09 function keys F1 up to F19 are emulated as
defined in the following table:
PAT09 key |
Mapped key |
Emitted hex code |
F1 |
F1 |
C0 |
F2 |
F2 |
C1 |
F3 |
F3 |
C2 |
F4 |
F4 |
C3 |
F5 |
F5 |
C4 |
F6 |
F6 |
C5 |
F7 |
F7 |
C6 |
F8 |
F8 |
C7 |
F9 |
F9 |
C8 |
F10 |
F10 |
C9 |
F11 |
Shift+F1 |
CA |
F12 |
Shift+F2 |
CB |
F13 |
Shift+F3 |
CC |
F14 |
Shift+F4 |
CD |
F15 |
Shift+F5 |
CE |
F16 |
Shift+F6 |
CF |
F17 |
Shift+F7 |
D0 |
F18 |
Shift+F8 |
D1 |
F19 |
Shift+F9 |
D2 |
ASCII control characters
All ASCII control characters with hex code 00
up to
1F
and 7F
can be entered with flexemu:
key combination |
Control character |
hex code |
Ctrl+@ or Ctrl+`
[1]
|
NUL |
00 |
Ctrl+A ... Ctrl+Z |
SOH ... SUB |
01 ... 1A |
ESC or Ctrl+[ or Ctrl+{
[1]
|
ESC |
1B |
Ctrl+\ or Ctrl+|
[1]
|
FS |
1C |
Ctrl+] or Ctrl+}
[1]
|
GS |
1D |
Ctrl+^ or Ctrl+~
[1]
|
RS |
1E |
Ctrl+_ or Ctrl+Delete
[1]
|
US |
1F |
Delete
[2]
|
DEL |
7F |
[1] Depending on the keyboard layout evtl. also Alt Gr has to be pressed.
[2] Works only for the Delete key located on the main keypad.
Numeric Keypad and Cursor Control
On a standarized keyboard a separate numeric keypad can be used for both
entering numbers (Num Lock is switched on) or cursor control
characters (Num Lock is switched off).
The Eurocom II
PAT09 keyboard has both a separate cursor control keypad and numeric keypad:
On flexemu both keypads are emulated using the numeric keypad:
If Num Lock is switched on all keys of the PAT09 numeric keypad
are emulated one by one. Depending on the current locale setting the decimal
point character can be a comma or period. flexemu
always maps this to a period because it is not locale aware.
If Num Lock is switched off the cursor control keys of the PAT09
keyboard are mapped to a standardized keyboard on the numeric keypad.
The following hex codes can be generated.
PAT09 key |
Mapped key |
Emitted hex code |
<key> |
Shift+<key> |
Ctrl+<key> |
Shift+Ctrl+<key> |
 |
Pos1 |
F1 |
E1 |
B1 |
A1 |
 |
↓ |
F2 |
E2 |
B2 |
A2 |
 |
Page Down |
F3 |
E3 |
B3 |
A3 |
 |
← |
F4 |
E4 |
B4 |
A4 |
 |
Clear |
F5 |
E5 |
B5 |
A5 |
 |
→ |
F6 |
E6 |
B6 |
A6 |
 |
Page Up |
F7 |
E7 |
B7 |
A7 |
 |
↑ |
F8 |
E8 |
B8 |
A8 |
 |
End |
F9 |
E9 |
B9 |
A9 |
 |
Insert
[1]
|
FA |
EA |
FA |
EA |
 |
Delete
[2]
|
91 |
81 |
91 |
81 |
[1] The Insert key located on the main keypad does not emit
any hex code.
[2] The Delete key located on the main keypad emits hex code
7F
,
Ctrl+Delete key emits key code 1F
.
MONITOR PROGRAM
The monitor program provides basic I/O functions to the operating system.
It is comparable to the BIOS on a PC.
But in addition it provides a simple command line interface to display or
change memory contents or display, set or clear breakpoints. or boot FLEX
operating system. From within FLEX the monitor program can be entered by
entering MON on the FLEX prompt.
flexemu is deployed with the following monitor programs:
Monitor program |
Eurocom II |
RAM Extension |
Boot disk |
Comment |
Version |
File |
V5 |
V7 |
None |
2 x 96 KByte |
2 x 288 KByte |
V5.4 spec |
neumon54.hex |
- |
✓ |
✓ |
✓ |
✓ |
system.dsk, system54.dsk |
|
V5.3 |
mon53.s19 |
- |
✓ |
✓ |
- |
- |
system54.dsk |
|
V5.4 |
mon54.s19 |
- |
✓ |
- |
✓ |
- |
system54.dsk |
|
U5.4 |
monu54-6.s19 |
- |
✓ |
- |
✓ |
✓ |
system54.dsk |
Boot FLEX by entering D |
V2.4 |
mon24.s19 |
✓ |
- |
✓ |
- |
- |
|
|
V2.4 |
mon24z.s19 |
✓ |
- |
✓ |
- |
- |
|
|
SEE ALSO
Documents on the behalf of the FLEX User Group
Other Documents
BUGS
If a drive can not be logged in no error message will be displayed.
If a directory will be logged in as a drive and it has too much files or its
filesize all together is too large no error message will be displayed and
as much files as possible will be managed.
emu commands (See
FLEX Utilities for details)
only have poor error messages.