Functions

General Description

Functions are used in the driver.

Functions
void	Cy_IPC_Pipe_EndpointInit (uint32_t epAddr, cy_ipc_pipe_callback_array_ptr_t cbArray, uint32_t cbCnt, uint32_t epConfig, cy_stc_sysint_t const *epInterrupt)
	This function initializes the endpoint of a pipe for the current CPU. More...
cy_en_ipc_pipe_status_t	Cy_IPC_Pipe_SendMessage (uint32_t toAddr, uint32_t fromAddr, void *msgPtr, cy_ipc_pipe_relcallback_ptr_t callBackPtr)
	This function is used to send a message from one endpoint to another. More...
cy_en_ipc_pipe_status_t	Cy_IPC_Pipe_RegisterCallback (uint32_t epAddr, cy_ipc_pipe_callback_ptr_t callBackPtr, uint32_t clientId)
	This function registers a callback that is called when a message is received on a pipe. More...
void	Cy_IPC_Pipe_ExecuteCallback (uint32_t epAddr)
	This function is called by the ISR for a given pipe endpoint to dispatch the appropriate callback function based on the client ID for that endpoint. More...
void	Cy_IPC_Pipe_RegisterCallbackRel (uint32_t epAddr, cy_ipc_pipe_relcallback_ptr_t callBackPtr)
	This function registers a default callback if a release interrupt is generated but the current release callback function is null. More...
void	Cy_IPC_Pipe_Config (cy_stc_ipc_pipe_ep_t *theEpArray)
	This function stores a copy of a pointer to the array of endpoints. More...
void	Cy_IPC_Pipe_Init (cy_stc_ipc_pipe_config_t const *config)
	Initializes the system pipes. More...
cy_en_ipc_pipe_status_t	Cy_IPC_Pipe_EndpointPause (uint32_t epAddr)
	This function sets the receiver endpoint to paused state. More...
cy_en_ipc_pipe_status_t	Cy_IPC_Pipe_EndpointResume (uint32_t epAddr)
	This function sets the receiver endpoint to active state. More...
void	Cy_IPC_Pipe_ExecCallback (cy_stc_ipc_pipe_ep_t *endpoint)
	This function is called by the ISR for a given pipe endpoint to dispatch the appropriate callback function based on the client ID for that endpoint. More...

Function Documentation

Cy_IPC_Pipe_EndpointInit()

void Cy_IPC_Pipe_EndpointInit	(	uint32_t	epAddr,
		cy_ipc_pipe_callback_array_ptr_t	cbArray,
		uint32_t	cbCnt,
		uint32_t	epConfig,
		cy_stc_sysint_t const *	epInterrupt
	)

This function initializes the endpoint of a pipe for the current CPU.

The current CPU is the CPU that is executing the code. An endpoint of a pipe is for the IPC channel that receives a message for the current CPU.

After this function is called, the callbackArray needs to be populated with the callback functions for that endpoint using the Cy_IPC_Pipe_RegisterCallback() function.

Note

In general case, this function is called within Cy_IPC_Pipe_Init, so user doesn't need to call it anywhere. However, it may be useful in case of some pipe/endpoint customizations.

Parameters

epAddr	This parameter is the address (or index in the array of endpoint structures) that designates the endpoint you want to initialize.
cbArray	This is a pointer to the callback function array. Based on the client ID, one of the functions in this array is called to process the message.
cbCnt	This is the size of the callback array, or the number of defined clients.
epConfig	This value defines the IPC channel, IPC interrupt number, and the interrupt mask for the entire pipe. The format of the endpoint configuration Bits[31:16] Interrupt Mask Bits[15:8 ] IPC interrupt Bits[ 7:0 ] IPC channel
epInterrupt	This is a pointer to the endpoint interrupt description structure.

Function Usage

#define MY_IPC_PIPE_CLIENT_CNT   (4UL) /* Number of clients on each endpoint */

cy_ipc_pipe_callback_ptr_t myIpcPipeCbArray[MY_IPC_PIPE_CLIENT_CNT];

#define MY_IPC_PIPE_CHAN_EP0     (8UL) /* IPC data channel for MYPIPE EP0 */
#define MY_IPC_PIPE_CHAN_EP1     (9UL) /* IPC data channel for MYPIPE EP1 */
#define MY_IPC_PIPE_INTR_EP0     (8UL) /* Notifier EP0 */
#define MY_IPC_PIPE_INTR_EP1     (9UL) /* Notifier EP1 */
#define MY_IPC_PIPE_INTR_MUX_EP0 (1UL) /* CM0+ NVIC MUX for IPC */
#define MY_IPC_PIPE_INTR_MASK    (uint32_t)((1UL << MY_IPC_PIPE_CHAN_EP0) |\
                                            (1UL << MY_IPC_PIPE_CHAN_EP1))
#define MY_IPC_PIPE_EP0_CONFIG   (_VAL2FLD(CY_IPC_PIPE_CFG_IMASK, MY_IPC_PIPE_INTR_MASK) |\
                                  _VAL2FLD(CY_IPC_PIPE_CFG_INTR,  MY_IPC_PIPE_INTR_EP0) |\
                                  _VAL2FLD(CY_IPC_PIPE_CFG_CHAN,  MY_IPC_PIPE_CHAN_EP0))
#define MY_IPC_PIPE_EP1_CONFIG   (_VAL2FLD(CY_IPC_PIPE_CFG_IMASK, MY_IPC_PIPE_INTR_MASK) |\
                                  _VAL2FLD(CY_IPC_PIPE_CFG_INTR,  MY_IPC_PIPE_INTR_EP1) |\
                                  _VAL2FLD(CY_IPC_PIPE_CFG_CHAN,  MY_IPC_PIPE_CHAN_EP1))

cy_stc_ipc_pipe_ep_config_t myIpcPipeEp0Config =
{
    MY_IPC_PIPE_INTR_EP0,        /* .ipcNotifierNumber       */
    1UL,                         /* .ipcNotifierPriority     */
    MY_IPC_PIPE_INTR_MUX_EP0,    /* .ipcNotifierMuxNumber    */
    MY_IPC_PIPE_EP_ADDR_CM0,     /* .epAddress               */
    MY_IPC_PIPE_EP0_CONFIG       /* .epConfig                */
};

cy_stc_ipc_pipe_ep_config_t myIpcPipeEp1Config =
{
    MY_IPC_PIPE_INTR_EP1,        /* .ipcNotifierNumber       */
    1UL,                         /* .ipcNotifierPriority     */
    0UL,                         /* .ipcNotifierMuxNumber    */
    MY_IPC_PIPE_EP_ADDR_CM4,     /* .epAddress               */
    MY_IPC_PIPE_EP1_CONFIG       /* .epConfig                */
};

    /* Scenario: it may be usable in case if user wants to setup theirs own
     * custom pipe.
     * Instead, in general cases user can just register custom client IDs
     * (callbacks) into the System Pipe (CYPIPE) using Cy_IPC_Pipe_RegisterCallback
     */
    cy_stc_ipc_pipe_ep_config_t * epReceiverConfig;
    cy_stc_ipc_pipe_ep_config_t * epSenderConfig;
    cy_stc_sysint_t               epIntrConfig;

    #if (CY_CPU_CORTEX_M0P)
        epReceiverConfig     = &myIpcPipeEp0Config;
        epSenderConfig       = &myIpcPipeEp1Config;
        epIntrConfig.intrSrc = (IRQn_Type)epReceiverConfig->ipcNotifierMuxNumber;
    #else
        epReceiverConfig     = &myIpcPipeEp1Config;
        epSenderConfig       = &myIpcPipeEp0Config;
        epIntrConfig.intrSrc = (IRQn_Type)(cy_device->cpussIpc0Irq + epReceiverConfig->ipcNotifierNumber);
    #endif

    epIntrConfig.intrPriority     = epReceiverConfig->ipcNotifierPriority;

    /* Initialize the Receiver endpoint */
    Cy_IPC_Pipe_EndpointInit(epReceiverConfig->epAddress,
                             myIpcPipeCbArray,
                             MY_IPC_PIPE_CLIENT_CNT,
                             epReceiverConfig->epConfig,
                             &epIntrConfig);

    /* Create the Sender endpoint just for reference */
    Cy_IPC_Pipe_EndpointInit(epSenderConfig->epAddress, NULL, 0UL, epSenderConfig->epConfig, NULL);

Cy_IPC_Pipe_SendMessage()

cy_en_ipc_pipe_status_t Cy_IPC_Pipe_SendMessage	(	uint32_t	toAddr,
		uint32_t	fromAddr,
		void *	msgPtr,
		cy_ipc_pipe_relcallback_ptr_t	callBackPtr
	)

This function is used to send a message from one endpoint to another.

It generates an interrupt on the endpoint that receives the message and a release interrupt to the sender to acknowledge the message has been processed.

Parameters

toAddr	This parameter is the address (or index in the array of endpoint structures) of the endpoint to which you are sending the message.
fromAddr	This parameter is the address (or index in the array of endpoint structures) of the endpoint from which the message is being sent.
msgPtr	Pointer to the message structure to be sent.
callBackPtr	Pointer to the Release callback function.

Returns

CY_IPC_PIPE_SUCCESS: Message was sent to the other end of the pipe CY_IPC_PIPE_ERROR_BAD_HANDLE: The handle provided for the pipe was not valid CY_IPC_PIPE_ERROR_SEND_BUSY: The pipe is already busy sending a message

Function Usage

void myReleaseCallback(void)
{
    /* The sent data is already processed on the receiver side,
     * the pipe is ready for next transactions
     */
}

    /* Scenario: there is a need to send a message to the MY_IPC_CLIENT_ID client
     * on another CPU side with the user code MY_IPC_MSG_USR_CODE
     */
    #define MY_IPC_CLIENT_ID        (4UL) /* Example client ID */
    #define MY_IPC_MSG_USR_CODE     (5UL) /* Example message user code for client #MY_IPC_CLIENT_ID */
    #define MY_IPC_MSG_SIZE         (7UL) /* Example message size */

    uint32_t myMsg[MY_IPC_MSG_SIZE];      /* Example message */

    myMsg[0] = _VAL2FLD(CY_IPC_PIPE_MSG_CLIENT,  MY_IPC_CLIENT_ID) |
               _VAL2FLD(CY_IPC_PIPE_MSG_USR,     MY_IPC_MSG_USR_CODE) |
               _VAL2FLD(CY_IPC_PIPE_MSG_RELEASE, CY_SYS_CYPIPE_INTR_MASK ); /* Example message header */
    /* CY_SYS_CYPIPE_INTR_MASK is combined masks of both pipe endpoints
     * interrupt channels - to notify both sides about an event, as example.
     * The rest of the message content (as well as message size and user codes
     * in the first message's word) can be defined by user without any restrictions.
     */

    Cy_IPC_Pipe_SendMessage(CY_IPC_EP_CYPIPE_TO_ADDR, CY_IPC_EP_CYPIPE_FROM_ADDR, (void *) &myMsg, myReleaseCallback);
    /* The myReleaseCallback will be called when addressee has handled the message,
     * i.e. the correspondent notify callback is returned.
     */

Cy_IPC_Pipe_RegisterCallback()

cy_en_ipc_pipe_status_t Cy_IPC_Pipe_RegisterCallback	(	uint32_t	epAddr,
		cy_ipc_pipe_callback_ptr_t	callBackPtr,
		uint32_t	clientId
	)

This function registers a callback that is called when a message is received on a pipe.

The client_ID is the same as the index of the callback function array. The callback may be a real function pointer or NULL if no callback is required.

Parameters

epAddr	This parameter is the address (or index in the array of endpoint structures) that designates the endpoint to which you want to add callback functions.
callBackPtr	Pointer to the callback function called when the endpoint has received a message. If this parameters is NULL current callback will be unregistered.
clientId	The index in the callback array (Client ID) where the function pointer is saved.

Returns

CY_IPC_PIPE_SUCCESS: Callback registered successfully CY_IPC_PIPE_ERROR_BAD_CLIENT: Client ID out of range, callback not registered.

Function Usage

#define MY_IPC_MSG_SIZE         (7UL) /* Example message size */
uint32_t myMsg[MY_IPC_MSG_SIZE];      /* Example message container */

void myAcquireCallback(uint32_t * msgData)
{
    uint32_t i;

    for(i = 0; i < MY_IPC_MSG_SIZE; i++)
    {
        myMsg[i] = *((uint32_t*)((uint32_t)msgData + i)); /* Copying the message content */
    }

    /* The release callback will be automatically called on the sender side
     * just after returning from this callback
     */
}

    /* Scenario: there is a need to register an acquire notify event callback */
    #define MY_IPC_CLIENT_ID        (4UL) /* Example client ID */

    if(CY_IPC_PIPE_SUCCESS != Cy_IPC_Pipe_RegisterCallback(CY_IPC_EP_CYPIPE_ADDR, myAcquireCallback, MY_IPC_CLIENT_ID))
    {
        /* Handle possible errors */
    }

Cy_IPC_Pipe_ExecuteCallback()

void Cy_IPC_Pipe_ExecuteCallback

(

uint32_t

epAddr

)

This function is called by the ISR for a given pipe endpoint to dispatch the appropriate callback function based on the client ID for that endpoint.

Parameters

epAddr

This parameter is the address (or index in the array of endpoint structures) that designates the endpoint to process.

Note

This function should be used instead of obsolete Cy_IPC_Pipe_ExecCallback() function because it will be removed in the next releases.

Function Usage

/* Number of endpoints of the MyPipe */
#define MY_IPC_PIPE_MAX_ENDPOINTS     (2UL)
/* Endpoint indexes in the pipe array */
#define MY_IPC_PIPE_EP_ADDR_CM0       (0UL)
#define MY_IPC_PIPE_EP_ADDR_CM4       (1UL)

cy_stc_ipc_pipe_ep_t myIpcPipeEpArray[MY_IPC_PIPE_MAX_ENDPOINTS];

/* Scenario: the Cy_IPC_Pipe_ExecuteCallback is intended to use in the endpoint
 * notifier interrupt handler.
 * It may be usable in case if user wants to setup their own custom pipe.
 * In general cases user can just register custom client IDs (callbacks)
 * into the System Pipe (CYPIPE) using \ref Cy_IPC_Pipe_RegisterCallback.
 */
#if (CY_CPU_CORTEX_M0P)
    #define MY_IPC_PIPE_EP_ADDR       MY_IPC_PIPE_EP_ADDR_CM0
#else
    #define MY_IPC_PIPE_EP_ADDR       MY_IPC_PIPE_EP_ADDR_CM4
#endif  /* (CY_CPU_CORTEX_M0P) */

void My_IPC_PipeIsr(void)
{
    Cy_IPC_Pipe_ExecuteCallback(MY_IPC_PIPE_EP_ADDR);
}

Cy_IPC_Pipe_RegisterCallbackRel()

void Cy_IPC_Pipe_RegisterCallbackRel	(	uint32_t	epAddr,
		cy_ipc_pipe_relcallback_ptr_t	callBackPtr
	)

This function registers a default callback if a release interrupt is generated but the current release callback function is null.

Parameters

epAddr	This parameter is the address (or index in the array of endpoint structures) that designates the endpoint to which you want to add a release callback function.
callBackPtr	Pointer to the callback executed when the endpoint has received a message. If this parameters is NULL current callback will be unregistered.

Returns

None

Function Usage

void myDefaultReleaseCallback(void)
{
    /* The Cy_IPC_Pipe_SendMessage was called without a pointer to specific callback,
     * threfore this one is called.
     * The sent data is already processed on the receiver side,
     * the pipe is ready for next transactions
     */
}

    /* Scenario: there is a need to register a default release callback */
    Cy_IPC_Pipe_RegisterCallbackRel(CY_IPC_EP_CYPIPE_ADDR, &myDefaultReleaseCallback);

    uint32_t myMsg; /* Some already initialised message */
    Cy_IPC_Pipe_SendMessage(CY_IPC_EP_CYPIPE_TO_ADDR, CY_IPC_EP_CYPIPE_FROM_ADDR, (void *) &myMsg, NULL);
    /* Therefore the myDefaultReleaseCallback will be called
     * when addressee has handled the message,
     * i.e. the correspondent acquire callback has returned.
     */

Cy_IPC_Pipe_Config()

void Cy_IPC_Pipe_Config

(

cy_stc_ipc_pipe_ep_t *

theEpArray

)

This function stores a copy of a pointer to the array of endpoints.

All access to endpoints will be via the index of the endpoint in this array.

Note

In general case, this function is called in the default startup code, so user doesn't need to call it anywhere. However, it may be useful in case of some pipe customizations.

Parameters

theEpArray

This is the pointer to an array of endpoint structures that the designer created and will be used to reference all endpoints.

Function Usage

/* Number of endpoints of the MyPipe */
#define MY_IPC_PIPE_MAX_ENDPOINTS     (2UL)
/* Endpoint indexes in the pipe array */
#define MY_IPC_PIPE_EP_ADDR_CM0       (0UL)
#define MY_IPC_PIPE_EP_ADDR_CM4       (1UL)

cy_stc_ipc_pipe_ep_t myIpcPipeEpArray[MY_IPC_PIPE_MAX_ENDPOINTS];

    /* Scenario: there is a need to register the endpoint array prior to
     * pipe/endpoints initializing.
     * It may be usable in case if user wants to setup theirs own custom pipe.
     * Instead, in general cases user can just register custom client IDs
     * (callbacks) into the System Pipe (CYPIPE) using Cy_IPC_Pipe_RegisterCallback
     */
    Cy_IPC_Pipe_Config(myIpcPipeEpArray);

Cy_IPC_Pipe_Init()

void Cy_IPC_Pipe_Init

(

cy_stc_ipc_pipe_config_t const *

config

)

Initializes the system pipes.

The system pipes are used by BLE.

Note

The function should be called on all CPUs.

In general case, this function is called in the default startup code, so user doesn't need to call it anywhere. However, it may be useful in case of some pipe customizations.

Parameters

config

This is the pointer to the pipe configuration structure

Function Usage

#define MY_IPC_PIPE_CLIENT_CNT   (4UL) /* Number of clients on each endpoint */

cy_ipc_pipe_callback_ptr_t myIpcPipeCbArray[MY_IPC_PIPE_CLIENT_CNT];

#define MY_IPC_PIPE_CHAN_EP0     (8UL) /* IPC data channel for MYPIPE EP0 */
#define MY_IPC_PIPE_CHAN_EP1     (9UL) /* IPC data channel for MYPIPE EP1 */
#define MY_IPC_PIPE_INTR_EP0     (8UL) /* Notifier EP0 */
#define MY_IPC_PIPE_INTR_EP1     (9UL) /* Notifier EP1 */
#define MY_IPC_PIPE_INTR_MUX_EP0 (1UL) /* CM0+ NVIC MUX for IPC */
#define MY_IPC_PIPE_INTR_MASK    (uint32_t)((1UL << MY_IPC_PIPE_CHAN_EP0) |\
                                            (1UL << MY_IPC_PIPE_CHAN_EP1))
#define MY_IPC_PIPE_EP0_CONFIG   (_VAL2FLD(CY_IPC_PIPE_CFG_IMASK, MY_IPC_PIPE_INTR_MASK) |\
                                  _VAL2FLD(CY_IPC_PIPE_CFG_INTR,  MY_IPC_PIPE_INTR_EP0) |\
                                  _VAL2FLD(CY_IPC_PIPE_CFG_CHAN,  MY_IPC_PIPE_CHAN_EP0))
#define MY_IPC_PIPE_EP1_CONFIG   (_VAL2FLD(CY_IPC_PIPE_CFG_IMASK, MY_IPC_PIPE_INTR_MASK) |\
                                  _VAL2FLD(CY_IPC_PIPE_CFG_INTR,  MY_IPC_PIPE_INTR_EP1) |\
                                  _VAL2FLD(CY_IPC_PIPE_CFG_CHAN,  MY_IPC_PIPE_CHAN_EP1))

cy_stc_ipc_pipe_ep_config_t myIpcPipeEp0Config =
{
    MY_IPC_PIPE_INTR_EP0,        /* .ipcNotifierNumber       */
    1UL,                         /* .ipcNotifierPriority     */
    MY_IPC_PIPE_INTR_MUX_EP0,    /* .ipcNotifierMuxNumber    */
    MY_IPC_PIPE_EP_ADDR_CM0,     /* .epAddress               */
    MY_IPC_PIPE_EP0_CONFIG       /* .epConfig                */
};

cy_stc_ipc_pipe_ep_config_t myIpcPipeEp1Config =
{
    MY_IPC_PIPE_INTR_EP1,        /* .ipcNotifierNumber       */
    1UL,                         /* .ipcNotifierPriority     */
    0UL,                         /* .ipcNotifierMuxNumber    */
    MY_IPC_PIPE_EP_ADDR_CM4,     /* .epAddress               */
    MY_IPC_PIPE_EP1_CONFIG       /* .epConfig                */
};

    /* Scenario: it may be usable in case if user wants to setup theirs own
     * custom pipe.
     * Instead, in general cases user can just register custom client IDs
     * (callbacks) into the System Pipe (CYPIPE) using Cy_IPC_Pipe_RegisterCallback
     */
    cy_stc_ipc_pipe_config_t myIpcPipeConfig =
    {
        myIpcPipeEp0Config,         /* CM0+ endpoint configuration structure */
        myIpcPipeEp1Config,         /* CM4  endpoint configuration structure */
        MY_IPC_PIPE_CLIENT_CNT,     /* .endpointClientsCount    */
        myIpcPipeCbArray,           /* .endpointsCallbacksArray */
        &My_IPC_PipeIsr             /* .userPipeIsrHandler      */
    };

    Cy_IPC_Pipe_Init(&myIpcPipeConfig);

Cy_IPC_Pipe_EndpointPause()

cy_en_ipc_pipe_status_t Cy_IPC_Pipe_EndpointPause

(

uint32_t

epAddr

)

This function sets the receiver endpoint to paused state.

Parameters

epAddr

This parameter is the address (or index in the array of endpoint structures) that designates the endpoint to pause.

Returns

CY_IPC_PIPE_SUCCESS: Callback registered successfully

Function Usage

    /* Scenario: the CPU needs to perform some critical operation
     * that cannot be disturbed. So there is a need to put the endpoint into
     * paused state while the operation is being performed.
     */
    Cy_IPC_Pipe_EndpointPause(CY_IPC_EP_CYPIPE_ADDR);

    /* Perform the critical operation */

    /* Resume endpoint, return to normal pipe operation */
    Cy_IPC_Pipe_EndpointResume(CY_IPC_EP_CYPIPE_ADDR);

Cy_IPC_Pipe_EndpointResume()

cy_en_ipc_pipe_status_t Cy_IPC_Pipe_EndpointResume

(

uint32_t

epAddr

)

This function sets the receiver endpoint to active state.

Parameters

epAddr

This parameter is the address (or index in the array of endpoint structures) that designates the endpoint to resume.

Returns

CY_IPC_PIPE_SUCCESS: Callback registered successfully

Function Usage

    /* Scenario: the CPU needs to perform some critical operation
     * that cannot be disturbed. So there is a need to put the endpoint into
     * paused state while the operation is being performed.
     */
    Cy_IPC_Pipe_EndpointPause(CY_IPC_EP_CYPIPE_ADDR);

    /* Perform the critical operation */

    /* Resume endpoint, return to normal pipe operation */
    Cy_IPC_Pipe_EndpointResume(CY_IPC_EP_CYPIPE_ADDR);

Cy_IPC_Pipe_ExecCallback()

void Cy_IPC_Pipe_ExecCallback

(

cy_stc_ipc_pipe_ep_t *

endpoint

)

This function is called by the ISR for a given pipe endpoint to dispatch the appropriate callback function based on the client ID for that endpoint.

Parameters

endpoint

Pointer to endpoint structure.

Note

This function is obsolete and will be removed in the next releases. Please use Cy_IPC_Pipe_ExecuteCallback() instead.