The xspice backend for gnetlist has two functions: 1.) To convert a geda netlist into a usable spice format. 2.) To convert non spice native devices in to the corresponding spice models and subcircuits to be usable in ngspice (and possibly other spice dialects.)
This is accomplished through the use of a python script to output spice netlist lines (called cards in spice nomenclature), a collection of spice libraries containing the spice cards needed to represent non native devices, and a set of device descriptions which specify how to convert a geda symbol into a corresponding set of one or more spice cards. An attempt has been made to make the device description system as simple to use as possible.
A spice device card consists of a set of fields:
While some attempt has been made by geda symbol authors to
make their symbols spice compatible, most devices are not
native to spice and as a result the symbols were not designed
with spice in mind. Additionally some devices have multiple
symbols for the same device, each of which may vary in some
way. As a result not all symbols will work with the xspice
backend without some additional effort. Attributes are
supported to address these issues.
The structures which are used to describe the devices are
complex due to a number of factors including nesting.
Additionally the people most likely to be adding devices are
those focused primarily on hardware. These individuals may not
have extensive experience or comfort with python programming.
Finally there are some portions of the device description
system which can only be determined at installation time, most
notably paths for the spice libraries. While ngspice does have
a rather rudimentary search system for finding libraries using
it entails accessing and possibly modifying configuration
files. I chose not to do this. Instead the needed paths are
encoded into the device descriptions. However the full
pathname is not known until the package is installed.
In order to address these issues the device description system uses an executable, xpde.py (Xspice Processor Data Editor), to manipulate xml files which store the device descriptions. These descriptions do not in the general course of usage change with any frequency so it would be inefficient to parse them each time the backend is invoked. Instead the xpde.py executable is again invoked to convert the xml into python source which is then loaded as needed. Due to the number of devices in existence, e.g. the 74xx series of logic devices has nearly 2000 members and the number of linear devices far exceeds that, I chose to break up the device descriptions into multiple files, each focusing on a particular family of devices. This way if you are working on a solely digital project you don't need to waste the resources to load the linear devices, and vice versa. It is anticipated that at some point the linear library will be sufficiently large that it will be broken up into smaller libraries as well. The xpde.py executable is also used to set the paths when the backend is installed.
The device description system contains a library dependency
system (both inter-library and intra-library) to ensure that
devices which depend on other devices are properly handled
without introducing redundant descriptions.
Attributes are supported which allow devices which are not
contained in the libraries, but for which spice
models/subcircuits are available, to be used.
A device description script is referred to as a processor,
largely for historical reasons. The early versions of the
backend used plugins which both described a set of devices and
contained functions for processing them. In the current system
most processors only describe the devices and hold a set of
meta information about them. However fully customized
processors are still supported.
The simplest processor is that created by the xpde.py
executable. These processors can be customized by including a
pre-written python code snippet to provide functions which can
then be referenced in the device descriptions. A fully custom
processor can be written which does not use the xpde system at
all. Such a processor must have a function called setup which
takes as a single parameter an object of type xspice_sys (see
xspice_util.py for the declaration of that structure) and is
responsible to hooking itself into the system as it needs to.
The order in which processors is loaded can be significant
because a processor can override the description of a device
from a processor loaded previously. See the xspice-order attribute and the -O processors command line switch for
how to control order in which processors are loaded.
Much credit and many thanks go to the author(s) of the
spice-sdb backend. While I ultimately decided to employ a
different architectural approach I derived a great deal of
inspiration and direction from the spice-sdb backend. In many
cases I tried to maintain the same or similar functionality
while adding what I considered a better approach (for which
they are wholly blameless).
The xspice backend can be cloned from the git source
repository found at: http://epilitimus.com/git_repos/xspice.git
The main directory contains two backend scripts, some
utility scripts, the device descriptions, and a very
simple makefile to reduce typing when working with the
device descriptions.
Some of the devices contained in the spice libraries were
developed using gschem and the xspice backend to produce
the desired subcircuits, e.g. LM555 timer. The schematics
for these devices are found here.
The spice libraries live here. All of the models
and subcircuits contained in these libraries are
original work and are NOT taken from any
manufacturer supplied models or subcircuits. Reference
was made to manufacturer datasheets for parametric
information only. See commit notes for authorship.
It was necessary to develop a number of new schematic
symbols for various purposes. To use them you should place
a component-library-search directive referencing this
directory in your gafrc file.
This is the core of the xspice backend. See command
line arguments below.
The processing order is:
Produces a listing of the hierarchy generated from the
supplied schematic(s).
This utulity provides a very simple minded interactive
interface for manipulating the device description xml
files, converts them to python sources, and other
things. See command line arguments
below.
A simple Makefile is provided to reduce typing.Targets:
These files are found in the libs directory and use the
xspiceLib_<processor id>.lib filename pattern. They
contain the spice/xspice library blocks imported by
ngspice. Note that not all variants of spice support the
.LIB <library> <libname> card and so the
usefulness of these files may vary with versions of spice
other than ngspice.
These files store the device descriptions as xml. They
use the filename pattern xspiceDev_<processor
id>.xml which is relied upon by xpde.py
The xpde.py executable is used to convert the xml files
into python scripts for use by the backend. They use the
filename pattern of xspiceDev_<processor id>.py
which is enforced by gnet_xspice.py
This file contains the various structures used in the
backend as well as some utility functions which may be
of use to custom processors.
This script is used by both the gnet_xspice and gnet_hierarchy backends.
This file has code for some special processing needed
to support xspice bridge devices. It is included in the
base device desciption library. It will probably be
relocated at some point.
Specifies the title to be used for the spice netlist.
See also -O force_title, -O use_title, comment attribute. If no
title is specifed the filename of the first top level
sheet is used.
Add a path to the search path list for xspice
processors.
Specify a processor to be loaded. Some processors may
need to be loaded which are not directly used to handle
dependencies (at this point most often for linear
devices). The base device processor is always
loaded and is always loaded first so there is no
need to explicitly load it. See also -O processors and xspice-order attribute.
Add a library call to the list of libraries to be
loaded. Can be used to work with libraries unknown to
xpde. See section 2.7 of the ngspice34 manual.
The xspice_control device will cause the contents of
the named file to be included in the control section of
the netlist. The file should *not* include the .control
and .endc cards as these will be automatically added by
the backend. The directive device will include the text
from the device's value attribute in the control section
of the netlist.
The specified file will be added to the include section
of the netlist.
If the model has a file attribute attached the
indicated file will be added to the include section. If
instead there is a value attribute its text will be
placed in the model section. Note that file takes
precedence over value if both are present.
Designates a net to be listed on the .SUBCKT line. The name of the attached net will be used (use the netname attribute to control this value). The order in which nets are listed on the .SUBCKT card is as follows:
Specifies that the schematic is for a subcircuit and
specifies the name of the subcircuit. See also xspice-subckt-parm
attribute.
Some of these symbols were drawn from scratch, where I
was able to find an example of a pre-existing schematic
symbol for the device I tried to draw something as close
to that as I could manage. In other cases I was unable to
find such an example and had to come up with something
that made sense to me. In a number of cases I was able to
simply modify an existing geda symbol, my thanks to the
authors of those symbols.
Symbols for devices in the functional library are found
here.
Geda was previously missing symbols for JFets. These
symbols are to support these devices. Spice also
supports MESFETS but I was not able to find an example
schematic symbol for them and since I know very little
about them I chose not to include them.
Symbols for several custom devices are included here.
It was necessary to include new symbols for various
tasks unique to xspice and the xspice backend. These are
found here.
This is the primary key for the entire device description
system. It is case sensitive. Components without a device
attribute are ignored.
REQUIRED - Associates the given model name with
the associated file or value
POSSIBLY REQUIRED - Outputs the given model name
in the model slot for the device card. It is the users
responsibility to ensure the specified model has a
corresponding model device. The device description
specifies whether the model is optional or required.
Will override the default model. It is the users responsibility to ensure the specified model has a corresponding model device.
When combined with xspice-signature and xspice-pinseq
allows the unknown device to be listed in the netlist.
All three attributes must be present for this to occur.
It is the users responsibility to ensure the specified
model has a corresponding model device. Without these
three attributes the device will be entered in the
netlist as a comment providing all known information
about the device.
Lists parameters for a subcircuit. The contents are a
colon separated list of name/value pairs. The contents
will be separated and each parameter will be listed
individually on the .SUBCKT card. Note: Contrary
to the ngspice34 manual the default parameter values are
used and so must be meaningful. See also device parameters and flags
and section 2.8.3 of the ngspice34 manual.
Order by refdes is flawed as renumbering a schematic can
change the refdes thus changing the order. This attribute
solves this issue allowing the order to remain consistent.
REQUIRED - Controls the order in which
processors are loaded. Processors from the schematic are
loaded first then processors from the command line. See
also -O processors
Controls the order in which nets are listed on the
.SUBCKT card. All spice-IO devices with an xspice-order
attribute are listed first in specified order, then all
spice-IO devices without an xspice-order attribute
sorted by the integer portion of the refdes.
A '*' is automatically prepended.
Lists the text as a comment immediately after the title
line of the netlist.
Replaces the default include comment which lists the
device from which the include comes.
Replaces the default library comment which typically
lists the processor responsible for the library call.
Replace the default model comment. Both for the file
and the value versions.
Places the provided text as a comment immediately prior
to the device card.
REQUIRED - Adds the provided path to the search
list for processors (and libraries?)
REQUIRED - Designates the processor to be
loaded. The provided id is used to form the actual
processor name as in xspiceDev_<processor id>
Causes the contents of the indicated file to be listed
in the control section of the netlist. See also value
Adds the provided file name to the list of files to
include. See also value
REQUIRED - Designates the file for the library
call. Note that an absolute pathname should be used
unless you are sure you know what you are doing.
REQUIRED - Designates a file to be included
The provided text is a colon separated list. The first
field is the model type, and the remaining fields are
name/value pairs. A .MODEL card will be generated with
the value of the model-name attribute followed by the
model type and the name/value pairs. This attribute is
ignored if the model device also has a file attribute
attahced.
The provided text will be included in the control
section of the netlist.
REQUIRED - The provided text will be used as the
first line of the netlist preceded by .TITLE if the -O
force-title command line option is used.
REQUIRED - For a library
device designates the libname for the library call.
The refdes mangler in geda changes the refdes if the the
device is from a subsheet causing the refdes to start with
an X (if I recall correctly it could be anything but the
standard practice is to use X). In spice an X designates a
subcircuit which is probably not what you want. It is
therefore necessary to remangle the mangled refdes to
ensure it works correctly. The mangled refdes does however
contain information which may be useful.
Overrides the signature contained in the device
description. Be very very certain you know what you
are doing here. Most useful if you need to replace the
default description with a custom one. See also xspice-pinseq and model-name.
If there is no matching description for the provided
device it will be included in the netlist as a comment
unless all of model-name, xspice-pinseq, and
xspice-signature are supplied. If they are they will
be used to output a card for the device.
The value of this attribute is a colon separated list of
strings and comma separated lists. Strings are interpreted
as pintypes and comma separated lists are interpreted as
lists of pin numbers. Either can be enclosed in square
brackets to have them treated as a vector.
Overrides the node groups from the device description. Be very very certain you know what you are doing here. Most useful if you need to replace the default description with a custom one. See also xspice-signature and model-name.
Provides the node groups used to generate the device
card. All three of model-name, xspice-signature, and
xspice-pinseq must be supplied for this to work.
Otherwise the device will be output as a comment.
Compared to the value given in a pintype node group.
For pintype node groups the pins are sorted by pinseq
For slotted devices this is used to map pins from a
pinlist node group into the slot for the current device.
Used to determine if the device's slot is the same as the
one described by the description's node group.
Output when an unknown device is listed as a comment.
Many devices have optional parameters and flags which can
be specified on a instance basis to override various model
parameters for that device. Where available attributes
with the same names as those parameters and flags are
output as part of the device card. Be aware that
parameters are only evaluated during circuit setup and so
can not reference simulation values.
Also when looking at the some of the non native devices
in the libraries it will be noted that they are
implemented as subcircuits containing just a model and a
device call. This was done because spice subcircuits can
have parameters. These parameters can then be used to
configure subcircuit model parameters. Otherwise the model
parameters could only be parameterized with global
parameters which means all devices must share the same
model parameters. By using subcircuits the model
parameters can be set on a per instance basis just like
native devices. This also holds true for complex devices,
e.g. LM555. See also xspice-subckt-parm.
Command line options are passed to the backend with the
-O command line switch in gnetlist, e.g. gnetlist -O
force_title. While no error is issued if the same -O
option is used multiple times on the gnetlist command line
the backend is only notified of the last one. Therefore,
for those command line options which take arguments, e.g.
use_title, only the last instance is significant.
Places .TITLE before whatever title line would
otherwise be produced. Ngspice does not require this but
some other spice variants may. In addition this option
can be useful when generating subcircuits as without the
.TITLE the line is interpreted as a device line when the
subcircuit is read by the spice parser. This can lead to
errors during simulation. When generating subcircuits
either this option should be used or the title line
should be manually removed.
Causes the backend to output various messages
regardless of the verbosity level of gnetlist. This has
limited testing. It was added early and there have been
many changes since then which may have affected it
usefulness.
Use the provided argument as the title of the netlist
rather than the title which would otherwise have been
produced.
Designates that the generated netlist should be
produced as a subcircuit. The argument is a colon
separated list. The first field is the subcircuit name
followed by a comma separated list of the net names of
the connection nodes. The connection nodes are placed on
the .SUBCKT line in the order they appear. Provided net
names are checked to make sure they exist in the
schematic and a warning is issued if they do not. No
direct provision is made for defining subcircuit
parameters, though they can be produced by including
them at the end of the node list and ignoring the
resulting warnings.
The argument is a semicolon separated list of paths to
be searched for processors. This list of paths can be
used by custom processors via the findFile function in
the xspice_sys structure to locate other files as well.
The paths from this command line option are added to
those from the schematic, see xspice_path
device.
A comma separated list of processors to load. These are
loaded after those found in the schematic so
they can overload those listed in the schematic. They
are loaded in the order listed.
If a custom net name mangler is used which alters the
prefix used to identify unnamed nets this option can be
used to provide this prefix to the backend so it can be
removed. See also keep_unnamed
In usual operation net names for unnamed nets are
represented by numbers. This is accomplished by removing
the prefix added to such nets by the gnetlist net name
mangler, usually 'unnamed_net'. This option causes the
prefix to be kept resulting in netnames like
'unnamed_net3' as opposed to the '3' which would
otherwise be used.
The xpde.py executable uses the gnu_getopt python
function to parse the command line so options and non
options can be mixed. Option arguments must immediately
follow their associated option. With no options xpde.py
enters an interactive mode.
Generate the python source from the provided xml file.
Produce a list of the devices described by the provided
xml file. See Current device list for examples
Set the spice library path to the argument provided.
Unlike the menu option from the interactive mode there
does not need to be a trailing slash.
Show a usage page.
Non-native devices should be considered primarily at a
functional level and will probably not exhibit the same edge
case behaviors as the actual device. The digital xspice
portion of ngspice only models function and propagation
delays. It does not appear to make any calculations relating
to fan-in/fan-out or power consumption (as far as I can find).
xspiceDev_base.xml
Device
Description
-------------------- --------------------
CAPACITOR
COIL
CURRENT_SOURCE
DIODE
INDUCTOR
NFET_TRANSISTOR
NMOS_TRANSISTOR
NPN_TRANSISTOR
PFET_TRANSISTOR
PMOS_TRANSISTOR
PNP_TRANSISTOR
RESISTOR
SPICE-VC-switch
SPICE-cccs
SPICE-ccvs
SPICE-vccs
SPICE-vcvs
VOLTAGE_SOURCE
vpulse
vpwl
vsin
xspice_ad_bridge XSpice
analog to digital bridge
xspice_da_bridge XSpice
digital to analog bridge
xspice_pulldown XSpice
digital pulldown
xspice_pullup
XSpice digital pullup
Total: 25 devices
xspiceDev_74xx.xml
Device
Description
-------------------- --------------------
7400
2 input Nand gate
7401
2 input Nand gate w/ open collector output
7402
2 input Nor gate
7403
2 input Nor gate with open collector ouput
7404
Inverter
7405
Inverter with open collector output
7406
Inverter with open collector output
7407
Buffer with open collector output
7408
2 input AND gate
7432
2 input OR gate
7434
Buffer
7474
Positive edge triggered D flop with active low set/reset
7486
2 input Xor gate
Total: 13 devices
xspiceDev_functional.xml
Device
Description
-------------------- --------------------
CtrlLimiter
Controlled limiter block
Differentiator
Time differentiation node
Divider
Divider
Gain
Gain block
Integrator
Time integration node
Inverter
NOT gate
Limiter
Limit block
Multiplier
2 node multiplier point
OSC
Controlled digital oscillator
SRLatch
Digital SR latch
Slew
Slew rate limiting block
Summer
2 node summing point
lf_edge_trig
Active low, Falling edge, Edge trigger
lr_edge_trig
Active low, Rising edge, Edge trigger
Total: 14 devices
xspiceDev_misc.xml
Device
Description
-------------------- --------------------
bouncy_sw
Time controlled switch with switch bounce
cap_meter
Capacitance meter
ind_meter
Inductance meter
Total: 3 devices
xspiceDev_linear.xml
Device
Description
-------------------- --------------------
LM311
LM311 comparator
LM311_doc
LM311 comparator with digital open collector output
LM555
LM555 timer circuit (out & reset are digital, all others
analog)
LM741
LM741 OpAmp
ideal_comparator Ideal
comparator (use symbol opamp-1.sym & set
device=ideal_comparator)
ideal_opamp
Ideal OpAmp (use symbol opamp-1.sym & set
device=ideal_opamp)
Total: 6 devices