OpenVAF-reloaded

OpenVAF is a Verilog-A compiler written by Pascal Kuthe. The compiler outputs a dynamic library whose functionality can be accessed via the OSDI API (version 0.3). The original compiler received no support since end of 2023. This fork of the original repository was started by Árpád Bűrmen in early 2024. Since then several small bugs were fixed that prevented the use of OpenVAF for building SPICE3 equivalent device models.

New functionality will be added to OpenVAF in the future. In order to achieve this the OSDI interface was modified to accommodate the changes. Consequently the current version of OSDI API is 0.4. OSDI API 0.4 differs from version 0.3 in the module descriptor. It also exports OSDI_DESCRIPTOR_SIZE which can be used to traverse the array of descriptors without relying on the definition of the OsdiDescriptor structure. New members are added after the first part of the descriptor which still complies with OSDI specification v0.3. Simulators that rely on OSDI v0.3 can still use compiled models using the newer OSDI API by applying some minor changes.

The last version of OpenVAF before the project was renamed to OpenVAF-reloaded and the binary was renamed to openvaf-r is tagged with osdi_0.3. Currently two branches are maintained: master branch using the OSDI 0.4 API and a branch named branches/osdi_0.3 using the old OSDI 0.3 API. Both branches include bugfixes by Geoffrey Coram and Dietmar Warning.

OSDI 0.4

In OSDI 0.4 new members are added to the module descriptor data structure after the members defined in the OSDI specification v0.3. The descriptor (if cast to the declaration given in the OSDI 0.3 header file) remains compatible with OSDI 0.3 and should work just like before. Simulators using OSDI API 0.3 can be adapted to use version 0.4 by applying the following changes

• allowing major.minor version >=0.4 beside 0.3,
• reading the OSDI_DESCRIPTOR_SIZE symbol of type uint32 specifying the descriptor size,
• making sure the table of descriptors (pointed to by the OSDI_DESCRIPTORS symbol) is traversed in steps of size OSDI_DESCRIPTOR_SIZE instead of sizeof(OsdiDescriptor), and
• casting each descriptor to the structure declared in the OSDI header file, version 0.3.

This is the current state of OSDI 0.4 support

If you know of any other simulator supporting OSDI models generated by OpenVAF, let me know.

Some internals of the OpenVAF compiler are documented in the internals.md file.

What is new in OSDI 0.4?

• OSDI descriptor size for traversing the OSDI descriptor table in simulators not supporting OSDI 0.4
• Support for reading param given flags of parameters in the instance and model data structures. This is pretty much self-explanatory. Look at the OSDI 0.4 header file. This one takes care of issue #76 in the original repository.
• Support for writing nonzero resistive and reactive Jacobian contributions to an array of doubles.
• List of model inputs (node pairs) that produce a nonlinear response.

What about binaries?

Yes, binaries for 64-bit Linux and Windows are available here. The naming scheme of the binaries is

openvaf-reloaded-<version>-<platform>

The version name is generated with git --describe. The OpenVAF-reloaded that produces models with the OSDI API v0.3 is version osdi_0.3. All newer versions (osdi_0.4) produce models with OSDI API v0.4.

If the binary is named openvaf it comes from the branches/osdi_0.3 branch and produces models with the OSDI 0.3 API. If the binary is named openvaf-r it comes from the master branch and produces models with the OSDI 0.4 API.

Building OpenVAF-reloaded

Setting up the dependencies under Debian Bookworm

Get LLVM 15 built by Pascal (do not use the Debian-supplied version). You can also build your own LLVM and Clang 15.0.7 from sources.

Unpack Pascal's binaries in /opt as root (creates directory /opt/LLVM). You will need zstd for that.

cd /opt
zstd -d -c --long=31 <path/to/archive.tar.zst> | tar -xf -

Install Rust as ordinary user (files will go to ~/.cargo and ~/.rustup).

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

During installation select "Customize installation" and set profile to "complete".

Set LLVM_CONFIG, add LLVM to PATH, and set up the working environment for Rust. Add these lines at the end of .bashrc

. "$HOME/.cargo/env"
export LLVM_CONFIG=/opt/LLVM/bin/llvm-config
export PATH=/opt/LLVM/bin:$PATH

Restart shell. You're good to go.

Setting up the dependencies under Windows

Download rustup, run it to install Rust. During installation select "Customize installation" and set profile to "complete".

Install Visual Studio 2019 Community Edition (tested with version 16.11.33) Make sure you install CMake Tools that come with VS2019 (also installs Ninja).

Build LLVM and Clang, download LLVM 15.0.7 sources (get the .zip file)

Unpack the sources. This creates directory llvm-project-llvmorg-15.0.7. Create a directory named build.

Start Visual Studio x64 native command prompt. Run CMake, use Ninja as build system. Do not use default (nmake) because for me it always built the Debug version, even when I specified Release. Replace e:\llvm with the path where you want your LLVM and Clang binaries and libraries to be installed.

cmake -G Ninja -S llvm-project-llvmorg-15.0.7\llvm -B build -DCMAKE_INSTALL_PREFIX=e:\LLVM -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86;ARM;AArch64" -DLLVM_ENABLE_PROJECTS="llvm;clang"

Run Ninja (build and install)

ninja -C build
ninja -C build install 

Now you have your own LLVM and Clang. Hope it did not take too many Snickers :).

The LLVM and Clang version built by Pascal did not work for me (the openvaf binary failed to link due to undefined symbols).

Add LLVM to the PATH (in the above example that would be e:\llvm\bin). Set the LLVM_CONFIG environmental variable if you have multiple LLVM installations (for the above example that would be e:\llvm\bin\llvm-config.exe).

Restart command prompt. Now you are good to go.

Building

To build the release version (target/release/openvaf-r), type

cargo build --release --bin openvaf-r

To build the debug version (target/debug/openvaf-r), type

cargo build --bin openvaf-r

Debugging OpenVAF-reloaded in Visual Studio Code

You will need two extensions: CodeLLDB and rust-analyzer. In the .vscode directory there are two files: launch-openvaf-r.json (for working with the master branch) and launch-openvaf.json (for working with the branches/osdi_0.3 branch). Copy the one that matches your branch to launch.json. There is a debug setup in that file. Set your breakpoints and run the program. If there are any changes since the last build they will be applied upon which the program will be started and then stop at the first breakpoint.

The debug configuration disables rayon running the .osdi file build process in parallel so that debugging the last step of compilation is somewhat easier.

Acknowledgement

Kudos to Pascal Kuthe for the great work he did.

Geoffrey Coram and Dietmar Warning are authors of several bugfixes included in OpenVAF-reloaded.

Copyright

This work is free software and licensed under the GPL-3.0 license. It contains code that is derived from rustc and rust-analyzer. These projects are both licensed under the MIT license. As required a copy of the license and disclaimer can be found in copyright/LICENSE_MIT.

Many models in integration tests folder are not licensed under a GPL compatible license. All of those models contain explicit license information. They do not endup in the openvaf binary in any way and therefore do not affect the license of the entire project. Integration tests without explicit model information (either in the model files or in a dedicated LICENSE file) fall under GPLv3.0 like the rest of the repo.