Device Functions

Microvisor system calls currently include the following functions for device-oriented operations:

Device information functions

• mvGetDeviceId()

Device clock functions

• mvGetSysClk()
• mvGetHClk()
• mvGetPClk1()
• mvGetPClk2()

Peripheral-register access functions

• mvPeriphPeek32()
• mvPeriphPoke32()

Return values and errors

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).

mvGetDeviceId()

Get the device’s unique SID

Declaration

extern enum MvStatus mvGetDeviceId(uint8_t *buffer, 
                                   uint32_t length);

Parameters

Possible errors

Description

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 Twilio. 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').

Example

uint8_t buffer[35] = { 0 };
mvGetDeviceId(buffer, 34);
printf("Device ID: %s\n", buffer);

mvGetSysClk()

Get the current frequency of the CPU clock

Declaration

extern enum MvStatus mvGetSysClk(uint32_t *frequency);

Parameters

Possible errors

mvGetHClk()

Get the current frequency of the microcontroller’s Advanced High-performance Bus (AHB)

Declaration

extern enum MvStatus mvGetHClk(uint32_t *frequency);

Parameters

Possible errors

mvGetPClk1()

Get the current frequency of the microcontroller’s Advanced Peripheral Bus (APB1)

Declaration

extern enum MvStatus mvGetPClk1(uint32_t *frequency);

Parameters

Possible errors

mvGetPClk2()

Get the current frequency of the microcontroller’s Advanced Peripheral Bus (APB2)

Declaration

extern enum MvStatus mvGetPClk2(uint32_t *frequency);

Parameters

Possible errors

Register access functions

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.

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.

mvPeriphPeek32()

Read the contents of a device peripheral register

Declaration

extern enum MvStatus mvPeriphPeek32(uint32_t *register, 
                                    uint32_t *register_value;

Parameters

Possible errors

Description

This call reads the contents of one of the microcontroller’s peripheral registers and writes the result to non-secure memory.

Example

int64_t readRegisterOrNegOnError(uint32_t reg) {
  uint32_t tmp = 0;
  extern enum MvStatus status = mvPeriphPeek32(reg, &tmp);
  return (status == MV_STATUS_OKAY ? (int64_t)tmp : -1);
}

mvPeriphPoke32()

Write data to a device peripheral register

Declaration

extern enum MvStatus mvPeriphPoke32(uint32_t *register, 
                                    uint32_t mask,
                                    uint32_t xor_value);

Parameters

Possible errors

Description

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: