Thread Monitor Framework

Framework module providing monitoring of threads. More...

Data Structures
struct	sf_thread_monitor_instance_ctrl_t

Macros
#define	SF_THREAD_MONITOR_CODE_VERSION_MAJOR   (2U)

Functions
void	SF_THREAD_MONITOR_Thread (ULONG thread_input)
	The SF_THREAD_MONITOR_thread() is the main thread monitor thread which runs periodically. More...
ssp_err_t	SF_THREAD_MONITOR_Open (sf_thread_monitor_ctrl_t *const p_api_ctrl, sf_thread_monitor_cfg_t const *const p_cfg)
	Calls the driver .open function in the p_lower_lvl_wdt parameter. More...
ssp_err_t	SF_THREAD_MONITOR_Close (sf_thread_monitor_ctrl_t *const p_api_ctrl)
	Stop the thread monitoring thread. All threads are unregistered and no longer monitored. More...
ssp_err_t	SF_THREAD_MONITOR_ThreadRegister (sf_thread_monitor_ctrl_t *const p_api_ctrl, sf_thread_monitor_counter_min_max_t const *p_counter_min_max)
	Register a thread to be monitored by the watchdog monitoring thread. More...
ssp_err_t	SF_THREAD_MONITOR_ThreadUnregister (sf_thread_monitor_ctrl_t *const p_api_ctrl)
	Remove a thread from being monitored by the Watchdog monitoring thread. More...
ssp_err_t	SF_THREAD_MONITOR_CountIncrement (sf_thread_monitor_ctrl_t *const p_api_ctrl)
	Safely increment the counter of a thread. A mutex is used to ensure this increment occurs without corruption. More...
ssp_err_t	SF_THREAD_MONITOR_VersionGet (ssp_version_t *const p_version)
	Get version and store it in provided pointer p_version. Implements sf_thread_monitor_api_t::versionGet. More...

Detailed Description

Framework module providing monitoring of threads.

Any misbehaving threads result in the device being reset. Both the WDT and IWDT HAL modules are supported by this framework module.

Interface Used

See also

WDT Interface

Macro Definition Documentation

SF_THREAD_MONITOR_CODE_VERSION_MAJOR

#define SF_THREAD_MONITOR_CODE_VERSION_MAJOR   (2U)

Version of code that implements the API defined in this file

Function Documentation

SF_THREAD_MONITOR_Close()

ssp_err_t SF_THREAD_MONITOR_Close

(

sf_thread_monitor_ctrl_t *const

p_api_ctrl

)

Stop the thread monitoring thread. All threads are unregistered and no longer monitored.

Return values

SSP_SUCCESS	Close was successful and watchdog monitoring thread has stopped.
SSP_ERR_ASSERTION	p_ctrl pointer is NULL.
SSP_ERR_NOT_OPEN	SF_THREAD_MONITOR_Open() has either not been called or it was not called successfully.

Returns

See Common Error Codes or HAL driver for other possible return codes or causes.

Note

This function is not reentrant.

This function DOES NOT stop the watchdog timer (e.g. WDT or IWDT). It does however stop the thread which refreshes the these timers. To prevent the hardware watchdog from reseting the device the watchdog must be refreshed elsewhere.

The Thread Monitor can be closed with SF_THREAD_MONITOR_Close(). However, if the underlying watchdog timer hardware such as WDT or IWDT cannot be closed or stopped then there are likely to be undesirable results.

SF_THREAD_MONITOR_CountIncrement()

ssp_err_t SF_THREAD_MONITOR_CountIncrement

(

sf_thread_monitor_ctrl_t *const

p_api_ctrl

)

Safely increment the counter of a thread. A mutex is used to ensure this increment occurs without corruption.

Return values

SSP_SUCCESS	Thread counter successfully incremented.
SSP_ERR_ASSERTION	p_ctrl pointer is NULL.
SSP_ERR_INSUFFICIENT_SPACE	Not enough entries in the threads to be monitored array to add this thread.
SSP_ERR_NOT_OPEN	SF_THREAD_MONITOR_Open() has either not been called or it was not called successfully.
SSP_ERR_INTERNAL	An internal ThreadX error has occurred.

Returns

See Common Error Codes or HAL driver for other possible return codes or causes.

Note

This function is reentrant.

SF_THREAD_MONITOR_Open()

ssp_err_t SF_THREAD_MONITOR_Open	(	sf_thread_monitor_ctrl_t *const	p_api_ctrl,
		sf_thread_monitor_cfg_t const *const	p_cfg
	)

Calls the driver .open function in the p_lower_lvl_wdt parameter.

After successively opening and configuring the HAL driver, the SF_THREAD_MONITOR_Open() function starts the thread monitoring thread. This thread is responsible for checking thread execution through thread count variables and for refreshing the implemented watchdog timer peripheral.

Return values

SSP_SUCCESS	Initialization was successful and watchdog monitoring thread has started.
SSP_ERR_ASSERTION	p_ctrl, p_cfg, p_cfg->p_lower_lvl_wdt pointers and/or p_cfg->p_lower_lvl_wdt are NULL.
SSP_ERR_IN_USE	Thread monitor has already been opened.
SSP_ERR_INVALID_MODE	Low level watchdog peripheral returned an error when opened.
SSP_ERR_UNSUPPORTED	Data structure could not be allocated.
SSP_ERR_INVALID_ARGUMENT	One or more configuration options is invalid for the low level driver.
SSP_ERR_INTERNAL	An internal ThreadX error has occurred.

Returns

See Common Error Codes or HAL driver for other possible return codes or causes.

Note

This function is not reentrant.

If there are no threads registered to be monitored the monitoring thread refreshes the watchdog and prevents the watchdog from reseting the device.

The Thread Monitor can be closed with SF_THREAD_MONITOR_Close and then SF_THREAD_MONITOR_Open can be called again. However, if the underlying watchdog timer hardware such as WDT or IWDT cannot be closed or stopped then there are likely to be undesirable results.

SF_THREAD_MONITOR_Thread()

void SF_THREAD_MONITOR_Thread

(

ULONG

thread_input

)

The SF_THREAD_MONITOR_thread() is the main thread monitor thread which runs periodically.

The period is determined from the timeout period of the Watchdog hardware. This thread's period should be half of that of the watchdog hardware so the watchdog is refreshed at 50% of the count value.

Parameters

[in]

thread_input

This is the address of the control block for the thread monitor module. This allows this thread to be created multiple times with the data used and hardware interfaced with governed by the control structure.

As this is a ThreadX thread this function does not return.

Note

This function is not reentrant.

If there are no threads registered to be monitored the monitoring thread will refresh/tickle/kick the watchdog and so prevent the watchdog from reseting the device.

SF_THREAD_MONITOR_ThreadRegister()

ssp_err_t SF_THREAD_MONITOR_ThreadRegister	(	sf_thread_monitor_ctrl_t *const	p_api_ctrl,
		sf_thread_monitor_counter_min_max_t const *	p_counter_min_max
	)

Register a thread to be monitored by the watchdog monitoring thread.

This thread must supply the minimum and maximum expected values for the thread. The mininimum and maximum values can be determined by using monitoring mode.

Return values

SSP_SUCCESS	Thread successfully registered.
SSP_ERR_ASSERTION	p_ctrl or p_counter_min_max pointers are NULL.
SSP_ERR_INSUFFICIENT_SPACE	Not enough entries in the threads to be monitored array to add this thread. Increase the value of THREAD_MONITOR_CFG_MAX_NUMBER_OF_THREADS in sf_thread_moinitor_cfg.h
SSP_ERR_NOT_OPEN	SF_THREAD_MONITOR_Open() has either not been called or it was not called successfully.
SSP_ERR_INTERNAL	An internal ThreadX error has occurred.

Returns

See Common Error Codes or HAL driver for other possible return codes or causes.

Note

This function is reentrant.

SF_THREAD_MONITOR_ThreadUnregister()

ssp_err_t SF_THREAD_MONITOR_ThreadUnregister

(

sf_thread_monitor_ctrl_t *const

p_api_ctrl

)

Remove a thread from being monitored by the Watchdog monitoring thread.

Return values

SSP_SUCCESS	Thread successfully unregistered.
SSP_ERR_ASSERTION	p_ctrl pointer is NULL.
SSP_ERR_NOT_OPEN	SF_THREAD_MONITOR_Open() has either not been called or it was not called successfully.
SSP_ERR_INTERNAL	An internal ThreadX error has occurred.

Returns

See Common Error Codes or HAL driver for other possible return codes or causes.

Note

This function is reentrant.

SF_THREAD_MONITOR_VersionGet()

ssp_err_t SF_THREAD_MONITOR_VersionGet

(

ssp_version_t *const

p_version

)

Get version and store it in provided pointer p_version. Implements sf_thread_monitor_api_t::versionGet.

Return values

SSP_SUCCESS	Version returned successfully.
SSP_ERR_ASSERTION	Parameter p_version was null.