
Welcome the the WRspice Device Kit
----------------------------------

This is supplemental to the WRspice circuit simulation program from
Whiteley Research Inc.  This distribution is the starting point for
users who wish to develop custom device models for WRspice.

Creating Loadable Device Modules For WRspice
--------------------------------------------

WRspice has the ability to load device modules while running.  These
devices can then be used in simulations in the normal way.  The
modules can be generated from C++ source code, compiled by the user. 
In particular, modules can be compiled from Verilog-A source into C++
source using the open-source ADMS package, making available device
models supplied only in Verilog-A form to WRspice.

This document describes how to create a loadable device module from a
Verilog-A description for use in WRspice.

Caveat
------

This is a new capability, beta-grade.  Not all Verilog-A constructs
are supported.  Consider this somewhat experimental.

Requirements
------------

1.  The user's computer must contain the gcc C/C++ compiler and the
regular set of program development tools.  Apple users are advised to
install Apple's XCode program development environment, which is a free
(but huge) download from Apple.  It is recommended that you set up a
build environment as described in the README file at the top level of
the XicTools source tree.

2.  The compiler version used to build modules must be compatible with
the version used to build WRspice.  Incompatibility may be manifested
in various ways:

    - The module fails to load, with an error message.
    - The module loads, but with warnings.
    - The module loads, but causes program instability when used.

That being said, I haven't noticed any problems, even in the case of
using gcc-3 to compile the module and gcc-4 to compile the program. 
The safest approach is to build WRspice from source, which should not
be hard since you already have the build environment set up.

3.  The XicTools version of the ADMS translator must be installed.
This is available as a package and as part of the source code for
XicTools.

4.  The procedure to build the example modules is simple.  However, to
successfully build an arbitrary module will probably require expertise
in C++ coding/program building, Verilog-A syntax, and possibly the
ADMS language, if the module does not build or work properly initially.

How It Works
------------

The ADMS program reads the Verolog-A file, and builds a representation
of the file logic in memory.  A set of XML scripts access this tree
and generate the C++ code to describe the device functionality.  The
C++ files are then compiled into a loadable module (shared library)
which can be loaded into WRspice.

WRspice can load device modules in two ways.  On program startup, any
device modules found in the devices sub-directory in the startup
directory (typically
/usr/local/xictools/wrspice/startup/devices) will be loaded. 
While running, the WRspice devload command can be used to load a
module, with the command argument being the path to the module.  If no
argument is given, a list of the modules currently loaded is printed.

The ADMS Scripts
----------------

The scripts which control the interpretation of the Verilog-A source
during translation into C++ reside in the admst directory.  There is a
fairly steep learning curve in gaining proficiency with the language
and logic of these scripts, but they can in theory be modified by the
user.  In fact, the wrspiceVersion.xml file provides some
user-customization switches.

Some of the features provided by the WRspice script set, that are not
available in the script sets available for many/most/all other
simulators, are the following:

1.  Rigorous automatic partitioning of static and dynamic contribution
    terms, as well as noise terms.
2.  Support for potential nature contributions (V() <+ ...), and
    automatic node collapsing when possible.
3.  Support for optional ports and the $port_connected call.
4.  Support for the idt (time integration) operator, and most other
    system functions.
5.  Does not require adms-specific format extensions, but will use
    them if found.
6.  Full computation of second-derivative terms.
7.  Full support for noise analysis in WRspice.
8.  A new and more efficient math package.
9.  No "built in" fixes for common public Verilog-A models, scripts
    are intended to be completely generic.
10. Produces C++ code that is indented and humanly-readable.

How to Build a Module
---------------------

If all goes according to plan, this is easy.

1.  Create a fresh directory somewhere.

2.  Copy the Makefile from the devkit directory (typically
/usr/local/xictools/wrspice/devkit) into the new directory.

3.  This is optional, but you may want to copy the Verilog-A source file
(or files) into this directory as well, for convenience.

4.  Edit the top of the Makefile with a text editor.  The Makfile
contains comments explaining what needs setting.  Basically, you need
to set the device key letter and model level (as will be used in
WRspice), a short name for the module, and the path to the XML scripts
provided under the devkit.

5.  Type "make" at the shell prompt.  The processing may take a few
minutes.  Some compiler warnings may appear.

There may be a lot of messages like:
  warning: declaration of T10 shadows a previous local
These appear when the module code defines a variable in a block, and
also in a lower-level block.  These should be harmless, but some
models (bsimsoi) generate a lot of these messages.

Messages like
  warning: unused variable vd
appear if a variable is declared in a block but never used.  Once
again, these are harmless, but may represent declarations in the
Verilog-A source that could be omitted.

6.  If all goes well, a loadable module will be created.  This is a
file with a ".so" extension (".dylib" under OS X, or ".dll" in
Windows) with the base name the same as the module name that you
supplied in the Makefile.  You should be able to load this module into
WRspice, and access the device description in simulation files.

Building the Examples
---------------------

The examples subdirectory contains several publicly-available
Verilog-A models for testing and illustrating the procedure.  The
README files provide more information.  You should copy the
directories and their contents to your local directory to build the
modules.  In each model directory, follow the procedure above.

Test the new loadable module.  First, verify that the loadable module
file exists, i.e., the compile succeeded.  Then, change to the "tests"
subdirectory, and start WRspice.  At the WRspice prompt, give the
command

  devload ../module.so

where "module.so" is the actual name of the module file.  WRspice will
print a "Loading device ..." message, and no error messages should
appear.

Next, bring up the File Selection panel with the File/Open button. 
There will be at least one file listed with a ".sp or ".cir"
extension, these are the SPICE input source files.  Click on one of
these to select, and click on the green octagon button.  The
simulation will run and a plot will appear.

Have fun!

What if it Doesn't Work?
------------------------

There are many things that can go wrong, and it is likely that
something will.  Most likely, the Verilog-A file contains a construct
that either ADMS or the scripts can't handle.  The author of ADMS
describes the translator as "alpha", but that being said, it seems
fairly complete and stable.  The problem most likely resides with the
XML scripts.  These were adapted to WRspice using scripts for other
simulators as a starting point.  They will evolve to provide more
complete and error-free translation.  As a quick look at the script
text will show, they can be hideously complex.  The language itself is
not well documented, though "experts" can figure it out from the
configuration files in the ADMS installation.

