flexemu - an MC6809 emulator running FLEX

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

OPTIONS

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 384 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

[1] When this option is enabled a floppy disk can be formatted from within the emulator. Only *.FLX disk image files (not *.DSK or virtual disk images) support formatting a disk. When this option is on, the corresponding disk image file can be an empty file. NEWDISK.CMD distributed on system.dsk for example can be used to format a disk. When trying to read or write such an empty, unformatted disk the floppy disk controller responds with error bit "record not found". After successfully formatting it with NEWDISK.CMD it is detected as FLEX formatted disk, read or write is possible. In general as disk can be formatted with other disk formats like CP/M or MS/DOS.

All flexemu settings are stored in a file on Unix like OS or in the Windows Registry. The detailed location is

Breakpoint support

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 a system wide flexemu label file flexlabl.conf. It's location depends on the operating system.

Windows:	<INSTDIR>\flexlabl.conf
Unix like OS:	/etc/flexlabl.conf

On Unix like OS the path depends on the sysconfdir directory. Before compiling flexemu this path can be adapted (see ./configure --help).

A user specific flexemu label file can be defined by creating the file (for example by copying it from the system wide configuration file):

$HOME/.config/flexemu/flexlabl.conf

The user specific configuration file has precedence over the system wide configuration file.

CPU Instruction Logging

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

Memory Window

The Memory Window displays and updates the memory content for a given address range. When the CPU is running the display gets updated once a second and is indicated by the red LED on the right end of the status bar. When the CPU is stopped it is possible to change memory contents for memory type RAM. The cursor control automatically positions on memory values only. The current address, its value and the memory type is displayed in the right corner of the status bar. Any changes are taken over immediately by pressing a key. Up to 24 Memory Windows can be opened at the same time.

The contents of a Memory Window can be controlled by the following properties:

Flexemu configuration file

Property	Default value	Description
Window Title	%START-%END	The window title. It can contain variables which are replaced. [1] %START: Is replaced by the 4-digit start address in hex %END: Is replaced by the 4-digit end address in hex
Start Address	C100	The start address of the memory range to be displayed. [2][3]
End Address	C6FF	The end address of the memory range to be displayed. [2][3]
Style	16 bytes per line	The display style to be used. Dynamic: Diplay a multiple of 8 bytes depending on the window width 4 bytes per line: Diplay 4 bytes per line 8 bytes per line: Diplay 8 bytes per line 16 bytes per line: Diplay 16 bytes per line 32 bytes per line: Diplay 32 bytes per line 64 bytes per line: Diplay 64 bytes per line
Display Address	Yes	Display the address on the left of each row.
Display ASCII	Yes	Display the ASCII content on the right of each row. [4]
Extra space each 8th byte	No	Insert an extra space every 8 bytes.
Automatic update window size	Yes	When changing the style the window size gets updated automatically.

Menu	Description
Search->Find	Start to find an ASCII string, a regular expression string or one or multiple HEX bytes. The search starts at the current cursor position until end of data, continues at start of data until current cursor position minus one. [1] To guarantee consistent data the menu only is enabled if CPU is stopped.
Search->Find Next	Continue to find next after starting find with Search->Find. To guarantee consistent data the menu only is enabled if CPU is stopped.

On Unix like OS the path depends on the sysconfdir directory. Before compiling flexemu this path can be adapted (see ./configure --help).

A user specific flexemu configuration file can be defined by creating the file (for example by copying it from the system wide configuration file):

The user specific configuration file has precedence over the system wide configuration file.

KEYBOARD

Eurocom 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

Function keys

ASCII control characters

Numeric Keypad and Cursor Control

MONITOR PROGRAM

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.

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

User Interface	Hotkeys
Windows	`F11` or `Alt`+`Enter`
macOS	`Ctrl`+`Meta`+`F`
KDE	`F11` or `Ctrl`+`Shift`+`F`
GNOME	`Ctrl`+`F11`
Others	`F11`

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`

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`

PAT09 key	Mapped key	Emitted hex code
PAT09 key	Mapped key	`<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`