The Symlib format is a text file format that defines schematic symbol shapes. Symlib files are used by the GateVision PRO tool (see the Read Dialog or use cmdline option “-symlib”). GateVision PRO scans the symlib files in order to get symbol shape information.

Symlib files can either be created manually or by a converter program such as cadence2symlib (see Symlib Utilities for an overview).

Overview

Each Symlib file stores a set of symbol shapes, usually customer shapes (but built-in shapes and Boolean equations are also supported). This document describes:

The Symlib File Structure

A symlib file consists of: (a) one symlib header line, (b) a set of symref index lines, and (c) a set of symbol lines, defining DEF customer shapes (please check out built-in shapes or Boolean equations as alternatives).

The Symlib File is ASCII line-oriented; each entry ends with a newline character, but the lines can be concatenated with a "\" (backslash) character. Comment lines start with a "#" character.

Here is a small example:

header line

 
symlib 1.5 noname 4 16 25

file index

 
symref      219 and2
symref      626 xor3
...

port symbols

 
symio ipin in  * *
symio gnd  pg0 * *
...

symbol entries

 
symbol and2 * DEF \
        pin Y out -loc 50 0 40 0 \
        pinattrdsp @name -cr 50 -5 8i \
        pin A in -loc -10 -10 0 -10 \
        pinattrdsp @name -cl -10 -15 8i \
        pin B in -loc -10 10 0 10 \
        pinattrdsp @name -cl -10 5 8i \
        permute all_inputs \
        path 25 15 40a 0a 25 -15 0 -15 0 15 25 15 \
        attrdsp @name -ll 5 -22 12 \
        attrdsp @cell -cl 5 22 10i
symbol xor3 * DEF \
        pin C in -loc -10 20 0 20 \
        ...

The File Header Line

The header line starts with “symlib”, followed by (1) the version number, (2) the symlib name (unused), (3) the number of symref entries in the index (that is also the number of symbol entries), (4) the character offset to the symbol name in each symref line, (5) the length of each symref line, and (6) the options. For example:

symlib 1.5 noname 4 16 25 i

The option "i" (6th argument) makes the name matching case-insensitive (for symbol-name and view-name and symbol pin names); this option is only available in symlib version >= 1.2.
The SpiceVision, GateVision, RTLvision, and StarVision tools additionally support the option 'g' to define that glob style pattern can be used for symbol-name matching; this option is only available in symlib version >= 1.4.
The header line as well as the file index is usually automatically created/updated by a converter program or by Symbol Viewer/Editor.

The File Index Section

The file index consists of a set of symref lines, one per symbol entry. It is used to get fast access to the required symbols. Each symref line defines the start position of a symbol definition and the symbol name. This start position is the lseek position, that is the byte count within the file.

All symref lines have a fixed common line width - they are padded with trailing blanks. The line width is defined by the header line. For example:

symref      219 and2
symref      626 xor3

The Port Symbols

The port symbol part consists of a set of symio lines. They define rules for user defined port and power/ground symbols. Each line references a symbol shape, which will replace the builtin symbol if the following three pattern match. The first pattern is one of the types

  • * matches for all types

  • in matches input port symbols

  • out matches output port symbols

  • inout matches inout port symbols

  • pg+ matches power symbols

  • pg- matches negpower symbols

  • pg0 matches ground symbols

The second pattern matches the port (for in,out,inout) or net (for pg+, pg-, pg0) name. The third pattern matches the module name. Both may contain glob style pattern.

The DEF Symbol Definition

The last section in the Symlib File consists of a set of “symbol” lines, each defines one symbol shape, either a DEF customer shape (as described in this chapter) or a Builtin Shapes or a Boolean Equations; the syntax for them is similar, but described in an extra chapter below.

Each symbol shape is defined in one line (with some optional continuous lines). The symbol definition list is actually a tcl-style list of words. Special character in the words (like spaces and some punctuation characters) must be protected according to the tcl rules by surrounding braces { …​ }.

In each symbol line, the first words identify the symbol and the word #3 identifies the symbol type, here a DEF. Each sub-keyword (the first sub-keyword is at word #4) defines a symbol item with a fixed number of subsequent words that belong to that item (the documentation of the symbol items follows). The Symbol Definition for a DEF customer shape has this format:

word count meaning example

0

keyword: symbol

symbol

1

symbol name

and2

2

symbol view name (or wildcard=*)

*

3

keyword: DEF

DEF

4

a new sub-keyword, one of pin, pinBus, permute, attrdsp, pinattrdsp, text, pintext, fillcolor, pinfillcolor, arc, path, fpath, prop, place, boxcolor, autoalign, scalenow, bboxnow, func

pin

5

…​ (depends on previous sub-keyword)

…​

…​

Pin Definition: pin

A symbol Pin Entry requires 7 more arguments:

word count meaning example

0

keyword: pin

pin

1

pin name

O

2

pin direction, (see below for supported values)

out

3

pin option-keyword: -loc (see also: polygons)

-loc

4

pin connect-location x-coord

50

5

pin connect-location y-coord

0

6

pin stub end location (inside) x-coord

40

7

pin stub end location (inside) y-coord

0

The order of the pins within a symbol does not matter, the mapping to the EXT symbol is done by pin name (usually case-sensitive, unless the option "i" is specified). Additional pins do not cause any problem - they are always unconnected, of course. Missing pins cause a warning message and the missing pins are marked by the hidden flag, to disable the routing of the connected net to this symbol.

Note: The 4th and 5th argument (pin connect-location) should be a multiple of the schematic grid; the default is 10.

Pin Bus Definition: pinBus

A symbol PinBus Entry requires 8+width more arguments (except for the gwidth syntax - see below). Although this entry defines the pin width and the subpin names, that information is ignored when the symbol shape is mapped to a netlist-level symbol statement (symbol type = EXT); this means, the netlist-level symbol object overwrite bus details. The order of the pinBuses within a symbol does not matter, the mapping is done by pinBus name - analog to the pin.

word count meaning example

0

keyword: pinBus

pinBus

1

pinBus name

DATA(3:0)

2

pinBus direction (see below for supported values)

in

3

pinBus width

4

4

pinBus’s subpin #0 (MSB)

DATA(3)

5

pinBus’s subpin #1

DATA(2)

6

pinBus’s subpin #2

DATA(1)

7

pinBus’s subpin #3 (LSB)

DATA(0)

8

pinBus option-keyword: `-loc (see also: polygons)

-loc

9

pinBus connect-location x-coord

50

10

pinBus connect-location y-coord

0

11

pinBus stub end location (inside) x-coord

40

12

pinBus stub end location (inside) y-coord

0

Below are two alternative ways to define a pinBus using the gwidth and range syntax, respectively. This is the preferred syntax for regular bus names, where sub-names can be derived from the bus name: The column "example: gwidth" is equivalent to the example above. The column "example: range" differs from above example in such as the sub-script range is not part of the pinBus name; instead, the range is given as an extra argument defining the bus width and the sub-names' sub-scripts.

word count

meaning

example: gwidth

example: range

0

keyword: pinBus

pinBus

pinBus

1

pinBus name

DATA(3:0)

DATA

2

pinBus direction (see below for supported values)

in

in

3

pinBus g_width_ or range (auto-generate sub-names)

g4

(3:0)

8

pinBus option-keyword: -loc (see also: polygons)

-loc

-loc

9

pinBus connect-location x-coord

50

50

10

pinBus connect-location y-coord

0

0

11

pinBus stub end location (inside) x-coord

40

40

12

pinBus stub end location (inside) y-coord

0

0

SubPin Options: pinsopt

A symbol SubPin Option Entry defines deviating options for one subpin of the previous pinBus Entry. Usually, the subpins inherit the options from their pinBus Entry, but can be overwritten on a per-subpin basis. The subpin is addressed by order number, starting with index 0 for the first subpin (MSB). It requires 2 more arguments:

word count meaning example

0

keyword: pinsopt

pinsopt

1

the zero-based subpin order number

0

2

the subpin option(s)

in.neg.clk

Notes: * Directional options like top or right are ignored, the pinBus direction always applies to all its subpins. * This entry must be repeated for every subpin that differs in options from its pinBus entry.

Pin Permutation: permute

A symbol Permute Entry requires 1 more argument:

word count meaning example

0

keyword: permute

permute

1

the permutation definition

all_inputs

The permutation definition is either a keyword, one of “all_inputs”, “all_outputs” or “all” - or a pin permutation definition list by name like “(A,B,D)” or by index numbers like “#(0,1,3)”.

Permutation Syntax

Each permutation group is defined by a list of symbol pin names (or index numbers) or nested sub-groups, the elements are separated by commas. A permutable group is enclosed in parentheses (), a non-permutable group is enclosed in brackets []. The top-most group is considered non-permutable, unless it is explicitly enclosed in parentheses ().

Please note: the keywords "all_inputs" and "all_outputs" only work, if all input pins (or all output pins) are located on the same side (left, right, top or bottom) - see also symbol pin directions.

a,b,c

a,b and c are not permutable.

[a,b,c]

same as above; the braces at the top group are optional

(a,b,c)

a,b and c are permutable.

((a,b),(c,d))

a and b can be permuted, c and d can be permuted, the two groups can be permuted

([a,b],[c,d])

only the two groups "a,b" and "c,d" can be permuted.

([a,(b,c)],[d,(e,f)])

defines two permutable sets, abc and def, where bc and ef may also be permuted

([a,(b,c)][d,(e,f)])

same as above; the commas preceding a ( or [ are optional.

Permutation Syntax (by Pin Number)

If the permute string starts with a # character, then pin index numbers (instead of pin names) are expected. The parentheses, brackets and commas “()[],” are used as above with identical meaning. The pin index numbers start at zero. For example, “#(0,1,2,3)” defines a permutation group of 4 pins (the index refers to the definition order of the pins).

Display Location for Attributes: attrdsp and pinattrdsp

A symbol (or symbol-pin) Attribute Display Entry defines a display location for instance (or instance-pin) attributes. It requires 5 more arguments:

word count meaning example

0

keyword: attrdsp or pinattrdsp

attrdsp

1

attribute name

@name

2

text justification, one of -ll, -lc, -lr, -cl, -cc, -cr, -ul, -uc, -ur

or -ll.v, -lc.v, -lr.v, -cl.v, -cc.v, -cr.v, -ul.v, -uc.v, -ur.v

-ll

3

display-location x-coord

5

4

display-location y-coord

-22

5

font size - optionally followed with suffix flag characters "i", "c" or "r"
(no space between number and flag characters).

12

Word #2 (the justification) defines:

the origin of the displayed text - to be at lower-left, lower-center, lower-right, …​, etc. The display orientation is either horizontal (default) or vertical if .v is added. Horizontal text means: rotated 90 degrees counterclockwise. Justification will be applied before rotation, e.g. -ll.v will display the attribute vertically, growing from the display-location (words #3 and #4) towards top; the attribute’s bounding box’s lower-right corner will meet the display-location.

Word #5 (the font size) defines optional flags:

“i” means, this is an invisible attribute.
“c” defines an case-insensitive name lookup for finding the matching instance attributes. Special attributes like @name, @cell, @attr, etc cannot be flagged to be case-insensitive.
“r” defines a non-rotating attribute (or text) that means it is not updated when an instance is rotated.

Each pinattrdsp entry refers to the previous pin or pinBus.

Display Location for Constant Text: text and pintext

A symbol (or symbol-pin) Text Entry defines a text label and a display location for it. It requires the same 5 arguments as attrdsp above, except argument #1 is the text label string instead of the attribute name.

The text can also span several lines (multi-line text). Use \n in the text string to force the beginning of a new line. \n itself will not be displayed. For example:

text "This component\ndemonstrates\nmultiline attributes." -ul 40 50 12

Symbol Properties: prop and pinprop

A symbol (or symbol-pin) Property Entry defines an arbitrary name-value-pair like an attribute, but at a Symbol or Symbol-Pin instead of Instance or Pin. These properties are never displayed and they do not derive their values to instances/pins of the symbol. It requires 2 more arguments:

word count meaning example

0

keyword: prop or pinprop

prop

1

name

ident

2

value

5812

Arc Definition: arc (Deprecated)

A symbol Arc Entry defines a (unfilled) circle or a circular arc. If the start and end locations are identical, then it is a circle, else it is an arc. As of Symlib format 1.5 arc bows can also occur within a path element - effectively rendering the arc keyword obsolete; but the Arc entry is still accepted for backward compatibility. The Arc entry requires 6 more arguments:

word count meaning example

0

keyword: arc

arc

1

arc start location x-coord

25

2

arc start location y-coord

15

3

middle location on arc x-coord

40

4

middle location on arc y-coord

0

5

arc end location x-coord

25

6

arc end location y-coord

-15

Polygon Path Definition: path

A symbol Path Entry defines a non-closed polygon path. It consists of vertices (x/y pairs) that are automatically terminated by the first non-number argument. The intermediate vertices define corner points. There is one exception: If the vertex coordinates are postfixed by an "a", then they define the middle point of a circular arc (from previous vertex to next vertex) - see also fpath.

word count meaning example

0

keyword: path

path

1

1st vertex (start location) x-coord

25

2

1st vertex (start location) y-coord

15

3

2nd vertex x-coord - middle point of intermittent arc

40a

4

2nd vertex y-coord - middle point of intermittent arc

0a

5

3rd vertex (start location) x-coord

25

6

3rd vertex (start location) y-coord

-15

7

4th vertex x-coord

0

8

4th vertex y-coord

-15

9

5th vertex x-coord

0

10

5th vertex y-coord

15

11

6th vertex x-coord

25

12

6th vertex y-coord

15

13

not a number - beyond end of path

attrdsp

Polygon Fill-Path Definition: fpath

A symbol Fpath Entry defines a closed polygon path as required for the fillcolor feature. It consists of vertices (x/y pairs) that are automatically terminated by the first non-number argument. The first and last vertex should be the same. The intermediate vertices define corner points. There is one exception: If the vertex coordinates are postfixed by an "a", then they define the middle point of a circular arc (from previous vertex to next vertex) - see also path. The example below defines two fill-paths for a NAND gate. The second path is actually a filled circle (a filled closed arc):

word count meaning example

0

keyword: fpath

fpath

1

1st vertex (start location) x-coord

0

2

1st vertex (start location) y-coord

0

3

2nd vertex x-coord

0

4

2nd vertex y-coord

15

5

3rd vertex x-coord

25

6

3rd vertex y-coord

15

7

4th vertex x-coord - middle point of intermittent arc

40a

8

4th vertex y-coord - middle point of intermittent arc

0a

9

5th vertex x-coord

25

10

5th vertex y-coord

-15

11

6th vertex x-coord

0

12

6th vertex y-coord

-15

13

7th vertex x-coord

0

14

7th vertex y-coord

0

0

end of fpath, start of another fpath

fpath

1

1st vertex (start location) x-coord

40

2

1st vertex (start location) y-coord

0

3

2nd vertex x-coord

48a

4

2nd vertex y-coord

0a

5

3rd vertex x-coord

40

6

3rd vertex y-coord

0

15

another keyword - beyond end of fpath

???

Placement Hint: place

A symbol Place Entry can be used to give hints for the placement of special symbols like latches or IO buffers or to define a port symbol. The Place entry requires 1 more argument:

word count meaning example

0

keyword: place

place

1

one of “latch”, “in_buffer”, “out_buffer”, “io_buffer”

or, to specify a port symbol: “port”

or, to specify a power/ground symbol: “power_stub”, “ground_stub”

latch

Color Setting #1: boxcolor

A symbol Boxcolor Entry can be used to define an alternate color for the symbol body. The Boxcolor entry requires 1 more argument:

word count meaning example

0

keyword: boxcolor

boxcolor

1

a number between 0 and 15

2

Color Setting #2: fillcolor and pinfillcolor

A symbol (or symbol-pin) Fillcolor Entry can be used to define an alternate background color (fillcolor) for the symbol body (or polygon shaped symbol-pin). In order to see a background color for a particular area an appropriate closed shape using fpath and/or arc (-locfpath and/or -locarc) must be defined. The Fillcolor Entry requires 1 more argument:

word count meaning example

0

keyword: fillcolor

fillcolor

1

a number between 1 and 15

1

Automatic Symbol Alignment: autoalign

A symbol Autoalign entry can be used to immediately transform all coordinates of the symbol shape, so that the symbol origin (0,0) is placed at the upper left corner of the symbol shape. To keep the symbol on grid the y origin is not always at the top edge but snapped to grid.

As a result all components of these symbols will be lined up (left side aligned) in each component column of the schematic page. Autoalignment is only supported for DEF and EXT symbols. All builtin symbols are already defined with a left side alignment.

word count meaning example

0

keyword: autoalign

autoalign

Automatic Symbol Scaling: scalenow

A symbol Scalenow entry can be used to immediately scale all coordinates of the symbol shape by the given factor. Scalenow is only supported for DEF symbols. Since the symbol is scaled immediately after reading this keyword, it is required that this keyword is placed after the last declaration containing coordinates.

word count meaning example

0

keyword: scalenow

scalenow

1

the factor

1.5

Enlarge Symbol Bounding-Box: bboxnow

A symbol Bboxnow entry can be used to immediately enlarge the symbol’s bounding-box by the given coordinates. Bboxnow is only supported for DEF symbols.

word count meaning example

0

keyword: bboxnow

bboxnow

1

left coord

-20

2

top coord

-80

3

right coord

200

4

bottom coord

80

Define Symbol Function: func

A symbol function can be defined (only needed if different from the symbol shape type). If the symbol type is DEF or EXT (user-defined shape), then a function for that user-defined symbol may be specified to control some internal functions. Not defining a function usually has very little impact. Non-simple shape types (like those for combi gates with a number sequence as part of the shape type) are not supported and silently handled as UNDEF.

word count meaning example

0

keyword: func

func

1

One of the builtin device symbol shapes, or simple builtin symbol shapes, or UNDEF.

NMOS

Symbol Pin Directions

The pin direction (word #2 of the pin or pinBus definition) must specify the graphical direction. It is a dot-separated list of keywords; this list must not be empty, and may contain a combination of electrical direction and graphical direction, e.g. input.top.

For symbol shape definitions in Symlib Files the electrical direction can be omitted.

Direction Description

left

The pin will be connected from the left side.

right

The pin will be connected from the right side.

top

The pin will be connected from the top.

bottom or bot

The pin will be connected from the bottom.

unknown

The pin connect direction is unknown and will be determined by
(a) the graphical orientation of the pin stub or if not possible by
(b) the distance between the gravity center and the pin location.

Builtin Shapes in the Symlib File

In addition to the DEF custom shapes (described above), the Symlib Files also supports Builtin Shapes. When Builtin Shapes are defined in the symlib files then most builtin types do not require to have the pins listed, however, they can - to specify additional pin options like neg, clk, top or bot, etc - if needed. However, the builtin combi-gates and PLA need all (input) pins to be listed (to match the pin order).

A mapping of symbol names to Builtin Shapes can be defined as simple as in this Symlib Files example:

header line

 
symlib 1.5 example ...

file index

…​

symbol entries

 
symbol invx1   * INV
symbol invx4   * INV
symbol nand2x1 * NAND
symbol nor2x1  * NOR
symbol xnor2   * XNOR
symbol xor2    * XOR
symbol mux2    * MUX pin S in.top
symbol lat     * GEN fillcolor 2 pin G in.neg.clk \
                 pin Set in.top pin Res in.bot

Builtin Combi-Gate Shapes and PLA

Builtin shapes for combi-gates (AO, OA, AX, etc) as well as for PLA need to have all pins defined, because the pin order matters. The pin order from the symlib file entry overwrite the original symbol.

If the pin names as defined in the symlib file entry don’t match to the original symbol, then the symlib file entry is dropped and a BOX is used instead.

header line

 
symlib 1.5 example ...

file index

…​

symbol entries

 
symbol ao1 * AO(21) pin A in pin B in pin C in.neg

Boolean Equations in the Symlib File

A special way for defining a Builtin Shapes is using a Boolean Equations, as explained in the Builtin Symbol Shapes document.

A mapping from a symbol name to Boolean Equation (resulting in a Builtin Shapes) can be defined as simple as in this Symlib File example:

header line

 
symlib 1.5 example ...

file index

…​

symbol entries

 
symbol xor * BOOL Y a^b^c   fillcolor 1
symbol xa1 * BOOL Y (a^b)*c fillcolor 1

Polygon Shaped Pins and PinBuses

Starting with Symlib format version 1.4, the pin and pinBus keywords alternatively support defining arbitrary polygon shapes. Depending on the desired polygon(s) you have to replace the pin option -loc by one of: -locarc (deprecated), -locpath or -locfpath. To define a multi-part polygon, you can repeat these keywords multiple times (including the mandatory connect location - see below for details). These polygon shaped pins are implicitly excluded from Pin Permutation.

Please note: The first point in all three polygon pin options below is the connect-location. This defines the start/end point of a connecting net wire for that pin. The connect-location is not part of the polygon; it can be placed arbitrarily. This, however, may confuse the internal guessing for the net connect direction. That’s why you probably want to add the desired pin direction (left, right, top, bot) explicitly.

Pin Option: -locarc (Deprecated)

Similar to the arc keyword, this polygon pin option defines a single (unfilled) circle or circular arc. If the start and end locations are identical, then it is a circle, else it is an arc. Note, as of Symlib format 1.5 arcs can also occur within a -locpath element.

word count meaning example

0

polygon pin/pinBus option keyword: -locarc

-locarc

1

pin/pinBus connect-location x-coord

-15

2

pin/pinBus connect-location y-coord

45

3

arc start location x-coord

0

4

arc start location y-coord

45

5

middle location on arc x-coord

-30

6

middle location on arc y-coord

45

7

arc end location x-coord

0

8

arc end location y-coord

45

Pin Option: -locpath

Similar to the path keyword, this polygon pin option defines a (unfilled) non-closed polygon path. It consists of vertices (x/y pairs) that are automatically terminated by the first non-number argument. The intermediate vertices define corner points. There is one exception: If the vertex coordinates are postfixed by an "a", then they define the middle point of a circular arc (from previous vertex to next vertex) - see also -locfpath.

word count meaning example

0

polygon pin/pinBus option keyword: -locpath

-locpath

1

pin/pinBus connect-location x-coord

27

2

pin/pinBus connect-location y-coord

-10

3

1st vertex (start location) x-coord

20

4

1st vertex (start location) y-coord

-10

5

2nd vertex x-coord

25

6

2nd vertex y-coord

-10

7

3rd vertex x-coord - middle point of intermittent arc

30a

8

3rd vertex y-coord - middle point of intermittent arc

-10a

9

4th vertex x-coord

25

10

4th vertex y-coord

-10

…​

…​

…​

…​

not a number - beyond end of polygon path

pinattrdsp

Pin Option: -locfpath

Similar to the fpath keyword, this polygon pin option defines a closed polygon path as required for the fillcolor or @fillcolor features. It consists of vertices (x/y pairs) that are automatically terminated by the first non-number argument. The first and last vertex should be the same. The intermediate vertices define corner points. There is one exception: If the vertex coordinates are postfixed by an "a", then they define the middle point of an intermittent circular arc (from previous vertex to next vertex) - see also -locpath.

word count meaning example

0

polygon pin/pinBus option keyword: -locfpath

-locfpath

1

pin/pinBus connect-location x-coord

-15

2

pin/pinBus connect-location y-coord

15

3

1st vertex (start location) x-coord

10

4

1st vertex (start location) y-coord

56

5

2nd vertex x-coord

10

6

2nd vertex y-coord

50

7

3rd vertex x-coord

20

8

3rd vertex y-coord

50

9

4th vertex x-coord

20

10

4th vertex y-coord

62

11

5th vertex x-coord

10

12

5th vertex y-coord

62

13

6th vertex x-coord - middle point of intermittent arc

4a

14

6th vertex y-coord - middle point of intermittent arc

56a

15

7th vertex x-coord

10

16

7th vertex y-coord

50

…​

…​

…​

…​

another keyword - beyond end of polygon fpath

pinattrdsp