XSPICE Extensions

Introduction to Using Code Models in Circuits

  Vin 1 0 DC 0 AC 0 SIN 0 2 50
  A1 1 2 foo
  .model foo gain(in_offset=0 out_offset=0.5 gain=2)
  Rout 2 0 1k

  out=gain*(in+in_offset)+out_offset                     (eq. 1)

There are 4 things you must know about code models:

1. The device letter for code models is A.
2. Code model instances have no instance parameters
   Instance parameters are parameters you provide on the line where the instance is described (in our case 'A1 1 2 foo'). A1 is in our case an instance of model 'foo' whose behaviour is described by the 'gain' code model and its parameter values. An example for an instance parameter is the resistance for a resistor.
3. Code models have only model parameters
   Model parameters are given on a '.MODEL' line. In our case the model name is 'foo' and the code model to use for 'foo' is 'gain'. Values for model parameters for the 'foo' model are given in the .MODEL line.
4. Code model instances can be connected with the rest of the circuit in many different ways. The allowed ways to connect a code model instance to the circuit are compiled in the code model. You can see them by inspecting the .ifs file for that specific code model. Details are described in the next two sections of this document. In our example we used the simplest possible way to connect the code model instance with the rest of the circuit.

Code Model Interface Specification (.ifs) File

The .ifs file for the gain code model (gain.ifs) is as follows:

NAME_TABLE:
C_Function_Name:       cm_gain
Spice_Model_Name:      gain
Description:           "A simple gain block"

PORT_TABLE:
Port_Name:             in                 out
Description:           "input"            "output"
Direction:             in                 out
Default_Type:          v                  v
Allowed_Types:         [v,vd,i,id,vnam]   [v,vd,i,id]
Vector:                no                 no
Vector_Bounds:         -                  -
Null_Allowed:          no                 no

PARAMETER_TABLE:
Parameter_Name:     in_offset           gain  
Description:        "input offset"      "gain"
Data_Type:          real                real  
Default_Value:      0.0                 1.0   
Limits:             -                   -     
Vector:             no                  no   
Vector_Bounds:      -                   -    
Null_Allowed:       yes                 yes   

PARAMETER_TABLE:
Parameter_Name:     out_offset
Description:        "output offset"
Data_Type:          real
Default_Value:      0.0
Limits:             -
Vector:             no
Vector_Bounds:      -
Null_Allowed:       yes

• NAME_TABLE section provides some general information about the CM:
  • C_Function_Name
    This is the name of the C function in the .mod file which is actually the one describing the CM's behaviour. This function does the initialisation and output calculations for a CM.
  • Spice_Model_Name
    This is probably the most imortant part of the NAME_TABLE section. This is the name of the CM. You use this name to refer to the CM on the .MODEL line when defining a model and its parameters.
  • Description
    This description is printed when you execute the siminfo command. Note that the description is quoted.
• PORT_TABLE section provides information about CM's ports used for connecting a CM instance with the rest of the circuit. In case there are too many ports to fit them on one line, they can be split into multiple PORT_TABLE sections. Ports appear on the A line describing a CM instance in the same order as they appear in the .ifs file (see gain.ifs).
  • Port_Name
    This is the name of the port.
  • Description
    This is the description of the port. Note that it is quoted.
  • Direction
    Direction can be one of in, out or inout. For instance the inout direction is used for the resistive port of the smooth transition analog switch CM.
  • Default_Type
    XSPICE supports various connection types for a port. For instance you can connect the input of a gain CM instance as a voltage input or as a current input. The default type is the assumed connection type if you don't provide a port type modifier on the A line when describing a CM instance. See the the connection types table in the next section for details on available connection types.
  • Allowed_Types
    As mentioned before, a CM's port can be connected to the rest of the circuit in many different ways. This field specifies which connection types are allowed for a CM's port. The Allowed_Types field must be a blank or comma separated list of type names delimited by square brackets ([v,vd,i,id] or [d]).
  • Vector
    A port can be a vector. A vector port can be thought of as a bus. Valid values for this field are YES, NO, TRUE and FALSE. Values YES and TRUE specify that this port is a vector port. Vector ports must have a corresponding vector bounds field that specifies valid sizes of the vector port.
  • Vector_Bounds
    Specifies valid sizes for a vector port. This field must be a comma or blank separated pair of integer values delimited by square brackets ([1 9] or [1, 9]). The first value specifies the minimal number of elements and the second value the maximal number of elements. In case you don't want an upper limit on the vector size, you can use hyphen for the maximal size ([5, -]). If the range is unconstrained or the port is not a vector, the vector bounds can be specified by a hyphen value (-).
  • Null_Allowed
    In some cases it is allowed to leave a port unconnected to any electrical node in the circuit. In such cases a 'null' connection can be made. An example of a 'null' connection is when you want to leave the 'set' input of a jk flip-flop unconnected. This field specifies if it is legal to leave the port unconnected. Allowed values for this field are YES, NO, TRUE and FALSE.
• PARAMETER_TABLE section provides information about CM's parameters. As with ports in PORT_TABLE sections, parameters can also be split in multiple PARAMETER_TABLE sections.
  • Parameter_Name
    This is the parameter name that is used on the .MODEL line in the netlist.
  • Description
    This is the parameter description. Note that it is quoted.
  • Data_Type
    This is the data type for the parameter. It can be one of boolean, complex, int, real, string.
  • Null_Allowed
    This is a boolean field that specifies wheather the parameter may be ommited on the .MODEL line. If the parameter is ommited, the default value is used. If there is no default value, an undefined value is passed to the CM and the PARAM_NULL() macro will return a value of "TRUE" so that defaulting can be handled within the model itself at runtime. If Null_Allowed is "FALSE" or "NO", the simulator will flag an error if the parameter is ommited on the corresponding .MODEL line. Allowed values for this field are YES, NO, TRUE and FALSE.
  • Default_Value
    If Null_Allowed is "TRUE" for this parameter, then a default value may be specified. This value is used if the parameter is not specified on the corresponding .MODEL line. The default value must be of the correct type. If the parameter is a vector, the default value applies to all elements of the vector. Initialization of separate vector componenets is not supported. In case a parameter is a vector and Null_Allowed is true, the Vector_Bounds parameter must be set to a vector port name whose length defines the length of the vector parameter. If you don't wan't to specify a vector port to asociate with the vector parameter, you must leave the Default_Value field empty (-) and take care of parameter defaulting in the .mod file where you detect the case when a parameter is not specified by using the PARAM_NULL(paramname) macro.
  • Limits
    Integer and real parameters may be constrained to accept only a limited range of values. A range is specified by two numbers in square brackets ([-1.1, 9.9]). The first value represents the lower bound and the second value the upper bound. The lower and upper bounds are inclusive. Either the lower or upper bound may be replaced by a hyphen ('-') ([-, 0.1] or [-9, -]). A hyphen indicates that the bound is unconstrained. For a totally unconstrained range a single hyphen without surrounding brackets may be used (-).
  • Vector
    A parameter can also be a vector. Allowed values for this field are YES, NO, TRUE and FALSE. Vectors are specified in square brackets. Elements must be blank or comma delimited.
  • Vector_Bounds
    This field has the similar meaning as the Vector_Bounds field for ports. The bounds are specified in the similar manner as the limits in the Limits field for a parameter. Instead of using a numeric range in square brackets a port name may be used. The port must be a vector port. In this case the size of the vector parameter must be the same as the size of the associated vector port.
• STATIC_VAR_TABLE section provides information about CM's static variables. This part is only important if you are writing a .mod CM description file. Static varibles can also be split into multiple STATIC_VAR_TABLE sections.
  • Name
    This is the name for the static variable. It must be a valid C identifier.
  • Description
    This is the description of the static variable. It must be enclosed in quotes.
  • Data_Type
    This is the data type for the static variable. It must be one of boolean, complex, int, real, string or pointer. Pointer type is used for tables (matrix, vector, ...). The space for the table must be malloced during the initialisation cycle of the CM in the .mod file.

Using Code Models

Input (in type) analog port connections

Modifier	Instance example	Explanation	Schematic
%v	Again1 %v(in) out gain_model	The input of the Again1 istance is the voltage of node 'in'.
%vd	Again1 %vd(in1 in2) out gain_model	The input of the Again1 instance is the voltage between nodes 'in1' and 'in2' (v(in1)-v(in2))
%i	Again1 %i(in) out gain_model	The input of the Again1 instance is the current that flows out from node 'in' and through the instance into the ground node. The input resistance of the instance is 0.
%id	Again1 %id(in1 in2) out gain_model	The input of the Again1 instance is the current that flows out from node 'in1' and throuh the instance into node 'in2'. The input resistance of the instance is 0.
%vnam	Again1 %vnam(V1) out gain_model	The input of the Again1 instance is the current that flows through independent voltage source V1.

Output (out type) analog port connection

Modifier	Instance example	Explanation	Schematic
%v	Again1 in %v(out) gain_model	The output of the Again1 istance is a voltage source voltage with + pole at node 'out' and - pole at ground node.
%vd	Again1 in %vd(out1 out2) gain_model	The output of the Again1 istance is a voltage source voltage with + pole at node 'out1' and - pole at node 'out2'.
%i	Again1 in %i(out) gain_model	The output of the Again1 instance is a current source current. The current flows from node 'out' through the source into the ground node.
%id	Again1 in %id(out1 out2) gain_model	The output of the Again1 instance is a current source current. The current flows from node 'out1' through the source into node 'out2'.

Bidirectional (inout type) analog port connections

Modifier	Instance example	Explanation	Schematic
%g	Axind %g(inout) xind_model	The voltage at node 'inout' is taken as input. Effectively the Axind instance works in this case as a voltage controlled current source. It generates an output current flowing from node 'inout' into ground node. Note that a %g port is a bidirectional port (input and output at the same time).
%gd	Axind %gd(inout1 inout2) xind_model	The voltage between nodes 'inout1' and 'inout2' (v(inout1)-v(inout2)) is taken as input. Effectively the Axind instance works in this case as a voltage controlled current source. It generates an output current that flows out from node 'inout1' and back into node 'inout2'. Note that a %gd port is a bidirectional port (input and output at the same time).
%h	Axcap %h(inout) xcap_model	The current flowing out from node 'inout' and through the instance into ground node is taken as input. The input resistance of the instance is 0. Effectively the Axcap instance works in this case as a current controlled voltage source. It generates an output voltage with its + pole at node 'inout' and - pole at ground node. Note that a %h port is a bidirectional port (input and output at the same time).
%hd	Axcap %hd(inout1 inout2) xcap_model	The current flowing out from node 'inout1' and through the instance into node 'inout2' is taken as input. The input resistance of the instance is 0. Effectively the Axcap instance works in this case as a current controlled voltage source. It generates an output voltage with its + pole at node 'inout1' and - pole at node 'inout2'. Note that a %hd port is a bidirectional port (input and output at the same time).

Input or output (in or out type) event-driven port connections

Modifier	Instance example	Explanation	Schematic
%d	Ainv %d(in) %d(out) inv_model	This is a digital port. It can be connected to digital nodes only.
%UDN	Ad2r %d(in) enable %real(out) d2r_model	A port modifier for a user defined node (UDN). First port of instance Ad2r is connected to node 'in' which must be digital. Second port is connected to node 'enable' using the default connection type for the second port. Third port of instance Ad2r is connected to node 'out'. Node 'out' must be a real UDN.

Vector connections
Vector connections are parallel connections of multiple nodes to a certain port of a CM. Of course such connections must be supported by the CM. A typical vector connection is the connection of multiple analog nodes to the input port of the adc_bridge CM. Of course the output port of the adc_bridge must have the same number of digital nodes connected. Let's take a look at an example of a vector connection:

  Aadc1 [n_a1 n_a2 n_a3 n_a4] [n_d1 n_d2 n_d3 n_d4] adc_model1

Inverting a digital input/output
You can invert a digital node value before it is passed to the CM input. This is achieved by placing a tilde before the node name. The example inverts the first input of the and gate:

  Aand1 [~in1 in2] out and_model1

  Aand1 [in1 in2] ~out and_model1

null connections
Inputs or outputs of CMs can be left unconnected. This is specified using the node name 'null'. In case you use the name 'null' on a builtin SPICE device it will be interpreted as node name 'null' and not as a null connection. Example leaves the set and reset inputs and the Nout output of a jk flip-flop unconnected:

  Aff1 jnode knode clknode null null out null jkff_model1

Model parameters
Model parameters for a code model are specified the same way as model parameters for other models. Vector type parameters must be given in square brackets:

  .MODEL laplace_s_xfer1 s_xfer(num_coeff=[1 0 0] den_coeff=[1 2 1] 
  +                             denormalized_freq=1000)

Netlist examples
In case a port modifier is placed in front of square brackets it is valid for all nodes inside brackets i.e. for all vector elements. The example specifies two differential voltage connections (1,2) and (3,4) as elements of a vector port. The vector port has length 2 in this case.

  Avec %vd [1 2 3 4]

  Avec %v [1 2 %vd 3 4]

  Avec %v [1 2 %vd(3 4)]

  a1 1 2 amp
  .MODEL amp gain(in_offset=0.1 gain=5.0 out_offset=-0.01)

  a2 %i[2 3] 2 sum1
  .MODEL sum1 summer(in_offset=[0.1 -0.2] in_gain=[2.0 1.0] 
  +                  out_gain=5.0 out_offset=-0.01)

  a21 %i[1 %vd(2 5) 7 10] 3 sum2
  .MODEL sum2 summer(out_gain=10.0)

  .MODEL xfer_1 pwl(x_array=[-2.0 -1.0 2.0 4.0 5.0]
  +                 y_array=[-0.2 -0.2 0.1 2.0 10.0]
  +                 input_domain=0.05 fraction=TRUE)

  a4 3 %gd(6 7) switch3
  .MODEL switch3 aswitch(cntl_off=0.0 cntl_on=5.0 r_off-1e6 
  +                      r_on=10.0 log=TRUE)