1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
|
<HTML>
<HEAD>
<STYLE type="text/css">
H1 {color: maroon}
H2 {color: #007090}
H3 {color: #0050b0}
A.head {color: #0060a0}
</STYLE>
</HEAD>
<TITLE>XCircuit Schematic Capture Tutorial Page</TITLE>
<BODY BACKGROUND=../giffiles/blpaper.gif>
<H1><IMG ALIGN=top SRC=../xcicon.gif> The XCircuit Schematic Capture Tutorial</H1>
<!--
<HR>
<font color=red>
<IMG SRC=../giffiles/constr.gif ALIGN=middle>
NOTICE: Page still under construction (but almost finished)!
</font>
-->
<HR>
<H2>Table of Contents</H2>
<UL>
<LI> <A HREF="#Start">Getting Started</A>
<LI> <A HREF="#Task1">Task1</A> Acquaint yourself with XCircuit
<LI> <A HREF="#Task2">Task2</A> Run the program
<LI> <A HREF="#Task3">Task3</A> Drawing a circuit for SPICE simulation
<LI> <A HREF="#Task4">Task4</A> Introduction to parameters
<LI> <A HREF="#Task5">Task5</A> Drawing a circuit with parameters
<LI> <A HREF="#Task6">Task6</A> Making a new "fundamental" object
<LI> <A HREF="#Task7">Task7</A> A schematic with symbol-less schematics
in the hierarchy
<LI> <A HREF="#Task8">Task8</A> Identifying electrical connections
<LI> <A HREF="#Task9">Task9</A> A symbol on its own schematic
<LI> <A HREF="#Task10">Task10</A> "sim" format and flattened
<LI> <A HREF="#Task11">Task11</A> "pcb" type netlists
<LI> <A HREF="#Task12">Task12</A> Multiple-gate chips in PCB netlists
<LI> <A HREF="#Task13">Task13</A> Modifying netlist formats
<LI> <A HREF="#Task14">Task14</A> Example: A bridge rectifier for a PCB
</UL>
<H2><A NAME="Start">Getting started</A></H2>
This tutorial is provided to help users get up and running with the
schematic capture capabilities of xcircuit.
In order to get the most out of this page, you should have already
downloaded, compiled, and installed the xcircuit program and its libraries,
and xcircuit should be compiled with schematic capture capability (on by
default; see the Imakefile for details). <P>
<BLOCKQUOTE>
<font color=red> IMPORTANT NOTICE: </font>
<font color=green>
It is necessary for you to have the new (version 2.3.3) distribution of xcircuit
compiled <I>and installed</I> to get the correct behavior in the tutorial.
In particular, the PostScript prolog has changed and if the old one is
prepended to the new xcircuit files, the files will not be printable or
viewable from a PostScript previewer. <P>
There are additional differences between versions 2.1(beta) to version 2.3.3,
mainly in the way symbols and schematics are associated with each other.
The new methods are incorporated into this tutorial. Version 2.3.3 also
corrects some errors in netlist generation, and is generally more stable.
Versions before 2.3.3 will <I>not</I> produce <B>pcb</B>-style netlists
as featured in this tutorial.<P>
</font>
</BLOCKQUOTE>
<H2><A NAME="Task1">Task 1: Acquaint yourself with XCircuit</A></H2>
If you are not yet familiar with the basic features of xcircuit, I recommend
you to peruse the basic <A HREF=tutorial.html>XCircuit tutorial</A> for
essential features of the program which will not be reiterated here.
<H2><A NAME="Task2">Task 2: Run the program</A></H2>
XCircuit now starts in schematic capture mode unless explicitly compiled
without the feature. So just start xcircuit as you normally would:
<BLOCKQUOTE>
<B>xcircuit</B>
</BLOCKQUOTE>
Xcircuit in schematic capture mode will start with a window which
has a menu button for ``Netlist'' and two
buttons at the bottom left-hand corner, one of which is blank and the other
which is colored red and labeled ``Schematic.''
The bottom buttons can be interpreted to mean that the current page is a
schematic drawing, and this schematic has no corresponding symbol (more
about this later). <P>
There is a menu button, "Options->Disable (Enable) XSchema", which toggles
the visibility of the ``Netlist'' menu button and the two status buttons at the
bottom. In case you're working on a drawing which has nothing to do with
schematic capture, you might prefer to have the option disabled. This
does not affect the program in any way other than to make the buttons
disappear so that xcircuit looks like the original version without the
schematic capture features. <P>
<H2><A NAME="Task3">Task 3: Drawing a circuit for SPICE simulation</A></H2>
This task outlines some of the features of xcircuit used to make a simple
circuit. In this and the following tasks, you will create an analog
circuit, an operational amplifier, and make it into a symbol to be used
as a subcircuit of a more general circuit (an integrator). First you will
draw a circuit using simple (default) devices, and later I will show how to
pass parameters to devices, such as width and length of individual MOSFETs.
<OL>
<LI> Drag the elements which you need from the built-in library to
(a clean) Page 1. Namely, the nMOS, pMOS, Vdd, and GND symbols. <P>
<LI> Duplicate elements (copy (<B>c</B>), flip (<B>f</B>)) as necessary
and connect with lines to produce the following transconductance
amplifier schematic: <BR><BR>
<CENTER><IMG SRC=giffiles/amp1.gif><BR>
A transconductance amplifier, schematic drawing. </CENTER> <BR>
<LI> Either drag the "dot" object from the library page or use the
period key ("<B>.</B>") to place connections between the wires
at junctions. This is not strictly necessary, as xcircuit will
deduce connectivity from the T-connections of wires, not from
the "dot" symbols; it is merely a matter of preference depending
on the style with which you like to draw circuits. In the case
of wires crossing at a junction, the dot <I>is</I> necessary
since crossing wires generally do not indicate a connection in
schematic diagrams. You may also use a "jumper" object to
indicate that two crossing wires do not connect although this,
like the use of dots at T-junctions, is a matter of style and
personal preference. <P>
<LI> Add "circle" connections at the inputs and outputs. Once again,
this is a matter of style; the actual inputs and outputs from
the netlist's point of view will be indicated by pin labels
(see next step). The resulting diagram looks like the following:
<BR><BR>
<CENTER><IMG SRC=giffiles/amp2.gif><BR>
Same transconductance amplifier, a little fancier style. </CENTER> <BR>
<LI> Because the amplifier will be a SPICE subcircuit, it is necessary
to tell the netlist generator where the input and output ports
are. For this, you need <I>pin labels</I>. Pin labels differ
from ordinary labels in several ways: By default, they are
colored red (though this can be changed), and are placed with a
slight offset from their marked positions, so the position
marker can be used as a tag to indicate what wire the label is
attached to. Additionally, the marked position is visible on
the drawing, since its exact location with respect to wires is
critical to the resultant netlist. Finally, pin labels only
appear on the top level of the hierarchy. <P>
To generate the pin label, type key macro (capital) <B>T</B>, or
choose menu item "Netlist->Make Pin". Set justification as
desired and place the "x" marking the pin position over the
"o" of the circle objects, or on top of a wire. The pins in
this amplifier will be labeled "in.m", "in.p", "out", and "bias".
<BR><BR>
<CENTER><IMG SRC=giffiles/amp3.gif><BR>
Transconductance amplifier with I/O pins marked. </CENTER> <BR>
<LI> Now it's time to turn this schematic into a symbol, that is,
to make a symbol which will be used on the top-level drawing
to designate the transconductance amplifier. What we really
want to do is to use the symbol "wramp" (stands for "wide
range (transconductance) amplifier", which is what this is),
from library "avlsi.lps" (part of the distribution), as the
symbol for the schematic you just drew. Go to the built-in
library, then edit the "wramp" symbol from there by placing
the cursor over the "wramp" symbol and typing key macro
"<B>></B>". The result looks like this: <BR><BR>
<CENTER><IMG SRC=giffiles/wramp1.gif><BR>
Transconductance amplifier symbol from the "avlsi.lps" library.
</CENTER><BR>
Note that in this picture, the bottom left-hand corner of
the screen says "Symbol" in the button that was, on Page 1, blank,
and the button that used to say "Schematic" is now blank. This
means that this object is a symbol, not a schematic, and it currently
does not have a schematic attached to it. <P>
Also note that the pin labels marking input/output positions for
<font color=red>in.m</font>,
<font color=red>in.p</font>,
<font color=red>out</font>, and
<font color=red>bias</font>
are invisible on the library page, but become visible when
editing the object, that is, when the library object has been placed
on the top-level page. When the library object is used in a circuit,
the pin labels are again invisible. This way, the drawing doesn't
get cluttered up with nested labels. <P>
<LI> The procedure to attach the schematic to this symbol is quite
simple. Choose menu item <I>Netlist->Associate With Schematic</I>.
Immediately, you will be taken to the page directory, with the
message "Click on schematic page to associate." With the first
mouse button, click on Page 1 (assuming that's the amplifier
schematic). Instead of the usual behavior on the page directory
(go immediately to the page under the cursor), you will be
returned back to the amplifier symbol edit page.
Now both buttons appear at the same time, one named "Symbol" and
one named "Schematic". The one named "Schematic" is colored white,
indicated that the current page is the symbol, and that a
schematic exists which is the circuit represented by this symbol.
Press either button, and you will go to the schematic drawing
(back to Page 1). Press either button again, and you will return
to the symbol. The library object "wramp" is now a symbol for
the schematic of Page 1. <P>
A symbol can be <I>disassociated</I> from its schematic, and
vice versa, by choosing menu item
<I>"Netlist->Disassociate Symbol"</I> or
<I>"Netlist->Disassociate Schematic"</I>.
This menu option will appear only for the appropriate case.
Choose this action from the menu now. Note that the white button
in the lower left-hand corner goes back to being blank. The
library object "wramp" is no longer a symbol for the schematic
of Page 1. <P>
Association can be initiated both ways. The alternate method is
as follows: Go back to Page 1 (the amplifier schematic).
Choose menu item <I>"Netlist->Associate with Symbol"</I> (note
that this is the same button that used to be "Disassociate").
You are transported to the library directory, with the instructions
in the message window to "click on the library page, then the
object to associate". <P>
Click on the first library page (the one containing the wide-range
amplifier symbol "wramp"). Now click on the symbol "wramp".
Now, you will be returned to the original schematic page, and
once again, the buttons in the window's lower-left-hand corner
are red and white, indicating that you are on the schematic page
(red) but can move to the symbol page (white). Alternately to
clicking buttons to move between pages, you can choose menu
item <I>"Netlist->Go To Symbol"</I> (or "Go To Schematic",
as appropriate), or use the "<TT>/</TT>" key macro. Note that
the key macro only works if an association exists (i.e., it will
never create a new schematic or symbol, as described in the next
paragraph, although this was formerly the behavior in xcircuit
version 2.1(beta)). <P>
The schematic and symbol both do not need to exist before association.
You can associate an existing schematic to a non-existing symbol
or associate an existing symbol to a non-existing schematic by using
the <I>"Netlist->Make Matching Symbol"</I> or
<I>"Netlist->Make Matching Schematic"</I> selection, respectively.
If you are editing a symbol, then you will be transported to the first
blank top-level page. If you are editing a schematic (top-level
page), a new User Library symbol will be generated and you will
be transported there. In either case, the new object will take
the name of its associated object, and all pin labels from the
original will be copied to the new, so that's one less step you
have to do yourself.
<LI> Now it's time to use the symbol as a subcircuit in a top-level
circuit schematic. Go to Page 2, which will be the top-level
circuit. Draw an integrator as shown below: <BR><BR>
<CENTER><IMG SRC=giffiles/integrate1.gif><BR>
Simple continuous-time integrator using a transconductance
amplifier. </CENTER> <BR>
Note that there is a "regular" text label titling the page;
this is made in the usual fashion, using key macro (lowercase)
"<B>t</B>", and therefore is not a pin label. <P>
There is a one-to-one correspondence between the
pin labels on the schematic and the pin labels on the
corresponding symbol. This is important to make sure that
the wires attaching to the symbol on the top-level schematic
go to the correct destinations in the amplifier's schematic.
It is not an error to have unassigned pins: A pin inside
the schematic may be labeling a net for reference purposes
only. A pin on the symbol which is not used in the
schematic is much less likely, but may, for instance, be
representing an unconnected pin on an IC. <P>
<LI> Save this page. Call it "integrator". At this point, several
points should be noted:
<UL>
<LI> Two pages were saved instead of one. XCircuit followed
the path of the symbol to its schematic, and saved the
schematic for the amplifier. This becomes a separate
page in the PostScript output. Running "ghostview" or
your favorite PostScript previewer shows the two-page
output.
<LI> Page 1, the page containing the schematic of the amplifier,
regardless of what you called it in the first place (if
anything), was renamed "wramp".
By convention, the schematic and symbol have the same
name, although this does not have to be the case.
<LI> All the pages got saved as "Full Page" and not as
"Encapsulated". For multi-page files, "Encapsulated"
PostScript is not meaningful. Options for positioning
the schematic on the page will probably appear in the
future.
</UL> <P>
<LI> Go to the top-level schematic page (Page 2, or "integrator").
From the menu, select "Netlist->Write Spice". The message
label will read "spice netlist saved as integrator.spc".
You can view the file <A HREF=netfiles/integrator.spc>integrator.spc</A>
here. Note in particular that xcircuit has generated a
hierarchical netlist, using the amplifier "wramp" as a
subcircuit. The subcircuit contains parameters which are
its pin labels; the <I>call</I> to the subcircuit has parameters
which are the pin labels given on the top level page. <P>
</OL>
For reference, the resulting PostScript file can be found here:
<A HREF=psfiles/integrator.ps>integrator.ps</A><P>
SPICE simulation: Xcircuit provides only the netlist. It can also
provide voltage sources and so forth, which will be described in the
next task. However, it has no concept of "models" and provides no
commands for running analyses. In the example above, the spice file
will need to be edited to insert models for devices "nmos" and "pmos",
Declare a voltage source and value for Vdd, and add commands
for DC operating point determination and transient analysis. <P>
<H2><A NAME="Task4">Task 4: Introduction to parameters</A></H2>
One thing you may have noticed about the previous circuit is that you
did not, in fact <I>could not</I> specify a value for the capacitor,
which defaulted in the spice netlist to 1.0pF. And there was no way
to specify a width and length of each nMOS and pMOS device. You might
have guessed: There does exist a way to pass values such as capacitance
to the capacitor object, and width and length to the MOS device objects. <P>
Here's a brief description of how parameters work:<BR>
Each object contains a list of its parameters, NULL if there are no
parameters. Each item in this list declares what is the <I>type</I> of
parameter (so far, "string" or "integer", with only string types fully
supported at present), a default value for the parameter, and another
list which points to all the locations where the parameter gets
substituted. <P>
It is important to keep in mind the distinction between an <I>object</I>
and its <I>instantiations</I>. If you are on Page 1 looking at an object
you just dragged back from the library, you are looking at a single
<I>instance</I> of that object. If you use the <B>></B> key to
edit the object, then you are editing the object itself. Normally,
there is no particular need to make the distinction. However, when
using parameters, the object itself will declare the default parameter,
but each instance of the object may contain its own unique value for
that parameter. <P>
Xcircuit adopts a method for editing parameters in which either the
default value or the instance value may be altered, and which one is
altered depends on <I>what top-level page you came from</I>. The
most obvious way to implement this is that if you edit an object from
one of the library pages, you are assumed to be altering the default
(the object on the library page always displays the default value of
all its parameters). If, instead, you edit the object by getting
there from a top-level page or another object, you are editing the
<I>instance</I>, and changes you make to the parameters will only
affect the value of that instance only. This should be made clear
by the tutorial below.
<OL>
<LI> Run xcircuit, which should automatically load "analoglib2.lps"
onto library page 2 (since xcircuit version 2.2.0. Otherwise,
load it from the subdirectory "examples" of the source
distribution).
<LI> Go to library page 2 (macro <B>L</B>, click on second page).
You will see a set of
replacement objects for the basic circuit structures "capacitor",
"resistor", "nmos", etc. The main difference between these and
the original objects is that they contain labels indicating
values. <BR><BR>
<CENTER><IMG SRC=giffiles/alib.gif><BR>
The parameterized analog component library. </CENTER> <BR>
<LI> Select, say, the "Resistor" object and drag it back to Page 1.
<LI> Copy the resistor so you have two resistors on Page 1.
<LI> Edit one of the resistors (<B>></B> key). You will note that,
in addition to pin labels, there are some other strings (called
"info labels") which will be described in detail later.
<LI> Edit the string which reads "1.0 k(Ohm)" (<B>e</B> key macro, or
menu selection <I>Edit->Edit</I>). As you move the
cursor around the string, look at the message window. You will
note that in addition to the usual ASCII characters and string
commands such as font changes, half-space, etc., there is now
an additional embedded command label "Parameter(<I>n</I>)<
<I>text</I>>", where <I>n</I> is the parameter number, and
<I>text</I> is a substring (may be empty) which is the parameter
text. For the resistor, "1.0" is a parameter
describing the value, and "k" is a parameter for the metric
scale prefix. Unlike all other parts of the string, you cannot
delete the parameter delimiter marks (parameters must be
removed from a string with the "Unparameterize" function).
<LI> Replace the substring "1.0" with "20" and replace "k" by "M"
or whatever your favorite resistor value is. Be sure that you
are inside the parameter delimiters when you make the change,
or you will get unexpected results.
<LI> Pop back up to the originating page (<B><</B> key). You will
see that only the resistor which you edited has its values
changed; the other one still has the original (default) values
of "1.0" and "k".
<LI> Go to the library again (<B>L</B> key, then click on the second
page), and from there, edit the
resistor (<B>></B> key). From here, change the value to, say,
"2.0 k". Note that now you are changing the <I>default</I> value,
not an instance value.
<LI> Return to the library page (<B><</B> key). Now the library
object shows the new resistance value, indicating that the
default value was altered. From here, go back to the
originating page (third mouse button). Now you see that the
resistor you altered retained its unique value, but the
resistor you didn't alter changed with the default. <BR>
The rule here is that each instance of an object accepts the
default unless is specifically declares its own unique value.
</OL>
<BLOCKQUOTE>
<font color=red> How does this work?</font><BR>
<font color=green>
There are already traces of parameterization at work in xcircuit.
Each instance of an object has its own unique value for position,
rotation, color, and scale. These can be thought of as parameters.
Whenever xcircuit draws an object instance, it uses the unique
position, rotation, and scale to alter the 2-D transformation
matrix, then recursively calls the object drawing routine on the
object itself. When parameters are present, xcircuit first looks
up any unique values which the object instance might declare, and
substitutes these values into the object itself. If the instance
does not declare a particular parameter, then xcircuit substitutes
the default value. Then xcircuit recursively calls the drawing
routine on the object.
</font>
</BLOCKQUOTE>
<H2><A NAME="Task5">Task 5: Drawing a circuit with parameters</A></H2>
<OL>
<LI> Run xcircuit, as in the last example.
<LI> Using the parameterized devices from the <TT>analoglib2</TT>
library, create the simple lowpass R-C filter shown below:<BR><BR>
<CENTER><IMG SRC=giffiles/filter1.gif><BR>
Simple R-C filter. </CENTER> <BR>
<LI> Now, using what you learned from Task 4, alter the individual
parameter values so that they look like the following:<BR><BR>
<CENTER><IMG SRC=giffiles/filter2.gif><BR>
Simple R-C filter, with new parameter values. </CENTER> <BR>
<LI> Choose menu item "File->Write XCircuit PS", and rename the top
page something obvious like "filter". Save it if you like.
<LI> Choose menu item "Netlist->Write Spice".
You can view the resulting SPICE file
<A HREF=netfiles/filter.spc>filter.spc</A> here.
</OL> <P>
For reference, the finished PostScript file can be found here:
<A HREF=psfiles/filter.ps>filter.ps</A><P>
Although there are no MOS devices in this file, as in the previous task,
the SPICE deck will need to be completed with commands for performing
transient analysis and so forth, unless the file is to be used for
netlist comparison purposes only. <P>
Spice output is determined solely by the ``info labels'' (which are green
by default, and only show up when the object they are in is on the top-level
page), in particular, those that begin with the token ``spice:''. There
are several ``escape sequences'' which have special meaning in this info
label. They begin with the ``%'' character and are summarized below.
Also, string parameters can be inserted directly into the info label, a
process which is described directly after.
<H3>Info label escape sequences:</H3>
<BLOCKQUOTE>
<DL>
<DT> <TT>%%</TT>
<DD> Inserts the character `%' into the netlist output line.
<DT> <TT>?</TT>
<DD> When a single question mark is parameterized as its
own parameter, it is interpreted in the following way: If the
parser encounters a non-default value (i.e., a number), it uses
that number as the index. Otherwise, it generates a unique sequence
number for the object instance. This method is preferred over the
"%i" escape, as it allows each part number to be individually
assigned, if desired.
<DT> <I>(parameter)</I>
<DD> Any parameter may be inserted into the info
label, and therefore takes the value of either the instance string,
if defined, or else takes the value of the default string. The
question mark (<TT>?</TT>) is a special case (see above).
<DT> <TT>%n</TT>
<DD> Insert the name of the object.
<DT> <TT>%p"name"</TT>
<DD> Insert the name of a pin. The pin name must
be quoted exactly as is the label which defines the pin. The quotes
may be omitted if the name contains no white space and is followed
by white space (if in doubt, just use the quotes).
<DT> <TT>%r</TT>
<DD> Insert a carriage-return into the netlist output line.
Carriage-returns can also be inserted directly into the output
by using Alt-Enter or menu option
<I>"Text->Insert->Carriage Return"</I>.
<DT> <TT>%t</TT>
<DD> Insert a tab into the netlist output line.
</DL>
</BLOCKQUOTE>
Obsoleted sequences (maintained for backward compatibility):
<BLOCKQUOTE>
<DL>
<DT> <TT>%i</TT>
<DD> Insert a number, in sequence, incrementing each time
a new object instance is visited during netlist compilation.
<DT> <TT>%v"name"</TT>
<DD> Insert the name of a parameter. The parameter
name must be quoted exactly as the label or label segement which
defines the <I>default</I> parameter. Alternately, a parameter
can be inserted directly into the string during text edit mode
using the "Alt-p" key. This is perhaps more intuitive, because the
value shown is either the default or substituted value, as appropriate,
rather than always listing the default value. The library file
<A HREF=../xcircuit/psfiles/analoglib1.lps>analoglib1.lps</A>,
which is available either
at this link or in the source distribution under the "examples"
directory, makes use of the "%v" method. <TT>analoglib2.lps</TT>
makes use of the direct-insertion method.
</DL>
</BLOCKQUOTE>
<font color=red> <I>Example:</I> </font>
<font color=green>
<BLOCKQUOTE><PRE><TT>
sim:n %pG %pS %pD
</TT></PRE></BLOCKQUOTE>
</font>
<font color=red>
<I>or:</I>
</font>
<font color=green>
<BLOCKQUOTE><PRE><TT>
spice:M%i %pD %pG %pS GND nmos
</TT></PRE></BLOCKQUOTE>
</font>
The top example produces an nMOS transistor line in a "sim" netlist, where
the actual net names inserted into the output file are those which correspond
to the gate, source, and drain pins, respectively. The bottom example does
the same thing for a SPICE netlist file, assuming that the SPICE model will
be called "nmos" (this can be parameterized if more than one model is
required; see paragraph below), and the "%i" sequence ensures that each
transistor gets a different label: M1, M2, M3, and so forth.
<H3>Inserting string parameters directly into a label:</H3>
While editing a label, use the key sequence ``Alt-p'' to insert a parameter.
If the object has only one parameter, it will be inserted automatically. If
the object has two or more parameters, xcircuit will prompt for the one to
use (listed by number). Once the copy of the parameter string is in the
label, there is effectively no difference between the copies: making changes
to one automatically changes the other (although the change may not show up
immediately). In general, this method is clearer than using ``%v'', since
the subsituted string appears directly in the info label rather than
referring back to the default string, so ``what you see is what you get.''<P>
<OL>
<LI> From the default analog library (library page 1), grab the
(unparameterized) object "nmos" and drag
it back to page 1 (or whatever page you're working on).
<LI> Edit the "nmos" object (key "<B>></B>").
<LI> Use the second mouse button to draw a selection box around the
word ``nmos'' in the first information (green) label.
<LI> The word ``nmos'' will be highlighted; in this selection
mechanism, only that substring of the label has been selected.
<LI> Choose menu option <I>Text->Parameterize</I>.
<LI> Now edit the info label. When you get to the word ``nmos'',
you will notice, as printed in the message field at the bottom
of the xcircuit window, that it is bounded by invisible marker
characters ``Parameter(1)<'' and ``>''.
At this point, the SPICE model is a parameter of the object,
and its default value is ``nmos''.
<LI> Because you entered the object from Page 1 rather than the Library,
what you are editing is the string <I>instance</I>, not the
string <I>default</I>. Change the parameter substring to read
<B>nmos1</B>, indicating an alternate MOS model called ``nmos1''
(which must be added to the output SPICE file before simulation!).
Make <I>sure</I> that the character "1" comes <I>before</I> the
">" parameter end marker; otherwise, it is not part of the
parameter, and instead becomes part of the default value.
<LI> Finish editing and return to the calling page (key "<B><</B>").
<LI> Grab another object ``nmos'' from the library and place it on
Page 1. Edit it (key "<B>></B>"). Note that the parameter
string contains the default value ``nmos''.
<LI> Pop back out to Page 1 and run ``Netlist->Write spice''. The
resulting file is simple and can be included below. <BR><BR>
<font color=green>
<TT>
Spice circuit Page 1<BR><BR>
M1 net.1 net.2 net.3 GND nmos<BR>
M2 net.4 net.5 net.6 GND nmos1<BR>
.end
</TT>
</font>
</OL>
Information labels with embedded parameters are used in the library file
<A HREF=../xcircuit/psfiles/analoglib2.lps>analoglib2.lps</A>.
Note that in most objects
("Capacitor", "Resistor"), the parameterized value is in a string and
therefore shows up as part of the circuit diagram. However, others
("PNP", "NPN", where the SPICE model name is parameterized) have the
parameter only in an information label, where it does not show up on
the top-level page. Yet others ("nMOS", "pMOS") contain both (width
and length values appear on the top-level page and are copied into
the information label, but the name of the SPICE model only appears
in the information label). <P>
As an addendum to this task, run xcircuit and load the file and generate
a spice circuit which uses two nMOS devices from the "analoglib2"
library page, each instance having a different SPICE model. In
addition, make the widths of the two devices different.
Note that when more than one string contain the same parameter, editing
one of the values will not be immediately reflected on the screen as
a change in the other(s). Popping back to the level above the object
and returning to edit the object will show all the proper substitutions.
<H2><A NAME="Task6">Task 6: Making a new "fundamental" object</A></H2>
All netlists generate output when they reach a ``fundamental'' object,
which is defined as an object containing one or more informational
labels. <P>
Fundamental objects require several features:
<UL>
<LI> Fundamental objects are expected to be symbols. As in all
symbols, lines are interpreted as part of the symbol drawing,
not as nets. The only ``electrically relevant'' elements on
a symbol are the pins.
<LI> Fundamental objects contain ``info labels'' which tell the
netlist compiler what to do with the information passed to
the object via the pins. Presently, there are three
different "styles" of netlist, named after the primary
format which uses that kind of netlist:
<UL>
<LI> Hierarchical, or ``spice'' netlists
<LI> Flattened, or ``sim'' netlists
<LI> Network, or ``pcb'' netlists
</UL>
Information on each of these netlists is widely available
and distributed with layout and simulation software
packages. In a nutshell, however:
<UL>
<LI> Hierarchical and Flattened netlists both list by
<B>element</B>, with each line of the file consisting
of an element name followed by a list of network names
corresponding to each of the element's pins.
<font color=red>
<BR><I>example:</I>
</font>
<font color=green>
<TT>Q1 net2 D0 gnd npn1</TT><BR>
</font>
indicates that NPN transistor ``Q1'' has a collector
connection to "net2", base connection to "D0", and
an emitter connection to "gnd" (presumably a global
network).
<LI> A Network netlist lists by <B>network</B>, with each
line consisting of a network name followed by a list
of pins in the circuit to which the network connects.
The element names are part of the pin names, with
the circuit hierarchy encoded in the element name by
slashes (`/'), much like a file system directory listing.
<font color=red>
<BR><I>example:</I>
</font>
<font color=green>
<TT> Net3 control/74LS00_1#1-2 display/LED#2-5</TT><BR>
</font>
indicates that the network named "Net3" connects
pin number 2 in the first 74LS00 chip in subcircuit
"control" to pin number 5 of the second LED in subcircuit
"display".
</UL>
<LI> A result of being an object and having an info-label is that the
"Symbol" button is green, indicating a "fundamental" element.
</UL>
There is another type of symbol called a "trivial" symbol. This cannot be
designated from xcircuit. It is only a optimization which tells xcircuit
that an object does not produce output and is not a sub-schematic, and
therefore can be ignored except for the presence of pins. This prevents
the xcircuit netlist generator from wasting time looking for subschematics
or informational labels. Except for saving compute cycles, there is no
other difference between "trivial" and normal symbols. "Trivial" symbols
are declared in the PostScript file with a "% trivial" line.
<H2><A NAME="Task7">
Task 7: A schematic with symbol-less schematics in the hierarchy</A></H2>
A "subschematic" is a special kind of symbol which, unlike other symbols,
contains electrically relevant objects. Really, it's just a grouping of
electrical objects which bypasses the trouble of making a symbol to
represent the grouping. This can be useful, for instance, in drawing
one-half of a differential amplifier and repeating the schematic, flipped
horizontally. <P>
XCircuit is extremely sophisticated in its ability to deal with subschematics.
It will determine how the subschematic is used, searching for input and
output "ports" that link the subschematic to the circuit on the level above. <P>
The file in the xcircuit source "examples" directory
<TT>diffamp_test.ps</TT> is an example of such a file with subschematics.
It represents an obvious situation in which a subschematic is useful: This is
a differential amplifier, so a large portion of the amplifer is duplicated on
the positive and negative sides. <P>
<CENTER><IMG SRC=giffiles/halfamp.gif><BR><BR>
Differential amplifier sub-schematic: One half of an amplifier.
</CENTER> <BR><BR>
<CENTER><IMG SRC=giffiles/fullamp_anno.gif><BR><BR>
Differential amplifier complete schematic
</CENTER> <BR><BR>
The second of the two figures above shows how the half-amplifer subschematic
connects into the differential amplifier schematic. Note that no pins (pin
labels) have been explicitly called out in the subschematic. All connections
are determined from context. Different contexts which xcircuit finds and
interprets are marked with red circles on the differential schematic
(the <A HREF=giffiles/fullamp.gif>unannotated version</A> of the schematic can be
found here). The annotations, called out by number, are as follows: <P>
<font color=red>
<OL>
<LI> Port makes connection to a wire (polygon)
<LI> Port makes connection on one side but not on the other
<LI> Port makes connection to a label (pin)
<LI> Port makes connection to a pin of another object
<LI> Two ports in the subschematic get merged into one network
<LI> (not shown) Port connects to port on another subschematic
</OL>
</font>
On any given schematic page, port connections between symbols, between
subschematics, and from subschematics to symbols and vice versa, may be
from any layer in the circuit hierarchy to any other layer in the circuit
hierarchy. <P>
<H2><A NAME="Task8">Task 8: Identifying electrical connections</A></H2>
XCircuit has the ability to highlight all wires belonging to a single
electrical network. This is a very useful feature for debugging
schematics, finding shorts and open-circuits. The command for
identifying network connectivity is menu selection
<I>Netlist->Highlight Connectivity</I> and the default key binding
for the same function is <B>Alt-w</B>. The key macro operates immediately
on either selected elements or whatever element is nearest the cursor,
while the menu item either operates immediately on any selected element
or prompts for a mouse click on an element to show connectivity for.
If multiple elements are selected prior to choosing the connectivity
function, connectivity will be searched for the first item encountered
in the select list which is part of a valid network. <P>
As an example, load the file <TT>diffamp_test</TT> used previously in
Task 7 (<TT>examples/diffamp_test.ps</TT> in the XCircuit source
distribution). Place the pointer over any wire and type <B>Alt-w</B>.
The whole network will be ``highlighted'' in green. Note some features
of connectivity searches:
<UL>
<LI> Global networks such as ground have all parts of the network
highlighted, even if they are physically separated on the
drawing.
<LI> Network selection is a different from element selection: It is
recursive. In the schematic drawing for "ampl_test" (Page 2),
networks inside the "half_amp" sub-schematic can be selected for
connectivity search, even though for purposes of normal move,
copy, etc., the "half_amp" can only be selected as an entire object.
<LI> Pins can be selected as well as wires, and pins belonging to a
network will be highlighted along with the rest of the network.
<LI> The name of the network is printed in the message window at the
bottom of the xcircuit screen. Hierarchy is relevant: A network
may have a different name depending on whether it is selected on
the top-level schematic, or somewhere down in the schematic
hierarchy. The network name displayed is that name belonging to
the network at the <I>highest</I> level of the hierarchy.
<LI> Additional networks can be highlighted without erasing the original.
To erase one network before starting another, click the right
mouse button once ("Cancel" operation).
</UL>
Currently, there is no method to detect and return a network name for
pin positions connecting two objects (that is, networks which do not
have a polygon or label explicitly attached to them in the schematic
drawing). <P>
<I>Note:</I> Network connectivity searches only work as described above
in XCircuit version 2.3.5 rev. 1 and later. <P>
<H2><A NAME="Task9">Task 9: A symbol on its own schematic</A></H2>
File example "<TT>examples/logic8.ps</TT>" in the source distribution has
an example of a symbol on its own schematic. Run xcircuit on this example
file, and go to page 2, the schematic for the 2-input NAND gate. At the
bottom of the schematic is a picture of the "NAND" symbol. Note that
you can "push" (">" key) into the symbol picture, and then cross over
("/" key) to the schematic, returning to where you started in a circular
manner. You can do this all day until you run out of memory, so it is
not recommended. Fortunately, when xcircuit generates the circuit netlist,
it is not fooled into this recursive path. Instead, it detects the
presence of the recursion and will not treat the symbol picture as part
of the network. You can verify this by generating a SPICE netlist for
circuit "logic8" and reading the resulting file "<TT>logic.spc</TT>":
<FONT color=green>
<BLOCKQUOTE>
<PRE>
*SPICE circuit "logic" from XCircuit v2.30
.GLOBAL Vdd
.GLOBAL GND
.subckt invert Out In
M1 Out In Vdd Vdd pmos
M2 Out In GND GND nmos
.ends
.subckt nand Out In.1 In.2
M1 Out In.1 Vdd Vdd pmos
M2 Out In.1 ext13 GND nmos
M3 ext13 In.2 GND GND nmos
M4 Out In.2 Vdd Vdd pmos
.ends
X1 int1 Pin.1 invert
X2 Pin.4 int1 Pin.2 nand
X3 Pin.5 Pin.2 Pin.3 nand
.end
</PRE>
</BLOCKQUOTE>
</FONT>
As you can see, the circuit has been created as intended, and the symbols
marked on their own schematics do not present a problem. <P>
<I>Caveat:</I> It is possible to do more subtle forms of recursion. For
instance, in the "<TT>logic8</TT>" circuit, redraw the NAND2 schematic so
that the output goes through a buffer made of two inverters. This is
perfectly reasonable, by itself. Now, go to the inverter schematic, and
in place of the nMOS + pMOS stack, put a NAND2 gate with its two inputs
tied together between the In and Out pins. This is also perfectly reasonable,
by itself. However, the two changes taken together try to define the
NAND2 and inverter in terms of each other, which is recursive. Versions
of xcircuit before 2.3.5 rev. 1 will simply crash. Later versions will
detect the error as a suspiciously deep hierarchy, and halt the netlist
process before the processor hits a stack limit. <P>
<H2><A NAME="Task10">Task 10: "sim" format and flattened netlists</A></H2>
"sim" netlists are normally associated with digital VLSI circuits, but they
also can be useful for netlist comparisons of digital, analog, and mixed-signal
VLSI circuits. The standard "sim" format defines device types for nFET
(enhancement and depletion) and pFET transistors, resistors (explicitly
defined and lumped), and capacitors. However, the format has variously
been extended to cover other devices such as bipolar transistors, and any
variation of any component, provided it gets a unique letter assigned for
the device and is meaningful to whatever software uses the format downstream. <P>
The main difference between "sim" and "SPICE" netlists is that SPICE allows
hierarchical descriptions containing subcircuits, whereas "sim" is by
definition a "flattened" version of a circuit. There is very little that
is necessary to say here, other than to note the ability of XCircuit to
generate flattened circuit netlists. XCircuit also has an option to
generate flattened SPICE. Note the difference in output, for instance,
between the output "logic.spc" for circuit "logic8" (shown in Task 9, above),
and the following output "logic.fspc" for the same circuit (generated by
<I>Netlist->Write flattened SPICE</I>:
<FONT color=green>
<BLOCKQUOTE>
<PRE>
*SPICE (flattened) circuit "logic" from XCircuit v2.30
M1 int1 Pin.1 Vdd Vdd pmos
M2 int1 Pin.1 GND GND nmos
M3 Pin.4 int1 Vdd Vdd pmos
M4 Pin.4 int1 nand1/ext13 GND nmos
M5 nand1/ext13 Pin.2 GND GND nmos
M6 Pin.4 Pin.2 Vdd Vdd pmos
M7 Pin.5 Pin.2 Vdd Vdd pmos
M8 Pin.5 Pin.2 nand2/ext13 GND nmos
M9 nand2/ext13 Pin.3 GND GND nmos
M10 Pin.5 Pin.3 Vdd Vdd pmos
</PRE>
</BLOCKQUOTE>
</FONT>
<H2><A NAME="Task11">Task 11: "pcb" type netlists</A></H2>
XCircuit is ostensibly an ideal platform for generating schematic netlists
to compare against PCB (printed circuit board) designs. However, by
default (at least for now), xcircuit libraries are set up primarily for
VLSI layout work, so PCB netlisting requires a little extra work
(because a lot of users want to use XCircuit for PCB netlisting, I'd like
some help putting together libraries of IC's). <P>
PCB netlists are fundamentally different from SPICE and sim netlists.
Instead of listing by <I>device</I>, the file lists by <I>network</I>.
The format is flattened, probably on the assumption that printed circuit
boards have no hierarchy. By default, xcircuit will list device pins
(network connections) by the name of the object followed by a dash and
the name of the pin to which the network connects. Any hierarchy present
in the xcircuit file is flattened by separating layers of the hierarchy
with slashes, as is done for the "sim" format. <P>
For PCB symbols, the name of the object is used as the part name in the
netlist unless the object's symbol has a "pcb:" info label. In addition,
the sequence number of the part is assigned automatically unless declared
as a parameter in the "pcb:" info label. Typically, PCB components are
labeled "U" for integrated circuits, "R" for resistors, "C" for capacitors,
"J" for connectors and jumpers, and so forth. The sequence number for
each part, if automatically generated, will be unique with respect to
the name used for the part in the netlist output.<P>
Consider Harry Eatons's ``<B>LED</B>'' design which comes as an example
in the "PCB" distribution. The relevant files are also linked
here:
<OL>
<LI> <A HREF=pcb/LED>LED</A> (a PCB-format file)
<LI> <A HREF=pcb/LED.NET>LED.NET</A> (a PCB netlist file)
</OL>
Creating the schematic is very complicated, so I've done much of the
work to get you started. Here is an xcircuit file which can be used to
create a (partial, because it's unfinished) netlist to compare
against the <B>LED</B> printed circuit layout and netlist.
<UL>
<LI> <A HREF=pcb/FlareLED.ps>FlareLED.ps</A> (an XCircuit-format file)
</UL>
The important thing to notice about this file is the way components are
handled. Each component has an object name (a generic name, such as
"Resistor" or a part description, such as "LTC490"), text which may or
may not duplicate the title, and text which parameterizes the object
(such as resistor and capacitor values). In addition, each object is
parameterized for use in PCB. This requires a string inside the object,
an "info label" which is interpreted by the pcb netlist generator in
xcircuit. Also inside the object, not visible from the top level
drawing, are pin numbers for each object. For integrated circuits,
there is text on each pin which is a <I>functional</I> pin description.
This is not needed for the netlist, but makes it much easier to understand
the schematic.
<OL>
<LI> Start up xcircuit on the file <A HREF=pcb/FlareLED.ps>FlareLED.ps</A>.
<LI> Go to the User Library (the library containing all of the ICs and
connectors in the schematic).
<CENTER><IMG SRC=pcb/flare_objects.gif><BR>
Integrated circuits and components library for FlareLED.
</CENTER> <BR>
<LI> Edit ("<B>></B>" key) the PIC controller (object named
"PIC16C54".
<LI> You will note several things: This is an 18-pin chip, with pin
labels corresponding to the actual DIP package pin numbers.
Next to each pin number is the functional name for that pin.
On the top level page, only the functional names appear. On
the top level page, the device can be flipped, rotated, etc.,
without regard to the physical PCB layout. It is only necessary
that the networks of wires correctly connect the pins of
all the components.
<LI> The "PIC16C54" object, like all the integrated circuits in the
schematic, has an "info label" which reads <BR><BR>
<font color=green><BLOCKQUOTE><PRE><TT>
pcb:U?
</TT></PRE></BLOCKQUOTE></font>
<CENTER><IMG SRC=pcb/pic_object.gif><BR>
PIC 16C54 object, as edited from the library (default parameters)
</CENTER> <BR>
<LI> Edit this info label ("<B>e</B>" key). Note that the question
mark is a parameter.
<LI> Escape from the label edit (3rd mouse button) and return to the
main page ("<B>1</B>" key). Now edit the <I>same</I> object,
the PIC16C54, from this page ("<B>></B>" key).
<LI> Now you will see that the info label reads
<font color=green><BLOCKQUOTE><PRE><TT>
pcb:U5
</TT></PRE></BLOCKQUOTE></font>
This is an <I>instance</I> value. It corresponds to the location
and label for an IC on the PCB layout. <BR><BR>
<CENTER><IMG SRC=pcb/pic_instance.gif><BR>
PIC 16C54 instance, as edited from the top page (instanced parameters)
</CENTER> <BR>
<LI> End the label edit and return once again to the top level page.
From the menu, choose <I>Netlist->Write pcb</I>. The result
is a file named <TT>FlareLED.pcb</TT>. Compare this file to
the supplied netlist file named <TT>LED.NET</TT>. The XCircuit
schematic is not complete, but the parts that are correspond in
both netlist files.
<LI> <I>Challenge</I>: Finish this schematic and show that the two
netlists are the same (``Layout vs. Schematic'', or ``LVS'').
<LI> <I>Another Challenge</I>: Create an xcircuit library containing
the entire 7400 digital IC series and send it to me so I can
post it on this website.
</OL>
<H2><A NAME="Task12">Task 12: Multiple-gate chips in PCB netlists</A></H2>
Pins can be parameterized beginning in version 2.5.2 (it is allowed in
earlier versions but will cause invalid netlist output). Pins normally
work differently than label strings when making substitutions during
netlist generation; it is the network name which is substituted.
However, PCB-type netlists write pin names directly to the output, and
this is where parameterized pin names can be useful: For example, a
``quad part'' like a 7400 quad NAND chip has four NAND gates which are
identical except for their pin numbers on the package. Normally, a
PCB netlist would declare these as four parts, say, ``U1-1'' through
``U1-4''. By parameterizing all of the pin names, four instances can
be made representing the four gates inside the 7400 chip, each having
the correct pinout. <P>
A method for saving the pinouts of gate subunits in chips was added
to version 2.5.2 along with the meaningful method for generating PCB
netlists from parameterized pin names. This method allows multiple
instances of a single object to appear on the same library page.
These copies should represent the object with different parameter
values. The most common use of this method is to parameterize pins
of a logic gate that is a subunit of a multiple-gate IC, and show
each of the subunits on the library page, where they can be used to
generate a PCB netlist. <P>
Using XCircuit 2.5.2 or later, installed, start xcircuit and go to the
fourth library page ``<B>Library: quadparts</B>''. You will see the
following set of objects (partial view of the library):
<CENTER><IMG SRC=giffiles/quadparts.gif><BR><BR>
Partial view of the ``Quadparts'' library (from preliminary version).
</CENTER> <BR><BR>
Note that there are four copies of each named object. Each of the copies has
the same name, but three of the names are ``shaded out'' in a gray color.
The part with the name written in black is the original library part. It
contains parameters, but like standard library page objects, it displays all
of the default values for these parameters. As in Tasks 4 and 5, editing
parameter values in this library object will change the default values of
those parameters. The objects with the names printed in gray are
called ``virtual objects.'' They act like objects on a page rather than
objects in a library. Parameters in these objects may take on individual
values, and those specific values are copied along with the object when
it is selected and dragged back to a page. <P>
<CENTER><IMG SRC=giffiles/nand4.gif><BR><BR>
Editing a library virtual copy (instance) of gate ``quadnand''.
</CENTER> <BR><BR>
From the library page, grab all four ``quadnand'' objects and bring them
back to Page 1. With the four objects, one can make, for instance, a
delay flip-flop implementation from a single 7400 chip. This is shown
below:
<CENTER><IMG SRC=giffiles/dff.gif><BR><BR>
<A HREF=psfiles/dff.ps>Delay Flip-Flop</A> using the ``quadparts'' library.
</CENTER> <BR><BR>
After building the circuit, select <I>Netlist->Write pcb</I>. The
result is a valid PCB netlist for the circuit:
<FONT color=green>
<BLOCKQUOTE>
<PRE>
!Q U2-2-5 U1-1-3
D U3-3-9
CLK U4-4-13 U3-3-10
int5 U4-4-12 U3-3-8 U2-2-4
int6 U4-4-11 U1-1-2
Q U2-2-6 U1-1-1
</PRE>
</BLOCKQUOTE>
</FONT>
<H2><A NAME="Task13">Task 13: Modifying netlist formats</A></H2>
The Python interpreter is supposed to make new netlist formats easy to
implement. However, the Python interface does not yet include access
to netlist information, so for the moment, netlist formats are limited. <P>
As it stands, netlists must be one of three formats:
<OL>
<LI> Flattened ("sim" or SPICE)
<LI> Hierarchical (with subcircuits in SPICE "subckt" format)
<LI> Netlist (flattened, in a PCB netlist format)
</OL>
Flattened netlists are the easiest to implement new formats in, since
the only structure in the file is determined by the elements themselves
(not counting comment lines, such as the first line that xcircuit writes
to the netlist file). The other two formats contain syntax that is
(currently) hard-coded into xcircuit (the "subckt" command in hierarchical
SPICE, and the entire syntax of PCB). Information about how to write
devices is encoded into ``informational labels'' (otherwise abbreviated
as ``info labels''). The syntax of info labels is described above in
<B>Task 5</B>. <P>
Modifications to netlist formats can be useful in several ways:
<OL>
<LI> Implement a completely different netlist type (some subset of VHDL,
for instance)
<LI> Modify an existing format (hspice or pspice syntax vs. ordinary
Berkeley spice3).
<LI> Avoid explicitly drawing circuit schematics for simple devices.
<LI> Write output at the gate level instead of the transistor level.
</OL>
The last two require some explaining, so start up xcircuit and prepare
for another task. <P>
<H3> Aggregate output per device </H3>
Here, we will change an "inverter" into a fundamental device consisting
of two transistors in the usual CMOS configuration for the inverter.
By default, XCircuit neither attaches schematics to gates nor defines
aggregate (multiple line) output for a gate because there are too many
ways to define a gate. For instance, the inverter could be an nMOS
device with a p-pullup, or it could be a bipolar-based TTL inverter,
etc., ad nauseum.
<OL>
<LI> Go to the first library page and drag back an inverter to the
first page.
<LI> Add some pin labels to the input and output nodes. Call them,
say, "in" and "out" (or something less boring, if you prefer).
<LI> Edit the inverter device (<B>></B> key)
<LI> Start an "info label" (<B>I</B> key, or <I>Netlist->Make Info Pin</I>
from the menu)
<LI> Type <BR>
<TT>sim:n %pIn GND %pOut</TT><Alt-Enter><TT>p %pIn Vdd %pOut</TT><BR>
where "<Alt-Enter>"
is the key combination Alt + Enter (also available using the
menu selection <I>Text->Insert->Carriage Return</I>).
Note that spaces, tabs, and other characters will transfer
to the netlist output, although embedded commands such as color,
font, and size change will not.
The embedded carriage return <I>will</I> end up in the netlist
output, as a real carriage return/newline. The result is shown
below. <BR><BR>
<CENTER><IMG SRC=giffiles/aggregate.gif><BR>
Inverter with informational label for "sim" netlist output.
</CENTER> <BR>
<LI> Return to the top level page, choose "File->Write Output" to
change the name from "Page 1" to something more useful.
Then, from the menu, select <I>Netlist->Write sim</I>.
The netlist output will look something like the following: <BR>
<font color=green>
<BLOCKQUOTE>
<PRE><TT>
| sim circuit "aggregate" from XCircuit v2.30
n in GND out
p in Vdd out
</TT></PRE>
</BLOCKQUOTE>
</font>
<LI> If you return to editing the symbol "invert", you will find
that after writing the netlist, the "Symbol" button in
the lower left-hand corner of the XCircuit window turned
green, indicating that this symbol is now considered to be
a "fundamental" object. That is, it has an informational
label and contains no subcircuits.
</OL>
<H3> Output not on the device (transistor) level </H3>
Suppose, in the above example, we didn't know or care what is the
transistor-level implementation of the inverter, but wanted a SPICE
file showing the hierarchy, for which an inverter subcircuit could
be inserted at a later point.
<OL>
<LI> Repeat the above task through number <B>4</B>.
<LI> Write for the info label <BR>
<TT>spice:X%i %pIn %pOut inverter</TT>
<LI> Return to the top level page, and write a SPICE netlist.
The netlist output will look something like the following: <BR>
<font color=green>
<BLOCKQUOTE>
<PRE><TT>
*SPICE circuit "aggregate" from XCircuit v2.30
X1 in out inverter
.end
</TT></PRE>
</BLOCKQUOTE>
</font>
<LI> While this deck is not directly simulatable, it only awaits the
insertion of an inverter model in the form of a subcircuit.
</OL>
<H2><A NAME="Task14">Task 14: Example: A bridge rectifier for a PCB</A></H2>
This task will summarize most of what has been covered above in the tutorial
with a practical example, a power supply bridge rectifier for a printed circuit
board layout. The example will work through detailed explanations of each
step, for the benefit of the impatient. <P>
The bridge rectifier is a simple power supply circuit which transforms an AC
supply (e.g., wall outlet) into a DC current for powering a circuit. The
"bridge" is a diode bridge, a loop of four diodes which act as a full-wave
rectifier. The bridge also acts as a nonlinear resistance in a simple
single-pole R-C low-pass filter. The filter pole is set by a large
polarized capacitor on the rectifier output. The larger the capacitor,
the steadier the output voltage, including resistance to short spikes and
dropouts of the AC supply. <P>
Usually the bridge rectifier circuit drives the input of a voltage regulator
to clean up the 120Hz bumps generated by the less-than-ideal lowpass filter,
and to adjust the voltage between the transformer and the circuit being
powered. For simplicity, this example will not consider the voltage
regulator. <P>
For more information about bridge rectifiers, see Horowitz and Hill,
<I>The Art of Electronics</I>, 2nd edition, pages 45 and following
(Cambridge Press, 1989). <P>
<H3>Step 1</H3>
If you have xcircuit version 2.3.3 after revision 6, there will be a
symbol "Diode" (with capital-D) in the analoglib2.lps file (the
second library page). If not, you can update your library from this
link: <A HREF=../xcircuit/psfiles/analoglib2.lps>analoglib2.lps</A>,
and skip to Step 2. Alternatively, you can
use the following instructions to generate the PCB-compatible diode
from the simple diode on the first library page (named "diode", no
capital letter). <P>
The diode symbol "diode" in the first library is not configured for use in
PCBs. This can be changed easily. Go to the first library page (<TT>l</TT>
key macro), and edit the diode symbol (<TT>></TT> key macro).
Change the pin names to "1" and "2" (edit, or <TT>e</TT> key) to match
PCB naming conventions. Finally, add an "info label" for the PCB
netlister (<TT>I</TT> key, or else create a normal label then select
menu item <I>Netlist->Convert Label To...->Info label</I>). The label
text should be
<font color=green>
<BLOCKQUOTE><PRE><TT>
pcb:D?
</TT></PRE></BLOCKQUOTE>
</font>
After creating the label, use the second mouse button to drag a select
box over the question mark. Only the question mark should be highlighted.
Then select menu item <I>Text->Parameterize</I>. As described earlier in
the tutorial, the PCB netlister will use this parameterized string to
determine a part number for the diode, or else the part number can be
explicitly declared by editing the info label from each of the four
instances of symbol "diode" that we will generate.
<CENTER><BR><IMG SRC=giffiles/pcbdiode.gif><BR></CENTER> <BR>
Return to a drawing page (<TT><</TT> key, <TT>1</TT> key to go to Page 1)
and continue with Step 2.
<H3>Step 2</H3>
Go to the library (<TT>l</TT> key, twice to get to the analoglib2 page,
or once if using an edited version of the simple diode, from Step 1)
and select the diode for copying (<TT>c</TT> key).
This action will take you back to the main
drawing page, with a diode instance in tow. While the diode is still
selected, rotate it (<TT>r</TT> key, as many times as necessary).
Place it four times with a click of the first (left) mouse button,
and finish with a click of the third (right) mouse button. Rotate and
position the diodes as shown below.
<CENTER><BR><IMG SRC=giffiles/bridge2.gif><BR></CENTER> <BR>
<H3>Step 3</H3>
Connect the diodes together in a bridge configuration. While the
diode endpoints are not quite on the drawing grid when the diode is
rotated 45 degrees, they are fairly close (as drawn, see figure
above), and there is some "slop" in the netlist generator when
considering whether two wires are connected together. No special
measures are necessary to ensure the connection.
<CENTER><BR><IMG SRC=giffiles/bridge3.gif><BR></CENTER> <BR>
Make a schematic out of the rectifier by selecting all the components
drawn so far, typing <TT>m</TT> to "make" the object, and name
the object "rectifier". This is a "subschematic", as described
above in the tutorial, and pins will be determined from context.
<H3>Step 4</H3>
Grab the transformer symbol from the "analoglib2" library (2nd library
page). Add wires to the transformer input, ending in terminals for
the input AC supply. Name these terminals "V+" and "V-" (typographical
suggestion: use the Symbol font for "+" and "-").
<CENTER><BR><IMG SRC=giffiles/bridge1.gif><BR></CENTER> <BR>
Connect the transformer and the rectifier together as shown.
<CENTER><BR><IMG SRC=giffiles/bridge4.gif><BR></CENTER> <BR>
<H3>Step 5</H3>
Grab two capacitors (one polarized, one not) from the second library
page. These are the capacitors with values listed.
They are already configured for use with a PCB netlist. <P>
The capacitors default to a picofarad value (for use with VLSI
layouts, not PCBs), so the value string needs to be edited to
change this to the "micro" symbol for microFarads. <P>
<font color=red>Typographical note:</font> <BR>
The best way to do this is to change the font of the whole
string from "Times-Roman" to "Times-RomanISO" (use menu option
<I>Text->Encoding->ISO-Latin1</I> or, while editing the label,
use the <I>Alt-</I><TT>e</TT> key combination). The "micro"
symbol (Greek "mu") is available from the font symbol table (accessed
with the backslash key while editing text). The change to ISO
encoding will be necessary on both the value string and the "SPICE"
info label. <P>
<font color=red>Netlist note:</font> <BR>
The SPICE netlist generator will convert the "mu" symbol to the "u"
used by SPICE. This happens regardless of whether the ISO-encoded
"mu" or the Symbol font "mu" is used. Of course, one may also
write ASCII "u" in the value string.
<CENTER><BR><IMG SRC=giffiles/pcbcap.gif><BR></CENTER> <BR>
<H3>Step 6</H3>
Connect all the parts together on the top level page as shown.
<CENTER><BR><IMG SRC=giffiles/bridge6.gif><BR></CENTER> <BR>
Add finishing touches, and the completed bridge rectifier should
look something like the one shown below.
<CENTER><BR><IMG SRC=giffiles/bridge.gif><BR></CENTER> <BR>
The xcircuit file can be obtained here: <A HREF=psfiles/bridge.ps>bridge.ps</A>.
<H3>Step 7</H3>
Select menu option <I>File->Write XCircuit PS</I> and select a "Page label"
for the file. This will be the name used by the netlist generator for
the netlist file name. <P>
Generate the PCB netlist by selecting menu option <I>Netlist->Write pcb</I>.
The result is shown below:<BR><BR>
<font color=red>
<BLOCKQUOTE><PRE><TT>
V- T1-2
V+ T1-1
int5 T1-3 rectifier1/D4-1 rectifier1/D3-2
int6 T1-4 rectifier1/D2-1 rectifier1/D1-2
Vout rectifier1/D3-1 rectifier1/D1-1 C2-1 C1-1
GND rectifier1/D4-2 rectifier1/D2-2 C2-2 C1-2
</TT></PRE></BLOCKQUOTE>
</font>
<BR>
and can also be obtained from this link:
<A HREF=pcb/bridge.pcb>bridge.pcb</A>.
<H3>Step 8</H3>
The example is essentially done, but we can take it one step further
by generating a symbol called "power_supply" to represent this circuit
in a larger schematic. <P>
Go to an empty page (Page 2, perhaps) and generate the following figure:<BR>
<CENTER><BR><IMG SRC=giffiles/powersup.gif><BR></CENTER> <BR>
Labels in black are normal text (created with the <TT>t</TT> key), and labels
in red are pins (created with the <TT>T</TT> key). After drawing, select
everything and put it all into an object (<TT>m</TT> key). Name the object
"power_supply". <P>
<H3>Step 9</H3>
Now go back to Page 1, the bridge rectifier schematic. Choose the menu
selection <I>Netlist->Associate with Symbol</I>. You will be taken to
the library directory. Click (once) on the user library. You will be
taken directly to the user library. Finally, click (once) on the symbol
"power_supply". Now you should be returned to the bridge rectifier
schematic, with the difference that there is a white button labeled
"Symbol" in the bottom left-hand corner of the window. Clicking on the
button toggles the drawing window between the schematic and its
(newly associated) symbol. <P>
<H3>Step 10</H3>
Return to Page 2, the top-level schematic with the "power_supply" symbol.
Try out the following (trivial to the point of uselessness) circuit
(also available at this link: <A HREF=psfiles/powersup.ps>powersup.ps</A>):
<BR>
<CENTER><BR><IMG SRC=giffiles/powersup2.gif><BR></CENTER> <BR>
Go to menu selection <I>File->Write XCircuit PS</I> and rename the "Page
label" to "powersup". Then select <I>Netlist->Write pcb</I> to
generate a new PCB netlist. <P>
Now look at the result: <BR><BR>
<font color=red>
<BLOCKQUOTE><PRE><TT>
NET1 power_supply1/T1-3 power_supply1/rectifier1/D4-1 \
power_supply1/rectifier1/D3-2
NET2 power_supply1/T1-4 power_supply1/rectifier1/D2-1 \
power_supply1/rectifier1/D1-2
In+ power_supply1/T1-1
In- power_supply1/T1-2
Out power_supply1/rectifier1/D3-1 power_supply1/rectifier1/D1-1 \
power_supply1/C2-1 power_supply1/C1-1 R1-1
GND power_supply1/rectifier1/D4-2 power_supply1/rectifier1/D2-2 \
power_supply1/C2-2 power_supply1/C1-2 R1-2
</TT></PRE></BLOCKQUOTE>
</font>
<BR>
which can also be obtained from this link:
<A HREF=pcb/powersup.pcb>powersup.pcb</A>.
Note that the main difference is that the netlist is hierarchical, with
components inside the power supply being referenced by the prepended
name "power_supply1". The resistor, the only component on the top-level
page, is not so prefixed. Throughout the netlist, net names take the
name given in the highest level of the hierarchy. <P>
<HR>
<P><A HREF=../welcome.html><IMG ALIGN=middle SRC=../giffiles/bluebutton.gif
BORDER=0></A> Back to the xcircuit home page. . .
<P><IMG SRC=../giffiles/line1.gif><P>
email: <I>tim@bach.ece.jhu.edu</I>
</BODY>
</HTML>
|
