How uEDA tracks electrical interconnect (netlist) information

Whereas the MCL (see mcldoc.txt) is the authoritative source of information
about all components making up a board design, information about the way they
are interconnected is stored in the schematic sheets (.usch files) in the
language described in uschemlang.txt.  Electrical connections are declared by
way of assigning component pins to named or unnamed nets and may or may not be
represented graphically.  The following two constructs in the uschem language
connect component pins to nets:

* Net and GraphNet objects
* PinToNet decorations on component instance objects

Whichever method is used (see uschemlang.txt for the syntax details), the
declaration of an electrical connection effectively consists of the following
3 parts:

* Identification of the component involved;
* Identification of which pin to connect;
* The name of the net. (Net and GraphNet objects can create unnamed nets -
  those connect together everything listed in the respective object, but
  nothing else can connect to such nets.)

While it's possible for the component identification to be equal to the refdes
as given in the MCL and for the pin identification to be the "raw" pin number,
uEDA provides two mechanisms that allow the interconnect information to be
entered in a slightly more high-level form: component instances and pinout
mapping.

Component instances

In uEDA a component instance is essentially a reference from a schematic sheet
to a component in the MCL.  In a graphical schematic each component instance
would normally be represented by a graphical symbol, and all net connections
made in schematic sheets actually refer to component instances rather than to
MCL components directly.

For trivial components like resistors and capacitors as well as some simple
ICs there is normally only one instance per component, hence the component in
the MCL and the instance in a .usch sheet are one and the same for all practical
purposes.  However, for many of the more complex components it is generally
desirable to break the component up into multiple sections (which may be
identical or heterogeneous) represented separately in the schematic source code
for the design.  That's what the component instances in uEDA are for.

In the case when there are multiple component instances referring to the same
component, these instances may appear either in the same schematic sheet or in
different sheets.  If a given schematic sheet contains only one instance of a
given MCL component, regardless of whether or not there are other instances for
the same component in other sheets, the instance name may be equal to the refdes
of the component - that's what happens when the user doesn't make use of the
component instance mechanism.  However, if a single schematic sheet contains
more than one instance for a given component, there needs to be a way to
distinguish between them.

When uEDA tools process a uschem sheet and match it to the MCL, the following
algorithm is used to match component instances to components:

1. All component instance names appearing in a given schematic sheet are
   required to be unique.
2. Each component instance name is stripped of any trailing lowercase letters to
   obtain the corresponding refdes.
3. Each refdes is looked up in the MCL - if not found, that is an error.

Thus if you need to put multiple instances for a given component in a single
schematic sheet, give each a unique name consisting of the refdes with a unique
all-lowercase suffix appended to it.

Pinout mapping

uEDA allows one to use two different alphanumeric strings to identify the
individual pins of a component: pin name and pin number.  Both are arbitrary
alphanumeric strings (actually strings of any printable ASCII characters subject
only to common sense limitations); the pin number string doesn't have to be
purely numeric.  (For example, PGA and BGA packages normally use alphanumeric
pin numbers.)

Pin numbers are what appears in the final netlist output from uschem-netlist(1),
and they may also be used in the schematic source code.  If the source only uses
pin numbers for a given component, then there is no need for uEDA to know the
pinout of that component.  However, uEDA also allows one to specify the pinout
mapping for a component and to use pin names instead of pin numbers.

Pinouts are specified in dedicated pinout mapping files and brought into the
design via pinout= attributes in the MCL.  Pinout mapping files use a very
straightforward format: each pin mapping is given on a separate line; each such
line consists of two fields separated by tabs or spaces: the left field is the
pin name and the right field is the pin number.  Comments are marked by '#';
all blank lines and comment lines are ignored.  Any additional fields past the
pin number are currently ignored as well, but this behavior should not be relied
upon; any such line-appended comments should begin with a '#' character.

The name of the pinout mapping file specified in the pinout= attribute is only
the base filename, not a pathname.  uschem-netlist and uschem-print (the only
two programs in the uEDA suite that need pinout mappings) locate pinout mapping
files using the same mechanism that is used to locate graphical symbol files -
see uschem-netlist(1) and uschem-print(1).

In addition to making the schematic source code more readable, pinout mappings
make it easy to support components that come in several different packages with
different physical pin numbers for the same logical functions.  It is no longer
necessary to create multiple versions of the same graphical symbols with
different pin numbers embedded inside or to edit pin references in Net objects;
instead all those references can now be made by the logical pin name.  If a
decision is made to change to a different package with a different pinout, only
the pinout= attribute in the MCL entry for the respective component needs to be
changed - at the same time when you change the manufacturer_part_number= and
footprint= attributes.

By the same token it is no longer necessary to create special PCB footprints
with logical pin names embedded in them where pin number strings normally go:
instead one can take the natural approach of having footprints identify pins or
pads by their physical position, having schematics and symbols refer to pins by
their logical function only and using pinout mapping files to bridge the gap.
The pinout mapping feature is one of uEDA's main advantages over gEDA.

Slotting

The concept of slotting (and the term) originates in gEDA, but uEDA implements
it in a very different manner.  uEDA's approach to slotting combines component
instances with pinout mapping in a special way.  But first, what is slotting?

Suppose that you have a physical component (typically an IC) that consists of
multiple identical logical blocks such that each of those blocks should be
treated as a separate device in the schematic source code.  74xx logic ICs are
a classic example.  When one needs to describe the use of such a component in a
design, it is normally desirable to represent each slot as its own component
instance and furthermore to do it in such a way that one doesn't have to decide
upfront which slot will be used for what, allowing slots to be reassigned with
ease.

In uEDA this feat is accomplished by combining component instances with pinout
mapping.  When each slot is declared as a component instance, all connections
to it are made by logical names only: for example, a NAND gate that is 1/4th of
a 7400 would have connections made to A, B and Y rather than to specific pin
numbers.  So far, so good.  But how would the tools know whether A for example
should be mapped to pin 1, 4, 9 or 12?  That is where the slot= attribute comes
in.  It is one of the few attributes defined in the component instance
declaration (Component object) in a schematic sheet rather than in the MCL.
When uEDA tools map a pin name to a pin number for a component instance that has
the slot= attribute defined, the value of this attribute is appended to the pin
name after a colon, e.g., if the pin name is A and slot=1, the pin name looked
up in the pinout mapping table will be A:1.  The pinout for a 7400 quad NAND
gate looks like this:

#pin name	pin number
A:1		1
B:1		2
Y:1		3
A:2		4
B:2		5
Y:2		6
GND		7
Y:3		8
A:3		9
B:3		10
Y:4		11
A:4		12
B:4		13
Vcc		14

Note the GND and Vcc pins which are not slotted.  It is perfectly legitimate to
have some component instances which have the slot= attribute selecting one of
the logic slots, yet have other component instances referring to the same
component (e.g., for the power pins) without slotting.

The following pinout for an SN75LBC784 EIA-423 transceiver is a more complicated
example of heterogeneous slotting:

#pin name	pin number
Drvr_In:3	1
Rcvr_Out:3	2
BIAS1		3
Drvr_In:4	4
Rcvr_Out:4	5
BIAS2		6
Vss		7
GND		8
Rcvr_In_N:4	9
Drvr_Out:4	10
Rcvr_In_N:3	11
Drvr_Out:3	12
Rcvr_In_P:3	13
Rcvr_In_P:4	14
Rcvr_In_P:1	15
Rcvr_In_P:2	16
Rcvr_In_N:2	17
Drvr_Out:2	18
Rcvr_In_N:1	19
Drvr_Out:1	20
Vdd		21
Rws		22
Drvr_In:1	23
Rcvr_Out:1	24
BIAS3		25
Drvr_In:2	26
Rcvr_Out:2	27
BIAS4		28

This IC has 4 driver sections, 4 receiver sections and a set of common pins.
The pinout file given above allows it to be represented schematically using a
separate component instance for each driver section (with slotting), a separate
set of component instances for the receiver sections (an independent set of
slots) and one or more non-slotted component instances for the common pins.

It is also worth noting that slot names (the value of the slot= attribute) are
not restricted to numbers only and may in fact be arbitrary ASCII strings.  For
example, it would be sensible to define the pinout for a bicolor LED with slots
named "red" and "green", having complete pin names such as A:green and C:red
with connections being made to just A and C on the proper instances.

Netlist generation

When uschem-netlist processes a set of schematic sheets and an MCL to compile a
complete netlist, it first resolves all pin names (with or without slots) to
physical pin numbers and tracks the connection information at the component
level, i.e., the information is effectively moved up from the instance level at
which it is specified in the schematic source code to the component level.  The
netlist data structures constructed by uschem-netlist maintain a hard
requirement that every physical pin of every component listed in the MCL be
either connected to exactly one net or left unconnected; thus any attempt to
connect the same physical pin to more than one net will be detected and flagged
as an error regardless of how each connection was specified in the source code.

One may use the NoConnect decoration on a component instance object to declare
explicitly that a given pin shall be left unconnected.  uschem-netlist will note
such declarations and flag an error if an attempt is made anywhere else in the
source code to connect the same physical pin to some net.

Differences from gEDA

The main difference between gEDA and uEDA with regard to netlisting is that in
uEDA graphical elements such as symbols and net lines do not create electrical
connections, they merely illustrate them.  The uschem language (documented fully
in uschemlang.txt) is designed so that the graphical information and the
electrical interconnect information are mostly orthogonal.  The electrical
interconnect information must be fully specified in the .usch files, not
inferred from symbol files, to the point that the latter files are not needed
for netlist generation and are not read by uschem-netlist at all.  Thus gEDA
constructs such as auto-connected hidden power pins have no place in uEDA; the
closest one can get to that would be to insert a non-graphical component
instance with the necessary net connections into an otherwise graphical
schematic sheet.

By a similar token the graphical symbols for power rails and such do not cause
a net to be connected to a rail, instead that connection is made by having the
proper netname set on the GraphNet object in the .usch file; the symbols merely
illustrate it graphically for those looking at the printout rather than the
source code.

The downside with uEDA's approach is of course the very real possibility that
the netlist and the graphics will get out of sync, i.e., that the set of
electrical interconnections mentally inferred by someone looking at the
graphical schematic printout will differ from the set of interconnections
embodied in the source code processed by uEDA tools.  See drc.txt for the
discussion of how uEDA addresses this problem.