Skip to content

Commit

Permalink
Update the Readme
Browse files Browse the repository at this point in the history
  • Loading branch information
dwarning committed Oct 15, 2024
1 parent c60382d commit 72f630f
Showing 1 changed file with 62 additions and 51 deletions.
113 changes: 62 additions & 51 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,13 @@
<img alt="OpenVAF" src="logo_dark.svg">
</picture>

<br>
<br>
<br>
<br>

## About this repository

This project is a fork of the ingenious work of **Pascal Kuthe [website](https://github.com/pascalkuthe/OpenVAF)**.

OpenVAF is a Verilog-A compiler that can compile Verilog-A files for use in circuit simulator.
The major aim of this Project is to provide a high-quality standard compliant compiler for Verilog-A.
Expand All @@ -20,8 +24,7 @@ Some highlights of OpenVAF include:
* **fast simulations** surpassing existing solutions by 30%-60%, often matching handwritten models
* IDE aware design

Detailed documentation, examples and precompiled binaries of all release are **available on our [website](https://openvaf.semimod.de)**. To test the latest development version you can download nightly version of OpenVAF for [linux](https://openva.fra1.digitaloceanspaces.com/openvaf_devel-x86_64-unknown-linux-gnu.tar.gz) or [windows](https://openva.fra1.digitaloceanspaces.com/openvaf_devel-x86_64-pc-windows-msvc.tar.gz).

Detailed documentation, examples and precompiled binaries of all release are **available on our [website](https://openvaf.semimod.de)**.

## Projects

Expand All @@ -33,39 +36,19 @@ This repository currently contains the following useable projects:
OpenVAF is the main project of the repository and all other tools use OpenVAF as a library in some form.
OpenVAF can be build as a standalone CLI program that can compile Verilog-A files to shared objects that comply with the simulator independent OSDI interface.

OpenVAF has been tested with a preliminary NGSPICE prototype and Melange.
OpenVAF has been tested with a NGSPICE prototype.
It can already support a large array of compact models.
However, due to the larger feature set (compared to VerilogAE) additional testing and verification is still required.
However, due to the larger feature set additional testing and verification is still required.
Furthermore, some Verilog-A language features are currently not supported.

### VerilogAE

Allows obtaining model equations (calculates the value of a single Variable) from Verilog-A files.
VerilogAE is primarily useable from python (available on pypi) but can also be compiled as a static/shared library and called by any programming language (that supports the C ABI).

VerilogAE is used in production at SemiMod and various partners.
Its stable and ready for general use.

### Melange

Melange is an experimental circuit simulator that leverage OpenVAF to gain access to compact models.
This allows it to easily support a large array of models without the huge effort associated with traditional simulators.
The focus of Melange is primarily on automation.
That means Melange focuses on providing an ergonomic and extensible API in mainstream programming languages (python and rust currently) instead of a special purpose netlist format.
However, to remain compatible with existing PDKs a subset of the spectre netlist format can be parsed.

Melange is currently in early development and most features are not complete.
Some mockups of planned usage can be found in `melange/examples`.
Some working minimal examples (in rust) can be found in `melange/core/test.rs`.

## Building OpenVAF with docker

The official docker image contains everything required for compiling OpenVAF. To build OpenVAF using the official docker containers, simply run the following commands:
The official docker image contains everything required for compiling OpenVAF. To build OpenVAF using the docker containers, simply run the following commands:

``` shell
git clone https://github.com/gjcoram/OpenVAF.git && cd OpenVAF
git clone https://github.com/dwarning/OpenVAF.git && cd OpenVAF
# On REHL distros and fedora replace docker with podman
# on all commands below.
# on all commands below.
docker pull ghcr.io/pascalkuthe/ferris_ci_build_x86_64-unknown-linux-gnu:latest
# On Linux distros that enable SELinux linux RHEL based distros and fedora use $(pwd):/io:Z
docker run -ti -v $(pwd):/io ghcr.io/pascalkuthe/ferris_ci_build_x86_64-unknown-linux-gnu:latest
Expand All @@ -75,59 +58,78 @@ cd /io
cargo build --release
# OpenVAF will be build this can take a while
# afterwards the binary is available in target/release/openvaf
# inside the repository
# inside the repository
```

## Build Instructions
## Building OpenVAF without docker

OpenVAF **requires rust/cargo 1.64 or newer** (best installed with [rustup](https://rustup.rs/)). Furthermore, the **LLVM-15** development libraries and **clang-15** are required. Newer version also work but older versions of LLVM/clang are not supported. Note that its imperative that **you clang version matches your LLVM version**. If you want to compile VerilogAE python 3.8+ is also required.
### Prerequisite under linux

OpenVAF **requires rust/cargo 1.64 or newer** (best installed with [rustup](https://rustup.rs/)). Furthermore, the **LLVM-15** development libraries and **clang-15** are required. Newer version also work but older versions of LLVM/clang are not supported. Note that its imperative that **you clang version matches your LLVM version**.
Cargo (rustc is included) should installed by the normal apt command.

On Debian and Ubuntu the [LLVM Project provided packages](https://apt.llvm.org/) can be used:

``` shell
sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh <version number> all
```
Please use version number <17, e.g. 15.0.7 or 16.0.6. Higher gives trouble with some libs used in openVAF. Pascals docker image uses 16.

On fedora (37+) you can simply install LLVM from the default repositories:

``` shell
sudo dnf install clang llvm-devel
```

On Linux distributions where packages for LLVM-15 are not available (like centos-7) and windows you can download the prebuild LLVM packages that are also used
in our docker images. These binaries are build on centos-7 and will therefore
work on any linux distribution (that is supported by rustc):
Environment variable (in case there are different LLVM versions installed): `LLVM_CONFIG=/usr/lib/llvm-16/bin/llvm-config`
PATH should include: `usr/lib/llvm-16/bin`

* [clang and LLVM for windows](https://openva.fra1.cdn.digitaloceanspaces.com/llvm-15.0.7-x86_64-pc-windows-msvc-FULL.tar.zst)
* [clang and LLVM for linux](https://openva.fra1.cdn.digitaloceanspaces.com/llvm-15.0.7-x86_64-unknown-linux-gnu-FULL.tar.zst)
### Prerequisite under Windows

Simply download and extract these tar archives and set the `LLLVM_CONFIG` (see below) environment variable to point at the downloaded files: `LLVM_CONFIG=<extracted directory>/bin/llvm-config`.
Download [rustup-init](https://win.rustup.rs), run it to install Cargo/Rust.
During installation select "Customize installation" and set profile to "complete".

> Note: To decompress this archive you need to use the following command:
> ``` shell
> zstd -d -c --long=31 <path/to/archive.tar.zst> | tar -xf -
> ```
> afterwards the decompressed files can be found in `./LLVM`
Install Visual Studio Community Edition (tested with version 2019 and 2022). There are alternative ways only to install MSVC compiler, linker & other tools, also headers/libraries from Windows SDK by using this [download and install tool](https://github.com/Data-Oriented-House/PortableBuildTools).
Make sure you install CMake Tools that come with Visual Studio or by alternative windows installation.

Build LLVM and Clang, download [LLVM 16.0.6](https://github.com/llvm/llvm-project/releases/tag/llvmorg-16.0.6) sources (get the .zip file)

Once all dependencies have been installed you can build the entire project by running:
Unpack the sources. This creates directory `llvm-project-llvmorg-16.0.6`. Create a directory named `build` in parallel.

``` shell
cargo build --release
Start Visual Studio x64 native command prompt.
Run CMake, using nmake as build system (default). Alternativ Ninja build system is possible by given switch `-G ninja'.
Replace `c:\llvm` with the path where you want your LLVM and Clang binaries and libraries to be installed.
```
cmake -S llvm-project-llvmorg-16.0.6\llvm -B build -DCMAKE_INSTALL_PREFIX=C:\LLVM -DCMAKE_BUILD_TYPE=Release -DLLVM_TARGETS_TO_BUILD="X86;ARM;AArch64" -DLLVM_ENABLE_PROJECTS="llvm;clang"
```
Build and install:
```
cd build
nmake
nmake install
```
The LLVM build needs some time!

To only build OpenVAF (and ignore melange/VerilogAE) you can run:
Environment variable (in case there are different LLVM versions installed): `LLVM_CONFIG=C:\LLVM\bin\llvm-config.exe`
PATH should include: `C:\LLVM\bin`

### Build OpenVAF

To build OpenVAF you can run:

``` shell
cargo build --release --bin openvaf
```
Place the binary from `openvaf/target/release` in one location of your PATH.


By default, OpenVAF will link against the static LLVM libraries, to avoid runtime dependencies. This is great for creating portable binaries but sometimes building with shared libraries is preferable. Simply set the `LLVM_LINK_SHARED` environment variable during linking to use the shared system libraries. If multiple LLVM versions are installed (often the case on debian) the `LLVM_CONFIG` environment variable can be used to specify the path of the correct `llvm-config` binary.
An example build invocation using shared libraries on debian is shown below:

``` shell
LLVM_LINK_SHARED=1 LLVM_CONFIG="llvm-config-15" cargo build --release
LLVM_LINK_SHARED=1 LLVM_CONFIG="llvm-config-16" cargo build --release
```

OpenVAF includes many integration and unit tests inside its source code.
Expand All @@ -144,20 +146,29 @@ By default, the test suite will skip slow integration tests that compile entire
These can be enabled by setting the `RUN_SLOW_TESTS` environment variable:

``` shell
RUN_SLOW_TESTS=1 cargo nextest run
RUN_SLOW_TESTS=1 cargo nextest run
```

During development, you likely don't want to run full release builds as these
can take a while to build. Debug builds are much faster:
``` shell
cargo build # debug build
cargo run --bin opnevaf test.va # create a debug build and run it
cargo run --bin openvaf test.va # create a debug build and run it
cargo clippy # check the sourcecode for errors/warnings without building (even faster)
```

## Download binaries and usage OpenVAF

You can download binaries for Linux and Windows [here](https://github.com/dwarning/OpenVAF/releases/tag/v1.0).
OpenVAF needs a linker. On Linux at most linke is part of the operating system - on windows you need the MS linker `link.exe`.

``` shell
openvaf your_verilog-a-model.va
```

## Acknowledgement

The architectures of the [rust-analyzer](https://github.com/rust-analyzer/rust-analyzer) and [rustc](https://github.com/rust-lang/rust/) have heavily inspired the design of this compiler.
Geoffrey Coram and Arpad Buermen are authors of several bugfixes included in this fork.

## Copyright

Expand Down

0 comments on commit 72f630f

Please sign in to comment.