General Description

The inter-processor communication (IPC) driver provides a safe and reliable method to transfer data between CPUs.

Hardware locking ensures that only one device can acquire and transfer data at a time so no data is lost or overwritten by asynchronous processes or CPUs.

Include either cy_ipc_pipe.h, cy_ipc_sema.h or cy_ipc_bt.h. Alternatively include cy_pdl.h to get access to all functions and declarations in the PDL.

There are three parts to the API:

Driver-level (DRV) API - used internally by Semaphore, Pipe and Bluetooth levels.
Pipe-level (PIPE) API - establishes a communication channel between processors.
Semaphore-level (SEMA) API - enables users to set and clear flags to synchronize operations.

Firmware does not need to use the DRV API. It can implement IPC functionality entirely with the PIPE, SEMA APIs.

Background

IPC is implemented in hardware as a collection of individual communication channels, each with a set of 32-bit registers. The IPC design implements a set of interrupts that enable each processor to notify the other that data is available, or has been processed. There is also a locking mechanism that allows only one CPU to gain access at a time.

In case of devices having multiple IPC IP instances, IPC channels and IPC interrupts are associated with each other within particular IP instance. It is not possible to create an IPC mechanism where IPC channels of one IPC instance interacts with interrupts of another IPC instance. Following table describes channels and interrupts present in different devices:

Device category	IPC IP instances	Channel numbers	Interrupt numbers
PSE8	IPC0 ( First instance )	0-15	0-7
PSE8	IPC1 ( Second instance )	16-31	8-15

The Driver-level API manages each channel's registers to implement IPC functionality. For information on the IPC registers, see the IPC chapter of the Technical Reference Manual (TRM).

At the hardware level, communication is a five-step process.

The sending processor acquires a channel
It puts data into the channel
The sender generates a notify event (interrupt)
The receiving processor identifies the sender and retrieves the data
The receiving processor generates a release event (interrupt)

These transactions are handled transparently by the DRV-level API. Use the PIPE, SEMA layers of the API to implement communication in your application. The data transferred is limited to a single 32-bit value in case of PIPE and SEMA As implemented by the PIPE API, that value is a pointer to a data structure of arbitrary size and complexity.

Overview

The Pipe is the key element in the PDL design. A pipe is typically a full-duplex communication channel between CPU cores. A pipe allows a single conduit to transfer messages or data to and from multiple processes or CPUs.

A pipe has two endpoints, one on each core. Each endpoint contains a dedicated IPC channel and an interrupt. IPC channels 0-7(8 for the CYB064XX devices) and IPC interrupts 0-7 are reserved for system use.

The pipe also contains the number of clients it supports, and for each client a callback function. So, the pipe can service a number of clients, each with a separate callback function, on either endpoint. The number of clients a pipe supports is the sum of each endpoint's clients.

This design enables any number of processes on the sending core to put arbitrary data into a single pipe. The first element of that data is the client ID of the client that should handle the data.

An interrupt notifies the receiving core that data is available. The receiving core parses the data to identify the client, and then dispatches the event to the appropriate client via the client callback function. An interrupt notifies the sending core that the receiver is finished. In this way a single pipe can manage arbitrary data transfers between cores with data flowing in either direction.

The application can use semaphores to control access to shared resources, as required by the application's logic.

The PDL provides specific files that set up default IPC functionality. They are system_psoc6.h, system_psoc6_cm0plus.c and system_psoc6_cm4.c. You can modify these files based on the requirements of your design. If you use PSoC Creator as a development environment, it will not overwrite your changes when you generate the application or build your code.

PIPE layer

A pipe is a communication channel between two endpoints. PSoC 6 devices support 16 IPC channels, and 16 IPC interrupts, each numbered 0-15. IPC Channels 0-7 and IPC interrupts 0-7 are reserved for system use. Channels 8-15 and interrupts 8-15 are available for application use.

A full duplex pipe uses two IPC channels, one per endpoint. Each endpoint specifies all the information required to process a message (either sent or received). Each endpoint is configured to use an IPC channel, and an IPC interrupt. Common practice is to use the interrupt with the same number as the IPC channel. However, IPC Interrupts are not directly associated with the IPC channels, so any channel can use any interrupt. Any IPC channel can trigger 0, 1 or all the IPC interrupts at once, depending on the Notify or Release masks used.

It is also possible to set up a one-directional pipe, using a single IPC channel. In this design one processor is always the sender, and the other is always the receiver. However, there are still two endpoints.

A pipe supports an arbitrary number of clients with an array of callback functions, one per client. The client ID is the index number into the array for the client. After a pipe is configured and initialized, the application calls Cy_IPC_Pipe_RegisterCallback() once per client to register each client's callback function. Multiple clients can use the same callback function. The endpoints in a pipe share the callback array.

Use Cy_IPC_Pipe_SendMessage() to send data. You specify both the "to" and "from" endpoints, and a callback function to be used when the data transfer is complete. The data is a 32-bit void pointer. The data pointed to is arbitrary, and can be an array, a structure, or a location in memory. The only limitation is that the first element of the data must be a 32-bit unsigned word containing a client ID number. The ID number is the index into the callback array.

When a message is sent, the receiving endpoint's interrupt handler is called. The ISR can perform any task required by the design. However, as part of its function it calls Cy_IPC_Pipe_ExecCallback. This function retrieves the client ID from the data and calls the associated callback function. The user-supplied callback function handles the data in whatever way is appropriate based on the application logic.

After the callback function is returned by the receiver, it invokes the release callback function defined by the sender of the message.

SEMA Layer

A semaphore is a flag the application uses to control access to a shared resource. The SEMA-level API uses an IPC channel to implement semaphores. Startup code sets up a default semaphore system. The default system creates an array of 128 semaphores (four 32-bit values). Semaphores 0-15 are reserved for system use. See Configuration Considerations - SEMA.

Functions are available to initialize the semaphore system, to set or clear a semaphore, or to get the semaphore's current status. Application logic uses SEMA functions to relate a particular semaphore to a particular shared resource, and set, clear, or check the flag when accessing the shared resource.

Configuration Considerations - CYPIPE

There are none. The startup files set up the required CYPIPE for system use. Do not modify the CYPIPE. It uses IPC channels 5 and 6 to implement full duplex communication between cores. See System Interrupt (SysInt) for background.

To create your own pipe (USRPIPE) you should edit startup files and take 4 steps:

Define a pipe callbacks processing interrupt handler (similar to Cy_SysIpcPipeIsrCm0 or Cy_SysIpcPipeIsrCm4)
Define a callbacks array (similar to systemIpcPipeSysCbArray)
Define your pipe configuration with a cy_stc_ipc_pipe_config_t type structure (similar to systemIpcPipeConfigCm0 and systemIpcPipeConfigCm4)
Call Cy_IPC_Pipe_Init() from each core to initialize your pipe (similar to call in the SystemInit)

Configuration Considerations - SEMA

Startup code calls Cy_IPC_Sema_Init() with default values to set up semaphore functionality. By default, the semaphore system uses IPC channel 4, and creates 128 semaphores. Do not change the IPC channel. You can change the number of semaphores.

To change the number of semaphores, modify this line of code in system_psoc6.h.

#define CY_IPC_SEMA_COUNT (uint32_t)(128u)

Startup also declares array cybsp_ipc_sema_array to hold the semaphore flags based on the size defined for this symbol. Use increments of 32. You must have at least 32 semaphores. Semaphores 0-15 are reserved for system use. Your application can use semaphores greater than 15.

API Reference
	IPC driver layer (IPC_DRV)
	The functions of this layer are used in the higher IPC levels (Semaphores and Pipes).

	IPC semaphores layer (IPC_SEMA)
	The semaphores layer functions made use of a single IPC channel to allow multiple semaphores that can be used by system or user function calls.

	IPC pipes layer (IPC_PIPE)
	The Pipe functions provide a method to transfer one or more words of data between CPUs or tasks.