4.4. CDD_IPC

4.4.1. Introduction

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

AM273x

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.4.2. Complex Device Driver Architecture

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

../_images/ipc_architecture.png

Fig. 4.1 CDD in AUTOSAR architecture

4.4.3. Functional Description

4.4.3.1. 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 Callback functionality supported

4.4.3.2. 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.4.3.3. Error Handling

4.4.3.3.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.4.3.3.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

●

●

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.4.3.4. 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.4.4. Include Structure

../_images/ipc_headerstructure.png

Fig. 4.2 CDD header file include structure

4.4.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.4.6. Services used by Complex device Driver

The CDD does not provide any call back functions.

4.4.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.4.7. API Definition

Refer the MCAL_ApiGuide for API documentation and Type definition

4.4.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.4.8. Configuration Parameter

There are following different parameter which user can configure from the EB tresos:

  1. CddIpcTimeout : This parameter will help to configure timeout which will be used to terminate if our execution time exceed the timeout time.

  2. CddIpcNumOfBuffers : This parameter will be used to configure number of buffer in VRING. And this parameter will be used in case of RPMsg transfer.

  3. CddIpcMaxBufferSize : This parameter will be used to configure the size of the buffer in VRING.And this will also be used in case of RPMsg transfer.

  4. CddIpcRpMsgEnable : This checkbox parameter will act as STD_ON/STD_OFF. So in case user want RPMsg enable then they can tick this otherwise in else case configuration will be generated considering notify transfer only.

  5. CddIpcRecvCallBack : This parameter is used when user want to register a callback along with the RPMsg transfer.

  6. CddIpcLocalCoreId : Used to select which coreID user want as a local core or the core on which MCAL will run.

  7. CddIpcRemoteCoreList : In this user get option to select what all remote they want in there communication and accord’list all those under this list.

  8. CddIpcEndPtConfig : This will suggest what EndPoint is used for the communication between the cores.

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 transfering 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.4.9. Example Application

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

4.4.9.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.4.9.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 PLATFORM=am273.

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 PLATFORM=am273.

4.4.9.3. Changing and Compiling SDK examples:

Examples to import from SDK to validate the CDD_IPC 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\am273x-evm

  3. $(MCU_PLUS_SDK_PATH)\examples\drivers\ipc\ipc_rpmsg_echo\am273x-evm

4.4.9.3.1. Notify App Sample Output:

../_images/ipc_notifyappsample.png

4.4.9.3.2. RPMsg App Sample Output:

../_images/ipc_rpmsgappsample.png

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