CEF CORE SPECIFICATION

Specification Version: 2.2

Last Modification: 1-November-2007

Note

This specification is not backward-compatible with specification versions earlier than 2.0.

Overview

CEF is the framework specification, allowing mixing and matching of components in CEF applications. A CEF application is an application which uses one or more CEF components (usually a CPU component at least), and may use some generic components.

Components

A CEF component is a software analogy to the hardware components of a computer, such as the CPU, memory, IO devices, and buses. A CEF component serves up a standard interface that allows the various devices to be connected in either a dynamic or static way (or some combination thereof). The CEF application marshalls the various components, initializing instances of them and connecting the instances to each other to configure an emulated computer environment. Components are described in greater detail in the section titled "Components".

There are two relationships that components have with each other: connections and ownership. A connection indicates an emulated connection between two components through which data is transferred, but implies no hierarchy or ownership. An ownership relationship indicates that one component "owns" another. An owner component (hereinafter referred to as the parent component) creates its owned component (hereinafter referred to as the child component), terminates it, and manages connections to it. For instance, a bus and a memory component are connected, but a motherboard owns a CPU.

Data transfer size

All data transfers between components are byte-aligned. This refers to the actual CEF architecture and has no effect on the emulation. A component which implements a word size not exactly equal to a multiple of 8 bits will transfer data using the number of bytes necessary to contain all of the bits, with the extra bits being unused and undefined. For instance, a CPU with a word size of 36 bits would transfer data in 5-byte quantities with the uppermost 4 bits of the last byte ignored. From an emulation standpoint, the transfer is 36 bits, but the actual implementation code uses bytes for consistency.

Address Space

Address Space is a concept that is supported by CEF, but not required. The idea is that a component may support several address "spaces", each of which can be accessed via a 64-bit integer value. Space 0 is the default. All other address spaces are optional and defined by the component. For instance, a CPU may support both a Code segment and a Data segment - each with the same range of addresses. Both segments represent different address spaces. This is used in breakpoints, profiling, and other cases where it is necessary to distinguish between the different spaces.

Signals and States

Signals are inputs and outputs that are unique to a specific component implementation. For instance, an Interrupt signal on a CPU. Signals for a component have a textual name, an integer index, a state (true for High, false for Low), and an indication of whether or not the signal is active low. When signals change, a notice is sent to the UI, which passes it on to any component which has requested to be notified of signal changes.

States are flags indicating the internal state of a component. States have textual names, an integer index, and a state (true or false). Like Signals, State changes are only reported to the UI. Unlike Signals, State changes are not passed to other components by the UI. Examples of states are "Fetch", "Handling Interrupt", and "Priority".

Typical configuration

All applications must have a TUI_Interface object, an optional Master clock object, a memory component, and a CPU component, as a minimum. The CPU and memory are connected together in this simplest of configurations.

For more detailed simulation, a bus component may exist between the CPU and memory objects. Or, a motherboard object may be used in place of a CPU object (in which case, it marshalls its own CPU - and other - components).

For multi-processor systems, several instances of a CPU object may be created. However, in order for simulation of multi-processing to work, the master clock object MUST be used and the CPU objects must block themselves appropriately.

Stacks

Stacks are a common, though optional, aspect of computers. Most computers support stacks in hardware. In the "standard model", the stack is stored in the main memory with other data. A CPU has a means of pointing into this stack area of memory via a "stack pointer". CEF supports the concept of multiple stack spaces, though most computer's support only one hardware stack. The TCEF_Stack_Interface class is used to access stacks which do not follow the standard model. For instance, a CPU may have a fixed-size internal stack. An instance of this class can be obtained from the TCPU object via the Get_Stack_Interface method.

TCEF_Stack_Interface has the following methods:

void Terminate()

This method destructs the object instance.

int64 Low_Bound()

This function returns the lowest valid stack entry index.

int64 High_Bound()

This function returns the highest valid stack entry index.

int Item_Size()

This function returns the size of each stack entry, in bits.

int64 Value( int64 Index )

This function returns the value of the Indexth item on the stack.

Master Clock

The Master Clock is used to simulate hardware timing issues. In many cases, this is not needed for adequate emulation. When not needed, the master clock instance can simply return the same Time_Index at all times, and immediately Wake a component upon a Block request. In any case, components should block themselves when starting (or completing) an operation that takes a known amount of time. For instance, when a CPU executes an instruction, it should block for the amount of time that the instruction should take. Blocking is accomplished by calling the master clock's Block method. The component should cease doing any further (time-related) processing until it is woken.

TMaster_Clock has the following methods:

void Block( TComponent*, int64 Time_Delta )

This procedure registers a request for a component to receive a Wake signal at the specified time delta (in picoseconds).

TDebug_Interface* Debugger()

This method returns an instance of a debug interface for the clock. If the clock component doesn't support debugging, the method returns NULL.

void Initialize( TUI_Interface* )

Initializes the clock to time index 0 and sets the UI interface.

int64 Get_Time_Index()

This function returns the current simulated master clock (which is measured in picoseconds) time index.

integer Serial_Number()

Returns the value passed at creation time (see Make_Instance).

boolean Support_Feature( integer ID )

Returns True if the clock supports the specified feature. This is reserved for future use.

integer Version()

Returns the version of the CEF specification that the object adheres to. This is the major.minor version times 10. For instance, a value of 20 indicates version 2.0.

UI Interface

The application must supply all components with a UI interface. This UI interface is the TUI_Interface class. It is used to communicate asynchronous events and communications back to the application and, in certain cases, between different components.

TUI_Interface consists of the following methods:

void Block( TComponent* Component, boolean Blocked )

This method is called whenever a component blocks (Blocked is true) or unblocks (Blocked is false). Component is the component in question.

boolean Breakpoint_Notice( int64 Address, boolean Physical, integer Space, TComponent* CPU )

This method is called when a CPU triggers a breakpoint. The method returns True if the CPU is to continue execution of the instruction or False if not. CPU is the CPU component which triggered the breakpoint, Address is the execution address, and Physical indicates whether the address is physical or virtual. Space indicates the address space for the breakpoint.

TMaster_Clock* Clock()

This function returns the instance of the Master clock object for the application. NULL is a valid return value and should be tested by any code calling this program (indicating that there is no master clock and timing issues are to be ignored).

TDebug_Interface* Debugger()

Returns a pointer to a debug interface for the UI Interface object. If debugging into the UI Interface is not supported, this returns NULL.

TCOM_Stream* Get_File_Stream( string Name )

Returns a stream for the passed (partial or full) filename. If the file cannot be opened/accessed, NULL is returned.

void Hide( bool Value )

Sets the UI visible state to Value. That is if Value is true, the UI is made visible. If Value is false, the UI is hidden.

void Idle( TComponent* Component )

Called by Attention: blocked component (such as a CPU in wait state).

void Log_Error( TComponent* Component, string Text, integer Severity )

This logs an actual program error (exception or warning) from the specified component. Severity is one of the following values:

0 = Informational message

1 = Warning

2 = Non-fatal error

3 = Fatal error. The application should shut down.

void Log_Simulated_Error( TComponent* Component, string Text, integer Severity )

This logs a simulated hardware error from the specified component. Severity is one of the following values:

0 = Informational message

1 = Warning

2 = Non-fatal error

3 = Fatal simulated hardware failure.

void Log_Status( string Text, integer Index )

A component calls this method in response to a Show_Status request. Each call provides one line of status information. Index is 0 for the first line, 1 for the second, etc.

void Log_Trace( TComponent* Component, string Description )

Logs a trace event for the specified component.

void Signal_Change_Notice( TComponent* Component, integer Index, bool Active )

Called when a component changes a signal state. Index is the state index. Active is true if the new state of the signal is active.

void Signal_Exception( TComponent* Component, string Description, integer Index )

Called when a component suffers some form of exceptional condition in emulation that doesn't qualify as a hardware failure (which is reported via Log_Simulated_Error). Note that CPUS that support exception handling must report these exceptions via State_Change_Notice.

For instance, assume that a CPU encountered an invalid instruction. If the CPU handles this condition in a special manner (such as an "exception"), this would result in a state change, which is reported via State_Change_Notice. However, if the result of the CPU operation in this case is undefined, it should report the condition via this method and then continue on as the actual hardware would.

void State_Change_Notice( TComponent* Component, integer Index, bool Active )

Called when a state change occurs for the specified component. Index is the signal's index. Active is true if the state is true.

void Terminate

Destroys the component, which may terminate the application.

void Toggle_Embed( TComponent* Component )

Called when the specified visual component, via user action, requests a change to its embedded state. An embedded component may be stand- alone or embedded within the application (such as in a tabbed window). The UI may ignore this request.

integer Version()

Returns the version of the CEF specification that the UI adheres to. This is the major.minor version times 10. For instance, a value of 20 indicates version 2.0.

void Want_Signals( TComponent* Component, bool Value )

Notifies that UI that the specified component wants (Value true) or does not want (Value false) to receive Signal change notifications.

void Watchpoint_Notice( int64 Address, integer Access, integer Tag, TComponent* Component )

This method is called when a component triggers a watchpoint. Address is the address that triggered the watchpoint. Access indicates the type of access:

2 = Read (input)

3 = Write (output)

Tag is dependent upon the component and Component is the component which triggered the watchpoint.

The following methods are supported in components conforming to version 2.1, or later, of the specification.

String Get_Port_Name( int Index )

Returns the name of the port with the specified index, across all loaded components. If Index is invalid, NULL is returned. These ports are provided primarily by system emulators to allow users to select where to connect other components (such as printers and terminals).

String Get_Port_Description( integer Index )

Returns the description of the port with the specified index, across all loaded components. If Index is invalid, NULL is returned. These ports are provided primarily by system emulators to allow users to select where to connect other components (such as printers and terminals).

TComponent* Get_Port( integer Index )

Returns the cable-end for the port with the specified index, across all loaded components. If Index is invalid, NULL is returned. This component is the object to which to connect another component. These ports are provided primarily by system emulators to allow users to select where to connect other components (such as printers and terminals).

TComponent* Get_Port_Connection( integer Index )

Returns the component currently connected to the port with the specified index, across all loaded components. If Index is invalid, NULL is returned. If no component is connected to the port, NULL is returned. These ports are provided primarily by system emulators to allow users to select where to connect other components (such as printers and terminals).

TComponent* Port_Parent_Component( integer Index )

Returns the component that provides the port with the specified index, across all loaded components. If Index is invalid, NULL is returned. If no component is connected to the port, NULL is returned. These ports are provided primarily by system emulators to allow users to select where to connect other components (such as printers and terminals).

The following TUI_Interface methods are new with V2.2 of the specification:

Void Run( boolean State )

If State is true, the loaded CPUs begin/continue execution. If State if False, the loaded CPUs are paused.

The following TUI_Interface methods are new with V2.2 of the specification:

integer Process_ID( string Name, boolean Force )

Obtain a process ID for a parallel process. Returns -1 if no (more) parallel processes are allowed (or not supported). If Force is True, an ID is always returns (unless not supported, in which case -1 is returned).

boolean Process_Start( integer ID, integer& Priority )

Indicates that the specified process ID is about to start running. False is returned if parallel processing is disabled. Priority is ignored on call. On return, it is the priority that the process should run at. This value is 0 to indicate default (or normal) priority. Greater than 0 means elevated priority and less than 0 means lowered priority. Anything outside the range of -32767 to 32767, inclusive, should be ignored. Within the range of 1 to 32767 (or -1 to -32767), the entire possible range of the system running the emulator is mapped on this range. For instance, if the system supports 2 levels of priority above and below normal, then the priority value should be shifted 15 bits to the right and that value maps onto -2, -1, 0, 1, or 2.

void Process_End( integer ID )

Indicates that the specified process ID is not running.

void Process_Deleted( integer ID )

Indicates that the specified process has been destructed.

Streaming interface

A stream is a collection of data that is accessed as an array of bytes. Some components may be able to save and/or restore their current states and/or contents. Also, assemblers may take a stream interface to a file in certain circumstances. The mechanism used to access a stream is the TCOM_Stream class. The methods in this class are:

TUEC Initialize()

Initializes the stream object.

TUEC Terminate()

Frees the stream object. No other method of object destruction may be used on the object. After this call, the instance is no longer valid. Note that Attach and Detach should be used as the means of object destruction.

void Attach()

Increments the reference count to the object.

void Detach()

Decrements the reference count to the object. If the reference count goes to zero, the object is destructed.

integer Interface_Version()

Returns the version of the interface to which the object conforms.

integer Facility_ID()

Returns facility ID for this streamer (see UEH).

integer Facility_Version()

Returns the version of the facility.

TDebug_Interface* Debugger()

Returns a debugging interface to the object. Returns NULL if not supported.

void* Extension()

Returns an extended interface. For now, this always returns NULL.

boolean At_End()

Returns True if there is no more data in the stream to read.

void Last_Error( TUEC& UEC )

Returns the last error code, and clears the error code.

TUEC Read( pointer Buffer, integer &Size )

Reads the specified number of bytes from the stream. Size is modified to be the actual bytes transferred. The read starts at the current position. After the read, the current position will be one byte past the end of the read data.

TUEC Read_Line( pointer Buffer, integer &Size )

Reads one line of input, up to the size of the buffer. The line is assumed to end at an ASCII 13 code. The ASCII 13 code is not included in the returned data. Size is modified to be the actual bytes transferred.

void Seek( integer Position )

Positions to the specified byte offset within the stream. The next read or write operation will start from this position.

integer Size()

Returns the size of the stream data, in bytes. -1 is returned if the size is unknown or larger than 2,147,483,647 bytes.

TUEC Write( pointer Buffer, integer size )

Writes the specified buffer, of the specified size in bytes, to the stream. The write operation starts at the current position and sets the current position to the byte immediately after the last written byte.

TUEC Write_Line( pointer Buffer )

Writes the specified null-terminated text to the stream. An ASCII code 13 is appended to the text on output.

Component interface

All component providers (eg DLLs) provide three API functions. The API definition is:

Integer Facility_Code()

This function returns a UEH facility code for the component class provided by Make_Instance.

pointer Make_Instance( integer Serial_Number, TUI_Interface* UI )

Make_Instance is responsible for creating an instance of the component and associating the UI Interface with the component. This instance is an object which is a descendant of the TComponent class. Serial_Number is a numeric value which is accessible via the Tcomponent's Serial_Number method. This can be used for any purpose desired and need not be unique.

integer Version()

Returns the version of the CEF specification that the API adheres to. This is the major.minor version times 10. For instance, a value of 20 indicates version 2.0.

Components

All components are instances of TComponent. The TComponent class defines the features common to all components and consists of the methods described in this section. Features that are unique to certain kinds of components (such as CPUs or memories), are accessed via another class whose methods handle those features. TComponent provides instances of these classes where appropriate. For instance, the CPU method provides a TCPU object for this component. However, if the component is not a CPU, this method would return a NULL. Note that it is possible for a component to provide a User_Interface object as well as one of the others. The methods specific to certain classes are:

Cable

CPU

Keyboard

Memory

User_Interface

TUEC Initialize( TUI_Interface* )

Reinitializes the component. Note that this is not a constructor! It is not necessary for the application to call this method, since Make_Instance should have initialized the component appropriately. This simply allows the component to be initialized again.

TUEC Terminate()

Terminates the component. Note that this is not a destructor, although it should eventually cause the instance to be destructed. By convention, once this method is called, the instance is no longer valid.

integer Serial_Number()

This method returns the number passed during creation (see Make_Instance).

TUEC Add_Notification( TComponent* Component )

Adds the specified component to the list of components to notify along with Parent in Child_Notifications.

TCable Cable()

Returns the TCable interface for a cable component. If the component is not a cable, this method returns NULL.

TComponent* Child_Component( integer Index )

This method returns the Indexth child component for this component. It returns NULL if Index is outside of the range: 0 <= n < Max_child_component. Child components are components owned by this component (such as a motherboard would own the CPU component).

void Child_Notification( TComponent* Child, longint &Notice, int64 &params )

This is called by a component's child components to notify the parent asynchronously of some change. The usage of the params parameter depends upon the notice code. It is ignored unless otherwise specified. The Notice codes are:

0 = Child is about to terminate. As soon as the call returns, the child component will destruct.

1 = Child is requesting termination. If the Notice parameter is unchanged when the call returns, the child will go ahead and terminate. If Notice is set to 0 on return, the child will not terminate. Typically termination is cancelled when the parent component wishes to terminate the child itself.

2 = Child has received asynchronous data.

TUEC Clear_Watchpoint( int64 Address, boolean Memory, integer Access )

Clears a watchpoint at the specified address. Access is the type of access:

1 = Read or write (input or output)

2 = Read (input)

3 = Write (output)

integer Component_Type()

This method returns a value indicating the type of the component, as follows:

0 = Unknown (TComponent)

1 = CPU

2 = Bus

3 = Memory

4 = Motherboard

5 = I/O device

6 = User Interface

7 = Cable

8 = Keyboard

TUEC Connect_Input( TComponent* Component )

For components which accept input, this connects another component to this component's default input port.

TUEC Connect_Output( TComponent* Component )

For components which generate output, this connnects another component to this component's default output port.

TCPU* CPU()

Returns an instance of a TCPU object for this component. If the component is not a CPU, this method returns NULL. This is a reference to an object managed by this component and should not be freed or destructed by calling code.

TDebug_Interface* Debugger()

Returns a pointer to a debugger interface for this component. If the component doesn't support a debugger interface, this method returns NULL.

TUEC Delete_Notification( TComponent* Component )

This removes the specified component from the list of components to be notified. The component must have been added via Add_Notification.

TUEC Deposit( int64 Address, integer Size, pointer Buffer, boolean Memory )

This method writes Size bits of data from the specified address from the specified buffer. Memory is True if this is a memory write versus a I/O write. This is solely for the UI, and the write does no trigger watchpoints or have any other side-effects other than changing the contents of the component.

TUEC Disconnect_Input( TComponent* Component )

This disconnects the specified component from this component's default input port.

TUEC Disconnect_Output( TComponent* Component )

This disconnects the specified component from this component's default output port.

TUEC Examine( int64 Address, integer &Size, pointer Buffer, boolean Memory )

This method reads Size bits of data from the specified address into the specified buffer. Size is updated with the actual number of bits copied. Memory is True if this is a memory read versus an I/O read. This is solely for the UI - the read triggers no watchpoints and must have no other side-effects. In the case where an actual read would result in a change to a component's state, the examine must not make that change and the returned data should reflect what would be returned if a Read were done. Finally, access modes are ignored since this operation must always succeed if the address is valid.

integer Get_Access_Mode( int64 Address, boolean Memory )

Returns the access mode of the specified address. Return values are:

0 = Not supported (address out of range, etc.)

1 = Read/Write (I/O)

2 = Read-only (input-only)

3 = Write-only (write-only)

Memory is true if address is a memory address and false if it is an I/O address. See Set_Access_Mode for more details.

string Get_Exception_Description( integer Index )

Returns a description of the exception with the given index. If the index is invalid, the function returns NULL.

TComponent* Get_Parent()

Returns the parent component of this component. Returns NULL if there is no parent.

boolean Get_Profiling

Returns True if profiling for this component is on.

integer Get_Read_Latency()

Returns the component's default read latency. If the component doesn't support latency, this should return 0.

boolean Get_Signal( string Name, boolean& state )

Returns the state of a signal with the specified name. If the component recognizes the signal name, it returns True. Otherwise it returns False. If the result is True, state is set to the current state of the signal.

string Get_State_Name( integer index )

Returns the name of the state with the specified index. If the index is invalid, the function returns NULL.

integer Get_Tag()

Returns the component's tag value. See Set_Tag for details.

boolean Get_Trace()

Returns True if the component has tracing turned on.

integer Get_Write_Latency()

Returns the component's default write latency. If the component doesn't support latency, this should return 0.

TComponent* Input_Component( integer Index )

This method returns the Indexth input component for this component. It returns NULL if Index is outside of the range: 0 <= n < Max_input_component

TKeyboard* Keyboard()

Returns the TKeyboard interface for a keyboard component. If the component is not a keyboard, this method returns NULL.

TMemory Memory()

Returns the TMemory interface for a memory component. If the component is not memory, this method returns NULL.

string Name()

This method returns a string containing the name of this component.

TComponent* Output_Component( integer Index )

This method returns the Indexth output component for this component. It returns NULL if Index is outside of the range: 0 <= n < Max_output_component

TProfiler* Profiler()

Returns a profiler interface for the component. Profilers are described in another section.

boolean Read( int64 Address, integer Size, integer IO_Type )

Calling this method requests the component to transmit data to its default output port. Size is the number of bits being requested (0=default for component). The component should verify that the address is within its range before responding. If not, it should do nothing. If the component will respond to the request, the method returns true, otherwise it returns false. For CPUs, this reads the internal CPU memory cache. If the CPU doesn't have an internal memory cache, it should return False. IO_Type indicates the type of read operation:

0 = Memory read

1 = Port input
2 = Read current data bus state

3-65535 = reserved for future use

void Reset()

Reset the component. The behavior is implementation dependent.

TUEC Restore_Contents( TCOM_Stream* )

This method causes the component to restore its contents (but NOT state) from the passed stream. It is the responsibility of the component to restore the contents of any child components (but not attached components). For CPUs, the purpose of this is to restore cache contents.

TUEC Restore_State( TCOM_Stream* )

This method causes the component to restore its current state (but NOT contents) from the passed stream. It is the responsibility of the component to restore the state of any child components (but not attached components).

TUEC Save_Contents( TCOM_Stream* )

This method causes the component to save its contents (but NOT state) to the passed stream. It is the responsibility of the component to save the contents of any child components (but not attached components). For CPUs, the purpose of this is to store cache contents.

TUEC Save_State( TCOM_Stream* )

This method causes the component to save its current state (but NOT contents) to the passed stream. It is the responsibility of the component to save the state of any child components (but not attached components).

TUEC Set_Access_Mode( int64 Low, int64 High, boolean Memory. integer Type )

Sets the access mode of the specified address range (Low to High, inclusive). Type is:

1 = Read/Write (I/O)

2 = Read-only (input-only)

3 = Write-only (write-only)

Memory is true if address is a memory address and false if it is an I/O address. Note that a memory component has the same access mode for all addresses it handles, so if the address range overlaps that of the memory component, the new access mode applies to the entire address range of the component. The address range is n ot saved in the component, so if the valid address range is changed after the mode is set, the mode will remain as it was last set.

void Set_Parent( TComponent component )

Sets the component's parent. This value can be queried with Get_Parent.

void Set_Profiling( boolean On, boolean Children )

Turns profiling for this component on or off. Profiling is off by default. If Children is true, all child components will be assigned the same profiling value (this doesn't affect input or output components).

void Set_Read_Latency( integer Value )

Sets the component's default read latency in nanoseconds. If the component supports latency, it should block by this amount on each read.

void Set_Signal( string Name, boolean State )

Sets the state of a signal with the specified name. This should only be called with the signal actually changes state. That is, the value of state should never be the same on two consecutive calls. If it is, behavior is undefined.

void Set_Tag( integer Value )

Sets a user-defined value for the component, which can be queried via Get_Tag. The component does nothing with this value other than store it for retrieval with Get_Tag.

void Set_Trace( boolean Value )

Turns the component trace mode on if Value is True, and off otherwise.

void Set_Up( string Value )

Provides a means for a component-specific initialization string to be sent to the component after initialization. The format of this value and the component's behavior are implementation-specific.

TUEC Set_Watchpoint( int64 Address, boolean Memory, integer Access )

Sets a watchpoint at the specified address. When the component is about to access this address, it will generate a watchpoint notice to the UI interface. Access is the type of access:

1 = Read or write (input or output)

2 = Read (input)

3 = Write (output)

void Set_Write_Latency( integer Value )

Sets the component's default write latency in nanoseconds. If the component supports latency, it should block by this amount on each write.

void Show_Status()

Calling this method causes the component to report its status to the UI interface, in a human-readable form. For instance, a CPU component would report its registers and their contents.

void Signal_Change_Notice( TComponent* Component, integer Index, boolean Active )

Called when the specified component has a signal change. This is only called if the receiving component requested signal notices from the UI. Index is the signal index from the specified component.

integer Signal_Count()

Returns the number of signals defined (the maximum index plus 1).

string Signal_Name( integer Index )

Returns the name of the signal with the specified index. If the index is invalid, NULL is returned.

integer Signal_Index( string Name )

Returns the index of the signal with the specified name. If the name is invalid, -1 is returned.

boolean Signal_Out( integer Index )

Returns True if the signal is an output from the component. If the signal is an input to the component, the function returns False. If the index is invalid, the result is undefined.

boolean Signal_Active_Low( integer Index )

Returns True if the signal with the specified index is active when low (false). The Result is undefined if the index is invalid.

boolean Support_Feature( integer ID )

This method is reserved for future use.

TUser_Interface User_Interface()

Returns a TUser_Interface interface to the component. If the component is not a user interface, the method returns NULL.

integer Version()

Returns the version of the CEF specification that the UI adheres to. This is the major.minor version times 10. For instance, a value of 20 indicates version 2.0.

void Wake()

Calling this allows a component to resume its activity after it sends a Block request to the Master clock.

TUEC Write( int64 Address, integer Value, integer Size, integer IO_Type )

Calling this method writes Value to the component's input port with the specified address. Size is the number of bits in Value to write (0=default for component) and may be 0 to 32, inclusive. The component should verify that the address is within its range before responding. If not, it should do nothing and return success. For CPUs, this writes to the internal CPU memory cache. If the CPU has no internal memory cache, it should return success. IO_Type indicates the type of write operation:

0 = Memory write

1 = I/O output

2 = Set data bus to value. This indicates an address-less access.

3-65535 = reserved for future use

TUEC Write_String( int64 Address, string Value, integer Size, integer IO_Type )

This is the same as calling Write_Byte once for each byte in the string, incrementing Address once per byte. It is provided to allow more efficient means of transmitting large amounts of data. Size is the number of bits in Value to write (0=default for component). The component should verify that the address is within its range before responding. If not, it should do nothing. For CPUs, this writes to the internal CPU memory cache. If the CPU has no internal memory cache, it should return success. IO_Type indicates the type of write operation:

0 = Memory write

1 = Port output

The following methods are supported in components conforming to version 2.1, or later, of the specification.

String Get_Port_Name( int Index )

Returns the name of the port with the specified index. If Index is invalid, NULL is returned. These ports are provided primarily by system emulators to allow users to select where to connect other components (such as printers and terminals).

String Get_Port_Description( integer Index )

Returns the description of the port with the specified index. If Index is invalid, NULL is returned. These ports are provided primarily by system emulators to allow users to select where to connect other components (such as printers and terminals).

TComponent* Get_Port( integer Index )

Returns the cable-end for the port with the specified index. If Index is invalid, NULL is returned. This component is the object to which to connect another component. These ports are provided primarily by system emulators to allow users to select where to connect other components (such as printers and terminals).

TComponent* Get_Port_Connection( integer Index )

Returns the component currently connected to the port with the specified index. If Index is invalid, NULL is returned. If no component is connected to the port, NULL is returned. These ports are provided primarily by system emulators to allow users to select where to connect other components (such as printers and terminals).

void UI_Notice( integer Code, int64& Data )

Notice from TUI_Interface component. Code is UC_* code. Data depends on the calue of Code.

Profilers

A profiler is an interface to profiling information in a component. An instance of a profiler is requested from the component whose profile data is required. The profiler can then be queried for profile information. Integral to the design of profilers is the concept of domains. A profiler domain is a specific type of profiling data. A profiler may provide zero, one, or more domains. Examples of domains from a CPU component are numbers of calls to specific instructions, number of accesses to specific ports, and number of accesses to specific memory addresses. However, it should be noted that no component, including CPUs, are required to provide any profiling information or any specific domains. The methods of the TProfiler class are:

void Clear( integer Domain )

Clears all profiling information for the specified domain. If Domain is -1, all domains are cleared. The call is ignored if Domain is out of the range of valid domains.

string Domain_Name( integer Index )

Returns the domain name for the specified index. If the index is not a valid domain, the method returns NULL. The first domain is index 0.

string Report_Line( integer Domain, integer Index )

Returns a line of textual information associated with the specified domain. Index is the line of information to retrieve. The first line is index 0. If an invalid domain or index is passed, the method returns NULL.

integer Version()

Returns the version of the CEF specification that the object adheres to. This is the major.minor version times 10. For instance, a value of 20 indicates version 2.0.

CPUs

CPUs differ from most other components in that they usually take over the operation of the application once Marshalling is complete. Initialization of the CPU component doesn't begin operation (the TCPU.Run method does). That way, Marshalling can be completed prior to the CPU beginning operation. Functions unique to CPUs are accessed via the TCPU object, provided via the Tcomponent.CPU method.

CPUs support the concept of address spaces. There is always at least one address space (index 0), which is the default address space. An address space is a range of memory addresses. Some CPUs may only support a single address space which is accessed via the Program Counter (or Instruction Pointer). Other CPUs with virtual memory mapping may support a number of address spaces, each of which is indexed via a different register.

CPU's examine/deposit methods access the internal cache of the CPU (if Memory parameter is true) or the registers of the CPU (if Memory parameter is false). See the TCPU.Register_Name and TCPU.Register_Size methods for more information on the CPU registers. A CPU component returns a TCPU* instance when the CPU() method is called.

The TCPU class has the following methods:

boolean Big_Endian()

Returns True if the CPU processes data in a big-endian manner (most-significant bytes at lower addresses), or False if the CPU processes data in a little-endian manner (least significant bytes a re lower addresses).

TUEC Cancel_Breakpoint( int64 Address, integer Space, boolean Physical )

Clears a breakpoint at the specified address in the specified address space. If Physical is true, the address is a physical address, otherwise it is a virtual address.

TUEC Clear_Internal_Watchpoint( int64 Address, boolean Memory, integer Access )

Clears a watchpoint at the specified address. Access is the type of access:

1 = Read or write (input or output)

2 = Read (input)

3 = Write (output)

If Memory is true, the address is an internal cache address. Otherwise it is a register index.

integer Default_Base()

Indicates the specified base used by the CPU instruction set.

tUEC Disassemble( int64 Address, integer Base, integer Size, TCOM_Stream* )

Disassembles the instructions at the specified address, for the specified number of bytes and directs the output to the passed stream. Constants are shown in the specified base. If Base is 0, the CPUs default base is used.

integer Facility_Code()

This method returns the facility code for this object.

TAssembler* Get_Assembler( TMaster_Assembler* )

This method returns an assembler object for this CPU. It is passed a TMaster_Assembler object. See the section on the Assembler fo details.

integer Get_Clock_Speed()

Returns the CPU clock speed (in KHz).

int64 Get_Current_Address( integer Space, boolean Physical )

Returns the current CPU memory position for the specified address space.

int64 Get_Low_Memory()

Indicates the lowest physical memory address accessible by the CPU.

int64 Get_High_Memory()

Indicates the highest physical memory address accessible by the CPU.

int64 Get_Low_Port()

Indicates the lowest port address accessible by the CPU.

int64 Get_High_Port()

Indicates the highest port address accessible by the CPU.

int64 Get_Low_Virtual_Memory()

Indicates the lowest virtual memory address accessible by the CPU.

int64 Get_High_Virtual_Memory()

Indicates the highest virtual memory address accessible by the CPU.

void Halt()

Halts CPU execution. The effect upon the CPU is implementation-dependent.

boolean Halted()

Returns true if the CPU is in a halted state (non-execution mode).

string Memory_Space_Description( integer Index, boolean Physical )

Returns a description of the memory space with the specified index. It returns NULL for any invalid index. Physical is True for physical memory space and false for virtual address space. Most CPUs make no distinction between physical and virtual memory in this method.

integer Page_Size()

Returns the CPU's memory page size, in bytes. If the CPU doesn't support paging, this returns 0.

string Register_Description( integer Index )

Returns a description of the register associated with the specified index (0 is the first valid index). If the index is not valid, the function returns NULL. This is not the register name, but some additional information about the register. For instance, for a flags register, this would be a break-out of the flags in the register.

string Register_Name( integer Index )

Returns the name corresponding to the register index passed. A null string or NULL result indicates that the index is out of range. Note that all registers start at offset 0. Register 0 is always the current Instruction pointer (IP, PC, etc) and register 1 is always the current Stack pointer (SP).

integer Register_Size( integer Index )

Returns the size (in bits) of the register associated with the passed index. A result of 0 indicates that the index is out of range.

void Restart

Performs a power-on (cold) reset.

void Run()

Begins CPU execution from the current CPU state. Typically one instruction is executed, and then the CPU requests a block from the master clock.

void Run_From_Stream( TCOM_Stream* )

The causes the CPU to execute instructions directly from the passed stream. This is usually for immediate instruction execution from the user interface, thus no profiling is done, no breakpoints apply, and single-stepping does not occur.

TUEC Set_Breakpoint( int64 Address, integer Space, boolean Physical )

Sets a breakpoint at the specified address in the specified address space. When the CPU is about to begin execution at this address, it will generate a breakpoint notice to the UI interface. If Physical is true, the address is a physical address, otherwise it is a virtual address.

void Set_Clock_Speed( integer value )

Sets the CPU clock speed (in KHz).

void Set_Current_Address( integer Space, boolean Physical, int64 Value )

Sets the current CPU memory position for the specified address space. If Physical is true, the address is a physical address, otherwise it is a virtual address.

TUEC Set_Internal_Watchpoint( int64 Address, boolean Memory, integer Access )

Sets a watchpoint at the specified address. When the CPU is about to access this address, it will generate a watchpoint notice to the UI interface. Access is the type of access:

1 = Read or write (input or output)

2 = Read (input)

3 = Write (output)

If Memory is true, the address applies to internal cache. If Memory is false, address is the register.

void Step( boolean Into )

Executes a single instruction based on the current CPU context. This is the same as Run(), but execution doesn't continue after the CPU is unblocked. If Into is true, only a single instruction is excecuted. If Into is false, and the instruction to be executed is a nested instruction (such as a subroutine call), execution continues until the execution returns to the instruction following the call.

void Stop()

Stops CPU execution.

boolean Support_Virtual_Address()

Returns True if the CPU supports virtual address mapping.

int64 Top_Of_Stack( integer Index )

Returns the address of the top of the stack with the specified index. The first valid stack index is 0. For CPUs with only one stack, the stack is index 0.

int64 Translate( integer Space, int64 Address )

Returns the physical address for the passed virtual address in the passed address space. For a CPU with no virtual addresses, this returns the value passed.

integer Version()

Returns the version of the CEF specification that the object adheres to. This is the major.minor version times 10. For instance, a value of 20 indicates version 2.0.

The following methods apply to Version 2.2, and later, of the specification:

int Segment_Size( int Index )

Indicates the size (in bits) of the Indexth segment in the last assembled instruction. A value of 0 indicates either an invalid Index or that the information is otherwise not available. Index < 0 is not valid. The result can be used to separate the various segments of assembled instructions. For instance, a 2-byte instruction followed by two 2-byte operands would return 2 for indexes 0, 1, and 2.

string Address_Representation( int Base, int64 Address )

Returns a representation of the passed address, or nil if not supported, or the address is invalid. This is used when addresses are displayed in a format not otherwise supported by CEF. Base is the base to use for any numeric representation.

int64 Translate_Address( Boolean& B, int Base, string Address )

Used to convert an address specification into a linear address value. B is ignored on call and is True on return if the address is a valid format. Base is the base that any numeric portion of the address is assumed to be.

int64 Get_Low_Input_Port( int Space )

Indicates the lowest input port address accessable by the CPU for port space Space. -1 indicates an invalid port space.

int64 Get_High_Input_Port( int Space )

Indicates the highest input port address accessable by the CPU for port space Space. -1 indicates an invalid port space.

int64 Get_Low_Output_Port( int Space )

Indicates the lowest output port address accessable by the CPU for port space Space. -1 indicates an invalid port space.

int64 Get_High_Output_Port( int Space )

Indicates the highest output port address accessable by the CPU for port space Space. -1 indicates an invalid port space.

TCEF_Stack_Interface* Get_Stack_Interface( int Space )

Returns an instance of a stack interface for accessing non-standard stacks for stack space Space. Returns nil if no stack or standard stack handling.

Cable components

Cable components emulate a hardware cable, which connects other components. More specifically, this indicates one side of a cable, with the states matching the port that the cable is connected to. Simple cables, such as RS-232 serial cables, are usually connected to a port on one side and to another cable end on the other. Some cables have addresses (such as SCSI) and the normal Write operations should be used to supply an address in these cases. These cables are typically connected to multiple components, addressed via those addresses. Functions unique to cables are accessed via the TCable object, provided via the TComponent.Cable method.

The TCable class has the following methods:

Boolean Serial()

Returns true if this is a serial cable. False if parallel.

String Protocol()

Returns name of the protocol supported by this cable. Returns empty string if generic.

TUEC Transmit( int64 Speed, integer Value, integer Data_Size, integer Stop_Bits )

Calling this method transmits Value to the component. Speed is the transfer rate in bits/second. A speed of 0 indicates automatic speed matching between both ends of the cable. Data_Size is the number of bits in Value to write (0=default for component) and may be 0 to 32, inclusive. Stop bits indicate the number of stop bits for serial transfers. This calls Receive on connected cable components.

TUEC Transmit_String( int64 Speed, string Value, integer Data_Size, integer Stop_Bits )

This is the same as calling Transmit once for each byte in the string. It is provided to allow more efficient means of transmitting large amounts of data. Speed is the transfer rate in bits/second. A speed of 0 indicates automatic speed matching between both ends of the cable. Size is the number of bits in Value for each transmission (0=default for component). Stop_Bits indicates the number of stop bits for each transmit on serial transfers.

void Receive( TComponent Source, int64 Speed, integer Value, integer Data_Size, integer Stop_Bits )

Called by a Transmit from a connected cable component. Speed is the transfer rate in bits/second. A speed of 0 indicates automatic speed matching between both ends of the cable. Data_Size is the number of bits in Value to write (0=default for component) and may be 0 to 32, inclusive. Stop bits indicate the number of stop bits for serial transfers. THe component that the transmission is received from is passed in Source.

boolean Get_Data( int64 &Speed, integer &Value, integer &Data_Size, integer &Stop_Bits )

Returns the data last received. The function returns False if no data has been received since the last call to Get_Data. The parameters are ignored on call. On a successful return the parameters are filled with the data from the last Receive call.

Memory components

A Memory component is a data storage and retrieval component. Functions unique to memories are accessed via the TMemory object, provided via the TComponent.Memory method.

The TMemory class has the following methods:

void Dump( int64 Start, int64 Size, pointer Buffer )

Dumps an image of memory between Start and Start + Size - 1, inclusive, to the passed buffer, which must be large enough to hold Size bytes. Any range of addresses that are outside of the memory component's range are zero-filled.

void Get_Address_Range( int64& Low, int64& High )

Returns the set of addresses that this component responds to.

void Load( int64 Start, int64 Size, pointer Buffer )

Loads memory between Start and Start + Size - 1, inclusive, with data in the passed buffer. Any data outside of the memory component's range is ignored.

TUEC Set_Address_Range( int64 Low, int64 High )

Defines the set of addresses that this component responds to.

integer Version()

Returns the version of the CEF specification that the object adheres to. This is the major.minor version times 10. For instance, a value of 20 indicates version 2.0.

Assembler Status

Instances of the assembler status class are used to record the status of an assembly operation. The instance is created by the code that calls the master assembler's Assemble() method.

The TAssembler_Status class contains the following methods:

string Filename()

Returns the name of the current file being assembled.

boolean Get_Aborted()

Returns the current aborted state. Initially it is false but can be set via Set_Aborted.

int64 Get_Code()

Returns the number of bytes of generated Code.

int64 Get_Data()

Returns the number of bytes of generated Data.

integer Get_Errors()

Returns the count of serious and/or fatal errors.

integer Get_Warnings()

Returns the count of warnings.

string Get_Error_Text()

Returns the default error text set via Set_Error_Text.

void Set_Aborted( boolean Value )

Sets the aborted state.

void Set_Code( int64 Value )

Sets the code size, in bytes.

void Set_Data( int64 Value )

Sets the data size, in bytes.

void Set_Errors( integer Value )

Set error count.

void Set_Warnings( integer Value )

Set warning count.

void Set_Error_Text( string Value )

Sets the default error text.

void Get_Error( integer Index, string& Text, string& Filename, integer& Line, integer& Severity )

Retrieves the error information from the error list at the specified index (0 is the first). If the index is invalid the text will be set to NULL.

void Log_Error( string Text, string Filename, integer Line, integer Severity )

Add an error to the error list with the specified text, filename, line number and severity. If Line is -1, the current line is used. The current line is set via Set_Line. Severity is one of the following values:

0 = Informational message

1 = Warning

2 = Non-fatal error

3 = Fatal error

void Set_Line( integer Value )

Sets the current line number.

Void Output_To_Listing( String Text, integer Text_Type )

The assembler sends text to this method while assembling the code. This can be ignored, or used to create a listing output. The text types are:

Value	Meaning
0	Source
1	Generated data
2	New line
3	New page. Has no effect if paging is turned off.
4	Title text
5	Turn on paging mode. Paging mode defines 66 lines per page, with the top 3 and bottom 3 being margins and headings. Paging is on by default.
6	Turn off paging mode.

User Interface Components

User Interface components should not be confused with the TUI_Component object which is the interface between TComponent descendants and the main application. User Interface components are Components which provide a visual interface for the user. They operate in one of two modes: stand-alone and embedded. When embedded, user interface components are shown inside the application (assuming the application supports that). In Stand-alone mode the component shows apart from the application. Functions unique to User Interfaces are accessed via the TUser_Interface object, provided via the TComponent.User_Interface method.

The TUser_Interface class has the following methods:

boolean Get_Hidden()

Returns True if the component is currently visible.

void Set_Hidden( boolean Value )

Sets the component to hidden (if Value is true) or visible (if Value is false).

integer Get_Parent_Window()

Returns the handle of the component's parent window.

void Set_Parent_Window( integer Value )

Sets the component's parent to the window with the passed handle.

string Get_Caption()

Returns the caption of the component.

void Set_Caption( string Value )

Sets the caption of the component.

void Set_Size( integer Height, integer Width )

Sets the visual size of the component to the passed height and width, in pixels.

integer Optimal_Height()

Returns the optimal height of the component, in pixels.

integer Optimal_Width()

Returns the optimal width of the component, in pixels.

integer Version()

Returns the version of the CEF specification that the object adheres to. This is the major.minor version times 10. For instance, a value of 20 indicates version 2.0.

Keyboard Components

A keyboard component is a visual component that represents a particular keyboard layout. A CEF keyboard component doesn't send data associated with keystrokes, but rather uses key names. For some keys, names are simply "A", or "1". For others, the name represents the glyph or function of the key - for instance, "LEFT" or "BREAK". Each key name also has a corresponding index. A series of individual keys can be pressed together (for instance, SHIFT and a letter). Such a combination of keys is called a "keystroke". A keystroke ends when all keys are no longer pressed by the user. Note that some keys can lock into a down position and in a down state do not prevent a keystroke from completing. The keyboard component can notify connected components of key state changes, but the keyboard can also be queried for keystroke state. These operations operate in parallel and the application can use the component in a polled or interrupt fashion. However, when used in an interrupt fashion, the keyboard should be polled to clear its queue of keystrokes and prevent excessive memory usage.

The convention of a "NKP_" prefix is used for otherwise normal characters that occur on a numeric keypad. Thus "1" indicates a normal "1" key, but "NKP_1" indicates a "1" key from a numeric keypad. Any receiver of data from a keyboard component should strip "NKP_" from the front of a key name when interpreting keys UNLESS that receiver wishes to specifically distinguish between the two keys. Likewise, "LEFT_" prior to a key name indicates the left of two instances of a key (for instance, SHIFT), and "RIGHT_" indicates the right of the two keys. These conditions should be handled appropriately.

When a key is pressed or released, the component does a port write to connected components where the port number is the key index and the data is 1 for keydown or 0 for keyup.

TKeyboard provides special functions for accessing simple LEDs on the keyboard. For more complicated displays, the Write method should be used. Functions unique to keyboards are accessed via the TKeyboard object, provided via the TComponent.Keyboard method.

The TKeyboard class has the following methods:

PChar Get_Key()

Retrieves the next key in a keystroke from the keyboard. Returns NULL if no more keystrokes or a null string if end of current keystroke. Note that all keys returned by this method are appropriate for any corresponding key states. For instance, when the "A" key is pressed then if SHIFT is down, the returned key will be "A". If SHIFT is up, the returned key will be "a".

Boolean Get_Key_Down( string Name )

Returns True if the specified key is down in the pending keystroke. If Name is NULL, returns True if any key is down in the pending keystroke. It also returns False if the key name is unknown.

void Set_Key_Down( string Name, Boolean State )

Sets the state of a given key to up or down. The key is reset when the next keystroke is returned. This can be used to synchronize the keyboard component's visible state with the physical keyboard.

string Get_Key_Name( integer Index )

Returns the name of the key associated with the passed index. Returns NULL if the index is invalid. It is valid for different indexes to refer to the same key name. Typically this occurs for corresponding upper and lower-case letters.

boolean Get_LED_State( string Name )

Returns True if the specified LED is lit. If the LED name is not recognized, the function returns false.

void Set_LED_State( string Name, boolean State ) ;

Sets the state of a given LED to lit or not. This can be used to synchronize the keyboard component's visible state with the physical keyboard.

string Get_LED_Name( integer Index )

Returns the name of the LED associated with the passed index. Returns NULL if the index is invalid.

integer Version()

Returns the version of the CEF specification that the object adheres to. This is the major.minor version times 10. For instance, a value of 20 indicates version 2.0.

Further, keyboard components have special meanings for TComponent methods, as follows:

Reset()

Clears all pending keystrokes and sets all keys to the default state (usually up). A given implementation may also perform other functions during a Reset.

The Assembler

The process of assembly (compilation of CPU instructions) requires the cooperation of two objects: one TAssembler and one TMaster_Assembler. The master assembler controls the assembly process, but the TAssembler does the actual translation of CPU instructions into machine code. The scope of responsibility for each component is thus: the master assembler is responsible for all file I/O, including source, listings, and binaries. It is also responsible for handling general directives and formatting of output. The TAssembler is responsible for handling any unique directives, translation of synonym directives, and compiling the actual CPU instructions. All source tokens are passed first to the TAssembler. Anything it doesn't handle must be passed back to the Master Assembler (via the Expand method of the latter).

TAssembler methods:

void Initialize( TMaster_Assembler* )

Informs the assembler the a new assembly operation is beginning. This assembly will use the passed master assembler.

void Terminate

Informs the assembler that the current assembly operation is now complete.

TUEC Assemble( string inputs, string &outputs, string &machines, integer &machinel, int64 &address, integer &Segment, TAssembler_Status* Status )

This method is equivalent to the Assemble_Ex method with the Flags parameter set to 0.

integer Default_Radix()

Returns the default radix (base) of numeric literals.

integer Default_Size()

Returns the default size of numeric literals, in bits.

integer Facility_Code()

Returns the facility code for this assembler (see UEH).

string Source_Extensions()

Returns a bar-delimited list of source file extensions. The first one is the default. Example: "asm|mac|txt"

string Valid_Symbol_Initial()

Returns a list of valid characters for starting a symbol name.

string Valid_Symbol_After()

Returns a list of valid characters for a symbol name, past the first.

integer Version()

Returns the version of the CEF specification that the object adheres to. This is the major.minor version times 10. For instance, a value of 20 indicates version 2.0.

boolean Backpatching( string Name, int64 Address, int64& Value, integer& Size, integer Context, integer Options, Tassembler_Status* Status )

Called by the master assembler just before it backpatches an address. If the function returns False, the master assembler doesn't perform the backpatch. Otherwise it does. Name is the expression that was evaluated for this backpatch, Address is the address of the backpatch data, Value is the data to write to Address, and Size is the size of the backpatch, in bytes. Context and Options are the values passed to the Add_Reference_Ex method of the master assembler.

The following TAssembler methods are new with V2.2 of the specification:

string Normalize_Expression( string Expression, boolean Numeric, TAssembler_Status* Status )

This method is called by the Master Assembler when it is about to evaluate an expression. This allows the CPU's assembler to handle any special syntax, etc, by converting the expression to a "normalized" expression that can be understood by the master assembler. If the CPU's assembler doesn't handle this it should simply pass back the passed-in value.

TUEC Assemble_Ex( TCOM_Stream* Input, TCOM_Stream* Output, TCOM_Stream* Listing, TAssembler_Status* Status, integer Flags )

This method assembles the source code in the inputs string. If inputs is a null string, the assembler should fetch the data from the master assembler (Get_Token method). Formatted output (if any) is returned in outputs, which is assumed to be in a human-readable form. Upon return, machines contains the generated machine code for the instruction(s) passed. machinel is the length of the data in machines. address is the target memory address where the machines data is to go. Segment is the current destination segment for the data in machines. It has the following values:

0 = Default code segment

1 = Default data segment

other = CPU-dependent or user-defined segments

machinel, address, and Segment are passed the current values from the master assembler, but the called assembler may change them. address is virtual (physical if virtual addressing not supported by CPU). Status is the status object to be used to log assembly status. Flags are bit flags indicating processing options:

Value	Description
1	Assembly is in immediate mode. No forward declarations should be allowed.
2+	Reserved.

Assembler Context

The assembler context is used to keep track of symbols defined during assembly. It is used both by the master assembler and also by any

application that wishes to make use of symbol information after assembly. Essentially, the assembler context is a symbol table manager.

During assembly, all symbol manipulation should be done through the Master Assembler rather than directly through the assembler context so that the Master Assembler has the option of keeping additional symbol information. TCEF_Assembler_Context has the following methods.

int Add_Mapping( char* Filename, int64 Address, int Line )

Associates a memory address with a Filename and Line number. The line number is 1-based. The method returns a context which can be passed to Delete_Mapping.

TUEC Add_Symbol( char* Name, TSymbol_Record* P )

Adds a symbol to the current scope with the data specified in P. The return value's code field is one of the following:

Value	Meaning
0	Success
1	Invalid symbol name
2	Reserved name
3	Multiply defined symbol

void Delete( char* Sym )

Deletes the symbol with the specified name from the current scope, or the most recent scope in which it was defined.

void Delete_Mapping( int Index )

Deletes the mapping added with Add_Mapping. Index is the mapping context returned by Add_Mapping.

int Find( char* Sym, int64& Addr, int& Flg, int& D_T, int& Siz, void*& Dat )

Returns information on the specified symbol in the current, or nearest, scope. Sym is the symbol name and the rest of the parameters are ignored on call. On return, Addr is the address/value of the symbol, Flg is symbol flags, D_T is data type, Siz is the size (in bytes), and Dat is user-defined data. Method return values:

Value	Meaning
0	Success
1	Invalid symbol name
4	Undefined reference
5	No more matches

int Mapping( int64 Address, char*& Filename )

Returns filename and line number corresponding to the passed address. If there is no mapping, it returns -1.

void Pop_Level()

Ends the current symbol table scope level. All Symbols in the current scope are lost