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

Notification Functions


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

Microvisor system calls include the following functions to manage notifications:


Return values and errors

return-values-and-errors page anchor

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


mvSetupNotifications()

mvsetupnotifications page anchor

Instantiate a notification dispatch center

Declaration


_10
extern enum MvStatus mvSetupNotifications(const struct MvNotificationSetup *setup,
_10
MvNotificationHandle *handle);

Parameters

ParameterDescription
setupA pointer to non-secure memory in which notification setup data is stored by the application
handleA pointer to non-secure memory into which the notification center handle will be written by Microvisor

Possible errors

Error ValueDescription
MV_STATUS_PARAMETERFAULTparams or handle does not reference memory accessible to the application
MV_STATUS_TOOMANYNOTIFICATIONBUFFERSMicrovisor cannot create the necessary notification center because the maximum has already been reached
MV_STATUS_INVALIDBUFFERSIZEThe buffer size specified in setup is not a multiple of 16 bytes, or at least 32 bytes in size
MV_STATUS_BUFFERALREADYINUSEThe specified buffer is already being used by another notification center
MV_STATUS_INVALIDINTERRUPTThe IRQ specified in setup (see below) is not available to the application

Description

You configure the notification center by providing a pointer to a NotificationSetup structure:


_10
struct MvNotificationSetup {
_10
uint32_t irq;
_10
struct MvNotification *buffer;
_10
uint32_t buffer_size;
_10
}

These properties are:

  • irq — The number of the non-secure interrupt line that will be triggered to signal that a new notification has been posted. The call to mvSetupNotifications() will return an error if this value indicates a secure interrupt, or has already been assigned to a notification center.
  • buffer — A pointer to a previously allocated buffer. It must be 8-byte aligned.
  • buffer_size — The size of the center's buffer in bytes. It must be at least 32 bytes and a multiple of 16 bytes.

Example


_30
// Central store for Microvisor resource handles used in this code.
_30
struct {
_30
MvNotificationHandle notification;
_30
MvNetworkHandle network;
_30
MvChannelHandle channel;
_30
} http_handles = { 0, 0, 0 };
_30
_30
// Store for HTTP notification records.
_30
// Holds four records at a time -- each record is 16 bytes.
_30
volatile struct MvNotification http_notification_center[4] __attribute__((aligned(8)));
_30
_30
// Clear the notification store
_30
memset((void *)http_notification_center, 0xFF, sizeof(http_notification_center));
_30
_30
// Configure a notification center for network-centric notifications
_30
static struct MvNotificationSetup http_notification_setup = {
_30
.irq = TIM8_BRK_IRQn,
_30
.buffer = (struct MvNotification *)http_notification_center,
_30
.buffer_size = sizeof(http_notification_center)
_30
};
_30
_30
// Ask Microvisor to establish the notification center
_30
// and confirm that it has accepted the request
_30
enum MvStatus status = mvSetupNotifications(&http_notification_setup, &http_handles.notification);
_30
assert((status == MV_STATUS_OKAY) && "[ERROR] Could not set up HTTP channel NC");
_30
_30
// Start the notification IRQ
_30
NVIC_ClearPendingIRQ(TIM8_BRK_IRQn);
_30
NVIC_EnableIRQ(TIM8_BRK_IRQn);
_30
printf("[DEBUG] Notification center handle: %lu\n", (uint32_t)http_handles.notification);

(information)

Info

For more details on Microvisor's notifications mechanism, please see Microvisor Notifications.


mvCloseNotifications()

mvclosenotifications page anchor

Halt the dispatch of messages from a notification center

Declaration


_10
extern enum MvStatus mvCloseNotifications(MvNotificationHandle *handle);

Parameters

ParameterDescription
handleA pointer to non-secure memory in which the notification center handle is stored by the application

Possible errors

Error ValueDescription
MV_STATUS_PARAMETERFAULThandle does not reference memory accessible to the application
MV_STATUS_INVALIDHANDLEhandle is invalid or identifies some other type of handle

Description

To stop receiving notifications from a specific notification center, call mvCloseNotifications() and pass in a pointer to the memory in which the center's handle is stored.

If the center is in use by other objects — for example, the same center is dispatching notifications from a network and a channel — calling mvCloseNotifications() will stop the delivery of notifications from all of its sources, and no error will be issued.

The center's non-secure interrupt will not be pended by Microvisor when the center is closed. If the interrupt has already been pended, it will not be cleared. This is the job of the application.

Example

This example uses variables defined in the example above.


_10
// If we have a valid notification center handle, then ask Microvisor
_10
// to tear down the center and confirm acceptance of the request.
_10
if (http_handles.notification != 0) {
_10
status = mvCloseNotifications(&http_handles.notification);
_10
assert((status == MV_STATUS_OKAY) && "[ERROR] Could not close HTTP channel NC");
_10
}


Rate this page: