The XCircuit Tutorial Part 2: Schematic Capture

Table of Contents

Getting started

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).

IMPORTANT NOTICE: It is necessary for you to have compiled and installed the distribution version 3.6.66 or better to get the correct behavior in the tutorial.

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 not produce pcb-style netlists as featured in this tutorial.

The way parameters are defined and handled was changed in version 3.1.25. The way info labels for PCB are handled was changed in version 3.6.66. This tutorial reflects the new methods.

The Tcl/Tk-based version of XCircuit is beginning to diverge from the Xw-widget-based version, which lacks the simplicity and convenience of scripting new GUI functions. Any part of the tutorial which describes features available only in the Tcl/Tk version of XCircuit will be preceded by the icon.

Task 1: Acquaint yourself with XCircuit

If you are not yet familiar with the basic features of xcircuit, I recommend you to peruse the basic XCircuit tutorial for essential features of the program which will not be reiterated here.

Task 2: Run the program

XCircuit now starts in schematic capture mode unless explicitly compiled without the feature. So just start xcircuit as you normally would:
xcircuit
Xcircuit's main drawing window has a menu button for "Netlist" and two buttons at the bottom left-hand corner, one of which (normally, on startup) is colored gray and labeled "Symbol", 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). To the right of the Schematic button it says "Editing: Page 1", indicating that the name of the current schematic is "Page 1". This happens to be an invalid name, since most netlist formats and PostScript don't allow names with spaces in them, and XCircuit will tend to complain if you try to write a netlist or save the schematic before changing its name.

Task 3: Drawing a circuit for SPICE simulation

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.
  1. Drag the elements which you need from the "Generic" library page to (a clean) Page 1. Namely, the nMOS, pMOS, Vdd, and GND symbols.

  2. Duplicate elements (copy (c), flip (f)) as necessary and connect with lines to produce the following transconductance amplifier schematic:


    A transconductance amplifier, schematic drawing.

  3. Either drag the "dot" object from the library page or use the period key (".") 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 is 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.

  4. 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:


    Same transconductance amplifier, a little fancier style.

  5. 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 pin labels. 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 appear (that is, you will see them) only on the top level of the hierarchy.

    To generate the pin label, type key macro (capital) T, 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".


    Transconductance amplifier with I/O pins marked.

  6. 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 the technology file "avlsi.lps" (part of the distribution), as the symbol for the schematic you just drew. Go to the "Generic" library, then edit the "wramp" symbol from there by placing the cursor over the "wramp" symbol and typing key macro ">". The result looks like this:


    Transconductance amplifier symbol from the "avlsi.lps" technology file.

    Note that in this picture, the bottom left-hand corner of the screen says "Symbol" in a white button that was, on Page 1, gray, and the button that used to say "Schematic" is now gray. This means that this object is a symbol, not a schematic, and it currently does not have a schematic attached to it.

    Also note that the pin labels marking input/output positions for in.m, in.p, out, and bias 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.

  7. The procedure to attach the schematic to this symbol is quite simple. Choose menu item Netlist->Associate With Schematic. 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.

    A symbol can be disassociated from its schematic, and vice versa, by choosing menu item "Netlist->Disassociate Symbol" or "Netlist->Disassociate Schematic". 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.

    Association can be initiated both ways. The alternate method is as follows: Go back to Page 1 (the amplifier schematic). Choose menu item "Netlist->Associate with Symbol" (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".

    Click on the first library page (the one containing the wide-range amplifier symbol "wramp"). Click on the symbol "wramp". 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 "Netlist->Go To Symbol" (or "Go To Schematic", as appropriate), or use the "/" 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).

    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 "Netlist->Make Matching Symbol" or "Netlist->Make Matching Schematic" 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. The Tcl scripted version of Make Matching Symbol creates a basic rectangular symbol and allows you to choose whether pins are on the left, right, top, or bottom, and takes care of a number of other details. It is not necessary to keep the simple rectangular shape. The symbol may look like anything at all. As long as the pin names correspond between the schematic and the symbol, the circuit will have a proper netlist.

  8. 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:


    Simple continuous-time integrator using a transconductance amplifier.

    Note that there is a "regular" text label titling the page; this is made in the usual fashion, using key macro (lowercase) "t", and therefore is not a pin label.

    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.

    Note that this is one way in which XCircuit differs from many if not most other schematic capture systems, which distinguish between "pins" (ports of the symbol) and "labels" (net name assignments that are not ports). XCircuit makes no such distinction. A name can be assigned to any net in the schematic by connecting a pin label to it. This pin label may or may not appear in the symbol, and may be added to or deleted from the symbol at any time, as required by the circuit design.

  9. Save this page. Call it "integrator". It is important to make sure that both the filename and the page label have been changed from their default ("Page 2") values. Netlist output saves to the name of the "Page label", not the name of the "filename". If you change only the "Page label" or do not actually write the schematic file to disk, you will need to press the "Apply" button(s) for the change to take effect.

    At this point, several points should be noted:

  10. 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 integrator.spc 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 call to the subcircuit has parameters which are the pin labels given on the top level page.

For reference, the resulting PostScript file can be found here: integrator.ps

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.

Also note that many SPICE-based simulators require that "ground" be the net named "0" (zero). XCircuit's "ground" symbol is labeled "GND". Some simulators will require either a zero volt voltage source or a zero ohm resistor between nodes "GND" and "0" to simulate correctly. This can be added specifically to the top-level schematic in XCircuit or added by hand to the output netlist.

Task 4: Introduction to parameters

One thing you may have noticed about the previous circuit is that you did not, in fact could not 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.

Here's a brief description of how parameters work (more information will be revealed in the following tasks):
Each object contains a list of its parameters, stored as key:value pairs. Each key in the pair is a unique name describing the parameter (such as "length", "width", "value", etc.), and the value is the value assigned to the parameter. Each item in the list also declares what is the type of parameter (so far, "string", "integer", or "float"). The values in the object's list are the default values for the parameters.

Every object instance may contain an additional list of parameters, in the same key:value pair format. The keys in this list must match the keys in the object's list. Values in this list represent specific values of the parameters for this instance only. Values in this list override (or "shadow") parameter values in the object.

It is important to keep in mind the distinction between an object and its instantiations. If you are on Page 1 looking at an object you just dragged back from the library, you are looking at a single instance of that object. If you use the > key to edit the object, then you are editing the object itself, but parameters seen and edited are the parameters of the instance, not the default parameters of the object. If you go to the library page and use the > key to edit the library object, parameters seen and edited are the default parameters of the object. This is further complicated by the ability to define library virtual instances, described later in the tutorial.

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 what top-level page you came from. 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 instance, 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.

  1. Run xcircuit, which should automatically load "analoglib3.lps" onto library page 2, titled "Library: AnalogLib".
  2. Go to library page 2 (macro L, 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.


    The parameterized analog component library.

  3. Select, say, the "Resistor" object and drag it back to Page 1.
  4. Copy the resistor so you have two resistors on Page 1.
  5. Edit one of the resistors (> 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.
  6. Edit the string which reads "1.0 k(Ohm)" (e key macro, or menu selection Edit->Edit). 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(n)< text>", where n is the parameter number, and text 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 in the "Text" menu).
  7. 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.
  8. Pop back up to the originating page (< 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".
  9. Go to the library again (L key, then click on the second page), and from there, edit the resistor (> key). From here, change the value to, say, "2.0 k". Note that now you are changing the default value, not an instance value.
  10. Return to the library page (< 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.
    The rule here is that each instance of an object accepts the default unless is specifically declares its own unique value.
How does this work?
There are already traces of parameterization at work in xcircuit, even where parameters are not explicitly defined. 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.

Simplified parameter editing in Tcl-based XCircuit

Beginning with XCircuit version 3.1.25, in the Tcl/Tk-based version, there is an easier way to create and change parameters of an object instance. The Tcl command parameter defines an option -forward that, when present, returns forward-referenced parameters, that is, parameters of a selected object instance instead of parameters of the top-level object. This method can be used to query and set parameters for each object instance in a drawing.

Below is the same task as above, using the simplified method for editing parameters.

  1. Select one of the resistors (mouse button 2), and type key macro Ctrl-p, or the menu button . You will get a pop-up window showing the defined (string) parameters: index (component number), units (metric prefix of the units), and value (the value of the components).
  2. Click on the value of units (whose default is "k", for kiloOhms). You will see the value appear in the text entry area at the bottom of the parameter window, where you can edit the value and change it from "k" to "M" or nothing, or whatever you want the units on your resistor to be. Likewise, you can click on the value entry for key value and change it from "1.0" to whatever you want the resistor value to be. Upon accepting any change, the new parameter will be reflected in the parameter list and on the schematic drawing.
  3. You can also create and delete parameters from the parameter pop-up window, and click on the parameter key in the pop-up window while creating or editing text to insert a parameter into a string. So there are really two different methods for getting a parameter: 1) create a text label, select part of it, and parameterize the substring. 2) create a substring parameter in the parameter pop-up window, then place it into a text string.

Task 5: Virtual library instances

Often, one wants to use a component with a specific, non-default value many times. In such a case, one doesn't want to have to select each object, one by one, and change its parameter value or values. One way to get around this is to make a copy of the object instance in question, which copies the parameter instances along with the rest. However, there is another useful method called virtual library instances. The following tutorial task saves a copy of several transistors of varying length and width:
  1. Go to the AnalogLib library page. Select the nMOS and bring it back to the drawing page. By either method described in the last task, change the width and length parameters from 3 and 2, respectively, to, say, 36 and 1.8.
  2. Now, select the nMOS instance with W=36, L=1.8 (if it is not already selected), and type key macro V (shift-v).
  3. Go to the User Library. There will be a new object on the page, which is a copy of the nMOS transistor with W=36 and L=1.8. To clarify that the values of this transistor are not default values, the name of the object (nMOS), is written in gray rather than black. If you edit the parameters of a library virtual instance, you will not affect the original library object (that is, you will not change the parameter default values).
  4. Click on the library virtual instance and bring it back to the schematic drawing, to confirm that you do indeed get a copy of the device with W=36, L=1.8.
  5. Here's another trick: Rotate the second copy of the nMOS transistor by 45 degrees. Select it, then type key macro V again. Now go to the User Library. Note that a virtual instance has been saved in the orientation of the original, and copies of it keep the same rotation. The same is true for scale as for rotation, although scaling schematic elements is of limited use (and usually looks bad).

Task 6: Drawing a circuit with parameters

  1. Run xcircuit, as in the last example.
  2. Using the parameterized devices from the AnalogLib library page, create the simple lowpass R-C filter shown below:


    Simple R-C filter.

  3. Now, using what you learned from Task 4, alter the individual parameter values so that they look like the following:


    Simple R-C filter, with new parameter values.


    Hint: Use the Ctrl-p method described above for Tcl-based XCircuit.
  4. Choose menu item "File->Write XCircuit PS", and rename the top page something obvious like "filter". Save it if you like.
  5. Choose menu item "Netlist->Write Spice". You can view the resulting SPICE file filter.spc here.

For reference, the finished PostScript file can be found here: filter.ps

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.

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.

Info label escape sequences:

%%
Inserts the character `%' into the netlist output line.
?
When a single question mark is parameterized as its own parameter named "idx" or "index", 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 component 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.
(parameter)
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 "index" or "idx" parameter with default value (?) is a special case (see above).
%n
Insert the name of the object.
%p"pin_name"
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). The name of the pin may even be parameterized, which is useful for generating different pin numberings for several instances of the same gate in an IC package.
%r
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 "Text->Insert->Carriage Return".
%t
Insert a tab into the netlist output line.
%f"name"
(XCircuit version 3.6 and newer only) Insert the contents of file name into the output. This will happen whenever an instance of the object is encountered while generating the netlist output. name may include the tilde ("~") character to indicate a home directory, and it may include Tcl variable names (in the non-Tcl version, variable names beginning with "$" refer to shell environment variables).
%F"name"
(XCircuit version 3.6 and newer only) This command works like the %f escape, except that the file is included exactly once, the first time an instance of the object is encountered while writing netlist output. Normally, this will be used to include an entire netlist definition for the object, or model definitions for a process. In these cases, prefix the info label with, for example, "spice@1:", where the "@" character indicates that the label should be inserted into the netlist before, and outside of, any subcircuit definition.
Deprecated sequences (maintained for backward compatibility):
%i
Insert a number, in sequence, incrementing each time a new object instance is visited during netlist compilation.
%v"name"
Insert the name of a parameter. The parameter name must be quoted exactly as the key in the parameter key:value pair. For backward compatibility with versions before parameters were stored as key:value pairs, the name can be the name of the parameter default value (ignoring escape sequences).
Example: 

sim:n %pG %pS %pD
or: 

spice:M%i %pD %pG %pS GND nmos
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.

Inserting string parameters directly into a label:

There are many instances in which you will want to use a parameter more than once in the same object. In particular, the directives for netlist output (the "info-labels") do not show up except when editing the object itself. If a parameter in the directives is to show up in the output (e.g., component index, transistor width and height, resistor value, etc.), then the parameter must be duplicated. The parameter appears once in the info-label and once in a plain-text label. It is advantageous to have a single parameter used in both places, rather than create two different parameters. While editing a label, use the key sequence "Alt-p" to insert an existing parameter into a string, as an alternative to creating a new parameter with the Text->Parameterize function introduced in Task 15. If the object has only one parameter defined, that parameter will be inserted automatically, because there is no ambiguity as to which parameter to substitute. If the object has two or more parameters, xcircuit will prompt for the one to use. In the Tcl version of XCircuit, this is a pop-up listbox showing each key-value pair that may be inserted into the string. Clicking on the key entry will insert the parameter and pop down the selection listbox.

Once the copy of the parameter string is in the label, it tracks with changes to the same parameter in any other label. Making changes to one automatically changes the other, updated instantaneously. For information labels, 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."

  1. From the default "Generic" library (library page 1), grab the (unparameterized) object "nmos" and drag it back to page 1 (or whatever page you're working on).
  2. Edit the "nmos" object (key ">").
  3. Use the second mouse button to draw a selection box around the word "nmos" in the first information (green) label.
  4. The word "nmos" will be highlighted; in this selection mechanism, only that substring of the label has been selected.
  5. Choose menu option Text->Parameterize.
  6. You will get a pop-up box asking for a name (key) of the parameter. Type "model" into the box and click "Okay".
  7. 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(model)<" and ">". At this point, the SPICE model is a parameter of the object, its key is "model", and its default value is "nmos".
  8. Because you entered the object from Page 1 rather than the Library, what you are editing is the string instance, not the string default. Change the parameter substring to read nmos1, indicating an alternate MOS model called "nmos1" (which must be added to the output SPICE file before simulation!). Make sure that the character "1" comes before the ">" parameter end marker; otherwise, it is not part of the parameter, and instead becomes part of the label in every instance of the object, which is not what is intended (alternately, the Ctrl-p key macro described above avoids the problem of accidentally modifying the label outside of the parameter).
  9. Finish editing and return to the calling page (key "<").
  10. Grab another object "nmos" from the library and place it on Page 1. Edit it (key ">"), or type Ctrl-p to view its parameters. Note that the parameter string contains the default value "nmos".
  11. From the schematic page, run "Netlist->Write spice". The resulting file is simple and can be included below.

    Spice circuit Page 1

    M1 net.1 net.2 net.3 GND nmos
    M2 net.4 net.5 net.6 GND nmos1
    .end
Information labels with embedded parameters are used in the technology file analoglib3.lps, normally loaded into the "AnalogLib" library page. 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).

As an addendum to this task, run xcircuit and load the file and generate a spice circuit which uses two nMOS devices from the "AnalogLib" library page, each instance having a different SPICE model. In addition, make the widths of the two devices different.

Multiple info labels per page

One way to get multiple lines of netlist output from a single symbol is to embed carriage-return sequences in the output string (see "aggregate", below in Task15). Another way is to have multiple info labels, beginning with "spice1:", "spice2:", etc. The rules on these are very relaxed; the numbering can start anywhere from zero and up, may skip numbers, etc. The lines will be ordered in the output as they are numbered in the info labels.

Numbered info labels may be interspersed with non-numbered info labels. The ordering of the numbered labels relative to each other will be enforced, although unnumbered labels may appear in the output in any order.

Schematic-level info labels

Usually info labels appear in symbols and indicate the format of electrical components in the netlist. However, it is often helpful to have option or model information in the netlist. This information would normally appear only on the top-level schematic. XCircuit allows info labels to appear on a top-level schematic. These info labels will appear after the initial first line (which is usually a comment line indicating the source file and acknowleging XCircuit as the schematic capture tool) but before any subcircuit or component output. Because ordering may be important, it is possible to specify lines that appear after the subcircuits and components but before the final statement (e.g., ".end" in SPICE), if any. These lines are written, e.g., "spice-1:", "spice-2:", etc. This is the only circumstance in which negative numbers can be used in output line number ordering. In this scheme, line "spice-1:" is output before line "spice-2:", and so forth. Schematic-level info labels were introduced in XCircuit version 3.3 revision 15.

Task 7: Parameter tricks

So far, only the most basic parameter functions have been introduced. These are the substring parameters, and they have been encountered in objects having some obvious parametric function, like units and values of an electrical component. This task introduces the many ways that parameters may be defined and manipulated.

Top-level parameters:

Sometimes it is useful to have parameters on the top-level page. In particular, it may be useful to have one bit of text in several places on the page referencing the same value, so that if one of them is edited, the others update automatically.

The main thing to note about top-level parameters is that each page has only one instance, so "default" and "instanced" values have no meaning for top-level pages. There can be only one value for each top-level parameter. This lack of instances is used to advantage by XCircuit version 3.6 (from revision 120). When a symbol is associated with a schematic, and the symbol and schematic both share a parameter with the same key, then the parameter value of the symbol instance will "shadow" the schematic's parameter when writing flattened netlists. This feature only applies to flattened netlists, and in no other case. Tutorial number 3 further describes this feature, and how to use it.

Dedicated numeric parameters:

There are two main types of parameters: substring parameters, already described in detail, and numeric parameters. Numeric parameters come in two flavors: dedicated and undedicated. A dedicated numeric parameter refers to some specific aspect of an element: The rotation of an object, the start and end angles of an arc, the justification of text, etc. These parameters can be used to make two instances of the same object look different in ways other than simply changing text. Every aspect of every element may be parameterized. The most common use of dedicated numeric parameters is to adjust label placement (rotation, justification, and possibly position) to account for the rotation of an object. The virtual object instances in the analoglib2 library are defined this way, such that each component has one instance aligned vertically, and another aligned horizontally, with the text remaining upright in both instances.

Undedicated numeric parameters:

Undedicated numeric parameters are not attached to any aspect of any element. They behave like string parameters and can be inserted into strings due to type promotion (see below). The main reason to use a numeric parameter in place of a string is so a Tcl script can do arithmetic manipulations on the value.

Indirectly referenced parameters:

Sometimes the parameter you want to change is two (or more) levels deep in the hierarchy. This is best shown by example, so:
  1. Start up XCircuit. Go to the analoglib2 library, select object nMOS, and drag it back to the page.
  2. Edit (> key) the nMOS object.
  3. Select the text string "W=3 L=2"
  4. Do Edit->Make User Object. In the dialog box, select some appropriate name like "mostext".
Now we have an apparent contradiction: Parameters width and length are used both in object nMOS (in the info label), and in the new object mostext which we just created. But we really want them to point to the same parameter! Otherwise, if we change width or length in object nMOS, the change will be reflected in any SPICE decks we create, but the object will still say "W=3, L=2".

  1. Pop back up to the top-level page (< key), select the nMOS FET device, and type Ctrl-p.
  2. In the parameter selection box that pops up, select the Value column entry ("3") for parameter width
  3. Enter, say, "20" in the dialog box, and click "Okay".
  4. Behold! The string value of the label changed! What happened? The "Make User Object" command will create an indirectly referenced parameter in the parent object (here, the object "nMOS") if the selection contains a parameter defined in the parent. The new object gets its own copy of the parameter, with default values, so there is no error in using the new object elsewhere in XCircuit.
  5. Go to the User Library. There you will find "mostext" with its own values "W=3, L=2".
  6. Grab a copy of "mostext" and bring it back to the page. Select it, type Ctrl-p, and change its width to, say, "100". Note that its parameters are entirely independent.
  7. Bring up the Tcl console (File->Tcl console). Edit (> key) the object nMOS, then again (> key) the object mostext.
  8. On the Tcl command line, type
    parameter get width
    You will get back:
    {{Text 20} {End Parameter}}
    This is simply the parameter value and does not reveal the indirect reference.
  9. Now execute the Tcl command
    parameter get width -verbatim
    and this time, you get back:
    width
    which indicates that this parameter is an indirect reference, and inherits the value of parameter width from its parent (in this case, object nMOS).
There are two ways to create indirectly-referenced parameters. One is using "Make User Object", as shown above. The other is the Tcl command-line command "parameter set <key> <refkey> -indirect", which sets the value of parameter key to be an indirect reference to parameter refkey in the parent of the object instance.

Be aware of the indirect parameter reference generation when making new objects. If you do not want indirect parameters, it is best to use the "Make Object" function before defining parameters, and only create parameters when editing the object itself. Since this behavior can be very confusing, it is likely to change in the near future.

Expression parameters:

Perhaps the most powerful type of parameter is the expression parameter. This is available in both Tcl- and non-Tcl-based versions of XCircuit. In the non-Tcl version, an expression parameter is defined as a simple character string, and always evaluates to itself (or rather, an XCircuit string version of itself). In the Tcl version, however, the expression can be any valid Tcl expression. The actual parameter value is determined by evaluating the expression in the Tcl interpreter and promoting the result to an XCircuit string type. This method allows xcircuit to interact strongly with the interpreter. For example, a parameter value may be an expression incorporating a Tcl variable known to a simulation program (such as tclspice), allowing XCircuit to act as a graphical front-end to the simulation.

An example of this can be found in the examples subdirectory of the XCircuit source, file xcclock.ps. This file defines an expression parameter called date on the top-level page. The expression itself is the Tcl command

clock format [clock seconds]
The result of this Tcl command is a string containing the current date and time.
  1. Run XCircuit and load the file xcclock.ps. Note that the date string reflects the current date and time.
  2. Run a PostScript viewer such as ghostview on xcclock.ps. You will see the date and time that the file was saved (January 16, 2004). This is true because the expression parameter executes a Tcl expression, which cannot be evaluated by the PostScript interpreter. When saving the file, XCircuit writes both the Tcl expression (so it can be recovered when reading the file back in) and the last evaluated result of the expression. That is the result that shows up in a PostScript viewer. However, when the file is read back into XCircuit, the Tcl expression is evaluated immediately, and the new result shows up.
  3. This example file also presents instructions to be run in the Tcl interpreter. To do this, select menu option File->Tcl console to bring up the console, and type the code in as instructed, on the Tcl command line (the "%" is the Tcl prompt):
    % proc timedrefresh {} {
    refresh
    after 1000 timedrefresh
    }

    % timedrefresh
    Once the self-refreshing "timedrefresh" function is entered, XCircuit begins refreshing its display once every second. And on each refresh, the Tcl expression is re-evaluated, resulting in a running clock on the XCircuit display. The Tcl "after" command uses an interrupt timer, so this animation does not use up an inordinate amount of compute cycles.
  4. Note that you can continue to draw and manipulate things in XCircuit while the animation is running, even altering the contents of the animated label itself! You can also make copies of the date string, which themselves continue to track the time.
  5. Copy the date label. Then, which the label is still "grabbed", go to the next page ("Page Down" key, or number "2" key). Note that the time and date disappear from the label! This is because the expression parameter date is defined on the "Page 1" object. It is undefined on "Page 2". When the grabbed label passes between pages 1 and 2, it discovers that the parameter key suddenly has no reference, and it promptly deletes the parameter.
  6. Click a mouse button to either place or delete the truncated label.
Expression parameters have one important advantage over normal substring parameters: They can refer to other parameters, even use them in a mathematical expression. The normal way to get the value of a parameter would be to execute the Tcl command "[param get param_key ]. This command is executed in the context of the instance when the instance is drawn or otherwise evaluated (e.g., when generating a netlist). XCircuit adds a shorthand method to refer to the value of a parameter, which is the string "%param_key", that is, the name of the parameter prefixed with a percent sign.

XCircuit specifically understands one special kind of Tcl statement construction that is useful in many situations. Suppose one wants to limit the choices of a parameter to a handful of known values. For example, the parameter name might be "subs" and the only usable values "vdd" and "gnd". The way to do this is to create an expression parameter as follows:

  1. Edit a symbol to which you want to add this parameter.
  2. Click on the icon in the toolbar to get the pop-up parameter menu.
  3. Click on "New...", then choose "Expression". You should get a box with two entry lines, "Parameter name" and "Default value".
  4. In the "Parameter name" box, enter the parameter key, e.g., "subs".
  5. In the "Default value" box, enter the Tcl statement exactly as written below:
    lindex {vdd gnd} 0
    Then click the "Okay" button to accept. You should see the new expression parameter key "subs" in the list of parameters, and the default value "vdd", which is the result of evaluating the above Tcl statement.
  6. Now, click on the "value" field. Instead of the usual entry line, you will instead get a box that lists the two choices "vdd" and "gnd". Click on either of the choices to make that choice the active parameter value.
The two methods described above can be used together. In the "quadparts" library (see below), each component consists of four parts. Only parts 1, 2, 3, and 4 are meaningful, so the parameter "part" uses the construction described above, with the Tcl statement "lindex {1 2 3 4} 0" to set the part number. Each pin in the logic symbol for the component has a different pin number on the package, depending on the part number. So each pin name has been made another expression parameter, with the value, e.g., "lindex {0 1 4 9 12} %part". The pin number is determined by the part number. If you click on the value of parameter, say, "pinA" in the parameter window, you will get the expression, not the choice, because you can't choose the value (you can, however, change the instance value of the expression itself, if there were some reason to do so).

Parameter type promotion:

In general, any parameter type can substitute for any other parameter type. Appropriate conversion takes place when necessary to display or compute the parameter value. So, for example, a transistor object may define its "width" value as an xcircuit string, but an instance of that transistor may compute the width as a Tcl expression. In that case, the result of the Tcl expression will be promoted to an xcircuit string to be displayed in the text. Likewise, numeric values can always be promoted to strings, and strings and expression results will be promoted to numeric types, assuming that a valid number can be parsed from the string or expression result.
  1. Continuing the task above, go to Page 2. In the Tcl console, type the command:
    % parameter make numeric date 2004
    This command creates a new top-level parameter called date on Page 2, defines it as a numeric parameter, and gives it the value 2004.
  2. Return to Page 1, copy the label again, and once again move it to Page 2. This time, the label says:
    Today is: 2004
  3. What just happened? The xcircuit label can only contain string parameters. But it contains a reference to the parameter named date, which is not necessarily a string. On Page 1, parameter date is a Tcl expression. When drawing the label on Page 1, the Tcl command is evaluated, and the result is promoted to an XCircuit string. On Page 2, parameter date is a number. The same label now picks up the number, not an expression, and promotes it to an XCircuit string.
  4. While still grabbing the label, you can continuously flip between pages 1 and 2, and the label will keep re-assigning the parameter as appropriate for the definition of date on each page. However, if you go to any page where date is undefined, the parameter will be stripped out of the label.

Task 8: Making a new "fundamental" object

All netlists generate output when they reach a "fundamental" object, which is defined as an object containing one or more informational labels.

Fundamental objects require several features:

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.

Task 9: A schematic with symbol-less schematics in the hierarchy

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.

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.

The file in the xcircuit source "examples" directory diffamp_test.ps 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.



Differential amplifier sub-schematic: One half of an amplifier.




Differential amplifier complete schematic


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 unannotated version of the schematic can be found here). The annotations, called out by number, are as follows:

  1. Port makes connection to a wire (polygon)
  2. Port makes connection on one side but not on the other
  3. Port makes connection to a label (pin)
  4. Port makes connection to a pin of another object
  5. Two ports in the subschematic get merged into one network
  6. (not shown) Port connects to port on another subschematic
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.

Task 10: Identifying electrical connections

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 Netlist->Highlight Connectivity and the default key binding for the same function is Alt-w. 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.

As an example, load the file diffamp_test used previously in Task 8 (examples/diffamp_test.ps in the XCircuit source distribution). Place the pointer over any wire and type Alt-w. The whole network will be "highlighted" in green. Note some features of connectivity searches:

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).

Note: Network connectivity searches only work as described above in XCircuit version 2.3.5 rev. 1 and later.

Task 11: A symbol on its own schematic

File example "examples/logic8.ps" 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 "logic.spc": 
*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
As you can see, the circuit has been created as intended, and the symbols marked on their own schematics do not present a problem.

Caveat: It is possible to do more subtle forms of recursion. For instance, in the "logic8" 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.

Task 12: "sim" format and flattened netlists

"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.

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 10, above), and the following output "logic.fspc" for the same circuit (generated by Netlist->Write flattened SPICE: 

*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

Task 13: "pcb" type netlists

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).

PCB netlists are fundamentally different from SPICE and sim netlists. Instead of listing by device, the file lists by network. 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.

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.

Consider Harry Eatons's "LED" design which comes as an example in the "PCB" distribution. The relevant files are also linked here:

  1. LED (a PCB-format file)
  2. LED.NET (a PCB netlist file)
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 LED printed circuit layout and netlist. 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 functional pin description. This is not needed for the netlist, but makes it much easier to understand the schematic.
  1. Start up xcircuit on the file FlareLED.ps.
  2. Go to the User Library (the library containing all of the ICs and connectors in the schematic).

    Integrated circuits and components library for FlareLED.

  3. Edit (">" key) the PIC controller (object named "PIC16C54".
  4. 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.
  5. The "PIC16C54" object, like all the integrated circuits in the schematic, has an "info label" which reads 

    
	pcb:U?

    PIC 16C54 object, as edited from the library (default parameters)

  6. Edit this info label ("e" key). Note that the question mark is a parameter.
  7. Escape from the label edit (3rd mouse button) and return to the main page ("1" key). Now edit the same object, the PIC16C54, from this page (">" key).
  8. Now you will see that the info label reads 
    
	pcb:U5
    This is an instance value. It corresponds to the location and label for an IC on the PCB layout.


    PIC 16C54 instance, as edited from the top page (instanced parameters)

  9. End the label edit and return once again to the top level page. From the menu, choose Netlist->Write pcb. The result is a file named FlareLED.pcb. Compare this file to the supplied netlist file named LED.NET. The XCircuit schematic is not complete, but the parts that are correspond in both netlist files.
  10. Challenge: Finish this schematic and show that the two netlists are the same ("Layout vs. Schematic", or "LVS"). If you don't have an LVS program, check the Magic website and click on "Magic 7.2 (development)". There you will find a downloadable version of "netgen", along with instructions on how to use it to compare two netlists.
  11. Another Challenge: Create a 7400-series IC chip from the template in the "ic_templates" library in XCircuit. If you don't want to directly edit the template, be sure to create a copy of it in the User Library by doing a library copy ("C" macro), and edit the copy instead of the template master. Note that there is a library containing the whole 7400 series of ICs in the library repository section, before you waste most of the week trying to create one from scratch.

Task 14: Multiple-gate chips in PCB netlists

Pins could 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.

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.

Using XCircuit 3.6.66 or later, installed, start xcircuit and select the menu option "File->Library Manager". Under "Source Technology File" choose "quadparts". Then, under "Objects", select everything, then click "Load Selected". You may also load the library from the "File->Load Technology (.lps)" menu button, but you will need to know where to find XCircuit's installed libraries (usually /usr/local/lib/xcircuit-3.6/). This is the method you must use for the non-Tcl version of XCircuit, which does not have the Library Manager window. No, go to the last library page (the "User Library"). You will see the following set of objects:



View of the "Quadparts" library (from XCircuit-3.6.66).


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.



Editing a library virtual copy (instance) of gate "quadnand".


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:


Delay Flip-Flop using the "quadparts" library.


After building the circuit, select all of the gates, then select the icon (parameters) to get the parameter selection window. Then select "?" (the value of parameter "index") and type in the new value "1". This gives all of the parts the same index number, indicating that all the parts belong to the same chip. As of this writing (version 3.6.67), if you use the "autonumber" feature, XCircuit will assign a different chip number to each part. Manually setting the component indices of each part is necessary to get the valid PCB netlist shown below. Beginning with version 3.6.67, XCircuit compares pin names when it sees two components with the same index, and will allow any number of component symbols to be labeled, say, "U1", provided that no two symbols have the same name for any pin.

Now, select Netlist->Write pcb. The result is a valid PCB netlist for the circuit: 

VDD         U1-14
GND         U1-7
D           U1-12
CLK         U1-10   U1-13
int7        U1-4    U1-9   U1-11
int10       U1-2    U1-8
Q           U1-1    U1-6
!Q          U1-3    U1-5
XCircuit version 3.6.66 differs from previous versions in the handling of the "quadparts" library. First, note the special info label string in each part, "pcb:U? 7=GND 14=VDD". The notation "pin=net" is used to declare pin assignments to global networks. In this case, it is used to tell the PCB netlister which pins connect to ground and power (7 and 14, respectively). These pins are used only once per chip, as you can see in the netlist.

Task 15: Modifying netlist formats

The Tcl and Python interpreters are supposed to make new netlist formats easy to implement. However, this requires a good deal of script writing, and there are currently no examples to show. As it stands, netlists must be one of three formats:
  1. Flattened ("sim" or SPICE)
  2. Hierarchical (with subcircuits in SPICE "subckt" format)
  3. Netlist (flattened, in a PCB netlist format)
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 Task 5.

Modifications to netlist formats can be useful in several ways:

  1. Implement a completely different netlist type (some subset of VHDL, for instance)
  2. Modify an existing format (hspice or pspice syntax vs. ordinary Berkeley spice3).
  3. Avoid explicitly drawing circuit schematics for simple devices.
  4. Write output at the gate level instead of the transistor level.
The last two require some explaining, so start up xcircuit and prepare for another task.

Aggregate output per device

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.
  1. Go to the first library page and drag back an inverter to the first page.
  2. Add some pin labels to the input and output nodes. Call them, say, "in" and "out" (or something less boring, if you prefer).
  3. Edit the inverter device (> key)
  4. Start an "info label" (I key, or Netlist->Make Info Pin from the menu)
  5. Type
    sim:n %pIn GND %pOut<Alt-Enter>p %pIn Vdd %pOut
    where "<Alt-Enter>" is the key combination Alt + Enter (also available using the menu selection Text->Insert->Carriage Return). 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 will end up in the netlist output, as a real carriage return/newline. The result is shown below.


    Inverter with informational label for "sim" netlist output.

  6. 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 Netlist->Write sim. The netlist output will look something like the following: 
    
| sim circuit "aggregate" from XCircuit v2.30
n in GND out
p in Vdd out
  7. 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.

Output not on the device (transistor) level

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.
  1. Repeat the above task through number 4.
  2. Write for the info label
    spice:X%i %pIn %pOut inverter
  3. Return to the top level page, and write a SPICE netlist. The netlist output will look something like the following: 
    
*SPICE circuit "aggregate" from XCircuit v2.30

X1 in out inverter
.end
  4. While this deck is not directly simulatable, it only awaits the insertion of an inverter model in the form of a subcircuit.

Task 16: Example: A bridge rectifier for a PCB

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.

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.

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.

For more information about bridge rectifiers, see Horowitz and Hill, The Art of Electronics, 2nd edition, pages 45 and following (Cambridge Press, 1989).

Step 1

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: analoglib2.lps, 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).

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 (l key macro), and edit the diode symbol (> key macro). Change the pin names to "1" and "2" (edit, or e key) to match PCB naming conventions. Finally, add an "info label" for the PCB netlister (I key, or else create a normal label then select menu item Netlist->Convert Label To...->Info label). The label text should be 


   pcb:D?
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 Text->Parameterize. 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.



Return to a drawing page (< key, 1 key to go to Page 1) and continue with Step 2.

Step 2

Go to the library (l 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 (c 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 (r 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.



Step 3

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.



Make a schematic out of the rectifier by selecting all the components drawn so far, typing m 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.

Step 4

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 "-").



Connect the transformer and the rectifier together as shown.



Step 5

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.

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.

Typographical note:
The best way to do this is to change the font of the whole string from "Times-Roman" to "Times-RomanISO" (use menu option Text->Encoding->ISO-Latin1 or, while editing the label, use the Alt-e 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.

Netlist note:
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.




Step 6

Connect all the parts together on the top level page as shown.



Add finishing touches, and the completed bridge rectifier should look something like the one shown below.



The xcircuit file can be obtained here: bridge.ps.

Step 7

Select menu option File->Write XCircuit PS and select a "Page label" for the file. This will be the name used by the netlist generator for the netlist file name.

Generate the PCB netlist by selecting menu option Netlist->Write pcb. The result is shown below:


   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

and can also be obtained from this link: bridge.pcb.

Step 8

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.

Go to an empty page (Page 2, perhaps) and generate the following figure:




Labels in black are normal text (created with the t key), and labels in red are pins (created with the T key). After drawing, select everything and put it all into an object (m key). Name the object "power_supply".

Step 9

Now go back to Page 1, the bridge rectifier schematic. Choose the menu selection Netlist->Associate with Symbol. 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.

Step 10

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: powersup.ps):



Go to menu selection File->Write XCircuit PS and rename the "Page label" to "powersup". Then select Netlist->Write pcb to generate a new PCB netlist.

Now look at the result: 


   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

which can also be obtained from this link: powersup.pcb. 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.

Task 17: Bus Representation in XCircuit

No schematic capture package worth its salt fails to handle some representation of buses, and XCircuit now does this (as of revision 3.2.19, posted May 20, 2004). In my usual style for working out XCircuit methods, I have tried to be very liberal about allowing numerous styles of bus notation to be handled.

Virtually all EDA tools recognize buses by some obvious representation like

busname(x:y)
which indicates a bus of (y - x + 1) separate nets that is drawn with a single wire. In a netlist format that doesn't allow buses, this bus will be expanded into its individual nets:
busname(x)
busname(x + 1)
busname(x + 2)
...
busname(y)
Note that the above expansion assumes that x < y, but that need not be the case.

  1. The file examples/buses.ps in the XCircuit distribution (and with a link to a copy of it here) shows an example of a simple PCB-style circuit using buses. Load this circuit into XCircuit and take a look at it. This shows the "normal" way of representing buses, using the tap object.



  2. You can get accustomed to the bus notation by pointing the cursor at various things on the screen and typing Alt-w to look at the connectivity. In particular, all the individual nets of the primary bus mynet have been spelled out in a box on the left. Look at the connectivity of each of these nets in turn by typing Alt-w with the cursor over each label. Do the same for the other labels in the schematic. The figure above shows mynet(4) highlighted.

    Note that individual wires can represent more than one net, but they can be grouped in different ways. If you select the wire connecting to the capacitor top mynet(4), and highlight its connectivity, you will also get the nets mynet(4:3) and mynet(0:7) highlighted, because both of these networks include the individual net mynet(4). If you highlight the connectivity of the label mynet(3), you will also highlight the nets mynet(4:3) and mynet(0:7), but not mynet(4), which is separate. When you highlight the connectivity, you will also get a report in the message window at the bottom of the screen spelling out all the individual nets that have been selected.

  3. In the example file, none of the sub-buses have labels. How does XCircuit know which nets to tap off from the bus? The answer is that it's all done in the tap object (the little black triangle between the master bus mynet(0:7) and the individual tap nets).

    Edit one of the tap objects by typing ">" with the mouse cursor directly over the tap. Return to the top level schematic ("<" key) and do the same for the other taps. You will note that each tap has a different text label on the right-hand side. This is a parameterized label, and can take a different value for each individual tap.




    The tap object works much like the jumper and circle objects; the object does nothing more than to merge together nets that connect to its pins. However, the bus notation together with the parameterized label allows one of the two tap pins to be a subset of the other. Normally, the net on the pointed end of the tap would be a subset of the net on the other end, but this not need be the case. For instance, you can declare one end of the tap to be bus(0:7) and the other to be bus(7:0), thus effectively reversing the order of the individual bus nets as the bus crosses the tap.

    For the tap to work, it is necessary that the part of the bus name outside of the parentheses match for both pins. For example, if the pins are called data(0:7) and address(0:7), they will not make a tap. The name of the bus does not have to match the name of the bus on the top level schematic; in this example file, the default tap name of bus creates a tap for the bus named mynet in the top level. It is only the relative ordering of the subnet numbers that is important. The topmost tap that has the internal labels bus(0:7) and bus(0) would generate the same netlist if it had the labels bus(1:8) and bus(1).




  4. There are several different methods that will all generate valid netlist outputs with bus notation. Do the following to the schematic buses.ps:
    1. Generate the PCB netlist for the schematic. Copy it to a location where you can see it for comparison with netlists generated later in this task. Or, you can use this link for the reference: bustest.pcbnet. 
      
		dVdd        U3-1   U2-4   U1-4
		mynet(7)    U3-2
		mynet(6)    U3-3
		mynet(5)    U3-4
		mynet(0)    U3-9   R1-1
		mynet(3)    U3-6   U1-3
		mynet(4)    U3-5   C1-1   U1-2
		mynet(2)    U3-7   U2-3
		mynet(1)    U3-8   U2-2
		GND         U3-10  R1-2   U2-1   C1-2   U1-1

    2. Delete all of the bus taps.
    3. Move the four labels to the left of the subnets such that they are connected to the respective wires.
    4. Generate the PCB netlist, and compare to the original. It should be the same. Declaring each subnet or sub-bus of a bus by explicitly labeling it is just as good as using a tap.
    5. Now, adjust the subnet wires so that they actually touch the bus. Generate the netlist again. XCircuit will generate a warning for each of the touching subnets, as an alert that buses of different sizes appear to be connected. However, XCircuit recognizes these connections as invalid and ignores them. Thus, the netlist remains the same.
    6. Return to the original buses.ps (with the taps in place). Confirm the statement above that only the relative order of the subnets in the tap object is significant by changing the numbering of the label in the top tap from bus(0:7) to bus(1:8) on the left side, and from bus(0) to bus(1) on the right side. Generate the netlist again and compare.
    7. Now, edit the label that says mynet(0:7) to say only mynet. Generate the netlist again. The netlist is still the same! Although the label does not have bus notation, the tap objects clearly identify the wire as a bus of 8 nets. If the direction of the bus is not called out (0:7 vs. 7:0), then XCircuit assumes that the direction is not critical, and defaults to 0:7.
    8. Finally, remove the label for mynet altogether. Generate the netlist one last time. The netlist is no longer the same; however, it is functionally the same netlist, as the only difference is that XCircuit has generated an arbitrary node name (something like int6(0:7)) for the bus.
  5. Bus direction is important where buses connect to objects further down in the hierarchy. Note that in the schematic buses.ps, parts of the master bus mynet connect to the equivalent bus inputs on two different instances of object ic2. However, the bus taps have been used to flip the wires of the master bus such that in one case, mynet(1:2) connects to ic2 pins 2 and 3, in that order, whereas mynet(3:4) connects to ic2 pins 3 and 2, in that order. You can confirm that the netlist changes if you change the text on the left-hand side in the second tap object from the top, from "bus(1:2)" to "bus(2:1)" (thus swapping the two nets in that sub-bus) and regenerating the netlist.

    One thing to note here is that the object ic2 groups two of its pins togther as a bus input. Because the pins are numbered, they don't have names, and so the text (2:3) suffices to declare the group of two pins to be a bus. Unlike other uses of bus notation, though, the parentheses do not show up in the netlist output. Instead, they follow the usual pin numbering notation for PCB nets: U2-2 and U2-3, for example.




Task 18: Using the Library Manager

The structure of XCircuit library pages was originally designed for use with analog design; at least it suffices to say that the visual representation of the library only works well with a limited number of objects per library page, and navigating the library system works well only with a limited number of library pages. The introduction of some large libraries like the 7400-series parts quickly revealed a part-management problem. To get rid of this problem, the Tcl version of XCircuit has a "Library Manager" window, which can be used to see what parts are in a library and to load specific parts from a library.

The Library Manager window looks like the figure below:




The Library Manager window is divided into four sections and a button bar:
Source Library
This is the XCircuit .lps-format library (on disk) from which objects will be loaded. It is a button; if you press it, you will get a list of library files to choose from.
Target Library
This is the name of the library page in XCircuit where objects will be placed when loaded. It is a button; pressing it will reveal a list of all the library pages in XCircuit.
Search Directories
This is a list of directories where the Library Manager will look for .lps files.
Objects
Once a Source Library has been selected, all of the objects defined in the library will appear in the Objects window. Specific objects may be selected for loading from this window.
Menu Bar:
The menu bar has four buttons, which work as follows:
Add Directory
This button allows you to add more entries to the search list in the "Search Directories" window.
Add New Library Page
This button allows you to create a new library page in XCircuit. It does the same thing as the menu selection Window->Go To Library->Add New Library in the XCircuit main drawing window.
Load Selected
Once objects have been selected in the "Objects" window, press this button to load them from the library file into the target library page.
Show Loaded
Normally, the XCircuit Library Manager removes objects which are already loaded into XCircuit from the list in the "Objects" window. If you select this option button, all objects in a library will be listed, regardless of whether or not they have already been loaded into XCircuit.
Here are some simple directions to get used to using the Libary Manager:
  1. Select menu option File->Library Manager to pop up the Library Manager window.
  2. By default, the "Source Library" is "analog". Note that the "Objects" window is blank: this is because all the objects in the "analog.lps" library were loaded into XCircuit on startup. Push the "Show Loaded" option button. You will see all of the objects in the analog library listed, in alphabetical order (which is not the same order as they are found on the library page). Turn off "Show Loaded" before going to the next step.
  3. Push the button Add New Library Page. In the popup window, at the prompt, type "7400 series" for the library name (or anything you prefer). Once you hit return or the "Okay" button, xcircuit will immediately switch to this new library page.
  4. Select the target library by clicking on the button saying "User Library" and choosing the new library "7400 series".
  5. Now, push and hold the mouse button on the Library Manager button where the library name "analog" is shown. You will see a list of all the libraries that come with the XCircuit distribution, not all of which are loaded into XCircuit on startup.
  6. Choose the library "series74xx". You will now see all of the objects in that library in the "Objects" window, starting with "dil_7400".
  7. Select some of the objects in the "Objects" window. You can select multiple objects by holding the mouse button down while you drag the cursor down the list. If you press the "Shift" key when you press the button, you can select everything between the last selection and the current cursor position. If you press the "Control" key when you press the mouse button, you can select non-contiguous items from the list (see the Tk manual page for the "listbox" widget for details on the selection mechanism).
  8. After you have selected a few objects, press the "Load Selected" button. You will see all the selected objects appear on the XCircuit library page. At the same time, they are removed from the "Objects" list in the Library Manager. An example is shown below.



Back to the xcircuit home page. . .

email:

Last updated: August 5, 2016 at 6:59pm