start => gnetlist_ug

<< Basic netlisting | gEDA gnetlist User Guide | Slots and slotting >>

## Hierarchy

gnetlist has support for hierarchical schematics. These are schematic diagrams that include other schematic diagrams as subcircuits. This can be very useful for designs that use the same circuit multiple times, or for re-using a circuit in multiple designs. Subcircuits can in turn contain other subcircuits!

Each subcircuit schematic diagram needs to have a subcircuit symbol associated with it. The "`device=`" attribute on a subcircuit symbol is ignored. The "`source=`" attribute should be used to specify the name of the subcircuit's schematic file.

Subcircuit symbols are loaded from the symbol library as normal. Subcircuit schematics are loaded from the source library.

See Configuring gnetlist for details of how to control where gnetlist looks for subcircuit schematic files.

### Hierarchical ports

The pins on a subcircuit symbol define the ports where designs that include the circuit can connect to it. Each port should be named using a "`pinlabel=`" attribute. To define the points where a port attaches to the subcircuit's nets, gnetlist will look for the first pin on a component which has a "`refdes=`" attribute that matches the port's name. You can normally use the "in-1.sym" and "out-1.sym" symbols from the generic "Input/Output" symbol library for this.

### Renaming components and nets

Each subcircuit symbol placed into a schematic must have a "`refdes=`" attribute attached to it. This is the name of the subcircuit instance. In order to uniquely identify components and nets in each instance of a hierarchical subcircuit, gnetlist will rename them using the subcircuit's name as a prefix.

For example, consider a subcircuit that contains a component with "`refdes=U1`" and a net with "`netname=FEEDBACK`". Now, suppose the subcircuit symbol is placed in a schematic and an attribute "`refdes=A1`" is attached to it. When the schematic is processed using gnetlist, gnetlist will rename the component to "A1/U1" and rename the net to "A1/FEEDBACK".