[microTVM][RVM] Fix base-box-tool command in README.md (apache#8613)

This commit fixes the platform argument order for base-box-tool.py
'test' command in the documentation about the RVM. Currently the example
in documentation places <platform> before option
[--test-device-serial=<serial>], whilst the correct order is after all
the options, so trying to use the 'test' command arguments in the order
as suggested by the documentation will not work.

This commit also fixes a typo (inovke -> invoke).

Finally it tweaks a bit the text format: lines with maximum 80 columns,
a better diagram format for the dir structure, and a better format for
the bash commands. A link is added too for easy access to the
"microTVM Reference VM tutorial" found in tutorials/micro directory. A
couple of command examples were also added to the documentation.

Signed-off-by: Gustavo Romero <gustavo.romero@linaro.org>

apps/microtvm/reference-vm/README.md

@@ -15,53 +15,100 @@
 <!--- specific language governing permissions and limitations -->
 <!--- under the License. -->
 
-# 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
-* `<platform>/`
-** `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=<provider>] build <platform>`
-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=<provider>] test [--microtvm-platform=<platform>] <platform> [--test-device-serial=<serial>]`. This
-       command does the following for each provider:
-        1. Copies all files inside `./<platform>` 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=<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=<provider>] release <--release-version=<version>> <--platform-version=<version>> <platform>`. 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.