--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/ueda/doc/mcldoc.txt	Mon Jul 20 00:24:37 2015 +0000
@@ -0,0 +1,395 @@
+uEDA Master Component List (MCL) description
+
+The MCL is an essential component of the design source code in the uEDA flow.
+It is a human-created and human-edited text file which lists all components on
+the board being designed and all their attributes.  The file must be named
+"MCL" (w/o quotes) and must reside in the project directory.  This document
+describes the file format and everything you need to know in order to write the
+MCL for your board.
+
+Each component on the board must have a reference designator (refdes).  Valid
+characters for the refdes are uppercase and lowercase letters and digits; the
+first character must be an uppercase letter.  Lowercase letters are allowed but
+not recommended, in particular a refdes should not end in any lowercase letters
+- see the description of component instances in netlisting.txt for the
+explanation.
+
+The MCL contains a section for each component of the form:
+
+refdes:
+ attribute=value
+ attribute=value
+ ...
+
+Each refdes line must begin in the leftmost column without leading spaces
+and end with a colon.  It is followed by attribute lines defining various
+attributes for the component in question; these attributes are the essence of
+the information contained in the MCL.  Different attributes are required by
+different tools in the uEDA suite and all currently defined attributes are
+listed in this document.  Attributes are name=value pairs and attribute lines
+in the MCL must begin with a tab or space.  Both the name and the value must
+be present and non-null.  For most attributes it is meaningless and illegal to
+have multiple attributes with the same name for the same component, but there
+are a few attributes which can be given more than once for a given component.
+Attribute values may contain spaces.
+
+Blank lines are ignored and non-processed comments may appear anywhere in the
+file introduced by a '#' character.  Everything between a '#' character and
+the following newline is ignored.
+
+Here is an example component definition that can appear in the MCL:
+
+J1:
+ device=DB25F
+ footprint=DB25F
+ description=Connector, DB25F, right angle
+ manufacturer=AMP
+ manufacturer_part_number=747846-4
+
+If it is desired to define multiple components with the same attributes, the
+following shorthand syntax may be used:
+
+C43,C44,C45,C46,C47,C48,C49:
+ # Voltage reference capacitors for RS8973
+ # schematic page 6
+ value=0.22 uF
+ footprint=0805
+ description=Ceramic chip capacitor, X7R, 0.22 uF, 0805
+ manufacturer=Panasonic
+ manufacturer_part_number=ECJ-2VB1C224K
+ vendor=Digi-Key
+ vendor_part_number=PCC1816CT-ND
+ bom_comment=RoHS part, no SnPb version available
+
+uEDA tools generally process components in the order in which they are defined
+in the MCL, thus you should list your components in the MCL in the order in
+which you would like them to appear on the BOMs generated from it.  In
+particular, there is no collating function for the refdes string, so if you have
+a collating order in mind for your reference designators, implement it in the
+order in which you list them in the MCL.
+
+Currently defined attributes
+
+bom_comment=
+
+	This attribute specifies a free-form line of text to be included in the
+	procurement BOM (generated by ueda-mkbom) for this part.  This attribute
+	may be given more than once in order to include multiple comment lines.
+	This attribute should be used to include information in the BOM that is
+	not covered by any other defined attributes.
+
+bom_part_title=
+
+	This attribute specifies the title line for this part in the procurement
+	BOM.  Normally the title line is constructed from the manufacturer= and
+	manufacturer_part_number= attributes, but this attribute overrides it.
+
+description=
+
+	This attribute gives a one line summary description of the component for
+	BOMs.  What information should be included is subjective, but one
+	starting point is that uEDA-generated BOMs include the information from
+	the manufacturer= and manufacturer_part_number= attributes, but not from
+	other attributes like value= or footprint=.  Thus if the value and
+	footprint information is desired, it should be included in the
+	description, but don't include the manufacturer or the part #.
+
+device=
+
+	If the component has an associated alphanumeric designation that is
+	universally recognized and meaningful to someone looking at your design
+	at the high level (i.e., without getting down to part numbers), it
+	should be given as the device= attribute.  Examples:
+
+	device=74LS04
+	device=29F010
+	device=41256
+
+	A good general rule of thumb is that if it isn't obvious what to put in
+	the device= attribute, you probably shouldn't have this attribute at all
+	for the component rather than make something up.  In particular, basic
+	semiconductors (diodes and transistors) and passives do not use this
+	attribute.
+
+	The device= attribute is not currently used very much by uEDA tools,
+	but it sometimes provides a fallback for the manufacturer_part_number=
+	attribute if the latter isn't given.
+
+footprint=
+
+	This attribute facilitates the pre-layout step of the uEDA flow.
+	See prelayout.txt for the details.
+
+	A value of "none" indicates that the component has no footprint on the
+	PCB.  I admit that the physical meaning of such a specification is a
+	little unclear, but ueda-getfps will skip such components without error
+	or warning messages.
+
+	A value of "TBD" (to be determined) means that you realise you need a
+	footprint, but aren't able to name it yet.  ueda-getfps recognizes this
+	special value and issues an appopriate warning, but doesn't try to look
+	for an actual footprint named "TBD".
+
+manufacturer=
+
+	Should be self-explanatory.
+
+manufacturer_part_number=
+
+	Should be self-explanatory.  Meaningless without manufacturer= also
+	being specified.
+
+npins=
+
+	In the uEDA model pin numbers are arbitrary alphanumeric strings in the
+	general case, allowing for mixed alphanumeric pin "numbers" used on PGA
+	and BGA packages.  However, most components have simple numeric pin
+	numbers ranging from 1 to some N inclusive.  If your component falls
+	into the latter category, you should define an npins=N attribute.
+	Having this definition makes uschem-netlist(1) run much more
+	efficiently, detect invalid pin numbers and produce naturally sorted
+	pin lists.
+
+part=
+
+	See the Components vs. parts section below.
+
+pcbvalue=
+
+	The PCB layout file format includes 3 ASCII strings for each element:
+	"description" (not really used, uEDA puts the footprint name there),
+	"name on the PCB" (refdes) and "value".
+
+	The pcbvalue= attribute explicitly sets the "value" parameter in the
+	PCB elements generated by the ueda-getfps | ueda-runm4 pipeline (see
+	prelayout.txt).  If the pcbvalue= attribute is not defined, ueda-getfps
+	tries value=, device= and manufacturer_part_number= in this order.  If
+	none of these attributes are given, a null string is used.
+
+pinout=
+
+	This attribute specifies the name of the pinout mapping file to be used
+	for this component.  See the Pinout mapping section in netlisting.txt
+	for the explanation.
+
+population_option=
+
+	See Population options in bom_model.txt.
+
+	The value of this attribute is either a decimal integer identifying the
+	population group this component belongs to or the keyword "NO".
+
+	population_option=NO indicates that the component is never populated at
+	all in any of the standard population options, e.g., a component that
+	is only populated for debug purposes.  Such components appear in the BOM
+	only if -pall is given to ueda-mkbom(1) or ueda-shortbom(1).
+
+socket=
+
+	If the component is to be socketed, this attribute specifies the part ID
+	for the socket.  See the Components vs. parts section below for the
+	explanation of the part ID.
+
+source=
+
+	This attribute indicates a source for the procurement of this part.
+	It may be given more than once to indicate multiple sources where parts
+	can be obtained.
+
+	If one or more source= attributes are given, the vendor= and
+	vendor_part_number= attributes are not used.
+
+substitute=
+
+	This attribute lists an "acceptable substitute" for the part specified
+	by the manufacturer= and manufacturer_part_number= attributes.  This
+	attribute may be given more than once.
+
+	Given the unfortunate reality of part availability, it is often the
+	case that the manufacturer= and manufacturer_part_number= attributes
+	specify the ideal wish list part (e.g., one with SnPb solder coating)
+	while substitute= attributes list what's actually obtainable (e.g., the
+	lead-free crap).
+
+value=
+
+	This attribute is intended to hold the value of components such as
+	resistors and capacitors for which a numeric value is meaningful.  uEDA
+	does not currently make any formal use of this attribute, hence there
+	are no formal rules currently as to units, exact syntax etc.
+
+vendor=
+
+	Should be self-explanatory.  Specifies the name of a vendor from whom
+	the part may be obtained.
+
+vendor_part_number=
+
+	Should be self-explanatory.  Meaningless without vendor= also being
+	specified.
+
+	Unlike source=, the vendor= and vendor_part_number= attributes may not
+	be given more than once.  If multiple sources need to be listed, the
+	source= attribute must be used instead.  Neither vendor= nor
+	vendor_part_number= is used if any source= attributes are present.
+
+Components vs. parts
+
+Contrast the following alternative descriptions of the same component:
+
+* A 0.1 uF capacitor
+* Ceramic chip capacitor, X7R, 0.1 uF, 0805
+* Panasonic ECJ-2VB1C104K
+
+The first description is what you would likely use in the initial design of your
+circuit, the second description may appear on the list of required components
+when your design is finished, and a description of the third kind can be made
+about the components found on the final board when it's fully assembled.
+
+The uEDA MCL makes a distinction between components and parts.  A component is
+something that has a refdes and an associated section in the MCL; a part is
+something that can appear on a procurement BOM with a quantity next to it.
+uEDA also has a process of "reducing components to parts", which basically
+means going from a description of the first kind above to one of the 2nd or 3rd
+kind.
+
+Given that you are free to specify or not specify each of the defined attributes
+for each component in the MCL, your initial design may be as vague or as
+specific as you like.  For example, you may put a capacitor on your schematic
+and list it in the MCL, but not specify anything else.  Or you may specify the
+value while leaving the footprint undecided.  Or vice-versa.  Or you could
+specify both the value and the desired footprint, but put no more thought as
+to what kind of actual capacitor you would need.
+
+However, when it's time to actually build your board, you will have to pick
+some specific part from the Digi-Key catalog (or substitute your favourite
+component supplier), order it and populate it on the board.  That will be a
+specific part with a very concrete set of parametric specifications.  This is
+what I mean by reducing components to parts.
+
+The concepts just described may be self-evident, but the reason I'm spelling
+them out is that uEDA has some special support for reducing components to parts.
+Namely, the MCL syntax that has been described so far is not actually the whole
+story.  If the syntax described so far was all that's available, the process of
+reducing components to parts would be very clumsy.  For example, if you had
+decided that your 0.1 uF bypass caps would be 0805s and that you would order
+and populate Panasonic ECJ-2VB1C104K parts for them, you would have to enter
+the full information about this part for every component (every refdes) in the
+MCL where you had a 0.1 uF bypass capacitor.  This approach would suffer from
+two problems:
+
+* The replication of information would be very redundant and error-prone.
+
+* The process for generating the procurement BOM would face the problem of
+  how to tally all of those separately described components into a quantity of
+  one part.
+
+The uEDA solution is that in addition to components with reference designators,
+the MCL file format allows for part definitions.  A part definition has the
+following form:
+
+part part-ID:
+ attribute=value
+ attribute=value
+ ...
+
+The part-ID is an arbitrary ASCII label for your part.  Component definitions
+can then refer to your part definition by its part-ID using this syntax:
+
+refdes:
+ part=part-ID
+
+Example:
+
+part bypasscap-0.1uF-0805:
+ value=0.1 uF
+ footprint=0805
+ description=Ceramic chip capacitor, X7R, 0.1 uF, 0805
+ manufacturer=Panasonic
+ manufacturer_part_number=ECJ-2VB1C104K
+ vendor=Digi-Key
+ vendor_part_number=PCC1812CT-ND
+ bom_comment=RoHS part, no SnPb version available
+
+C1:
+ # Bypass cap for U5
+ part=bypasscap-0.1uF-0805
+
+Most tools in the uEDA suite treat such part references as nothing more than
+shorthand, in other words, the example above would be equivalent to:
+
+C1:
+ value=0.1 uF
+ footprint=0805
+ description=Ceramic chip capacitor, X7R, 0.1 uF, 0805
+ manufacturer=Panasonic
+ manufacturer_part_number=ECJ-2VB1C104K
+ vendor=Digi-Key
+ vendor_part_number=PCC1812CT-ND
+ bom_comment=RoHS part, no SnPb version available
+
+The one important exception is ueda-mkbom.  For the procurement-oriented BOM
+parts are essential, and ueda-mkbom operates only on parts, not on components.
+When it reads the example above, it takes note of part bypasscap-0.1uF-0805,
+counts all components that refer to it and emits it in the BOM with the counted
+quantity.
+
+What does ueda-mkbom do when it encounters a component that has no part=
+attribute?  It may be either a component that hasn't been reduced to a part yet
+(in which case ueda-mkbom can't do anything with it other than issue a warning
+message), or a component that self-defines its part.  A component is considered
+to self-define a part if it has both manufacturer= and manufacturer_part_number=
+attributes or a bom_part_title= attribute.  Alternatively, a component may be
+explicitly declared to self-define its part with a part=yes attribute (see
+below).
+
+Every part definition (explicit or implicit in a component that self-defines
+its part) that is to be usable to ueda-mkbom must have some attributes from
+which ueda-mkbom can make a title for it in the BOM.  ueda-mkbom considers part
+attributes in this order:
+
+* bom_part_title= if one is given
+* manufacturer= and manufacturer_part_number= if both are given
+* manufacturer= and device= if both are given
+* description= if one is given
+
+If none of the above attributes are present for a part which needs to go into
+the BOM, it is an error.
+
+Formal definition of the part= attribute
+
+The part= attribute may appear only in component definitions and not in part
+definitions.  The value of the part= attribute may be one of the following:
+
+* The keyword "none". This specification indicates that the component has no
+  associated part and that this lack of a part is not an error. Note that it's
+  possible to have a component which has no part but still has a footprint.
+  An example would be a test point or an antenna made from the copper etch on
+  the PCB.
+
+* The keyword "yes". This specification indicates that this component
+  self-defines its part, i.e., that the MCL section being parsed is both a
+  component definition and a part definition.
+
+* A part-ID defined by a part definition earlier in the MCL file.
+
+* A refdes of another component which appears earlier in the MCL file and self-
+  defines its part.
+
+Note that no forward references are allowed.
+
+Component definitions which refer to a part definition may override some of the
+attributes in the latter, as long as such an override is physically meaningful.
+(Overriding the value of a Panasonic ECJ-2VB1C104K cap to something other than
+0.1 uF is not.)  The population_option= attribute is normally set at the
+component level rather than the part level, but other attributes may also be
+overridden sometimes.  For example, a dual position resistor (DPR) may be made
+by taking a standard SMT resistor part (which would contain a footprint=
+attribute for its normal two-pad footprint) and overriding its footprint to
+a DPR footprint with 3 pads.
+
+Socket parts
+
+If a component is to be socketed, the socket part should have its own part
+definition with a part-ID assigned and should be referenced via the socket=
+attribute.