PDK API Guide for AM64x
Mailbox Driver External Functions

Introduction

The section has a list of all the exported APIs which the application can invoke in order to use the driver.

Functions

static int32_t Mailbox_initParams_init (Mailbox_initParams *initParam)
 init structure initialization function. More...
 
static int32_t Mailbox_openParams_init (Mailbox_openParams *openParam)
 open structure initialization function. More...
 
int32_t Mailbox_init (Mailbox_initParams *initParam)
 Function to initialize the Mailbox module.
It must be called only once per local endpoint. More...
 
int32_t Mailbox_deinit (void)
 Function to deinitialize the Mailbox module.
. More...
 
Mbox_Handle Mailbox_open (Mailbox_openParams *openParam, int32_t *errCode)
 Function to initialize an instance of the mailbox driver. More...
 
int32_t Mailbox_enableInterrupts (Mbox_Handle handle)
 Function to enable the mailbox interrupts for a mailbox instance if enableInterrupts was set to false in the Mailbox_open params. This is useful for the situation where the application wishes to delay enabling of interrupts until it has been able to do further setup. This functionality is not supported on TPR12. More...
 
int32_t Mailbox_disableInterrupts (Mbox_Handle handle)
 Function to disable the mailbox interrupts for a mailbox instance. This functionality is not supported on TPR12. More...
 
int32_t Mailbox_write (Mbox_Handle handle, const uint8_t *buffer, uint32_t size)
 Function that writes data to a Mailbox. More...
 
int32_t Mailbox_read (Mbox_Handle handle, uint8_t *buffer, uint32_t size)
 Function that reads data from a Mailbox. More...
 
int32_t Mailbox_readFlush (Mbox_Handle handle)
 Function that should be called after application is done reading the message. More...
 
uint32_t Mailbox_GetMessageCount (Mbox_Handle handle)
 Function that retrieves the number of messages available to be read. More...
 
int32_t Mailbox_getStats (Mbox_Handle handle, Mailbox_Stats *stats)
 Function that collects mailbox driver statistics. More...
 
int32_t Mailbox_close (Mbox_Handle handle)
 Function to close a Mailbox peripheral specified by the Mailbox handle. More...
 

Function Documentation

◆ Mailbox_initParams_init()

static int32_t Mailbox_initParams_init ( Mailbox_initParams initParam)
inlinestatic

init structure initialization function.

Parameters
[in]initParamPointer to init param structure.
Returns
Returns error code in case of failure.

◆ Mailbox_openParams_init()

static int32_t Mailbox_openParams_init ( Mailbox_openParams openParam)
inlinestatic

open structure initialization function.

Parameters
[in]openParamPointer to open param structure.
Returns
Returns error code in case of failure.

◆ Mailbox_init()

int32_t Mailbox_init ( Mailbox_initParams initParam)

Function to initialize the Mailbox module.
It must be called only once per local endpoint.

Precondition
This function must be called before any other Mailbox driver API is used.
Parameters
[in]initParamPointer to init parameters.
Returns
Returns error code in case of failure.

◆ Mailbox_deinit()

int32_t Mailbox_deinit ( void  )

Function to deinitialize the Mailbox module.
.

Precondition
Mailbox_init() has been called

◆ Mailbox_open()

Mbox_Handle Mailbox_open ( Mailbox_openParams openParam,
int32_t *  errCode 
)

Function to initialize an instance of the mailbox driver.

Precondition
Mailbox_init() has been called
Parameters
[in]openParamPointer to open parameters.
[out]errCodePointer to error code value/status to be returned by the function
Returns
A Mbox_Handle upon success. NULL if an error occurs.

◆ Mailbox_enableInterrupts()

int32_t Mailbox_enableInterrupts ( Mbox_Handle  handle)

Function to enable the mailbox interrupts for a mailbox instance if enableInterrupts was set to false in the Mailbox_open params. This is useful for the situation where the application wishes to delay enabling of interrupts until it has been able to do further setup. This functionality is not supported on TPR12.

Precondition
Mailbox_open() has been called
Parameters
[in]handleA Mbox_Handle
Returns
Returns error code in case of failure.

◆ Mailbox_disableInterrupts()

int32_t Mailbox_disableInterrupts ( Mbox_Handle  handle)

Function to disable the mailbox interrupts for a mailbox instance. This functionality is not supported on TPR12.

Precondition
Mailbox_open() with open param enableInterrupts set to true or Mailbox_enableInterrupts() has been called.
Parameters
[in]handleA Mbox_Handle
Returns
Returns error code in case of failure.

◆ Mailbox_write()

int32_t Mailbox_write ( Mbox_Handle  handle,
const uint8_t *  buffer,
uint32_t  size 
)

Function that writes data to a Mailbox.

Mailbox can only send one message at a time to a remote endpoint. After data is copied to mailbox buffer, driver triggers interrupt to remote endpoint. This means that a call to the Mailbox_write() is always a complete mailbox transaction. A new message can only be sent after the previous message has been acknowledged by the remote endpoint. The acknowledgement process is handled internally by the driver. All interrupts related to the write operations are managed by the driver and are not exposed to the application. If called with data that will surpass the maximum size of the mailbox buffer, the write operation will fail with an error code and nothing will be written to the mailbox buffer. Returns number of bytes written or error.
The maximum size of the mailbox buffer is given by MAILBOX_DATA_BUFFER_SIZE. Application code is responsible for fragmentation of the message if the size is bigger than the mailbox buffer.

Write modes:

In Mailbox_MODE_BLOCKING:
Mailbox_write() will block task execution until the message has been copied from application to the mailbox buffer and an acknowledgement is received from the remote endpoint. If a new Mailbox_write() is issued before the acknowledgement is received, the write will fail with an error code returned to application.

In Mailbox_MODE_POLLING:
Mailbox_write() will block task execution until the message has been copied from application to the mailbox buffer but it does not wait for an acknowledgement from the remote endpoint. If a new Mailbox_write() is issued before the acknowledgement is received, the write will fail with an error code returned to application. In this mode, application does not know when acknowledgement is received and it may try to write the next message multiple times until it succeeds as if it is polling for the status of the acknowledgement.

In Mailbox_MODE_FAST:
Mailbox_write() will behave similar to Mailbox_MODE_POLLING, but limited to no error checking is performed in order to achieve the best latency. It is the responsibility of the application to ensure that there is sufficient space in the mailbox to complete the write operation successfully. For performance reasons, no protection and limited error checking is provided in this mode. The application takes the responsibility of making sure that access to the API is properly protected. Please see the soc-specific documentation for support for this mode as this mode is not supported in all cases.

Precondition
Mailbox_open() has been called
Parameters
[in]handleA Mbox_Handle
[in]bufferA pointer to buffer containing data to be written to the Mailbox.
[in]sizeThe number of bytes in the buffer that should be written to the Mailbox.
Returns
Returns the number of bytes that have been written to the Mailbox. If an error occurs, one of the Mailbox Error codes is returned.

◆ Mailbox_read()

int32_t Mailbox_read ( Mbox_Handle  handle,
uint8_t *  buffer,
uint32_t  size 
)

Function that reads data from a Mailbox.

Mailbox can only read one message at a time from a remote endpoint. Multiple Mailbox_read() calls can be done for the same message in the mailbox.

E.g. Application can read part of the message to figure out full message length and issue a subsequent Mailbox_read().

Mailbox driver keeps track internally of number of bytes read for a message. The first Mailbox_read() for a message always starts at byte zero. In case of multiple Mailbox_read() calls for the same message, the subsequent reads start in the next byte from where the previous read stopped. Once application finishes reading the message it must issue a Mailbox_readFlush() to release the mailbox buffer and notify the remote endpoint.
The maximum size of the mailbox buffer is given by MAILBOX_DATA_BUFFER_SIZE. Application code is responsible for fragmentation of the message if the size is bigger than the mailbox buffer.

All interrupts related to the read operation are managed by the driver and are not exposed to the application. Returns number of bytes read or error.

Read modes:

In Mailbox_MODE_BLOCKING:
If this is the first read on a new message, Mailbox_read() will block task execution until a new message has arrived in the local Mailbox buffer and it is copied to the application buffer. If this is not a new message, Mailbox_read() will block task execution until "size" bytes are copied to the application buffer.

In Mailbox_MODE_POLLING:
If this is the first read on a new message and the new message has not arrived, Mailbox_read() will return size zero to indicate no bytes were read. If the new message has arrived or if this is not a new message, Mailbox_read() will copy the data to application buffer. Mailbox_read() will return after "size" bytes are copied to the application buffer.

In Mailbox_MODE_CALLBACK:
The driver will invoke the application callback function once a new message is received in the mailbox. Application is responsible for calling Mailbox_read() to read the new message. Mailbox_read() copies the data into the application buffer and then exit.

In Mailbox_MODE_FAST:
The driver will invoke the application callback function (if provided) when a new message is received in the mailbox. If not callback is provided, then the application must call Mailbox_read() in a polling manner to retrieve messages. Application is responsible for calling Mailbox_read() to read the new message. Mailbox_read() copies the data into the application buffer and then exit. For performance reasons, no protection and limited error checking is provided in this mode. The application takes the responsibility of making sure that access to the API is properly protected. Please see the soc-specific documentation for support for this mode as this mode is not supported in all cases. In addition, when running in this mode, the application can choose to enable VIM direct interrupt registration in the driver by setting the open-time config enableVIMDirectInterrupt. When this option is enabled, the driver will register the driver's interrupt handler directly with the VIM, providing a software performance savings. However, there are limitations when choosing this mode. Currently, this option should only be used by baremetal applications and not RTOS applications as there is no support for this feature with RTOS currently. If this option is enabled for RTOS, it will be ignored and fall back to the regular interrupt registration path.

For TPR12, in any of the modes described above, Mailbox_readFlush() needs to be issued after the message is fully read by the application.

Precondition
Mailbox_open() has been called
Parameters
[in]handleA Mbox_Handle
[in]bufferA pointer to an empty buffer in which received data should be written to.
[in]sizeThe number of bytes to be written into buffer
Returns
Returns the number of bytes that have been read from the Mailbox. If an error occurs, one of the Mailbox Error codes is returned.

◆ Mailbox_readFlush()

int32_t Mailbox_readFlush ( Mbox_Handle  handle)

Function that should be called after application is done reading the message.

Notifies the remote endpoint that the local mailbox is ready to receive a new message after the previous message was read.
Remote endpoint can not send a new message to the local endpoint until Mailbox_readFlush() is issued by the local endpoint. Once Mailbox_readFlush() is issued, the local endpoint must assume that the previously received message is no longer in the mailbox buffer and subsequent Mailbox_read() will return no data until a new message arrives in the mailbox. This applies only for TPR12 Mailbox LLD. It is not needed for AM64X.

Precondition
Mailbox_open() has been called
Parameters
[in]handleA Mbox_Handle
Returns
Returns error code in case of failure.

◆ Mailbox_GetMessageCount()

uint32_t Mailbox_GetMessageCount ( Mbox_Handle  handle)

Function that retrieves the number of messages available to be read.

If the mailbox HW is capable of supporting multiple messages at a time, then the number of messages currently available in the mailbox can be retrieved by calling this function. The application can use this information, for example, to determine how many messasges to read after receiving a callback.

Precondition
Mailbox_open() has been called
Parameters
[in]handleA Mbox_Handle
Returns
Returns the number of messages available in the mailbox.

◆ Mailbox_getStats()

int32_t Mailbox_getStats ( Mbox_Handle  handle,
Mailbox_Stats stats 
)

Function that collects mailbox driver statistics.

This function is used to collect mailbox driver statistics. It's main purpose is debugging of mailbox driver.

Precondition
Mailbox_open() has been called
Parameters
[in]handleA Mbox_Handle
[out]statsPointer to mailbox stats structure to be filled
Returns
Returns error code in case of failure.

◆ Mailbox_close()

int32_t Mailbox_close ( Mbox_Handle  handle)

Function to close a Mailbox peripheral specified by the Mailbox handle.

Precondition
Mailbox_open() has been called.
Parameters
[in]handleA Mbox_Handle returned from Mailbox_open()
See also
Mailbox_open()
Returns
Returns error code in case of failure.