MCUSW
Cdd Ipc User Guide

Table of Contents

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 SDK 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 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

Cdd IPC design page, which is not included as part of release

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 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 (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>

Message reception process

  • Remote core sends a message
  • An interrupt occurs on the host core (On which MCAL AUTOSAR code is running)
  • Checks MBOX_IRQSTATUS_RAW register (BASE_ADDR + 0x100 + (n*16U)), corresponding mailbox bit is set if there is a message in MBOX.
  • Checks MBOX_MSGSTATUS register (BASE_ADDR + 0xC0 + (n*4U)), gives the number of messages available in MBOX.
  • Reads MBOX_MSG register (BASE_ADDR + 0x40 + (n*4U)), gives message written in MBOX. Transmitting core usually writes the remote core ID (core meant for message reception).
  • Clear interrupt by writing 1 to MBOX_IRQSTATUS_CLR (BASE_ADDR + 0x104 + (n*16U)) registers corresponding bit.
  • Read the actual message written in VRING.

Message transmission process

  • Write actual message to VRING.
  • Check if FIFO of specific MBOX is not already full in MBOX_FIFOSTATUS register (BASE_ADDR + 0x80 + (n*4U)), if FIFO is full bit 0 will be set else it will be cleared.
  • Write a message in MBOX via MBOX_MSG register (BASE_ADDR + 0x40 + (n*4U)), usually remote core ID is written (core meant for message reception).

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 It is an endpoint which can be used to send or receive control messages, primarily used by Announce API’s to notify remote cores about the availability of service.

Back To Top

Interrupt to ISR mapping

The following table lists the interrupt details, required for applications to register ISR to receive interrupt on the core that hosts MCAL/IPC

AM62AX: CDD IPC Example on MCU 0_0 (deprecated because baremetal IPC app cant be supported on MCU 0_0)

Please note the SCI Client / DMSC Firmware API are invoked to route interrupt to MCU 0_0 (via routers or no routers) Note: Remote core Application on MPU 1_0 Core is deprecated because FreeRTOS is not supported on that core.

Host Core Remote Core Cluster User Int No for cluster 1 Comm
R5FSS 0 0 A53SS 0 0 4 0 242 ISR Cdd_IpcIrqMbxFromMcu_10

Back To Top

Configuration

The design document details the various configurable parameters of this implementation, please refer section Configurator of 2

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
$ gmake -s cdd_ipc_app BOARD=am62ax_evm SOC=am62ax BUILD_PROFILE=release CORE=mcu0_0 BUILD_OS_TYPE=baremetal
$ OR
$ gmake -s cdd_ipc_app BOARD=am62ax_evm SOC=am62ax BUILD_PROFILE=debug CORE=mcu0_0 BUILD_OS_TYPE=baremetal
  • The generated executable is available at
    • (SDK Install Directory)/mcusw.xx.yy.zz.bb/binary/cdd_ipc_app/bin/(SoC)_evm/cdd_ipc_app_mcu0_0_(BUILD_PROFILE).xer5f
    • e.g. (SDK Install Directory)/mcusw.xx.yy.zz.bb/binary/cdd_ipc_app/bin/am62ax_evm/cdd_ipc_app_mcu0_0_release.xer5f

Build MCAL example application for Linux communication

The MCAL example application could be built with the command

$ cd (SDK Install Directory)/mcusw.xx.yy.zz.bb/build
$ gmake -s cdd_ipc_app_rc_linux BOARD=am62ax_evm SOC=am62ax BUILD_PROFILE=release CORE=mcu0_0 BUILD_OS_TYPE=baremetal CDD_IPC_LINUX_BUILD=yes
$ OR
$ gmake -s cdd_ipc_app_rc_linux BOARD=am62ax_evm SOC=am62ax BUILD_PROFILE=debug CORE=mcu0_0 BUILD_OS_TYPE=baremetal CDD_IPC_LINUX_BUILD=yes
Note: Vring address and Vring size should match with host and remote application.
  • 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_mcu0_0_(BUILD_PROFILE).xer5f
    • e.g. (SDK Install Directory)/mcusw.xx.yy.zz.bb/binary/cdd_ipc_app_rc_linux/bin/am62ax_evm/cdd_ipc_app_rc_linux_mcu0_0_release.xer5f

Back To Top

Steps to run example application

Running the example application via CCS

Preparing the board

Copy the cdd_ipc_app_rc_linux_mcu0_0_debug.xer5f file in to root->lib->firmware in the SD card which contains the Linux image(Linux system required windows file system not supported).

Inside the folder a file named am62a-mcu-r5f0_0-fw will be present, remove that file and rename the copied .xer5f file to am62a-mcu-r5f0_0-fw.

The A53 core will boot the firmware in the MCU R5 core automatically once the SD card is inserted in the board and powered. The logs can be seen using any terminal serially(UART).

Steps to run in CSS console
  1. Create target configuration for AM62A and launch.
  2. Power on the board and wait for Linux to boot, once Linux boots successfully connect to the MCU R5 core.
  3. Load the binary file into load symbols on CCS.
  4. Give free run to the MCU R5 core.
load_symbols_CCS.png
load symbols on CCS
Steps to run in terminal
  1. Login to the board where logs are visible on the terminal using username root.
  2. Use the following command to display the CDD IPC kernel-related messages retrieved from the kernel ring buffer
  3. dmesg | grep IPC
  4. Use the following command to run the CDD IPC module and view the communication logs in the terminal
  5. modprobe rpmsg_client_sample count=10
  6. This command can only be run once to view the CDD IPC logs as the application is running in kernel space.
  7. To run the application again reconnect the device and repeat the steps mentioned in this section.
Terminal_Configuration.png
Terminal Configuration
Terminal_View.png
Terminal View

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_tirtos.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 host R5FSS 0 0 (SDK Install Directory)/mcusw/mcal_drv/mcal/examples_config/CddIpc_Demo_Cfg/output/generated/soc/am62ax/mcu0_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

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 [] (design_cdd_ipc_desc_error_runtime)

Back To Top

API Description

The AUTOSAR BSW Eth Driver specification details the APIs [2].

Back To Top

Example Logs

AM62AX MCU 2 1

       1. LINUX TERMINAL LOGS
         
    root@am62axx-evm:~# rpmsg_char_simple -r 0 -n 10
    Created endpt device rpmsg-char-0-699, fd = 4 port = 1025
    Exchanging 10 messages with rpmsg device ti.ipc4.ping-pong on rproc id 0 ...

    Sending message #0: hello there 0!
    Receiving message #0: hello there 0!
    Sending message #1: hello there 1!
    Receiving message #1: hello there 1!
    Sending message #2: hello there 2!
    Receiving message #2: hello there 2!
    Sending message #3: hello there 3!
    Receiving message #3: hello there 3!
    Sending message #4: hello there 4!
    Receiving message #4: hello there 4!
    Sending message #5: hello there 5!
    Receiving message #5: hello there 5!
    Sending message #6: hello there 6!
    Receiving message #6: hello there 6!
    Sending message #7: hello there 7!
    Receiving message #7: hello there 7!
    Sending message #8: hello there 8!
    Receiving message #8: hello there 8!
    Sending message #9: hello there 9!
    Receiving message #9: hello there 9!

    Communicated 10 messages successfully on rpmsg-char-0-699

    TEST STATUS: PASSED
    root@am62axx-evm:~# modprobe rpmsg_client_sample count=10
    [   93.561808] rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.13: new channel: 0x401 -> 0xd!
    [   93.570354] rpmsg_client_sample virtio2.ti.ipc4.ping-pong.-1.13: new channel: 0x401 -> 0xd!
    [   93.570358] rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.13: incoming msg 1 (src: 0xd)
    [   93.570567] rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.13: incoming msg 2 (src: 0xd)
    [   93.579001] rpmsg_client_sample virtio1.ti.ipc4.ping-pong.-1.13: new channel: 0x401 -> 0xd!
    [   93.587086] rpmsg_client_sample virtio2.ti.ipc4.ping-pong.-1.13: incoming msg 1 (src: 0xd)
    [   93.612028] rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.13: incoming msg 3 (src: 0xd)
    [   93.620325] rpmsg_client_sample virtio1.ti.ipc4.ping-pong.-1.13: incoming msg 1 (src: 0xd)
    root@am62axx-evm:~# [   93.628624] rpmsg_client_sample virtio2.ti.ipc4.ping-pong.-1.13: incoming msg 2 (src: 0xd)
    [   93.638620] rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.13: incoming msg 4 (src: 0xd)
    [   93.646920] rpmsg_client_sample virtio1.ti.ipc4.ping-pong.-1.13: incoming msg 2 (src: 0xd)
    [   93.655222] rpmsg_client_sample virtio1.ti.ipc4.ping-pong.-1.13: incoming msg 3 (src: 0xd)
    [   93.663504] rpmsg_client_sample virtio2.ti.ipc4.ping-pong.-1.13: incoming msg 3 (src: 0xd)
    [   93.671782] rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.13: incoming msg 5 (src: 0xd)
    [   93.680075] rpmsg_client_sample virtio1.ti.ipc4.ping-pong.-1.13: incoming msg 4 (src: 0xd)
    [   93.688365] rpmsg_client_sample virtio1.ti.ipc4.ping-pong.-1.13: incoming msg 5 (src: 0xd)
    [   93.696644] rpmsg_client_sample virtio2.ti.ipc4.ping-pong.-1.13: incoming msg 4 (src: 0xd)
    [   93.704921] rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.13: incoming msg 6 (src: 0xd)
    [   93.713204] rpmsg_client_sample virtio1.ti.ipc4.ping-pong.-1.13: incoming msg 6 (src: 0xd)
    [   93.721494] rpmsg_client_sample virtio1.ti.ipc4.ping-pong.-1.13: incoming msg 7 (src: 0xd)
    [   93.729779] rpmsg_client_sample virtio2.ti.ipc4.ping-pong.-1.13: incoming msg 5 (src: 0xd)
    [   93.738074] rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.13: incoming msg 7 (src: 0xd)
    [   93.746367] rpmsg_client_sample virtio1.ti.ipc4.ping-pong.-1.13: incoming msg 8 (src: 0xd)
    [   93.754657] rpmsg_client_sample virtio1.ti.ipc4.ping-pong.-1.13: incoming msg 9 (src: 0xd)
    [   93.762947] rpmsg_client_sample virtio2.ti.ipc4.ping-pong.-1.13: incoming msg 6 (src: 0xd)
    [   93.771229] rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.13: incoming msg 8 (src: 0xd)
    [   93.779514] rpmsg_client_sample virtio1.ti.ipc4.ping-pong.-1.13: incoming msg 10 (src: 0xd)
    [   93.787871] rpmsg_client_sample virtio1.ti.ipc4.ping-pong.-1.13: goodbye!
    [   93.794677] rpmsg_client_sample virtio2.ti.ipc4.ping-pong.-1.13: incoming msg 7 (src: 0xd)
    [   93.802956] rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.13: incoming msg 9 (src: 0xd)
    [   93.811251] rpmsg_client_sample virtio2.ti.ipc4.ping-pong.-1.13: incoming msg 8 (src: 0xd)
    [   93.819536] rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.13: incoming msg 10 (src: 0xd)
    [   93.827887] rpmsg_client_sample virtio0.ti.ipc4.ping-pong.-1.13: goodbye!
    [   93.834753] rpmsg_client_sample virtio2.ti.ipc4.ping-pong.-1.13: incoming msg 9 (src: 0xd)
    [   93.843129] rpmsg_client_sample virtio2.ti.ipc4.ping-pong.-1.13: incoming msg 10 (src: 0xd)
    [   93.851539] rpmsg_client_sample virtio2.ti.ipc4.ping-pong.-1.13: goodbye!

Back To Top

References

Sl No Specification Comment / Link
1 AUTOSAR 4.3.1 AUTOSAR Specification for CDD Driver & Integration Intranet Link

Back To Top

Document Revision History

Revision Date Author Description Status
0.1 01 Oct 2022 VijayKumar A First version Approved
0.2 15 Mar 2023 VijayKumar A Updated Example Log Approved
0.3 21 July 2023 VijayKumar A Updated Example Log Approved
0.4 11 Sep 2023 VijayKumar A Updated Example Log Approved