 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Thread Monitor Framework provides a high-level API for system monitoring applications using the watchdog timer (WDT) or independent watchdog timer (IWDT) to monitor program execution. The Thread Monitor Framework uses the WDT or IWDT peripherals on the Synergy MCU device.
The Thread Monitor Framework defines APIs for opening and closing the framework and registering and unregistering threads for monitoring. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of return status values follows the API summary table.
Thread Monitor Framework Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| open | g_sf_thread_monitor.p_api->open (g_sf_thread_monitor.p_ctrl,g_sf_thread_monitor.p_cfg);Configures the WDT or IWDT module. From the configuration data, the timeout period of the WDT/IWDT is determined. A thread created to monitor registered threads. |
| close | g_sf_thread_monitor.p_api->close (g_sf_thread_monitor.p_ctrl);Suspends the thread monitoring thread. The watchdog peripheral no longer refreshes. |
| threadRegister | g_sf_thread_monitor.p_api-> threadRegister (g_sf_thread_monitor.p_ctrl, &p_min_max_struct);Registers a thread for monitoring. |
| threadUnregister | g_sf_thread_monitor.p_api-> threadUnregister (g_sf_thread_monitor.p_ctrl);Removes a thread from monitoring. |
| countIncrement | g_sf_thread_monitor.p_api-> countIncrement (g_sf_thread_monitor.p_ctrl);Safely increments a monitored thread's count value. |
| versionGet | g_sf_thread_monitor.p_api-> versionGet(&version);Retrieves the API version and stores it in the version pointer. |
Status Return Values
| Name | Description |
|---|---|
| SSP_SUCCESS | API Call Successful. |
| SSP_ERR_ASSERTION | Pointer is null. |
| SSP_ERR_IN_USE | Thread monitor has already been opened. |
| SSP_ERR_INVALID_MODE | Low-level watchdog peripheral returns 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_NOT_OPEN | sf_thread_monitor_api_t::open has either not been called or was not called successfully. |
| SSP_ERR_INSUFFICIENT_SPACE | Not enough entries in the threads-to-be-monitored array to add this thread. Increases the value of THREAD_MONITOR_CFG_MAX_NUMBER_OF_THREADS in sf_thread_moinitor_cfg.h. |
The Thread Monitor performs as follows: a thread registers a counter variable with the thread monitor along with the minimum and maximum expected values for this counter variable. The thread which is monitored increments the counter variable while it runs. At a period of half the watchdog timeout period, the thread monitor checks the counter variables of registered threads. If any fall outside of the minimum and maximum values, the watchdog timer is allowed to reset the microcontroller. If all fall within their expected range, the watchdog timer is refreshed and the counter variables are cleared to zero.
The following figure shows a flowchart for the operation of the Thread Monitor Framework module.
The following figure shows when the WDT/IWDT refreshes. Note that the valid refresh period is the central 50% of the count period, 25% on either side of the 50% count value.
Internally, the Thread Monitor Framework runs at the rate of half of the watchdog timer reset period. This rate ensures the Thread Monitor Framework runs at 50% of the watchdog count value-well within the valid refresh window. The Thread Monitor calculates the reset period internally by querying the lower-level watchdog driver.
The thread monitor framework provides a method to keep track of the number of times a thread is registered. Any of the threads registered with the thread monitor framework need to call the sf_thread_monitor_api_t::countIncrement API to update a counter which is an indication of the number of times a specified thread was executed. A thread, which is part of the thread monitor framework would run at a predefined time interval and keeps the count value of the thread registered for monitoring. The monitor task will analyze count values taken over each interval and keeps track of the minimum and maximum counts obtained for each of the threads.
For example, consider a WDT configured with a time-out cycle of 16384 and clock division ratio of 8192. Assuming a PCLK of 60 MHz and time for a system tick to be 10 ms, the total number of ticks for WDT time out would be 223. Considering 50% of WDT time out, the thread monitor task would run at every 111 ticks to keep track of the threads registered for monitoring.
In a scenario where a simple thread executing a continuous loop with a sleep of 2 ticks in between each iteration, the max count value would be 56 (that is, 111/2).
When the thread monitor is run for the first time, it waits a full WDT time-out period of 111 counts (223 ticks) before activating the framework. This feature ensures proper working of WDT. In addition, whenever a new thread is registered, the max/min count value will not update unless the registered thread is activated from the thread monitor. This results in an additional delay of 56 counts (111 ticks).
This section describes how to include the Thread Monitor Framework Module in an application using the SSP configurator.
To add the Thread Monitor Framework to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the Thread Monitor Framework is g_sf_thread_monitor. This name can be changed in the associated Properties window.)
Thread Monitor Framework Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_thread_monitor0 Thread Monitor Framework | Threads | New Stack> Framework> Services> Thread Monitor Framework on sf_thread_monitor |
When the Thread Monitor Framework on sf_thread_monitor is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.
The Thread Monitor Framework Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.
Configuration Settings for the Thread Monitor Framework Module on sf_thread_monitor
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | Enabled, Disabled, BSP Default: BSP | Controls whether to include code for API parameter checking. |
| Maximum Number of Monitored Threads | 5 | Maximum number of threads that can be monitored. |
| Name | g_sf_thread_monitor0 | The name of the Thread Monitor instance. |
| Profiling Mode | Enabled, Disabled, Default: Disabled | Whether profiling mode should be enabled. |
| Thread Monitor Thread Priority | 1 | Priority of thread monitor internal thread. |
| Name of generated initialization function | sf_thread_monitor_init0 | Name of generated initialization function. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
Typically, only a small number of settings must be modified from the default for lower level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and will be locked to prevent user modification. The following tables identify all the settings within the properties section for the module.
Configuration Settings for the Independent Watchdog Timer on r_iwdt
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enables or disables the parameter checking. |
| Name | g_wdt0 | Module name. |
| NMI Callback | NULL | Callback. A user callback function can be registered in external_irq_api_t::open. If this callback function is provided, it will be called from the interrupt service routine (ISR) each time the IRQn triggers. Warning: Since the callback is called from an ISR, care should be taken not to use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system. |
Configuration Settings for the Watchdog Timer on r_wdt
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enables or disables the parameter checking. |
| Name | g_wdt0 | Module Name. |
| Start Mode | Register, Auto Default: Register | Configures the start mode as register start or auto-start. |
| Start Watchdog After Configuration | True, False Default: True | Controls whether WDT is started during initialization. |
| Timeout | 1024 cycles, 4096 cycles, 8192 cycles, 16384 cycles Default: 16384 cycles | WDT timeout period. |
| Clock Division Ratio | PCLK/4, PCLK/64, PCLK/128, PCLK/512, PCLK/2048, PCLK/8192 Default: PCLK/8192 | WDT clock divider. |
| Window Start Position | 100% (Window Position Not Specified), 75%, 50%, 25% Default: 100% (Window Position Not Specified) | Permitted refresh period start postion. |
| Window End Position | 0% (Window Position Not Specified), 25%, 50%, 75% Default: 0% (Window Position Not Specified) | Permitted refresh period end postion. |
| Reset Control | Reset Outpout, NMI Generated Default: Reset Output | Select whether WDT should reset the MCU or generate an NMI. |
| Stop Control | WDT Count Enabled in Low Power Mode, WDT Count Disabled in Low Power Mode Default: WDT Count Disabled in Low Power Mode | Select whether the WDT should stop counting in low power modes. |
| NMI Callback | NULL | Callback. A user callback function can be registered in open. If this callback function is provided, it will be called from the interrupt service routine (ISR) each time the IRQn triggers. Warning: Since the callback is called from an ISR, care should be taken not to use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system. |
Use the ISDE to configure the WDT clock using the Clocks tab.
The WDT is initially based on the PCLKB frequency. Set the PCLKB frequency in the ISDE using the clock configurator or the CGC Interface at run-time.
With the PCLKB running at 60 MHz, the WDT maximum timeout period is approximately 2.24 seconds.
The IWDT clock runs at 15 kHz resulting in a maximum possible timeout period of just under 35 seconds.
The Thread Monitor Framework does not require any pins for its operation.
Any thread monitored by the Thread Monitor Framework must be instrumented to work with the monitoring module. When a thread to be monitored is registered with the Thread Monitor, the expected minimum and maximum count values are passed via a pointer to a structure of type sf_thread_monitor_counter_min_max_tcontaining the values.
The thread's counter and minimum and maximum values must be registered with the Thread Monitor Framework by calling g_sf_thread_monitor.p_api->threadRegister().
Each time round the monitored thread's loop, the counter value should be updated by calling g_sf_thread_monitor.p_api->countIncrement().
The Thread Monitor Framework does not use any interrupts; the WDT/IWDT must be configured to generate a reset.
The steps in using the Thread Monitor Framework module on sf_thread_monitor in a typical application are:
These common steps are illustrated in a typical operational flow diagram in the following figure:
