4.7. CDD_IPC Module

4.7.1. Acronyms and Definitions

Abbreviation/Term	Explanation
AUTOSAR	Automotive Open System Architecture
BSW	Basic Software
MCAL	Micro Controller Abstraction Layer
API	Application Programming Interface
DET	Default Error Tracer
IPC	Inter Process Communication
SW	Software
MCU	Micro Controller Unit
OS	Operating System
CDD	Complex Device Driver

4.7.2. Introduction

This document describes the functionality, API and configuration of the AUTOSAR BSW module Complex Device driver for IPC on AM263Px device.


Supported AUTOSAR Release	4.3.1
Supported Configuration Variants	Post Build
Vendor ID	CDD_IPC_VENDOR_ID (44)
Module ID	CDD_IPC_MODULE_ID (255)
Supported Platform	AM263Px

4.7.3. Functional Overview

The main tasks of Complex Device Driver for IPC are the following:

Initialization of the mailbox driver
Simplifies reading and writing to the mailbox peripheral.

4.7.3.1. Complex Device Driver Architecture

The following figure shows where the Complex device driver is located in the AUTOSAR architecture.

4.7.3.2. Initialization

The initialization covers the following steps:

Initialize the mailbox peripheral.
Cdd_Ipc_Init should be called only once during initialization.
No other CDD API can be invoked until this API is called.

4.7.4. Hardware Features

4.7.4.1. Supported Features

Open/Close mailbox instance
Send/Receive both Notify and RpMsg messages
RpMsg Callback functionality supported

4.7.4.2. Not supported Features

Multiple mailbox channels between the cores
Applications are validated only for the R50_0 core

4.7.5. Source files

Description of static files is provided below:

📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂Ipc
┃ ┃ ┣ 📂include
┃ ┃ ┃ ┣ 📜Cdd_Ipc.h : Contains interface header for Complex device driver for IPC
┃ ┃ ┃ ┣ 📜Cdd_Ipc_Irq.h : contains ISR function declaration for Complex Device Driver
┃ ┃ ┃ ┣ 📜ipc_notify_lld_utils.h : Contains Internal functions declaration
┃ ┃ ┃ ┣ 📜ipc_notify_v1_lld.h : Contains Internal functions declaration
┃ ┃ ┃ ┣ 📜ipc_notify_v1_mailbox.h : Contains Internal functions declaration
┃ ┃ ┃ ┣ 📜ipc_rpmsg_linux_resource_table.h : Contains Internal functions declaration
┃ ┃ ┃ ┣ 📜ipc_rpmsg_lld.h : Contains Internal functions declaration
┃ ┃ ┃ ┣ 📜ipc_rpmsg_lld_priv.h : Contains Internal functions declaration
┃ ┃ ┃ ┗ 📜ipc_rpmsg_lld_queue.h : Contains Internal functions declaration
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📜Cdd_Ipc.c : Contains function definitions for the Complex device driver for IPC and helper functions
┃ ┃ ┃ ┣ 📜Cdd_Ipc_Irq.c : Contains ISR function definitions for Complex Device Driver
┃ ┃ ┃ ┣ 📜ipc_notify_lld_utils.c : Contains Internal functions definition
┃ ┃ ┃ ┣ 📜ipc_notify_v1_lld.c : Contains Internal functions definition
┃ ┃ ┃ ┣ 📜ipc_rpmsg_lld.c : Contains Internal functions definition
┃ ┃ ┃ ┗ 📜ipc_rpmsg_lld_vring.c : Contains Internal functions definition
┃ ┃ ┣ 📂V0
┃ ┃ ┃ ┣ 📜hw_mailbox.h : Contains Internal functions definition
┃ ┃ ┃ ┣ 📜ipc_notify_v1_cfg_lld.c : Contains Internal functions definition
┃ ┃ ┃ ┗ 📜ipc_notify_v1_cfg_lld.h : Contains Internal functions definition
┃ ┃ ┗ 📜Makefile
┣ 📂mcal_config
┣ 📂mcal_docs
┗ 📜README.txt

The below diagram shows the files structure for the CDD driver.

Fig. 4.40 CDD header file include structure

4.7.6. Module requirements

4.7.6.1. Memory Mapping

Memory Mapping Sections	CDD_CODE	CDD_CODE_ISR	CDD_VAR_NO_INIT	CDD_VAR_ZERO_INIT
CDD_IPC_START_SEC_VAR_INIT_UNSPECIFIED (.bss)				x
CDD_IPC_STOP_SEC_VAR_INIT_UNSPECIFIED				x
CDD_IPC_START_SEC_CODE_APPL (.text)		x
CDD_IPC_STOP_SEC_CODE_APPL		x
CDD_IPC_START_SEC_VAR_UNSPECIFIED (.data)			x
CDD_IPC_STOP_SEC_VAR_UNSPECIFIED			x
CDD_IPC_START_SEC_CODE(.rodata)	x
CDD_IPC_START_SEC_CODE	x

4.7.6.2. Scheduling

4.7.6.2.1. SchM

Will be added in future releases:

4.7.6.2.2. Critical Sections

Will be added in future releases:

4.7.6.3. Error handling

4.7.6.3.1. Development Error Reporting

Development errors are reported to the DET using the service Det_ReportError().

4.7.6.4. Error codes

4.7.6.4.1. Development Errors

The errors reported to DET and DEM are described in the following table

Type of Error	Related Error code	Value (Hex)
Error code indicating the IPC is uninitialized	CDD_IPC_E_UNINIT	0x01
Error code indicating register client failed event	CDD_IPC_E_REGISTER_CLIENT_FAILED	0x02
Error code indicating IPC Initialization Failed	CDD_IPC_E_INIT_FAILED	0x03
Error code indicating IPC Deinitialization Failed	CDD_IPC_E_DEINIT_FAILED	0x04
Error code indicating invalid parameter	CDD_IPC_E_PARAM_POINTER	0x05
Error code indicating IPC already initialized	CDD_IPC_E_ALREADY_INITIALIZED	0x06
Error code indicating Service called with wrong param	CDD_IPC_E_PARAM_VALUE	0x07
Error code indicating Service called with invalid length	CDD_IPC_E_PARAM_LENGTH	0x08
Error code indicating invalid IPC Channel	CDD_IPC_E_INVALID_CHANNEL	0x09
Error code indicating invalid IPC configuration	CDD_IPC_E_INVALID_CONFIG	0x0A
Error code indicating IPC Write Failed configuration	CDD_IPC_E_WRITE_FAILED	0x0B
Error code indicating unregister client failed event	CDD_IPC_E_UNREGISTER_CLIENT_FAILED	0x0C
Error code indicating construct failed event	CDD_IPC_E_CONSTRUCT_FAILED	0x0D
Error code indicating RpMsg Write failed event	CDD_IPC_E_RPMSG_WRITE_FAILED	0x0E
Error code indicating Rpmsg read failed event	CDD_IPC_E_RPMSG_READ_FAILED	0x0F
Error code indicating destruct failed event	CDD_IPC_E_DESTRUCT_FAILED	0x10

4.7.6.4.2. Parameter Checking

AUTOSAR requires that API functions check the validity of their parameters. These checks are for development error reporting and can be en-/disabled via the parameter CDD_IPC_DEV_ERROR_DETECT. The following table shows which parameter checks are performed on which services:

Services	CDD_IPC_E_UNINIT	CDD_IPC_E_REGISTER_CLIENT_FAILED	CDD_IPC_E_UNREGISTER_CLIENT_FAILED	CDD_IPC_E_PARAM_POINTER	CDD_IPC_E_ALREADY_INITIALIZED	CDD_IPC_E_PARAM_VALUE	CDD_IPC_E_WRITE_FAILED	CDD_IPC_E_CONSTRUCT_FAILED	CDD_IPC_E_RPMSG_WRITE_FAILED	CDD_IPC_E_RPMSG_READ_FAILED
Cdd_Ipc_Init				x	x
Cdd_Ipc_DeInit	x			x
Cdd_Ipc_Notify_RegisterClient	x	x		x
Cdd_Ipc_Notify_UnregisterClient	x		x			x
Cdd_Ipc_Notify_Write	x					x	x	x
Cdd_Ipc_Construct	x					x
Cdd_Ipc_Destruct	x					x
Cdd_Ipc_RpMsg_SendMsg	x					x			x
Cdd_Ipc_RpMsg_SendMsg	x					x				x

4.7.7. Used resources

4.7.7.1. Interrupt Handling

Will be updated in future release:

4.7.8. Integration description

4.7.8.1. Dependent modules

4.7.8.1.1. OSEK/AUTOSAR OS (Optional)

An operating system can be used for task scheduling, interrupt handling, global suspend and restore of interrupts and creating of the Interrupt Vector Table. The CDD module may use OSEK/AUTOSAR OS to suspend and restore global interrupts.

4.7.8.1.2. DET (Optional)

The module CDD depends on the DET (by default) in order to report development errors. The mailbox operations like write, read are protected by a critical section.

Service ID	Service
0x01	Cdd_Ipc_Init
0x02	Cdd_IpcGetVersionInfo
0x03	Cdd_Ipc_RpMsg_RecvMsg
0x04	Cdd_Ipc_RpMsg_SendMsg
0x05	Cdd_Ipc_Notify_RegisterClient
0x06	Cdd_Ipc_Construct
0x07	Cdd_Ipc_DeInit
0x09	Cdd_Ipc_Notify_UnregisterClient
0x0A	Cdd_Ipc_Destruct

4.7.8.1.3. Services used by Complex device Driver

The CDD does not provide any call back functions.

4.7.8.1.4. Notifications

At its configurable interfaces the CDD defines notifications that can be mapped to callback functions provided by other modules. The mapping is not statically defined by the CDD but can be performed at configuration time. The function prototypes that can be used for the configuration have to match the appropriate function prototype signatures, which are described in the following.

Cdd_Ipc_notify_msgHandler: This is defined in the Cdd_Ipc_notify_app.c for reference.

4.7.8.2. Multi-core and Resource allocator

Will be updated in future release:

4.7.9. Configuration

4.7.9.1. Configuration Parameter

Texas Instruments Parameters	Description	Default Value
CddIpcLocalCoreId	This param contains the local coreId on which the IPC instance is running	CDD_IPC_R5FSS0_0_ID
CddIpcRemoteCoreIdIndex	The cores that are participating the IPC message exchange (Exclude the local core from these)	CDD_IPC_R5FSS0_0_ID
CddIpcSafeIpcCoresEnable	Switch to enable Safe Ipc between local and remote core	False
CddIpcLocalEndPt	This parameter is used to register a local call back especially for receiving or sending a RPMsg message	12
CddIpcRecvCallBack	Function pointer to RPMSG callback function	NULL
CddIpcrecvCallbackArguments	Function Pointer to receive callback function’s arguments	NULL
CddIpcrecvNotifyCallback	Function pointer to IPC notify message Callback function. User can pass a pointer to a custom defined arguments structure and the callback passes this pointer when a notify interrupt is received	NULL
CddIpcrecvNotifyCallbackArguments	Pointer to IPC notify message callback function’s arguments	NULL
CddVersionInfoApi	Switches the Cdd_IpcGetVersionInfo function ON or OFF	True
CddDeinitApi	Switches the Cdd_IpcDeinit function ON or OFF	True
CddIpcWriteApi	Switches the Cdd_IpcWrite function ON or OFF	True
CddIpcReadApi	Switches the Cdd_IpcRead function ON or OFF	True
CddIpcRpMsgEnable	Switch to enable RpMsg API’s to be enabled or not	True
CddIpcRecvCallBackEnable	Switch to enable RPMsg Recv Callback (This is different from Notify Callback)	True
CddIpcRecvNotifyCallbackEnable	Switch to enable RPMsg Notify message Recv Callback	False
CddRegisterReadBackApi	Switches the Cdd_IpcRegisterReadBack function ON or OFF	True
CddDevErrorDetect	Switches the Development Error Detection and Notification ON or OFF	True
CddIpcSafeIpcEnable	Switch to enable Safe Ipc to be enabled or not	False
CddIpcCrcEnable	Switch to enable Crc to be enabled or not	False
CddIpcCrcHookFunc	Hook function in application for Crc Calculation	NULL
CddIrqType	Type of Isr function: void functionname(void) CAT1 : interrupt void func(void) CAT2 : ISR(func)	CDD_IPC_ISR_VOID
CddIpcTimeout	Timeout value for send/receive/wait API’s. Unit is in clock ticks	2000000
CddIpcNumOfBuffers	This parameter indicates the number of buffers for sending RPMsg	8
CddIpcMaxBufferSize	This parameter indicates the Max size of each buffer. Note that the actual size available is 16 bytes less than the above chosen value (16 bytes are used for the header in RPMsg)	128
CddDefaultOSCounterId	Default Os Counter Id if node reference to OsCounter ref CddOsCounterRef is not set	0
CddOsCounterRef	This parameter contains a reference to the OsCounter, which is used by the GPT driver	ASPathDataOfSchema:/AUTOSAR /EcucDefs/Os/OsCounter
CddDeviceVariant	Device variant AM263Px	AM263Px

Note: In case of CddIpcRecvCallBack , when RPMsg arrive then that is invoked along with the data in the VRING buffer.So now if the msg size is less then what we are transferring between cores then we will send the echo msg back to the core from which we are receiving and will do UNLOCK of core only if complete msg transfer happens.So by this way we are acknowledging the remote core.

For details of configuration supported refer the MCAL_Configurator_UserGuide.pdf present in mcal_config/docs folder

4.7.10. Examples

CDD example application demonstrating the Complex device driver features 2 different examples namely ipc_notify_app and ipc_rpmsg_app.

4.7.10.1. Ipc_notify_app_working

This application is low payload, low latency message type where user will be able to send a maximum of 28bits of data as the payload. The first 4 bits are used internally by the driver for the client ID. Notify app sends 1000000, to all the other 3 cores and waits for all of them to echo back. To make the example work with lesser cores, edit the following parameters in the example.

#define MAX 4 To the number of cores user needs to reduce.
uint32 gRemoteCoreId[]; Enable only the cores that are required.
uint32 gIpcTransferMutex[MAX] Remove the extra Lock variables (These can be replced with any kind of mutex or semaphore implementation at the user End).
In addition to these please also ensure the Cdd_Ipc_PBCfg.c has the proper cores configured from the XDM file.

The same changes stand valid for the rpmsg_echo_app as well.

4.7.10.2. Ipc_rpmsg_app working

RpMsg application uses Vrings as the medium to send larger data whose size and buffer depth can be configured using the parameters CDD_IPC_NUM_OF_BUFFERS and CDD_IPC_MAX_BUFFER_SIZE.
The application exchanges 100000 messages, the payload data is integer value where it gets incremented on every echo back from each core. In order to change the data from the integer to other data i.e., String or characters for command use-cases please change the following line.

snprintf(msgBuf, MAX_MSG_SIZE-1, "%d", msg);

to

snprintf(msgBuf, MAX_MSG_SIZE-1, "%s", Your String Data);

The notify application is present under the path <MCAL_ROOT>/examples/Ipc/Ipc_app_notify. This application can be built from the build folder by giving "gmake -s ipc_notify_app".

The rpmsg application is present under the path <MCAL_ROOT>/examples/Ipc/Ipc_app_rpmsg. This application can be built from the build folder by giving "gmake -s ipc_rpmsg_app".

4.7.10.2.1. Sample Log

Will be updated in future release:

4.7.10.3. Changing and Compiling SDK examples

Examples to import from SDK to validate the CDD_IPC example,

Use all the other cores except R50-0 (this is where CDD_IPC app will be run), the path to the examples inside MCU+SDK directory
$(MCU_PLUS_SDK_PATH)\examples\drivers\ipc\ipc_notify_echo\am263px-cc
$(MCU_PLUS_SDK_PATH) \examples\drivers\ipc\ipc_rpmsg_echo\am263px-cc

4.7.10.3.1. Notify App Sample Output

4.7.10.3.2. RPMsg App Sample Output

4.7.10.4. Sample log

Ipc Notify:

CDD_IPC_NOTIFY_APP: Sample IPC Application started!
CDD_IPC_NOTIFY_APP: Sync All Completed
CDD_IPC_NOTIFY_APP: Message exchange started by main core
CDD_IPC_NOTIFY_APP: All echoed messages received by main core from 3 remote cores !!!
CDD_IPC_NOTIFY_APP: Messages sent to each core = 1000000
CDD_IPC_NOTIFY_APP: Number of remote cores = 3
All tests have passed

Ipc Rpmsg:

CDD_IPC_RPMSG_APP: Sample IPC Application started!
CDD_IPC_RPMSG_APP: Sync All Completed
CDD_IPC_RPMSG_APP: RpMsg Message exchange started by main core
CDD_IPC_RPMSG_APP: All echoed messages received by main core from 3 remote cores !!!
CDD_IPC_RPMSG_APP: Messages sent to each core = 100000
CDD_IPC_RPMSG_APP: Number of remote cores = 3
All tests have passed

Ipc Rpmsg Callback:

CDD_IPC_RPMSG_CALLBACK_APP: Sample IPC Application started!
CDD_IPC_RPMSG_CALLBACK_APP: Sync All Completed
CDD_IPC_RPMSG_CALLBACK_APP: RpMsg Message exchange started by main core
CDD_IPC_RPMSG_CALLBACK_APP: All echoed messages received by main core from 3 remote cores !!!
CDD_IPC_RPMSG_CALLBACK_APP: Messages sent to each core = 100000
CDD_IPC_RPMSG_CALLBACK_APP: Number of remote cores = 3
All tests have passed

4.7.10.5. File Structure

📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂examples
┃ ┃ ┣ 📂Ipc
┃ ┃ ┃ ┣ 📂soc
┃ ┃ ┃ ┣ 📂Ipc_app_notify
┃ ┃ ┃ ┃ ┣ 📜Cdd_Ipc_app.h : Contains Cdd Ipc example header file
┃ ┃ ┃ ┃ ┣ 📜Cdd_Ipc_notify_app.c : contains the IPC R50 test app for IPC Notify
┃ ┃ ┃ ┃ ┗ 📜Makefile
┃ ┃ ┃ ┣ 📂Ipc_app_rpmsg
┃ ┃ ┃ ┃ ┣ 📜Cdd_Ipc_app.h : Contains Cdd Ipc example header file
┃ ┃ ┃ ┃ ┣ 📜Cdd_Ipc_rpmsg_app.c : Contains IPC R50 test app for RpMsg
┃ ┃ ┃ ┃ ┗ 📜Makefile
┃ ┃ ┃ ┣ 📂Ipc_app_rpmsg_callback_mode
┃ ┃ ┃ ┃ ┣ 📜Cdd_Ipc_app.h : Contains Cdd Ipc example header file
┃ ┃ ┃ ┃ ┣ 📜Cdd_Ipc_rpmsg_callback_app.c : Contains IPC R50 test app for RpMsg
┃ ┃ ┃ ┃ ┗ 📜Makefile
┃ ┣ 📂examples_config
┃ ┃ ┣ 📂Ipc_Demo_Cfg
┃ ┃ ┃ ┗ 📂soc
┃ ┃ ┃ ┃ ┣ 📂am263px
┃ ┃ ┃ ┃ ┃ ┗ 📂r5f0_0
┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂include
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗📜Cdd_Ipc_Cfg.h : Contains the configuration parameters
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂src
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣📜Cdd_Ipc_Callback_app_PBCfg.c : Contains all Pre-Compile Configured parameters with Recv CallBack Function
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗📜Cdd_Ipc_PBCfg.c : Contains all Pre-Compile Configured parameters
┃ 📂mcal_config
┃ 📂mcal_docs
┗ 📜README.txt

4.7.10.6. Test Report

Please refer AM26x CDD IPC Driver Test Case Report as part of CSP provided in the release package.

4.7.11. References

Technical Reference Manual