Mailbox使用参考¶

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	01/30/2024
	Modify the document outline	05/06/2025

1. 概述¶

SGS Mailbox是ARM和CM4之间传递信息的一种机制，允许应用程序在两者间传递自定义的消息，仅支持Iford系列芯片。

图1-1 Mailbox通信框架

关键字说明

ARM

具体指Iford系列芯片non pm domain的ARM CPU。
CM4

具体指Iford系列芯片pm domain的CM4 CPU。
Class

消息类型，不同的class表示不同类型的消息。具体的class id和消息类型的对应关系由应用程序自定义的通信协议决定。

2. 功能描述¶

SGS Mailbox是利用mailbox寄存器和中断实现的ARM和CM4通信方式，通过读写mailbox寄存器和触发、响应中断从而实现简单的全双工通信。Mailbox只是提供了通信的手段，应用程序需要基于此通信手段自行构建核间的通信协议以及解析mailbox传递的内容。

ARM和CM4的一次发送接收交互细节如下图：

发送方向mailbox寄存器写入需要传递的内容并设置标志位，用于后续确认对方是否已经读取传递的内容。
发送方通过中断通知接收方。
接收方影响中断，从mailbox寄存器中读取传递的内容，并清除标志位。
发送方等待标志位被清除。

图2-1 Mailbox通信流程

从应用程序层面上，两个应用程序的交互如下图：

双方各自调用SS_Mailbox_Init进行mailbox的初始化。
双方根据应用程序自定义的通信协议，对所需要使用的mailbox class调用SS_Mailbox_Enable进行初始化。
双方根据应用程序自定义的通信协议，调用SS_Mailbox_SendMsg/SS_Mailbox_RecvMsg对mailbox class进行消息的读写。
通信结束后，双方调用SS_Mailbox_Disable进行mailbox class的反初始化。
通信结束后，双方调用SS_Mailbox_Deinit进行mailbox的反初始化。

图2-2 应用程序通信流程

3. RTOS用法介绍¶

3.1. DRIVER PATH¶

proj/sc/driver/sysdriver/mbx

3.2. CONFIG配置¶

在编译RTOS时，通过make menuconfig进行mailbox driver的编译控制。

BSP Driver Options  --->
    [ ] Support MBX driver

4. LINUX用法介绍¶

4.1. DRIVER PATH¶

drivers/sstar/include/ss_mbx.h
drivers/sstar/mbx/

4.2. CONFIG配置¶

在编译LINUX KERNEL时，通过make menuconfig进行mailbox driver的编译控制。

Device Drivers  --->
    [*] Sgs SoC platform drivers  --->
        < >   Sgs MBX driver

5. 使用介绍¶

以下的sample code non pm domain实现了以下流程：

初始化mailbox。
初始化mailbox class 0~15。
向mailbox class0发送消息，消息内容为6个数字7,6,5,4,3,2。
从mailbox class0读取消息。
反初始化mailbox class 0~15。
反初始化mailbox。

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include "ss_mbx.h"

#define MBXCHKRET(_func_)\
    do{ \
        int ret = 0; \
        ret = _func_; \
        if (ret != 0)\
        { \
            printf("exec function failed, error:%x\n", ret); \
            exit(-1); \
        } \
        else \
        { \
            printf("exec function pass\n"); \
        } \
    } while(0)

#define DIRECT E_SS_MBX_DIRECT_ARM_TO_CM4

typedef enum
{
    E_MBX_CLASS_0 = 0,
    E_MBX_CLASS_1,
    E_MBX_CLASS_2,
    E_MBX_CLASS_3,
    E_MBX_CLASS_4,
    E_MBX_CLASS_5,
    E_MBX_CLASS_6,
    E_MBX_CLASS_7,
    E_MBX_CLASS_8,
    E_MBX_CLASS_9,
    E_MBX_CLASS_10,
    E_MBX_CLASS_11,
    E_MBX_CLASS_12,
    E_MBX_CLASS_13,
    E_MBX_CLASS_14,
    E_MBX_CLASS_15,
    E_MBX_CLASS_MAX,
} E_MBX_CLASS;

int mbx_send(u8 class, SS_Mbx_Msg_t *pstMsg)
{
    pstMsg->eDirect = DIRECT;
    pstMsg->u8MsgClass = class;

    return SS_Mailbox_SendMsg(pstMsg);
}

int mbx_recv(u8 class, SS_Mbx_Msg_t *pstMsg, s32 wait_ms)
{
    return SS_Mailbox_RecvMsg(class, pstMsg, wait_ms);
}

int main(int argc, char *argv[])
{
    SS_Mbx_Msg_t sendmsg = {}, recv_msg;
    int ret = 0;
    u8 class = 0;
    u16 u16Parameters[SS_MBX_MAX_PARAM_SIZE] = {7, 6, 5, 4, 3, 2};

    MBXCHKRET(SS_Mailbox_Init());
    for(class = E_MBX_CLASS_0; class < E_MBX_CLASS_MAX; class++)
    {
        MBXCHKRET(SS_Mailbox_Enable(class));
    }

    sendmsg.u8ParameterCount = SS_MBX_MAX_PARAM_SIZE;
    memcpy(sendmsg.u16Parameters, u16Parameters, sizeof(sendmsg.u16Parameters));
    ret = mbx_send(E_MBX_CLASS_0, &sendmsg);
    printf("send ret:%d.\n", ret);

    ret = mbx_recv(E_MBX_CLASS_0, &recv_msg, 3000);
    printf("recv ret:%d.\n", ret);

    for(class = E_MBX_CLASS_0; class < E_MBX_CLASS_MAX; class++)
    {
        MBXCHKRET(SS_Mailbox_Disable(class));
    }
    MBXCHKRET(SS_Mailbox_Deinit());

    return 0;
}

6. API 参考¶

6.1. API 说明¶

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

6.1.1. SS_Mailbox_Init¶

功能

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

无。
返回值

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

6.1.2. SS_Mailbox_Deinit¶

功能

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

无。
返回值

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

6.1.3. SS_Mailbox_Enable¶

功能

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

参数名称描述输入/输出

u8MsgClass 消息类型输入
返回值

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

6.1.4. SS_Mailbox_Disable¶

功能

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

参数名称描述输入/输出

u8MsgClass 消息类型输入
返回值

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

6.1.5. SS_Mailbox_SendMsg¶

功能

发送mailbox消息。

语法

int SS_Mailbox_SendMsg(SS_Mbx_Msg_t *pstMbxMsg);

形参

参数名称描述输入/输出

pstMbxMsg mailbox消息输入
返回值

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

6.1.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

6.1.7. SS_Mailbox_SetConfig¶

功能

设置mailbox class的配置参数。

语法

int SS_Mailbox_SetConfig(u8 u8MsgClass, SS_Mbx_ClassConfig_t *pstClassConfig);

形参

参数名称描述输入/输出

u8MsgClass 消息类型输入

pstClassConfig mailbox class配置参数输入
返回值

参照SS_Mbx_ClassConfig_t。
依赖
- 头文件：ss_mbx.h
- 库文件：libss_mbx.a / libss_mbx.so
注意
- 仅在SS_Mailbox_Enable调用前设置才生效，不支持动态配置。

6.2. 数据类型说明¶

6.2.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

6.2.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]	参数数组

注意

SS_MBX_MAX_PARAM_SIZE的数值，不同芯片系列会存在差异，请通过下表进行查询。

芯片系列 SS_MBX_MAX_PARAM_SIZE

iford 6

6.2.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_CLASS_CLOSING = 7,
    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	内存不足
E_SS_MBX_RET_CLASS_CLOSING	mailbox class 正在反初始化

6.2.4. SS_Mbx_ClassConfig_t¶

说明

mailbox class 配置结构体。

定义

typedef struct SS_Mbx_ClassConfig_s
{
    u16 u16RecvDepth;
} SS_Mbx_ClassConfig_t;

成员

成员名称 描述

u16RecvDepth class接收消息队列的深度

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

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

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