5 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 methods are supported in UI Interfaces conforming to version 2.2, or later, 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.

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.

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

void Add_Port_Breakpoint()

Prompt user and add a new port breakpoint.

void Add_Breakpoint()

Prompt user and add an execution breakpoint.

void Add_Register_Breakpoint()

Prompt user and add register breakpoint.

void Create_New_Breakpoint()

Prompt user and create a new memory breakpoint.

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.

The following methods are supported in UI Interfaces conforming to version 2.6, or later, of the specification.

string Get_Component_Filename( string Name )

Return passed component name qualified by path, etc.

procedure Termination_Notice( TComponent* C )

Notice that the passed component is being destroyed and should not be referenced again.

TComponent* Load_Component( string Name )

Load and return a component with the specified name.