PDK API Guide for AM64x
MAILBOX_DRIVER_EXTERNAL_DATA_STRUCTURE

Introduction

Data Structures

struct  Mailbox_Config
 Mailbox Configuration Parameters. More...
 
struct  Mailbox_Stats
 Mailbox Statistics. More...
 
struct  Mailbox_initParams
 Mailbox initialization parameters. More...
 
struct  Mailbox_openParams
 Mailbox Open parameters. More...
 

Typedefs

typedef void * Mbox_Handle
 A handle that is returned from a Mailbox_open() call. More...
 
typedef void(* Mailbox_Callback) (Mbox_Handle handle, Mailbox_Instance remoteEndpoint)
 The definition of a callback function used by the MAILBOX driver when used in MAILBOX_MODE_CALLBACK. The callback can occur in task or HWI context. More...
 
typedef uint64_t(* Mailbox_VirtToPhyFxn) (const void *virtAddr)
 
typedef void *(* Mailbox_PhyToVirtFxn) (uint64_t phyAddr)
 MAILBOX Physical to Virtual address translation callback function. More...
 

Enumerations

enum  Mailbox_Mode { MAILBOX_MODE_BLOCKING, MAILBOX_MODE_POLLING, MAILBOX_MODE_CALLBACK, MAILBOX_MODE_FAST }
 Mailbox mode settings. More...
 
enum  Mailbox_OpMode { MAILBOX_OPERATION_MODE_PARTIAL_READ_ALLOWED }
 Mailbox operation mode settings. More...
 
enum  Mailbox_DataTransferMode { MAILBOX_DATA_TRANSFER_MEMCPY, MAILBOX_DATA_TRANSFER_DMA }
 Mailbox data transfer mode. More...
 
enum  Mailbox_ChType { MAILBOX_CHTYPE_SINGLE = 0, MAILBOX_CHTYPE_MULTI = 1, MAILBOX_CHTYPE_MAX = MAILBOX_CHTYPE_MULTI }
 Mailbox channel type. More...
 
enum  Mailbox_ChID {
  MAILBOX_CH_ID_0 = 0, MAILBOX_CH_ID_1 = 1, MAILBOX_CH_ID_2 = 2, MAILBOX_CH_ID_3 = 3,
  MAILBOX_CH_ID_4 = 4, MAILBOX_CH_ID_5 = 5, MAILBOX_CH_ID_6 = 6, MAILBOX_CH_ID_7 = 7,
  MAILBOX_CH_ID_MAX = MAILBOX_CH_ID_7
}
 Mailbox channel ID. More...
 

Typedef Documentation

◆ Mbox_Handle

typedef void* Mbox_Handle

A handle that is returned from a Mailbox_open() call.

◆ Mailbox_Callback

typedef void(* Mailbox_Callback) (Mbox_Handle handle, Mailbox_Instance remoteEndpoint)

The definition of a callback function used by the MAILBOX driver when used in MAILBOX_MODE_CALLBACK. The callback can occur in task or HWI context.

Warning
For TPR12, making Mailbox_read() calls within its own callback routines are STRONGLY discouraged as it will impact Task and System stack size requirements! For AM64x, it is advised to call Mailbox_read() within the callback routine in this mode, because the interrupt will remain asserted until the message is read.
Parameters
handleMbox_Handle
remoteEndpointRemote endpoint

◆ Mailbox_VirtToPhyFxn

typedef uint64_t(* Mailbox_VirtToPhyFxn) (const void *virtAddr)

◆ Mailbox_PhyToVirtFxn

typedef void*(* Mailbox_PhyToVirtFxn) (uint64_t phyAddr)

MAILBOX Physical to Virtual address translation callback function.

This function is used by the driver to convert physical address to virtual address.

Parameters
phyAddr[IN] Physical address
Returns
Corresponding virtual address

Enumeration Type Documentation

◆ Mailbox_Mode

Mailbox mode settings.

This enum defines the read and write modes for the configured Mailbox. Note that not all types are supported by read/write APIs.

Enumerator
MAILBOX_MODE_BLOCKING 

Blocking mode. Driver uses a semaphore to block while data is being sent or received. Context of the call must be a Task. Please refer to Mailbox_write() and Mailbox_read() APIs for specific information.

MAILBOX_MODE_POLLING 

Polling mode. Please refer to Mailbox_write() and Mailbox_read() APIs for specific information.

MAILBOX_MODE_CALLBACK 

Call back mode. Valid only for Mailbox_read API. Application call back functions are called when interrupt is received for a new message to be read or when interrupted is received from an acknowledge of a previously transmitted message. Application still needs to call the Mailbox_read() API to handle the received message.

MAILBOX_MODE_FAST 

Fast mode. Please refer to Mailbox_write() and Mailbox_read() APIs for specific information. In this mode, for performance reasons there is no protection and limited error checking. Application must take care to protect access to the mailbox.

◆ Mailbox_OpMode

Mailbox operation mode settings.

This enum defines the operation modes for the configured Mailbox.

Enumerator
MAILBOX_OPERATION_MODE_PARTIAL_READ_ALLOWED 

Current only one available operation mode. In this mode the driver allows for a partial read of a received message. Mailbox_readFlush() needs to be used once application finishes reading the message.

◆ Mailbox_DataTransferMode

Mailbox data transfer mode.

This enum defines the data transfer mode for the mailbox instance.
It configures how the data is transferred from the application buffer to the mailbox peripheral and from the mailbox peripheral to the application buffer in the Mailbox_write and Mailbox_read APIs. The configuration applies to both directions.

Enumerator
MAILBOX_DATA_TRANSFER_MEMCPY 

Data transfer between maibox memory and application memory done through memcpy()

MAILBOX_DATA_TRANSFER_DMA 

Data transfer between maibox memory and application memory done through DMA

Warning
This mode is currently not supported.

◆ Mailbox_ChType

Mailbox channel type.

This enum defines the mailbox channel type. This field allows to use multiple (virtual) mailbox channels to communicate.
As there is only one mailbox physical channel, even when multiple channels are open, only one channel can be used at a time by the application.
When multiple channels are used, each channel is identified by a Mailbox_ChID.
The maximum number of channels (or mailbox instances) is given by MAILBOX_CH_ID_MAX.
Each channel is created by opening a new instance of the mailbox driver using a different Mailbox_ChID.
If a channel is opened as MAILBOX_CHTYPE_SINGLE then only one channel is allowed and Mailbox_ChID does not need to be populated.
Note that the channel types can not be mixed. That is, a channel of type MAILBOX_CHTYPE_SINGLE in MSS (or DSS) can not communicate with a channel of type MAILBOX_CHTYPE_MULTI on DSS (or MSS).
Also note that if a channel is opened of type MAILBOX_CHTYPE_MULTI, then all channels must be of MAILBOX_CHTYPE_MULTI.

Enumerator
MAILBOX_CHTYPE_SINGLE 

Only one mailbox channel (in each direction) allowed between local and remote endpoint.
In this case, the field Mailbox_ChID does NOT need to be specified.

MAILBOX_CHTYPE_MULTI 

Multiple mailbox channels (in each direction) allowed between local and remote endpoint.
In this case, the field Mailbox_ChID needs to be specified.

MAILBOX_CHTYPE_MAX 

Maximum channel type value.

◆ Mailbox_ChID

Mailbox channel ID.

This enum defines the possible mailbox channel IDs.
IDs are used only when Mailbox_ChType is of type MAILBOX_CHTYPE_MULTI.

Enumerator
MAILBOX_CH_ID_0 

ID = 0

MAILBOX_CH_ID_1 

ID = 1

MAILBOX_CH_ID_2 

ID = 2

MAILBOX_CH_ID_3 

ID = 3

MAILBOX_CH_ID_4 

ID = 4

MAILBOX_CH_ID_5 

ID = 5

MAILBOX_CH_ID_6 

ID = 6

MAILBOX_CH_ID_7 

ID = 7

MAILBOX_CH_ID_MAX 

Maximum ID value, which is MAILBOX_CH_ID_7