FreeCalypso > hg > ueda-linux

comparison ueda/doc/mcldoc.txt @ 0:cd92449fdb51

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial import of ueda and ifctf-part-lib from ifctfvax CVS
author Space Falcon <falcon@ivan.Harhan.ORG>
date Mon, 20 Jul 2015 00:24:37 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:cd92449fdb51
1 uEDA Master Component List (MCL) description
2
3 The MCL is an essential component of the design source code in the uEDA flow.
4 It is a human-created and human-edited text file which lists all components on
5 the board being designed and all their attributes. The file must be named
6 "MCL" (w/o quotes) and must reside in the project directory. This document
7 describes the file format and everything you need to know in order to write the
8 MCL for your board.
9
10 Each component on the board must have a reference designator (refdes). Valid
11 characters for the refdes are uppercase and lowercase letters and digits; the
12 first character must be an uppercase letter. Lowercase letters are allowed but
13 not recommended, in particular a refdes should not end in any lowercase letters
14 - see the description of component instances in netlisting.txt for the
15 explanation.
16
17 The MCL contains a section for each component of the form:
18
19 refdes:
20 attribute=value
21 attribute=value
22 ...
23
24 Each refdes line must begin in the leftmost column without leading spaces
25 and end with a colon. It is followed by attribute lines defining various
26 attributes for the component in question; these attributes are the essence of
27 the information contained in the MCL. Different attributes are required by
28 different tools in the uEDA suite and all currently defined attributes are
29 listed in this document. Attributes are name=value pairs and attribute lines
30 in the MCL must begin with a tab or space. Both the name and the value must
31 be present and non-null. For most attributes it is meaningless and illegal to
32 have multiple attributes with the same name for the same component, but there
33 are a few attributes which can be given more than once for a given component.
34 Attribute values may contain spaces.
35
36 Blank lines are ignored and non-processed comments may appear anywhere in the
37 file introduced by a '#' character. Everything between a '#' character and
38 the following newline is ignored.
39
40 Here is an example component definition that can appear in the MCL:
41
42 J1:
43 device=DB25F
44 footprint=DB25F
45 description=Connector, DB25F, right angle
46 manufacturer=AMP
47 manufacturer_part_number=747846-4
48
49 If it is desired to define multiple components with the same attributes, the
50 following shorthand syntax may be used:
51
52 C43,C44,C45,C46,C47,C48,C49:
53 # Voltage reference capacitors for RS8973
54 # schematic page 6
55 value=0.22 uF
56 footprint=0805
57 description=Ceramic chip capacitor, X7R, 0.22 uF, 0805
58 manufacturer=Panasonic
59 manufacturer_part_number=ECJ-2VB1C224K
60 vendor=Digi-Key
61 vendor_part_number=PCC1816CT-ND
62 bom_comment=RoHS part, no SnPb version available
63
64 uEDA tools generally process components in the order in which they are defined
65 in the MCL, thus you should list your components in the MCL in the order in
66 which you would like them to appear on the BOMs generated from it. In
67 particular, there is no collating function for the refdes string, so if you have
68 a collating order in mind for your reference designators, implement it in the
69 order in which you list them in the MCL.
70
71 Currently defined attributes
72
73 bom_comment=
74
75 This attribute specifies a free-form line of text to be included in the
76 procurement BOM (generated by ueda-mkbom) for this part. This attribute
77 may be given more than once in order to include multiple comment lines.
78 This attribute should be used to include information in the BOM that is
79 not covered by any other defined attributes.
80
81 bom_part_title=
82
83 This attribute specifies the title line for this part in the procurement
84 BOM. Normally the title line is constructed from the manufacturer= and
85 manufacturer_part_number= attributes, but this attribute overrides it.
86
87 description=
88
89 This attribute gives a one line summary description of the component for
90 BOMs. What information should be included is subjective, but one
91 starting point is that uEDA-generated BOMs include the information from
92 the manufacturer= and manufacturer_part_number= attributes, but not from
93 other attributes like value= or footprint=. Thus if the value and
94 footprint information is desired, it should be included in the
95 description, but don't include the manufacturer or the part #.
96
97 device=
98
99 If the component has an associated alphanumeric designation that is
100 universally recognized and meaningful to someone looking at your design
101 at the high level (i.e., without getting down to part numbers), it
102 should be given as the device= attribute. Examples:
103
104 device=74LS04
105 device=29F010
106 device=41256
107
108 A good general rule of thumb is that if it isn't obvious what to put in
109 the device= attribute, you probably shouldn't have this attribute at all
110 for the component rather than make something up. In particular, basic
111 semiconductors (diodes and transistors) and passives do not use this
112 attribute.
113
114 The device= attribute is not currently used very much by uEDA tools,
115 but it sometimes provides a fallback for the manufacturer_part_number=
116 attribute if the latter isn't given.
117
118 footprint=
119
120 This attribute facilitates the pre-layout step of the uEDA flow.
121 See prelayout.txt for the details.
122
123 A value of "none" indicates that the component has no footprint on the
124 PCB. I admit that the physical meaning of such a specification is a
125 little unclear, but ueda-getfps will skip such components without error
126 or warning messages.
127
128 A value of "TBD" (to be determined) means that you realise you need a
129 footprint, but aren't able to name it yet. ueda-getfps recognizes this
130 special value and issues an appopriate warning, but doesn't try to look
131 for an actual footprint named "TBD".
132
133 manufacturer=
134
135 Should be self-explanatory.
136
137 manufacturer_part_number=
138
139 Should be self-explanatory. Meaningless without manufacturer= also
140 being specified.
141
142 npins=
143
144 In the uEDA model pin numbers are arbitrary alphanumeric strings in the
145 general case, allowing for mixed alphanumeric pin "numbers" used on PGA
146 and BGA packages. However, most components have simple numeric pin
147 numbers ranging from 1 to some N inclusive. If your component falls
148 into the latter category, you should define an npins=N attribute.
149 Having this definition makes uschem-netlist(1) run much more
150 efficiently, detect invalid pin numbers and produce naturally sorted
151 pin lists.
152
153 part=
154
155 See the Components vs. parts section below.
156
157 pcbvalue=
158
159 The PCB layout file format includes 3 ASCII strings for each element:
160 "description" (not really used, uEDA puts the footprint name there),
161 "name on the PCB" (refdes) and "value".
162
163 The pcbvalue= attribute explicitly sets the "value" parameter in the
164 PCB elements generated by the ueda-getfps | ueda-runm4 pipeline (see
165 prelayout.txt). If the pcbvalue= attribute is not defined, ueda-getfps
166 tries value=, device= and manufacturer_part_number= in this order. If
167 none of these attributes are given, a null string is used.
168
169 pinout=
170
171 This attribute specifies the name of the pinout mapping file to be used
172 for this component. See the Pinout mapping section in netlisting.txt
173 for the explanation.
174
175 population_option=
176
177 See Population options in bom_model.txt.
178
179 The value of this attribute is either a decimal integer identifying the
180 population group this component belongs to or the keyword "NO".
181
182 population_option=NO indicates that the component is never populated at
183 all in any of the standard population options, e.g., a component that
184 is only populated for debug purposes. Such components appear in the BOM
185 only if -pall is given to ueda-mkbom(1) or ueda-shortbom(1).
186
187 socket=
188
189 If the component is to be socketed, this attribute specifies the part ID
190 for the socket. See the Components vs. parts section below for the
191 explanation of the part ID.
192
193 source=
194
195 This attribute indicates a source for the procurement of this part.
196 It may be given more than once to indicate multiple sources where parts
197 can be obtained.
198
199 If one or more source= attributes are given, the vendor= and
200 vendor_part_number= attributes are not used.
201
202 substitute=
203
204 This attribute lists an "acceptable substitute" for the part specified
205 by the manufacturer= and manufacturer_part_number= attributes. This
206 attribute may be given more than once.
207
208 Given the unfortunate reality of part availability, it is often the
209 case that the manufacturer= and manufacturer_part_number= attributes
210 specify the ideal wish list part (e.g., one with SnPb solder coating)
211 while substitute= attributes list what's actually obtainable (e.g., the
212 lead-free crap).
213
214 value=
215
216 This attribute is intended to hold the value of components such as
217 resistors and capacitors for which a numeric value is meaningful. uEDA
218 does not currently make any formal use of this attribute, hence there
219 are no formal rules currently as to units, exact syntax etc.
220
221 vendor=
222
223 Should be self-explanatory. Specifies the name of a vendor from whom
224 the part may be obtained.
225
226 vendor_part_number=
227
228 Should be self-explanatory. Meaningless without vendor= also being
229 specified.
230
231 Unlike source=, the vendor= and vendor_part_number= attributes may not
232 be given more than once. If multiple sources need to be listed, the
233 source= attribute must be used instead. Neither vendor= nor
234 vendor_part_number= is used if any source= attributes are present.
235
236 Components vs. parts
237
238 Contrast the following alternative descriptions of the same component:
239
240 * A 0.1 uF capacitor
241 * Ceramic chip capacitor, X7R, 0.1 uF, 0805
242 * Panasonic ECJ-2VB1C104K
243
244 The first description is what you would likely use in the initial design of your
245 circuit, the second description may appear on the list of required components
246 when your design is finished, and a description of the third kind can be made
247 about the components found on the final board when it's fully assembled.
248
249 The uEDA MCL makes a distinction between components and parts. A component is
250 something that has a refdes and an associated section in the MCL; a part is
251 something that can appear on a procurement BOM with a quantity next to it.
252 uEDA also has a process of "reducing components to parts", which basically
253 means going from a description of the first kind above to one of the 2nd or 3rd
254 kind.
255
256 Given that you are free to specify or not specify each of the defined attributes
257 for each component in the MCL, your initial design may be as vague or as
258 specific as you like. For example, you may put a capacitor on your schematic
259 and list it in the MCL, but not specify anything else. Or you may specify the
260 value while leaving the footprint undecided. Or vice-versa. Or you could
261 specify both the value and the desired footprint, but put no more thought as
262 to what kind of actual capacitor you would need.
263
264 However, when it's time to actually build your board, you will have to pick
265 some specific part from the Digi-Key catalog (or substitute your favourite
266 component supplier), order it and populate it on the board. That will be a
267 specific part with a very concrete set of parametric specifications. This is
268 what I mean by reducing components to parts.
269
270 The concepts just described may be self-evident, but the reason I'm spelling
271 them out is that uEDA has some special support for reducing components to parts.
272 Namely, the MCL syntax that has been described so far is not actually the whole
273 story. If the syntax described so far was all that's available, the process of
274 reducing components to parts would be very clumsy. For example, if you had
275 decided that your 0.1 uF bypass caps would be 0805s and that you would order
276 and populate Panasonic ECJ-2VB1C104K parts for them, you would have to enter
277 the full information about this part for every component (every refdes) in the
278 MCL where you had a 0.1 uF bypass capacitor. This approach would suffer from
279 two problems:
280
281 * The replication of information would be very redundant and error-prone.
282
283 * The process for generating the procurement BOM would face the problem of
284 how to tally all of those separately described components into a quantity of
285 one part.
286
287 The uEDA solution is that in addition to components with reference designators,
288 the MCL file format allows for part definitions. A part definition has the
289 following form:
290
291 part part-ID:
292 attribute=value
293 attribute=value
294 ...
295
296 The part-ID is an arbitrary ASCII label for your part. Component definitions
297 can then refer to your part definition by its part-ID using this syntax:
298
299 refdes:
300 part=part-ID
301
302 Example:
303
304 part bypasscap-0.1uF-0805:
305 value=0.1 uF
306 footprint=0805
307 description=Ceramic chip capacitor, X7R, 0.1 uF, 0805
308 manufacturer=Panasonic
309 manufacturer_part_number=ECJ-2VB1C104K
310 vendor=Digi-Key
311 vendor_part_number=PCC1812CT-ND
312 bom_comment=RoHS part, no SnPb version available
313
314 C1:
315 # Bypass cap for U5
316 part=bypasscap-0.1uF-0805
317
318 Most tools in the uEDA suite treat such part references as nothing more than
319 shorthand, in other words, the example above would be equivalent to:
320
321 C1:
322 value=0.1 uF
323 footprint=0805
324 description=Ceramic chip capacitor, X7R, 0.1 uF, 0805
325 manufacturer=Panasonic
326 manufacturer_part_number=ECJ-2VB1C104K
327 vendor=Digi-Key
328 vendor_part_number=PCC1812CT-ND
329 bom_comment=RoHS part, no SnPb version available
330
331 The one important exception is ueda-mkbom. For the procurement-oriented BOM
332 parts are essential, and ueda-mkbom operates only on parts, not on components.
333 When it reads the example above, it takes note of part bypasscap-0.1uF-0805,
334 counts all components that refer to it and emits it in the BOM with the counted
335 quantity.
336
337 What does ueda-mkbom do when it encounters a component that has no part=
338 attribute? It may be either a component that hasn't been reduced to a part yet
339 (in which case ueda-mkbom can't do anything with it other than issue a warning
340 message), or a component that self-defines its part. A component is considered
341 to self-define a part if it has both manufacturer= and manufacturer_part_number=
342 attributes or a bom_part_title= attribute. Alternatively, a component may be
343 explicitly declared to self-define its part with a part=yes attribute (see
344 below).
345
346 Every part definition (explicit or implicit in a component that self-defines
347 its part) that is to be usable to ueda-mkbom must have some attributes from
348 which ueda-mkbom can make a title for it in the BOM. ueda-mkbom considers part
349 attributes in this order:
350
351 * bom_part_title= if one is given
352 * manufacturer= and manufacturer_part_number= if both are given
353 * manufacturer= and device= if both are given
354 * description= if one is given
355
356 If none of the above attributes are present for a part which needs to go into
357 the BOM, it is an error.
358
359 Formal definition of the part= attribute
360
361 The part= attribute may appear only in component definitions and not in part
362 definitions. The value of the part= attribute may be one of the following:
363
364 * The keyword "none". This specification indicates that the component has no
365 associated part and that this lack of a part is not an error. Note that it's
366 possible to have a component which has no part but still has a footprint.
367 An example would be a test point or an antenna made from the copper etch on
368 the PCB.
369
370 * The keyword "yes". This specification indicates that this component
371 self-defines its part, i.e., that the MCL section being parsed is both a
372 component definition and a part definition.
373
374 * A part-ID defined by a part definition earlier in the MCL file.
375
376 * A refdes of another component which appears earlier in the MCL file and self-
377 defines its part.
378
379 Note that no forward references are allowed.
380
381 Component definitions which refer to a part definition may override some of the
382 attributes in the latter, as long as such an override is physically meaningful.
383 (Overriding the value of a Panasonic ECJ-2VB1C104K cap to something other than
384 0.1 uF is not.) The population_option= attribute is normally set at the
385 component level rather than the part level, but other attributes may also be
386 overridden sometimes. For example, a dual position resistor (DPR) may be made
387 by taking a standard SMT resistor part (which would contain a footprint=
388 attribute for its normal two-pad footprint) and overriding its footprint to
389 a DPR footprint with 3 pads.
390
391 Socket parts
392
393 If a component is to be socketed, the socket part should have its own part
394 definition with a part-ID assigned and should be referenced via the socket=
395 attribute.