This repository contains a series of examples showing how to use SimBricks.
The repository is set up with a dev container configuration that makes running the examples a breeze. For quick tests you can just open the repo in CodeSpaces. The easiest way to use this is with vscode and its Dev Containers Extension (details on setup)
Under first-steps/first_steps.ipynb
you will
find an iPython Notebook with an interactive introductions for your first steps
with SimBricks. This introduces the basic concepts for how to configure and run
SimBricks simulations. For initial quick playing around, you can even
immediately open this in the browser with
mybinder
(although there you will not have enough compute for anything interesting).
Any non-trivial project will typically require you to set up custom disk images for your simulated hosts to install necessary software dependencies and tools. In this simple example, we demonstrate an easy way to do this, by creating an image with memcached and a simple client benchmark, and then configuring and running a simple simulation using this image. Start here
This is a series of course projects on hardware acceleration, demonstrating a complete SimBricks-based development flow, from initial software profiling to Verilog-RTL implementation. The example is split up in multiple project milestones with step-by-step instructions, for the different development stages. Start here
You can plug your own RTL into SimBricks for end-to-end evaluation or for full-system integration testing instead of writing complex Verilog testbenches. Here, we integrate an open-source Verilog JPEG decoder as a PCIe-based HW accelerator along with the necessary user-space driver.
This repository is set up with a devcontainer configuration based on the SimBricks Docker Images. This is the easiest way of starting to use SimBricks, as you do not have to manually install dependencies, build SimBricks, or set up other environment components. You will need a working docker setup. We recommend doing this natively on Linux, but Windows and OS X should work as well (with some restrictions).
First off, you will need a working docker installation. The docker
documentation has instructions. For
some of the simulations (gem5 with kvm-checkpointing) you need a system with kvm
virtualization available and enabled. You only need kernel support (among other
things /dev/kvm
has to exist), but no user space qemu-kvm setup etc. is
required.
You need to install docker desktop. We have tested with the WSL2 backend.
Here as well you would need at least a working docker desktop installation. We have not recently tested kvm support on OS-X.
The easiest way to use this is with vscode and its Dev Containers Extension. If you have a working docker setup and the extension installed, once you open a workspace for the cloned repo, vscode will prompt you to re-open in the devcontainer. vscode will then automatically set up the container, start it, and automatically have the terminals in vscode run inside the container.
If you prefer using the commandline directly you could give the devcontainers cli a try. This will also take care of starting and initializing the container, just as with vscode.
You first have to set up the container. For this, run the following command in
the root directory of the project, that is the hwaccel-class-project
folder
in this repository: devcontainer up --workspace-folder .
To then run an interactive shell in the container, run:
devcontainer exec --workspace-folder . bash
. You can replace bash with any
other commands if you just want to run an individual command.
Note that devcontainers cli goes quite a bit beyond just docker run
. Instead
this will set up a user with a correct UID for a user in the container matching
yours, mount the workspace directory in the container, and run additional
initialization commands. But you can do this manually too, if you prefer, in
which case you can directly use the
simbricks/simbricks-examples
docker image. This image just extends the simbricks/simbricks
image
some development tools (including ipython).
Finally, you can of course also build everything locally. For that please refer to the README in the main SimBricks repo.