Watchdog Service (rm_watchdog_service_w)

Functions
fsp_err_t	RM_WATCHDOG_SERVICE_W_Open (watchdog_service_ctrl_t *const p_api_ctrl, watchdog_service_cfg_t const *const p_cfg)
fsp_err_t	RM_WATCHDOG_SERVICE_W_Register (watchdog_service_ctrl_t *const p_api_ctrl, watchdog_service_cfg_t const *const p_cfg, uint8_t *p_id)
fsp_err_t	RM_WATCHDOG_SERVICE_W_Unregister (watchdog_service_ctrl_t *const p_api_ctrl, uint8_t id)
fsp_err_t	RM_WATCHDOG_SERVICE_W_Suspend (watchdog_service_ctrl_t *const p_api_ctrl, uint8_t id)
fsp_err_t	RM_WATCHDOG_SERVICE_W_Resume (watchdog_service_ctrl_t *const p_api_ctrl, uint8_t id)
fsp_err_t	RM_WATCHDOG_SERVICE_W_Notify (watchdog_service_ctrl_t *const p_api_ctrl, watchdog_service_cfg_t const *const p_cfg, uint8_t id)
fsp_err_t	RM_WATCHDOG_SERVICE_W_ResumeAndNotify (watchdog_service_ctrl_t *const p_api_ctrl, watchdog_service_cfg_t const *const p_cfg, uint8_t id)
fsp_err_t	RM_WATCHDOG_SERVICE_W_NotifyFromIdle (watchdog_service_ctrl_t *const p_api_ctrl, watchdog_service_cfg_t const *const p_cfg)
fsp_err_t	RM_WATCHDOG_SERVICE_W_SetLatency (watchdog_service_ctrl_t *const p_api_ctrl, uint8_t id, uint8_t latency)
fsp_err_t	RM_WATCHDOG_SERVICE_W_SetIdleId (watchdog_service_ctrl_t *const p_api_ctrl, uint8_t id)
fsp_err_t	RM_WATCHDOG_SERVICE_W_IsMonitorMaskEmpty (watchdog_service_ctrl_t *const p_api_ctrl)
void	rm_watchdog_service_w_nmi_reset (uint32_t *p_exception_args)

Detailed Description

Watchdog Service to monitor system tasks and avoid system freezes. This module implements the Watchdog Service Interface.

Overview

The Watchdog Service (rm_watchdog_service_w) runs on FreeRTOS and is designed to monitor system tasks and prevent system freezes. The Watchdog Service acts as a layer on top of the low-level watchdog timer driver, allowing multiple tasks (up to 64) to share the underlying hardware watchdog timer. The Watchdog Service can trigger a system reset, enabling the system to recover from catastrophic failures in one or more tasks.

To be monitored, a task must first register with the service to receive a unique handle (ID). The task must then periodically notify the Watchdog Service using this ID to signal that it is working properly.

The watchdog timer is essentially a countdown timer that triggers a system reset if it expires. To prevent this, the timer must be reset to its starting value before it expires. The timer's value is 400, which corresponds to approximately 4 seconds.

If all monitored tasks notify the Watchdog Service during a single watchdog period, the timer will be updated, and no system reset will be triggered for that period. However, if at least one task fails to notify the Watchdog Service in time, a system reset will be triggered.

Each task is responsible for periodically notifying the Watchdog Service that it is still running using the notify API. This must be done before the watchdog timer expires. Occasionally, a registered task may need to temporarily exclude itself from monitoring if it expects to be blocked for an extended period while waiting for an event. This is achieved using the suspend API.

The suspend API suspends monitoring of specific tasks in the Watchdog Service, as there is no need to monitor a task that is blocked waiting for an event that may take too long to occur (which would lead to the task failing to notify the Watchdog Service and resulting in a system reset). When the task is unblocked, the resume API should be called to restore task monitoring by the Watchdog Service. From that point on, the task must notify the Watchdog Service as usual.

Finally, the setLatency API is intended for cases where a task requires a watchdog period greater than the timer's reset value. Using this API allows a task to delay notification of the Watchdog Service for a specified number of watchdog periods without triggering a system reset. The effect of calling this API is one-time, so it must be set every time increased latency is required.

Features

The Watchdog Service module has the following key features:

• Register monitoring task
• Unregister monitoring task
• Suspend monitoring task
• Resume monitoring task
• Notify from monitoring task
• Notify from idle task

Configuration

Build Time Configurations for rm_watchdog_service_w

The following build time configurations are defined in fsp_cfg/rm_watchdog_service_w_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 > Watchdog Service (rm_watchdog_service_w)

This module can be added to the Stacks tab via New Stack > Monitoring > Watchdog Service (rm_watchdog_service_w).

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_watchdog_service0	Module name.

Clock Configuration

This module has no required clock configurations.

Pin Configuration

This module does not use I/O pins.

FreeRTOS Configuration

Note

Should enable configUSE_RECURSIVE_MUTEXES in FreeRTOSConfig.h.

Usage Notes

Limitations

Note

Should not use this the Watchdog Service APIs in interrupt context.

Examples

Watchdog Service Basic Example

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

void watchdog_service_w_basic_example (void)
{
    TaskHandle_t example_task;
    fsp_err_t    err;

    xTaskCreate(watchdog_service_w_basic_example_task,
                "Example task",
                (WATCHDOG_SERVICE_W_EXAMPLE_STACK_SIZE / 4),
                NULL,
                WATCHDOG_SERVICE_W_EXAMPLE_TASK_PRIORITY,
                &example_task);

    vTaskStartScheduler();


    /* Initialize and start the Watchdog Service. */
    err = RM_WATCHDOG_SERVICE_W_Open(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg);

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


    while (1);
}

void watchdog_service_w_basic_example_task (void * pvParameters)
{
    fsp_err_t err;
    uint8_t   id_task = WATCHDOG_SERVICE_W_NOT_REGISTERED_ID;


    /* Register monitoring task. */
    err = RM_WATCHDOG_SERVICE_W_Register(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg, &id_task);

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


    while (1)
    {

        /* Notify Watchdog Service from the task. */
        err = RM_WATCHDOG_SERVICE_W_Notify(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg, id_task);

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


        vTaskDelay(WATCHDOG_SERVICE_W_EXAMPLE_TASK_DELAY_TICK);
     }

    FSP_PARAMETER_NOT_USED(pvParameters);
}

Watchdog Service Advanced Example

This gives an advanced example of using APIs other than notify.

void watchdog_service_w_advanced_example (void)
{
    TaskHandle_t example_task;
    fsp_err_t    err;
    uint8_t      id_idle_task = WATCHDOG_SERVICE_W_NOT_REGISTERED_ID;

    xTaskCreate(watchdog_service_w_advanced_example_task,
                "Example task",
                (WATCHDOG_SERVICE_W_EXAMPLE_STACK_SIZE / 4),
                NULL,
                WATCHDOG_SERVICE_W_EXAMPLE_TASK_PRIORITY,
                &example_task);

    vTaskStartScheduler();

    /* Initialize and start the Watchdog Service. */
    err = RM_WATCHDOG_SERVICE_W_Open(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg);
    assert(FSP_SUCCESS == err);

    /* Register monitoring task. */
    err = RM_WATCHDOG_SERVICE_W_Register(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg, &id_idle_task);
    assert(FSP_SUCCESS == err);


    /* Set Idle task ID. */
    err = RM_WATCHDOG_SERVICE_W_SetIdleId(&g_watchdog_service0_ctrl, id_idle_task);

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


    while (1);
}

void vApplicationIdleHook (void)
{
    fsp_err_t err;


    /* Notify Watchdog Service from the idle task. */
    err = RM_WATCHDOG_SERVICE_W_NotifyFromIdle(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg);

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

}

void watchdog_service_w_advanced_example_task (void * pvParameters)
{
    fsp_err_t err;
    uint8_t   id_task = WATCHDOG_SERVICE_W_NOT_REGISTERED_ID;
    uint32_t  cnt     = 0;

    /* Register monitoring task. */
    err = RM_WATCHDOG_SERVICE_W_Register(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg, &id_task);

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

    while (1)
    {
        cnt++;

        switch (cnt % 6)
        {
            case 0:
                /* Notify Watchdog Service from the task. */
                err = RM_WATCHDOG_SERVICE_W_Notify(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg, id_task);

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

                break;
            case 1:

                /* Set watchdog latency. */
                err = RM_WATCHDOG_SERVICE_W_SetLatency(&g_watchdog_service0_ctrl, id_task, WATCHDOG_SERVICE_W_EXAMPLE_TASK_LATENCY);

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


                break;
            case 2:

                /* Suspend monitoring the task. */
                err = RM_WATCHDOG_SERVICE_W_Suspend(&g_watchdog_service0_ctrl, id_task);

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


                break;
            case 3:

                /* Resume monitoring the task. */
                err = RM_WATCHDOG_SERVICE_W_Resume(&g_watchdog_service0_ctrl, id_task);

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


                break;
            case 4:
                /* Suspend monitoring the task. */
                err = RM_WATCHDOG_SERVICE_W_Suspend(&g_watchdog_service0_ctrl, id_task);

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

                break;
            case 5:
            default:

                /*  Resume monitoring the task and notify the Watchdog Service from the task. */
                err = RM_WATCHDOG_SERVICE_W_ResumeAndNotify(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg, id_task);

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


                break;
        }

        if (cnt >= WATCHDOG_SERVICE_W_EXAMPLE_TASK_LOOP_COUNT)
        {

            /* Unregister monitored task. */
             err = RM_WATCHDOG_SERVICE_W_Unregister(&g_watchdog_service0_ctrl, id_task);

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


             vTaskDelete(NULL);
        }

        vTaskDelay(WATCHDOG_SERVICE_W_EXAMPLE_TASK_DELAY_TICK);
     }

    FSP_PARAMETER_NOT_USED(pvParameters);
}

Data Structures
struct	watchdog_service_w_instance_ctrl_t

Variables
volatile uint32_t	g_watchdog_service_w_nmi_event_data [9]

---

Data Structure Documentation

watchdog_service_w_instance_ctrl_t

struct watchdog_service_w_instance_ctrl_t

Private control block. DO NOT MODIFY. Initialization occurs when RM_WATCHDOG_SERVICE_W_Open() is called.

Data Fields
uint32_t	open	Indicates whether the open() API has been successfully called.
SemaphoreHandle_t	lock	Semaphore handle.
uint8_t	max_task_id	Current maximum value of task ID.
uint8_t	idle_task_id	Id of idle task.
uint32_t	tasks_mask[WATCHDOG_SERVICE_W_MAX_INDEX]	Bitmask of registered tasks identifiers.
uint32_t	tasks_monitored_mask[WATCHDOG_SERVICE_W_MAX_INDEX]	Bitmask of monitored tasks identifiers.
uint32_t	notified_mask[WATCHDOG_SERVICE_W_MAX_INDEX]	Bitmask of tasks which notified.
uint8_t	tasks_latency[WATCHDOG_SERVICE_W_MAX_TASKS]	Allowed latency set by tasks.
TaskHandle_t	tasks_handle[WATCHDOG_SERVICE_W_MAX_TASKS]	Handles of monitored tasks.

Function Documentation

RM_WATCHDOG_SERVICE_W_Open()

fsp_err_t RM_WATCHDOG_SERVICE_W_Open	(	watchdog_service_ctrl_t *const	p_api_ctrl,
		watchdog_service_cfg_t const *const	p_cfg
	)

Configure and start the Watchdog Service. This should be called before using the Watchdog Service, preferably at application startup.

Example:

    /* Initialize and start the Watchdog Service. */
    err = RM_WATCHDOG_SERVICE_W_Open(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg);

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

Return values

FSP_SUCCESS	Watchdog Service was opened successfully.
FSP_ERR_ASSERTION	NULL pointer to parameters in argument.
FSP_ERR_ALREADY_OPEN	Watchdog Service is already opened.
FSP_ERR_INVALID_STATE	Mutex was not created successfully.
FSP_ERR_INVALID_HW_CONDITION	HW WDT was not opened successfully.

Note

If this API returns FSP_SUCCESS, the Watchdog Service creates a mutex in ((watchdog_service_w_instance_ctrl_t *) p_api_ctrl)->lock. The Watchdog Service never delete the mutex.

RM_WATCHDOG_SERVICE_W_Register()

fsp_err_t RM_WATCHDOG_SERVICE_W_Register	(	watchdog_service_ctrl_t *const	p_api_ctrl,
		watchdog_service_cfg_t const *const	p_cfg,
		uint8_t *	p_id
	)

Register current task in the Watchdog Service. Returned id via argument p_id shall be used in all other Watchdog Service API calls from current task. Once registered, the task shall notify the Wathcdog Service periodically using notify API to prevent watchdog expiration. It is up to each task how this is done, but a task can request that it will be triggered periodically using the task notification capability, to notify the Watchdog Service back as a response.

Example:

    /* Register monitoring task. */
    err = RM_WATCHDOG_SERVICE_W_Register(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg, &id_task);

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

Return values

FSP_SUCCESS	Task was registered successfully.
FSP_ERR_ASSERTION	NULL pointer to parameters in argument.
FSP_ERR_NOT_OPEN	Watchdog Service is not opened.
FSP_ERR_IN_USE	Could not register a task because the registered tasks are full.

RM_WATCHDOG_SERVICE_W_Unregister()

fsp_err_t RM_WATCHDOG_SERVICE_W_Unregister	(	watchdog_service_ctrl_t *const	p_api_ctrl,
		uint8_t	id
	)

Unregister task from the Watchdog Service.

Example:

            /* Unregister monitored task. */
             err = RM_WATCHDOG_SERVICE_W_Unregister(&g_watchdog_service0_ctrl, id_task);

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

Return values

FSP_SUCCESS	Task was unregistered successfully.
FSP_ERR_ASSERTION	NULL pointer to parameters in argument.
FSP_ERR_NOT_OPEN	Watchdog Service is not opened.
FSP_ERR_INVALID_ARGUMENT	Id is out of range.

RM_WATCHDOG_SERVICE_W_Suspend()

fsp_err_t RM_WATCHDOG_SERVICE_W_Suspend	(	watchdog_service_ctrl_t *const	p_api_ctrl,
		uint8_t	id
	)

Suspend monitoring a task by the Watchdog Service. A monitor-suspended task is not unregistered entirely, but it is ignored by the Watchdog Service until its monitoring is resumed. It is faster than unregistering and registering the task again.

Example:

                /* Suspend monitoring the task. */
                err = RM_WATCHDOG_SERVICE_W_Suspend(&g_watchdog_service0_ctrl, id_task);

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

Return values

FSP_SUCCESS	Monitoring task was suspended successfully.
FSP_ERR_ASSERTION	NULL pointer to parameters in argument.
FSP_ERR_NOT_OPEN	Watchdog Service is not opened.
FSP_ERR_INVALID_ARGUMENT	Id is out of range.

RM_WATCHDOG_SERVICE_W_Resume()

fsp_err_t RM_WATCHDOG_SERVICE_W_Resume	(	watchdog_service_ctrl_t *const	p_api_ctrl,
		uint8_t	id
	)

Resume monitoring of a task by the Watchdog Service. It should be called as soon as the reason that suspend API was called is removed.

Example:

                /* Resume monitoring the task. */
                err = RM_WATCHDOG_SERVICE_W_Resume(&g_watchdog_service0_ctrl, id_task);

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

Return values

FSP_SUCCESS	Monitoring task was resumed successfully.
FSP_ERR_ASSERTION	NULL pointer to parameters in argument.
FSP_ERR_NOT_OPEN	Watchdog Service is not opened.
FSP_ERR_INVALID_ARGUMENT	Id is out of range.

RM_WATCHDOG_SERVICE_W_Notify()

fsp_err_t RM_WATCHDOG_SERVICE_W_Notify	(	watchdog_service_ctrl_t *const	p_api_ctrl,
		watchdog_service_cfg_t const *const	p_cfg,
		uint8_t	id
	)

Notify the Watchdog Service about a task. A registered task shall call this API periodically to notify the Watchdog Service that it is alive. This should be done frequently enough to fit into the watchdog timer interval.

Example:

        /* Notify Watchdog Service from the task. */
        err = RM_WATCHDOG_SERVICE_W_Notify(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg, id_task);

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

Return values

FSP_SUCCESS	Task notified successfully.
FSP_ERR_ASSERTION	NULL pointer to parameters in argument.
FSP_ERR_NOT_OPEN	Watchdog Service is not opened.
FSP_ERR_INVALID_ARGUMENT	Id is out of range.

RM_WATCHDOG_SERVICE_W_ResumeAndNotify()

fsp_err_t RM_WATCHDOG_SERVICE_W_ResumeAndNotify	(	watchdog_service_ctrl_t *const	p_api_ctrl,
		watchdog_service_cfg_t const *const	p_cfg,
		uint8_t	id
	)

Resume monitoring of a task and notify the Watchdog Service about the task.

Example:

                /*  Resume monitoring the task and notify the Watchdog Service from the task. */
                err = RM_WATCHDOG_SERVICE_W_ResumeAndNotify(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg, id_task);

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

Return values

FSP_SUCCESS	Resume monitoring task and task notified successfully.
FSP_ERR_ASSERTION	NULL pointer to parameters in argument.
FSP_ERR_NOT_OPEN	Watchdog Service is not opened.
FSP_ERR_INVALID_ARGUMENT	Id is out of range.

RM_WATCHDOG_SERVICE_W_NotifyFromIdle()

fsp_err_t RM_WATCHDOG_SERVICE_W_NotifyFromIdle	(	watchdog_service_ctrl_t *const	p_api_ctrl,
		watchdog_service_cfg_t const *const	p_cfg
	)

Notify the Watchdog Service about the idle task.

Example:

    /* Notify Watchdog Service from the idle task. */
    err = RM_WATCHDOG_SERVICE_W_NotifyFromIdle(&g_watchdog_service0_ctrl, &g_watchdog_service0_cfg);

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

Return values

FSP_SUCCESS	Idle task notified successfully.
FSP_ERR_ASSERTION	NULL pointer to parameters in argument.
FSP_ERR_NOT_OPEN	Watchdog Service is not opened.
FSP_ERR_INVALID_ARGUMENT	Id is out of range.

RM_WATCHDOG_SERVICE_W_SetLatency()

fsp_err_t RM_WATCHDOG_SERVICE_W_SetLatency	(	watchdog_service_ctrl_t *const	p_api_ctrl,
		uint8_t	id,
		uint8_t	latency
	)

Set watchdog latency for a task. This allows a task to miss a given number of notification periods to the Watchdog Service without triggering a system reset. Once set, the task is allowed to not notify the Watchdog Service for “latency” consecutive watchdog timer intervals. This option can be used to facilitate the operation of code that is expected to remain blocked for long periods of time (i.e. computation). This value is set once and does not reload automatically, thus it shall be set every time increased latency is required.

Example:

                /* Set watchdog latency. */
                err = RM_WATCHDOG_SERVICE_W_SetLatency(&g_watchdog_service0_ctrl, id_task, WATCHDOG_SERVICE_W_EXAMPLE_TASK_LATENCY);

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

Return values

FSP_SUCCESS	Set latency successfully.
FSP_ERR_ASSERTION	NULL pointer to parameters in argument.
FSP_ERR_NOT_OPEN	Watchdog Service is not opened.
FSP_ERR_INVALID_ARGUMENT	Id is out of range.

RM_WATCHDOG_SERVICE_W_SetIdleId()

fsp_err_t RM_WATCHDOG_SERVICE_W_SetIdleId	(	watchdog_service_ctrl_t *const	p_api_ctrl,
		uint8_t	id
	)

Set watchdog ID of the idle task.

Example:

    /* Set Idle task ID. */
    err = RM_WATCHDOG_SERVICE_W_SetIdleId(&g_watchdog_service0_ctrl, id_idle_task);

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

Return values

FSP_SUCCESS	Set idle id successfully.
FSP_ERR_ASSERTION	NULL pointer to parameters in argument.
FSP_ERR_NOT_OPEN	Watchdog Service is not opened.
FSP_ERR_INVALID_ARGUMENT	Id is out of range.

RM_WATCHDOG_SERVICE_W_IsMonitorMaskEmpty()

fsp_err_t RM_WATCHDOG_SERVICE_W_IsMonitorMaskEmpty

(

watchdog_service_ctrl_t *const

p_api_ctrl

)

Find out if the only task monitored is the idle task.

Return values

FSP_SUCCESS	Only the idle task is monitored.
FSP_ERR_IN_USE	Tasks other than the idle task are monitored.
FSP_ERR_ASSERTION	NULL pointer to parameters in argument.
FSP_ERR_NOT_OPEN	Watchdog Service is not opened.

rm_watchdog_service_w_nmi_reset()

void rm_watchdog_service_w_nmi_reset

(

uint32_t *

p_exception_args

)

Store system register values at WDT NMI and wait for system reset.

Parameters

[in]

p_exception_args

Pointer to system register values at NMI.

Variable Documentation

g_watchdog_service_w_nmi_event_data

volatile uint32_t g_watchdog_service_w_nmi_event_data[9]

Hold the stack contents when NMI occurs.