CEF32 For Emulator Developers

Last Modification: 10-January-2007

Introduction
============
CEF32 is an implementation of the Computer Emulation Framework (CEF) V1.6 for
Microsoft Windows 95 and later.  It is distributed with several default
components.  This will allow developers to rapidly develop emulators for
various CPUs, since CEF32 and the default components provide most of the
non-CPU framework required for an emulator.

This document describes the default components provided with CEF32 and also
defines how the CEF32 application adds features beyond the CEF specification.

CEF32 provides the TUI_Interface, TMaster_Clock, and TMaster_Assembler objects.
It also serves as a reference implementation of the specification.


CEF32 differences from the specification
========================================
CEF32 provides all of the features of the CEF specification, except as
described in this section.  Additional capabilities are also described here.

The memory display is limited to 2^63 addresses instead of 2^64.

Bases from 37 through 49, inclusive, are supported in addition to the CEF
standard 2 through 36.

CEF32 supports additional features in expressions.  The following additional
operators are available:

 !    Factorial (do a factorial of the previous value)
 %    Percentage (divide the previous value by 100)
 MOD  Division remainder only
 MIN  Return left side value if greater than the right side
      value, otherwise, return the right side value
 MAX  Return left side value if less than the right side value,
      otherwise, return the right side value

 SHR  Shift value right (value interpreted as a signed 2s complement integer)
 SHL  Shift value left (value interpreted as a signed 2s complement integer)
 AND  Bitwise and (value interpreted as a signed 2s complement integer)
 OR   Bitwise or (value interpreted as a signed 2s complement integer)
 XOR  Bitwise exclusive-or (value interpreted as a signed 2s complement integer)

 PI  is  a  predefined  constant  equal  to  3.14159265...

Functions have the form:

FUNCTION(expression)

where  expression  is  the  value  to  perform  the  function  on.
Available trigonometric functions are:

TAN   Tangent
SIN   Sine
COS   Cosine
SEC   Secant
COT   Cotangent
CSC   Cosecant

ARC and Hyperbolic functions are available by prefixing the trigonometric
function name with "ARC", "HYP", or "HYPARC" (eg ARCTAN and HYPARCSEC).  Other
functions available:

RAD   Degree to radian conversion
DEG   Radian to degree conversion
ABS   Absolute value
EXP   Constant E raised to the specified power
INT   Integer
LOG   Natural logrithm
LOG10 Common logrithm
SQR   Square root
SGN   Sign (returns -1 if negative, 1 if positive, or 0 if 0)
FIB   Fibonacci sequence


Command-line Options
====================
CEF32 can be started with a command line that automatically loads an emulator
(.cef) file.  Passing the emulator file, preceeded by a commercial at-sign (@),
causes CEF32 to load that file.  The file extension is not required if it is
".cef".  Example:

CEF32 @TRS80


CEF_Util.dll
============
This DLL implements the CEF Utilites Specification.  It is used by several of
the included components.


Supplied Standard Components
============================
The following components are provided with CEF32 for the benefit of emulator
developers.  Use of these components are not required, but can save
development time.

Altair.dll
----------
This is an emulator for the MITS Altair 8800 microcompuer.  It can also emulate
the IMSAI 8080.  It starts up with one serial port (port 0) and a front panel.


Null.dll
--------
This is a null component, which performs no functions but can be used as a
placeholder for other components.


Panel.dll
---------
This is an old-style "font panel", with LEDs for address and data lines.  It
queries connected components for available signals and shows those as well.
Startup commands:
ADDRESS n	Show n address lines.  The value is assumed to be hexadecimal
		unless it is terminated with a period (.) - indicating a
		decimal value.
DATA n		Show n data lines.  The value is assumed to be hexadecimal
		unless it is terminated with a period (.) - indicating a
		decimal value.
TITLE x		Change caption of panel to x.  If the text contains any spaces
		the entire text must be enclosed in quotes (").


GenScreen.dll
-------------
This provides a generic memory-mapped screen component.  It shows a specified
number of rows and columns mapped to a contiguous range of memory addresses.
Startup commands:
COLUMNS n	Number of columns.  The value is assumed to be hexadecimal
		unless it is terminated with a period (.) - indicating a
		decimal value.
ROWS n		Number of rows.  The value is assumed to be hexadecimal
		unless it is terminated with a period (.) - indicating a
		decimal value.
START n		Starting address of screen memory.  The value is assumed to be
		hexadecimal unless it is terminated with a period (.) -
		indicating a decimal value
TITLE x		Change caption of screen window to x.  If the text contains any
		spaces the entire text must be enclosed in quotes (").


S64K_RAM.dll
------------
This is a 64K static RAM memory component.  The valid maximum address range is
0 to 65535, inclusive.  This allocates a 64K buffer in memory and is, therefore,
much faster than the CEFMemory component.
Startup commands:
HIGH n		Sets the highest address responded to by the memory.  The value
		is assumed to be hexadecimal unless it is terminated with a
		period (.) - indicating a decimal value.
LOAD x		Loads the contents of memory from the specified filename (x).
		If the filename contains spaces, it must be enclosed in single
		(') or double (") quotes.  The loaded file is assumed to be a
		memory image which is loaded starting at the memory's low
		address.
LOW n		Sets the lowest address responded to by the memory.  The value
		is assumed to be hexadecimal unless it is terminated with a
		period (.) - indicating a decimal value.
ROM		Sets entire memory range to read-only.


CEFMemory.dll
-------------
This is a 64-bit-address memory.  It allocates used memory in 256 byte chunks
(with some overhead), so it uses only as much memory as is written to.  But it
is slower than the S64K_RAM component due to additional overhead.


CEFClock.dll
------------
This is an ultra-simple master clock component implementation.  It serves as a
means of keeping track of time (in terms of emulation) and as an example of a
clock component implementation.  However, it is unsuitable for more demanding
applications as it doesn't actually block any components.


Serial.dll
----------
This is a generic serial cable component implementation.  It maintains the
states and signals found in standard RS-232C serial cables.  It serves as an
interface between a non-cable component and a cable component.  The following
signals are supported by this component:

Name    Description
----    -----------
CD      Carrier detect
DSR     Data Set Ready
CTS     Clear To Send
RTS     Ready To Send
DTR     Data Terminal Ready
RI      Ring Indicator
BREAK   Break transmission


SIO.dll
-------
This emulates a S-100 bus MIT 88-SIO board.  It consists of two physical ports,
the first is the I/O status, and the second is the I/O latch.  The second port
is always the first port + 1.  The default ports are 0 and 1, but can be set to
any two contiguous ports.  Connect a cable component to the SIO component to
allow I/O.
Startup commands:

PORT n    Set ports to n (status) and n+1 (data).


SOL20.dll
---------
This is an emulator for the Processor Technology SOL-20 personal computer.  This
implements the keyboard, screen, screen RAM, and external interfaces.  Use the
sol20.cef file for setting up a complete SOL-20 emulation.


VDM1.dll
--------
This is a S-100 VDM-1 video and screen emulator.  Two fonts are supplied for
this component named 6574.c and 6575.c.
Startup commands:
CLEAR           Initializes display memory to spaces.
CONTROL         Display controls.  The default is to display controls.
CURSOR x        Sets the cursor mode to "x", where "x" is one of the following:
                    NONE    No cursor
                    BLINK   Blinking cursor
                    SOLID   Solid cursor
FONT x          Use character set "x", where "x" is 6574 (the default) or 6575.
INVERT          Sets the screen to inverted video.  The default is normal video.
PORT x          Sets the control port to address x (default is C8 hex).
NOCONTROL       Don't display controls.  The default is to display controls.
NORMAL          Sets the screen to normal video.
START n		Sets the lowest memory address mapped to the screen.  The value
		is assumed to be hexadecimal unless it is terminated with a
		period (.) - indicating a decimal value.
TEST            Fills the screen with a test pattern.
TITLE x         Sets the screen window caption to "x".
TOP n           Sets the top line counter to n.


VT05.dll
--------
This is a simple video terminal component.  It uses the VT05_KB keyboard, and
can emulate a "glass teletype", the DEC VT05 terminal, and the DEC VT50
terminal.  In addition, numerous individual parameters can be adjusted.  It
includes support for swappable keyboards and a printer port.
Startup commands:
8_BIT               Display 8-bit characters (otherwise trim high bit).
AUTO_COPY           Turn auto copy on.
BAUD x              Sets baud rate to x.  x may be "AUTO" for auto-baud rate.
COLUMNS x           Sets number of screen columns to x.  The total screen size
                    (rows times columns) must be no more than 32,768.
COLUMN x            Sets cursor position to x.
CONTROL x           Defines how control characters received by the terminal are
                    handled.  x is one of the following:
                        BLANK       Do not display control characters
                        IGNORE      Ignore control characters
                        NOBLANK     Display control characters
                        NOIGNORE    Do not ignore control characters
CURSOR x            Defines cursor mode.  x is one of the following:
                        NONE        No cursor is shown.
                        BLINK       Cursor blinks.  See RATE.
                        SOLID       Solid cursor.
DATA_BITS x         Sets the transmitted data bits to x.  Default is 8.
EMULATION x         Sets terminal emulation.  x is one of the following:
                        TTY         Component emulates a "glass teletype".
                        VT05        Component emulates a DEC VT05 terminal.
                        VT50        Component emulates a DEC VT50 terminal.
FLOW x              Defines the flow-control mechanism used on the serial
                    interface.  x can be one of the following:
                        NONE        No flow control (the default).
                        XOFF        Use XON/XOFF flow control.
                        CTS         Use CTS/RTS flow control.
FONT{/WINDOWS} x    Defines the character set.  x is the character set file to
                    load.  If /WINDOWS is specified, x is interpreted as a
                    Windows font name.
KEYBOARD x          Change keyboard to use the component specified as x.  Note
                    that the component name must include a complete path and
                    filename, including extension.  Also unhides the keyboard.
LOG{/APPEND} x      Log received data to file x.  If /APPEND is specified, the
                    file is appended to, otherwise it is overwritten if it
                    exists.
MAP k x             Maps Windows key k to text in x.  In addition to normal
                    ASCII characters, valid Windows key names are:
                        F1
                        F2
                        F3
                        F4
                        F5
                        F6
                        F7
                        F8
                        F9
                        F10
                        F11
                        F12
                        CANCEL
                        CLEAR
                        PAUSE
                        PAGE_UP
                        PAGE_DOWN
                        END_CB
                        PRINT
                        INSERT
                        SPACE
                        TAB
                        ESCAPE
                        CR
                        LF
                        RUB OUT
                        BREAK
MARGIN x            Set screen margin to x pixels.
MARGIN_BELL         Sound bell when cursor reaches end of row.
MIXEDCASE x         Defines uppercase conversions.  x is one of the following:
                        IN    Do not convert all in-coming characters to
                              uppercase.  This is the default.
                        OUT   Do not convert all out-going characters to
                              uppercase.  This is the default.
NO8_BIT             Trim high bit from displayed characters.  This is the
                    default.
NOAUTO_COPY         Turn auto copy off.  This is the default.
NOKEYBOARD          Hide keyboard.
NOMARGIN_BELL       Do not sound bell when cursor reaches end of row.  This is
                    the default.
NORMAL              Sets screen to normal (white on black).  This is the
                    default.
NOSCROLL            Do not scroll screen.
NOWRAP              Do not move cursor to next line when past end of line.
PPBAUD x            Sets printer port baud rate to x.  x may be "AUTO" for
                    auto-baud rate.
PPDATA_BITS x       Sets the transmitted data bits to x for the printer port.
                    Default is 8.
PPFLOW x            Defines the flow-control mechanism used on the printer port
                    interface.  x can be one of the following:
                        NONE        No flow control (the default).
                        XOFF        Use XON/XOFF flow control.
                        CTS         Use CTS/RTS flow control.
PPSTOP x            Sets the number of stop bits on the printer port interface
                    to x, where x is "1" or "2".
PRINTER x           Connect to a cable component, specified as x, to the printer
                    port.  Note that the component name must include a complete
                    path and filename, including extension.
RATE x              Set cursor blink rate to x milliseconds.
ROW x               Set cursor row to x.
ROWS x              Sets the number of screen rows to x.
SCROLL              Allow scrolling.  This is the default.
STOP x              Sets the number of stop bits on the serial interface to x,
                    where x is "1" or "2".
UPPERCASE x         Defines uppercase conversions.  x is one of the following:
                        IN    Convert all in-coming characters to uppercase.
                        OUT   Convert all out-going characters to uppercase.
WRAP                Move cursor to next line when past end of line.  This is the
                    default.


VT05_KB.dll
-----------
This is a keyboard component that uses a DEC VT05 keyboard layout.  The
keyboard supports the following special keys:

Name            Description
----            -----------
BREAK
CONTROL
DOWN            Down arrow.
EEOL
EEOS
LEFT            Left arrow.
RIGHT           Right arrow.
SHIFT
LOCK            Shift lock.
UP              Up arrow.


VT52_KB.dll
-----------
This is a keyboard component that uses a DEC VT52 keyboard layout.  The
keyboard supports the following special keys:

Name            Description
----            -----------
BREAK
LEFT            Left arrow
RIGHT           Right arrow
UP              Up arrow
DOWN            Down arrow
NKP_.           . on the numeric keypad
CONTROL
CAPS LOCK
LEFT_SHIFT      Left Shift
RIGHT_SHIFT     Right Shift
COPY
REPEAT
SCROLL
NKP_ENTER       Enter on the numeric keypad
NKP_0           0 on the numeric keypad
NKP_1           1 on the numeric keypad
NKP_2           2 on the numeric keypad
NKP_3           3 on the numeric keypad
NKP_4           4 on the numeric keypad
NKP_5           5 on the numeric keypad
NKP_6           6 on the numeric keypad
NKP_7           7 on the numeric keypad
NKP_8           8 on the numeric keypad
NKP_9           9 on the numeric keypad


VT100_KB.dll
------------
This is a keyboard component that uses a DEC VT100 keyboard layout.  The
keyboard supports the following special keys:

Name            Description
----            -----------
BREAK
CAPS LOCK
CONTROL
DOWN            Down arrow.
LEFT            Left arrow.
LEFT_SHIFT
PF1
PF2
PF3
PF4
RIGHT           Right arrow.
RIGHT_SHIFT
SET-UP
UP              Up arrow.


ASR33_KB.dll
------------
This is a keyboard component that uses an ASR-33 Teletype keyboard layout.  The
keyboard is uppercase-only and supports the following special keys:

Name
----           
BREAK
CONTROL
HERE IS
LEFT_SHIFT
REPT
RIGHT_SHIFT



LA120_KB.dll
------------
This is a keyboard component that uses a DEC LA120 (DecWrite III) keyboard
layout.  The keyboard supports the following special keys:

Name            Description
----            -----------
BREAK
CAPS LOCK
CONTROL
HERE IS
LEFT_SHIFT
LINE LOCAL
LOCAL LINE FEED
LOCAL FORM FEED
NKP_0           0 on the numeric keypad
NKP_1           1 on the numeric keypad
NKP_2           2 on the numeric keypad
NKP_3           3 on the numeric keypad
NKP_4           4 on the numeric keypad
NKP_5           5 on the numeric keypad
NKP_6           6 on the numeric keypad
NKP_7           7 on the numeric keypad
NKP_8           8 on the numeric keypad
NKP_9           9 on the numeric keypad
NKP_.           . on the numeric keypad
NKP_,           , on the numeric keypad
NKP_-           - on the numeric keypad
NKP_ENTER       Enter on the numeric keypad
PF1
PF2
PF3
PF4
RIGHT_SHIFT
SET-UP


The LA120 keyboard also supports the following LEDs:

Name
----
ALT CHAR SET
CTS
DSR
LED 3
LOCAL
ON LINE
PAPER OUT
SETUP


There is also a small alphanumeric display on the keyboard, which is accessed by
writing to the keyboard component's memory.  Memory address 0 is for the far-
right character of the display; address 1 is for the next-to-far-right
character; address 2 is for the next character to the left, and so on.  There is
room for roughly 4 characters on the display.



LK201_KB.dll
------------
This is a keyboard component that uses a DEC LK201 keyboard layout.  The
keyboard supports the following special keys:

Name                Description
----                -----------
COMPOSE CHARACTER
CONTROL
DO
DOWN                Down arrow
F1
F2
F3
F4
F5
F6
F7
F8
F9
F10
F11
F12
F13
F14
F17
F18
F19
F20
FIND
HELP
INSERT HERE
LEFT                Left arrow
LEFT_SHIFT
LOCK
NEXT SCREEN
NKP_0               0 on the numeric keypad
NKP_1               1 on the numeric keypad
NKP_2               2 on the numeric keypad
NKP_3               3 on the numeric keypad
NKP_4               4 on the numeric keypad
NKP_5               5 on the numeric keypad
NKP_6               6 on the numeric keypad
NKP_7               7 on the numeric keypad
NKP_8               8 on the numeric keypad
NKP_9               9 on the numeric keypad
NKP_.               . on the numeric keypad
NKP_,               , on the numeric keypad
NKP_-               - on the numeric keypad
NKP_ENTER           Enter on the numeric keypad
PF1
PF2
PF3
PF4
PREV SCREEN
RIGHT               Right arrow
RIGHT_SHIFT
REMOVE
SELECT
UP                  Up arrow


Apple_2_KB.dll
--------------
This is a keyboard component that uses an Apple II keyboard layout.  The
keyboard supports the following special keys:

Name
----
CONTROL
LEFT_SHIFT
REPT
RESET
RIGHT_SHIFT



SOL20_KB.dll
------------
This is a keyboard component that uses a PT SOL-20 keyboard layout.  The
keyboard supports the following special keys:

Name            Description
----            -----------
BREAK
CLEAR
CONTROL
DIVIDE          Arithmetic divide symbol
DOWN            Down arrow.
HOME CURSOR
LEFT            Left arrow.
LOAD
LOCAL
MODE SELECT
RIGHT           Right arrow.
SHIFT
SHIFT LOCK
UP              Up arrow.
UPPER CASE


The keyboard also supports the following LEDs:

Name            Description
----            -----------
LOCAL           On the LOCAL button.
LOCK            On the SHIFT LOCK button
UPPER           On the UPPER CASE button.


TRS80_1_KB.dll
--------------
This is a keyboard component that uses a TRS-80 Model I keyboard layout.  The
keyboard supports the following special keys:

Name            Description
----            -----------
BREAK
CLEAR
DOWN            Down arrow.
LEFT            Left arrow.
NKP_.           . on the numeric keypad.
NKP_ENTER       ENTER on the numeric keypad.
NKP_0           0 on the numeric keypad.
NKP_1           1 on the numeric keypad.
NKP_2           2 on the numeric keypad.
NKP_3           3 on the numeric keypad.
NKP_4           4 on the numeric keypad.
NKP_5           5 on the numeric keypad.
NKP_6           6 on the numeric keypad.
NKP_7           7 on the numeric keypad.
NKP_8           8 on the numeric keypad.
NKP_9           9 on the numeric keypad.
RIGHT           Right arrow.
SHIFT
UP              Up arrow.



PC108_KB.dll
------------
This is a 108-key keyboard component that uses a standard PC layout.  The
keyboard supports the following special keys:

Name            Description
----            -----------
BREAK
CAPS LOCK
DOWN            Down arrow.
END
F1
F2
F3
F4
F5
F6
F7
F8
F9
F10
F11
F12
HOME
INSERT
LEFT            Left arrow.
LEFT_ALT
LEFT_CONTROL
LEFT_SHIFT
LEFT_WINDOWS
NKP_0           0 on Numeric keypad
NKP_1           1 on Numeric keypad
NKP_2           2 on Numeric keypad
NKP_3           3 on Numeric keypad
NKP_4           4 on Numeric keypad
NKP_5           5 on Numeric keypad
NKP_6           6 on Numeric keypad
NKP_7           7 on Numeric keypad
NKP_8           8 on Numeric keypad
NKP_9           9 on Numeric keypad
NKP_ENTER       Enter on Numeric keypad
NKP_+           + on Numeric keypad
NKP_.           . on Numeric keypad
NKP_-           - on Numeric keypad
NKP_/           / on Numeric keypad
NKP_*           * on Numeric keypad
NUM LOCK
PAGE DOWN
PAGE UP
PAUSE
POPUP
POWER
PRINT SCREEN SYSRQ
RIGHT           Right arrow.
RIGHT_ALT
RIGHT_CONTROL
RIGHT_SHIFT
RIGHT_WINDOWS
SCROLL LOCK
SLEEP
UP              Up arrow.
WAKE UP


The keyboard also supports the following LEDs:

Name
----
NUM LOCK
CAPS LOCK
SCROLL LOCK


Z80.dll
-------
This is an 8-bit CPU component that emulates the Intel 8080 and 8085
microprocessors as well as the Zilog Z80 (the default emulation).  NOTE: This
component has not been rigorously tested but has run some 8080 programs
successfully.
Startup commands:
8080		Sets the component to Intel 8080 emulation.
8085		Sets the component to Intel 8085 emulation.
Z80 		Sets the component to Zilog Z80 emulation (the default).


Emulators
=========
The following emulator files provide complete machine emulation for various
systems:

Altair.cef
----------
A MITS Altair 8800/IMSAI 8080 emulator with front panel, 64K of RAM, 1 88-SIO
S-100 serial port (expandable to 127 serial ports), and 8080 CPU.  Contains a
port manager for easily adding/removing serial ports and connecting them to
cable components.


Sample Files
============
The following files are provided with CEF32 as examples.

TRS80.cef
---------
A sample emulator file.  It references non-existant files, but serves as an
example of an emulator file.


sol20.cef
---------
A sample emulator file for the Processor Technology SOL-20 computer.  It
references a non-existant ROM file, but appears to work if you provide a valid
ROM image.


Emulator Script Files
=====================
CEF32 can load CEF emulator definition files which automatically marshal the
appropriate components to emulate a specific machine.  These files have a
default extension of .cef.  See the included sample *.cef files for examples of
the format of these files.  In addition to the commands described in the CEF
specification, several others are added.  The following list is a comprehensive
and complete list.

The valid commands are:

Command        Description
-------        -----------
ASCII          Show text in memory display as ASCII.
BYTE           Show default data size to 1 byte.
CAPTION x      Set CEF caption to x.
CONNECT x y    Connect component named x to component named y.  Component y is
               connected to the output of x.  Both components must be loaded.
               If the names contain spaces, they should be enclosed in quotes.
DISCONNECT x y Disconnect component named x from component named y.  If the
               names contain spaces, they should be enclosed in quotes.
DOUBLE         Convert default data size to double long integer (8 bytes).
EBCDIC         Show text in memory display as EBCDIC.
HIDE           Hide the CEF application.
HIGH x         Set highest valid memory address to x.
IMMEDIATE x    Execute command x in immediate mode.  If x contains spaces, it
               must be enclosed in quotes.
LOAD x {y}     Load component from DLL named x.  Optionally a command line can
               be passed to the component as y.  If the command line contains
               spaces, it must be enclosed in quotes.  "/NAME=z" may be appended
               to the end of the line, where z is the name by which this
               component will be referenced.
LONG           Set default data size fo long integer (4 bytes).
LOW x          Set lowest valid memory address to x.
RADIX          Sets default base for numbers (2 through 49).
RUN            Starts execution of the (default) CPU.
SIGNED         Sets the default display of numbers to be signed.
UNLOAD_ALL     Removes all loaded components.
UNLOAD x       Removes component named x.  If x contains spaces, it must be
               enclosed in quotes.
UNSIGNED       Sets the default display of numbers to be unsigned.
WORD           Sets default data size to word (2 bytes).

