The Xyce/ADMS Verilog-A compiler tool
Xyce/ADMS is a set of XML templates that provide a code-generating "back-end" to the open source Verilog-A compiler ADMS. With the Xyce/ADMS templates and the ADMS compiler, the Xyce team has been able to import industry-standard device models written in Verilog-A into Xyce. To date, the capability is still an "alpha-quality" tool that has mostly been used internally by the Xyce team; but it has matured enough in recent releases to attract the interest of device model developers inside and outside of Sandia National Laboratories.
The purpose of this document is to describe the use of the Xyce/ADMS capability, its features, and its limitations.
NOTE: Xyce/ADMS has been refactored since Xyce 6.11.1 and now requires additional admsXml command line options to function correctly. If you are a user of Xyce/ADMS in versions of Xyce up to 6.11.1, please re-read the sections on invoking Xyce/ADMS carefully so you can update your workflow.
What is ADMS?
ADMS ("Automatic Device Model Synthesizer") is an open-source Verilog-A translator. It reads a Verilog-A input file and produces a complex internal data structure representing the module. It then processes a set of XML templates written in an XSLT-based templating language called ADMST. These user-provided templates access the internal ADMS data structure, and can be written to emit code in any desired language targeting any desired simulator.
Though it is not completely consistent with the use of the term in computer science, since all code generation is provided through the use of XML templates after all Verilog-A parsing has been completed, we refer to these templates throughout this document as the "back-end" of an ADMS compiler. ADMS itself does not come with any code generation templates—these must all be provided by the developer of a simulator for which the code is targeted.
What is Xyce/ADMS?
The term "Xyce/ADMS" refers only to the set of XML templates provided by the Xyce team for use with ADMS. These templates allow ADMS to emit C++ code for a Xyce device model. In most cases, the code produced by this process is ready to compile into Xyce; in a few cases the C++ code emitted requires some manual editing to add features or Xyce-specific changes that cannot be expressed in Verilog-A.
The Xyce/ADMS templates are all found in the utils/ADMS subdirectory of a Xyce source distribution. The primary template files used in Xyce/ADMS are:
- adms.implicit.xml -- a slightly modified version of the "implicit" templates that are distributed with ADMS itself. The modifications provide fixes for certain special cases of analog function use that are not covered in the version provided with ADMS.
- xyceVersion_nosac.xml — provides basic simulator variables to ADMS, mostly used to output comments.
- xyceBasicTemplates_nosac.xml — a set of ADMST templates (subroutine-like code) used to process the ADMS data structure and emit fragments of code
- xyceAnalogFunction_nosac.xml -- ADMST templates for generation of functions that evaluate the derivatives of user-defined analog functions
- xyceHeaderFile_nosac.xml — a template that generates the C++ ".h" header file defining the device class
- xyceImplementationFile_nosac.xml — template that generates the C++ ".C" file implementing the device
The "_nosac" suffix of these files refers to their being refactored versions of the original Xyce/ADMS that was distributed with Xyce versions through 6.11.1. This refactor removes most of the use of the Sacado templated data types that had previously provided run-time automatic differentiation. The refactored Xyce/ADMS now performs symbolic differentiation at the time of code translation instead, which results in significant performance improvements (up to a factor of nine in some cases) in the function that evaluates model equations for all analyses other than sensitivity.
The legacy Xyce/ADMS of previous releases is still available, and consists of the following XML template files in addition to adms.implicit.xml above:
- xyceVersion.xml — provides basic simulator variables to ADMS, mostly used to output comments.
- xyceBasicTemplates.xml — a set of ADMST templates (subroutine-like code) used to process the ADMS data structure and emit fragments of code
- xyceHeaderFile.xml — a template that generates the C++ ".h" header file defining the device class
- xyceImplementationFile.xml — template that generates the C++ ".C" file implementing the device
The legacy back-end can be invoked in the command lines below by replacing the five "-e" command line options other than adms.implicit.xml with these four.
In addition to templates that generate C++ model code, the Xyce team provides templates that can produce other artifacts of a model:
- html_params.xml — generates an HTML file describing the device model, its variables, parameters, and other details. This is primarily of interest to Xyce/ADMS developers as a debugging tool.
- xyceBootstrapFile.xml — generates a small C++ object declaration that can be used in creation of a shared-library plugin for the model
- xyceMakefile.am.xml — generates a Makefile.am file that can be used to create a shared-library plugin as part of a Xyce build
A directory of all the source code for Verilog-A models that have been incorporated into Xyce (e.g. VBIC, PSP, MEXTRAM, etc.) is provided with the Xyce source code in the utils/ADMS/examples directory. A "toys" subdirectory under this examples directory has a set of simple Verilog-A models is also included. The toys directory also contains a DiodeClipper.cir netlist that consists entirely of devices provided as Verilog-A source in that directory.
Table of Contents
- Obtaining ADMS
- Running Xyce/ADMS
- Verilog-A language elements implemented
- Verilog-A language elements not implemented
- Xyce/ADMS-specific extensions
- Guidance for writing models for use with Xyce
- Special topics