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.