RA Flexible Software Package Documentation  Release v3.7.0

 
Watchdog (r_wdt)

Functions

fsp_err_t R_WDT_Open (wdt_ctrl_t *const p_ctrl, wdt_cfg_t const *const p_cfg)
 
fsp_err_t R_WDT_TimeoutGet (wdt_ctrl_t *const p_ctrl, wdt_timeout_values_t *const p_timeout)
 
fsp_err_t R_WDT_Refresh (wdt_ctrl_t *const p_ctrl)
 
fsp_err_t R_WDT_StatusGet (wdt_ctrl_t *const p_ctrl, wdt_status_t *const p_status)
 
fsp_err_t R_WDT_StatusClear (wdt_ctrl_t *const p_ctrl, const wdt_status_t status)
 
fsp_err_t R_WDT_CounterGet (wdt_ctrl_t *const p_ctrl, uint32_t *const p_count)
 
fsp_err_t R_WDT_CallbackSet (wdt_ctrl_t *const p_ctrl, void(*p_callback)(wdt_callback_args_t *), void const *const p_context, wdt_callback_args_t *const p_callback_memory)
 

Detailed Description

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

Overview

The watchdog timer is used to recover from unexpected errors in an application. The watchdog timer must be refreshed periodically in the permitted count window by the application. If the count is allowed to underflow or refresh occurs outside of the valid refresh period, the WDT resets the device or generates an NMI.

r_wdt_operation_example.png
Watchdog Timer Operation Example

Features

The WDT HAL module has the following key features:

Selecting a Watchdog

RA MCUs have two watchdog peripherals: the watchdog timer (WDT) and the independent watchdog timer (IWDT). When selecting between them, consider these factors:

WDT IWDT
Start ModeThe WDT can be started from the application (register start mode) or configured by hardware to start automatically (auto start mode). The IWDT can only be configured by hardware to start automatically.
Clock SourceThe WDT runs off a peripheral clock.The IWDT has its own clock source which improves safety.

Configuration

When using register start mode, configure the watchdog timer on the Stacks tab.

Note
When using auto start mode, configurations on the Stacks tab are ignored. Configure the watchdog using the OFS settings on the BSP tab.

Build Time Configurations for r_wdt

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

ConfigurationOptionsDefaultDescription
Parameter Checking
  • Default (BSP)
  • Enabled
  • Disabled
Default (BSP) If selected code for parameter checking is included in the build.
Register Start NMI Support
  • Enabled
  • Disabled
Disabled If enabled, code for NMI support in register start mode is included in the build.

Configurations for Monitoring > Watchdog (r_wdt)

This module can be added to the Stacks tab via New Stack > Monitoring > Watchdog (r_wdt). 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_wdt0 Module name.
Timeout
  • 1,024 Cycles
  • 4,096 Cycles
  • 8,192 Cycles
  • 16,384 Cycles
16,384 Cycles Select the watchdog timeout in cycles.
Clock Division Ratio
  • PCLK/4
  • PCLK/64
  • PCLK/128
  • PCLK/512
  • PCLK/2048
  • PCLK/8192
PCLK/8192 Select the watchdog clock divisor.
Window Start Position
  • 100% (Window Position Not Specified)
  • 75%
  • 50%
  • 25
100% (Window Position Not Specified) Select the allowed watchdog refresh start point.
Window End Position
  • 0% (Window Position Not Specified)
  • 25%
  • 50%
  • 75%
0% (Window Position Not Specified) Select the allowed watchdog refresh end point.
Reset Control
  • Reset Output
  • NMI Generated
Reset Output Select what happens when the watchdog timer expires.
Stop Control
  • WDT Count Enabled in Low Power Mode
  • WDT Count Disabled in Low Power Mode
WDT Count Disabled in Low Power Mode Select the watchdog state in low power mode.
NMI CallbackName must be a valid C symbolNULL A user callback function must be provided if the WDT is configured to generate an NMI when the timer underflows or a refresh error occurs. If this callback function is provided, it will be called from the NMI handler each time the watchdog triggers.

Clock Configuration

The WDT clock is based on the PCLKB frequency. You can set the PCLKB frequency using the Clocks tab of the RA Configuration editor or by using the CGC Interface at run-time. The maximum timeout period with PCLKB running at 60 MHz is approximately 2.2 seconds.

Pin Configuration

This module does not use I/O pins.

Usage Notes

NMI Interrupt

The watchdog timer uses the NMI, which is enabled by default. No special configuration is required. When the NMI is triggered, the callback function registered during open is called.

Note
When using the WDT in software start mode with NMI and the timer underflows, the WDT status must be reset by calling R_WDT_StatusClear before restarting the timer via R_WDT_Refresh.

Period Calculation

The WDT operates from PCLKB. With a PCLKB of 60 MHz, the maximum time from the last refresh to device reset or NMI generation will be just over 2.2 seconds as detailed below.

PLCKB = 60 MHz
Clock division ratio = PCLKB / 8192
Timeout period = 16384 cycles
WDT clock frequency = 60 MHz / 8192 = 7.324 kHz
Cycle time = 1 / 7.324 kHz = 136.53 us
Timeout = 136.53 us x 16384 cycles = 2.23 seconds

Limitations

Developers should be aware of the following limitations when using the WDT:

Examples

WDT Basic Example

This is a basic example of minimal use of the WDT in an application.

void wdt_basic_example (void)
{
fsp_err_t err = FSP_SUCCESS;
/* In auto start mode, the WDT starts counting immediately when the MCU is powered on. */
/* Initializes the module. */
err = R_WDT_Open(&g_wdt0_ctrl, &g_wdt0_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* In register start mode, start the watchdog by calling R_WDT_Refresh. */
err = R_WDT_Refresh(&g_wdt0_ctrl);
assert(FSP_SUCCESS == err);
while (true)
{
/* Application work here. */
/* Refresh before the counter underflows to prevent reset or NMI. */
err = R_WDT_Refresh(&g_wdt0_ctrl);
assert(FSP_SUCCESS == err);
}
}

WDT Advanced Example

This example demonstrates using a start window and gives an example callback to handle an NMI generated by an underflow or refresh error.

#define WDT_TIMEOUT_COUNTS (16384U)
#define WDT_MAX_COUNTER (WDT_TIMEOUT_COUNTS - 1U)
#define WDT_START_WINDOW_75 ((WDT_MAX_COUNTER * 3) / 4)
/* Example callback called when a watchdog NMI occurs. */
void wdt_callback (wdt_callback_args_t * p_args)
{
fsp_err_t err = FSP_SUCCESS;
/* (Optional) Determine the source of the NMI. */
err = R_WDT_StatusGet(&g_wdt0_ctrl, &status);
assert(FSP_SUCCESS == err);
/* (Optional) Log source of NMI and any other debug information. */
/* (Optional) Clear the error flags. */
err = R_WDT_StatusClear(&g_wdt0_ctrl, status);
assert(FSP_SUCCESS == err);
/* (Register start mode) In register start mode, call R_WDT_Refresh() to
* continue using the watchdog after an error. */
err = R_WDT_Refresh(&g_wdt0_ctrl);
assert(FSP_SUCCESS == err);
/* (Optional) Issue a software reset to reset the MCU. */
__NVIC_SystemReset();
}
void wdt_advanced_example (void)
{
fsp_err_t err = FSP_SUCCESS;
/* (Optional) Enable the WDT to count and generate NMI or reset when the
* debugger is connected. */
R_DEBUG->DBGSTOPCR_b.DBGSTOP_WDT = 0;
/* (Optional) Check if the WDTRF flag is set to know if the system is
* recovering from a WDT reset. */
if (R_SYSTEM->RSTSR1_b.WDTRF)
{
/* Clear the flag. */
R_SYSTEM->RSTSR1 = 0U;
}
/* Open the module. */
err = R_WDT_Open(&g_wdt0_ctrl, &g_wdt0_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* Initialize other application code. */
/* (Register start mode) Call R_WDT_Refresh() to start the WDT in register
* start mode. Do not call R_WDT_Refresh() in auto start mode unless the
* counter is in the acceptable refresh window. */
err = R_WDT_Refresh(&g_wdt0_ctrl);
assert(FSP_SUCCESS == err);
while (true)
{
/* Application work here. */
/* (Optional) If there is a chance the application takes less time than
* the start window, verify the WDT counter is past the start window
* before refreshing the WDT. */
uint32_t wdt_counter = 0U;
do
{
/* Read the current WDT counter value. */
err = R_WDT_CounterGet(&g_wdt0_ctrl, &wdt_counter);
assert(FSP_SUCCESS == err);
} while (wdt_counter >= WDT_START_WINDOW_75);
/* Refresh before the counter underflows to prevent reset or NMI. */
err = R_WDT_Refresh(&g_wdt0_ctrl);
assert(FSP_SUCCESS == err);
}
}

Data Structures

struct  wdt_instance_ctrl_t
 

Data Structure Documentation

◆ wdt_instance_ctrl_t

struct wdt_instance_ctrl_t

WDT private control block. DO NOT MODIFY. Initialization occurs when R_WDT_Open() is called.

Function Documentation

◆ R_WDT_Open()

fsp_err_t R_WDT_Open ( wdt_ctrl_t *const  p_ctrl,
wdt_cfg_t const *const  p_cfg 
)

Configure the WDT in register start mode. In auto-start_mode the NMI callback can be registered. Implements wdt_api_t::open.

This function should only be called once as WDT configuration registers can only be written to once so subsequent calls will have no effect.

Example:

/* Initializes the module. */
err = R_WDT_Open(&g_wdt0_ctrl, &g_wdt0_cfg);
Return values
FSP_SUCCESSWDT successfully configured.
FSP_ERR_ASSERTIONNull pointer, or one or more configuration options is invalid.
FSP_ERR_ALREADY_OPENModule is already open. This module can only be opened once.
FSP_ERR_INVALID_STATEThe security state of the NMI and the module do not match.
Note
In auto start mode the only valid configuration option is for registering the callback for the NMI ISR if NMI output has been selected.

◆ R_WDT_TimeoutGet()

fsp_err_t R_WDT_TimeoutGet ( wdt_ctrl_t *const  p_ctrl,
wdt_timeout_values_t *const  p_timeout 
)

Read timeout information for the watchdog timer. Implements wdt_api_t::timeoutGet.

Return values
FSP_SUCCESSWDT timeout information retrieved successfully.
FSP_ERR_ASSERTIONNull Pointer.
FSP_ERR_NOT_OPENInstance control block is not initialized.

◆ R_WDT_Refresh()

fsp_err_t R_WDT_Refresh ( wdt_ctrl_t *const  p_ctrl)

Refresh the watchdog timer. Implements wdt_api_t::refresh.

In addition to refreshing the watchdog counter this function can be used to start the counter in register start mode.

Example:

/* Refresh before the counter underflows to prevent reset or NMI. */
err = R_WDT_Refresh(&g_wdt0_ctrl);
assert(FSP_SUCCESS == err);
Return values
FSP_SUCCESSWDT successfully refreshed.
FSP_ERR_ASSERTIONp_ctrl is NULL.
FSP_ERR_NOT_OPENInstance control block is not initialized.
Note
This function only returns FSP_SUCCESS. If the refresh fails due to being performed outside of the permitted refresh period the device will either reset or trigger an NMI ISR to run.

◆ R_WDT_StatusGet()

fsp_err_t R_WDT_StatusGet ( wdt_ctrl_t *const  p_ctrl,
wdt_status_t *const  p_status 
)

Read the WDT status flags. Implements wdt_api_t::statusGet.

Indicates both status and error conditions.

Example:

/* (Optional) Determine the source of the NMI. */
err = R_WDT_StatusGet(&g_wdt0_ctrl, &status);
assert(FSP_SUCCESS == err);
Return values
FSP_SUCCESSWDT status successfully read.
FSP_ERR_ASSERTIONNull pointer as a parameter.
FSP_ERR_NOT_OPENInstance control block is not initialized.
FSP_ERR_UNSUPPORTEDThis function is only valid if the watchdog generates an NMI when an error occurs.
Note
When the WDT is configured to output a reset on underflow or refresh error reading the status and error flags serves no purpose as they will always indicate that no underflow has occurred and there is no refresh error. Reading the status and error flags is only valid when interrupt request output is enabled.

◆ R_WDT_StatusClear()

fsp_err_t R_WDT_StatusClear ( wdt_ctrl_t *const  p_ctrl,
const wdt_status_t  status 
)

Clear the WDT status and error flags. Implements wdt_api_t::statusClear.

Example:

/* (Optional) Clear the error flags. */
err = R_WDT_StatusClear(&g_wdt0_ctrl, status);
assert(FSP_SUCCESS == err);
Return values
FSP_SUCCESSWDT flag(s) successfully cleared.
FSP_ERR_ASSERTIONNull pointer as a parameter.
FSP_ERR_NOT_OPENInstance control block is not initialized.
FSP_ERR_UNSUPPORTEDThis function is only valid if the watchdog generates an NMI when an error occurs.
Note
When the WDT is configured to output a reset on underflow or refresh error reading the status and error flags serves no purpose as they will always indicate that no underflow has occurred and there is no refresh error. Reading the status and error flags is only valid when interrupt request output is enabled.

◆ R_WDT_CounterGet()

fsp_err_t R_WDT_CounterGet ( wdt_ctrl_t *const  p_ctrl,
uint32_t *const  p_count 
)

Read the current count value of the WDT. Implements wdt_api_t::counterGet.

Example:

/* Read the current WDT counter value. */
err = R_WDT_CounterGet(&g_wdt0_ctrl, &wdt_counter);
assert(FSP_SUCCESS == err);
Return values
FSP_SUCCESSWDT current count successfully read.
FSP_ERR_ASSERTIONNull pointer passed as a parameter.
FSP_ERR_NOT_OPENInstance control block is not initialized.

◆ R_WDT_CallbackSet()

fsp_err_t R_WDT_CallbackSet ( wdt_ctrl_t *const  p_ctrl,
void(*)(wdt_callback_args_t *)  p_callback,
void const *const  p_context,
wdt_callback_args_t *const  p_callback_memory 
)

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