--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/ueda/doc/netlisting.txt	Mon Jul 20 00:24:37 2015 +0000
@@ -0,0 +1,256 @@
+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.