RA Flexible Software Package Documentation  Release v5.1.0

 
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-bit1 data and can detect the following events:

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:

ConfigurationOptionsDefaultDescription
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.

ConfigurationOptionsDefaultDescription
NameName must be a valid C symbolg_doc0 Module name.
EventMCU Specific OptionsSelect the event that will trigger the DOC interrupt.
Bit WidthMCU Specific OptionsThe bit width for DOC operations.
Reference/Initial DataValue 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 DataValue must be an integer greater than or equal to 0.0 Additional reference data used for Window Compare modes.
CallbackName must be a valid C symbolNULL 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 PriorityMCU Specific OptionsSelect 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)
{
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_SUCCESSDOC successfully configured.
FSP_ERR_ALREADY_OPENModule already open.
FSP_ERR_ASSERTIONOne 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_SUCCESSModule successfully closed.
FSP_ERR_NOT_OPENDriver not open.
FSP_ERR_ASSERTIONPointer 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_SUCCESSStatus successfully read.
FSP_ERR_NOT_OPENDriver not open.
FSP_ERR_ASSERTIONOne 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_SUCCESSValues successfully written to the registers.
FSP_ERR_NOT_OPENDriver not open.
FSP_ERR_ASSERTIONOne 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_SUCCESSCallback updated successfully.
FSP_ERR_ASSERTIONA required pointer is NULL.
FSP_ERR_NOT_OPENThe control block has not been opened.
FSP_ERR_NO_CALLBACK_MEMORYp_callback is non-secure and p_callback_memory is either secure or NULL.