Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

How to Install the Microvisor SDK


(warning)

Warning

Microvisor Public Beta

Microvisor is in a pre-release phase and the information contained in this document is subject to change. Some features referenced below may not be fully available until Microvisor's General Availability (GA) release.

To begin developing applications for Microvisor, you first need to prepare your development environment. This guide will show you how to do so: you will install the Microvisor SDK and essential third-party components. When you're done, you'll be ready to begin work on your own Microvisor-hosted application, perhaps using our FreeRTOS demo code as a basis.

This guide is primarily aimed at developers who are new to embedded projects. Developers with extensive embedded development experience, or who have use-cases that require very specific project configurations — for example to support testing — may choose to use the guide solely as a list of prerequisites.

If you are an experienced STM32 developer, please be aware that Microvisor requires dedicated versions of some of the tools that you will be familiar with and may be expecting to use for Microvisor work, such as the STM32Cube U5 HAL. Please read this guide thoroughly to understand which of these Microvisor-specific versions you may need, and why.


Platform support

platform-support page anchor

At this stage in Microvisor's release schedule, we support Ubuntu 20.04 LTS(link takes you to an external page) 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 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:

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.

The NSC system calls

the-nsc-system-calls page anchor

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.

(information)

Info

You can learn more about the peripherals mediated by Microvisor in Develop Applications for Microvisor.

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(link takes you to an external page), 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.

(error)

Danger

To work with a HAL in your code, you must use the Microvisor STM32U585 HAL. STM's generic STM32CubeU5 HAL will not work with Microvisor.

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 intention is to make it as easy as possible to port a "bare metal" implementation to Microvisor.

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(link takes you to an external page). We have provided a demo application that you can build and run on the upcoming Microvisor Nucleo Dev Board, or simply use as the basis for your own FreeRTOS-based IoT application.

The ARM CMSIS-RTOS API(link takes you to an external page) is used an 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.


Install the prerequisites

install-the-prerequisites page anchor

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


_10
sudo apt install gcc-arm-none-eabi \
_10
binutils-arm-none-eabi \
_10
git cmake curl \
_10
build-essential

Install Docker Desktop(link takes you to an external page) or the Docker Engine(link takes you to an external page) 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.

Option 1: Install the FreeRTOS demo

option-1-install-the-freertos-demo page anchor

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:


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

If you are installing under Ubuntu, run:


  1. _10
    cd Microvisor-Demo-CMSIS-Freertos


  2. _10
    cmake -S . -B build


  3. _10
    cmake --build build --clean-first

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


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


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

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

(information)

Info

Like to be informed about new FreeRTOS demo releases, or updates to any of the other repos described here? Go to your chosen repo's homepage — for example, https://github.com/korewireless/Microvisor-Demo-CMSIS-Freertos.git(link takes you to an external page) — select Watch > Custom and then check Releases . You'll receive an email notification whenever a new version of the the repo is released.

Option 2: Install the Microvisor STM32U585 HAL

option-2-install-the-microvisor-stm32u585-hal page anchor

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:


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

If you are installing under Ubuntu, run:


  1. _10
    cd Microvisor-HAL-STM32U5


  2. _10
    cmake -S . -B build


  3. _10
    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. _10
    docker build --build-arg UID=$(id -u) --build-arg \
    _10
    GID=$(id -g) -t microvisor-hal-stm32u5-image .


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

(information)

Info

The file mv_prescalers.c is not required if you already have a target in your project that defines the relevant prescaler values.

Option 3: Install the NSC system calls components

option-3-install-the-nsc-system-calls-components page anchor

Run the following command:


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

Using the NSC system calls components

using-the-nsc-system-calls-components page anchor

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.

Install the development tools

install-the-development-tools page anchor

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:


_10
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:


_10
git init
_10
git submodule add https://github.com/FreeRTOS/FreeRTOS-Kernel
_10
git submodule add https://github.com/korewireless/Microvisor-HAL-STM32U5
_10
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:


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

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


_10
ST_Code/CMSIS_RTOS_V2/cmsis_os2.c
_10
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.

(information)

Info

Microvisor Help and Support

We welcome all inquiries you may have about Microvisor and its implementation, and any support questions that arise once you've begun developing with Microvisor. Please submit your queries via a KORE Wireless ticket: log in to the Kore console(link takes you to an external page) and click the Contact Support button in the left-hand navbar.


Rate this page: