This project is based on a fork of the xc-bela-container project with added support for IREE projects on Bela. The image comes with IREE host binaries pre-installed, some IREE tools cross-compiled for Bela, a CMake toolchain for building IREE runtime components as well as instructions for benchmarking and profiling IREE programs. Please see the IREE project for more details on IREE.
By containerizing the cross-compilation toolchain, Bela code can be written and compiled on any host OS that can run Docker, and is compiled much faster and with more flexibility than in the Bela IDE. The VSCode environment is also set up for running GDB over SSH, allowing you to debug your Bela programs in the editor. This repo is set up to be used with VSCode.
This project is built with Docker, you can see instructions for installing it here.
You should also have a Bela with a Debian Bullseye image installed (>v0.5a) as well as the linux-perf package if you want to record profiles (sudo apt install linux-perf)
Once Docker is installed, you can continue the setup using just the command line or using VSCode, both options are shown below.
To use this Docker image with VSCode, first clone thi repository:
git clone --recurse-submodules https://github.com/ezrapierce000/bela-iree-container.gitInstall the Docker and Remote Development extensions, if you haven't already.
Open the repo folder in VSCode and run the command Remote-Containers: Reopen in Container or click the popup when prompted, ensure that the environment variables are set accordingly based on the Environment Variables section. This will download the image, install a few extensions and attach the editor to the container.
First, pull the latest docker image:
docker pull ezrapierce000/xc-bela-iree:latestThen, start and open a shell in the container by running:
docker run -it ezrapierce000/xc-bela-iree:latestNow, with Bela powered on, change directories, cd /home/scripts and run a test benchmark on Bela ./benchmark_test.sh. This test uploads the iree-benchmark-module tool to the Bela and runs a benchmark on a single multiply between two 4xfloat32 values.
Once you are in the container, move to /workspaces/bela-iree-container/models/embedded-model-zoo and run conda activate zoo && python -m zoo. This will create some untrained models for you to try compiling and benchmarking. Alternatively you can load you own TFLite, TOSA or MHLO files.
To compile your models into the IREE flatbuffers you can use the compile utility. To see how to use the utility simply run the command with no options. You can see more in depth documentation from the iree compiler by running iree-compile --help.
Once you have an IREE module compiled, you can benchmark and profile it on Bela.
To benchmark a model on Bela use the benchmark command. Once again, run the utility with no options to see how to use it. This utility requires you to already have a compiled VMFB file in either VMVX bytecode or LLVMIR.
To profile a model on Bela use the profile command.
TODO: notes on TraceCompass
The extensions installed by default are:
- clangd - much better IDE features for C/C++ than the Microsoft extension
- Native Debug - support for debugging over SSH
- CMake Tools - CMake support for building and debugging
- cmake - syntax highlighting for CMake files
Some others you may want to install locally:
- DeviceTree - syntax highlighting for device tree files
- PASM Syntax - syntax highlighting for PRU assembly
- Docker - helpful for managing containers in general, also provides syntax highlighting for Dockerfiles
Extensions are stored on a Docker volume, so they will persist through container rebuilds - so you shouldn't need to edit devcontainer.json to add extensions, just install them normally.
.devcontainer/devcontainer.env contains important environment variables that you should set before building the container:
- BBB_HOSTNAME - set this to the IP address of your Bela (could be 192.168.6.2, 192.168.7.2, etc)
You can set any other variables you wish in this file; they will all be sourced when the container starts up.
You don't usually need to build the image - Docker will pull it from Docker Hub automatically when you open the dev container for the first time. However, if you want to make changes that will persist across container boots, you can rebuild the image yourself. Note: These instructions are written for macOS/Linux.
First, make sure your Bela is connected - you'll need to copy some headers and libraries from it and compile the libbelafull static library. Open scripts/build_settings and change BBB_HOSTNAME to the IP address of your connected Bela.
If the Bela needs to be updated (e.g. if the static libraries haven't been compiled), run these commands:
Bela/scripts/update_board.sh
scripts/build_libs.shEnsure that the IREE submodule was properly initiated by running git submodule update --init.
You will only need to do this once, unless you change any of the core library code. Make any changes you wish to the scripts/Dockerfile, then start the build:
docker build --tag xc-bela-iree:mybuild .Finally, update .devcontainer/devcontainer.json to use your custom build:
...
"context": ".",
"image": "xc-bela-iree:mybuild",
"workspaceFolder": "/workspace",
...This project is based on a fork of the xc-bela-container project. All credit for the Bela code goes to Bela and Augmented Instruments Ltd. As per the license terms, this project is also licensed under the LGPLv3.