~dspom/openvaf_doc

44290153b35680bc1bc5c42bb561fd4ec0c79b3d — Markus Mueller 2 years ago 0b9d0b2 
improve doc
patch browse .tar.gz 
2 files changed, 52 insertions(+), 51 deletions(-)

M index.md
M language_support.md

M index.md => index.md +11 -7
@@ 34,15 34,19 @@ toc: false
  <strong>Notice</strong>: Page is currently under construction...
</div>

OpenVAF is a compiler for Verilog-A aimed predominantly at compact modeling.
This Project is not an executable itself but rather servers as the main component of various sub projects such as VerilogAE and OSDIC.
The aim of this Project is to provide a high quality standard compliant compiler for Verilog-A.
Furthermore, it aims to bring modern compiler construction algorithms/data structures to a field with a lack of such tooling.
OpenVAF is a Verilog-A compiler that can be used to compiler Verilog-A compact models into machine code.
The compiler is not an executable by itself and servers as the main component of other sub-projects such as 

* VerilogAE: An interface between Python and Verilog-A compact models (finished)
* OSDIC: An interface between Verilog-A compact models and circuit simulators (under development)

The aim of OpenVAF is to provide a high-quality standard compliant compiler for Verilog-A.
Furthermore, OpenVAF brings modern compiler construction algorithms/data structures to a field with a serious lack of such tooling.

Some highlights of OpenVAF include:

* IDE aware design
* High quality diagnostic messages
* High-quality diagnostic messages
* A linting framework (similar to rustc)
* A modular backend including data flow analysis and various state of the art compiler optimization algorithms
* Fast binary generation using LLVM


@@ 50,12 54,12 @@ Some highlights of OpenVAF include:

# Technical Documentation

A detailed description of what parts of the Verilog-A language are supported by OpenVAF can be found [here](language_support.md) 
A detailed description of the parts of the Verilog-A language that are supported by OpenVAF can be found [here](language_support.md) 


# News & Updates

 Want to keep up with the latest news on OpenVAF and its sub projects? Subscribe to the [announcement mailing list](https://lists.sr.ht/~dspom/openvaf-announce). 
Want to keep up with the latest news on OpenVAF and its sub-projects? Subscribe to the [announcement mailing list](https://lists.sr.ht/~dspom/openvaf-announce). 


# Development


M language_support.md => language_support.md +41 -44
@@ 1,12 1,12 @@
OpenVAF follows the [Verilog-AMS Language Reference Manual 2.4.0][vams].
Currently the goal is only to support the analog (Verilog-A) subset defined within this standard.
That means that digital behavior can not be parsed.
OpenVAF follows the [Verilog-AMS Language Reference Manual 2.4.0][vams] language standard.
The current goal is to support only the analog (Verilog-A) subset defined within this standard, 
digital models can not (yet) be parsed.


Furthermore the OpenVAF compiler is primarily aimed at compact modeling.
To better facilitate compact modeling (and to reduce the scope of the implementation) the behavior of the compiler
differences from the one defined in the standard. 
Herein all differences between the language subset implemented by OpenVAF and the Verilog-A subset of the [Verilog-AMS Language Reference Manual][vams] are documented.
Furthermore, the OpenVAF compiler is primarily aimed at compact modeling.
For better facilitating compact modeling (and for reducing the scope of the implementation) the behavior of the 
compiler sometimes differs from the standard. 
In this document all differences between the language subset implemented by OpenVAF and the Verilog-A subset of the 
[Verilog-AMS Language Reference Manual][vams] are documented.


# Incomplete Features


@@ 16,7 16,8 @@ Herein all differences between the language subset implemented by OpenVAF and th
  <strong>Notice</strong>: This section is currently under construction...
</div>

Some features in the [Verilog-AMS Language Reference Manual][vams] are aimed at behavioral modeling or describing entire circuits.
Some features in the [Verilog-AMS Language Reference Manual][vams] are aimed at behavioral modeling or describing 
entire circuits.
These features are hard or even impossible support when statically compiling compact models.
Therefore OpenVAF purposefully does not implement these features.
Here all language features not implemented by OpenVAF are laid out.


@@ 27,9 28,9 @@ Here all language features not implemented by OpenVAF are laid out.
* *Standard Section* 5.10 Analog event control statements
* *Status* Syntax for events other than `inital_step` and `final_step` can't be parsed

The Verilog-AMS standard allows marking statements with event control.
These statements are only executed when the indicated event has occurred.
These events are usually not used in compact modeling because they may introduce discontinuities.
The Verilog-AMS standard allows to mark statements with event control.
Such statements are only executed when the indicated event has occurred.
The events are usually not used in compact models as they may introduce discontinuities.
Therefore OpenVAF only supports the `inital_step` and `final_step` events for initialization code.

### Examples


@@ 40,25 41,21 @@ They are listed here with an example and an indication to show whether OpenVAF c
* Global events (`@(initial_step)`, `@(final_step)`) *supported*
* Named (manually triggered) events (`@foo`) *not supported*
* Monitored events (`@(cross(V(smpl) - thresh, dir))`) *not supported*
* Or Events (a combination of multiple other events) `@(initial_step or cross(V(smpl)-2.5,+1))` *not supported*
* Or events (a combination of multiple other events) `@(initial_step or cross(V(smpl)-2.5,+1))` *not supported*

## Arithmetic Bit Shift

* *Standard Section* 4.2.11 Shift Operators
* *Status* Arithmetic Shift Operator can not be parsed (no change planned)

Arithmetic bit shifts are now allowed in analog blocks by the language standard and therefore serve no purpose in the Verilog-A subset of the language.
However the standard does not explicitly exclude these operators from the language subset.
To avoid having to maintain unused code the Arithmetic Bit Shift Operator is not supported by the compiler.



Arithmetic bit shifts are not allowed in analog blocks, yet they are a sub-set of the Verilog-AMS standard that is not excluded for Verilog-A. 
To avoid having to maintain unused code, the arithmetic bit shift operator is not supported by the compiler.

# Additional Features

Some features that are not part of the Verilog-A standard have been added to OpenVAF.
The need for these features arose when OpenVAF was used in practice for compact model compilation and parameter extraction.
Below a list of these features is provided together with an example.
The need for these features arose when OpenVAF was used in practice for compact model compilation and parameter, 
extraction. Below is a table that lists these additional features and a corresponding example.


| Feature                                                                     | Example                      |


@@ 68,21 65,21 @@ Below a list of these features is provided together with an example.


In the following section each feature -including a motivation- is explained in detail.
To make it easy to remain standard compliant OpenVAF will emit a warning by default when any one of the listed features are used.

To make it easy to remain standard-compliant, 
OpenVAF will emit a warning by default when any one of the listed features is used.

## Symbolic Derivatives by Temperature 
## Symbolic Derivatives with respect to Temperature 

The [Verilog-AMS Language Reference Manual][vams] allows calculating derivatives with the `ddx` analog filter.
However only derivatives by node voltage `V(node)` or branch currents (`I(branch)`) are allowed.
For parameter extraction derivatives by ambient Temperature (`$temperature`) may be of interest for extracting temperature dependence.
However, only derivatives w.r.t. node voltages `V(node)` or branch currents (`I(branch)`) are allowed.
For parameter extraction derivatives by ambient Temperature (`$temperature`) may be of interest for extracting temperature dependencies.

### Guide

The behavior of the `ddx` analog filter is extended so that `ddx(foo,$temperature)` is valid.
All voltages and currents are considered as constants (so their derivatives are zero) and only the derivative of `$temperature` is 1.
Otherwise the `ddx` filter behaves identical as when used with nodes/branches.
So the derivative of the argument is calculated by repeated application of the chain rule.
When such a derivative is evaluated, all voltages and currents are assumed to be independent of temperature. 
Apart from this the `ddx` filter behaves identical as when used with nodes/branches, 
the derivative of the temperature is calculated by repeated application of the chain rule.

### Examples



@@ 100,14 97,15 @@ bar = ddx(foo,$temperature)



## Symbolic Derivatives by Voltage Difference
## Symbolic Derivatives with respect to Voltages

Equations of compact models usually depend upon Voltage differences `V(a,b)` (or equivalently branch voltage `V(br_ab)`).
The derivatives of these Model Equations are required/useful during parameter extraction.
Equations of compact models usually depend upon voltage differences `V(a,b)` (or equivalently branch voltage `V(br_ab)`).
The derivatives of these model Equations are required/useful during parameter extraction and for use in circuit simulators. However, Verilog-A only allows derivatives w.r.t. to node potentials. 

They are usually emulated with the derivative of the upper node `ddx(foo,V(a,b) = ddx(foo,V(a))`.
However this stops working when an expression depends on multiple branch voltages as demonstrated by the example below.
To ensure correct behavior it is therefore more desirable to calculate the derivative by `V(a,b)` directly.
Usually, such voltage derivatives are instead calculated with respect to the derivative of the voltage's 
upper node `ddx(foo,V(a,b) = ddx(foo,V(a))`.
This approach can fail when an equation depends on multiple branch voltages, as is demonstrated by the example below.
For ensuring correct behavior it is therefore more desirable to calculate the derivative by `V(a,b)` directly.

``` verilog
foo = V(a,b) + V(c,a)


@@ 119,7 117,7 @@ dfoo2 = ddx(foo,V(a,b))
### Guide

The behavior of the `ddx` analog filter is extended so that `ddx(foo,V(node1,node2))` is valid.
Branch currents are treated as constants. Voltage access is treated as follows:
Branch currents are treated as constants. Voltage derivatives w.r.t. `V(node1,node2)` are implemented as follows:

* The derivative of `V(node1,node2)` is 1
* The derivative of `V(node2,node1)` is -1


@@ 127,8 125,8 @@ Branch currents are treated as constants. Voltage access is treated as follows:
* The derivative of `V(branchX)` is -1 if the branches nodes are `node2` and `node1`: `branch (node2, node1) branchX`
* In all other cases the derivative is 0

Otherwise the `ddx` filter behaves identical as when used with nodes/branches.
So the derivative of the argument is calculated by repeated application of the chain rule.
Otherwise, the `ddx` filter behaves identical as when used with nodes/branches.
The derivative of the argument is calculated by repeated application of the chain rule.

### Example



@@ 151,8 149,8 @@ end

### Technical Background

For performance reasons osdic also uses these derivatives instead of derivatives by individual nodes to calculate matrix entries.
Consider a network with two nodes `a` and `b` that are connected by a single branch `br_ab` whose current only depends upon the voltage difference of these two nodes. 
For performance reasons ODIC uses voltage derivatives instead of potential derivatives to calculate the Jacobian matrix entries.
Consider a network with two nodes `a` and `b` which are connected by a single branch `br_ab` whose current only depends upon the voltage difference of the two nodes. 
The matrix entries can then be calculated as follows: 

``` verilog


@@ 160,10 158,9 @@ ddx(I(<a>),V(a))=ddx(I(<b>),V(b)) = ddx(I(br_ab),V(a,b))
ddx(I(<a>),V(b))= ddx(I(<a>),V(b)) = - ddx(I(br_ab),V(a,b))
```

Since almost most equations in compact models have the form shown above using this technique effectively allows reducing the number of derivatives by a factor of 4.
Considering how large these derivatives can get it is unlikely even modern compilers could optimize these duplication's away completely.
Even if they could achieve this it would significantly increase compile time.
Therefore it is preferable for osdic to calculate derivatives by voltage difference and then calculate the Matrix entries from the result.
Almost all equations in compact models have above form using this technique effectively enables to reduce the number of derivatives by a factor of 4.
Considering how complicated and therefore computationally expensive such derivatives can be, it is unlikely even modern compilers could optimize these duplication's away completely, and even if, it would reduce compile time significantly.
Therefore it is preferable for OSDIC to calculate derivatives by voltage difference and then calculate the Matrix entries from the results.

[vams]: https://www.accellera.org/images/downloads/standards/v-ams/VAMS-LRM-2-4.pdf
[vae]: dspom.gitlab.io/VerilogAE