4.5. CDD_IPC

4.5.1. Introduction

This document describes the functionality, API and configuration of the AUTOSAR BSW module Complex Device driver for IPC on AM263x 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:

AM263x

The Complex Device Driver main tasks are the following:

1. Initialization of the mailbox driver

2. Simplifies reading and writing to the mailbox peripheral.

4.5.2. Complex Device Driver Architecture

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

Fig. 4.2 CDD in AUTOSAR architecture

4.5.3. Functional Overview

4.5.3.1. Brief Overview

4.5.3.1.1. Safe_IPC Overview

Safe_IPC in a Multi core system requires both Firewalling of shared memory and Data integrity check of payload. Safe_IPC can be enabled using Configurator which configures the shared memory in a way that firewalling is possible(limitation being number of firewalls and firewall granularity). Firewall configuration is not automatic and need to be manually enabled and configured from Non-Autosar core(by the core from which MCAL core is communicating). Data Integrity check has to be enabled using Configuration. Once Enabled, Data Integrity Check using CRC is enabled for IPC Notify and RPMsg Data. The calculated CRC is sent as a part of IPC Payload and decoded in the receiver end. Application has to define a hook function which will be used by driver for CRC calculation. 8 Bit CRC is used by IPC Notify and 16 Bit CRC is used by IPC RPMsg.

Note

why firewall is needed?

1. Firewall Protection ensures that if any core which don’t have permission to access the mailbox memory and that core tries to access the memory then exception is called.

2. With the help of firewall, core which don’t have permission will not be able to read or write into the firewall protected mailbox memory. This insures the prevention of malacious activity by non-firewalled core.

4.5.3.2. Features Supported and Not Supported

Supported	Not Supported
Open/Close mailbox instance	Multiple mailbox channels between the cores.
Send/Receive both Notify and RpMsg messages.	Applications are validated only for the R50_0 core(RPmsg and Notify)
RpMsg Callback functionality supported
Safe IPC functionality supported

4.5.3.3. Initialization

The initialization covers the following steps

1. Initialize the mailbox peripheral

2. Cdd_Ipc_Init should be called only once during initialization.

3. No other CDD API can be invoked until this API is called.

4.5.3.4. Error Handling

4.5.3.4.1. Development Errors

Development errors are reported to the DET using the service Det_ReportError() if development error reporting is enabled (i.e. pre-compile parameter CDD_IPC_DEV_ERROR_DETECT== STD_ON). The reported service IDs identify the services which are described in 3.4. The following table presents the service IDs and the related services

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

Error Code	Symbolic Name	Description
0x01U	CDD_IPC_E_UNINIT	Error code indicating the IPC is uninitialized
0x02U	CDD_IPC_E_REGISTER_CLIENT_FAILED	Error code indicating register client failed event
0x03U	CDD_IPC_E_INIT_FAILED	Error code indicating IPC Initilization Failed
0x04U	CDD_IPC_E_DEINIT_FAILED	Error code indicating IPC Deinitilization Failed
0x05U	CDD_IPC_E_PARAM_POINTER	Error code indicating invalid parameter
0x06U	CDD_IPC_E_ALREADY_INITIALIZED	Error code indicating IPC already initialized
0x07U	CDD_IPC_E_PARAM_VALUE	Error code indicating Service called with wrong param
0x08U	CDD_IPC_E_PARAM_LENGTH	Error code indicating Service called with invalid length
0x09U	CDD_IPC_E_INVALID_CHANNEL	Error code indicating invalid IPC Channel
0x0AU	CDD_IPC_E_INVALID_CONFIG	Error code indicating invalid IPC configuration
0x0BU	CDD_IPC_E_WRITE_FAILED	Error code indicating IPC Write Failed configuration
0x0CU	CDD_IPC_E_UNREGISTER_CLIENT_FAILED	Error code indicating unregister client failed event
0x0DU	CDD_IPC_E_CONSTRUCT_FAILED	Error code indicating construct failed event
0x0EU	CDD_IPC_E_RPMSG_WRITE_FAILED	Error code indicating RpMsg Write failed event
0x0FU	CDD_IPC_E_RPMSG_READ_FAILED	Error code indicating Rpmsg read failed event
0x10U	CDD_IPC_E_DESTRUCT_FAILED	Error code indicating destruct failed event

4.5.3.4.2. Runtime Errors

The run time errors reported to DET module are described in the following table:

Error Code	Error Macro	Description
[0x01]	CDD_IPC_E_INIT_FAILED	Error code indicating the IPC is initialization failed after executing Cdd_Ipc_Init API
[0x0D]	CDD_IPC_E_CONSTRUCT_FAILED	Error code indicating construct failed after executing Cdd_Ipc_construct API.
[0x0D]	CDD_IPC_E_DEINIT_FAILED	Error code indicating IPC Deinitilization Failed after executing Cdd_Ipc_DeInit API.

4.5.3.4.3. 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				●	●
Cdd_Ipc_DeInit	●			●
Cdd_Ipc_Notify_RegisterClient	●	●		●
Cdd_Ipc_Notify_UnregisterClient	●		●			●
Cdd_Ipc_Notify_Write	●					●	●	●
Cdd_Ipc_Construct	●					●
Cdd_Ipc_Destruct	●					●
Cdd_Ipc_RpMsg_SendMsg	●					●			●
Cdd_Ipc_RpMsg_RecvMsg	●					●				●

4.5.3.5. Scope of Delivery

File Name	Description
Cdd_Ipc.h	This file contains interface header for Complex device driver for IPC
Cdd_Ipc_Irq.h	This file contains ISR function declaration for Complex Device Driver
Cdd_Ipc.c	This file contains function definitions for the Complex device driver for IPC and helper functions.
Cdd_Ipc_Irq.c	This file contains ISR function definitions for Complex Device Driver

4.5.4. Include Structure

Fig. 4.3 CDD header file include structure

4.5.5. 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) CDD_IPC_STOP_SEC_VAR_INIT_UNSPECIFIED				●
CDD_IPC_START_SEC_CODE_APPL(.text) CDD_IPC_STOP_SEC_CODE_APPL		●
CDD_IPC_START_SEC_VAR_UNSPECIFIED(.data) CDD_IPC_STOP_SEC_VAR_UNSPECIFIED			●
CDD_IPC_START_SEC_CODE(.text) CDD_IPC_START_SEC_CODE	●

4.5.6. Services used by Complex device Driver

The CDD does not provide any call back functions.

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

Dependencies on SW modules

• 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

• DET (Optional)

  The module CDD depends on the DET (by default) in order to report development errors. Detection and reporting of development errors can be enabled or disabled by the switch CDD_IPC_DEV_ERROR_DETECT = STD_ON in the Cdd_Ipc_Cfg.h o Critical Sections 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.5.7. API Definition

Refer the MCAL_ApiGuide for API documentation and Type definition

4.5.7.1. Supported API’s

1. Cdd_Ipc_Init : This API will act as Service for CDD IPC Initialization.

2. Cdd_Ipc_DeInit : This API will act as Service for deinitializing CDD IPC.

3. Cdd_Ipc_Notify_RegisterClient : This API will act as Service to register a client for IPC.

4. Cdd_Ipc_Notify_UnregisterClient : This API will act as Service to un-register a client for IPC.

5. Cdd_Ipc_Notify_Write : This API will act as Service to write ipc notify message.

6. Cdd_Ipc_Construct : Used to Create a RPMessage object to receive messages at a specified end-point

7. Cdd_Ipc_Destruct : This API will act as Service to delete a previously created RPMessage object

8. Cdd_Ipc_RpMsg_SendMsg : This API will act as Service to Send a message to a remote core at a specified remote end point

9. Cdd_Ipc_RpMsg_RecvMsg : Blocking API to wait till a message is received from any CPU at the specified local end point.

10. Cdd_Ipc_Notify_SyncAll : This API will act as Service to sync all the cores that are participating in the IPC.

4.5.8. 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 recv 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 AM263X	AM263X

4.5.9. Performance

One way message latency in case of notify	1648 nsec
One way message latency in case of RPMsg	9273 nsec
Average time taken to branch from ISR to notify callback	1782 nsec
Average time taken to branch from ISR to rpmsg callback	4055 nsec

Note

One way latency is calculated by taking all the other 3 cores apart from self core as remote core(i.e. R50_1, R51_0 and R51_1).

4.5.10. Example Application

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

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

1. #define MAX 4 To the number of cores user needs to reduce.

2. uint32 gRemoteCoreId[]; Enable only the cores that are required.

3. uint32 gIpcTransferMutex[MAX] Remove the extra Lock variables (These can be replced with any kind of mutex or semaphore implementation at the user End)

4. 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.5.10.2. Ipc_rpmsg_app working

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

2. 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.5.10.3. Ipc_safeipc_app_working

4.5.10.3.1. Overview

1. Safe_IPC application uses Vring as medium to transfer large size of data, along with providing the firewall protection on the mailbox memory(by configuring CDD_IPC_SAFEIPC_ENABLE as enable).

   

2. For selecting the remote core as safe core CddIpcSafeIpcCoresEnable is enabled at the remote core level in the configuration.

   

3. Apart from that CDD_IPC_CRC_ENABLE is enable in order to ensure the data integrity.

   

4. Inside the application hook function is defined for checking the CRC on the data payload.

5. This example demonstrate the safe communication between R50_0 AND R50_1, where MCAL is running on R50_1 and running SDK on R50_0(which is also resposible for setting up firewall).

Note

In order to run safe_ipc there are dependecies from TIFS and SDK. Since TIFS is responsible for providing the firewall services and SDK is responsible for setting up of firewall. So this setting up of firewall need to be taken care from SDK core in order to run safe_ipc with MCAL.

4.5.10.3.2. How to run the example:

1. The safe_ipc application is present under the path <MCAL_ROOT>/examples/Ipc/Ipc_app_safeipc.This can be build from the build folder by using "gmake -s ipc_safeipc_app CDD_IPC_SAFE_ENABLE=yes".

2. After the build is successfull, use the generated xer5f file as an input which should be to generate the appimage from the SDK safeIpc example present under $(MCU_PLUS_SDK_PATH)/examples/drivers/ipc/ipc_safeipc_echo/am263x-cc.

3. MCAL generated xer5f file should be used as an out file for R50_1 core of SDK and then build the SDK appimage.

4. In this case the generated appimage will have sdk running on R50_0 and MCAL on R50_1.

5. Now in order to run the appimage : Flash the appimage using UART_UNIFLASH.For more information refer: https://software-dl.ti.com/mcu-plus-sdk/esd/AM263X/09_01_00_41/exports/docs/api_guide_am263x/TOOLS_FLASH.html#TOOLS_FLASH_UART_UNIFLASH

4.5.10.4. Changing and Compiling SDK examples for Notify and RPMsg:

Examples to import from SDK to validate the CDD_IPC(Notify and Rpmsg) example,

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

2. $(MCU_PLUS_SDK_PATH)/examples/drivers/ipc/ipc_notify_echo/am263x-cc

3. $(MCU_PLUS_SDK_PATH)/examples/drivers/ipc/ipc_rpmsg_echo/am263x-cc

4.5.10.4.1. Notify App Sample Output:

4.5.10.4.2. RPMsg App Sample Output:

4.5.10.4.3. SafeIpc App Sample Output:

4.5.10.4.4. Plugin Generation:

The Cdd_Ipc has two configuration files inside Ipc_Demo_Cfg/soc/am263/r5f0_0/src. Cdd_Ipc_Callback_app_PBCfg.c and Cdd_Ipc_PBCfg.c

1. To generate Cdd_Ipc_Callback_app_PBCfg.c file, configure the macro CDD_IPC_RPMSG_CALLBACK_ENABLE as STD_ON in Cdd_Ipc_Cfg.h file.

2. Generate the configuration files.

3. Rename the PBCfg.c file as Cdd_Ipc_Callback_app_PBCfg.c and keep inside Ipc_Demo_Cfg/soc/am263/r5f0_0/src.

4. This file is used by the Cdd_Ipc_rpmsg_callback app.

5. To generate Cdd_Ipc_PBCfg.c file, configure the macro CDD_IPC_RPMSG_CALLBACK_ENABLE as STD_OFF in Cdd_Ipc_Cfg.h file.

6. Generate the configuration files.

7. keep the Cdd_Ipc_PBCfg.c file inside Ipc_Demo_Cfg/soc/am263/r5f0_0/src.

8. This file is used by the Cdd_Ipc_rpmsg app.

Note

1. Keep the Cdd_Ipc_Cfg.h file with macro CDD_IPC_RPMSG_CALLBACK_ENABLE as STD_ON inside the path Ipc_Demo_Cfg/soc/am263/r5f0_0/include.

4.5.11. TI Disclaimer

Texas Instruments and its subsidiaries (TI) reserve the right to make changes to their products or to discontinue any product or service without notice, and advise customers to obtain the latest version of relevant information to verify, before placing orders, that information being relied on is current and complete. All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgment, including those pertaining to warranty, patent infringement, and limitation of liability.

TI warrants performance of its products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily performed, except those mandated by government requirements.

Customers are responsible for their applications using TI components. In order to minimize risks associated with the customer’s applications, adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards.

TI assumes no liability for applications assistance or customer product design. TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right of TI covering or relating to any combination, machine, or process in which such products or services might be or are used. TI’s publication of information regarding any third party’s products or services does not constitute TI’s approval, license, warranty or endorsement thereof.

Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations and notices. Representation or reproduction o f this information with alteration voids all warranties provided for an associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.

Resale of TI’s products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.

Also see: Standard Terms and Conditions of Sale for Semiconductor Products https://www.ti.com/sc/docs/stdterms.htm

Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265