.. note:: :class: sphx-glr-download-link-note Click :ref:`here ` to download the full example code .. rst-class:: sphx-glr-example-title .. _sphx_glr_how_to_work_with_microtvm_micro_reference_vm.py: .. _tutorial-micro-reference-vm: =================================== 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: 1. A Vagrant Base Box, which contains all of the stable dependencies for that platform. Build scripts are stored in ``apps/microtvm/reference-vm//base-box``. TVM committers run these when a platform's "stable" dependencies change, and the generated base boxes are stored in `Vagrant Cloud`_. 2. A per-workspace VM, which users normally build using the Base Box as a starting point. Build scripts are stored in ``apps/microtvm/reference-vm/`` (everything except ``base-box``). .. _Vagrant: https://vagrantup.com .. _Vagrant Cloud: https://app.vagrantup.com/tlcpack Setting up the VM ================= Installing prerequisites ------------------------ A minimal set of prerequisites are needed: 1. `Vagrant `__ 2. 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. .. _VirtualBox Extension Pack: https://www.virtualbox.org/wiki/Downloads#VirtualBox6.1.16OracleVMVirtualBoxExtensionPack 3. If required for your hypervisor, the `Vagrant provider plugin `__ (or see `here `__ for VMWare). First boot ---------- The first time you use a reference VM, you need to create the box locally and then provision it. .. code-block:: bash # Replace zephyr with the name of a different platform, if you are not using Zephyr. ~/.../tvm $ cd apps/microtvm/reference-vm/zephyr # Replace 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= 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: 1. Downloads the `microTVM base box`_ and clones it to form a new VM specific to this TVM directory. 2. Mounts your TVM directory (and, if using ``git-subtree``, the original ``.git`` repo) into the VM. 3. Builds TVM and installs a Python virtualenv with the dependencies corresponding with your TVM build. .. _microTVM base box: https://app.vagrantup.com/tlcpack/boxes/microtvm 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: * `VirtualBox `__ * `Parallels `__ * `VMWare Workstation `__ Rebuilding TVM inside the Reference VM -------------------------------------- After the first boot, you'll need to ensure you keep the build, in ``$TVM_HOME/build-microtvm-zephyr``, 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 ``build-microtvm-zephyr``. Logging in to the VM -------------------- The VM should be available to your host only with the hostname ``microtvm``. You can SSH to the VM as follows: .. code-block:: bash $ vagrant ssh Then ``cd`` to the same path used on your host machine for TVM. For example, on Mac: .. code-block:: bash $ cd /Users/yourusername/path/to/tvm Running tests ============= Once the VM has been provisioned, tests can executed using ``poetry``: .. code-block:: bash $ cd apps/microtvm/reference-vm/zephyr $ poetry run python3 ../../../../tests/micro/qemu/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: .. code-block:: bash $ cd /Users/yourusername/path/to/tvm $ cd apps/microtvm/reference-vm/zephyr/ $ poetry run pytest ../../../../tests/micro/qemu/test_zephyr.py --zephyr-board=qemu_x86 .. _sphx_glr_download_how_to_work_with_microtvm_micro_reference_vm.py: .. only :: html .. container:: sphx-glr-footer :class: sphx-glr-footer-example .. container:: sphx-glr-download :download:`Download Python source code: micro_reference_vm.py ` .. container:: sphx-glr-download :download:`Download Jupyter notebook: micro_reference_vm.ipynb ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_