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.
Microvisor system calls currently include the following functions for device-oriented operations:
All of the functions described below return a 32-bit integer that is one of the values from the standard Microvisor enumeration MvStatus. All possible error values for a given system call are provided with each function's description.
Success is always signaled by a return value of zero (MV_STATUS_OKAY).
Get the device's unique SID
1extern enum MvStatus mvGetDeviceId(uint8_t *buffer,2uint32_t length);
| Parameter | Description |
|---|---|
buffer | A pointer to non-secure memory into which the device ID will be written by Microvisor |
length | The size of the buffer in bytes. Must be 34 |
| Error Value | Description |
|---|---|
MV_STATUS_PARAMETERFAULT | buffer does not reference memory accessible to the application |
MV_STATUS_INVALIDBUFFERSIZE | length is not the correct size for result, i.e., 34 bytes |
Every Microvisor-enabled device has associated with it a unique 34-character identifier called an SID. This is set during the production of the microcontroller containing Microvisor. Use this function to read the SID, which can then be used to identify the device in your interactions with the Microvisor cloud. You may also use it for device identification purposes within your own cloud and mobile apps.
Although the SID is output as Ascii text, it is not a C string. To use the SID characters with C string-manipulation functions, and printf(), ensure your buffer is 35 characters long and terminated with a nul ('\0').
1uint8_t buffer[35] = { 0 };2mvGetDeviceId(buffer, 34);3printf("Device ID: %s\n", buffer);
Restart the application and/or the device
extern enum MvStatus mvRestart(enum MvRestartMode mode);
| Parameter | Description |
|---|---|
mode | The level of restart to perform |
| Error Value | Description |
|---|---|
MV_STATUS_UNAVAILABLE | The call has been made from within an interrupt service routine (ISR) |
MV_STATUS_PARAMETERFAULT | An unknown mode value was provided |
MV_STATUS_MICROVISORBUSY | The restart cannot be performed because it will interrupt Microvisor's operation |
This call is typically made as part of an application's support for polite deployment: the means by which it manages staged application and/or Microvisor updates at moments when the system restart the installation of these updates require would interrupt critical tasks being performed by the application. When polite deployment is enabled and the application is notified that an update has been downloaded and staged, it can defer installation if it needs to. When the application knows it is safe to proceed with installation, it calls MvRestart() to begin the installation process.
Currently, only one value of the mode parameter is available: MV_RESTARTMODE_AUTOAPPLYUPDATE. This will cause any update, whether of the application, Microvisor, or both, to be applied immediately via a reset. As such, the call will return only in the case of an error.
mvRestart() may not be called from within in interrupt service routine.
For further guidance, please see the Microvisor polite deployment documentation.
Get the current frequency of the CPU clock
extern enum MvStatus mvGetSysClk(uint32_t *frequency);
| Parameter | Description |
|---|---|
frequency | A pointer to non-secure memory into which the frequency will be written by Microvisor |
| Error Value | Description |
|---|---|
MV_STATUS_PARAMETERFAULT | frequency does not reference memory accessible to the application |
Get the current frequency of the microcontroller's Advanced High-performance Bus (AHB)
extern enum MvStatus mvGetHClk(uint32_t *frequency);
| Parameter | Description |
|---|---|
frequency | A pointer to non-secure memory into which the frequency will be written by Microvisor |
| Error Value | Description |
|---|---|
MV_STATUS_PARAMETERFAULT | frequency does not reference memory accessible to the application |
Get the current frequency of the microcontroller's Advanced Peripheral Bus (APB1)
extern enum MvStatus mvGetPClk1(uint32_t *frequency);
| Parameter | Description |
|---|---|
frequency | A pointer to non-secure memory into which the frequency will be written by Microvisor |
| Error Value | Description |
|---|---|
MV_STATUS_PARAMETERFAULT | frequency does not reference memory accessible to the application |
Get the current frequency of the microcontroller's Advanced Peripheral Bus (APB2)
extern enum MvStatus mvGetPClk2(uint32_t *frequency);
| Parameter | Description |
|---|---|
frequency | A pointer to non-secure memory into which the frequency will be written by Microvisor |
| Error Value | Description |
|---|---|
MV_STATUS_PARAMETERFAULT | frequency does not reference memory accessible to the application |
Microvisor includes a set of functions which provide application code with access to the contents of host microcontroller peripheral registers that are claimed by Microvisor. An example is reading the Reset and Clock Controller (RCC) configuration: this is needed by the application to determine the underlying clock speeds and so configure a peripheral, but RCC owned by Microvisor so that it can control key clocks.
Non-secure code, i.e., the application, can't directly read or write these registers, at least not in a way that yields unambiguous values. TrustZone ensures writes from non-secure code are always ignored and reads return zero, but does not inform the application that it has done so. Microvisor therefore provides mediated read and write access to these secure registers.
Attempts to access peripheral registers outside of these system calls are trapped by Microvisor, which treats them as illegal accesses and restarts the application. This is done to alert the developer, who can then modify their code to prevent the illegal access.
Microvisor maintains a list of registers that the application is able to access through these system calls. These are provided as non-secure mappings; Microvisor translates the value to a secure mapping. If the call does not provide access to a given register, the call returns an error value.
For each valid register, Microvisor also maintains masks of the bits that are readable and the bits that are writable by the application. Bits the application is not permitted to access are unset in reads and unchanged by writes.
These system calls can be used for any register, including those that the application has non-secure access to. If the supplied address references a register that is implicitly accessible to the application, then Microvisor makes the access directly on the non-secure mapping. This is as if the application made the access itself. A consequence of this is that you can use these calls in your cade consistently across all register access operations.
Read the contents of a device peripheral register
1extern enum MvStatus mvPeriphPeek32(uint32_t *register,2uint32_t *register_value;
| Parameter | Description |
|---|---|
register | The non-secure address of the register being accessed |
register_value | A pointer to non-secure memory into which the register's contents will be written by Microvisor |
| Error Value | Description |
|---|---|
MV_STATUS_PERIPHERALACCESSFAULT | register addresses an unsupported register, or is not word-aligned |
MV_STATUS_PARAMETERFAULT | register_value does not reference memory accessible to the application |
This call reads the contents of one of the microcontroller's peripheral registers and writes the result to non-secure memory.
1int64_t readRegisterOrNegOnError(uint32_t reg) {2uint32_t tmp = 0;3extern enum MvStatus status = mvPeriphPeek32(reg, &tmp);4return (status == MV_STATUS_OKAY ? (int64_t)tmp : -1);5}
Write data to a device peripheral register
1extern enum MvStatus mvPeriphPoke32(uint32_t *register,2uint32_t mask,3uint32_t xor_value);
| Parameter | Description |
|---|---|
reg | The non-secure address of the register being accessed |
mask | A mask to indicate the bits that will be affected by the write |
xor_value | A value to Exclusive OR with the register's current contents |
| Error Value | Description |
|---|---|
MV_STATUS_PERIPHERALCCESSFAULT | register addresses an unsupported register, or is not word-aligned |
Use this function to update the value held by a microcontroller peripheral register. The call can be used for a variety of different operations, from writing specific values to the register, to performing bit-level changes. The function applies the following logic to the value of the chosen register:
*register = (*register & ~mask) ^ xor_value
and with appropriate mask and XOR values, these operations are possible:
| Operation | Mask Value | XOR value |
|---|---|---|
| Clear bits | Bits to clear | 0x00000000 |
| Set bits | Bits to set | Bits to set |
| Toggle bits | 0x00000000 | Bits to toggle |
| Change the whole register | 0xFFFFFFFF | New value |