PREV UP NEXT

# SYMBOL PROPERTY SYNTAX

### GENERAL RULES

For symbols a global property string (to show it press `'q'` when nothing is selected and `Options->Symbol global attrs` is selected) defines at least 3 attributes:

- `type` defines the the type of symbol. Normally the type attribute describes the symbol and is ignored by XSCHEM, but there are some special types:

- `subcircuit`: the symbol has an underlying schematic representation, when producing the netlist XSCHEM has to descend into the corresponding schematic. This will be covered in the subcircuits chapter.
- `primitive`: the symbol has a schematic representation, you can descend into it but the netlister will not use it. This is very useful if you want to netlist a symbol using only the `format` (or `vhdl_format` or `verilog_format` depending on the netlist type) attribute or use the underlying schematic. By setting the attribute back to `subcircuit` and deleting (or setting to `false`) the `verilog_format` of `vhdl_format` attribute you can quickly change the behavior. For spice netlists the `format` attribute is always used also for subcircuits instantiation so always leave it there.
- Any value different from `subcircuit` or `primitive` will cause xschem to not use any schematic file even if it exists. Xschem will not allow to descend into an existing schematic.
- `label`: the symbol is used to label a net. These type of symbols must have one and only one pin, and the template string must define a `lab` attribute that is passed at component instantiationi to name the net it is attached to.
- `probe`: this denotes a probe symbol that may be backannotated with a backannotation script (example: ngspice_backannotate.tcl).
- `ngprobe`: This is a probe element that uses a 'pull' method to fetch simulation data and display it in current schematic. The data displayed is thus dynamic, multiple instancs of the same symbol with annotators will display operating point data for that particular instance without the need to update the backannotation as is required for annotators using the 'push' annotation methid.
- `netlist_commands`: the symbol is used to place SPICE commands into a spice netlist. It should also have a `value` attribute that may contain arbitrary text that is copied verbatim into the netlist. More on this in the netlist slide.

Only symbols of type `subcircuit` or `primitive` may be descended into with the `'e'` bindkey if they have a schematic view.

- `format`:The format attribute defines the syntax for the SPICE netlist. the `@` character is a 'substitution character', it means that the token that follows is a parameter that will be substituted with the value passed at component instantiation. If no value is given there a value will be picked from the attribute declared in the `template` string.
  The `@pinlist` is a special token that will be substituted with the name of the wires that connect to symbol pins, in the order they are created in the symbol. See the pin ordering section in the xschem properties slide. if the order of pins for a NMOS symbol is for example, d,g,s,b, then @pinlist will be expanded when producing a netlist to the list of nets that connect to the symbol drain, gate, source, body respectively. There is also a special way to define single pins: `@@d` for example will be replaced by XSCHEM with the net that connects to the `d` pin of the symbol. so for example `@pinlist` is equivalent to `@@d @@g @@s @@b`. However using `@pinlist` and setting the correct pin ordering in the symbol pins will make netlist generation faster. This is important for very big components with lot of pins, and `@pinlist` is the default when symbol is generated automatically (`Symbol ->Make symbol` menu of `<Shift>A` key).
  The `format` attribute may contain a `@spiceprefix` string immediately preceding (with no spaces) the `@name` attribute.. This will be substituted with value given in instance (example: `spiceprefix=X`) but *ONLY* if `Simulation->Use 'spiceprefix' attribute` is set. This allows to create different netlists for simulation (example: all MOS are defined as subcircuits) or LVS (no device subcircuits).
- `template`: Specifies default values for symbol parameters

The order these attributes appear in the property string is not important, they can be on the same line or on different lines:

    type=nmos format="@name @pinlist @model w=@w l=@l m=@m" template="name=m1 model=nmos w=5u l=0.18u m=1"

    format="@name @pinlist @model w=@w l=@l m=@m"
    template="name=m1 model=nmos w=5u l=0.18u m=1"
    type=nmos

As you see double quotes are used when attribute values have spaces. For this reason if double quotes are needed in an attribute value they must be escaped with backslash `\"`

since the symbol global property string is formatted as a space separated list of `attribute=value` items, if a `value` has spaces in it it must be enclosed in double quotes, see for example the symbol template attribute: `template="name=m1 model=nmos w=5u l=0.18u m=1"` or the the format attribute: `format="@name @pinlist @model w=@w l=@l m=@m"`. As a direct consequence a literal double quote in property strings must be escaped (`\"`)

### ATTRIBUTE SUBSTITUTION

XSCHEM uses a method for attribute substitution that is very similar to shell variable expansion done with the `$` character (for example `$HOME --> /home/user`) The only difference is that XSCHEM uses the `'@'` character. The choice of '@' vs '$' is simply because in some simulation netlists shell variables are passed to the simulator for expansion, so to avoid the need to escape the '$' in property strings a different and less used character was chosen.
A literal `@` must be escaped to prevent it to be interpreted as the start of a token to be substituted (`\@`). If a non space character (different than `@`) ends a token it must be escaped. Attribute substitution with values defined in instance attributes takes place in symbol format attribute and in every text, as shown in below picture.

In recent xschem versions a `%` prefixed attribute (example: `%var`) can be used instead of a @ prefix. The only difference is that if no matching attribute is defined in instance the `%var` resolves to `var` instead of an empty string.

If no matching attribute is defined in instance (for example we have `@W` in symbol and no `W=...` in instance) the `@W` string is substituted with an empty string.

### OTHER PREDEFINED SYMBOL ATTRIBUTES

- `vhdl_ignore`
- `spice_ignore`
- `verilog_ignore`

These 3 attributes tell XSCHEM to ignore completely the symbol in the respective netlist formats.

- `vhdl_stop`
- `spice_stop`
- `verilog_stop`

These 3 attributes will avoid XSCHEM to descend into the schematic representation of the symbol (if there is one) when building the respective netlist format. For example, if an analog block has a schematic (.sch) file describing the circuit that is meaningless when doing a VHDL netlist, we can use a `vhdl_stop=true` attribute to avoid descending into the schematic. Only the global property of the schematic will be netlisted. This allows to insert some behavioral VHDL code in the global schematic property that describes the block in a way the VHDL simulator can understand.

- `spice_primitive`
- `vhdl_primitive`
- `verilog_primitive`

same as above `_stop` attributes, but in this case the schematic subcircuit is completely ignored, only the 'format' string is dumped to netlist. No component/entity is generated in vhdl netlist, no module declaration in verilog, no .subckt in spice, no schematic global attributes are exported to netlist.

- `highlight`

If set to `true` the symbol will be highlighted when one of the nets attached to its pins are highlighted.

- `net_name`

If set to `true` the `#n:net_name` symbol attributes will display the net names attached to pin terminals. the `n` is a pin number or name.

- `place`

This attribute is only useable in `netlist_commands` type symbols (`netlist.sym, code.sym,...`) if set to `end` it tells XSCHEM that the component instance of that symbol must be netlisted at the end, after all the other elements. This is sometimes needed for SPICE commands that must ge given at the end of the netlist. This will be explained more in detail in the netlisting slide.
The `place=header` attribute is only valid only for netlist_commands type symbols and spice netlisting mode, it tells XSCHEM that this component must be netlisted in the very first part of a spice netlist. This is necessary for some spice commands that need to be placed before the rest of the netlist.

- `generic_type`

`generic_type` defines the type of parameters passed to VHDL components. Consider the following MOS symbol definition; the `model` attribute is declared as `string` and it will be quoted in VHDL netlists.

the resulting netlist is shown here, note that without the `generic_type` attribute the `irf5305` string would not be quoted.

    entity test2 is
    end test2 ;

    architecture arch_test2 of test2 is
    signal d : std_logic ;
    signal s : std_logic ;
    signal g : std_logic ;
    begin
    x3 : pmos3
    generic map (
       model => "irf5305"
    )
    port map (
       d => d ,
       g => g ,
       s => s
    );

    end arch_test2 ;

- `extra`

This property specifies that some parameters defined in the `format` string are to be considered as additional pins. This allows to realize inherited connections, a kind of hidden pins with connections passed as parameters. Example of a symbol definition for the following cmos gate:

the symbol property list defines 2 extra pins , VCCPIN and VSSPIN that can be assigned to at component instantiation. The `extra` property tells XSCHEM that these 2 parameters are connection pins and not parameters and thus must not be declared as parameters in the .subckt line in a spice netlist:

    type=subcircuit
    vhdl_stop=true
    format="@name @pinlist @VCCPIN @VSSPIN @symname wn=@wn ln=@ln wp=@wp lp=@lp m=@m"
    template="name=x1 m=1
    + wn=30u ln=2.4u wp=20u lp=2.4u
    + VCCPIN=VCC VSSPIN=VSS"
    extra="VCCPIN VSSPIN"
    generic_type="m=integer wn=real ln=real wp=real lp=real VCCPIN=string VSSPIN=string"
    verilog_stop=true

with these definitions the above schematic will be netlisted as:

    **.subckt prova1
    x2 G_y G_a G_b G_c VCC VSS lvnand3 wn=1.8u ln=0.18u wp=1u lp=0.18u m=1
    **.ends
    * expanding symbol: customlogicLib/lvnand3 # of pins=4
    .subckt lvnand3 y a b c VCCPIN VSSPIN
    wn=30u ln=2.4u wp=20u lp=2.4u
    *.opin y
    *.ipin a
    *.ipin b
    *.ipin c
    m1 net2 a VSSPIN VSSPIN nlv w=wn l=ln geomod=0 m=1
    m2 y a VCCPIN VCCPIN plv w=wp l=lp geomod=0 m=1
    dxm2 0 VCCPIN dnwell area='(wp + 57u)*(lp + 31u)' pj='2*(wp +57u)+2*(lp +31u)'
    m3 y b VCCPIN VCCPIN plv w=wp l=lp geomod=0 m=1
    dxm3 0 VCCPIN dnwell area='(wp + 57u)*(lp + 31u)' pj='2*(wp +57u)+2*(lp +31u)'
    m6 y c net1 VSSPIN nlv w=wn l=ln geomod=0 m=1
    m4 y c VCCPIN VCCPIN plv w=wp l=lp geomod=0 m=1
    dxm4 0 VCCPIN dnwell area='(wp + 57u)*(lp + 31u)' pj='2*(wp +57u)+2*(lp +31u)'
    m5 net1 b net2 VSSPIN nlv w=wn l=ln geomod=0 m=1
    .ends

Without the `extra` property in the cmos gate symbol the following incorrect netlist will be produced:

    **.subckt prova1
    x2 G_y G_a G_b G_c VCC VSS lvnand3 wn=1.8u ln=0.18u wp=1u lp=0.18u m=1
    **** begin user architecture code
    **** end user architecture code
    **.ends

    * expanding symbol: customlogicLib/lvnand3 # of pins=4

    .subckt lvnand3 y a b c
    wn=30u ln=2.4u wp=20u lp=2.4u
    VCCPIN=VCC VSSPIN=VSS
    *.opin y
    *.ipin a
    *.ipin b
    *.ipin c
    m1 net2 a VSSPIN VSSPIN nlv w=wn l=ln geomod=0 m=1
    m2 y a VCCPIN VCCPIN plv w=wp l=lp geomod=0 m=1
    dxm2 0 VCCPIN dnwell area='(wp + 57u)*(lp + 31u)' pj='2*(wp +57u)+2*(lp +31u)'
    m3 y b VCCPIN VCCPIN plv w=wp l=lp geomod=0 m=1
    dxm3 0 VCCPIN dnwell area='(wp + 57u)*(lp + 31u)' pj='2*(wp +57u)+2*(lp +31u)'
    m6 y c net1 VSSPIN nlv w=wn l=ln geomod=0 m=1
    m4 y c VCCPIN VCCPIN plv w=wp l=lp geomod=0 m=1
    dxm4 0 VCCPIN dnwell area='(wp + 57u)*(lp + 31u)' pj='2*(wp +57u)+2*(lp +31u)'
    m5 net1 b net2 VSSPIN nlv w=wn l=ln geomod=0 m=1
    **** begin user architecture code
    **** end user architecture code
    .ends

as you can see the VSSPIN and VCCPIN are listed as parameters and not as pins in the netlist.

- `dir`

Defines the direction of a symbol pin. Allowed values are `in`, `out`, `inout`.

- `propag=n`

This attribute instructs xschem to do a 'propagate highlight' from the pin with this attribute to the pin `n`. The number 'n' refers to the pin sequence number (do a `shift-S` after selecting destination pin to know this information).

- `goto=n[,m,...]`

This attribute is used in the xschem embedded digital simulation engine: propagate logic simulation to the output pins `n,[m,...]`. The logic function is defined via the 'function`n`' global attribute. There is one 'funtion`n`' for each `n` output pin. see 'function`n`' attribute for more info.

- `clock=n`

A `clock` attribute defined on input pins add some information on the pin function as follows:

- `clock=0` This indicates an 'active low' clock signal for flip-flops
- `clock=1` This indicates an 'active high' clock signal for flip-flops
- `clock=2` This indicates an 'active low' reset signal for flip-flops
- `clock=3` This indicates an 'active high' reset signal for flip-flops

- `function`

This attribute is set in the symbol global attributes and specifies the logic function to be applied to the associated output pin. The format is: `function<n>="...logic function..."` where the number `<n>` refers to the sequence number of the output pin (do a 'Shift-S' after selecting the pin to know its sequence number). Multiple functions (function3="...", function4="...") can be defined in case of elements with multiple outputs.

Commands that can appear in functions are:

- `n`: A digit indicates to put on the stack the logic value (0, 1, X) of pin with sequence number `n` The sequence number of a pin my be obtained by clicking the red square of the pin and pressing `Shift-S`.
- `&`: Does a logical AND operation of the last 2 elements on top of the stack, the result is left on the stack
- `|`: Does a logical OR operation of the last 2 elements on top of the stack, the result is left on the stack
- `^`: Does a logical XOR operation of the last 2 elements on top of the stack, the result is left on the stack
- `~`: Does a logical Negation operation of the last element on top of the stack, the result is left on the stack
- `M`: preceeded by 3 element 'a', 'b', 'm', return 'a' if 'm' == 0, 'b' if 'm'==1, else 'X'
- `m`: same as above, but don't update if 'm' not 1 or 0. Used to avoid deadlocks.
- `z`: preceeded by 2 elements, 'a', 'e', return 'a' if 'e' == 1 else Z (hi-Z)
- `d`: Duplicates top element on the stack
- `x`: Exhanges the 2 top elements on the stack
- `r`: Rotate down: bottom element of stack goes to top
- `H`: Puts a Logic '1' on the stack
- `L`: Puts a Logic '0' on the stack
- `Z`: Puts a Logic 'Z' on the stack
- `U`: Puts a Logic 'U' on the stack (do not assign to node)

The remaining value on the stack is the value that is returned and assigned to the output pin.

- `global`

a `global=true` property in a `label` type symbol will declare the corresponding net as 'global'. Global nets in spice netlists are like global variables in a C program, these nets are accessible at any hierarchical level without the need of passing them through pin connections.

- `spice_netlist`
- `verilog_netlist`
- `vhdl_netlist`

If any of these 3 properties if set to `true` the symbol will be netlisted in the specified format. This is only valid if the split file netlisting mode is active (`Options -> Split netlist`). This is very rarely used but is required in mixed mode simulations, where part of the system will be handled by an analog simulator (spice) and another part of the system by a digital Verilog / VHDL simulator.

- `verilog_format`

This is the Verilog equivalent of the `format` property for Spice primitives. This is a valid definition for a 2 input inverted XOR gate:

    verilog_format="xnor #(@risedel , @falldel ) @name ( @@Z , @@A , @@B );"

- `vhdl_format`

same as above for VHDL primitives.

- `tedax_format`

same as above for tEDAx netlists.

- `device_model`

This attribute contains a SPICE .model or .subckt specification (`device_model=".model D1N4148 D ...."`) that will be printed at end of netlist only once for the specified component (D1N4148 in the example).

- `schematic`

This attribute specifies an alternate schematic file to open when descending into the subcircuit:

     schematic=inv_2.sch

### PREDEFINED SYMBOL VALUES

- `@symname`

This expands to the name of the symbol

- `@pinlist`

This expands to the list of nets that connect to symbol pins in the order they are set in the symbol

- `@@pin`

This expands to the net that connect to symbol pin named `pin`. This substitution takes place only when producing a netlist (Spice, Verilog, VHDL, tEDAx) so it is allowed to use this value only in `format`,`vhdl_format`, `tedax_format` or `verilog_format` attributes (see Netlisting slide)

- `@#n`

This expands to the net that connect to symbol pin at position `n` in the XSCHEM internal storage. This substitution takes place only when producing a netlist (Spice, Verilog, VHDL, tEDAx) so it is allowed to use this value only in `format`,`vhdl_format`, `tedax_format` or `verilog_format` attributes (see Netlisting slide)
This method of accessing a net that connects to a pin is much faster than previous one since XSCHEM does not need to loop through symbol pin names looking for a match.
Example: `@#2`: return net name that connects to the third pin of the symbol (position 2).

- `@#n:pin_attribute`

This expands to the value or property `pin_attribute` defined in the pin at position `n` in the XSCHEM internal storage. This method of looking up properties is very fast.
Example: `@#0:pinnumber`: This expands to the value of the pinnumber defined in pin object at position 0 in the xschem internal ordering. This format is very useful for slotted devices where the actual displayed pin number depends on the slot information defined in the instance name (example: U1:2, slot number 2 of IC U1). These tokens may be placed as text in the symbol graphic window, not in format strings.

- `@#pin_name:pin_attribute`

This expands to the value or property `pin_attribute` defined in the pin named `pin_name` This method of looking up properties is a bit slower since xschem has to do string matching to find out the pin.
Example: `@#A:pinnumber`: This expands to the value of the pinnumber defined in pin `A`. This format is very useful for slotted devices where the actual displayed pin number depends on the slot information defined in the instance name (example: U1:2, slot number 2 of IC U1). These tokens may be placed as text in the symbol graphic window, not in format strings.

- `@#pin_name:net_name`
- `@#n:net_name`

these expand to the net name attached to pin with name `pin_name` or with sequence number `n`.

- `@sch_last_modified`

this indicates the last modification time of the `.sch` file of the symbol.

- `@sym_last_modified`

this indicates the last modification time of the `.sym` file of the symbol.

- `@time_last_modified`

this indicates the last modification time of the schematic (.sch) containing the symbol instance.

- `@schname`

this expands to the name of the schematic (.sch) containing the symbol instance.

- `@prop_ptr`

this expandes to the entire property string passed to the component.

- `@schprop`

this expandes to the spice global property string of the schematic containing the symbol

- `@schvhdlprop`

this expandes to the VHDL global property string of the schematic containing the symbol

- `@schverilogprop`

this expandes to the Verilog global property string of the schematic containing the symbol

### TCL ATTRIBUTE SUBSTITUTION

Any attribute and symbol text can be embedded in a `tcleval(....)` construct, the string inside the parentheses will be passed to the tcl interpreter for evaluation. This allows to use any tcl variable/command/expression. Example:
`spice_ignore="tcleval($::ignore_symbol)"`
will cause the symbol to be ignored by the spice netlister if the `ignore_symbol` tcl variable is existing and set to `true`