microTVM Reference Virtual Machines¶
Author: Andrew Reusch
This tutorial explains how to launch microTVM Reference Virtual Machines. You can use these to develop on real physical hardware without needing to individually install the microTVM dependencies. These are also particularly useful when trying to reproduce behavior with microTVM, such as when filing bug reports.
microTVM is the effort to allow TVM to build and execute models on bare-metal microcontrollers. microTVM aims to be compatible with a wide variety of SoCs and runtime environments (i.e. bare metal, RTOS, etc). However, some stable software environment is needed to allow developers to share and reproduce bugs and results. The microTVM Reference Virtual Machines are intended to provide that environment.
How it works¶
No Virtual Machines are stored in the TVM repository–instead, the files stored in
apps/microtvm/reference-vm describe how to build VMs to the Vagrant VM builder tool.
The Reference VMs are split into two parts:
A Vagrant Base Box, which contains all of the stable dependencies for that platform. Build scripts are stored in
apps/microtvm/reference-vm/<platform>/base-box. TVM committers run these when a platform’s “stable” dependencies change, and the generated base boxes are stored in Vagrant Cloud.
A per-workspace VM, which users normally build using the Base Box as a starting point. Build scripts are stored in
Setting up the VM¶
A minimal set of prerequisites are needed:
A supported Virtual Machine hypervisor (VirtualBox, Parallels, or VMWare Fusion/Workstation). VirtualBox is a suggested free hypervisor, but please note that the VirtualBox Extension Pack is required for proper USB forwarding. If using VirtualBox, also consider installing the vbguest plugin.
The first time you use a reference VM, you need to create the box locally and then provision it.
# Replace zephyr with the name of a different platform, if you are not using Zephyr. ~/.../tvm $ cd apps/microtvm/reference-vm/zephyr # Replace <provider_name> with the name of the hypervisor you wish to use (i.e. virtualbox, parallels, vmware_desktop). ~/.../tvm/apps/microtvm/reference-vm/zephyr $ vagrant up --provider=<provider_name>
This command will take a couple of minutes to run and will require 4 to 5GB of storage on your machine. It does the following:
Downloads the microTVM base box and clones it to form a new VM specific to this TVM directory.
Mounts your TVM directory (and, if using
git-subtree, the original
.gitrepo) into the VM.
Builds TVM and installs a Python virtualenv with the dependencies corresponding with your TVM build.
Connect Hardware to the VM¶
Next, you need to configure USB passthrough to attach your physical development board to the virtual machine (rather than directly to your laptop’s host OS).
It’s suggested you setup a device filter, rather than doing a one-time forward, because often the device may reboot during the programming process and you may, at that time, need to enable forwarding again. It may not be obvious to the end user when this occurs. Instructions to do that:
Rebuilding TVM inside the Reference VM¶
After the first boot, you’ll need to ensure you keep the build, in
up-to-date when you modify the C++ runtime or checkout a different revision. You can either
re-provision the machine (
vagrant provision in the same directory you ran
vagrant up before)
or manually rebuild TVM yourself.
Remember: the TVM
.so built inside the VM is different from the one you may use on your host
machine. This is why it’s built inside the special directory
Logging in to the VM¶
The VM should be available to your host only with the hostname
microtvm. You can SSH to the VM
$ vagrant ssh
cd to the same path used on your host machine for TVM. For example, on Mac:
$ cd /Users/yourusername/path/to/tvm
Once the VM has been provisioned, tests can be executed using
$ cd apps/microtvm/reference-vm/zephyr $ poetry run python3 ../../../../tests/micro/zephyr/test_zephyr.py --zephyr-board=stm32f746g_disco
If you do not have physical hardware attached, but wish to run the tests using the local QEMU emulator running within the VM, run the following commands instead:
$ cd /Users/yourusername/path/to/tvm $ cd apps/microtvm/reference-vm/zephyr/ $ poetry run pytest ../../../../tests/micro/zephyr/test_zephyr.py --zephyr-board=qemu_x86