diff --git a/apps/microtvm/reference-vm/README.md b/apps/microtvm/reference-vm/README.md index 7ff75c75b4f91..9303c0a64eceb 100644 --- a/apps/microtvm/reference-vm/README.md +++ b/apps/microtvm/reference-vm/README.md @@ -15,53 +15,100 @@ -# microTVM Reference Virtual Machines +# microTVM Reference Virtual Machines (RVM) -This directory contains Vagrant specifications that create reference Virtual Machines for use with -microTVM. These machines help microTVM users collaborate by providing a stable reference test -environment. +This directory contains Vagrant specifications that create Reference Virtual +Machines (RVM) for use with microTVM. These machines help microTVM users +collaborate by providing a stable reference environment to build and test +microTVM. -For more information on how to use them, see the microTVM Reference Virtual Machines tutorial. +For more information on how to use them, see the +[microTVM Reference VM tutorial](../../../tutorials/micro/micro_reference_vm.py). -## Reference VM Developer Information +## microTVM Developer Information -Each RTOS or platform that integrates with microTVM can check-in a Reference VM in this directory to -help the community collaborate. You should use the tools provided here to ensure a uniform release -process across all platforms. Typically, releases need to be created by TVM committers. +Each RTOS or platform (like Zephyr, Ardunio, etc) that integrates with microTVM +can check-in a Reference VM in this directory to help the community collaborate. +You should use the tools provided here to ensure a uniform release process +across all platforms. Typically, releases need to be created by TVM committers. -Generally speaking, it's expected that any integrated platform with a regression test checked-in to -the tvm repository should also define a reference VM. If you want to integrate a new platform, -please raise a discussion on [the forum](https://discuss.tvm.ai). +Generally speaking, it's expected that any integrated platform with a regression +test checked-in to the tvm repository should also define a reference VM. If you +want to integrate a new platform, please raise a discussion on +[the forum](https://discuss.tvm.ai). -### Organization -Reference VMs are organized as follows: +## Reference VMs Organization + +Reference VMs are organized in this directory as follows: + +``` +. ++-- base-box-tool.py - Reference VM build, test, and release tool. ++-- PLATFORM/ - One or more dirs related to the supported platform(s), + like zephyr/ and arduino/. The dir names are the same to + be passed as arguments to base-box-tool.py as PLATFORM. + +-- Vagrantfile - Vagrantfile that end-users will invoke. Should be based + | off a base box which contains dependencies other than the + | TVM python dependencies. + +-- base-box/ - Top-level directory which defines the base box. + +-- Vagrantfile.packer-template - 'packer' template Vagrantfile which + | will be used to build the base box. + +-- test-config.json - JSON file explaining how to perform + release tests to base-box-tool.py. +``` -* `base-box-tool.py` - Reference VM build, test, and release tool -* `/` -** `Vagrantfile` Vagrantfile that end-users will inovke. Should be based off a base box - which contains dependencies other than the TVM python dependencies. -** `base-box` - Top-level directory which defines the base box. -*** `Vagrantfile.packer-template` - Packer template Vagrantfile which will be used to build the - base box. -*** `test-config.json` - JSON file explaining how to perform release tests to `base-box-tool.py` ## Creating Releases -1. Build the base box for the given platform: `$ ./base-box-tool.py [--provider=] build ` -2. Run release tests for each platform: - 1. Connect any needed hardware to the VM host machine. - 2. Run tests: `$ ./base-box-tool.py [--provider=] test [--microtvm-platform=] [--test-device-serial=]`. This - command does the following for each provider: - 1. Copies all files inside `./` except `.vagrant` and `base-box` to - `./release-test`. This is done to avoid reusing any VM the developer may have started. - 2. Executes `$ vagrant up [--provider=]`. - 3. Finds an attached USB device matching the VID and PID specified in `test-config.json`, - and if `--test-device-serial` was given, that serial number (as reported to USB). Creates - a rule to autoconnect this device to the VM, and also attaches it to the VM> - 4. SSHs to the VM, `cd` to the TVM root directory, and runs `test_cmd` from - `test-config.json`. Nonzero status means failure. -3. If release tests fail, fix them and restart from step 1. -4. If release tests pass: `$ ./base-box-tool.py [--provider=] release <--release-version=> <--platform-version=> `. Be sure you've logged - in to Vagrant Cloud using the `vagrant` tool. +1. **Build** the base box for a given platform: +```bash +$ ./base-box-tool.py [--provider=PROVIDER] build PLATFORM +``` + +For example: +```bash +$ ./base-box-tool.py --provider virtualbox build zephyr +``` + +2. **Run** release tests for each platform: + + A. Connect any needed hardware to the VM host machine; + + B. Run tests: + ```bash + $ ./base-box-tool.py [--provider=PROVIDER] test --microtvm-platform=MICROTVM_PLATFORM [--test-device-serial=SERIAL] PLATFORM + ``` + where MICROTVM_PLATFORM is one of the options listed in the + PLATFORM/base-box/test-config.json file. + + For example: + ```base + $ ./base-box-tool.py --provider virtualbox test --microtvm-platform=stm32f746xx_disco zephyr + ``` + + This command does the following for the specified provider: + + * Copies all files inside `PLATFORM/` dir except `.vagrant` and `base-box` to + `release-test/`. This is done to avoid reusing any VM the developer may have + started; + + * Executes `$ vagrant up [--provider=PROVIDER]`; + + * Finds an attached USB device matching the VID and PID specified in + `test-config.json`, and if `--test-device-serial` was given, that serial + number (as reported to USB). Creates a rule to autoconnect this device to the + VM, and also attaches it to the VM; + + * SSHs to the VM, `cd` to the TVM root directory, and runs `test_cmd` from + `test-config.json`. Nonzero status means failure. + +3. If release tests _fail_, fix them and restart from step 1. + +4. If release tests pass, **release** the box: +```bash +$ ./base-box-tool.py [--provider=PROVIDER] release --release-version=RELEASE_VER --platform-version=PLATFORM_VER PLATFORM +``` + For that step be sure you've logged in to Vagrant Cloud using the `vagrant` + tool.