| blob | a170d6f0e8009f12eb31c9494017224c26785bdd |
3 <html>
4 <head>
10 </head>
11 <body>
16 </div>
17 <!-- EDIT1 SECTION "Symbol guide" [1-28] -->
21 <p>
22 A symbol is a small gEDA file (typically with the file extension “<code>.sym</code>”) that defines the graphical appearance, pins, and inherited attributes of a component. It can be instantiated in a schematic as a component object.
23 </p>
25 </div>
26 <!-- EDIT2 SECTION "General" [29-279] -->
30 <p>
31 Attributes are text objects which follow the pattern “<code>name=value</code>”. They can be attached to a net, pin, or component object, or they can not be attached to anything. This allows five cases:
32 </p>
33 <ul>
34 <li class="level1"><div class="li"> Attributes in a symbol which are attached to a pin define this pin's properties. The four common pin attributes are <code>pinnumber=</code>, <code>pinseq=</code>, <code>pinlabel=</code>, and <code>pintype=</code>. There is no direct way to change these pin attributes from the instantiating schematic, but there's the <a href="geda-gnetlist_ug-slotting.html" class="wikilink1" title="geda-gnetlist_ug-slotting.html">slotting mechanism</a> which allows changing pinnumbers depending on a <code>slot=</code> attribute in the component.</div>
35 </li>
36 </ul>
37 <ul>
38 <li class="level1"><div class="li"> Attributes in a symbol which aren't attached to anything make up the basic attributes of that symbol and are inherited by components instantiating the symbol.</div>
39 </li>
40 </ul>
41 <ul>
42 <li class="level1"><div class="li"> Attributes attached to a component augment the attributes inherited from the symbol. For most attributes, attaching an attribute with the same name as an inherited attribute will override the inherited value, and attaching an attribute with the value “<code>unknown</code>” will remove the inherited value. Some attributes like <code>net=</code> follow more complex rules.</div>
43 </li>
44 </ul>
45 <ul>
46 <li class="level1"><div class="li"> Attributes can be attached to a net. The only attribute for which this is typically done is “<code>netname=</code>”; it makes that net segment part of the net with the specified name, connecting separate net segments with the same <code>netname=</code> attribute to form a single net.</div>
47 </li>
48 </ul>
49 <ul>
50 <li class="level1"><div class="li"> Attributes in a schematic which aren't attached to anything are called “floating”. They aren't too useful, but there are some backends which allow specifying global parameters via floating attributes.</div>
51 </li>
52 </ul>
54 <p>
55 Attributes must not contain a space before or after the “=” sign, and the value must not be empty. If you want to specify an empty value, use “<code>unknown</code>” instead; this is a special value that is treated as “no value” by the netlister.
56 </p>
58 </div>
59 <!-- EDIT3 SECTION "Attributes" [280-2195] -->
63 <p>
64 There are different types of symbols which are treated differently by gEDA/gaf:
65 </p>
67 </div>
68 <!-- EDIT4 SECTION "Symbol types" [2196-2302] -->
72 <p>
73 Regular symbols are the “bread and butter” symbol type. They represent some basic unit—a component, some part of a component, or whatever is appropriate in the context—which can be connected to other such units via nets connected to their pins.
74 </p>
76 <p>
77 Regular components must have a <code>refdes=</code> attribute. If multiple components in a schematic have the same <code>refdes=</code> attribute, they are treated as part of the same package; i.e., there will be a single package in the resulting netlist which contains all the pins and attributes of all the components which share that <code>refdes=</code>. It follows that a pinnumber must me unique, and there must not be attributes with conflicting values (except <code>slot=</code>), within all components which share a common <code>refdes=</code>.
78 </p>
80 <p>
81 It's recommended that regular symbols contain a <code>refdes=</code> attribute with a placeholder value (e.g., “<code>U?</code>”, “<code>C?</code>”, or “<code>R?</code>”) which will be promoted on instantiation. This way, the user just has to replace the “?” with a number and doesn't have to add a <code>refdes=</code> attribute themselves. It is common to add other attributes pre-populated with common or placeholder values, as well.
82 </p>
84 <p>
85 Recommended attributes:
86 </p>
87 <ul>
88 <li class="level1"><div class="li"> <code>refdes=</code> (with a placeholder value; e.g., “U?”, “C?”, or “R?”)</div>
89 </li>
91 </li>
93 </li>
95 </li>
96 </ul>
98 <p>
99 Recommended pin attributes:
100 </p>
101 <ul>
102 <li class="level1"><div class="li"> <code>pinnumber=</code> (required, must be unique; contrary to its name, this doesn't have to be a number)</div>
103 </li>
104 <li class="level1"><div class="li"> <code>pinlabel=</code> (if you want to have an additional label for the pin)</div>
105 </li>
106 <li class="level1"><div class="li"> <code>pinseq=</code> (if used for simulation, or if the symbol is slotted)</div>
107 </li>
109 </li>
110 </ul>
112 </div>
117 <p>
118 If you have a package which contains multiple instances of the same functionality (e.g., a 7400 IC with four NAND gates), it would be inconvenient if you had to create a separate symbol with the correct pinnumbers for each slot. Instead, you can create a single symbol and use the <a href="geda-gnetlist_ug-slotting.html" class="wikilink1" title="geda-gnetlist_ug-slotting.html">slotting mechanism</a> to automatically change the pinnumbers depending on the value of the <code>slot=</code> attribute.
119 </p>
121 </div>
126 <p>
127 Symbols don't have to have pins. If you want to treat some mechanical part (enclosure, screw, unplated or plated hole, copper antenna) as a component which will appear in the layout with its own footprint, you can do so.
128 </p>
130 <p>
131 Plated holes or other parts with electrical connectivity should have a pin that is connected to the appropriate net (e.g. <code>GND</code>) in the schematic so the PCB editor knows about the connection and will warn if the part is connected to the wrong net.
132 </p>
134 </div>
135 <!-- EDIT5 SECTION "Regular symbols" [2303-4965] -->
139 <p>
140 A symbol with a <code>source=</code> attribute is considered a subschematic symbol. As opposed to regular and graphical symbols, pins on subschematic symbols are named via <code>pinlabel=</code> attributes. They still have to have valid <code>pinnumber=</code> attributes, though, which are used as a fallback if hierarchy traversal is disabled.
141 </p>
143 <p>
144 If hierarchy traversal is enabled, gnetlist creates an instance of the schematic file (or multiple schematic files separated with “,”) listed in the <code>source=</code> attribute of each subschematic symbol, replacing the symbol with the contents of the subschematic and connecting the I/O ports in the subschematic with what is connected to the corresponding pins of the subschematic symbol. If <code>refdes=</code> mangling is enabled, the <code>refdes=</code> of subschematic packages is prefixed/suffixed with the subschematic symbol's <code>refdes=</code> depending on the mangling settings.
145 </p>
147 <p>
148 If hierarchy traversal is disabled, subschematic symbols are treated like regular symbols.
149 </p>
151 <p>
152 Recommended attributes:
153 </p>
154 <ul>
156 </li>
158 </li>
159 </ul>
161 <p>
162 Recommended pin attributes:
163 </p>
164 <ul>
165 <li class="level1"><div class="li"> <code>pinnumber=</code> (required, must be unique; only used if hierarchy traversal is disabled)</div>
166 </li>
167 <li class="level1"><div class="li"> <code>pinlabel=</code> (required, must be unique; only used if hierarchy traversal is enabled)</div>
168 </li>
169 </ul>
171 </div>
172 <!-- EDIT6 SECTION "Subschematic symbols" [4966-6247] -->
176 <p>
177 Power symbols indicate that what they are connected to is connected to some named net (usually a power rail; <code>GND</code>, <code>3.3V</code>, etc.). Instead of a <code>refdes=</code> attribute, they have a <code>netname=</code> attribute indicating the name of the net. Pins on power symbols mustn't have a <code>pinnumber=</code> attribute; they shouldn't have any attribute at all.
178 </p>
180 <p>
181 Recommended attributes:
182 </p>
183 <ul>
185 </li>
186 </ul>
188 <p>
189 Recommended pin attributes:
190 </p>
191 <ul>
193 </li>
194 </ul>
196 </div>
201 <p>
202 gEDA/gaf up to version 1.9.2 didn't support proper power symbols. Instead, symbols which has exactly one pin connected to a named net via a <code>net=</code> attribute were allowed not to have a <code>netname=</code> attribute; this marked them as a power symbol.
203 </p>
205 <p>
207 </p>
209 </div>
210 <!-- EDIT7 SECTION "Power symbols" [6248-7057] -->
214 <p>
215 Subschematics are hooked up to the schematic from which they are instantiated via port symbols. Instead of a <code>refdes=</code> attribute, port symbols have a <code>portname=</code> attribute; for each pin on the subschematic symbol, there should be exactly one I/O port in the subschematic whose <code>portname=</code> attribute matches the <code>pinlabel=</code> attribute of the pin. Port symbols mustn't have a <code>pinnumber=</code> attribute on their own pin.
216 </p>
218 <p>
219 Recommended attributes:
220 </p>
221 <ul>
223 </li>
224 </ul>
226 <p>
227 Recommended pin attributes:
228 </p>
229 <ul>
231 </li>
232 </ul>
234 </div>
239 <p>
240 gEDA/gaf up to version 1.9.2 didn't support proper port symbols. Instead, symbols with exactly one pin whose <code>refdes=</code> matched the <code>pinlabel=</code> of the respective pin were used.
241 </p>
243 <p>
245 </p>
247 </div>
248 <!-- EDIT8 SECTION "I/O port symbols" [7058-7889] -->
252 <p>
253 Graphical components convey additional information about a schematic that doesn't change the semantics of the netlist itself. They must have a <code>graphical=1</code> attribute (any other value is invalid) and can't have a <code>refdes=</code> attribute. gEDA/gaf doesn't assign a particular meaning to graphical components but passes them unchanged to netlist backends. Users and backend authors are free to assign any meaning to them. <strong>Contrary to a common misconception, graphical components are NOT ignored by the netlister.</strong> They are collected in a separate list of graphical components which is passed to backends together with the netlist.
254 </p>
256 <p>
257 The most common application of graphical symbols is <a href="#how_do_i_create_a_titleblock_symbol" title=":geda:symbols.txt ↵" class="wikilink1">titleblocks</a> and <a href="#how_do_i_create_an_nc_symbol" title=":geda:symbols.txt ↵" class="wikilink1">NC symbols</a>.
258 </p>
260 <p>
261 Recommended attributes:
262 </p>
263 <ul>
264 <li class="level1"><div class="li"> <code>graphical=1</code> (required; any other value is invalid)</div>
265 </li>
266 </ul>
268 <p>
269 Recommended pin attributes:
270 </p>
271 <ul>
273 </li>
274 </ul>
276 </div>
277 <!-- EDIT9 SECTION "Graphical symbols" [7890-8872] -->
281 </div>
282 <!-- EDIT10 SECTION "FAQ" [8873-8889] -->
283 <h3 class="sectionedit11" id="how_do_i_create_a_titleblock_symbol">How do I create a titleblock symbol?</h3>
286 <p>
287 A titleblock symbol has to have a “<code>graphical=1</code>” attribute so it isn't included in the regular netlist. Apart from that, you can draw it however you like.
288 </p>
290 <p>
291 If you plan to attach title, author, etc. as attributes, it makes sense to add pre-populated attributes to the symbol that will be promoted on instantiation. You are free to choose whatever attribute names seem appropriate; the information entered here is available to but isn't currently used by netlist backends.
292 </p>
294 </div>
295 <!-- EDIT11 SECTION "How do I create a titleblock symbol?" [8890-9418] -->
296 <h3 class="sectionedit12" id="how_do_i_create_a_symbol_for_a_mechanical_part">How do I create a symbol for a mechanical part?</h3>
299 <p>
300 Regular components are the only components listed in the BOM, so if you want to create a symbol for something that should be listed in the BOM, it has to be a regular symbol.
301 </p>
303 <p>
304 This means it is included in the netlist, so it has to have the proper attributes set, including a footprint. Ideally, the footprint would match the physical geometry of the part and provide e.g. a silk outline, but you could also just use a dummy footprint.
305 </p>
307 <p>
308 If the part has electrical connectivity (e.g. a plated hole), it should have a pin that is connected to the appropriate net (e.g. <code>GND</code>) in the schematic. This makes sure the PCB editor knows about the connection and warns if the part is connected to the wrong net.
309 </p>
311 </div>
312 <!-- EDIT12 SECTION "How do I create a symbol for a mechanical part?" [9419-10184] -->
316 <p>
317 An NC symbol is used in a schematic to indicate that some pin shouldn't be connected to anything. Using NC symbols is optional and doesn't have any effect on netlisting; however, if a pin which is connected to an NC symbol is also connected to something else, a DRC error is displayed.
318 </p>
320 <p>
321 NC symbols annotate the netlist with additional information but aren't “parts” by themselves, so they must be graphical symbols. To create an NC symbol, use the following attributes:
322 </p>
324 device=DRC_Directive
325 value=NoConnection</pre>
327 <p>
328 The symbol should have exactly one pin. You can avoid having to create multiple NC symbols for multiple directions by making the pin zero units long. (If you are using gEDA/gaf up to version 1.9.2, there is no way to do this in the <abbr title="Graphical User Interface">GUI</abbr>; you'll have to edit the symbol file manually.)
329 </p>
331 </div>
332 <!-- EDIT13 SECTION "How do I create an NC symbol?" [10185-11048] -->
333 <h3 class="sectionedit14" id="how_do_i_create_a_default_jumper_symbol">How do I create a default jumper symbol?</h3>
336 <p>
337 This depends on whether you want the default jumper to be listed in the BOM and visible in the layout or not.
338 </p>
340 <p>
341 If you want it to be listed in the BOM and/or visible in the layout, treat it as a regular component. This means you'll have to assign it a <code>refdes=</code> and a <code>footprint=</code> and place its footprint on the correct pins of the pin header in the layout.
342 </p>
344 <p>
345 If you don't want it to be listed in the BOM nor visible in the layout, set <code>graphical=1</code> and don't use a <code>refdes=</code> or <code>footprint=</code> attribute.
346 </p>
348 </div>
350 </html>