Functions

group group_ipc_pipe_functions

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.

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.

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);

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.

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.

Return

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.
     */

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.

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.

Return

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 */
    }

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.

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.

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);
}

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

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.

Return

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.
     */

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.

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.

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);

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

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.

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.

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);

Parameters
  • config: This is the pointer to the pipe configuration structure

cy_en_ipc_pipe_status_t Cy_IPC_Pipe_EndpointPause(uint32_t epAddr)

This function sets the receiver endpoint to paused state.

Return

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);

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

cy_en_ipc_pipe_status_t Cy_IPC_Pipe_EndpointResume(uint32_t epAddr)

This function sets the receiver endpoint to active state.

Return

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);

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

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.

note

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

Parameters
  • endpoint: Pointer to endpoint structure.