How to Install the Microvisor SDK

At this stage in Microvisor's release schedule, we support Ubuntu 20.04 LTS Linux as a primary development environment. While we hope to support other platforms in due course, for now Mac and Windows users will have to choose between interacting with the Microvisor development tools through Docker or from within a virtual machine running Ubuntu. Instructions for both approaches are included below.

The following instructions assume you have a fresh Ubuntu 20.04 Desktop installation.

This section introduces the SDK and its components. If you just want to crack on with installation, just jump down the page.

The Microvisor SDK comprises the following elements:

• A header file declaring Microvisor's non-secure callable (NSC) system calls and related data structures.
• An object file which contains the entry points for Microvisor's NSC functions.
• A linker script which maps the memory to which user applications have access.

The following components are optional and build on the SDK:

• A Microvisor-specific STM32U585 Hardware Abstraction Layer (HAL) which provides generic access to the STM32U585-specific peripherals in a way that is compatible with Microvisor.
• A FreeRTOS demo application.
• Additional development tools.

All of these components are provided through a series of public git repositories. Dependencies are included as submodules.

To support the SDK, a small number of third-party pre-requisites are required too.

While a number of applications, particularly legacy ones, can run alongside Microvisor without being aware of its presence, to make the most of the functionality Microvisor provides, applications will need to interact with Microvisor using system calls.

Applications which make system calls will need to include the header file, mv_syscalls.h, and incorporate the object file mv_implib.o into their build process. Both files are part of the SDK.

Whether the application makes use of the Microvisor system calls or not, it will need to be built with the Microvisor SDK linker script, STM32U585xx_FLASH_mv.ld, which makes sure that the application is primed to use the STM32U585 microcontroller's TrustZone-enabled non-secure SRAM and Flash allocated to you by Microvisor within the STM32U585.

Our recommended build management tool is CMake, and the linker script is accompanied by a CMakeLists.txt file which exports a library and linker flags to use in your application.

The optional Microvisor STM32U585 HAL library provides a set of convenience functions which your code can use to simplify its usage of the STM32U585's peripherals. Most embedded developers should start off with the HAL unless they have very specific and very low-level peripheral-access requirements.

Microvisor does not allow non-secure code to access to the RCC peripheral or secure registers directly. This conflicts with a number of STM32CubeU5 HAL functions, so the Microvisor port modifies the bodies of these functions to safely intercept disallowed accesses and perform the target action in a permitted way.

This ensures that commonly called standard library functions, such as __HAL_RCC_GPIOA_CLK_ENABLE() and LL_RCC_WriteReg(), can be used without modification, and that your existing application code can largely operate as if Microvisor is not present.

The HAL also includes a header file, mv_bitops.h, which provides a comprehensive set of generically named macros for performing register operations — reading and writing registers; setting and clearing individual register bits, etc. These match equivalent STM32 HAL bit operation macros, so use of the latter can be converted to Microvisor versions just by adding the prefix MV_, e.g., SET_BIT() becomes MV_SET_BIT().

Many embedded developers choose to build their IoT applications on top of a Real-time Operating System (RTOS) so that they can take advantage of the advanced services and functionality offered by the OS, such as multi-threading and scheduling. A popular RTOS for embedded products is FreeRTOS. We have provided a demo application that you can build and run on the upcoming Microvisor Nucleo Dev Board, or use as the basis for your own FreeRTOS-based IoT application.

The ARM CMSIS-RTOS API is used an intermediary between the application and FreeRTOS to make it easier to swap out the RTOS layer for another should you need to do so.

Microvisor's development tools are used after you have generated an application build. They include tools that you use to package the built application and configuration information into a file ready for uploading to the Microvisor cloud — and from there to be deployed to your devices. They also include a GDB server that will connect the standard gdb debugger to the Microvisor cloud to enable remote debugging.

You use Twilio's standard CLI tool and its Microvisor Plugin to perform these tasks.

If you are installing under Ubuntu, please install the following components:

1
sudo apt install gcc-arm-none-eabi \
2
                 binutils-arm-none-eabi \
3
                 git cmake curl \
4
                 build-essential

Install Docker Desktop or the Docker Engine if you plan to install the FreeRTOS demo or the HAL on Mac or Windows via Docker.

You have three choices:

• If you intend to work with an RTOS, such as FreeRTOS, you should install the demo application, which includes all the other SDK components, including the Microvisor STM32U585 HAL. Once you have built and run the demo code, you can use it as a foundation for your own application.
• If you do not intend to work with an RTOS, install the Microvisor STM32U585 HAL, which includes all the required SDK components. You can then begin building your own application.
• Install the standalone SDK. This is an advanced, manual install option provided only for developers with specific project configuration needs and/or experience of working with Microvisor. If you do plan to install a HAL too, please use option 2 as STM's generic U5 Cube HAL will not work with Microvisor.

The FreeRTOS demo is recommended as a starting point for any Microvisor-hosted application that will run under this popular RTOS. The code is provided as a standalone project: it includes the Microvisor SDK and STM32U585 HAL as git submodules.

Run the following commands. You can copy each one by clicking the copy button that appears when you mouse over each command:

git clone --recurse-submodules https://github.com/korewireless/Microvisor-Demo-CMSIS-Freertos.git

If you are installing under Ubuntu, run:

1. Copy code block

   cd Microvisor-Demo-CMSIS-Freertos

2. Copy code block

   cmake -S . -B build

3. Copy code block

   cmake --build build --clean-first

Alternatively, if you wish to build the demo using Docker, run the following commands:

1. Copy code block

   1
   docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) \
   2
     -t microvisor-gpio-sample-image .

2. Copy code block

   1
   docker run -it --rm -v $(pwd)/:/home/ --name microvisor-gpio-sample \
   2
     microvisor-gpio-sample-image

The deliverable you can provision onto Microvisor will be built into build/Demo/gpio_toggle_demo.elf.

Using the Microvisor-specific STM32U585 HAL in your application is optional, but we recommend it for all developers who are not planning to make use of FreeRTOS.

Run the following commands. You can copy each one by clicking the copy button that appears when you mouse over each command:

git clone --recurse-submodules https://github.com/korewireless/Microvisor-HAL-STM32U5.git

If you are installing under Ubuntu, run:

1. Copy code block

   cd Microvisor-HAL-STM32U5

2. Copy code block

   cmake -S . -B build

3. Copy code block

   cmake --build build --clean-first

The library will be built into build/libmicrovisor-hal-stm32u5.a.

The included CMakeFiles.txt is a "kitchen sink" inclusion of the HAL. You may choose to restrict the included files from the HAL to just those your project may need. An example of this approach can be found in our FreeRTOS demo. You can then link your code against the Microvisor port of the Standard Peripheral Library.

Alternatively, you can import the entire repository instead of importing the Standard Peripheral Library.

If you wish to build the HAL library using Docker, run the following commands:

1. Copy code block

   1
   docker build --build-arg UID=$(id -u) --build-arg \
   2
     GID=$(id -g) -t microvisor-hal-stm32u5-image .

2. Copy code block

   1
   docker run -it --rm -v $(pwd)/:/home/ --name microvisor-hal-stm32u5-lib \
   2
     microvisor-hal-stm32u5-image
   3
   

Run the following command:

https://github.com/korewireless/Microvisor-SDK.git

With the repo downloaded, you can choose the best way to consume its contents within your project:

1. Use CMake to reference the directory within your own CMake-based project's CMakeLists.txt file by including the command add_subdirectory(<PATH_TO_MICROVISOR_SDK>). You must also specify the environment variable $MV_ARCH. At this time, it must be set to "stm32u5".
2. #include the mv_syscalls.h header file in your application and link against stm32u5/mv_implib.o. Add stm32u5/STM32U585xx_FLASH_mv.ld to the linker flags in your project.

You will need to install the Twilio CLI and its Microvisor plugin. You can find instructions and guidance here.

If you prefer to start projects from scratch, you can assemble them by installing key components as git submodules and copying some dependencies from the FreeRTOS demo repo. We hope shortly to offer these by way of git templates.

To keep project dependencies up to date, run:

git submodule update --remote --recursive

To build a FreeRTOS project, create a directory and cd into it. Copy the ST_Code and config directories, and the CMakeLists.txt and toolchain.cmake files from the root of the FreeRTOS demo repo, and then run the following commands:

1
git init
2
git submodule add https://github.com/FreeRTOS/FreeRTOS-Kernel
3
git submodule add https://github.com/korewireless/Microvisor-HAL-STM32U5
4
git submodule update --init --recursive

Edit CMakeLists.txt to suit your project, specifying your source code directory (which will contain its own CMakeLists.txt file).

The sample code Basic HTTP Communications is a complete example of such a DIY project.

To set up a fresh project that does not use FreeRTOS or another RTOS, create a directory and cd into it. Copy the ST_Code directory and the toolchain.cmake and CMakeLists.txt files from the FreeRTOS demo clone, and then run the following commands:

1
git init
2
git submodule add https://github.com/korewireless/Microvisor-HAL-STM32U5
3
git submodule update --init --recursive

Edit CMakeLists.txt to suit your project, and to remove the lines

1
ST_Code/CMSIS_RTOS_V2/cmsis_os2.c
2
ST_Code/CMSIS_RTOS_V2

and all FreeRTOS references. You can also delete both CMSIS_ directories from the ST_Code directory.

The sample code Remote Debugging Demo is a complete example of such a DIY project.