Data Operation Circuit (r_doc)

Functions
fsp_err_t	R_DOC_Open (doc_ctrl_t *const p_ctrl, doc_cfg_t const *const p_cfg)
fsp_err_t	R_DOC_Close (doc_ctrl_t *const p_ctrl)
fsp_err_t	R_DOC_Read (doc_ctrl_t *const p_ctrl, uint32_t *p_result)
fsp_err_t	R_DOC_Write (doc_ctrl_t *const p_ctrl, uint32_t data)
fsp_err_t	R_DOC_CallbackSet (doc_ctrl_t *const p_ctrl, void(*p_callback)(doc_callback_args_t *), void const *const p_context, doc_callback_args_t *const p_callback_memory)

Detailed Description

Driver for the DOC peripheral on RZ microprocessor. This module implements the DOC Interface.

Overview

Features

The DOC HAL module peripheral is used to compare, add or subtract 16-bit data and can detect the following events:

• A match or mismatch between data values
• Overflow of an addition operation
• Underflow of a subtraction operation

A user-defined callback can be created to inform the CPU when any of above events occur.

Configuration

Build Time Configurations for r_doc

The following build time configurations are defined in fsp_cfg/r_doc_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.
Multiplex Interrupt	Enabled Disabled	Disabled	Enable multiplex interrupt for a single driver.

Configurations for Monitoring > Data Operation Circuit (r_doc)

This module can be added to the Stacks tab via New Stack > Monitoring > Data Operation Circuit (r_doc).

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_doc0	Module name.
Event	MCU Specific Options		Select the event that will trigger the DOC interrupt.
Bit Width	MCU Specific Options		The bit width for DOC operations.
Reference/Initial Data	Value must be a 16 bit integer between 0 and 65535	0	Enter Initial Value for Addition/Subtraction or enter reference value for comparison.
Callback	Name must be a valid C symbol	NULL	A user callback function must be provided. This will be called from the interrupt service routine (ISR) when the configured DOC event occurs.

Clock Configuration

The DOC HAL module does not require a specific clock configuration.

Pin Configuration

The DOC HAL module does not require and specific pin configurations.

Usage Notes

Interrupt

The DOC outputs an error signal to the ICU. ICU can output PERI_ERRn interrupt (Peripherals error event n) to GIC or cause error reset when ICU accepts error signal from DOC. To use PERI_ERRn interrupt or reset at DOC, Interrupt Controller Unit (ICU) ERROR (r_icu_error) need to be configured. When the PERI_ERRn interrupt is configured to use interrupt and triggered, the callback function registered during open is called.

DMAC Integration

DOC can be used with Direct Memory Access Controller (r_dmac) to write to the input register without CPU intervention. DMAC is more useful for most DOC applications because it can be started directly from software. To write DOC input data with DMAC, set transfer_info_t::p_dest to R_DOC->DODIR.

Basic Example

This is a basic example of minimal use of the R_DOC in an application. This example shows how this driver can be used for continuous 16 bit addition operation while reading the result at every overflow event.

#define DOC_EXAMPLE_VALUE    0xF000

uint32_t g_callback_event_counter = 0;

/* This callback is called when DOC overflow event occurs. It is registered in doc_cfg_t when R_DOC_Open is
 * called. */
void doc_callback (doc_callback_args_t * p_args)
{
    FSP_PARAMETER_NOT_USED(p_args);

    g_callback_event_counter++;
}

/* This callback is also called when a DOC overflow event occurs. It is registered in error_cfg_t
 * when R_ICU_ERROR_Open is called. */
void error_callback (error_callback_args_t * p_args)
{
    if ((ERROR_EVENT_PERIPHERAL_1 == p_args->error_event) &&
        (ICU_ERROR_PERIPHERAL_ERROR_1_DOC_DOPCI == p_args->error_status))
    {
        R_ICU_ERROR_StatusClear(&g_error_ctrl, ERROR_EVENT_PERIPHERAL_1, ICU_ERROR_PERIPHERAL_ERROR_1_DOC_DOPCI);
    }
}

void basic_example (void)
{
    fsp_err_t err;

    /* Open the ICU_ERROR driver to configure behavior when the DOC event occurs. */
    err = R_ICU_ERROR_Open(&g_error_ctrl, &g_error_cfg);

    /* Handle any errors. This function should be defined by the user. */
    handle_error(err);


    /* Initialize the DOC module for addition with initial value specified in doc_cfg_t::doc_data. */
    err = R_DOC_Open(&g_doc_ctrl, &g_doc_cfg);


    handle_error(err);

    /* Write data to the DOC Data Input Register and read the result of addition from status register when an
     * interrupt occurs. */
    for (int i = 0; i < 5; i++)
    {
        err = R_DOC_Write(&g_doc_ctrl, DOC_EXAMPLE_VALUE);
        handle_error(err);


        /* When the CPU operation is fast, there is a time lag with the operation of the DOC module. */
        R_BSP_SoftwareDelay(1U, BSP_DELAY_UNITS_MICROSECONDS);

        if (g_callback_event_counter >= 1)
        {
            uint32_t result;


            /* Read the result of the operation */
            err = R_DOC_Read(&g_doc_ctrl, &result);
            handle_error(err);

        }
    }
}

Function Documentation

R_DOC_Open()

fsp_err_t R_DOC_Open	(	doc_ctrl_t *const	p_ctrl,
		doc_cfg_t const *const	p_cfg
	)

Opens and configures the Data Operation Circuit (DOC) in comparison, addition or subtraction mode and sets initial data for addition or subtraction, or reference data for comparison.

Return values

FSP_SUCCESS	DOC successfully configured.
FSP_ERR_ALREADY_OPEN	Module already open.
FSP_ERR_ASSERTION	One or more pointers point to NULL or callback is NULL or the interrupt vector is invalid.

R_DOC_Close()

fsp_err_t R_DOC_Close

(

doc_ctrl_t *const

p_ctrl

)

Closes the module driver. Enables module stop mode.

Return values

FSP_SUCCESS	Module successfully closed.
FSP_ERR_NOT_OPEN	Driver not open.
FSP_ERR_ASSERTION	Pointer pointing to NULL.

Note

This function will disable the DOC interrupt in the GIC.

R_DOC_Read()

fsp_err_t R_DOC_Read	(	doc_ctrl_t *const	p_ctrl,
		uint32_t *	p_result
	)

Returns the result of addition/subtraction.

Return values

FSP_SUCCESS	Status successfully read.
FSP_ERR_NOT_OPEN	Driver not open.
FSP_ERR_ASSERTION	One or more pointers point to NULL.

R_DOC_Write()

fsp_err_t R_DOC_Write	(	doc_ctrl_t *const	p_ctrl,
		uint32_t	data
	)

Writes to the DODIR - DOC Input Register.

Return values

FSP_SUCCESS	Values successfully written to the registers.
FSP_ERR_NOT_OPEN	Driver not open.
FSP_ERR_ASSERTION	One or more pointers point to NULL.

R_DOC_CallbackSet()

fsp_err_t R_DOC_CallbackSet	(	doc_ctrl_t *const	p_ctrl,
		void(*)(doc_callback_args_t *)	p_callback,
		void const *const	p_context,
		doc_callback_args_t *const	p_callback_memory
	)

Updates the user callback and has option of providing memory for callback structure. Implements doc_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.