| << [[geda:gnetlist_ug:basic_netlisting|Basic netlisting]]  |  **[[geda:gnetlist_ug|gEDA gnetlist User Guide]]**     |  [[geda:gnetlist_ug:slotting|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//.

<note tip>See [[config|Configuring gnetlist]] for details of how to control where gnetlist looks for subcircuit schematic files.</note>

==== 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".