PDK API Guide for AM64x
mailbox.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) Texas Instruments Incorporated 2020
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  *
8  * Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *
11  * Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the
14  * distribution.
15  *
16  * Neither the name of Texas Instruments Incorporated nor the names of
17  * its contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 
78 #ifndef MAILBOX_DRIVER_H
79 #define MAILBOX_DRIVER_H
80 
81 /* ========================================================================== */
82 /* Include Files */
83 /* ========================================================================== */
84 
85 #include <stdint.h>
86 #include "ti/drv/mailbox/soc/mailbox_soc.h"
88 
89 #ifdef __cplusplus
90 extern "C" {
91 #endif
92 
93 /* ========================================================================== */
94 /* Macros & Typedefs */
95 /* ========================================================================== */
96 
104 #define MAILBOX_ERRNO_BASE (-2100)
105 
109 #define MAILBOX_SOK (0)
110 
114 #define MAILBOX_EINVAL (MAILBOX_ERRNO_BASE-1)
115 
120 #define MAILBOX_EINUSE (MAILBOX_ERRNO_BASE-2)
121 
125 #define MAILBOX_ENOMEM (MAILBOX_ERRNO_BASE-3)
126 
130 #define MAILBOX_EINVALCFG (MAILBOX_ERRNO_BASE-4)
131 
139 #define MAILBOX_ETXFULL (MAILBOX_ERRNO_BASE-5)
140 
145 #define MAILBOX_ETXACKTIMEDOUT (MAILBOX_ERRNO_BASE-6)
146 
150 #define MAILBOX_EREADTIMEDOUT (MAILBOX_ERRNO_BASE-7)
151 
155 #define MAILBOX_EINITIALIZED (MAILBOX_ERRNO_BASE-8)
156 
160 #define MAILBOX_EOSAL (MAILBOX_ERRNO_BASE-9)
161 
168 #define MAILBOX_EBADCHTYPE (MAILBOX_ERRNO_BASE-10)
169 
175 #define MAILBOX_EBADCHID (MAILBOX_ERRNO_BASE-11)
176 
180 #define MAILBOX_ECHINUSE (MAILBOX_ERRNO_BASE-12)
181 
185 #define MAILBOX_ETIMEOUT (MAILBOX_ERRNO_BASE-13)
186 
192 #define MAILBOX_NUM_ENDPOINT_TYPES ((uint8_t)3)
193 
197 #define MAILBOX_DATA_BUFFER_SIZE ((uint32_t)2044U)
198 
202 #define MAILBOX_WAIT_FOREVER (~((uint32_t) 0U))
203 
208 #define MAILBOX_OSAL_DEFAULT_PRIORITY (~((uint32_t) 0U))
209 
217 typedef void* Mbox_Handle;
218 
225 typedef enum
226 {
254 } Mailbox_Mode;
255 
261 typedef enum
262 {
270 
280 typedef enum
281 {
292 
310 typedef enum
311 {
327 
335 typedef enum
336 {
373 } Mailbox_ChID;
374 
391 typedef void (*Mailbox_Callback) (Mbox_Handle handle, Mailbox_Instance remoteEndpoint);
392 
393 /*
394  * \brief MAILBOX Virtual to Physical address translation callback function.
395  *
396  * This function is used by the driver to convert virtual address to physical
397  * address.
398  *
399  * \param virtAddr [IN] Virtual address
400  *
401  * \return Corresponding physical address
402  */
403 typedef uint64_t (*Mailbox_VirtToPhyFxn)(const void *virtAddr);
414 typedef void *(*Mailbox_PhyToVirtFxn)(uint64_t phyAddr);
415 
416 /* ========================================================================== */
417 /* Structure Declarations */
418 /* ========================================================================== */
419 
427 typedef struct Mailbox_Config_t
428 {
440  uint32_t readTimeout;
444  uint32_t writeTimeout;
489 
498 typedef struct Mailbox_Stats_t
499 {
503  uint32_t txBoxStatus;
507  uint16_t txCount;
511  uint16_t rxCount;
515  uint32_t newMessageFlag;
519  uint32_t numBytesRead;
523  uint16_t boxFullIsrCount;
531  uint16_t readFlushCount;
543  uint32_t regLclToRemRaw;
547  uint32_t regRemToLocRaw;
551  uint32_t regLclToRemMask;
555  uint32_t regRemToLocMask;
557 
562 typedef struct Mailbox_initParams_t
563 {
564  /* \brief Local Mailbox endpoint. */
566 
567  /* \brief OSAL callback parameters. */
569 
570  /* \brief Virtual to Physical Address conversion function */
572 
573  /* \brief Physical to Virtual Address conversion function */
575 
576  /* TODO: Add Memory Init paramterers.*/
577  /* TODO: Add Memory partitoining parameters.*/
579 
584 typedef struct Mailbox_openParams_t
585 {
586  /* \brief Local Mailbox endpoint. */
588  /* \brief configuration parameters. */
591 
596 /* ========================================================================== */
597 /* Function Declarations */
598 /* ========================================================================== */
599 
616 static inline int32_t Mailbox_initParams_init (Mailbox_initParams *initParam);
617 
627 static inline int32_t Mailbox_openParams_init (Mailbox_openParams *openParam);
628 
643 extern int32_t Mailbox_init(Mailbox_initParams *initParam);
644 
652 extern int32_t Mailbox_deinit(void);
653 
668 extern Mbox_Handle Mailbox_open(Mailbox_openParams *openParam, int32_t* errCode);
669 
686 extern int32_t Mailbox_enableInterrupts(Mbox_Handle handle);
687 
701 extern int32_t Mailbox_disableInterrupts(Mbox_Handle handle);
702 
758  /* Code review: Input variable "size" can be 16bit but 32bit matches the RL interface*/
759 extern int32_t Mailbox_write(Mbox_Handle handle, const uint8_t *buffer, uint32_t size);
760 
834 extern int32_t Mailbox_read(Mbox_Handle handle, uint8_t *buffer, uint32_t size);
835 
854 extern int32_t Mailbox_readFlush(Mbox_Handle handle);
855 
872 extern uint32_t Mailbox_GetMessageCount(Mbox_Handle handle);
873 
891 extern int32_t Mailbox_getStats(Mbox_Handle handle, Mailbox_Stats *stats);
892 
907 extern int32_t Mailbox_close(Mbox_Handle handle);
908  /* end defgroup MAILBOX_DRIVER_EXTERNAL_FUNCTION */
910 
911 /* ========================================================================== */
912 /* Internal Function Declarations */
913 /* ========================================================================== */
914 
922 extern uint64_t Mailbox_defaultVirtToPhyFxn(const void *virtAddr);
923 
931 extern void *Mailbox_defaultPhyToVirtFxn(uint64_t phyAddr);
932 
933 /* ========================================================================== */
934 /* Static Function Definitions */
935 /* ========================================================================== */
936 
937 static inline int32_t Mailbox_initParams_init (Mailbox_initParams *initParam)
938 {
939  int32_t retVal = MAILBOX_EINVAL;
940  if(initParam != NULL)
941  {
942  initParam->localEndpoint = MAILBOX_INST_INVALID;
945  MboxOsalPrms_init(&initParam->osalPrms);
946  retVal = MAILBOX_SOK;
947  }
948  return retVal;
949 }
950 
951 static inline int32_t Mailbox_openParams_init (Mailbox_openParams *openParam)
952 {
953  int32_t retVal = MAILBOX_EINVAL;
954  if(openParam != NULL)
955  {
957  openParam->cfg.readMode = MAILBOX_MODE_BLOCKING;
958  openParam->cfg.writeMode = MAILBOX_MODE_BLOCKING;
959  openParam->cfg.readTimeout = MAILBOX_WAIT_FOREVER;
961  openParam->cfg.readCallback = NULL;
964  openParam->cfg.chType = MAILBOX_CHTYPE_SINGLE;
965  openParam->cfg.chId = MAILBOX_CH_ID_0;
966  openParam->cfg.enableVIMDirectInterrupt = false;
967  openParam->cfg.enableInterrupts = true;
968  retVal = MAILBOX_SOK;
969  }
970  return retVal;
971 }
972 
973 #ifdef __cplusplus
974 }
975 #endif
976 
977 #endif /* MAILBOX_DRIVER_H */
uint32_t numBytesRead
Number of bytes already read by past calls to the read API in current message.
Definition: mailbox.h:519
void *(* Mailbox_PhyToVirtFxn)(uint64_t phyAddr)
MAILBOX Physical to Virtual address translation callback function.
Definition: mailbox.h:414
uint32_t regRemToLocMask
Mailbox register.
Definition: mailbox.h:555
Definition: mailbox.h:348
Mailbox_ChType chType
Mailbox channel type.
Definition: mailbox.h:461
uint32_t Mailbox_Instance
Mailbox Instance Number.
Definition: mailbox_soc.h:62
int32_t Mailbox_close(Mbox_Handle handle)
Function to close a Mailbox peripheral specified by the Mailbox handle.
Mailbox Configuration Parameters.
Definition: mailbox.h:427
void * Mbox_Handle
A handle that is returned from a Mailbox_open() call.
Definition: mailbox.h:217
Mailbox_Callback readCallback
Pointer to read callback.
Definition: mailbox.h:448
Mailbox_ChID
Mailbox channel ID.
Definition: mailbox.h:335
Mailbox_DataTransferMode
Mailbox data transfer mode.
Definition: mailbox.h:280
Definition: mailbox.h:360
bool enableInterrupts
Whether to enable interrupts during interrupt registration or not. Some software may want to control ...
Definition: mailbox.h:487
Mailbox_Instance remoteEndpoint
Definition: mailbox.h:587
Definition: mailbox.h:321
#define MAILBOX_INST_INVALID
Invalid Mailbox INST.
Definition: mailbox_soc.h:84
Mailbox driver OSAL function pointers.
Definition: mailbox_osal.h:182
Mailbox_ChID chId
Channel ID for this instance of the driver. Used only when chType is set to MAILBOX_CHTYPE_MULTI.
Definition: mailbox.h:467
uint32_t txBoxStatus
Status of TX box (full or empty)
Definition: mailbox.h:503
Definition: mailbox.h:364
uint16_t rxCount
Number of RX messages received.
Definition: mailbox.h:511
bool enableVIMDirectInterrupt
For R5F cores and select SoCs, the driver provides the ability to do direct VIM interrupt registratio...
Definition: mailbox.h:477
Definition: mailbox.h:232
Mailbox_Config cfg
Definition: mailbox.h:589
Mailbox_ChType
Mailbox channel type.
Definition: mailbox.h:310
Mailbox_Mode readMode
Mailbox read mode.
Definition: mailbox.h:432
uint32_t newMessageFlag
Flag used for read polling mode. Indicate if a new message has arrived.
Definition: mailbox.h:515
uint32_t readTimeout
Timeout for read semaphore.
Definition: mailbox.h:440
Definition: mailbox.h:237
Mailbox_PhyToVirtFxn phyToVirtFxn
Definition: mailbox.h:574
uint32_t regRemToLocRaw
Mailbox register.
Definition: mailbox.h:547
uint16_t boxFullIsrCount
Number of full box ISR received.
Definition: mailbox.h:523
#define MAILBOX_WAIT_FOREVER
Wait forever define.
Definition: mailbox.h:202
Definition: mailbox.h:316
Definition: mailbox.h:340
uint64_t Mailbox_defaultVirtToPhyFxn(const void *virtAddr)
Default virtual to physical translation function.
Mailbox Osal definitions.
Definition: mailbox.h:290
uint16_t readFlushCount
Number of times the readFlush API was called.
Definition: mailbox.h:531
int32_t Mailbox_write(Mbox_Handle handle, const uint8_t *buffer, uint32_t size)
Function that writes data to a Mailbox.
#define MAILBOX_EINVAL
Error Code: Invalid argument.
Definition: mailbox.h:114
#define MAILBOX_SOK
Error Code: Invalid argument.
Definition: mailbox.h:109
#define NULL
Define NULL if not defined.
Definition: csl_types.h:107
void MboxOsalPrms_init(Mbox_OsalPrms *osalPrms)
Mbox_OsalPrms structure init function.
Mailbox_Instance localEndpoint
Definition: mailbox.h:565
Definition: mailbox.h:368
int32_t Mailbox_disableInterrupts(Mbox_Handle handle)
Function to disable the mailbox interrupts for a mailbox instance. This functionality is not supporte...
static int32_t Mailbox_openParams_init(Mailbox_openParams *openParam)
open structure initialization function.
Definition: mailbox.h:951
Definition: mailbox.h:285
Mailbox_OpMode opMode
Driver mode of operation.
Definition: mailbox.h:452
Mailbox_OpMode
Mailbox operation mode settings.
Definition: mailbox.h:261
uint16_t txCount
Number of TX messages successfully sent (acknowledgement has been received)
Definition: mailbox.h:507
uint32_t regLclToRemRaw
Mailbox register.
Definition: mailbox.h:543
Mailbox Statistics.
Definition: mailbox.h:498
Mailbox_VirtToPhyFxn virtToPhyFxn
Definition: mailbox.h:571
Mailbox_Mode
Mailbox mode settings.
Definition: mailbox.h:225
void * Mailbox_defaultPhyToVirtFxn(uint64_t phyAddr)
Default physical to virtual translation function.
Mbox_Handle Mailbox_open(Mailbox_openParams *openParam, int32_t *errCode)
Function to initialize an instance of the mailbox driver.
uint8_t boxFullIsrErrCount
Number of full box ISR received with invalid arg.
Definition: mailbox.h:535
uint32_t Mailbox_GetMessageCount(Mbox_Handle handle)
Function that retrieves the number of messages available to be read.
uint32_t writeTimeout
Timeout for write semaphore.
Definition: mailbox.h:444
Mailbox_Mode writeMode
Mailbox write mode.
Definition: mailbox.h:436
Mbox_OsalPrms osalPrms
Definition: mailbox.h:568
Definition: mailbox.h:356
static int32_t Mailbox_initParams_init(Mailbox_initParams *initParam)
init structure initialization function.
Definition: mailbox.h:937
Mailbox initialization parameters.
Definition: mailbox.h:562
int32_t Mailbox_init(Mailbox_initParams *initParam)
Function to initialize the Mailbox module. It must be called only once per local endpoint.
Mailbox Open parameters.
Definition: mailbox.h:584
int32_t Mailbox_enableInterrupts(Mbox_Handle handle)
Function to enable the mailbox interrupts for a mailbox instance if enableInterrupts was set to false...
int32_t Mailbox_read(Mbox_Handle handle, uint8_t *buffer, uint32_t size)
Function that reads data from a Mailbox.
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....
Definition: mailbox.h:391
uint32_t regLclToRemMask
Mailbox register.
Definition: mailbox.h:551
Definition: mailbox.h:344
Definition: mailbox.h:246
Definition: mailbox.h:352
Definition: mailbox.h:325
Mailbox_DataTransferMode dataTransferMode
Data transfer mode.
Definition: mailbox.h:456
uint16_t size
Definition: tisci_boardcfg.h:112
int32_t Mailbox_deinit(void)
Function to deinitialize the Mailbox module. .
uint8_t boxEmptyIsrErrCount
Number of empty box ISR received with invalid arg.
Definition: mailbox.h:539
Definition: mailbox.h:372
int32_t Mailbox_readFlush(Mbox_Handle handle)
Function that should be called after application is done reading the message.
int32_t Mailbox_getStats(Mbox_Handle handle, Mailbox_Stats *stats)
Function that collects mailbox driver statistics.
Definition: mailbox.h:253
uint64_t(* Mailbox_VirtToPhyFxn)(const void *virtAddr)
Definition: mailbox.h:403
uint16_t boxEmptyIsrCount
Number of empty box ISR received.
Definition: mailbox.h:527