Mailbox User Guide

---

REVISION HISTORY

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

---

1. Overview

SGS Mailbox is a mechanism for transmitting information between ARM and CM4, allowing applications to transmit customized messages between ARM and CM4, and it is only supported by the Iford series chips.

Figure 1-1 Mailbox Communication Framework

Keyword Description

• ARM

  Specifically refers to the ARM CPU in the non-PM domain of the Iford series chips.

• CM4

  Specifically refers to the CM4 CPU in the PM domain of the Iford series chips.

• Class

  Message type; different classes indicate different types of messages. The specific correspondence between class IDs and message types is determined by the communication protocol customized by the application.

---

2. Function Description

SGS Mailbox is a communication method between ARM and CM4 realized through the mailbox register and interrupts. It enables simple full-duplex communication by reading and writing to the mailbox register and triggering and responding to interrupts. The mailbox merely provides a means of communication; the application program must construct its own communication protocol and parse the content transmitted via the mailbox based on this communication method.

The details of a send-receive interaction between ARM and CM4 are as follows:

1. The sender writes the content to be transmitted into the mailbox register and sets a flag to confirm later whether the receiver has read the transmitted content.

2. The sender notifies the receiver via an interrupt.

3. The receiver acknowledges the interrupt, reads the transmitted content from the mailbox register, and clears the flag.

4. The sender waits for the flag to be cleared.

Figure 2-1 Mailbox Communication Process

From the application perspective, the interaction between the two applications is illustrated as follows:

1. Both parties invoke SS_Mailbox_Init to initialize their respective mailboxes.

2. Based on the custom communication protocol defined by the application, both parties call SS_Mailbox_Enable to initialize the necessary mailbox classes.

3. Following the custom communication protocol, both parties use SS_Mailbox_SendMsg/SS_Mailbox_RecvMsg to perform message read and write operations on the mailbox classes.

4. After the communication concludes, both parties invoke SS_Mailbox_Disable to deinitialize the mailbox classes.

5. Upon the conclusion of communication, both parties call SS_Mailbox_Deinit to deinitialize the mailboxes.

Figure 2-2 Application Communication Process

---

3. Introduction to the Usage of RTOS

3.1. DRIVER PATH

proj/sc/driver/sysdriver/mbx

3.2. Configuration

When compiling the RTOS, control over the mailbox driver compilation is managed through make menuconfig.

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

---

4. Introduction to the Usage of LINUX

4.1. DRIVER PATH

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

4.2. Configuration

When compiling the LINUX KERNEL, control over the mailbox driver compilation is managed through make menuconfig.

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

---

5. User Introduction

The following sample code implements the process in a non-PM domain:

1. Initialize the mailbox.

2. Initialize mailbox classes 0 to 15.

3. Send a message to mailbox class 0, with the message content being the six numbers 7, 6, 5, 4, 3, 2.

4. Read the message from mailbox class 0.

5. Deinitialize mailbox classes 0 to 15.

6. Deinitialize the 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 Reference

6.1. API Description

API name	Function
SS_Mailbox_Init	Initialize mailbox function
SS_Mailbox_Deinit	Deinitialize mailbox function
SS_Mailbox_Enable	Enable the selected message type
SS_Mailbox_Disable	Disable the selected message type
SS_Mailbox_SendMsg	Send mailbox message
SS_Mailbox_RecvMsg	Receive mailbox messages of the specified type
SS_Mailbox_SetConfig	Set the configuration parameters for the mailbox class.

---

6.1.1. SS_Mailbox_Init

• Function

  Initialize the mailbox function.

• Syntax

  int SS_Mailbox_Init(void);
  

• Parameters

  None.

• Return value

  Refer to SS_Mbx_Ret_e

• Requirement

  • Header file: ss_mbx.h

  • Library files: libss_mbx.a/libss_mbx.so

---

6.1.2. SS_Mailbox_Deinit

• Function

  Deinitialize mailbox function.

• Syntax

  int SS_Mailbox_Deinit(void);
  

• Parameters

  None.

• Return value

  Refer to SS_Mbx_Ret_e

• Requirement

  • Header file: ss_mbx.h

  • Library files: libss_mbx.a/libss_mbx.so

---

6.1.3. SS_Mailbox_Enable

• Function

  Enable selected message types.

• Syntax

  int SS_Mailbox_Enable(u8 u8MsgClass);
  

• Parameters

  Parameter name	Description	Input/Output
  u8MsgClass	Message Type	Input

• Return value

  Refer to SS_Mbx_Ret_e

• Requirement

  • Header file: ss_mbx.h

  • Library files: libss_mbx.a/libss_mbx.so

---

6.1.4. SS_Mailbox_Disable

• Function

  Disable the selected message type.

• Syntax

  int SS_Mailbox_Disable(u8 u8MsgClass);
  

• Parameters

  Parameter name	Description	Input/Output
  u8MsgClass	Message Type	Input

• Return value

  Refer to SS_Mbx_Ret_e

• Requirement

  • Header file: ss_mbx.h

  • Library files: libss_mbx.a/libss_mbx.so

---

6.1.5. SS_Mailbox_SendMsg

• Function

  Send mailbox message.

• Syntax

  int SS_Mailbox_SendMsg(SS_Mbx_Msg_t *pstMbxMsg);
  

• Parameters

  Parameter name	Description	Input/Output
  pstMbxMsg	Mailbox message	input

• Return value

  Refer to SS_Mbx_Ret_e.

• Requirement

  • Header file: ss_mbx.h

  • Library files: libss_mbx.a/libss_mbx.so

---

6.1.6. SS_Mailbox_RecvMsg

• Function

  Receive mailbox messages of the specified type.

• Syntax

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

• Parameters

  Parameter name	Description	Input/Output
  u8MsgClass	Message Type	Input
  pstMbxMsg	Mailbox message	Output
  s32WaitMs	Waiting time	When >=0, it is the specific time; when <0, it is always waiting

• Return value

  Refer to SS_Mbx_Ret_e.

• Requirement

  • Header file: ss_mbx.h

  • Library files: libss_mbx.a/libss_mbx.so

---

6.1.7. SS_Mailbox_SetConfig

• Function

  Set the configuration parameters for the mailbox class.

• Syntax

  int SS_Mailbox_SetConfig(u8 u8MsgClass, SS_Mbx_ClassConfig_t *pstClassConfig);
  

• Parameters

  Parameter name	Description	Input/Output
  u8MsgClass	Message Type	Input
  pstClassConfig	Configuration parameters of the mailbox class.	Input

• Return value

  Refer to SS_Mbx_Ret_e.

• Requirement

  • Header file: ss_mbx.h

  • Library files: libss_mbx.a/libss_mbx.so

• Note

  This setting takes effect only when configured before the SS_Mailbox_Enable call and does not support dynamic configuration.

---

6.2. Data Type Description

---

The relevant data types are defined as follows:

Data Type	Definition
SS_Mbx_Direct_e	Define the sending direction of mailbox
SS_Mbx_Msg_t	Mailbox message structure
SS_Mbx_Ret_e	Mailbox interface return value enumeration
SS_Mbx_ClassConfig_t	Mailbox class configuration structure.

---

6.2.1. SS_Mbx_Direct_e

• Description

  Define the sending direction of mailbox.

• Definition

  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;
  

• Member

  Member Name	Description
  E_SS_MBX_DIRECT_CM4_TO_ARM	CM4 sent to ARM
  E_SS_MBX_DIRECT_ARM_TO_CM4	ARM sent to CM4

---

6.2.2. SS_Mbx_Msg_t

• Description

  Mailbox message structure.

• Definition

  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;
  

• Member

  Member Name	Description
  eDirect	Send Directions
  u8Ctrl	Control byte, user does not need to fill in
  u8Status	Status byte, user does not need to fill in
  u8MsgClass	Message class
  u8ParameterCount	Parameter count
  u16Parameters[SS_MBX_MAX_PARAM_SIZE]	Parameter array

---

6.2.3. SS_Mbx_Ret_e

• Description

  The mailbox interface return value enumeration.

• Definition

  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;
  

• Member

  Member Name	Description
  E_SS_MBX_RET_OK	Success
  E_SS_MBX_RET_FAIL	Mailbox internal error
  E_SS_MBX_RET_NOT_INIT	Not initialized
  E_SS_MBX_RET_NOT_ENABLE	The selected message type is not enabled
  E_SS_MBX_RET_INVAILD_PARAM	Illegal parameter
  E_SS_MBX_RET_TIME_OUT	Message timeout
  E_SS_MBX_RET_NO_MEM	Out of memory

---

6.2.4. SS_Mbx_ClassConfig_t

• Description

  Mailbox class configuration structure.

• Definition

  typedef struct SS_Mbx_ClassConfig_s
  {
      u16 u16RecvDepth;
  } SS_Mbx_ClassConfig_t;
  

• Member

  Member Name	Description
  u16RecvDepth	The depth of the message queue received by the mailbox class.