Backward Up Forward

2.4 Using SMI

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.

2.4.1 Building the SMI Library

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 SMI
To select the correct configuration options, we must answer three questions:
  1. Where should SMI be installed? In /usr/local (the default location) or somewhere else?
  2. Which inter-process communication methods need to be supported? Sockets, CORBA or threads?
  3. Which Verilog simulators need to be supported? Icarus, VCS or ModelSim?

Installation Directory

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

Inter-process Communication

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

Simulator Support

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

2.4.2 Compiling with the SMI Library

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

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

Hardware Simulation

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.

Test Threads

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++

2.4.3 Simulating with the SMI Library

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]"

TCP/IP Sockets

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:2345
For 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

CORBA

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 $ARGUMENTS
CORBA cannot currently be used with ModelSim SE.

Portable Threads

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
© Copyright 2000-2001 Adrian Lewis