| Backward | Up | Forward |
|---|
This section describes how the SMI library can be integrated into your simulation environment. The first sub-section shows how to configure, build and install the SMI library. The second sub-section describes how to compile the hardware simulation and test processes. The final sub-section discusses how to run simulations that use SMI.
Configuring, building and installing the SMI library is designed to be a straightforward procedure.
./configure configuration_options # Configure SMI make # Build SMI make install # Install SMITo select the correct configuration options, we must answer three questions:
By default the SMI library is installed in /usr/local/lib, the
header files are installed in /usr/local/include. To select a base
directory other than /usr/local append the
--prefix=path option to configure. For example, to install
into /opt/smi/lib and /opt/smi/include use the
following switch:
./configure --prefix=/opt/smi
SMI supports three implementations of the inter-process/inter-thread communications layer that connects the hardware simulation to the test processes. The following table shows the configuration switches required to enable support for each specific implementation. Multiple implementations can be supported.
| Implementation | Configuration Switch | Default State | Default Directory |
|---|---|---|---|
| TCP/IP Sockets | --disable-socket | Enabled | |
| CORBA | --enable-corba[=CORBA_DIR] | Disabled | CORBA_DIR = /usr/local/corba |
| Portable Threads | --enable-threads | Disabled |
TCP/IP sockets are supported by most operating systems without requiring additional libraries. The communications library provided by sockets is much lower level than CORBA. The sockets implementation requires SMI to do a lot more work and is less portable than the CORBA implementation. However, CORBA is a huge piece of code, has many flavours and does not come as standard with UNIX distributions.
CORBA or Common Object Request Broker Architecture was designed to allow objects
to communicate transparently over heterogeneous networks. As such, it is an
ideal mechanism for implementing SMI. Functions such as establishing
communications, advertising and finding models, and sending and receiving
messages are either already built into CORBA or are easily implemented using
CORBA. The CORBA directory specified by the configuration switch or default path
should contain bin, lib and include
sub-directories containing the CORBA library files.
The Portable Threads Library (pthreads) is supported by most UNIX operating systems. Using threads, hardware simulation and test threads run within the same process. This implementation is significantly faster than either of the inter-process communication implementations. However, the test threads must run on the same machine as the hardware simulation.
For example, the following configuration command will generate SMI libraries that use a CORBA implementation in directory "/usr/local/mico", disables the default socket implementation and enables the thread implementation.
./configure --enable-corba=/usr/local/mico --disable-socket --enable-threads
SMI supports three widely available Verilog simulators; Icarus Verilog, Synopsys VCS and ModelTech ModelSim SE for Linux. The following table shows the configuration switches required to enable support for a specific simulator. Multiple simulators can be supported.
| Simulator | Configuration Switch | Default Directory | H/W Library | PLI |
|---|---|---|---|---|
| Icarus | --enable-icarus[=ICARUS_DIR] | ICARUS_DIR = /usr/local | smi.vpi | vpi |
| VCS | --enable-vcs | libsmi_hs.a | tf | |
| ModelSim | --enable-modeltech[=MTI_DIR] | MTI_DIR = /usr/local/modeltech | smi.sl | tf |
The table also shows that the build process generates a simulator specific
hardware simulation library and uses both vpi and tf PLI
routines. The software model library libsmi_sm.a is not simulator
specific.
The Icarus and ModelSim directories specified by the configuration switches
and default paths should contain bin, lib and
include sub-directories containing the simulator library files.
For example, the following configuration command will generate SMI libraries that support all three simulators.
./configure --enable-icarus=/usr/icarus --enable-vcs --enable-modeltech
This section describes how to compile and link hardware simulations and test
processes. Compiling test threads into the hardware simulation is covered in a
special section. Our examples assume that the environment variable
SMI_DIR is set to the base directory of the SMI installation,
typically /usr/local.
Test processes execute user code that interacts with the SMI library. The following table lists the SMI header files that the user code can include and the classes they declare.
| Include File | Declarations |
|---|---|
| smi_channel.h | SMI_Channel |
| smi_model.h | SMI_Model |
| smi_message.h | SMI_RxMessage and SMI_TxMessage |
| smi_prototype.h | SMI_Prototype |
| smi_threads.h | SMI_Thread_Routine and smi_thread_routines[] |
To compile a source file that includes one or more of these files, the compiler
must be told the path to the included files. For example, the following command
compiles a user source file test_process.cc passing the include
path with the -I switch.
g++ -c -I$(SMI_DIR)/include test_process.cc
The resulting object files can then be linked with the SMI library to create a
test process executable. As for any executable, The code should define a single
main() procedure. NOTE: Test threads, compiled into the hardware
simulation executable, is discussed later. To link the object files that use
SMI, the linker must be told the path to and name of the SMI library. For
example, the following command create a test executable
test_process by linking the user object file
test_process.o. The library path is passed using the
-L switch. The SMI software model library libsmi_sm.a
name is passed with the -l switch.
g++ -o test_process -L$(SMI_DIR)/lib test_process.o -lsmi_sm
The commands for compiling hardware simulations are different for different simulators. The following table summarizes the compilation commands for hardware simulations without including support for test threads.
| Simulator | SMI Library | Compile Command |
|---|---|---|
| Icarus | smi.vpi
| iverilog -m $(SMI_DIR)/lib/smi -o executable verilog_source_files
|
| Synopsys VCS | libsmi_hs.a
| vcs +cli+2 +acc+2 -o executable verilog_source_files -P $(SMI_DIR)/include/smi.tab $(SMI_DIR)/lib/libsmi_hs.a -lstdc++
|
| ModelSim SE | smi.sl
| vlog verilog_source_files
|
The compilation commands for Icarus and VCS build verilog executables. The compilation command for ModelSim SE compiles the verilog source files into a working directory, the SMI library is linked at runtime.
Support for test threads changes the compilation of test process code and
hardware simulation. It even requires changes the test process code itself. The
main() procedure defined by the test process code must be
recompiled to rename this procedure. The following example code fragment shows
how the main() procedure can be renamed under the control of a
compilation switch -DTHREAD.
#ifdef THREAD int test_thread(int argc, char** argv) #else int main(int argc, char** argv) #endif
In addition to this change, SMI must be able to find all the test thread
routines when executing the hardware simulation. To do this, the user must
define a database that maps a text string to each thread routine. The following
code fragment shows how the test_thread procedure can be associated
with the string "test_thread". The smi_thread_routines array must
be terminated with an empty record {0,0}.
#include "smi_threads.h"
SMI_Thread_Routine
smi_thread_routines[] = {
{"test_thread", test_thread},
{0,0},
};
The following compilation commands show how support for test threads can be
added using Icarus Verilog. The first line recompiles the test process code
renaming main(). The second line creates a new shared library
test_thread.vpi by combining the test process object file and the
SMI library smi.vpi. The last line compiles the hardware simulation
replacing the SMI Library smi.vpi with the new shared library
test_thread.vpi.
g++ -c -I$(SMI_DIR)/include -DTHREAD test_thread.cc g++ -o test_thread.vpi -shared test_thread.o $(SMI_DIR)/lib/smi.vpi -lstdc++ iverilog -m ./test_thread -o hardware_simulation verilog_source_files
The following compilation commands show how support for test threads can be
added using Synopsys VCS. The first line recompiles the test process code
renaming main(). The second line compiles the hardware simulation
adding the test process object file and the SMI software model library.
g++ -c -I$(SMI_DIR)/include -DTHREAD test_thread.cc
vcs +cli+2 +acc+2 -o hardware_simulation verilog_source_files test_thread.o \
-P $(SMI_DIR)/include/smi.tab $(SMI_DIR)/lib/libsmi_sm.a $(SMI_DIR)/lib/libsmi_hs.a -lstdc++
The compilation commands for ModelSim SE are unchanged as the SMI library is
linked at run-time. However, the simulator must now link in a library that also
includes the test thread objects. The following compilation commands show how
this replacement shared library can be built. The first line recompiles the test
process code renaming main(). The second line creates a new shared
library test_thread.sl by combining the test process object file
and the SMI library smi.sl.
g++ -c -I$(SMI_DIR)/include -DTHREAD test_thread.cc g++ -o test_thread.sl -shared test_thread.o $(SMI_DIR)/lib/smi.sl -lstdc++
When running a hardware simulation and test processes, the inter-process communication method and any additional arguments required by that implementation must be passed using command line arguments. This section describes how to run a simulation using each inter-process communication implementation. The following table summarizes the command line options required to simulate with SMI.
| Implementation | Hardware Simulation Switch | Test Process Switch |
|---|---|---|
| TCP/IP Sockets | +socket+port | -socket [host:]port |
| CORBA | +corba+"corba_switches" | -corba corba_switches |
| Portable Threads | +threadnumber+"test_routine [test_switches]" |
Before starting the simulation, the user must select an unused port for socket
communication. The /etc/services file gives a list of ports used by
your system. Once a port is selected, the hardware simulation executable can be
run with a +socket+port argument. The test process or
processes can then be run with a
-socket [host:]port argument. If the test process
is run on a different host from the hardware simulation than the
host: qualifier specifies the host running the hardware
simulation. The port number is the same in both cases.
For Icarus and VCS, the following example starts a simulation. The first line
starts the hardware simulation by invoking the executable
hardware_simulation specifying socket communication via port 2345.
The second line starts a test process by invoking the executable
test_process specifying socket communication via port 2345 of host
"hs_host".
hardware_simulation +socket+2345 test_process -socket hs_host:2345For ModelSim SE, the following example starts a simulation. The first line starts the hardware simulation by running
vsim specifying the top
level module top_module, the SMI library and the port for
socket communication. The second line starts a test process by invoking the
executable test_process specifying socket communication via port
2345.
vsim -c top_module -pli $(SMI_DIR)/lib/smi.sl +socket+2345 test_process -socket 2345
Running a simulation using CORBA is more complicated as CORBA requires additional processes to be running and a more complicated set of switches. For Icarus and VCS, the following commands start a simulation. Please refer to the MICO CORBA documentation for details.
setenv ARGUMENTS "-ORBImplRepoAddr inet:host:2345 -ORBNamingAddr inet:host:2345" micod -ORBIIOPAddr inet:host:2345 --forward & imr create NameService poa nsd "IDL:omg.org/CosNaming/NamingContext:1.0#NameService" $ARGUMENTS hardware_simulation +corba+"$ARGUMENTS" test_process -corba $ARGUMENTSCORBA cannot currently be used with ModelSim SE.
Running a simulation using threads is simple as only a single executable need be
invoked. The hardware simulation is passed one or more +thread
arguments. Each of these arguments specifies a test routine to run in its own
thread and the arguments to pass the routine. Each thread must be consecutively
numbered from 0 up, this number forms part of the argument
+threadnumber+. The remaining part of the argument
specified the test routine and its arguments
"test_routine [test_switches]". The test routine
string must correspond to one of the strings stored in the database
smi_thread_routines[]. The optional
test_switches allow the user to pass the same switches
they could if the test thread was a test process.
For Icarus and VCS, the following example starts a simulation. The simulation begins by spawning a test thread running the test routine associated with the string "test_thread", no arguments are passed to this routine.
hardware_simulation +thread0+test_thread
In this example, two test threads are spawned running test routines associated with the strings "test_thread" and "another_thread". The "test_thread" routine is passed the argument "-switch".
hardware_simulation +thread0+"test_thread -switch" +thread1+another_thread
For ModelSim SE, the following example starts a simulation. The hardware
simulation is started by running vsim specifying the top level
module top_module and the SMI library. The simulation
begins by spawning a test thread running the test routine associated with the
string "test_thread", no arguments are passed to this routine.
vsim -c top_module -pli test_thread.sl +thread0+test_thread
| Backward | Up | Forward |
|---|