SigmaStar Mailbox使用参考

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	01/30/2024

1. 概述¶

SigmaStar Mailbox是多核之间传递信息的一种机制，允许使用者在多核之间传递自定义的消息。

2. API 参考¶

API名	功能
SS_Mailbox_Init	初始化mailbox功能
SS_Mailbox_Deinit	反初始化mailbox功能
SS_Mailbox_Enable	使能选定的消息类型
SS_Mailbox_Disable	关闭选定的消息类型
SS_Mailbox_SendMsg	发送mailbox消息
SS_Mailbox_RecvMsg	接收指定类型的mailbox消息

2.1. SS_Mailbox_Init¶

功能

初始化mailbox功能。
语法
```
int SS_Mailbox_Init(void);
```
形参

无。
返回值

参照SS_Mbx_Ret_e
依赖
- 头文件：ss_mbx.h
- 库文件：libss_mbx.a / libss_mbx.so

举例

mailbox使用范例：

SS_Mbx_Msg_t stMsg = {0};
u8 class = 0;

stMsg.eDirect          = E_SS_MBX_DIRECT_ARM_TO_CM4;
stMsg.u8MsgClass       = class;
stMsg.u8ParameterCount = 1;
stMsg.u16Parameters[0] = 1;

SS_Mailbox_Init();
SS_Mailbox_Enable(class);
SS_Mailbox_SendMsg(&stMsg, 500);
SS_Mailbox_RecvMsg(class, &stMsg, 500);
SS_Mailbox_Disable(class);
SS_Mailbox_Deinit();

2.2. SS_Mailbox_Deinit¶

功能

反初始化mailbox功能。
语法
```
int SS_Mailbox_Deinit(void);
```
形参

无。
返回值

参照SS_Mbx_Ret_e
依赖
- 头文件：ss_mbx.h
- 库文件：libss_mbx.a / libss_mbx.so
举例

参见SS_Mailbox_Init 举例。

2.3. SS_Mailbox_Enable¶

功能

使能选定的消息类型。
语法
```
int SS_Mailbox_Enable(u8 u8MsgClass);
```
形参

参数名称描述输入/输出

u8MsgClass 消息类型输入
返回值

参照SS_Mbx_Ret_e
依赖
- 头文件：ss_mbx.h
- 库文件：libss_mbx.a / libss_mbx.so
举例

参见SS_Mailbox_Init 举例。

2.4. SS_Mailbox_Disable¶

功能

关闭选定的消息类型。
语法
```
int SS_Mailbox_Disable(u8 u8MsgClass);
```
形参

参数名称描述输入/输出

u8MsgClass 消息类型输入
返回值

参照SS_Mbx_Ret_e
依赖
- 头文件：ss_mbx.h
- 库文件：libss_mbx.a / libss_mbx.so
举例

参见SS_Mailbox_Init 举例。

2.5. SS_Mailbox_SendMsg¶

功能

发送mailbox消息。

语法

int SS_Mailbox_SendMsg(SS_Mbx_Msg_t *pstMbxMsg, s32 s32WaitMs);

形参

参数名称描述输入/输出

pstMbxMsg mailbox消息输入

s32WaitMs 等待时间 >=0时为具体时间；<0时为一直等待
返回值

参照SS_Mbx_Ret_e。
依赖
- 头文件：ss_mbx.h
- 库文件：libss_mbx.a / libss_mbx.so
举例

参见SS_Mailbox_Init 举例。

2.6. SS_Mailbox_RecvMsg¶

功能

接收指定类型的mailbox消息。

语法

int SS_Mailbox_RecvMsg(u8 u8MsgClass, SS_Mbx_Msg_t *pstMbxMsg, s32 s32WaitMs);

形参

参数名称描述输入/输出

u8MsgClass 消息类型输入

pstMbxMsg mailbox消息输出

s32WaitMs 等待时间 >=0时为具体时间；<0时为一直等待
返回值

参照SS_Mbx_Ret_e。
依赖
- 头文件：ss_mbx.h
- 库文件：libss_mbx.a / libss_mbx.so
举例

参见SS_Mailbox_Init 举例。

3. 数据类型¶

3.1. SS_Mbx_Direct_e¶

说明

定义mailbox发送的方向。

定义

typedef enum
{
    E_SS_MBX_DIRECT_CM4_TO_ARM,
    E_SS_MBX_DIRECT_ARM_TO_CM4,
    E_SS_MBX_DIRECT_MAX,
} SS_Mbx_Direct_e;

成员

成员名称 描述

E_SS_MBX_DIRECT_CM4_TO_ARM CM4发送到ARM

E_SS_MBX_DIRECT_ARM_TO_CM4 ARM发送到CM4

3.2. SS_Mbx_Msg_t¶

说明

mailbox消息结构体。

定义

typedef struct SS_Mbx_Msg_s
{
    SS_Mbx_Direct_e eDirect;
    u8              u8Ctrl;
    u8              u8Status;
    u8              u8MsgClass;
    u8              u8ParameterCount;
    u16             u16Parameters[SS_MBX_MAX_PARAM_SIZE];
} SS_Mbx_Msg_t;

成员

成员名称	描述
eDirect	发送方向
u8Ctrl	控制字节，用户无需填写
u8Status	状态字节，用户无需填写
u8MsgClass	消息类型
u8ParameterCount	参数个数
u16Parameters[SS_MBX_MAX_PARAM_SIZE]	参数数组

3.3. SS_Mbx_Ret_e¶

说明

mailbox接口返回值枚举。

定义

typedef enum
{
    E_SS_MBX_RET_OK            = 0,
    E_SS_MBX_RET_FAIL          = 1,
    E_SS_MBX_RET_NOT_INIT      = 2,
    E_SS_MBX_RET_NOT_ENABLE    = 3,
    E_SS_MBX_RET_INVAILD_PARAM = 4,
    E_SS_MBX_RET_TIME_OUT      = 5,
    E_SS_MBX_RET_NO_MEM        = 6,
    E_SS_MBX_RET_MAX,
} SS_Mbx_Ret_e;

成员

成员名称	描述
E_SS_MBX_RET_OK	成功
E_SS_MBX_RET_FAIL	mailbox内部错误
E_SS_MBX_RET_NOT_INIT	未初始化
E_SS_MBX_RET_NOT_ENABLE	选定的消息类型未使能
E_SS_MBX_RET_INVAILD_PARAM	非法参数
E_SS_MBX_RET_TIME_OUT	消息超时
E_SS_MBX_RET_NO_MEM	内存不足

参数名称	描述	输入/输出
pstMbxMsg	mailbox消息	输入
s32WaitMs	等待时间	>=0时为具体时间；<0时为一直等待

数据类型	定义
SS_Mbx_Direct_e	定义mailbox发送的方向
SS_Mbx_Msg_t	mailbox消息结构体
SS_Mbx_Ret_e	mailbox接口返回值枚举

成员名称	描述
E_SS_MBX_DIRECT_CM4_TO_ARM	CM4发送到ARM
E_SS_MBX_DIRECT_ARM_TO_CM4	ARM发送到CM4