Basic Scripting

Basic admst Script File Structure

After ADMS has parsed a Verilog-A model, a tree representation of the model is held in memory. The data in this tree is accessible via a built-in language called admst. admst is an XML-based scripting language, inspired by XPath. All admst scripts share a basic structure. These tell the XML parser about the schema and namespace:

<!DOCTYPE admst SYSTEM "admst.dtd">
<admst version="2.3.0" xmlns:admst="http://mot-adms.sourceforge.net/xml-files/admst">
    <!-- Code Here -->
</admst>

Navigating The Data Tree

The information about a parsed Verilog-A file is stored as a tree in memory. To access the data, one uses an XPath-style path syntax.

The root node can be selected with the / character:

<admst:value-of select="/"/>

Elements can be selected with their absolute path. This will loop over each node in each module found:

<admst:for-each select="/module/node">

Some commands, like for-each create a new scope. It’s possible to access elements relative to that scope with . and ..

<admst:for-each select="/module/node">
    <admst:value-of select="./name"/>    <!-- Select the current node's name -->
    <admst:value-of select="../name"/>   <!-- Select the node's parent module's name -->
</admst:for-each>

You can also leave off the ./ to access the current element:

<admst:for-each select="/module/node">
    <admst:value-of select="name"/>    <!-- Also selects the current node's name -->
</admst:for-each>

It is possible to only select elements that match a certain condition:

<admst:for-each select="/module/node[direction='input']/name">

Inspecting Objects

Almost every object will have a name, all objects will have a datatypename and most will have a stringification (an implicit toString function). It’s possible to access these with the value-of command:

<admst:value-of select="."/>
<admst:value-of select="name"/>
<admst:value-of select="datatypename"/>

<admst:text format="datatypename=%s name=%s stringification=%s"/>

The value-of retrieves an object and puts it on top of a stack. (Note that values are used in the order opposite of how they were read.) The %s string used in the text‘s format argument pops an object off of the stack and converts it into a string, if necessary. This conversion will call the object’s stringification if it’s not already a string.

Calling value-of without a corresponding %s will result in an error at the end of the parsing due to a non-empty stack. Using %s without having first called value-of will result in an error when the stack underflows.

A much easier way to get strings is to use %(<path>):

<admst:text format="datatypename=%(datatypename) name=%(name) stringification=%(.)"/>

Object Reference

The structure of every object is defined in the ADMS source code, in adms.xml. This is used not just for documentation, but also code generation! Adding new objects to adms.xml will allow you to use them in admst scripts, as well as the actual Verilog-A parser.

You can generate an interactive tree representation of the object tree locally with:

xsltproc adms.xml -o adms.html

There is also a compiled version available online.

Variables

Variables provide storage for objects or data. Their values can be set to anything that you can use in a select argument:

<admst:variable name="myvar1" select="/module"/>
<admst:variable name="myvar2" select="/module/node[name='foo']"/>
<admst:variable name="myvar3" select="'foo'"/>
<admst:variable name="myvar4" select="1"/>

To access a variable, use $variable_name or $(variable_name), like this:

<admst:variable name="myvar5" select="$myvar4"/>
<admst:for-each select="$(myvar1)/node[name=$(myvar2)]">

You can omit the select statement in the variable declaration to leave the variable uninitialized:

<admst:variable name="myvar6"/>

Variables defined outside of a template are global, and can be accessed anywhere. Variables defined inside of a template are not accessible outside of the template.

Templates

Templates in admst are mostly equivalent to functions in other languages. They can only receive one argument, and may only return string values. They do create a new scope for variables, and may be called recursively.

You can define a template like this:

<admst:template match="my_first_template">
    <admst:text format="%(name)"/>
</admst:template>

And then call it like this:

<admst:apply-templates match="my_first_template" select="/module">

This will pass in the object/objects from the select argument, which all paths inside of the template will be relative to.