SIMetrix Extensions

In this topic:

In an Ideal World...

While that is our idealistic intention, reality never allows ideals. Verilog-A has quite a few little limitations that we would not want to impose on our users. Some of these we have already addressed and made non-standard extensions to do so. These are detailed below.

We will endeavour in the long run to make such extensions in a manner that would allow a source file to work with other Verilog-A simulators without modification.

Instance Parameters

The Verilog-A language does not distinguish between instance parameters and model parameters. An instance parameter is one that can be defined on the device line on a per instance basis whereas a model parameter is one defined in a .MODEL statement. The most flexible implementation is one that allows both, with the instance parameter taking precedence if both are specified by the user. However this method has a cost in terms of increased memory usage per instance. While memory consumption may not seem to be a big issue, it can impact on performance. The less memory used, the more likely that the processor will find what it wants in the cache. For this reason it is desirable to minimise the number of instance parameters.

The SIMetrix Verilog-A implementation provides two methods of defining instance parameters: one in the verilog-A source file and the other on the command line of va.exe which in turn can be passed from .LOAD.

To define an instance parameter in the .VA file, prefix the parameter key word with the special attribute 'type' with a value of "instance". This is how it should look:

(* type="instance" *) parameter a = 1 ;

To define on .LOAD, add the parameter "instparams=parameter_list" where parameter_list is a comma separated list of parameter names.

If a parameter is defined as an instance parameter, it will also be available as a model parameter. If both are specified, the instance value will take precedence.

Boolean Parameters

There is no boolean type in the Verilog-A language and so this data type must be implemented using integer values. SIMetrix and SPICE generally offers a boolean parameter type whereby the value is defined as TRUE if the parameter is present and FALSE if the parameter is not present. The parameter is not assigned a value. It is possible to define a parameter with this type by providing the special attribute format and assigning it a value of "flag". For example:

(* type="instance", format="flag" *) parameter integer OFF=0 ;

In the following instance line, the OFF parameter will have a value of 1:

U1 n1 n2 n3 modelname OFF

Note that the parameter type must be defined as integer; the attribute will be ignored if any other type.

This feature is not part of the Verilog-A language and will be ignored by other simulators.

SPICE compatibility

Verilog-A defines a number of features that allow interfacing between the SPICE simulator and Verilog-A code. SIMetrix implements the ability to instantiate a SPICE device in a Verilog-A module as defined in the LRM 2.4, sections E.2.2.3 and E.3.

LRM 2.4 Features Supported

SIMetrix Verilog-A supports all primitives as described in Table E.1 of LRM 2.4 with the following exceptions and differences

  • vsine, isine: parameters supported: dc, mag, phase, offset, ampl, freq, td, sinephase. Other parameters not supported. Additionally supports theta parameter which implements an exponential decay
  • diode, bjt, mosfet and jfet implement level 1 devices by default. Add a LEVEL parameter to specify other models.

Additional SPICE Devices

The SIMetrix device internal device name may be used to specify any device type. For a list of available internal names run the built-in script show_devices from the SIMetrix command line. This will copy to the clipboard a complete list. The name in the first column may be used provided your license supports it. Note that digital devices may not be used.

Output Variables

Output variables are values that can be plotted and are also listed in the .out file if ".op" or ".options opinfo" is specified in the netlist. Further, they can be accessed using the $simprobe function.

Normal real-valued variables may be defined as output variables by prefixing the definition with a special attribute. The full form is:

(* op="yes" *)real varname ;
Optionally, units may also be defined:
(* op="yes", units="units" *)real varname ;
Where units is one of:
  • "V"
  • "A"
  • "Secs"
  • "Hertz",
  • "Ohm",
  • "Sie",
  • "F",
  • "H",
  • "J",
  • "W",
  • "C",
  • "Vs",
  • "V^2",
  • "V^2/Hz",
  • "V/rtHz",
  • "A^2",
  • "A^2/Hz",
  • "A/rtHz",
  • "V/s",
  • "Celsius"
  • "coul"
  • ""

description is an arbitrary description of the variable. Note that description is currently unused.

If either description or units is present, the variable will be marked as an output variable.

To plot an output variable, add a .GRAPH statement to the netlist (or F11 window) in the form:

.GRAPH instance_ref#variable_name

Alternatively to instruct SIMetrix to save the data for the output variable without immediately plotting it, use ".KEEP" instead of ".GRAPH".

Device Mapping

You may control how the new device is represented in SIMetrix using a device mapping. This does the same as the sxcfg file. Mappings are applied as a module attribute in the form:

(* Mappings="mapping_defs" *)

This should prefix the "module" keyword.

mapping_def is a semi-colon delimited list of mapping definitions. Each mapping definition is itself a comma delimited list of attibutes in the following order:

model-type-name,level-number,device-letter,default-parameter,version

Where:
model-type-name The name used in the .MODEL statement.
level The LEVEL parameter value in the .MODEL statement.
device-letter The device letter to use for this device.
default-parameter A single parameter name and value. This is intended to be used to define device polarity. E.g. "pnp=1" might define a PNP BJT. This is useful to allow the definition of BJTs and MOS devices using conventional NPN/PNP or NMOS/PMOS model type names.
version Value of VERSION parameter.

For example, the HICUM device is defined with the following mapping:

(* Mappings="hicum_211,0;npn,8,Q,pnp=0,;pnp,8,Q,pnp=1," *)

This has three mappings. You can use hicum_211 with no level parameter to define a model. In this case the pnp parameter would need to be set for a PNP device. Alternatively you can use NPN as a model type name along with LEVEL=8 for an NPN device, or PNP with LEVEL=8 for a PNP device.

Device Binning

Some process development kits (PDK) for IC development use multiple models to define a single transistor type. Different models are selected according to specific instance parameters. This is known as "binning". Traditionally the selection parameters have been length and width (L) and (W) with model parameters LMIN, LMAX, WMIN and WMAX used to define the range of values allowed for each model bin.

SIMetrix Verilog-A supports model binning. The parameters L, W, LMIN, LMAX, WMIN and WMAX will automatically be used for binning if the parameters are defined in the Verilog-A code.

Other parameters may also be defined using a module attribute. This should follow the following format:

(* binparams=binparams_defs *)

This should prefix the "module" keyword.

binparams_defs is a semi-colon delimited list of bin parameter definitions. Each bin parameter definition must consist of three parameter names separated by commas. The first is the instance parameter name (e.g. L) and the remaining two parameters the minimum and maximum model parameter names (e.g. LMIN and LMAX).

The traditional , W, LMIN, LMAX, WMIN and WMAX bin parameters can be defined thus:

(* binparams="L,LMIN,LMAX;W,WMIN,WMAX" *)

Note any bin parameters defined using the above technique will override the built-in L and W definitions. Note also that the actual parameters used must be defined in the Verilog-A code with the bin selection parameter (L and W) defined as an instance parameter and the limit parameters defined as model parameters.

Schematic Symbol

When using a Verilog-A module in the schematic editor, a symbol for the module will be needed. The usual method is to invoke the menu Verilog > Construct Verilog-A Symbol. This menu auto-generates a symbol based on a simple specification that defines the edge for each pin.

It is possible to decorate the module statement using Verilog-A attributes to control the symbol generation. Two options are available:

  • Specify a library symbol instead of an auto-generated symbol. This is useful for modules that define a semi-conductor component such as a diode or transistor. It can also be used to pre-define a specialised symbol \\
  • Define the pin positions so as to bypass the GUI that requests this information when the auto-generate menu is invoked

Specify Library Symbol

To specify a library symbol to be used with a Verilog-A module, add a module attribute with name "symbol" with a value giving a list of symbol names separated by a semicolon:

(* symbol="list-of-symbols" *)module module_name(ports) ;
For example:
(* symbol="npn" *)module bjt_va(c, b, e) ;

In the above, the symbol for the NPN transistor will be used to represent the bjt_va module when the menu Verilog > Construct Verilog-A Symbol is invoked.

More than one symbol can be specified in which case the user will be asked which one to use each time the module is placed. For example:

(* symbol="npn;pnp" *)module bjt_va(c, b, e) ;

will offer the NPN and PNP transistor symbols.

To be able to use a library symbol for a Verilog-A module, the following properties must either be not present on the symbol, or if they are they must be not protected:

MODPARAMS  
MODULENAME  
TEMPLATE  
VAFILE  
VALUE  
VALUESCRIPT  
VAOPTIONS

 

About 75% of the symbols in the standard library satisfy this requirement.

The following table lists a number of standard symbols that may be used for various parts. Note this is just a selection; use the Symbol Manager to explore the entire symbol library.

Symbol name Description Pins
and2 2-input AND gate IN1,IN2,OUT
and3 3-input AND gate IN1,IN2,IN3,OUT
cap_simple_subckt Capacitor p,n
dio Junction diode p,n
diode_schottky Schottky diode p,n
igbt_2 IGBT (no diode) c,g,e
igbt_with_diode IGBT (with diode) c,g,e
ind_simple_subckt Inductor p,n
isrc Fixed current source p,n
mov Varistor p,n
nand2 2-input NAND gate IN1,IN2,OUT
nand3 3-input NAND gate IN1,IN2,IN3,OUT
njfet N-channel Junction FET d,g,s
nmf Gaas FET d,s,g
nmos 4 terminal NMOS d,g,s,b
nmos_2gate 2-gate NMOS s,d,g2,g1
nmos_depletion 4 terminal NMOS depletion type d,g,s,b
nmos_sub 3 terminal NMOS d,g,s
nmos_thermal_5 5 terminal thermal NMOS drain,gate,source,Tj,Tcase
nor2 2-input NOR gate IN1,IN2,OUT
nor3 3-input NOR gate IN1,IN2,IN3,OUT
npn NPN Transistor c,b,e
npn_darl NPN darlington c,b,e
npns 4 terminal NPN (with substrate) c,b,e,s
opamp 5 terminal opamp inp,inn,vsp,vsn,out
or2 2-input OR gate IN1,IN2,OUT
pjfet P-channel Junction FET d,g,s
pmos 4 terminal PMOS d,g,s,b
pmos_thermal_5 5 terminal thermal PMOS drain,gate,source,Tj,Tcase
pnp PNP Transistor c,b,e
pnp_darl PNP darlington c,b,e
pnps 4 terminal PNP (with substrate) c,b,e
res Resistor (box shape) p,n
resz Resistor (z shape) p,n
scr Thyristor A,G,K
switch Voltage-controlled switch P,N,CP,CN
triac Triac MT2,G,MT1
Triode Thermionic triode with heater Anode,Grid,Cathode,Heat1,Heat2
ujt Uni-junction transistor B2,E,B1
varactor Varactor (voltage dependent capacitor) p,n
vsrc Fixed voltage source p,n
zener_s Zener diode p,n

To use any of the symbols listed above add the attribute as described. The module port names and their order needs to be considered. The symbol will work correctly when assigned by the menu if either of the following is satisfied:

  • The port names match the symbol's pin names exactly
  • The port names are in the same order as the symbol's pin names (as listed in the above table)

In practice it is best that both are satisfied. However, changing port names for a Verilog-A module that is already written is potentially error-prone and in this case, just making sure they are in the same order as the symbol's pins will suffice.

Specify Pin Positions

When an explicit symbol is not specified, the Verilog > Construct Verilog-A Symbol menu will auto-generate a symbol. Without any attributes defined a simple dialog will be displayed asking the user to specify on which edge each pin should be located. Rather then imposing the user with this task, it is possible to define pin locations as module attributes.

(* pins="list-of-pin-locations" *)module module_name(ports) ;

Where list-of-pin-locations is a semicolon-separated list of the letters L,R,T and B representing respectively "Left", "Right", "Top" ansd "Bottom". There should be one letter for each module port. For example:

(* pins="L;L;T;B;R" *)module va_opamp(inp,inn,vcc,vee,out) ;

The above will place the inp and inn pins on the leftm the vcc pin at the top, the vee pin at the bottom and the out pin on the right.

Tolerances

The Verilog-A language only allows for absolute tolerances to be hardwired in the VA source file. This means for example, that absolute current tolerance, must be specified as a fixed constant which cannot be changed in the .OPTIONS line or anywhere else.

SIMetrix provides a workaround for this using the special values $abstol, $vntol, $chgtol and $fluxtol. These can be used to define absolute tolerances in electrical nature definitions. These are already used in the standard discipline header files supplied with the SIMetrix Verilog-A compiler.

Analysis() Function

Additional analyis types:

  • "sens" sensitivity analysis
  • "tf" transfer function analysis
  • "pta" pseudo-transient analysis
  • "smallsig" small signal analysis
  • "rtn" real time noise analysis

$simparam() Function

Standard types supported by SIMetrix:

  • "gdev"
  • "gmin"
  • "simulatorSubversion"
  • "simulatorVersion"
  • "sourceScaleFactor" - includes pseudo transient scale factor
  • "tnom"

Additional SIMetrix extensions:

"ptaScaleFactor" - as "sourceScaleFactor" but functional in pseudo transient analysis only. Default = 1.0.

In addition you can specify any option setting defined using .OPTIONS. E.g. $simparam("reltol") will return the value of the RELTOL option.

$fopen() Function

Use the argument "<listfile>" to write to the list file. This is the file created by every simulation with the extension .OUT.

Special Parameters

$model_dir

The special string parameter $model_dir returns the full file system path of the directory containing the file which defines the .MODEL statement associated with a Verilog-A instance. This can be used to locate files that are expected to be in the same folder such as data files for table models. The path returned will use UNIX-style forward slashes as a directory separator and includes a trailing '/'.

Note that this is non-standard and will return an error with other Verilog-A implementations or SIMetrix versions 9.0 or earlier. If using in a Verilog-A module that needs to be compatible with other implementations then use the pre-defined macro __VAMS_SX_VERSION_GE_910 to selectively compile lines that use that parameter.