Installing and Setting Up XMODEL

This page describes the step-by-step procedure to install the XMODEL package and setup the environment variables on your system.

Installing the XMODEL Package

The XMODEL package is distributed as a single self-extraction shell-script and you can download the latest release from this page.

Currently, XMODEL supports 32-bit and 64-bit RedHat Enterprise Linux (RHEL) version 5 or later. The name of the installation script reflects the version of the XMODEL release and intended OS platform. For instance, the installation script of the YYYY.MM Release for 64-bit Linux is named: xmodel_YYYY.MM_x86_64.sh.

Install the XMODEL package is easy – all you need is to execute the script on the shell prompt.

Note that depending on how you downloaded the installation script, you may have to make the script executable first by using the following command:

chmod +x xmodel_YYYY.MM_x86_64.sh

Then, for an interactive-mode installation, type:

./xmodel_YYYY.MM_x86_64.sh

The script will ask for the installation path, prompts for licensing agreement, etc. and guide the installation process in a friendly way.

On the other hand, for a batch-mode installation (i.e. installing the package in a single step with no questions asked), you can use the following options with the script:

./xmodel_YYYY.MM_x86_64.sh  -b  -p  <XMODEL_INSTALLATION_PATH>

Fill the field with the directory path where you want to install XMODEL. The script will then install the package to your designated installation path without prompting the user.

Setting Up the XMODEL Environments

To run XMODEL, users need to set the following three or four environment variables:

$XMODEL_HOME variable to indicate where XMODEL package is installed.
$PATH variable appended with the $XMODEL_HOME/bin executable directory.
$SALMD_LICENSE_FILE variable defining the license server information.
(Optional) $XMODEL_SIMULATOR variable to specify which Verilog simulator to use (Synopsys® VCS®, MentorGraphics® ModelSim®, or Cadence® NC-Verilog®) with XMODEL.

For bash-like shells, you can use the following commands
(see $XMODEL_HOME/etc/DOT.bashrc for example):

export  XMODEL_HOME=<XMODEL_INSTALLATION_PATH>
export  PATH=${PATH}:${XMODEL_HOME}/bin
export  SALMD_LICENSE_FILE=9524@<LICENSE_HOSTNAME>
export  XMODEL_SIMULATOR=<VERILOG_SIMULATOR>

where the fields and should be replaced with the full path to the XMODEL installation directory and license server hostname, respectively.

The field <VERILOG_SIMULATOR> can be either vcs, modelsim, or ncverilog. If $XMODEL_SIMULATOR environment variable is left undefined, the XMODEL simulator will try to find the simulator installed on your system automatically.

For csh-like shells, you can use the following commands
(see $XMODEL_HOME/etc/DOT.cshrc for example):

setenv  XMODEL_HOME  	 <XMODEL_INSTALLATION_PATH>
setenv  PATH  		 ${PATH}:${XMODEL_HOME}/bin
setenv  SALMD_LICENSE_FILE 9524@<LICENSE_HOSTNAME>
setenv  XMODEL_SIMULATOR <VERILOG_SIMULATOR>

Again, the fields <XMODEL_INSTALLATION_PATH> and <LICENSE_HOSTNAME> should be replaced with the full path to the XMODEL installation directory and license server hostname, respectively. The field <VERILOG_SIMULATOR> can be either ‘vcs‘, ‘modelsim‘, or ‘ncverilog‘.

It is convenient to set these environment variables within the shell start-up scripts (e.g. ~/.bashrc for bash-like shells and ~/.cshrc for csh-like shells) so that they can be properly set every time a new shell is started.

Also, since XMODEL runs on top of a Verilog simulator, it is necessary to set the proper environment variables for the Verilog simulator of your choice. For instance, for Synopsys® VCS®, one needs to set the VCS® installation directory ($VCS_HOME), prepend its executable directory ($VCS_HOME/bin) to the $PATH variable, and define the Synopsys® license path ($SNPSLMD_LICENSE_FILE). Please refer to the user manuals of your Verilog simulator for more details.

XMODEL_LICENSE_WAIT Environment Variable (Optional)

By default, an application program aborts immediately if it cannot check out the required license features. For instance, a feature ‘XMODEL’ is required for running XMODEL simulation. Instead of aborting immediately, you can make the program wait for the next available license for a specified time duration (called ‘license queuing’) by defining the $XMODEL_LICENSE_WAIT environment variable.

The basic usage of this $XMODEL_LICENSE_WAIT environment variable is to enable or disable license queuing. For bash-like shells, you can use the following commands to enable or disable license queuing, respectively:

export  XMODEL_LICENSE_WAIT=yes         # to enable license queuing

export  XMODEL_LICENSE_WAIT=no          # to disable license queuing

And for csh-like shells, you can use the following commands:

setenv  XMODEL_LICENSE_WAIT yes         # to enable license queuing

setenv  XMODEL_LICENSE_WAIT no          # to disable license queuing

A more advanced usage of the $XMODEL_LICENSE_WAIT environment variable is to specify the time period for which the application waits for the next available license. You can define this wait period in units of minutes by assigning an integer value to the $XMODEL_LICENSE_WAIT environment variable. For instance, the following command enables the license queuing and sets the wait period to be 20-minutes for bash-like shells:

export  XMODEL_LICENSE_WAIT=20

The equivalent command in csh-like shells is:

setenv  XMODEL_LICENSE_WAIT 20

Note that setting the wait period to zero is equivalent to disabling license queuing. If you enable license queuing by setting $XMODEL_LICENSE_WAIT to yes, the wait period would be infinite.

Configuring GLISTER on Cadence® Virtuoso®

If you’d like to use GLISTER to graphically compose the analog/mixed-signal models on Cadence® Virtuoso® Schematic Editor and netlist them into XMODEL source codes, you need to perform the following additional steps.

Installing XMODEL Registry Files

GLISTER introduces new viewtypes such as xmodel and tb_xmodel as well as new environment variables and menu interfaces for the GLISTER-ADE integration. To put them into effect, you need to install the XMODEL registry files. There are multiple ways of doing this depending on whether you’re a CAD administrator or an end-user.

If you are a CAD administrator with the write permission into the Cadence® installation directory and you’d like the XMODEL registry files to be effective for all projects using a particular version of Cadence® Virtuoso®, the easiest way is to use the following command to install the XMODEL registry files directly into the Cadence® Virtuoso® installation directory:

$XMODEL_HOME/bin/setup_registry --cdshome $CDSHOME

Here, the $XMODEL_HOME is the environment variable defining the XMODEL installation path and the $CDSHOME is the environment variable defining the installation path of the Cadence® IC package. The older versions of Cadence® IC package (e.g. IC5.1) may use $CDS_INST_DIR instead of $CDSHOME.

An example of running this command is shown below. You may supply an additional --dryrun option to the registry installer script setup_registry to see what actions the script will perform before actually installing the registry files.

$ $XMODEL_HOME/bin/setup_registry --cdshome $CDSHOME
*** setup_registry (XMODEL Release 2018.03 (x86_64))
The XMODEL registry files will be installed into the following Cadence installation directory:
    /cad/cadence/IC_06.17.717

Do you want to proceed? [y/N]: y

Installing the XMODEL registry files...
cp -R /cad/scianalog/xmodel_2018.03/cadence/etc/registry/* /cad/cadence/IC_06.17.717/share/cdssetup/registry/
cp -R /cad/scianalog/xmodel_2018.03/cadence/etc/tools/* /cad/cadence/IC_06.17.717/tools/dfII/etc/tools/

XMODEL registry files are successfully installed.

As of XMODEL Release 2018.03, the registry installer script installs the following four files into the Cadence® installation directory:

$CDSHOME/share/cdssetup/registry/data/xmodel.reg
$CDSHOME/share/cdssetup/registry/tools/xmodel.reg
$CDSHOME/tools/dfII/etc/tools/xmodel/xmodel.cdsenv
$CDSHOME/tools/dfII/etc/tools/menus/xmodel.menus

Note that these files do not interfere with any other parts of the Cadence® software or user customizations. Hence, it is safe to install these files without worrying about affecting your existing customizations.

If you don’t have the administrator privilege to modify the Cadence® installation directory, or if you want the XMODEL registry files to be effective only for a certain project or site, an alternative way is to install the XMODEL registry files into one of the local directories that can be reached by the Cadence® Setup Search File (CSF) mechanism. The local directory can be either your local work directory where you launch Cadence® Virtuoso® from, your home directory ($HOME), project directory ($CDS_PROJECT), or site directory ($CDS_SITE).

Depending on where you install the registry files, the XMODEL registry files will take effects for different range of projects and users. For instance, if you install the registry files into a local work directory, they will be effective only for the Virtuoso sessions started from that directory. On the other hand, if you install them to your home directory, they will be effective for all Virtuoso sessions started by you. If you install them into the directory pointed by $CDS_PROJECT or $CDS_SITE environment variable, they will be effective to everyone who shares the same $CDS_PROJECT or $CDS_SITE setting.

You can use the following command to install the XMODEL registry files into a local directory of your choice. Basically, change into the local directory and execute the setup_registry script with a --local option as below:

cd $CDS_PROJECT or <your cadence work directory>
$XMODEL_HOME/bin/setup_registry --local .

An example of running this command is shown below. Again, you may use an additional --dryrun option to see what actions the registry installer script will perform before actually installing the registry files.

$ cd /home/user/cadence
$ $XMODEL_HOME/bin/setup_registry --local .
*** setup_registry (XMODEL Release 2018.03 (x86_64))
The XMODEL registry files will be installed into the following local directory:
    /home/user/cadence

Do you want to proceed? [y/N]: y

Installing the XMODEL registry files...
mkdir -p /home/user/cadence/menus
cp -RL /cad/scianalog/xmodel_2018.03/cadence/etc/menus/* /home/user/cadence/menus/
cp -L /cad/scianalog/xmodel_2018.03/cadence/etc/xmodel.cdsenv /home/user/cadence/
cp /cad/scianalog/xmodel_2018.03/cadence/etc/data.reg /home/user/cadence/data.reg
cp /cad/scianalog/xmodel_2018.03/cadence/etc/csfLookupConfig /home/user/cadence/csfLookupConfig

XMODEL registry files are successfully installed.

As of XMODEL Release 2018.03, the registry installer script installs or modifies the following four files in the local directory:

xmodel.cdsenv
menus/xmodel.menus
data.reg
csfLookupConfig

For more information about the CSF mechanism or the $CDS_PROJECT and $CDS_SITE directories, please refer to the Cadence® Application Infrastructure User Guide located in $CDSHOME/doc/caiuser/caiuser.pdf.

Editing .cdsinit File

The next step is to configure your Cadence® Virtuoso® environment so that the Virtuoso® Schematic Editor executes the following SKILL commands upon start-up:

; XMODEL/Virtuoso Integration Setup
XMODEL_HOME = getShellEnvVar("XMODEL_HOME")
loadContext( strcat( XMODEL_HOME "/cadence/etc/xmodel.cxt" ) )
callInitProc( "xmodel" )

For instance, you can insert these lines in the site-wide or personal .cdsinit file which is located in the $CDS_SITE directory or in the Cadence® working directory ($CDS_PROJECT), respectively. Note that the shell environment variable $XMODEL_HOME must be defined prior to launching Virtuoso®.

Editing cds.lib File

To access the libraries of the XMODEL primitive symbols and modeling examples, you need to edit your cds.lib file to include the XMODEL-related libraries. Please refer to ${XMODEL_HOME}/cadence/etc/cds.lib for the lines to be inserted in your cds.lib.

One way is to simply include this whole cds.lib file into yours by adding the following line in your local cds.lib file:

INCLUDE ${XMODEL_HOME}/cadence/etc/cds.lib

Or, you can selectively include the libraries by adding the lines individually:

DEFINE xmodel_prims  ${XMODEL_HOME}/cadence/xmodel_prims
DEFINE xmodel_blocks  ${XMODEL_HOME}/cadence/xmodel_blocks

The xmodel_prims and xmodel_blocks libraries are the minimal set of libraries required to use GLISTER.

XMODEL_SIMDIR Environment Variable (Optional)

When GLISTER performs netlisting, it stores the generated model files and other supporting files in the directory defined by the $XMODEL_SIMDIR environment variable.

In a bash-like shell, you can define this environment variable by using the following shell command:

export  XMODEL_SIMDIR=$CDS_PROJECT/xmodel.sim

And in a csh-like shell, you can define it by:

setenv  XMODEL_SIMDIR  $CDS_PROJECT/xmodel.sim

If the $XMODEL_SIMDIR is not defined, the assumed default value is $CDS_PROJECT/xmodel.sim. If $CDS_PROJECT is not defined, then $XMODEL_SIMDIR is defaulted to $HOME/xmodel.sim.

XMODEL_LICENSE_TIMEOUT Environment Variable (Optional)

Using GLISTER features within the Cadence® Virtuoso® Design Environment checks out a GLISTER license feature. The checked-out GLISTER license does not get checked back in unless the user explicitly does so (e.g. by closing the Virtuoso session) or a specified inactivity period elapses.

You can customize this time-out period by defining the $XMODEL_LICENSE_TIMEOUT environment variable. For instance, using the following shell command in a bash-like shell defines the time-out period as 240 minutes (i.e., 4 hours):

export  XMODEL_LICENSE_TIMEOUT=240

The equivalent command in a csh-like shell is:

setenv  XMODEL_LICENSE_TIMEOUT  240

If you prefer setting the time-out period in the .cdsinit file, you can define a SKILL variable named xmodelLicenseTimeOut with the desired time-out period in minutes after the XMODEL/GLISTER context file is loaded:

; XMODEL/Virtuoso Integration Setup
XMODEL_HOME = getShellEnvVar("XMODEL_HOME")
loadContext( strcat( XMODEL_HOME "/cadence/etc/xmodel.cxt" ) )
callInitProc( "xmodel" )

xmodelLicenseTimeOut = 240

If neither the $XMODEL_LICENSE_TIMEOUT environment variable nor the xmodelLicenseTimeOut SKILL variable is defined, the default time-out period of 24 hours (i.e., 1440 minutes) is assumed.

Additional Configuration for MODELZEN

If you wish to use MODELZEN from Cadence® Virtuoso® Schematic Editor using the GLISTER interface, you may need to perform some additional setups:

Override MODELZEN-related GLISTER default options if necessary
Configure how MODELZEN extracts circuit netlists from schematic cellviews (modelzenGenNetlist())

Overriding MODELZEN-related GLISTER Default Options

GLISTER provides some MODELZEN-related options that control the ways GLISTER executes MODELZEN within Cadence® Virtuoso®. These options can be modified from the Set MODELZEN Options dialog box that opens when selecting the GLISTER->Set MODELZEN Options menu from the Cadence® Virtuoso® Schematic Editor window.

Figure 1. The dialog box for setting MODELZEN options.

For instance, the Netlist Simulator field sets the format of the circuit netlist to be extracted from the schematic cellview and the Technology Configuration File field sets the default technology configuration file to be used by MODELZEN. Please refer to the MODELZEN User’s Guide for more detailed descriptions on each of these options.

One can override the default values of the MODELZEN-related GLISTER options by overriding the values of the SKILL variables that correspond to these options after loading the XMODEL/GLISTER context file. An excerpt of the Cadence® Virtuoso® initialization file .cdsinit that overrides some of the MODELZEN-related GLISTER options is listed below. The first part initializes the XMODEL/GLISTER interface for Cadence® Virtuoso® as previously explained in Section 3. The second part redefines some SKILL variables with a prefix modelzen to override the default values of the MODELZEN-related GLISTER options.

; XMODEL/Virtuoso Integration Setup
printf( "Loading XMODEL/Virtuoso Integration...\n" )
XMODEL_HOME = getShellEnvVar("XMODEL_HOME")
loadContext( strcat( XMODEL_HOME "/cadence/etc/xmodel.cxt" ) )
callInitProc( "xmodel" )

; MODELZEN options (NOTE: must come after context file loading)
modelzenDefaultModelView = "xmodel"
modelzenDefaultConfigFile = "./tech_config.py"
modelzenDefaultRunDir = "./modelzen.run"
modelzenDefaultNetlistSimulator = "hspiceD"
modelzenSubModulePrefix = "SUB_%CELLNAME%_"
modelzenShowOptionDialog = t

Table 1 lists the names of the SKILL variables that define the default values of the MODELZEN-related GLISTER options shown in Figure 1.

Table 1. Listing of the SKILL variables setting the default values of the MODELZEN-related GLISTER options.

Option Name	Corresponding SKILL Variable Name
Netlist Simulator	`modelzenDefaultNetlistSimulator`
Technology Configuration File	`modelzenDefaultConfigFile`
Viewname of Generated Models	`modelzenDefaultModelView`
Run Directory	`modelzenDefaultRunDir`
Log File	`modelzenDefaultLogFile`
Confirm Options Before Generating Models	Set `modelzenShowOptionDialog` as t to select this flag
Save MODELZEN Properties in Compact Form	Set `modelzenIncludeAllPinInfo` as nil to select this flag
Use Aggregate Ports for Models	Set `modelzenUseAggregatePorts` as t to select this flag
Include Submodules in Generated Models	Set `modelzenSubModulePrefix` with any string to select this flag; setting it as nil unselects this flag
Submodule Prefix	`modelzenSubModulePrefix`

Configure How MODELZEN Extracts Circuit Netlists from Schematic Cellviews

Running MODELZEN using the GLISTER interface involves extracting a circuit netlist from the schematic cellview. If your design environment uses a customized procedure or interface for extracting SPICE or Spectre netlists from the schematic cellview, you may need to redefine a SKILL procedure named modelzenGenNetlist() in order for MODELZEN to use the same steps when extracting the circuit netlists.

The usage format of the SKILL function modelzenGenNetlist() is shown as below:

modelzenGenNetlist( libName cellName viewName simulator )

The function takes four arguments libName, cellName, viewName, and simulator where libName, cellName, and viewName are the library, cell, and view names of the design cellview to be netlisted and simulator is the name of the Cadence® netlist simulator that determines the format of the netlist (e.g. hspiceD, spectre, and cdl). The function then extracts a netlist from the cellview and returns the full path to the extracted netlist file.

To redefine the modelzenGenNetlist() function, one may need to know the basics of SKILL programming and specific steps required for netlisting in her or his design environment. Please refer to the appropriate Cadence® documentations, or consult your PDK providers or CAD administrators in case you need further help.

The following codes show the default modelzenGenNetlist() function which is defined when the XMODEL/GLISTER context file is first loaded. It extracts the netlist using the Cadence® Analog Design Environment (ADE) SKILL functions such as simulator(), design(), and createNetlist(). If you can extract netlists from your schematic cellview using the standard ADE interface, it is likely that you do not need to redefine modelzenGenNetlist().

; modelzenGenNetlist( libName cellName viewName simulator ):
; generates the 'simulator' netlist of a cellview and
; returns the full filepath of the generated netlist
procedure( modelzenGenNetlist( libName cellName viewName simulator )
    let( ( netlistFile netlistDir )
        ; initialize simulator
        simulator( simulator )

        ; generate netlist
        design( libName cellName viewName )
        unless( netlistFile = createNetlist( ?recreateAll t ?display nil )
            error( "error occurred while netlisting %s.%s:%s."
                    libName cellName viewName )
        )
        ocnCloseSession()

        ; return netlist filename
        netlistDir = xmodelGetDirName( netlistFile )
        strcat( netlistDir "/netlist" )
    )
)

Testing with Examples

To check whether the installation has been done successfully, use the following commands to execute a testbench for a charge-pump PLL example. For more information on the charge-pump PLL model itself and detailed description on the testbenches, please refer to the documentation titled Simulating Charge-Pump PLL in XMODEL.

unix> mkdir ~/xmodel
unix> cp -R $XMODEL_HOME/example ~/xmodel
unix> cd ~/xmodel/example/cp_pll/tb/tb_locking
unix> make tb_locking
unix> xwave -a xmodel.jez

The execution is successful if the simulation is run without errors and the last command pops-up a window displaying waveforms as shown below.

Figure 2. Locking transient simulation of a charge-pump phase-locked loop.

Disclaimer:
All the trademarks used in this page are the property of their respective holders.