Communicate with a high-level application
Important
This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.
Real-time capable applications (RTApps) communicate with high-level applications through a ring buffer that is mapped to a shared region of memory.
The IntercoreComms samples show how RTApps can communicate with high-level applications. Use the IntercoreComms_RTApp_MT3620_BareMetal sample as a starting point for developing your own RTApp communication code. See Communicate with a real-time capable application for information about the code required in a high-level application.
Important
For information about register addresses and other hardware-specific details, request the "MT3620 M4 Programmer's Guide" by emailing Azure.Sphere@avnet.com.
Operation
From the perspective of the RTApp, communication with a high-level application involves the following basic operations:
- Reading set-up information from the mailbox it shares with the high-level core on the MT3620
- Reading and writing data to shared memory
Initialize buffer sizes and pointers
The RTApp receives information about the ring buffer via three messages in the mailbox that the real-time and high-level cores share. Each message contains a command and data. The first two messages provide the base addresses of the read and write buffers that the applications will use to communicate; the third message indicates transmission of setup information for the buffers is finished.
| Command Value | Data |
|---|---|
| 0xba5e0001 | Outbound (write) buffer descriptor for the RTApp |
| 0xba5e0002 | Inbound (read) buffer descriptor for the RTApp |
| 0xba5e0003 | End of setup |
The RTApp calculates the size of the read and write buffers and sets up pointers to the initial position of each buffer based on the data in the buffer descriptors.
See the IntercoreComms_RTApp_MT3620_BareMetal sample for additional details about how to use the mailbox.
Read from and write to the buffers
After initialization, the RTApp can read from and write to the buffers. Because communication is implemented with a ring buffer, both reads and writes can wrap around to the beginning of the buffer.
Messages written to or read from the buffer have the following structure:
| Message header | Message content | ||||||
|---|---|---|---|---|---|---|---|
|
|
The first field of the message header (16 bytes) contains the component ID of the high-level app.
If the RTApp is initiating communication with the high-level app, ensure that the ordering of bytes in each of the first 3 segments of the component ID is little-endian (least significant byte first). The ordering of the bytes in the remaining two segments must be big-endian.
If the RTApp is responding to a message from the high-level app, you just need to copy the component ID in the source message to the header of the response message.
The second field of the message header (4 bytes) is currently reserved and must contain 0s.
The message header is always aligned on a 16-byte boundary.
Currently, message content can be at most 1 KB in size.
After each read or write operation to the buffer, the RTApp uses the shared mailbox to notify the high-level app that it has received or transmitted a message.
Application manifest settings
The application manifests for both the RTApp and the high-level app must list the component IDs of the applications with which they communicate. To configure this setting, add the AllowedApplicationConnections capability to the application manifest, and then add each component ID to the capability. Azure Sphere application manifest has more details. Here's an excerpt from an application manifest that configures an RTApp to communicate with one other application.
"AllowedApplicationConnections": [ "25025d2c-66da-4448-bae1-ac26fcdd3627" ]
Partner applications
When you load an application onto the Azure Sphere device, the Azure Sphere deployment tools by default delete all existing applications. To prevent this from happening when you develop applications that communicate with each other, you need to mark the applications as partners. When you deploy one of the applications, its partners will not be deleted. See Mark applications as partners for details.