Inter-Processor Communication (r_ipc)

Functions
fsp_err_t	R_IPC_Open (ipc_ctrl_t *const p_api_ctrl, ipc_cfg_t const *const p_cfg)
fsp_err_t	R_IPC_MessageSend (ipc_ctrl_t *const p_api_ctrl, uint32_t message)
fsp_err_t	R_IPC_EventGenerate (ipc_ctrl_t *const p_api_ctrl, ipc_generate_event_t event)
fsp_err_t	R_IPC_CallbackSet (ipc_ctrl_t *const p_api_ctrl, void(*p_callback)(ipc_callback_args_t *), void *const p_context, ipc_callback_args_t *const p_callback_memory)
fsp_err_t	R_IPC_Close (ipc_ctrl_t *const p_api_ctrl)

Detailed Description

Driver for the IPC peripheral on RA MCUs. This module implements the IPC Interface.

Overview

The IPC HAL module supports communication across processors via maskable interrupts and one-way message FIFOs.

Note

IPC semaphores and NMI are handled through BSP APIs. See Inter-Processor Communication (IPC) Support.

Features

• Send and receive messages through IPC FIFOs
• Trigger or receive maskable interrupts with multiple event bits settable per interrupt

Configuration

Build Time Configurations for r_ipc

The following build time configurations are defined in fsp_cfg/r_ipc_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Configurations for System > IPC (r_ipc)

This module can be added to the Stacks tab via New Stack > System > IPC (r_ipc). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_ipc0	Module name.
Channel	MCU Specific Options		Select the IPC channel.
Callback	Name must be a valid C symbol	NULL	A user callback function must be provided when the IPC interrupt is enabled. It will be called from the interrupt service routine (ISR).
Interrupt Priority	MCU Specific Options		Select the IPC interrupt priority. An interrupt is only required for receiving messages and events from the opposing core.

Interrupt Configuration

• In order to receive messages, the interrupt must be enabled and a callback must be supplied. If an IPC instance is only being used to send messages or generate events the interrupt doesn't have to be enabled.

Usage Notes

IPC maskable interrupts and FIFOs share the same interrupt so the IPC driver handles configuration of both similarly:

• The IPC driver will choose which IPC registers to use based on the selected core and channel.
• An interrupt and callback is only required when the IPC instance is being used to receive.
  • When receiving a callback should be used to process any received messages/interrupts.
• The channels across cores should always match up for IPC instances. For example, in order to communicate from Core 0 to Core 1 over channel 0:
  • Core 0 should have an IPC instance configured opened on channel 0
  • Core 1 should have an IPC instance configured opened on channel 0

IPC Maskable Interrupt Events

Each IPC channel can set multiple "event" bits in a single maskable interrupt. This should be done through ipc_api_t::eventGenerate.

Examples

Basic IPC Messaging Example

The following example demonstrates sending a simple message from Core 0 to Core 1 via IPC.

Core 0 Application

#define IPC_SEND_MESSAGE    0xABCD
void r_ipc_basic_messaging_core0_example (void)
{
    /* Open an IPC instance on the core 0 application configured to send a message to core 1.
     * @ref ipc_cfg_t::direction should be set to IPC_DIRECTION_SEND.
     * @ref ipc_cfg_t::channel should match for IPC instances on both cores.
     */
    fsp_err_t err = R_IPC_Open(&g_ipc0_ctrl, &g_ipc0_cfg);
    assert(FSP_SUCCESS == err);

    /* Send IPC_SEND_MESSAGE to core 1. */
    err = R_IPC_MessageSend(&g_ipc0_ctrl, IPC_SEND_MESSAGE);
    assert(FSP_SUCCESS == err);
}

Core 1 Application

void r_ipc_basic_messaging_core1_example (void)
{
    /* Open an IPC instance on the core 1 application configured to receive messages.
     * @ref ipc_cfg_t::direction should be set to IPC_DIRECTION_RECEIVE.
     * @ref ipc_cfg_t::channel should match for IPC instances on both cores.
     */
    fsp_err_t err = R_IPC_Open(&g_ipc0_ctrl, &g_ipc0_cfg);
    assert(FSP_SUCCESS == err);

    /* Wait for message from callback */
    while (!g_callback_called)
    {
        ;
    }

    /* Message will be in g_last_message_received */
    (void) g_last_message_received;
}

void ipc_message_example_callback (ipc_callback_args_t * p_args)
{
    /* Check for message received event */
    if (IPC_EVENT_MESSAGE_RECEIVED & p_args->event)
    {
        g_callback_called       = true;
        g_last_message_received = p_args->message;
    }
}

Basic IPC Interrupt Event Example

The following example demonstrates triggering an event via maskable interrupt from Core 0 to Core 1.

Core 0 Application

void r_ipc_basic_interrupt_event_core0_example (void)
{
    /* Open an IPC instance on the core 0 application configured to send to core 1.
     * @ref ipc_cfg_t::direction should be set to IPC_DIRECTION_SEND.
     * @ref ipc_cfg_t::channel should match for IPC instances on both cores.
     */
    fsp_err_t err = R_IPC_Open(&g_ipc0_ctrl, &g_ipc0_cfg);
    assert(FSP_SUCCESS == err);

    /* Trigger interrupt on core 1 with event 0 bit set. */
    err = R_IPC_EventGenerate(&g_ipc0_ctrl, IPC_GENERATE_EVENT_IRQ0);
    assert(FSP_SUCCESS == err);
}

Core 1 Application

void r_ipc_basic_interrupt_event_core1_example (void)
{
    /* Open an IPC instance on the core 1 application configured to receive.
     * @ref ipc_cfg_t::direction should be set to IPC_DIRECTION_RECEIVE.
     * @ref ipc_cfg_t::channel should match for IPC instances on both cores.
     */
    fsp_err_t err = R_IPC_Open(&g_ipc0_ctrl, &g_ipc0_cfg);
    assert(FSP_SUCCESS == err);

    /* Wait for event */
    while (!g_event0_triggered)
    {
        ;
    }
}

void ipc_event_example_callback (ipc_callback_args_t * p_args)
{
    /* Check for message received event */
    if (IPC_EVENT_IRQ0 & p_args->event)
    {
        g_event0_triggered = true;
    }
}

Function Documentation

R_IPC_Open()

fsp_err_t R_IPC_Open	(	ipc_ctrl_t *const	p_api_ctrl,
		ipc_cfg_t const *const	p_cfg
	)

Configures the IPC driver channel based on the input configuration.

Implements ipc_api_t::open.

Return values

FSP_SUCCESS	Channel opened successfully.
FSP_ERR_ASSERTION	Pointer to IPC control block or configuration structure is NULL.
FSP_ERR_IP_CHANNEL_NOT_PRESENT	The requested channel does not exist on this MCU.
FSP_ERR_ALREADY_OPEN	Control block has already been opened or channel is being used by another instance. Call close() then open() to reconfigure.

Returns

See Common Error Codes or functions called by this function for other possible return codes.

R_IPC_MessageSend()

fsp_err_t R_IPC_MessageSend	(	ipc_ctrl_t *const	p_api_ctrl,
		uint32_t	message
	)

Sends a message over the configured IPC channel.

Implements ipc_api_t::messageSend.

Return values

FSP_SUCCESS	Message written to FIFO successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_INSUFFICIENT_SPACE	IPC channel FIFO is full

Returns

See Common Error Codes or functions called by this function for other possible return codes.

R_IPC_EventGenerate()

fsp_err_t R_IPC_EventGenerate	(	ipc_ctrl_t *const	p_api_ctrl,
		ipc_generate_event_t	event
	)

Triggers an interrupt with the specified event bit set over the configured IPC channel.

Implements ipc_api_t::eventGenerate.

Return values

FSP_SUCCESS	Event request set successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.

Returns

See Common Error Codes or functions called by this function for other possible return codes.

R_IPC_CallbackSet()

fsp_err_t R_IPC_CallbackSet	(	ipc_ctrl_t *const	p_api_ctrl,
		void(*)(ipc_callback_args_t *)	p_callback,
		void *const	p_context,
		ipc_callback_args_t *const	p_callback_memory
	)

Updates the user callback and has option of providing memory for callback structure.

Implements ipc_api_t::callbackSet.

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	Pointer to IPC control block or callback is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_NO_CALLBACK_MEMORY	p_callback is non-secure and p_callback_memory is either secure or NULL.

Returns

See Common Error Codes or functions called by this function for other possible return codes.

R_IPC_Close()

fsp_err_t R_IPC_Close

(

ipc_ctrl_t *const

p_api_ctrl

)

Closes the IPC driver.

Implements ipc_api_t::close.

Return values

FSP_SUCCESS	Channel successfully closed.
FSP_ERR_ASSERTION	Pointer to IPC control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.

Returns

See Common Error Codes or functions called by this function for other possible return codes.