dbhi / containers Goto Github PK

Dynamic Binary Hardware Injection (DBHI) is a workflow towards decoupled functional hardware-software co-design on SoCs with FPGA, through injection of compiled HDL designs. The design flow is constructed from existing off-the-shelf tools, and it is tested on multiple architectures (ARMv7, ARMv8 and x86-64).

Resources, tools and examples are organized in multiple repositories:

• dbhi/dbhi: main repository, contains the documentation, publications and examples. Dependencies are included as submodules:
  • VUnit/vunit: a unit testing framework for VHDL/SystemVerilog.
  • VUnit/cosim: extends VUnit with co-simulation features.
  • beehive-lab/mambo: a low-overhead dynamic binary instrumentation and modification tool for ARM.
  • dbhi/gRPC: Go sources of the DBHI gRPC server, and common sources to embed Go gRPC clients in C applications.
• Other helper repositories:
  • dbhi/containers: sources and CI configuration to containerize open and free development tools that allow to evaluate DBHI. Images are periodically pushed to docker.io/aptman/dbhi.
  • dbhi/qus: qemu-user-static (qus) and docker, non-invasive minimal working and non-working setups. Used by dbhi/containers.

The list of required tools to run the examples is the following:

• GHDL
• VUnit
• Either of:
  • MAMBO (only avilable for ARM platforms)
  • DynamoRIO
• (Optional) GtkWave
• (Optional, to use gRPC) Go(lang)

Ready-to-use container images (for docker/podman) are available at docker.io/aptman/dbhi. These images include all the required dependencies to evaluate the design flow with lightweight, open and free tools.

Images provided by docker-library/official-images are used to build manifests for amd64, arm64v8 and arm32v7 platforms. Currently, all the images are based on Ubuntu 18.04 (bionic). See dbhi/containers for further details.

If docker|podman is available on your target platform, using the provided images is recommended, because the overhead is negligible, it helps reproducibility and it significantly reduces setup time. The following script can be used to test if a platform fulfills the requirements to run the docker daemon:

curl -fsSL https://raw.githubusercontent.com/moby/moby/master/contrib/check-config.sh | bash -

Should you want to install the tools natively on your host, the dockerfiles at dbhi/containers can be used as a reference (i.e., the same steps can be reproduced in a shell script). Nonetheless, please read the following notes carefully:

• Ensure that all the libraries are built with -fPIC when building GHDL.
• VUnit can be installed in a default location (e.g. pip install vunit_hdl), or:
  • It must be cloned recursively, and
  • colorama must be installed (e.g. pip install colorama).
• MAMBO must be recursively cloned.
• To get DynamoRIO, a release tarball can be downloaded or it can be built from sources.

NOTE: If GHDL, VUnit and/or DynamoRIO are installed in custom locations, these can be defined through PATH, PYTHONPATH and/or DYNAMORIO_HOME, respectively.

NOTE: Building DynamoRIO with g++-8 fails on amd64. Using g++-6 or g++-7 is suggested.