Notification Functions

Danger

This is historical documentation, and tooling and console operations are no longer available.

Microvisor system calls include the following functions to manage notifications:

mvSetupNotifications()
mvCloseNotifications()
mvOpenSystemNotification()
mvCloseSystemNotification()

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

mvSetupNotifications()

Instantiate a notification dispatch center

Declaration

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

Parameters

Parameter	Description
`setup`	A pointer to non-secure memory in which notification setup data is stored by the application
`handle`	A pointer to non-secure memory into which the notification center handle will be written by Microvisor

Possible Errors

Error Value	Description
`MV_STATUS_PARAMETERFAULT`	`setup` or `handle` does not reference memory accessible to the application
`MV_STATUS_TOOMANYNOTIFICATIONBUFFERS`	Microvisor cannot create the necessary notification center because the maximum number of centers has already been reached
`MV_STATUS_INVALIDBUFFERSIZE`	The buffer size specified in `setup` is not a multiple of 16 bytes, or at least 32 bytes in size
`MV_STATUS_BUFFERALREADYINUSE`	The specified buffer is already being used by another notification center
`MV_STATUS_INVALIDINTERRUPT`	The IRQ specified in `setup` (see below) is not available to the application

Description

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

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

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

// Central store for Microvisor resource handles used in this code.
struct {
    MvNotificationHandle notification;
    MvNetworkHandle      network;
    MvChannelHandle      channel;
} http_handles = { 0, 0, 0 };

// Store for HTTP notification records.
// Holds four records at a time -- each record is 16 bytes.
volatile struct MvNotification http_notification_center[4] __attribute__((aligned(8)));

// Clear the notification store
memset((void *)http_notification_center, 0xFF, sizeof(http_notification_center));

// Configure a notification center for network-centric notifications
static struct MvNotificationSetup http_notification_setup = {
    .irq = TIM8_BRK_IRQn,
    .buffer = (struct MvNotification *)http_notification_center,
    .buffer_size = sizeof(http_notification_center)
};

// Ask Microvisor to establish the notification center
// and confirm that it has accepted the request
enum MvStatus status = mvSetupNotifications(&http_notification_setup, &http_handles.notification);
assert((status == MV_STATUS_OKAY) && "[ERROR] Could not set up HTTP channel NC");

// Start the notification IRQ
NVIC_ClearPendingIRQ(TIM8_BRK_IRQn);
NVIC_EnableIRQ(TIM8_BRK_IRQn);
printf("[DEBUG] Notification center handle: %lu\n", (uint32_t)http_handles.notification);

Note

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

mvCloseNotifications()

Halt the dispatch of messages from a notification center

Declaration

extern enum MvStatus mvCloseNotifications(MvNotificationHandle *handle);

Parameters

Parameter	Description
`handle`	A pointer to non-secure memory in which the notification center handle is stored by the application

Possible Errors

Error Value	Description
`MV_STATUS_PARAMETERFAULT`	`handle` does not reference memory accessible to the application
`MV_STATUS_INVALIDHANDLE`	`handle` 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.

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

mvOpenSystemNotification()

Start the dispatch of system messages to a notification center

Declaration

extern enum MvStatus mvOpenSystemNotification(const struct MvOpenSystemNotificationParams *params,
                                              MvSystemEventHandle *handle);

Parameters

Parameter	Description
`params`	A pointer to non-secure memory in which the notification parameters are stored by the application
`handle`	A pointer to non-secure memory in which the handle of the system event sender is stored by the application

Possible Errors

Error Value	Description
`MV_STATUS_PARAMETERFAULT`	`params` or `handle` does not reference memory accessible to the application
`MV_STATUS_UNAVAILABLE`	The system call has been made from an interrupt service routine
`MV_STATUS_INVALIDHANDLE`	`handle` is invalid or identifies some other type of handle

Description

To begin receiving system notifications, call mvOpenSystemNotification() and pass in a pointer to the memory in which the system notification configuration is stored, and where a system event sender’s handle will be stored.

The params parameter takes a pointer to a MvOpenSystemNotificationParams structure:

struct MvOpenSystemNotificationParams {
    MvNotificationHandle notification_handle;
    uint32_t notification_tag;
    enum MvSystemNotificationSource notification_source;
}

These properties are:

notification_handle — The handle that will be issued for the notification center messages.
notification_tag — An arbitrary 32-bit value you can specify and which will then be included in all notifications relating to this center.
notification_source — One or more MvSystemNotificationSource values OR’d to indicate the type(s) of notifications to be issued. See below.

Available MvSystemNotificationSource values include:

enum MvSystemNotificationSource {
    MV_SYSTEMNOTIFICATIONSOURCE_NETWORK,
    MV_SYSTEMNOTIFICATIONSOURCE_UPDATE
};

Use MV_SYSTEMNOTIFICATIONSOURCE_UPDATE to receive polite deployment notifications.

mvCloseSystemNotification()

Halt the dispatch of system messages to a notification center

Declaration

extern enum MvStatus mvCloseSystemNotification(MvSystemEventHandle *handle);

Parameters

Parameter	Description
`handle`	A pointer to non-secure memory in which the handle of a system event sender is stored by the application

Possible Errors

Error Value	Description
`MV_STATUS_UNAVAILABLE`	The system call has been made from an interrupt service routine
`MV_STATUS_INVALIDHANDLE`	`handle` is invalid or identifies some other type of handle

Description

To stop receiving system notifications, call mvCloseSystemNotification() and pass in the handle of the system event sender that was provided when you called mvOpenSystemNotification().

This call does not tear down the notification center to which system notifications are being sent.