MCUSW
Cdd Ipc User Guide

Introduction

This document details Cdd Ipc module implementations

  • Supported AUTOSAR Release : 4.3.1
  • Supported Configuration Variants : Pre-Compile
  • Vendor ID : CDD_IPC_VENDOR_ID (44)
  • Module ID : CDD_MODULE_ID (255)

Cdd Ipc modules allows core hosting MCAL/AUTOSAR to communicate with other cores (processing entities, with-in SoC) hosting PDK based IPC driver as well as HLOS Linux IPC driver. This driver could be used to transmit and receive variable length messages between cores, via logical communication channel ID's. Can be mapped to Sender-Receiver AUTOSAR interface, for data oriented communication between core that host AUTOSAR / NON AUTOSAR processing entities.

Some of key points to note

  1. Can inter-operate with PDK Ipc and Linux IPC drivers
  2. Depends on the built-in mailbox hardware to notify arrival of new message
  3. Relies on shared memory (message would be copied into shared area and destination core notified, the destination core would read this message)
  4. Not configurable (via Cdd Ipc configuration parameters) to use different mailbox, FIFO & user
  5. Interrupt are used, to signal presence of new message destined to this core
  6. For a given channel local and remote endpoint pair is formed.
  7. In case of communication with Linux, remote endpoint is not published upfront, hence it is cached everytime a message a received.
  8. Refer IPC CDD Profiled Performance to determine the CPU Hz need to transport / receive a message

Cdd Driver Architecture/Design

Please refer the Cdd IPC design page, which is included as part of release [[2] (Refer to Design Document provided in CSP)

Functional Description

demo_cdd_ipc_ctrl_ep.png
Cdd Ipc Architecture

As depicted in architecture figure above, Cdd Ipc implementation relies on mailbox, shared memory to transport messages between cores. The shared memory & other associated memories are provided via the configurator, Refer [Shared Memory Configuration] (Refer to Design Document provided in CSP) for details.

It's recommended to not change the recommended configuration for these parameters, unless the user comprehends methods to change memory location (and/or size) of the shared memory.

Communication Channel

A communication channel provides a logical communication channel between two processors. Identified uniquely by an un-signed sequential integer, represented by configurator defined [symbolic name] (Refer to Design Document provided in CSP).

Refer (SDK Install Directory)/mcusw.xx.yy.zz.bb/mcal_drv/mcal/examples_config/CddIpc_Demo_Cfg/output/generated/include/Cdd_IpcCfg.h for the generated communication channel identifiers.

There could be multiple unique communication channel between any given 2 cores.

End Point

There are two primary identifiers, identifying the end-points for a core. This is used by the driver to identify the source / destination of a message.

  • LocalEp : An unique, non-repetitive integer on the core that hosts MCAL/AUTOSAR
  • RemoteProcId : An unique processor identifiers, which determines the core that this communication channel is associated with (i.e. to be able to send and receive message to / from that core)
  • RemoteEp : An unique, non-repetitive integer on the remote core

Notes on EndPoints

  1. Shall be unique on a core (either local or remote cores)
  2. Need not be same i.e. localEp = X and remoteEp = Y, is a valid
  3. A communication channel shall have unique end-points, i.e. localEp shall be unique and on remote cores, remoteEp shall be unique

Buffer for each channel

  • MaxNumMsgQueued : Number of messages that could potentially be received & queued in the driver before, these messages could be received by applications
  • MaxMsgSize : Size of the largest message that could be received The MaxNumMsgQueued & MaxMsgSize is used to determine the memory reserved by the driver. The memory is reserved in (SDK Install Directory)/mcusw.xx.yy.zz.bb/mcal_drv/mcal/examples_config/CddIpc_Demo_Cfg/output/generated/src/Cdd_IpcCfg.c with variable (s) Cdd_IpcCommChBuf_<Channel ID>

Control End Point

The demo application by default uses control channel/Announce API's to notify remote cores of service availability. This feature could be turned OFF Refer for steps to turn OFF

Back To Top

Interrupt to ISR mapping

Please refer to the SOC User Manual for detail.

Back To Top

Configuration

The design document details the various configurable parameters of this implementation, please refer section Configurator of [2] (Refer to Design Document provided in CSP)

Back To Top

Non Standard Service APIs

Cdd_IpcRegisterReadBack

As noted from the previous MCAL implementation, some of the critical configuration registers could potentially be corrupted by other entities (s/w or h/w). One of the recommended detection methods would be to periodically read-back the configuration and confirm configuration is consistent. The service API defined below shall be implemented to enable this detection

Description Comments
Service Name Cdd_IpcRegisterReadBack Can potentially be turned OFF (Refer to Design Document provided in CSP)
Syntax uint32 Cdd_IpcRegisterReadBack ( uint32 remoteProcId, P2VAR(Cdd_IpcRegRbValues, AUTOMATIC, CDD_APP_DATA) pRegArgs) E_OK: Register read back has been done, E_NOT_OK: Register read back failed
Service ID NA
Sync / Async Sync
Reentrancy Reentrant
Parameter in remoteProcId Remote Processor ID.
Parameters out pRegArgs - Pointer to where to store the readback values. If this pointer is NULL_PTR, then the API will return E_NOT_OK.
Return Value Std_ReturnType E_OK, E_NOT_OK

Cdd_IpcGetMailboxStatus

Service to get Mailbox state is FULL or not

Description Comments
Service Name Cdd_IpcGetMailboxStatus Service to get Mailbox state is FULL or not
Syntax uint32 Cdd_IpcGetMailboxStatus(uint32 chId) E_OK: Register read back has been done, E_NOT_OK: Register read back failed
Service ID CDD_IPC_SID_MAILBOX_STATE
Sync / Async Sync
Reentrancy Reentrant
Parameter in remoteProcId Remote ID.
Parameters out None
Return Value uint32 Returns the mailbox state

Back To Top

Power-up

The driver doesn't configure the functional clock and power for the Mailbox module. It is expected that the Secondary Bootloader (SBL) powers up the required modules. Please refer SBL documentation.

Note that, this implementation will NOT reset the Mailbox. Un Expected/stale messages could be delivered by the driver. It's recommended to drain stale messages before announcing the availability via service API Cdd_IpcAnnounce () if enabled.

Back To Top

Build and Running the Application

Please follow steps detailed in section (Build) to build library or example.

Build MCAL example application

The MCAL example application could be built with the command

$ cd (SDK Install Directory)/mcusw.xx.yy.zz.bb/build
$ make cdd_ipc_app CORE=mcu2_1 BOARD=(SOC)_evm SOC=(SOC) -sj
  • The generated executable is available at
    • (SDK Install Directory)/mcusw.xx.yy.zz.bb/binary/cdd_ipc_app/bin/(SoC)_evm/cdd_ipc_app_mcu2_1_(BUILD_PROFILE).xer5f

Build MCAL example application for Linux communication

Navigate to /build/Rules.make and set the CDD_IPC_LINUX_BUILD to yes The MCAL example application could be built with the command

$ cd (SDK Install Directory)/mcusw.xx.yy.zz.bb/build
$ make cdd_ipc_app_rc_linux CORE=(CORE_VARIABLE) BOARD=(SOC)_evm SOC=(SOC) -sj

The possible variable values are

  • CORE_VARIABLE = mcu2_1, mcu1_0
  • SOC = j721e, j7200
  • The generated executable is available at
    • (SDK Install Directory)/mcusw.xx.yy.zz.bb/binary/cdd_ipc_app_rc_linux/bin/(SoC)_evm/cdd_ipc_app_rc_linux_(CORE_VARIABLE)_(BUILD_PROFILE).xer5f

Building the remote core example application

The remote core application implementation is available at (SDK Install Directory)/mcusw.xx.yy.zz.bb/mcuss_demos/inter_core_comm/ipc_remote

Note: You can build remote core applications with freertos. Ensure to use the same OS example and remote core application.

  1. Change IpcRemoteApp_DstProc = IPC_MCU2_1 from IPC_MCU1_0 in mcusw/mcuss_demos/inter_core_comm/ipc_remote/main_rtos.c

Please follow steps detailed in section (Build) to build library or example

  1. Note: There is no special remote app needed for Linux communication/testing.
  2. Linux rpmsg_sample_client app can be used.

Building the MCAL IPC profiling application

Refer IPC Profiling Application for details on the profiling application.

$ cd (SDK Install Directory)/mcusw.xx.yy.zz.bb/build
$ make cdd_ipc_profile_app CORE=mcu2_1 BUILD_OS_TYPE=freertos -sj
  • The generated executable is available at
    • (SDK Install Directory)/mcusw.xx.yy.zz.bb/binary/cdd_ipc_profile_app_(BUILD_OS_TYPE)/bin/(SOC)_evm/cdd_ipc_profile_app_(BUILD_OS_TYPE)_mcu1_0_release.xer5f

Back To Top

Building the MCAL IPC profiling application for Linux communication

Refer IPC Profiling Application for details on the profiling application.

$ cd (SDK Install Directory)/mcusw.xx.yy.zz.bb/build
$ make cdd_ipc_profile_app_rc_linux CORE=mcu1_0 BUILD_OS_TYPE=freertos -sj
  • The generated executable is available at
    • (SDK Install Directory)/mcusw.xx.yy.zz.bb/binary/cdd_ipc_profile_app_rc_linux/bin/(SoC)_evm/cdd_ipc_profile_app_rc_linux_mcu1_0_(BUILD_PROFILE).xer5f

Back To Top

Build MCAL Unit Test application

The MCAL Unit Test application could be built with the command

$ cd (SDK Install Directory)/mcusw.xx.yy.zz.bb/build
$ make -s cdd_ipc_test BOARD=(SOC)_evm SOC=(SOC) BUILD_PROFILE=release CORE=mcu2_1 BUILD_OS_TYPE=baremetal MCAL_CONFIG=x
CDD IPC(2_1) config_1 config_2 config_3 config_4 config_5
REMOTE(2_0) ipc_remote_app ipc_remote_app ipc_remote_2chnls_app ipc_remote_app ipc_remote_test1
  • The generated executable is available at
    • (SDK Install Directory)/mcusw.xx.yy.zz.bb/binary/cdd_ipc_app/bin/(SoC)_evm/cdd_ipc_app_mcu2_1_(BUILD_PROFILE).xer5f

Back To Top

Steps to run example application

To run the CddIpcRprocLinuxApp on mcu1_0

  1. Download and install the Linux installer
  2. Partition and flash the SD card using the below mentioned steps
  3. Navigate to (SDK INSTALL DIR)/Makefile and update the UBOOT_DM variable to point to cdd_ipc_app_rc_linux_mcu1_0_release_strip.xer5f binary.
    • Navigate to (SDK INSTALL DIR) and run make u-boot on the terminal.
    • Replace the tispl.bin file in the SD-card inside bootfs with tispl.bin at (SDK INSTALL DIR)/board-support/u-boot_build/a72
    • Insert SD-card in the board, ensure that the board is in SD card boot mode and power it on.
    • Once the application core is booted, log in with username root and run the modprobe rpmsg_client_sample count=10 to view the communication logs with all remote cores.

To run the CddIpcRprocLinuxApp on mcu2_1

  1. Download and install the Linux installer
  2. Partition and flash the SD card using the below mentioned steps
  3. Navigate to ${SD_CARD_PATH}/rootfs/lib/firmware/pdk-ipc
    • Remove ipc_echo_test_mcu2_1_release_strip.xer5f and move the cdd_ipc_app_rc_linux_mcu2_1_release_strip.xer5f binary to $SD_CARD_PATH/rootfs/lib/firmware/pdk-ipc
    • Rename the cdd_ipc_app_rc_linux_mcu2_1_release_strip.xer5f file to ipc_echo_test_mcu2_1_release_strip.xer5f
    • Remove the old symbolic firmware link for mcu2_1 in $SD_CARD_PATH/rootfs/lib/firmware with rm j7200-main-r5f0_1-fw(for j7200) or rm j7-main-r5f0_1-fw(for j721e)
    • Recreate the symbolic link with the new firmware for J7200 by sudo ln -s pdk-ipc/ipc_echo_test_mcu2_1_release_strip.xer5f j7200-main-r5f0_1-fw
    • Recreate the symbolic link with the new firmware for J721E by sudo ln -s pdk-ipc/ipc_echo_test_mcu2_1_release_strip.xer5f j7-main-r5f0_1-fw
    • Once the application core is booted, log in with username root and run the modprobe rpmsg_client_sample count=10 to view the communication logs with all remote cores.

Please refer the SOC user manual for cdd_ipc_app.

Back To Top

Memory Mapping

Various objects of this implementation (e.g. variables, functions, constants) are defined under different sections. The linker command file at (Examples Linker File (Select memory location to hold example binary)) defines separate section for these objects. When the driver is integrated, it is expected that these sections are created and placed in appropriate memory locations. (Locations of these objects depend on the system design and performance needs)

Section CDD_IPC_CODE CDD_IPC_VAR CDD_IPC_VAR_NOINIT CDD_IPC_CONST CDD_IPC_CONFIG
CDD_IPC_DATA_NO_INIT_UNSPECIFIED_SECTION (.data) USED
CDD_IPC_DATA_INIT_32_SECTION USED
CDD_IPC_TEXT_SECTION USED
CDD_IPC_DATA_NO_INIT_8_SECTION USED
CDD_IPC_CONFIG_SECTION USED
CDD_IPC_ISR_TEXT_SECTION USED
CDD_IPC_CONFIG_SECTION USED

Back To Top

Dependencies on SW Modules

DET

This implementation depends on the DET in order to report development errors and can be turned OFF. Refer to the Development Error Reporting section for detailed error codes.

Back To Top

SchM

This implementation requires 1 level of exclusive access to guard critical sections. Invokes SchM_Enter_Cdd_Ipc_IPC_EXCLUSIVE_AREA_0(), SchM_Exit_Cdd_Ipc_IPC_EXCLUSIVE_AREA_0() to enter critical section and exit.

In the example implementation (SchM_Cdd_Ipc.c), all the interrupts on CPU are disabled. However, disabling of the enabled Mailbox related interrupts should suffice.

Back To Top

File Structure

Cdd Ipc File Structure

cdd_ipc_dir_src.png
CDD Ipc Implementation Directory Structure
  • Driver implemented by: Cdd_Ipc.c, Cdd_IpcIrq.c & Cdd_IpcPriv.h core driver files
  • Example Configuration by: Cdd_IpcCfg.c and Cdd_IpcCfg.h
  • Example Application by: CddIpcApp.c & CddIpcApp.h
  • Remote Core Application by: main_rtos.c, ipc_utils.c

Back To Top

Customizing Examples Application

Turn OFF Use Of Control End Point

IPC demo applications use atleast 2 applications running on 2 different cores. Namely ipc_remote_app & cdd_ipc_app OR cdd_ipc_profile_app , these two applications would have to be re built when this features requires to be turned OFF

  1. Update MCAL configuration
    1. Example Application
      1. The configuration used by this application is present in (SDK Install Directory)/mcusw/mcal_drv/mcal/examples_config/CddIpc_Demo_Cfg/output/generated/soc/(SOC)/mcu1_0
        • OR Incase application is being hosted on MCU 2 1 (SDK Install Directory)/mcusw/mcal_drv/mcal/examples_config/CddIpc_Demo_Cfg/output/generated/soc/(SOC)/mcu2_1
        1. Update the configurator to TURN OFF as show below
          cdd_ipc_ug_no_announce.png
          Announce API turned OFF
      2. Regenerate the configuration and copy the same into location specified above
      • Alternately
      1. Set the macro CDD_IPC_ANNOUNCE_API to STD_OFF in Cdd_IpcCfg.h
      2. Re compile the MCAL demo application User Guide
    2. Profiling Application
  2. Update Remote Application configuration

Back To Top

Error Handling

Development Error Reporting

Development errors are reported to the DET using the service Det_ReportError(), when enabled. The driver interface files (Cdd_IpcCfg.h shown in the driver directory structure of the File Structure section)

Refer Design Document for detailed [Error Codes] (Refer to Design Document provided in CSP)

Back To Top

Error codes

Production error are reported to DET via Det_ReportError(). Only the error codes in the Cdd Ipc driver specifications are reported which are listed in [] (Refer to Design Document provided in CSP)

Back To Top

API Description

The AUTOSAR BSW Eth Driver specification details the APIs [[2] (Refer to Design Document provided in CSP)].

Back To Top

Example Application

Flow Chart

The flow chart below depicts the demo application

  • ipc_remote_app_mpu1_0_release.xa53fg would be hosted on Remote Core (MPU 1 0)
  • cdd_ipc_app_mcu1_0_release.xer5f would be hosted on Local Core (MCU 1 0)
demo_cdd_ipc_flowchart.png
Cdd Ipc Demo Application flow chart

Back To Top

Example Logs

MCU 1 0 Linux communication

rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: new channel: 0x400 -> 0xb!
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 1 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 2 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 3 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 4 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 5 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 6 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 7 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 8 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 9 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 10 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: goodbye!

MCU 2 1 Linux communication

rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: new channel: 0x400 -> 0xb!
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 1 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 2 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 3 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 4 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 5 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 6 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 7 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 8 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 9 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: incoming msg 10 (src: 0xb)
rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.11: goodbye!

MCU 2 1

CDD_IPC_APP : CDD IPC MCAL Version Info
CDD_IPC_APP :---------------------
CDD_IPC_APP : Vendor ID           : 44
CDD_IPC_APP : Module ID           : 255
CDD_IPC_APP : SW Major Version    : 1
CDD_IPC_APP : SW Minor Version    : 0
CDD_IPC_APP : SW Patch Version    : 0

CDD_IPC_APP :
CDD_IPC_APP : Sample Application - STARTS !!!
CDD_IPC_APP : Received ti.ipc4.ping-pong as ctrl MSG from MCU 1 1
CDD_IPC_APP : Received ping 0 Iteration 10 from MCU 1 1
CDD_IPC_APP : Received ping 1 Iteration 9 from MCU 1 1
CDD_IPC_APP : Received ping 2 Iteration 8 from MCU 1 1
CDD_IPC_APP : Received ping 3 Iteration 7 from MCU 1 1
CDD_IPC_APP : Received ping 4 Iteration 6 from MCU 1 1
CDD_IPC_APP : Received ping 5 Iteration 5 from MCU 1 1
CDD_IPC_APP : Received ping 6 Iteration 4 from MCU 1 1
CDD_IPC_APP : Received ping 7 Iteration 3 from MCU 1 1
CDD_IPC_APP : Received ping 8 Iteration 2 from MCU 1 1
CDD_IPC_APP : Received ping 9 Iteration 1 from MCU 1 1
CDD_IPC_APP : Received ti.ipc4.ping-pong as ctrl MSG from MCU 2 0
CDD_IPC_APP : Received ping 0 Iteration 10 from MCU 2 0
CDD_IPC_APP : Received ping 1 Iteration 9 from MCU 2 0
CDD_IPC_APP : Received ping 2 Iteration 8 from MCU 2 0
CDD_IPC_APP : Received ping 3 Iteration 7 from MCU 2 0
CDD_IPC_APP : Received ping 4 Iteration 6 from MCU 2 0
CDD_IPC_APP : Received ping 5 Iteration 5 from MCU 2 0
CDD_IPC_APP : Received ping 6 Iteration 4 from MCU 2 0
CDD_IPC_APP : Received ping 7 Iteration 3 from MCU 2 0
CDD_IPC_APP : Received ping 8 Iteration 2 from MCU 2 0
CDD_IPC_APP : Received ping 9 Iteration 1 from MCU 2 0
CDD_IPC_APP : Received ti.ipc4.ping-pong as ctrl MSG from MPU 1 0
CDD_IPC_APP : Received ping 0 Iteration 10 from MPU 1 0
CDD_IPC_APP : Received ping 1 Iteration 9 from MPU 1 0
CDD_IPC_APP : Received ping 2 Iteration 8 from MPU 1 0
CDD_IPC_APP : Received ping 3 Iteration 7 from MPU 1 0
CDD_IPC_APP : Received ping 4 Iteration 6 from MPU 1 0
CDD_IPC_APP : Received ping 5 Iteration 5 from MPU 1 0
CDD_IPC_APP : Received ping 6 Iteration 4 from MPU 1 0
CDD_IPC_APP : Received ping 7 Iteration 3 from MPU 1 0
CDD_IPC_APP : Received ping 8 Iteration 2 from MPU 1 0
CDD_IPC_APP : Received ping 9 Iteration 1 from MPU 1 0
CDD_IPC_APP : Transmitted and Received 10 times
CDD_IPC_APP : Sample Application - Completes !!!

Back To Top

References

Sl No Specification Comment / Link
1 AUTOSAR 4.3.1 AUTOSAR Specification for CDD Driver & Integration Intranet Link
2 - Design Page (Cdd IPC Design Document)

Back To Top

Document Revision History

Revision Date Author Description Status
0.1 14 Apr 2019 Sujith S First version Pending Review
0.2 18 Apr 2019 Sujith S Addressed Review comments Approved
0.3 12 Jul 2019 Sujith S Included updates based on J721E Approved
0.4 16 Oct 2019 Sujith S Added Logs from J721E testing Approved
0.5 30 Oct 2020 Sunita N Added IPC CDD Linux communication Approved
0.6 22 Jun 2020 Nikki S 1.03.03 Release updates Approved
0.7 26 Jun 2023 Nikki Shah Updated based on 1.06 release Approved
0.8 6 Jul 2023 Arush Pant CDD IPC Updates for MCU1_0 Core Approved