Network Functions

• mvRequestNetwork()
• mvGetNetworkStatus()
• mvReleaseNetwork()
• mvGetNetworkReasons()

• mvOpenChannel()
• mvCloseChannel()
• mvGetChannelClosureReason()

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

Ask Microvisor to establish a primary network connection

This call, if successful, may subsequently yield any of the following notifications.

An application can call this function at any time to request that Microvisor establishes a connection to the Internet. Once the connection is in place, the application can use the returned network handle to establish data channels for the transfer of information.

Microvisor will maintain no more than 128 concurrent network handles, and will return an error if you request a further handle without first calling mvReleaseNetwork() for an existing network handles.

The params parameter takes a pointer to a MvRequestNetworkParams structure:

1
struct MvRequestNetworkParams {
2
  uint32_t version;
3
  union {
4
    struct {
5
      MvNotificationHandle notification_handle;
6
      uint32_t notification_tag;
7
    } v1;
8
  };
9
};

These properties are:

• version — The system calls version. This should always be 1.
• notification_handle — The handle of the notification center you wish to dispatch notifications relating to the connection. The notification center must already have been instantiated. For more information, please see the Microvisor system calls overview and notification functions.
• notification_tag — An arbitrary 32-bit value you can specify and which will then be included in all notifications relating to this connection. For more information, please see the Microvisor System Calls overview.

Please see A Guide to Microvisor Networking for code samples.

Request the state of a specific network connection

Call this function to get an indication of the network connection's current state. The value written to the memory referenced by status will be one of the following:

Please see A Guide to Microvisor Networking for code samples.

Relinquish access to a specified network connection

An application can call this function at any time to relinquish access to a network connection that Microvisor has established for it. If the request is successful — the call does not return an error — then the network handle will be invalidated: Microvisor will zero the non-secure bytes in which the handle is stored. The network connection will be closed, i.e., the device disconnected, provided there are no other valid network handles in place and the connection is not in use by Microvisor.

Please see A Guide to Microvisor Networking for code samples.

Request information on the state of the Microvisor's network management system

Call this function to receive a snapshot of the state of Microvisor's networking subsystem rather than that of a specific network connection (cf. mvGetNetworkStatus()). For instance, you can call mvGetNetworkReasons() at any time and even if the application has not yet initiated a connection by calling mvRequestNetwork().

The value written to the memory referenced by reasons will be a bitfield comprising any or all of the following flags:

The value written to current_handle_count will be the number of network handles Microvisor is currently maintaining, ie., from 0 to 128 inclusive.

Please see A Guide to Microvisor Networking for code samples.

Ask Microvisor to open a data transfer channel

This call, if successful, may subsequently yield any of the following notifications.

The application makes use of channels to transfer data over a network connection established by Microvisor. Think of the network as the transport layer and a channel as a data-exchange protocol operating via that transport. The network must be connected for the channel to be opened. Up to four channels can be opened at any one time on a given network connection.

Channels are bi-directional and maintain flow control: if you don't read incoming data, the receive buffer will fill, and no more incoming data will be accepted until space is made for it.

The channel will be available to write to and read from as soon as mvOpenChannel() returns no error, but that doesn't mean that the target is ready or has accepted the channel — your code will need to ensure it can communicate before attempting to do so.

You configure the channel by providing a pointer to a MvOpenChannelParams structure:

1
struct MvOpenChannelParams {
2
  uint32_t version;
3
  union {
4
    struct {
5
      MvNotificationHandle notification_handle;
6
      uint32_t notification_tag;
7
      MvNetworkHandle network_handle;
8
      uint8_t *receive_buffer;
9
      uint32_t receive_buffer_len;
10
      uint8_t *send_buffer;
11
      uint32_t send_buffer_len;
12
      enum MvChannelType channel_type;
13
      struct MvSizedString endpoint;
14
    } v1;
15
  };
16
};

These properties are:

• version — The system calls version. This should always be 1.
• notification_handle — The handle of the notification center you wish to dispatch notifications relating to the channel. The notification center must already have been instantiated. For more information, please see the Microvisor system calls overview
• notification_tag — An arbitrary 32-bit value you can specify and which will then be included with all notifications relating to this channel. For more information, please see the Microvisor system calls overview.
• network_handle — A pointer to non-secure memory in which the host network's handle is stored by the application.
• receive_buffer, send_buffer — Pointers to RX and TX buffers — see below.
• receive_buffer_len, send_buffer_len — The size of the RX and TX buffers — see below.
• channel_type — The protocol to be used — see below.
• endpoint — A data structure comprising an endpoint identifier for cloud configuration in bytes and the number of bytes — see below.

It is the responsibility of the application to provide memory for the channel's send and receive buffers. As with other Microvisor buffers, these are circular: Microvisor maintains a write pointer which is incremented as data is written but which will jump back to the start when the end of the backing store is reached.

For both the send and receive buffers, you specify their location in non-secure, i.e., application, memory and their sizes. Microvisor will write-protect the send buffers when the channel is opened. The send buffer must be a multiple of 512 bytes in size and its address must be 512-byte aligned. For example:

static volatile uint8_t http_rx_buffer[HTTP_RX_BUFFER_SIZE_B] __attribute__((aligned(512)));

The same is true of the receive buffer if you are working with HTTP channels. Beyond this limit, you're free to choose any size and non-secure location for the receive buffer, but you should ensure you have sufficient capacity for a response's headers and data. You will receive an MV_HTTPRESULT_RESPONSETOOLARGE error — via mvReadHttpResponseData() — if the received headers and data are too large for the buffer size you have chosen.

Once a channel is open, it isn't possible to resize the buffers or change their addresses. While buffers are in use, the application must not write to them or use their memory for other purposes. In fact, attempts to write to the send buffer will trigger an application crash. When the channel is closed, Microvisor zeroes the send buffer contents and removes the write protection.

Microvisor will support a number of channel types: protocols by which data can be exchanged with remote services. Currently, Microvisor supports only the transmission and reception of HTTP — channel type MV_CHANNELTYPE_HTTP. We expect to support MQTT transfers in due course.

The endpoint property is expected to be used to specify the name of a cloud-stored configuration record. This configuration will indicate a channel's target end server and the credentials required to access that resource. This will be done to ensure that the application code need hold high-value credentials.

This functionality is not yet implemented.

Please see A Guide to Microvisor Networking for code samples.

Read a number of bytes from the channel's RX buffer

When data has been received through a channel, Microvisor dispatches an MV_EVENTTYPE_CHANNELDATAREADABLE notification. The application can read the data now or later, but when it does so, it calls mvReadChannel() to learn how many bytes to read and where those bytes are located. This is done by setting read_pointer and writing the size to length.

The application doesn't need to read all the available data in one go. When it has read any of the data, or no longer requires it, it must call mvReadChannelComplete() to inform Microvisor that some bytes are now available to take fresh incoming data.

Please see A Guide to Microvisor Networking for code samples.

Inform Microvisor the application has read a number of bytes from the RX buffer

When the application reads from a channel's RX buffer using mvReadChannel(), it should call mvReadChannelComplete() when it has finished reading. It specifies the number of bytes consumed, whether that's all of the received bytes or just some of them. This ensures that Microvisor knows how much space has been freed for further incoming data.

Please see A Guide to Microvisor Networking for code samples.

Write bytes to a channel's TX buffer

To write data to the channel's TX buffer, pass a pointer to the data and indicate its length. Microvisor will check that there is sufficient free space in the buffer. If there is, it will copy the data into the buffer and then write the number of free bytes remaining to the memory referenced by available.

If the buffer has insufficient space for the data, Microvisor will write the number of free bytes to the memory referenced by available and return an error. It does not copy any of the data to the buffer to allow the application to decide what action to take: to re-call mvWriteChannel() with sufficient data to fill the available space, for example.

To avoid this decision, applications can call mvWriteChannel() with length set to zero: this causes Microvisor just to return the buffer's count of available bytes. The application can use that value to fill or partially fill the free space in the buffer. Applications can flush the TX buffer by writing exactly the number of bytes needed to fill the buffer.

Please see A Guide to Microvisor Networking for code samples.

Write to a channel in streaming mode

mvWriteChannelStream() allows applications to treat the channel as a byte-oriented stream. In this case, it is not an error if Microvisor doesn't have space to write all or any of the data: it will just write what it can. The amount of data consumed by Microvisor is passed back to the application through the written pointer, allowing it to keep the stream fed.

Contrast this with mvWriteChannel(), which adopts a message-centric approach.

Please see A Guide to Microvisor Networking for code samples.

Instruct Microvisor to shut down a channel

When the application has finished with a channel, it can call mvCloseChannel() to end communication and free the resources used by it. Microvisor also zeroes the handle store and removes write protection from the send buffer. Once the call has returned — and only after the call has returned — the application can reallocate buffer memory as it sees fit.

Application crashes or restarts should be treated as implicit channel closures.

Please see A Guide to Microvisor Networking for code samples.

Determine why a channel was closed

If the application receives an MV_EVENTTYPE_CHANNELNOTCONNECTED notification, it can call mvGetChannelClosureReason() to find out why the channel was closed. It should do so before mvCloseChannel() is called, or the channel's handle will be invalidated and made inaccessible. It is good practice to call mvCloseChannel() on unexpectedly closed channels in order to invalidate the handle and ensure the channel is not used inadvertently.

When mvGetChannelClosureReason() is called, Microvisor writes a reason code to the memory referenced by reason. It will be one of the following:

Please see A Guide to Microvisor Networking for code samples.