| Backward | Up | Forward |
|---|
The hardware interface to SMI is defined by two groups of system tasks. The first set is used to connect and send messages between hardware and software model instances. A connection is made with $smi_initial() which returns an model instance identifier. Messages, i.e. lists of values, can then be sent to the software model instance with either $smi_write(), if no reply is required, or $smi_read(), is a reply is required. Reply messages of more than a single value can be read using $smi_data().
The second set of system tasks is used to control the simulation exit procedure. The simulation exit procedure is initiated using $smi_exit() or by the user hitting Control-C after $smi_signal() has been run. The simulation must poll to see if the simulation exit procedure has been initiated using $smi_exiting() or by calling $smi_poll_exiting() periodically. Once the simulation exit procedure has been initiated, the simulation calls $smi_finish() to shut down SMI models and test processes.
| $smi_initial() | |||
|---|---|---|---|
| Synopsis: | Establish a connection to software model instance | ||
| Syntax: | $smi_initial(id, model, instance) | ||
| Outputs: | Type | Name | Description |
| integer | id | Model instance identifier | |
| Inputs: | Type | Name | Description |
| string | model | Model name | |
| string | instance | Instance name of this model | |
| Note: | This task must be called once for each model instance. | ||
This command must be the first SMI operation issued within a hardware model instance as calls to messaging tasks require the output "id" supplied by this task. The task begins by searching the internal database of model instances to see if it contains the instance specified by the "model" and "instance" strings. If so, the identifier uniquely identifying the model instance is output to "id" and the task returns. If the database does not contain an entry matching the "model" and "instance" strings, the task waits for a test process to connect to the hardware simulation. The test process begins communication by listing all the software model instances it supports (see SMI_Channel::post()). It lists a pair of "model" and "instance" strings for each model instance. These string were associated with the software model instance by using the SMI_Channel::add() method in the test process. For each software model instance advertised by the test process, SMI creates a corresponding hardware model instance and adds it to the database of model instances keyed by the "model" and "instance" strings. After each test process has connected to the hardware simulation, the database is re-scanned to see if an entry now matches the "model" and "instance" input strings. The task will continue to accept connections from test processes until the matching entry is found. At this point, the unique identifier is output to "id" and the task returns.
For example, the task call:
integer id;
initial
$smi_initial(id, "MyModel", "MyInstance");
creates a connection to the software model instance initialized as follows:
MyModel::MyModel()
{
SMI_Channel* channel = SMI_Channel::instance();
channel->add("MyInstance", "MyModel", this);
}
provided the class MyModel inherits from
SMI_Model and an instance exists in the test process.
| $smi_write() | |||
|---|---|---|---|
| Synopsis: | Send a message to a software model instance | ||
| Syntax: | $smi_write(id, value_1..value_N) | ||
| Inputs: | Type | Name | Description |
| integer | id | Model instance identifier | |
| wire, reg, real, integer, string | value_1..value_N | A variable length list of values to be sent to the software instance. Values may be of mixed data type and of any bit width. | |
| Note: | A valid "id" argument must have been obtained by calling $smi_initial() before invoking this task. | ||
This task sends a message to a software model instance identified by the "id" input argument. The message contains a representation of the values, "value_1..value_N", passed as input arguments to $smi_write(). No reply message is expected.
The message received by the software model instance is encapsulated by an SMI_RxMessage object. All messages are processed by the SMI_Model::process() method of the object implementing the software model instance.
For example, given the task call:
$smi_write(id, 3.14, "hello", 4'b01zx, 4'b0101);to the software model instance coded as follows:
SMI_TxMessage*
MyModel::process(const SMI_RxMessage& rx)
{
double value_1(rx.real(0));
string value_2(rx.text(1));
string value_3(rx.signal(2));
unsigned int value_4(rx.integer(3));
cout << "value_1 = " << value_1 << endl;
cout << "value_2 = " << value_2 << endl;
cout << "value_3 = " << value_3 << endl;
cout << "value_4 = " << value_4 << endl;
return 0;
}
the following output is produced:
value_1 = 3.14 value_2 = hello value_3 = 01zx value_4 = 5
| $smi_read() | |||
|---|---|---|---|
| Synopsis: | Send a message to and receive a reply from a software model | ||
| Syntax: | $smi_read(id, value_1..value_N, reply_1) | ||
| Inputs: | Type | Name | Description |
| integer | id | Model instance identifier | |
| wire, reg, real, integer, string | value_1..value_N | Variable length list of values to be sent to the software instance. Values may be of mixed data type and of any bit width. | |
| Outputs: | Type | Name | Description |
| reg, real, integer | reply_1 | Set to the first value in the reply message sent by the software instance. The data type must match the data type of the message value. | |
| Note: | Must occur after $smi_initial(). | ||
This task sends a message to and receives a reply from a software model instance identified by the "id" input argument. The outgoing message contains a representation of the values, "value_1..value_N", passed as input arguments to $smi_read(). After this message has been processed the software model instance sends a reply message back to the hardware simulation. The first value in the reply message is output to "reply_1". The remaining values in the reply message are stored until read by $smi_data().
The message received by the software model instance is encapsulated by an SMI_RxMessage object. All messages are processed by the SMI_Model::process() method of the object implementing the software model instance. The software model instance constructs a reply message encapsulated by an SMI_TxMessage object which is returned by the SMI_Model::process() method.
For example, given the task call:
$smi_read(id, 3.14, "hello", 4'b01zx, 4'b0101, reply_1);
$display("reply_1 = %d", reply_1);
to the software model instance coded as follows:
SMI_TxMessage*
MyModel::process(const SMI_RxMessage& rx)
{
// EXTRACT VALUES FROM INCOMING MESSAGE
double value_1(rx.real(0));
string value_2(rx.text(1));
string value_3(rx.signal(2));
unsigned int value_4(rx.integer(3));
// PRINT MESSAGE VALUES
cout << "value_1 = " << value_1 << endl;
cout << "value_2 = " << value_2 << endl;
cout << "value_3 = " << value_3 << endl;
cout << "value_4 = " << value_4 << endl;
// ALLOCATE REPLY MESSAGE STRUCTURE ONCE ONLY
static SMI_TxMessage* tx(0);
if (tx == 0)
tx = SMI_Channel::instance()->newTxMessage();
// APPEND REPLY MESSAGE VALUES
tx->append(3.14);
tx->append("0011zzxx");
tx->append(32, 42);
// RETURN REPLY MESSAGE
return tx;
}
the following output is produced by the test process:
value_1 = 3.14 value_2 = hello value_3 = 01zx value_4 = 5the following output is produced by the hardware simulation:
reply_1 = 3.14
| $smi_data() | |||
|---|---|---|---|
| Synopsis: | Read and remove values from a reply message | ||
| Syntax: | $smi_data(id, reply_2..reply_N) | ||
| Inputs: | Type | Name | Description |
| integer | id | Model instance identifier | |
| Outputs: | Type | Name | Description |
| reg, real, integer | reply_2..reply_N | Set to the values in the reply message sent by the software instance. The data types must match the data types of the message values. The number of values read must not exceed the number of values remaining in the reply message. | |
| Note: | Must occur after $smi_read(). | ||
The task $smi_read() receives a reply message from a software model instance identified by the "id" input argument. The first value in the reply message is output to by $smi_read(). The remaining values in the reply message are stored, on a per-model instance basis, until read by $smi_data() or until the next $smi_read() call for this model instance. Values in the reply message are output to "reply_2..reply_N".
For example, given the task call:
$smi_read(id, 3.14, "hello", 4'b01zx, 4'b0101, reply_1);
$smi_data(id, reply_2, reply_3);
$display("reply_1 = %d", reply_1);
$display("reply_2 = %b", reply_2);
$display("reply_3 = %d", reply_3);
to the software model instance coded as follows:
SMI_TxMessage*
MyModel::process(const SMI_RxMessage& rx)
{
// EXTRACT VALUES FROM INCOMING MESSAGE...
// PRINT MESSAGE VALUES...
// ALLOCATE REPLY MESSAGE STRUCTURE ONCE ONLY
static SMI_TxMessage* tx(0);
if (tx == 0)
tx = SMI_Channel::instance()->newTxMessage();
// APPEND REPLY MESSAGE VALUES
tx->append(3.14);
tx->append("0011zzxx");
tx->append(32, 42);
// RETURN REPLY MESSAGE
return tx;
}
the following output is produced by the hardware simulation:
reply_1 = 3.14 reply_2 = 0011zzxx reply_3 = 42
| $smi_exit() | |
|---|---|
| Synopsis: | Initiate the simulation exit procedure |
| Syntax: | $smi_exit() |
| Note: | Sets output of $smi_exiting() to 1 from 0. |
This task sets a global "exit" flag within the hardware simulation that can be polled using $smi_exiting() or $smi_poll_exiting(). When the flag is set, the simulation exit procedure cleans up the simulation (e.g. closes the waveform file) before calling $smi_finish(), which terminates all the models and test processes, followed by $finish, which ends the simulation.
| $smi_signal() | |
|---|---|
| Synopsis: | Causes Control-C to initiate the simulation exit procedure |
| Syntax: | $smi_signal() |
This task installs a handler that traps Control-C interrupts. The $smi_exit() task is run whenever the user hits Control-C after $smi_signal() has been called.
| $smi_exiting() | ||
|---|---|---|
| Synopsis: | Returns true if the simulation exit procedure has been initiated | |
| Syntax: | assign exit = $smi_exiting(); $smi_poll_exiting(exit); | |
| Returns: | Type | Description |
| boolean | Zero by default, this flag is set to one if a termination request is received. | |
| Note: | The simulation exit procedure may be initiated by calling $smi_exit() or SMI_Channel::setExiting(), or possibly by hitting Control-C (see $smi_signal() and SMI_Channel::signal()). | |
A single instance of $smi_exiting() (or $smi_poll_exiting()) must exist in every hardware simulation. The return value of this function is zero be default and set to one when the simulation exit procedure has been initiated. When the flag is set, the simulation exit procedure should clean up the simulation (e.g. close the waveform file) before calling $smi_finish(), which terminates all the models and test processes, followed by $finish, which ends the simulation.
For example, the following code implements the simulation exit procedure:
integer is_exiting; // EXIT FLAG
initial is_exiting = 0;
always@(posedge clock)
begin
// POLL SIMULATION EXIT FLAG EACH CLOCK CYCLE
$smi_poll_exiting(is_exiting);
// IF SIMULATION EXIT REQUESTED
if (is_exiting == 1)
begin
// SIMULATION EXIT PROCEDURE
$dumpflush; // FLUSH WAVEFORM LOG
$smi_finish; // SHUTDOWN SMI MODELS/PROCESSES
$finish; // EXIT THE SIMULATION
end
end
Implementation Note: System functions are not currently supported by Icarus Verilog and the VCS implementation is not behaving as expected. The system task $smi_poll_exiting(exit) has been introduced to work around these problems. It should be called periodically to test whether the simulation has terminated.
| $smi_finish() | |
|---|---|
| Synopsis: | Terminate SMI operations |
| Syntax: | $smi_finish() |
This task deletes all software model instances, terminates all test processes, and shuts down all SMI communications. This task should be part of the simulation exit procedure (see $smi_exiting()), invoked before $finish.
| Backward | Up | Forward |
|---|