Shared Memory (r_shared_memory)

Functions
fsp_err_t	R_SHARED_MEMORY_Open (shared_memory_ctrl_t *const p_ctrl, shared_memory_cfg_t const *const p_cfg)
fsp_err_t	R_SHARED_MEMORY_Read (shared_memory_ctrl_t *const p_ctrl, uint8_t *const p_dest, uint32_t const offset, uint32_t const bytes)
fsp_err_t	R_SHARED_MEMORY_Write (shared_memory_ctrl_t *const p_ctrl, uint8_t *const p_src, uint32_t const offset, uint32_t const bytes)
fsp_err_t	R_SHARED_MEMORY_StatusGet (shared_memory_ctrl_t *const p_ctrl, shared_memory_status_t *p_status)
fsp_err_t	R_SHARED_MEMORY_CallbackSet (shared_memory_ctrl_t *const p_ctrl, void(*p_callback)(shared_memory_callback_args_t *), void const *const p_context, shared_memory_callback_args_t *const p_callback_memory)
fsp_err_t	R_SHARED_MEMORY_Close (shared_memory_ctrl_t *const p_ctrl)

Detailed Description

Driver for the shared memory function on RZ microprocessor. This module implements the Shared Memory Interface.

Overview

Features

• Reads / Writes data on shared memory.
• Supports configuring a user callback function, which will be invoked on following timing.
  • When handshaking between two CPUs is finished
  • When written data to shared memory

Configuration

Build Time Configurations for r_shared_memory

The following build time configurations are defined in fsp_cfg/r_shared_memory_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 > Shared Memory Driver (r_shared_memory)

This module can be added to the Stacks tab via New Stack > System > Shared Memory Driver (r_shared_memory).

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_shared_memory0	Module name.
Shared Memory Address	Value must be an integer		Specify the start address of the shared memory.
Shared Memory Size	Value must be greater than 0		Size of the shared memory (bytes).
Semaphore	Value must be an integer between 0 and 7	0	Select a semaphore registor (SYTSEMFn).
Callback	Name must be a valid C symbol	NULL	A user callback function can be provided here. If this callback function is provided, it is called from the callback function of Inter-CPU IRQ Driver (RX)

This module can be selected only when using Dual core devices.

Clock Configuration

This module does not require any specific clock settings.

Pin Configuration

This module does not use I/O pins.

Usage Notes

1. Generate stacks for each CPUs

When using this module, it is necessary to configure shared memory driver stack on each CPU side.

Example of stack configuration

Stack	Property	Value (CPU0)	Value (CPU1)	Note
Shared Memory Driver	Name	g_shared_memory0	g_shared_memory0
	Shared Memory Address	0x30100000		Each value between CPU0 and CPU1 must be the same
	Shared Memory Size	256
	Semaphore	0
	Callback	shared_memory_callback	shared_memory_callback	User callback function
Inter-CPU IRQ Driver (TX)	Name	g_icu_inter_cpu_irq0	g_icu_inter_cpu_irq0
	Channel	0*1	1*2	*1 and *2 should be different channels
	Software Interrupt Priority	Disabled		Locked
Inter-CPU IRQ Driver (RX)	Name	g_icu_inter_cpu_irq1	g_icu_inter_cpu_irq1
	Channel	1*2	0*1	Set to the same channel as TX of the another shared memory driver
	Software Interrupt Priority	Priority 12	Priority 12	Set valid value

Note

This module do not allocated an instance of the shared memory. If necessary, edit the linker script to protect the area.

2. Prepare callback function

Declare the callback function as follows:

void <user_callback_function_name> (shared_memory_callback_args_t * p_args);

This callback function is invoked when the handshaking is completed and data is written. shared_memory_ready_t state in shared_memory_callback_args_t is useful to separate these cases.

3. Use API function

a) Open operation

To use shared memory, R_SHARED_MEMORY_Open() needs to be invoked on each CPU.

The driver determines if both drivers are open by accessing the shared memory space. Later opened driver sends an interrupt signal to the another CPU and the callback function is invoked.

Open operation

Attention

Do not write or erase data of the shared memory area by outside this module.

b) Read / Write operation

When one driver writes data to the shared memory with R_SHARED_MEMORY_Write(), it sends an interrupt signal to the another CPU and the callback function is invoked to notify the completion of data writing.

The another driver reads out the data via R_SHARED_MEMORY_Read().

Read / Write operation

c) Check the state of drivers

R_SHARED_MEMORY_StatusGet() provides an interface to get the status of the driver.

Examples

Basic Example

This is a basic example of minimal use of the shared memory module in CPU0 application.

volatile bool g_shared_memory_data_receive_flag = false;

void r_shared_memory_basic_example (void)
{
    fsp_err_t              err;
    shared_memory_status_t status;
    uint32_t               offset = 0;
    uint8_t                transmit_buffer[SHARED_MEMORY_SIZE] = {0};
    uint8_t                receive_buffer[SHARED_MEMORY_SIZE]  = {0};

    for (uint32_t i = 0; i < SHARED_MEMORY_SIZE; i++)
    {
        transmit_buffer[i] = (uint8_t) i;
    }

    /* Open the driver. */
    err = R_SHARED_MEMORY_Open(&g_shared_memory0_ctrl, &g_shared_memory0_cfg);
    handle_error(err);

    /* Wait until the driver of CPU1 opens. */
    do
    {
        err = R_SHARED_MEMORY_StatusGet(&g_shared_memory0_ctrl, &status);
        handle_error(err);
    } while (SHARED_MEMORY_STATE_READY_TO_WRITE != status.state);

    /* Write data to the shared memory. */
    err = R_SHARED_MEMORY_Write(&g_shared_memory0_ctrl, transmit_buffer, offset, SHARED_MEMORY_SIZE);
    handle_error(err);

    while (!g_shared_memory_data_receive_flag)
    {
        /* Wait until the driver of CPU1 writes data. */
    }

    g_shared_memory_data_receive_flag = false;

    /* Read data from the shared memory. */
    err = R_SHARED_MEMORY_Read(&g_shared_memory0_ctrl, receive_buffer, offset, SHARED_MEMORY_SIZE);
    handle_error(err);
}

void example_callback (shared_memory_callback_args_t * p_args)
{
    if (SHARED_MEMORY_STATE_READY_TO_READ_WRITE == p_args->state)
    {
        g_shared_memory_data_receive_flag = true;
    }
    else
    {
        /* do nothing */
    }
}

This is a basic example of minimal use of the shared memory module in CPU1 application.

volatile bool g_shared_memory_data_receive_flag = false;

void r_shared_memory_basic_example (void)
{
    fsp_err_t err;
    uint32_t  offset = 0;
    uint8_t   transmit_buffer[SHARED_MEMORY_SIZE] = {0};
    uint8_t   receive_buffer[SHARED_MEMORY_SIZE]  = {0};

    for (uint32_t i = 0; i < SHARED_MEMORY_SIZE; i++)
    {
        transmit_buffer[i] = (uint8_t) ~i;
    }

    /* Open the driver. */
    err = R_SHARED_MEMORY_Open(&g_shared_memory0_ctrl, &g_shared_memory0_cfg);
    handle_error(err);

    while (!g_shared_memory_data_receive_flag)
    {
        /* Wait until the driver of CPU0 writes data. */
    }

    g_shared_memory_data_receive_flag = false;

    /* Read data from the shared memory. */
    err = R_SHARED_MEMORY_Read(&g_shared_memory0_ctrl, receive_buffer, offset, SHARED_MEMORY_SIZE);
    handle_error(err);

    /* Write data to the shared memory. */
    err = R_SHARED_MEMORY_Write(&g_shared_memory0_ctrl, transmit_buffer, offset, SHARED_MEMORY_SIZE);
    handle_error(err);
}

void example_callback (shared_memory_callback_args_t * p_args)
{
    if (SHARED_MEMORY_STATE_READY_TO_READ_WRITE == p_args->state)
    {
        g_shared_memory_data_receive_flag = true;
    }
    else
    {
        /* do nothing */
    }
}

Function Documentation

R_SHARED_MEMORY_Open()

fsp_err_t R_SHARED_MEMORY_Open	(	shared_memory_ctrl_t *const	p_ctrl,
		shared_memory_cfg_t const *const	p_cfg
	)

Opens the shared memory driver. Implements shared_memory_api_t::open().

Return values

FSP_SUCCESS	Module opened successfully.
FSP_ERR_ALREADY_OPEN	Module is already open.
FSP_ERR_IN_USE	Semaphore registor selected in configuration is in use.
FSP_ERR_ASSERTION	Parameter check failure due to one or more reasons below: p_ctrl or p_cfg is NULL. extended parameter is NULL. Callback parameter is NULL.

Returns

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

• icu_inter_cpu_irq_api_t::open
• icu_inter_cpu_irq_api_t::generate

R_SHARED_MEMORY_Read()

fsp_err_t R_SHARED_MEMORY_Read	(	shared_memory_ctrl_t *const	p_ctrl,
		uint8_t *const	p_dest,
		uint32_t const	offset,
		uint32_t const	bytes
	)

Performs a read from the shared memory. Implements shared_memory_api_t::read().

Return values

FSP_SUCCESS	Function executed without issue
FSP_ERR_ASSERTION	p_ctrl or p_dest is NULL.
FSP_ERR_INVALID_ARGUMENT	Invalid input parameter.
FSP_ERR_IN_USE	Another transfer was in progress.
FSP_ERR_NOT_OPEN	Module is not open.

R_SHARED_MEMORY_Write()

fsp_err_t R_SHARED_MEMORY_Write	(	shared_memory_ctrl_t *const	p_ctrl,
		uint8_t *const	p_src,
		uint32_t const	offset,
		uint32_t const	bytes
	)

Performs a write to the shared memory. Implements shared_memory_api_t::write().

Return values

FSP_SUCCESS	Function executed without issue.
FSP_ERR_ASSERTION	p_ctrl or p_src is NULL.
FSP_ERR_INVALID_ARGUMENT	Invalid input parameter.
FSP_ERR_IN_USE	Another transfer was in progress.
FSP_ERR_NOT_OPEN	Module is not open.

R_SHARED_MEMORY_StatusGet()

fsp_err_t R_SHARED_MEMORY_StatusGet	(	shared_memory_ctrl_t *const	p_ctrl,
		shared_memory_status_t *	p_status
	)

Provides driver status. Implements shared_memory_api_t::statusGet().

Return values

FSP_SUCCESS	Status is stored in p_status.
FSP_ERR_ASSERTION	p_ctrl or p_status is NULL.
FSP_ERR_NOT_OPEN	Module is not open.

R_SHARED_MEMORY_CallbackSet()

fsp_err_t R_SHARED_MEMORY_CallbackSet	(	shared_memory_ctrl_t *const	p_ctrl,
		void(*)(shared_memory_callback_args_t *)	p_callback,
		void const *const	p_context,
		shared_memory_callback_args_t *const	p_callback_memory
	)

Updates the user callback and has option of providing memory for callback structure. Implements shared_memory_api_t::callbackSet

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.

R_SHARED_MEMORY_Close()

fsp_err_t R_SHARED_MEMORY_Close

(

shared_memory_ctrl_t *const

p_ctrl

)

Closes the SHARED_MEMORY. Implements shared_memory_api_t::close().

Return values

FSP_SUCCESS	Module closed successfully.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_ASSERTION	p_ctrl is NULL.