2022-10-22 22:52:55 +02:00
|
|
|
<!DOCTYPE html>
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<title>XSCHEM TUTORIAL: CREATE A SYMBOL AND USE AN EXISTING NETLIST</title>
|
|
|
|
|
<link rel="stylesheet" type="text/css" href="xschem_man.css" />
|
|
|
|
|
<style type="text/css">
|
|
|
|
|
/* Local styling goes here */
|
|
|
|
|
p{padding: 15px 30px 10px;}
|
|
|
|
|
</style>
|
|
|
|
|
|
|
|
|
|
</head>
|
|
|
|
|
<body>
|
|
|
|
|
|
|
|
|
|
<!-- start of slide -->
|
|
|
|
|
<div class="content">
|
|
|
|
|
<!-- navigation buttons -->
|
|
|
|
|
<a href="xschem_man.html" class="home">UP</a>
|
|
|
|
|
|
|
|
|
|
<!-- slide title -->
|
|
|
|
|
<h1> TUTORIAL: CREATE A SYMBOL AND USE AN EXISTING NETLIST</h1>
|
|
|
|
|
<p>
|
|
|
|
|
In some cases you have an existing netlist for a circuit block, perhaps from a previous design or
|
|
|
|
|
from a layout parasitic netlist extraction.
|
|
|
|
|
In order to use this netlist in your design you might consider creating a symbol for it in xschem.
|
|
|
|
|
This symbol should match the I/O interface and name of the block netlist and does not need to have
|
|
|
|
|
a corresponding schematic since we want to use the existing netlist.
|
|
|
|
|
One such example in the standard xschem distribution is the test_ne555.sch circuit.
|
|
|
|
|
The test schematic contains a symbol for the popular NE555 timer. The symbol does not provide any
|
|
|
|
|
implementation, the implementation is included in the top design as a .subckt netlist.
|
|
|
|
|
</p>
|
|
|
|
|
<img src="tutorial_use_existing_subckt00.png">
|
|
|
|
|
<p>
|
|
|
|
|
The symbol is implemented in the following way:
|
|
|
|
|
the symbol attributes are:
|
|
|
|
|
</p>
|
|
|
|
|
<img src="tutorial_use_existing_subckt01.png">
|
|
|
|
|
<pre class="code">
|
|
|
|
|
type=primitive
|
|
|
|
|
format="@name @pinlist @symname"
|
|
|
|
|
template="name=x1"
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
the <kbd>primitive</kbd> value for the <kbd>type</kbd> attribute (instead of the more used
|
|
|
|
|
<kbd>subcircuit</kbd> for symbols with a corresponding implementation schematic) tells xschem
|
|
|
|
|
to generate only the instance calls (the X lines for spice netlists) and not descend into the
|
|
|
|
|
symbol and not generate a .subckt for it.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The <kbd>@pinlist</kbd> is expanded into the netlist to the list of I/O ports. The order of the ports in
|
|
|
|
|
this case is the order these pins are created in the symbol. If you click a pin (the small red square box)
|
|
|
|
|
a "<kbd> n = <number></kbd>" appears in the status line. This is the index of the pin. The first
|
|
|
|
|
created pin starts from 0.<br>
|
|
|
|
|
</p>
|
|
|
|
|
<img src="tutorial_use_existing_subckt02.png">
|
|
|
|
|
<ol>
|
|
|
|
|
<li>
|
|
|
|
|
<h3> Changing the pin ordering by altering the object sequence number</h3>
|
|
|
|
|
<p>
|
|
|
|
|
You can change the order the pins are stored into the .sym file.
|
|
|
|
|
Start by clicking the pin that you want to have first in the
|
|
|
|
|
netlist, then press <kbd>Shift-s</kbd>, set the number to 0.
|
|
|
|
|
</p>
|
|
|
|
|
<img src="tutorial_use_existing_subckt03.png">
|
|
|
|
|
<p>
|
|
|
|
|
This will put the selected pin in first position.
|
|
|
|
|
Then move to the pin you want in second position, repeat above steps and assing to it index number 1,
|
|
|
|
|
and so on for all the symbol pins. At the end save your symbol and this will be the pin
|
|
|
|
|
ordering in netlists.
|
|
|
|
|
When netlist is produced this order will be used.
|
|
|
|
|
If left pins in above example have sequence numbers of (starting from the top) 0, 1, 2, 3 and
|
|
|
|
|
right pins have sequence numbers (starting from the bottom) 4, 5, 6, 7 the instance line in
|
|
|
|
|
the netlist will be (check the net names with the schematc in the first image above):
|
|
|
|
|
</p>
|
|
|
|
|
<pre class="code">
|
|
|
|
|
x1 VSS TRIG OUT VSUPPLY CTRL TRIG DIS VSUPPLY ne555
|
|
|
|
|
</pre>
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
<h3> Changing the pin ordering by using the <kbd>sim_pinnumber</kbd> attribute</h3>
|
|
|
|
|
<p>
|
|
|
|
|
If all symbol pins have a <kbd>sim_pinnumber</kbd> attribute
|
|
|
|
|
this symbol will be netlisted (in all
|
|
|
|
|
netlist formats) with pins sorted in ascending order according to <kbd>sim_pinnumber</kbd> value.
|
|
|
|
|
Start value of sim_pinnumber does not matter (may start at 1 or 0) , it is used as the sort key.
|
|
|
|
|
You can assign the sim_pinnumber attribute directly in the symbol...
|
|
|
|
|
</p>
|
|
|
|
|
<img src="tutorial_use_existing_subckt04.png">
|
|
|
|
|
<p>
|
|
|
|
|
... Or you can assign these in the schematic pins, if you use the
|
|
|
|
|
<kbd>Make symbol from schematic</kbd> function ('a' key) these attributes
|
|
|
|
|
will be transferred to the symbol.
|
|
|
|
|
The <kbd>sim_pinnumber</kbd> attributes that determine the netlist port ordering are
|
|
|
|
|
those defined in the symbol.
|
|
|
|
|
</p>
|
|
|
|
|
<img src="tutorial_use_existing_subckt05.png">
|
|
|
|
|
<p>
|
|
|
|
|
For sorting to happen all symbol pins must have a sim_pinnumber attribute.
|
|
|
|
|
If some pins miss this attribute no sorting is done and pin ordering will be unchanged,
|
|
|
|
|
the stored order of symbol pins will be used (first created pin netlisted first).
|
|
|
|
|
If there are duplicate sim_pinnumber attributes (but all pins have this attribute)
|
|
|
|
|
sorting will happen but relative ordering or pins with identical sim_pinnumber is undefined.<br>
|
|
|
|
|
As an example you may give <kbd>sim_pinnumber=9999</kbd> on a symbol output and
|
|
|
|
|
<kbd>sim_pinnumber=1</kbd> on
|
|
|
|
|
all other pins if you only require the output pin to be netlisted at the end
|
|
|
|
|
and don't care about the other pin ordering.
|
|
|
|
|
</p>
|
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<li>
|
|
|
|
|
<h3> Explicitly specify port ordering in <kbd>format</kbd>
|
|
|
|
|
(or <kbd>verilog_format</kbd> or <kbd>vhdl_format</kbd>) string</h3>
|
|
|
|
|
<p>
|
|
|
|
|
Instead of the following format string that defines the netlist instance line syntax:
|
|
|
|
|
</p>
|
|
|
|
|
<pre class="code">
|
|
|
|
|
format="@name @pinlist @symname"
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
You can use the following:
|
|
|
|
|
</p>
|
|
|
|
|
<pre class="code">
|
|
|
|
|
format="@name @@GND @@TRIG @@OUT @@RESETB @@CTRL @@THRES @@DIS @@VCC @symname"
|
|
|
|
|
</pre>
|
|
|
|
|
</p>
|
|
|
|
|
In this case you specify the port order one by one explicitly. This can be used for spice
|
|
|
|
|
primitive devices, spice subcircuits (like this example), VHDL and Verilog primitives.
|
|
|
|
|
This method can NOT be used for VHDL and verilog subcircuits since for these you
|
|
|
|
|
do not provide a <kbd>vhdl_format</kbd> or <kbd>verilog_format</kbd> string.
|
|
|
|
|
For these use one of the first two methods.
|
|
|
|
|
In general for VHDL and Verilog port order is not important since port-net association
|
|
|
|
|
is <b>named</b> and not <b>positional</b>.
|
|
|
|
|
</p>
|
|
|
|
|
</li>
|
2024-01-08 14:57:21 +01:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<a id="spice_sym_def">
|
|
|
|
|
<li>
|
|
|
|
|
<h3> Obtaining the pin ordering from the subcircuit definition specified via <kbd>spice_sym_def</kbd></h3>
|
|
|
|
|
<p>
|
|
|
|
|
For spice netlists if <kbd>@pinlist</kbd> is specified in format string and a symbol <kbd>spice_sym_def</kbd>
|
|
|
|
|
attribute is used then the order of the symbol ports will be obtained from the <kbd>.subckt</kbd> specified
|
|
|
|
|
by <kbd>spice_sym_def</kbd>, either directly or via a <kbd>.include</kbd> statement
|
|
|
|
|
</p>
|
|
|
|
|
<img src="tutorial_use_existing_subckt08.png">
|
|
|
|
|
<p>
|
|
|
|
|
The <kbd>symbol_include.cir</kbd> file has the following content:
|
|
|
|
|
</p>
|
|
|
|
|
<pre class="code">
|
|
|
|
|
* example of a subcircuit contained in a file
|
|
|
|
|
|
|
|
|
|
.subckt symbol_include Z VCC VSS
|
|
|
|
|
+ A B C W=10 L=1
|
|
|
|
|
...
|
|
|
|
|
...
|
|
|
|
|
.ends
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
And as a result the following circuit:
|
|
|
|
|
</p>
|
|
|
|
|
<img src="tutorial_use_existing_subckt09.png">
|
|
|
|
|
<p>
|
|
|
|
|
is netlisted in the following way, notice the net assignment in the <kbd>x1</kbd> subcircuit call
|
|
|
|
|
matches the order in the <kbd>symbol_include.cir</kbd> file:
|
|
|
|
|
</p>
|
|
|
|
|
<pre class="code">
|
|
|
|
|
** sch_path: /home/schippes/.xschem/xschem_library/symbol_include/tb_symbol_include.sch
|
|
|
|
|
**.subckt tb_symbol_include XZ XVSS XVCC XC XB XA
|
|
|
|
|
*.opin XZ
|
|
|
|
|
*.ipin XVSS
|
|
|
|
|
*.ipin XVCC
|
|
|
|
|
*.ipin XC
|
|
|
|
|
*.ipin XB
|
|
|
|
|
*.ipin XA
|
|
|
|
|
x1 XZ XVCC XVSS XA XB XC symbol_include
|
|
|
|
|
**.ends
|
|
|
|
|
|
|
|
|
|
* expanding symbol: symbol_include.sym # of pins=6
|
|
|
|
|
** sym_path: /home/schippes/.xschem/xschem_library/symbol_include/symbol_include.sym
|
|
|
|
|
.include symbol_include.cir
|
|
|
|
|
.end
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</li>
|
|
|
|
|
</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2022-10-22 22:52:55 +02:00
|
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
<h2>Specifying subcircuit netlist</h2>
|
|
|
|
|
<ol>
|
|
|
|
|
<li><h3>Add a <kbd>.include <file></kbd> line in the top level</h3>
|
|
|
|
|
<p>
|
|
|
|
|
The first method is to declare the symbol as <kbd>type=primitive</kbd> (this is the case in all
|
|
|
|
|
images above) and simply add a <kbd>.include /path/to/subcircuit.spice</kbd> in the top level netlist:
|
|
|
|
|
</p>
|
|
|
|
|
<img src="tutorial_use_existing_subckt06.png">
|
|
|
|
|
</li>
|
2024-06-24 08:04:08 +02:00
|
|
|
|
2022-10-22 22:52:55 +02:00
|
|
|
<li><h3>Use a <kbd>spice_sym_def=".include <file>"</kbd> line in the symbol</h3>
|
|
|
|
|
<p>
|
|
|
|
|
The second method is to declare the symbol <kbd>type</kbd> as <kbd>subcircuit</kbd> and
|
|
|
|
|
add a <kbd>spice_sym_def</kbd> attribute
|
|
|
|
|
in the symbol. the value of this attribute will be copied verbatim to the netlist, so
|
|
|
|
|
for the example shown here this should do the job:<br>
|
|
|
|
|
<kbd>spice_sym_def=".include model_test_ne555.txt"</kbd><br>
|
|
|
|
|
</p>
|
|
|
|
|
<img src="tutorial_use_existing_subckt07.png">
|
|
|
|
|
<p>
|
|
|
|
|
The produced netlist will be:
|
|
|
|
|
</p>
|
|
|
|
|
<pre class="code">
|
|
|
|
|
** sch_path: /home/schippes/xschem-repo/trunk/xschem_library/examples/test_ne555.sch
|
|
|
|
|
**.subckt test_ne555
|
|
|
|
|
x1 VSS TRIG OUT VSUPPLY CTRL TRIG DIS VSUPPLY ne555
|
|
|
|
|
...
|
|
|
|
|
...
|
|
|
|
|
* expanding symbol: ne555.sym # of pins=8
|
|
|
|
|
** sym_path: /home/schippes/xschem-repo/trunk/xschem_library/examples/ne555.sym
|
|
|
|
|
.include model_test_ne555.txt
|
|
|
|
|
.end
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
The advantage of this method is that the reference of the subcircuit is embedded in the symbol
|
|
|
|
|
and if the symbol is reused in another design the .include line travels with the symbol and you
|
|
|
|
|
don't have to add the line in the top level.
|
|
|
|
|
</p>
|
2024-06-24 08:04:08 +02:00
|
|
|
</li>
|
|
|
|
|
|
2024-06-24 08:58:00 +02:00
|
|
|
<li><h3>Completely specify a subcircuit in the <kbd>format</kbd> attribute of the symbol</h3>
|
2024-06-24 08:04:08 +02:00
|
|
|
<p>
|
|
|
|
|
The following set of symbol attrtibutes:
|
|
|
|
|
</p>
|
|
|
|
|
<pre class="code">
|
|
|
|
|
type=source
|
|
|
|
|
format="X@name @@in @@out sub_@name
|
|
|
|
|
.subckt sub_@name in out
|
|
|
|
|
@name out 0 V=@func
|
|
|
|
|
.ends sub_@name"
|
|
|
|
|
template="name=B1 FUNC="pow(V(in),2)""
|
|
|
|
|
</pre>
|
|
|
|
|
<p> will create a sub_xxx subcircuit with a unique name for every symbol instance using the @name attribute
|
|
|
|
|
(which is indeed unique). This allows to build subcircuits with arbitrary parameters (a math expression in the example).
|
|
|
|
|
<br><br>
|
|
|
|
|
The problem of this approach is that it works by creating nested .subckt inside the parent schematic
|
2024-06-24 08:58:00 +02:00
|
|
|
(which could itself be a .subckt). Not all simulators support this (although Ngspice and Xyce seem to work OK with this).
|
2024-06-24 08:04:08 +02:00
|
|
|
</p>
|
|
|
|
|
</li>
|
|
|
|
|
</ol>
|
2022-10-22 22:52:55 +02:00
|
|
|
<!-- end of slide -->
|
|
|
|
|
<div class="filler"></div>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- frame footer -->
|
|
|
|
|
<iframe seamless src="xschem_footer.html" class="footer_iframe" >
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
|
|
|
|
|
