Data Operation Circuit (r_doc)

Functions
fsp_err_t	R_DOC_Open (doc_ctrl_t *const p_api_ctrl, doc_cfg_t const *const p_cfg)
fsp_err_t	R_DOC_Close (doc_ctrl_t *const p_api_ctrl)
fsp_err_t	R_DOC_Read (doc_ctrl_t *const p_api_ctrl, uint32_t *p_result)
fsp_err_t	R_DOC_Write (doc_ctrl_t *const p_api_ctrl, uint32_t data)
fsp_err_t	R_DOC_CallbackSet (doc_ctrl_t *const p_api_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 RA MCUs. This module implements the DOC Interface.

Overview

Features

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

• Comparison Mode
  • Data is equal to the configured reference data setting.
  • Data is not equal to the configured reference data setting.
  • Data is less than the configured reference data setting².
  • Data is greater than the configured reference data setting².
  • Data is inside of a configurable pair of reference data settings².
  • Data is outside of a configurable pair of reference data settings².
• Addition Mode - Overflow of an addition operation
• Subtraction Mode - Underflow of a subtraction operation

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

Note

1. Operating on 32-bit data is not supported on all MCUs.

2. This comparison mode is not supported on all MCUs.

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.

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). 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_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 an integer greater than or equal to 0.	0	Enter Initial Value for Addition/Subtraction or enter reference value for comparison.
Additional Reference Data	Value must be an integer greater than or equal to 0.	0	Additional reference data used for Window Compare modes.
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.
DOC Interrupt Priority	MCU Specific Options		Select the DOC interrupt priority.

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

DMAC/DTC Integration

DOC can be used with Transfer (r_dmac) or Transfer (r_dtc) 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 DTC/DMAC, set transfer_info_t::p_dest to R_DOC->DODIR.

Examples

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

void basic_example (void)
{
    fsp_err_t 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 any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == 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);
        assert(FSP_SUCCESS == err);


        if (g_callback_event_counter >= 1)
        {

            uint32_t result;

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

        }
    }
}

Function Documentation

R_DOC_Open()

fsp_err_t R_DOC_Open	(	doc_ctrl_t *const	p_api_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.

Example:

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

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_api_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 NVIC.

R_DOC_Read()

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

Returns the result of addition/subtraction.

Example:

            uint32_t result;

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

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_api_ctrl,
		uint32_t	data
	)

Writes to the DODIR - DOC Input Register.

Example:

        err = R_DOC_Write(&g_doc_ctrl, DOC_EXAMPLE_VALUE);
        assert(FSP_SUCCESS == err);

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_api_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.
FSP_ERR_NO_CALLBACK_MEMORY	p_callback is non-secure and p_callback_memory is either secure or NULL.