From 72f630f267b0233e018a2da3f73ab45a9b320ea2 Mon Sep 17 00:00:00 2001 From: dwarning Date: Tue, 15 Oct 2024 11:22:22 +0200 Subject: [PATCH] Update the Readme --- README.md | 113 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 62 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 6948c47e..28536732 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,13 @@ OpenVAF -


+
+ +## 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. @@ -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 @@ -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 @@ -75,19 +58,24 @@ 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 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: @@ -95,39 +83,53 @@ On fedora (37+) you can simply install LLVM from the default repositories: 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=/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 | 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. @@ -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