HEART BEAT USER GUIDE

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	06/18/2024
	Modify the outline.	04/16/2025

1. OVERVIEW¶

InterCoreManager is a communication mechanism between cores implemented on the sstar platform, which facilitates the Heart Beat function. InterCoreManager provides a set of callbacks that allow applications to quickly achieve inter-core communication based on the framework of InterCoreManager.

1.1. MODULE DESCRIPTION¶

InterCoreManager implements the functions required for internuclear Heart Beats, including scanning, responding, status updates, heartbeat generation, and resetting. Depending on the platform it is running on, the underlying communication mechanism of InterCoreManager is also different, including mail box and rpmsg, and the APP does not need to care which communication mechanism is used.

1.2. DEVELOPMENT PROCESS¶

arm linux demo: sdk/verify/sample_code/source/pcupid/intercoremgr, the reference demo contains the call flow of the InterCoreManager linux user space API.

arm linux driver: kernel/drivers/sstar/intercoremgr, this part will compile the user space libss_intercoremgr. Whether the linux driver of InterCoreManager is compiled is determined by SSTAR_INTERCOREMGR.

SStar InterCoreMgr driver
There is no help available for this option.                                                                                                                                                                                         x
  x Symbol: SSTAR_INTERCOREMGR [=y]                                                                                                                                                                                                     x
  x Type  : tristate                                                                                                                                                                                                                    x
  x Defined at drivers/sstar/intercoremgr/Kconfig:1                                                                                                                                                                                     x
  x   Prompt: SStar InterCoreMgr driver
  x   Depends on: SSTAR_DRIVERS [=y]                                                                                                                                                                                                    x
  x   Location:                                                                                                                                                                                                                         x
  x     -> Device Drivers                                                                                                                                                                                                               x
  x       -> Sstar SoC platform drivers (SSTAR_DRIVERS [=y])

arm linux user space header: kernel/drivers/sstar/include/intercoremgr.h

riscv rtos demo: proj/sc/application/intercoremgr, whether InterCoreManager demo is compiled is determined by proj/mak/common/libs_common.mak.

ifeq ($(call FIND_COMPILER_OPTION, CONFIG_INTERCOREMGR_SUPPORT), TRUE)
PRODUCT_SC += intercoremgr_demo
endif

ifeq ($(call FIND_COMPILER_OPTION, CONFIG_INTERCOREMGR_SUPPORT), TRUE)
PRODUCT_SC_LIB_REL += intercoremgr
endif

riscv rtos driver: proj/sc/driver/sysdriver/intercoremgr, whether the rtos driver of InterCoreManager is compiled is determined by CONFIG_INTERCOREMGR_SUPPORT in proj/mak/options_pcupid_riscv_isw.mak.

# Feature_Name = [DRV] Intercoremgr driver
# Description = intercoremgr driver support
# Option_Selection = TRUE, FALSE
CONFIG_INTERCOREMGR_SUPPORT = TRUE

riscv rtos header: proj/sc/driver/sysdriver/intercoremgr/drv/pub/intercoremgr.h

1.2.2. EXAMPLE INTRODUCTION¶

The figure below illustrates a common use case where one CPU actively scans a remote CPU, and both parties establish a heartbeat mechanism. When one party needs to stop sending heartbeat messages and notify the other party of the status update due to an event (such as an upgrade or sleep), it does so accordingly.

2. INTERCOREMANAGER API INTRODUCTION¶

API name	Function
SS_InterCoreMgr_Comm_Init	Initialize InterCoreManager
SS_InterCoreMgr_Comm_DeInit	Destroy InterCoreManager
SS_InterCoreMgr_Scan	Scan the remote CPU
SS_InterCoreMgr_ScanAck	Respond to the scan
SS_InterCoreMgr_Heartbeat_Tick	Send heart beat to the remote end
SS_InterCoreMgr_Heartbeat_Stop	Tell the remote end to stop heart beat detection
SS_InterCoreMgr_Notify_State	Tell the remote end the local status
SS_InterCoreMgr_Query_State	Query the status of the remote end
SS_InterCoreMgr_Reset_Remote	Restart the remote CPU
SS_InterCoreMgr_Reset_Global	Restart SOC

2.1. SS_InterCoreMgr_Comm_Init¶

Description

Initialize InterCoreManager.

Definition

s32 SS_InterCoreMgr_Comm_Init(ReceiverCallback pRecvCb);

Parameter

Parameter name Description Input/Output

pRecvCb Register the callback to InterCoreManager Input
Return value
- 0: Success.
- Non-0: Failure.
Related data type
- ReceiverCallback

2.2. SS_InterCoreMgr_Comm_DeInit¶

Description

Destroy InterCoreManager.
Definition
```
s32 SS_InterCoreMgr_Comm_DeInit(void);
```
Return value
- 0: Success.
- Non-0: Failure.

2.3. SS_InterCoreMgr_Scan¶

Description

Scan the remote CPU.

Definition

s32 SS_InterCoreMgr_Scan(SS_InterCoreMgr_CPU_e peerCpu, u32 scanTimeoutInMs, SS_InterCoreMgr_ScanInfo_t *pScanInfo);

Parameter

Parameter name Description Input/Output

peerCpu Remote CPU type Input

scanTimeoutInMs Scan timeout time Input

pScanInfo Heart beat mechanism establishment information Input
Return value
- 0: Success.
- Non-0: Failure.
Note
- The heartbeat information will be transmitted to the remote CPU only when the remote CPU is scanned. When the scan is successful, the heartbeat packet must be sent to the remote CPU at a heartbeat frequency less than or equal to the heartbeat frequency set in pScanInfo, otherwise it will be judged as a heartbeat timeout by the remote CPU.
Related data type
- SS_InterCoreMgr_CPU_e
- SS_InterCoreMgr_ScanInfo_t

2.4. SS_InterCoreMgr_ScanAck¶

Description

Respond to the scan.

Definition

s32 SS_InterCoreMgr_ScanAck(SS_InterCoreMgr_CPU_e peerCpu, SS_InterCoreMgr_ScanAckInfo_t *pScanAckInfo);

Parameter

Parameter name Description Input/Output

peerCpu Remote CPU type Input

pScanAckInfo Heart beat mechanism establishment information Input
Return value
- 0: Success.
- Non-0: Failure.
Note
- When receiving the scan signal from the remote CPU, this interface needs to be called to respond and reply to the remote end the local heartbeat frequency. After responding, the heartbeat packet needs to be sent to the remote CPU at a heartbeat frequency less than or equal to the heartbeat frequency set in pScanAckInfo, otherwise it will be judged as a heartbeat timeout by the remote CPU.
Related data type
- SS_InterCoreMgr_CPU_e
- SS_InterCoreMgr_ScanAckInfo_t

2.5. SS_InterCoreMgr_Heartbeat_Tick¶

Description

Send heart beat to the remote end.

Definition

s32 SS_InterCoreMgr_Heartbeat_Tick(SS_InterCoreMgr_CPU_e peerCpu, SS_InterCoreMgr_HbInfo_t *pHbInfo);

Parameter

Parameter name Description Input/Output

peerCpu Remote CPU type Input

pHbInfo Heart beat information Input
Return value
- 0: Success.
- Non-0: Failure.
Related data type
- SS_InterCoreMgr_CPU_e
- SS_InterCoreMgr_HbInfo_t

2.6. SS_InterCoreMgr_Heartbeat_Stop¶

Description

Tell the remote end to stop heart beat.

Definition

s32 SS_InterCoreMgr_Heartbeat_Stop(SS_InterCoreMgr_CPU_e peerCpu, SS_InterCoreMgr_HbInfo_t *pHbInfo);

Parameter

Parameter name Description Input/Output

peerCpu Remote CPU type Input

pHbInfo Heart beat information Input
Return value
- 0: Success.
- Non-0: Failure.
Note
- After calling this interface, the remote end will stop performing heartbeat detection on the local end.
Related data type
- SS_InterCoreMgr_CPU_e
- SS_InterCoreMgr_HbInfo_t

2.7. SS_InterCoreMgr_Notify_State¶

Description

Tell the remote end the local status.

Definition

s32 SS_InterCoreMgr_Notify_State(SS_InterCoreMgr_CPU_e peerCpu, SS_InterCoreMgr_stateInfo_t *pStateInfo);

Parameter

Parameter name Description Input/Output

peerCpu Remote CPU type Input

pStateInfo Local status information Input
Return value
- 0: Success.
- Non-0: Failure.
Related data type
- SS_InterCoreMgr_CPU_e
- SS_InterCoreMgr_stateInfo_t

2.8. SS_InterCoreMgr_Query_State¶

Description

Query the remote end local status.

Definition

s32 SS_InterCoreMgr_Query_State(SS_InterCoreMgr_CPU_e peerCpu, SS_InterCoreMgr_queryStateInfo_t *pQueryStateInfo);

Parameter

Parameter name Description Input/Output

peerCpu Remote CPU type Input

pQueryStateInfo Remote status information Input
Return value
- 0: Success.
- Non-0: Failure.
Related data type
- SS_InterCoreMgr_CPU_e
- SS_InterCoreMgr_queryStateInfo_t

2.9. SS_InterCoreMgr_Reset_Remote¶

Description

Restart the remote CPU.

Definition

s32 SS_InterCoreMgr_Reset_Remote(void);

Return value
- 0: Success.
- Non-0: Failure.

2.10. SS_InterCoreMgr_Reset_Global¶

Description

Restart Soc.

Definition

s32 SS_InterCoreMgr_Reset_Global(void);

Return value
- 0: Success.
- Non-0: Failure.

3. DATA STRUCTURE INTRODUCTION¶

Data type	Definition
SS_InterCoreMgr_Action_e	Remote behavior that triggers callback
ReceiverCallback	InterCoreManager responds to callback
SS_InterCoreMgr_CPU_e	Remote CPU type
SS_InterCoreMgr_ScanInfo_t	Heart beat mechanism establishment information on the scanning end
SS_InterCoreMgr_ScanAckInfo_t	Heart beat mechanism establishment information on the scanned end
SS_InterCoreMgr_HbInfo_t	Heart beat information
SS_InterCoreMgr_State_e	Status
SS_InterCoreMgr_stateInfo_t	Status information
SS_InterCoreMgr_queryStateInfo_t	Query the status of the remote end

3.1. SS_InterCoreMgr_Action_e¶

Description

Remote behavior that triggers callback.

Definition

typedef enum
{
    E_COREMGR_DEFAULT = 0,
    E_COREMGR_SCAN,
    E_COREMGR_SCAN_ACK,
    E_COREMGR_HB,
    E_COREMGR_HB_STOP,
    E_COREMGR_STATE_QUERY,
    E_COREMGR_STATE_NOTIFY,
    E_COREMGR_MAX,
} SS_InterCoreMgr_Action_e;

Member

Member name	Description
E_COREMGR_DEFAULT	Reserved and not used temporarily
E_COREMGR_SCAN	Received the scan information of the remote end
E_COREMGR_SCAN_ACK	Received the scan reply information of the remote end
E_COREMGR_HB	Received the heart beat information of the remote end
E_COREMGR_HB_STOP	Received the heartbeat stop information of the remote end
E_COREMGR_STATE_QUERY	Received the local status information from the remote end query
E_COREMGR_STATE_NOTIFY	Received the status information of remote feedback

3.2. ReceiverCallback¶

Description

InterCoreManager responds to callback.

Definition

typedef void (*ReceiverCallback)(SS_InterCoreMgr_Action_e eAction, void *data);

Note
- After registering the callback through SS_InterCoreMgr_Comm_Init, when the remote CPU triggers the corresponding eAction, the callback will be called for processing. Different eAction data returns different data structures. For details, please refer to the provided demo.

3.3. SS_InterCoreMgr_CPU_e¶

Description

Remote CPU type.

Definition

typedef enum
{
    E_COREMGR_CPU_ARM = 0,
    E_COREMGR_CPU_RISCV,
    E_COREMGR_CPU_CM4,
    E_COREMGR_CPU_MAX,
} SS_InterCoreMgr_CPU_e;

Member

Member name Description

E_COREMGR_CPU_ARM Remote CPU is ARM

E_COREMGR_CPU_RISCV Remote CPU is RISCV

E_COREMGR_CPU_CM4 Remote CPU is CM4

3.4. SS_InterCoreMgr_ScanInfo_t¶

Description

Heart beat mechanism establishment information on the scanning end.

Definition

typedef struct SS_InterCoreMgr_ScanInfo_s
{
    SS_InterCoreMgr_CPU_e scanCPU;
    u16                   hbPeriodInMs;
    u32                   timestampInMs;
} SS_InterCoreMgr_ScanInfo_t;

3.5. SS_InterCoreMgr_ScanAckInfo_t¶

Description

Heart beat mechanism establishment information on the scanned end.

Definition

typedef struct SS_InterCoreMgr_ScanAckInfo_s
{
    SS_InterCoreMgr_CPU_e ackCPU;
    u16                   hbPeriodInMs;
    u32                   timestampInMs;
} SS_InterCoreMgr_ScanAckInfo_t;

3.6. SS_InterCoreMgr_HbInfo_t¶

Description

Heart beat information。

Definition

typedef struct SS_InterCoreMgr_HbInfo_s
{
    SS_InterCoreMgr_CPU_e hbCPU;
    u32                   hbSequenceNum;
    u32                   timestampInMs;
} SS_InterCoreMgr_HbInfo_t;

3.7. SS_InterCoreMgr_State_e¶

Description

Status.

Definition

typedef enum
{
    E_COREMGR_STATE_Normal = 0,
    E_COREMGR_STATE_STR,
    E_COREMGR_STATE_CHARGE,
    E_COREMGR_STATE_MAX,
} SS_InterCoreMgr_State_e;

Member

Member name Description

E_COREMGR_STATE_Normal Normal status

E_COREMGR_STATE_STR Suspend status

E_COREMGR_STATE_CHARGE Charge status

3.8. SS_InterCoreMgr_stateInfo_t¶

Description

Status information.

Definition

typedef struct SS_COREMGR_stateInfo_s
{
    SS_InterCoreMgr_CPU_e   notifyCpu;
    SS_InterCoreMgr_State_e newState;
    u32                     timestampInMs;
} SS_InterCoreMgr_stateInfo_t;

Parameter name	Description	Input/Output
peerCpu	Remote CPU type	Input
scanTimeoutInMs	Scan timeout time	Input
pScanInfo	Heart beat mechanism establishment information	Input

Member name	Description
E_COREMGR_CPU_ARM	Remote CPU is ARM
E_COREMGR_CPU_RISCV	Remote CPU is RISCV
E_COREMGR_CPU_CM4	Remote CPU is CM4

Member name	Description
E_COREMGR_STATE_Normal	Normal status
E_COREMGR_STATE_STR	Suspend status
E_COREMGR_STATE_CHARGE	Charge status

HEART BEAT USER GUIDE

REVISION HISTORY¶

1. OVERVIEW¶

1.1. MODULE DESCRIPTION¶

1.2. DEVELOPMENT PROCESS¶

1.2.1. INTERCOREMANAGER RELATED SOURCE CODE¶

1.2.2. EXAMPLE INTRODUCTION¶

2. INTERCOREMANAGER API INTRODUCTION¶

2.1. SS_InterCoreMgr_Comm_Init¶

2.2. SS_InterCoreMgr_Comm_DeInit¶

2.3. SS_InterCoreMgr_Scan¶

2.4. SS_InterCoreMgr_ScanAck¶

2.5. SS_InterCoreMgr_Heartbeat_Tick¶

2.6. SS_InterCoreMgr_Heartbeat_Stop¶

2.7. SS_InterCoreMgr_Notify_State¶

2.8. SS_InterCoreMgr_Query_State¶

2.9. SS_InterCoreMgr_Reset_Remote¶

2.10. SS_InterCoreMgr_Reset_Global¶

3. DATA STRUCTURE INTRODUCTION¶

3.1. SS_InterCoreMgr_Action_e¶

3.2. ReceiverCallback¶

3.3. SS_InterCoreMgr_CPU_e¶

3.4. SS_InterCoreMgr_ScanInfo_t¶

3.5. SS_InterCoreMgr_ScanAckInfo_t¶

3.6. SS_InterCoreMgr_HbInfo_t¶

3.7. SS_InterCoreMgr_State_e¶

3.8. SS_InterCoreMgr_stateInfo_t¶