A modeling library with virtual components for SystemC and TLM simulators
The Virtual Components Modeling Library contains a set of SystemC/TLM modeling primitives and component models that can be used to swiftly assemble system level simulators for embedded systems, i.e. Virtual Platforms. Its main design goal is to accelerate VP construction by providing a set of commonly used features, such as TLM sockets, Interrupt ports, I/O peripherals and registers. Based on these design primitives, TLM models for frequently deployed components are also provided, such as memories, memory-mapped buses, UARTs, etc.
In order to build vcml
, you need a working installation of SystemC.
Currently, versions >= 2.3.0 are supported. Furthermore, you need cmake
,
libelf
and, optionally, libvncserver
if you also want graphics support.
This is how to build and install them:
Optional: download and build SystemC (here systemc-2.3.2
). Make sure to
set the environment variables SYSTEMC_HOME
and TARGET_ARCH
accordingly:
wget http://www.accellera.org/images/downloads/standards/systemc/systemc-2.3.2.tar.gz
tar -xzf systemc-2.3.2.tar.gz && cd systemc-2.3.2
export SYSTEMC_HOME=`pwd`
export TARGET_ARCH=linux64
mkdir BUILD && cd BUILD
../configure --prefix=$SYSTEMC_HOME --enable-optimize --enable-static
make -j 4 && make install
Note: if you choose to skip this step, vcml
will automatically download
SystemC from github.com/machineware-gmbh/systemc.git
during configuration
and set the environment variables accordingly for this build.
Note: you can provide your own SystemC installation by specifing your own
SYSTEMC_HOME
and TARGET_ARCH
variables. Versions starting from 2.3.0
are supported.
Download and install cmake
:
Install optional dependencies:
Lua
for scripting supportSDL2
for graphic outputlibvnc
for remote graphic outputlibslirp
for userspace ethernet emulation# Ubuntu
sudo apt-get install liblua5.4-dev libsdl2-dev libvncserver-dev libslirp-dev
# Fedora
sudo dnf install lua-devel SDL2-devel libvncserver-devel libslirp-devel
Optional dependencies are automatically enabled if found by cmake
on the
host build system. To disable their use, pass -DUSE_<LUA|SDL2|VNC|SLIRP>=FALSE
to cmake
during configuration (see step 6).
Clone VCML repository and initialize submodules:
git clone https://github.com/machineware-gmbh/vcml.git --recursive
or, alternatively
git clone https://github.com/machineware-gmbh/vcml.git
git submodule init
git submodule update
Chose directories for building and deployment:
<source-dir> location of your repo copy, e.g. /home/jan/vcml
<build-dir> location to store object files, e.g. /home/jan/vcml/BUILD
<install-dir> output directory for binaries, e.g. /opt/vcml
Configure and build the project using cmake
. During configuration you must
state whether or not to build the utility programs and unit tests:
-DVCML_BUILD_UTILS=[ON|OFF]
: build utility programs (default: ON
)-DVCML_BUILD_TESTS=[ON|OFF]
: build unit tests (default: OFF
)Release and debug build configurations are controlled via the regular parameters:
mkdir -p <build-dir>
cd <build-dir>
cmake -DCMAKE_INSTALL_PREFIX=<install-dir> -DCMAKE_BUILD_TYPE=RELEASE <source-dir>
make -j 4
sudo make install
sudo make -C mwr install
sudo make -C systemc install # if you skipped step 1
If building with -DVCML_BUILD_TESTS=ON
you can run all unit tests using
make test
within <build-dir>
.
After installation, the following new files should be present:
<install-dir>/lib/libvcml.a # library
<install-dir>/include/vcml.h # library header
<install-dir>/include/vcml/ # header files
<install-dir>/bin/ # utility programs
Update your environment so that other projects can reference your build:
export VCML_HOME=<install-dir>
Debug builds (i.e. -DCMAKE_BUILD_TYPE=DEBUG
) are intended for developers
that use vcml
to construct a new VP and want to track down bugs.
Note that these builds operate significantly slower than optimized release
builds and should therefore not be used for VPs that are used productively,
e.g. for target software development. To maintain both builds from a single
source repository, try the following:
git clone https://github.com/machineware-gmbh/vcml.git --recursive && cd vcml
home=$PWD
for type in "DEBUG" "RELEASE"; do
install="$home/BUILD/$type"
build="$home/BUILD/$type/BUILD"
mkdir -p $build && cd $build
cmake -DCMAKE_BUILD_TYPE=$type -DCMAKE_INSTALL_PREFIX=$install $home
make install
done
Afterwards, you can use the environment variable VCML_HOME
to point to the
build you want to use:
export VCML_HOME=(...)/vcml/BUILD/DEBUG
for the debug build orexport VCML_HOME=(...)/vcml/BUILD/RELEASE
for the release buildWindows builds are currently supported using
Microsoft Visual Studio.
There are two ways to build vcml
on Windows:
Clone a Repository
https://github.com/machineware-gmbh/vcml
and click Clone
vcml
folderBuild All
from the build menu.git-bash
(installed by Git for Windows)git clone --recursive https://github.com:machineware-gmbh/vcml
cmake -B BUILD -G "Visual Studio 17" -DCMAKE_BUILD_TYPE=[DEBUG|RELEASE]
cmake --build BUILD
Some basic documentation about this library and its models can be found
here.
Another potential useful source for help can be the study of projects that
employ VCML to construct a complete VP, for example
or1kmvp
.
Please note that we currently cannot accept Pull Requests on Github. Instructions on how to contribute to VCML, along with a curated collection of existing contributions in the form of individual models or complete Virtual Platforms can be accessed on our community projects website at:
https://www.machineware.de/vcml-community
This project is licensed under the Apache-2.0 license - see the LICENSE file for details.