Specification Version: 2.1

Last Modification: 6-April-2007

Introduction

The CEF Utilities Specification defines helper classes, their semantics, and corresponding file formats for the Computer Emulation Framework. These utilities are provided to speed development of emulation and provide consistent behavior between them beyond that required by the CEF Core Specification. Note that this specification is build upon the CEF Core Specification. The implementation of this specification is contained within a single module with the following API:

integer Version()

This function returns a number indicating which version of the specification that this module implements, times 10. For instance, 16 indicates version 1.6.

TCEF_Watchpoint_Manager* Get_Watchpoint_Manager()

This creates a watchpoint manager and returns the instance to the caller.

TCEF_Character_Set* Get_Character_Set()

This creates a character set and returns the instance to the caller.

TCEF_Key_Mapper* Get_Key_Mapper()

This creates and returns a Key mapper object.

TCEF_Assembler_Context* Get_Assembler_Context()

This creates and returns an Assembler Context object.

TMaster_Assembler* Get_Master_Assembler( TComponent CPU, TUI_Interface UI )

This creates and returns a Master Assembler object. CPU is the default CPU to assemble code for, which may be NULL. UI is the user interface object, which may not be NULL.

Watchpoints

The TCEF_Watchpoint class implements a single address watchpoint. And contains the following methods.

int64 Get_Address()

Returns the address of the watchpoint.

integer Get_Access()

Returns the CEF access code for the watchpoint.

void Set_Access( integer Value )

Sets the access code for the watchpoint.

PChar Serialize()

Returns a string containing the watchpoint in XML.

void Deserialize( PChar Image )

Creates the watchpoint from a serialized XML string.

Watchpoint Manager

The TCEF_Watchpoint_Manager class manages a set of watchpoints. They consist of the following methods.

void Clear ;

Deletes all watchpoints managed by this object.

TUEC Clear_Watchpoint( int64 Address, integer Access )

Removes the watchpoint for the address with the access code(s).

TCEF_Watchpoint Create_Watchpoint( int64 Address, integer Access )

Creates a watchpoint for the specified address with the specified access code(s). The watchpoint is returned.

integer Count()

Returns the number of watchpoint addresses being managed.

void Deserialize( PChar Source )

Creates watchpoints from a serialized XML string.

PChar Serialize()

Returns a string containing all of the watchpoints in XML.

void Terminate()

Destroys the object.

TCEF_Watchpoint Watchpoint_At( int64 Address )

Returns a watchpoint for the specified address with all access codes for that address set.

Key Mapping

The TCEF_Key_Mapper class is used to manage key-to-action mappings for the host system. For instance, on a Microsoft Windows system the F1 key could be mapped to some functionality. Key names are case-insensitive, but the mapping string is stored and returned as-is. In summary, the class manages a list of key name strings, a list of valid mapping strings, and a set of strings that contain the current mapping for a given key.

This class consists of the following methods:

void Add_Key( PChar Name )

Adds a key name to the object.

void Add_Mapping( PChar Name )

Adds a valid mapping that the user can choose.

void Clear_Keys( boolean Mapping_Only )

Deletes all key names, and associated mapping text. If Mapping_Only is true, the keys are left but current mapping text is cleared.

void Clear_Mappings()

Deletes all valid mappings.

boolean Query()

Queries the user for key remapping. Returns True if the user Okayed his changes and false otherwise.

PChar Mapping( PChar Name )

Returns the text associated with the given key name. If the key is not defined, the function returns NULL.

void Set_Mapping( PChar Key, PChar Mapping )

Associates a mapping to a key. If the specified key is not defined, this does nothing.

void Terminate()

Destructs the object.

Character Sets

The TCEF_Character_Set class manages a set of characters for use on screen or terminal components. Up to 256 glyphs can be defined in a character set, with the first having an index of 0. If asked to render a glyph with an index greater than 127 and the correspoding glyph does not exist, the object will attempt to render the glyph with Index - 128. In the case of an index less than 128, nothing happens if the requested glyph doesn't exist. The maximum glyph width supported by this component is 32 pixels. The maximum height is 64 pixels. The component doesn't support differing glyph heights and the height of the glyphs in the character set is defined by the last defined glyph in the set. Attempts to load a character set file with differing glyph heights will result in unpredictable behavior. The glyphs in the set are assumed to contain blank scan lines for inter-line spacing.

This class consists of the following methods.

boolean Get_Invert()

Returns True if the object is set to render characters in inverted video.

void Set_Invert( boolean Value )

If Value is True, the object is set to render characters in inverted video.

void Clear()

Deletes all glyphs in the character set.

boolean Draw( Handle, X, Y, Index : integer )

Renders character glyph Index on the window specified by Handle, at position X, Y.

boolean Has_Glyph( integer Index )

Returns True if a glyph with the specified index is defined in the character set.

integer Height()

Returns the height of the glyphs in the set, in pixels (or scan lines).

void Initialize()

Initializes the object.

void Load( string Name ) ;

Loads a character set from the file specified in Name. This only supports CEF character files (*.c).

void Terminate()

Destructs the object.

integer Width( integer Index )

Returns the width of the specified glyph, in pixels.

CEF Character files

These files define monochrome raster glyphs for character sets. The default extension is "c". These files are text files with optional header lines. Each glyph definition is on its own line and each line is terminated with a CRLF (new line). The first glyph encountered is assigned to index 0, the next to index 1, and so forth. There is no limit as to the number of glyphs defined in the file, but some character set classes may have limits as to the number of glyphs that can be defined.

If present, the header file consists of two lines. The first is

RASTER

and the second is a number indicating the maximum width of glyphs, in pixels. In the absence of a header, the glyphs are assumed to be 8 pixels wide.

All lines following the header define glyphs. A blank line will define a blank glyph, otherwise the lines contain information defining the pixels that make up the glyph. A line may end with a comment. Comments begin with a semicolon (;). Everything from the semicolon to the end of the line are ignored by the software. Each scan line of the glyph is delimited by a comma in the file line. The scan line is a number whose 2's-complement bit layout defines the pixels that are set on that scan line of the glyph. The number is interpreted depending upon the prefix for the number, as follows:

Prefix	Meaning
0b	Rest of number is interpreted as binary.
0B	Same as 0b.
0x	Rest of number is interpreted as hexadecimal.
0X	Same as 0x.
0	Number is interpreted as octal.

Any other value is interpreted as a decimal numeric value.

Example lines defining glyphs with 11 scan lines:

0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 ; Space

0x00, 0x10, 0x10, 0x10, 0x10, 0x10, 0x00, 0x00, 0x10, 0x10, 0x00 ; ! (exclamation)