Mailbox Driver

The Mailbox driver simplifies reading and writing to the Mailbox peripherals on the board with multiple modes of operation and performance. These include blocking, non-blocking, callback. Throughout this document the term local endpoint refers to the subsystem that instantiates the mailbox driver. The term remote endpoint refers to the subsystem that communicates to the local endpoint through the mailbox instance.
The application initializes the Mailbox driver by calling Mailbox_init() and it is then ready to open a Mailbox instance to a remote endpoint by calling Mailbox_open(). Once the mailbox instance is open, read and write operations can be performed.
The Mailbox header file should be included in an application as follows:

#include <ti/drivers/mailbox/mailbox.h>

The mailbox/include/reg_mailbox.h has the register layer definitions for the Mailbox Module.

Initializing the driver

The Mailbox Driver needs to be initialized once per master (MSS or DSS). This is done using the Mailbox_init. None of the Mailbox APIs can be used before invoking this API.

Opening the driver

Once the Mailbox Driver has been initialized, the Mailbox Driver instance can be opened using the Mailbox_open.
For XWR14xx:
Between MSS<->BSS only one instance of the driver can be opened.
Note that the mailbox driver is instantiated in the MSS only. In the BSS, the BSS firmware handles the mailbox operations.
For XWR16xx/XWR18xx/XWR68xx:
Between MSS<->BSS only one instance of the driver can be opened.
Note that the mailbox driver is instantiated in the MSS only. In the BSS, the BSS firmware handles the mailbox operations.
Between DSS<->BSS only one instance of the driver can be opened.
Note that the mailbox driver is instantiated in the DSS only. In the BSS, the BSS firmware handles the mailbox operations.
Between MSS<->DSS multiple instances of the driver can be opened (each instance controls one virtual channel).
Note that the mailbox driver is instantiated both in the MSS and DSS.

Example 1:
The example below applies for XWR14xx and XWR16xx/XWR18xx/XWR68xx SoCs.
Following is pseudo code for opening the Mailbox driver for MSS to talk to BSS.
In this example the mailbox write mode is set to be polling and mailbox read mode is set to be callback.

Mbox_Handle  handle;
int32_t         errCode;
Mailbox_Config  cfg;

Mailbox_init(MAILBOX_TYPE_MSS);

if(Mailbox_Config_init(&cfg) < 0)
{
    Error: Unable to initialize configuration
}

cfg.writeMode    = MAILBOX_MODE_POLLING;
cfg.readMode     = MAILBOX_MODE_CALLBACK;
cfg.readCallback = myApp_mboxCallbackFxn;

handle = Mailbox_open(MAILBOX_TYPE_BSS, &cfg, &errCode);

if((handle == NULL) || (errCode != 0))
{
    Error: Unable to open mailbox between MSS and BSS.
}

Example 2:
The example below applies for XWR16xx/XWR18xx/XWR68xx SoC only.
Following is pseudo code for opening the Mailbox driver for MSS to talk to DSS.
In this example the mailbox write mode is set to be polling and mailbox read mode is set to be callback. Also, in this example, MSS and DSS applications are using multi-channels to communicate and the specific channels used in this case have ID MAILBOX_CH_ID_0 and MAILBOX_CH_ID_1.
Note that both endpoints need to use the same ID so that the channels are connected correctly.
Note that all mailbox channels are bi-directional. In this example, 2 bi-directional channels are open to show the configuration of multiple mailbox channels.

The following code runs on MSS:

Mbox_Handle  handle[2];
int32_t         errCode;
Mailbox_Config  cfg;

Mailbox_init(MAILBOX_TYPE_MSS);

if(Mailbox_Config_init(&cfg) < 0)
{
    Error: Unable to initialize configuration
}

cfg.writeMode    = MAILBOX_MODE_POLLING;
cfg.readMode     = MAILBOX_MODE_CALLBACK;
cfg.readCallback = myApp_mboxCallbackFxn_MSS_ch0;
cfg.chType       = MAILBOX_CHTYPE_MULTI;
cfg.chId         = MAILBOX_CH_ID_0;

handle[0] = Mailbox_open(MAILBOX_TYPE_DSS, &cfg, &errCode);

if((handle == NULL) || (errCode != 0))
{
    Error: Unable to open mailbox channel 0 between MSS and DSS.
}
cfg.writeMode    = MAILBOX_MODE_POLLING;
cfg.readMode     = MAILBOX_MODE_CALLBACK;
cfg.readCallback = myApp_mboxCallbackFxn_MSS_ch1;
cfg.chType       = MAILBOX_CHTYPE_MULTI;
cfg.chId         = MAILBOX_CH_ID_1;

handle[1] = Mailbox_open(MAILBOX_TYPE_DSS, &cfg, &errCode);

if((handle == NULL) || (errCode != 0))
{
    Error: Unable to open mailbox channel 1 between MSS and DSS.
}

The following code runs on DSS:

Mbox_Handle  handle[2];
int32_t         errCode;
Mailbox_Config  cfg;

Mailbox_init(MAILBOX_TYPE_DSS);

if(Mailbox_Config_init(&cfg) < 0)
{
    Error: Unable to initialize configuration
}

cfg.writeMode    = MAILBOX_MODE_POLLING;
cfg.readMode     = MAILBOX_MODE_CALLBACK;
cfg.readCallback = myApp_mboxCallbackFxn_DSS_ch0;
cfg.chType       = MAILBOX_CHTYPE_MULTI;
cfg.chId         = MAILBOX_CH_ID_0;

handle[0] = Mailbox_open(MAILBOX_TYPE_MSS, &cfg, &errCode);

if((handle == NULL) || (errCode != 0))
{
    Error: Unable to open mailbox channel 0 between DSS and MSS.
}

cfg.writeMode    = MAILBOX_MODE_POLLING;
cfg.readMode     = MAILBOX_MODE_CALLBACK;
cfg.readCallback = myApp_mboxCallbackFxn_DSS_ch1;
cfg.chType       = MAILBOX_CHTYPE_MULTI;
cfg.chId         = MAILBOX_CH_ID_1;

handle[1] = Mailbox_open(MAILBOX_TYPE_MSS, &cfg, &errCode);

if((handle == NULL) || (errCode != 0))
{
    Error: Unable to open mailbox channel 1 between DSS and MSS.
}

Writing a message

Once the Mailbox Driver has been opened, the application can write a message to the remote endpoint using Mailbox_write.

Reading a message

Once the Mailbox Driver has been opened, the application can read a message from the remote endpoint using Mailbox_read followed by Mailbox_readFlush after the message is fully read.