![]() |
PDK API Guide for AM64x
|
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... | |
|
inlinestatic |
init structure initialization function.
[in] | initParam | Pointer to init param structure. |
|
inlinestatic |
open structure initialization function.
[in] | openParam | Pointer to open param structure. |
int32_t Mailbox_init | ( | Mailbox_initParams * | initParam | ) |
Function to initialize the Mailbox module.
It must be called only once per local endpoint.
[in] | initParam | Pointer to init parameters. |
int32_t Mailbox_deinit | ( | void | ) |
Function to deinitialize the Mailbox module.
.
Mbox_Handle Mailbox_open | ( | Mailbox_openParams * | openParam, |
int32_t * | errCode | ||
) |
Function to initialize an instance of the mailbox driver.
[in] | openParam | Pointer to open parameters. |
[out] | errCode | Pointer to error code value/status to be returned by the function |
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.
[in] | handle | A Mbox_Handle |
int32_t Mailbox_disableInterrupts | ( | Mbox_Handle | handle | ) |
Function to disable the mailbox interrupts for a mailbox instance. This functionality is not supported on TPR12.
[in] | handle | A Mbox_Handle |
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.
[in] | handle | A Mbox_Handle |
[in] | buffer | A pointer to buffer containing data to be written to the Mailbox. |
[in] | size | The number of bytes in the buffer that should be written to the Mailbox. |
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.
[in] | handle | A Mbox_Handle |
[in] | buffer | A pointer to an empty buffer in which received data should be written to. |
[in] | size | The number of bytes to be written into buffer |
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.
[in] | handle | A Mbox_Handle |
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.
[in] | handle | A Mbox_Handle |
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.
[in] | handle | A Mbox_Handle |
[out] | stats | Pointer to mailbox stats structure to be filled |
int32_t Mailbox_close | ( | Mbox_Handle | handle | ) |
Function to close a Mailbox peripheral specified by the Mailbox handle.
[in] | handle | A Mbox_Handle returned from Mailbox_open() |