![]() |
m2mb API docs
37.00.006.0
m2mb API sets documentation
|
Watchdog interface. More...
Go to the source code of this file.
Macros | |
#define | M2MB_WDOG_INVALID 0 |
#define | M2MB_WDOG_ENABLED TRUE |
#define | M2MB_WDOG_DISABLED FALSE |
#define | M2MB_WDOG_GPIO_ISR_ENABLE TRUE |
#define | M2MB_WDOG_GPIO_ISR_DISABLE FALSE |
Functions | |
M2MB_RESULT_E | m2mb_wDog_init (M2MB_WDOG_HANDLE *h, M2MB_WDOG_IND_CALLBACK wDogCallback, void *userdata) |
m2mb_wDog_init More... | |
M2MB_RESULT_E | m2mb_wDog_deinit (M2MB_WDOG_HANDLE h) |
m2mb_wDog_deinit More... | |
M2MB_RESULT_E | m2mb_wDog_enable (M2MB_WDOG_HANDLE h, MEM_W wDogWakeUpTicks, MEM_W ticksToReboot) |
m2mb_wDog_enable More... | |
M2MB_RESULT_E | m2mb_wDog_disable (M2MB_WDOG_HANDLE h) |
m2mb_wDog_disable More... | |
M2MB_RESULT_E | m2mb_wDog_reset (M2MB_WDOG_HANDLE h) |
m2mb_wDog_reset More... | |
M2MB_RESULT_E | m2mb_wDog_isr (M2MB_WDOG_HANDLE h, const CHAR *gpioPath, M2MB_GPIO_TRIGGER_E edgeTrigger) |
m2mb_wDog_isr More... | |
M2MB_RESULT_E | m2mb_wDog_addTask (M2MB_WDOG_HANDLE h, M2MB_OS_TASK_HANDLE hTask, UINT32 wdTimeout) |
m2mb_wDog_addTask More... | |
M2MB_RESULT_E | m2mb_wDog_removeTask (M2MB_WDOG_HANDLE h, M2MB_OS_TASK_HANDLE hTask) |
m2mb_wDog_removeTask More... | |
M2MB_RESULT_E | m2mb_wDog_kick (M2MB_WDOG_HANDLE h, M2MB_OS_TASK_HANDLE hTask) |
m2mb_wDog_kick More... | |
M2MB_RESULT_E | m2mb_wDog_getItem (M2MB_WDOG_HANDLE h, M2MB_WDOG_SELECT_CMD_E wDogCmd, M2MB_OS_TASK_HANDLE hTask, MEM_W *pOut) |
m2mb_wDog_getItem More... | |
Watchdog interface.
m2m/m2m_generic/common/m2mb_inc/m2mb_wDog.h
Watchdog interface is provided. The module implements a general software watchdog architecture. Watchdog instances (handles) can be added to system watchdog control, using provided watchdog interface. Each handle manages a defined set of tasks accordingly to the configuration provided through defined APIs. Watchdog control can be based on a regular tick of internal task control, or can be based on external signal provided through the selected gpio, (when specified gpio interrupt is set through dedicated API) that triggers the control for any ISR configured instances on the same gpio. Once the tasks are included in the control and the relative deadlines or timeouts are configured, when the control is enabled, kick for each task needs to be provided on regular basis. Each configured task on the handle, is checked periodically against its timeout. Here inactivity of a task, is intended with respect to watchdog control, meaning no kick is provided. In case a timeout or deadline inactivity or missing kicks is reached, the system invokes, whenever is possible, the provided callback if any is set. In the callback, info can be collected and actions performed, like restarting the single application, rebooting the entire system, or resetting the watchdog (not recommended if not really needed). If no action is taken, the system, as a first action, whenever is possible, tries to restart the involved application in the watchdog task timeout; in case it is not possible, as next step, the control reboots the whole system. Task control cannot manage any busy loop, since in this scenario the control itself can no more be scheduled and, at the end, before or later, the invoked hardware watchdog bark reboots the entire system. In an interrupt control mode instead, busy loop could generally be managed (of course depending on system status and configured timeouts values), but an external timing signal needs to be provided and gpio resources reserved. In case a timeout or deadline inactivity or missing kicks is reached in ISR mode, when callback is configured, if system status allows it, the callback can be invoked or not, depending on the priority of the task that is in busy loop status. The higher the priority, the lower the chance the callback to be invoked. Just a reference, priorities lower than the task calling M2MB_main() generally allow watchdog callback to be served (see m2mb_os.h module for priorities and related functions). As pointed out, it is not guaranteed that in ISR mode, the watchdog control can catch any busy loop, since the success of control process, at the end, depends on the system status, timeout parameters set for the watchdog instance, tasks, etc... Too long timeouts set in a busy loop scenario (and/or associated with low periodicity of external signal), can bring the system to automatic watchdog hardware bark without software intervention. Only if watchdog handle belongs to the same application that has a task in the busy loop status, a restart of handle related application is tried before rebooting the entire system, otherwise the system is directly rebooted.
E.g using system watchdog task (no ISR) Scheduler -> wdTask -> check ticks -> control of handles (task: counter vs timeout ) <- if handle is enabled counter=timeout during kick or reset, counter– otherwise if ( counter == 0 ) manages deadline inactivity reached => user callback if configured
ISR HW signal -> check ticks -> control of handles of ISR type ( the same "logic" management )
@notes Dependencies: m2mb_types.h m2mb_gpio.h
M2MB_RESULT_E m2mb_wDog_addTask | ( | M2MB_WDOG_HANDLE | h, |
M2MB_OS_TASK_HANDLE | hTask, | ||
UINT32 | wdTimeout | ||
) |
m2mb_wDog_addTask
m2mb_wDog_addTask adds a task on instance to control its inactivity deadline on watchdog control. Here inactivity is intended with respect to watchdog control, meaning no kick is provided. The inactivity deadline is reached the next control period after timeout is reached, so after wdTimeout ticks increased by 1. E.g. with wdTimeout=1, first control is allowed and counter is decreased to 0 during control phase; the next control period, if the control finds the counter still at 0, the deadline is considered to be reached (so wdTimeout+1 watchdog controls allowed before deadline is declared)
[in] | h | handle of the watchdog instance to add task control on |
[in] | hTask | handle of task to be added on control |
[in] | wdTimeout | timeout of the deadline for task inactivity |
Adding task to watchdog instance
M2MB_RESULT_E m2mb_wDog_deinit | ( | M2MB_WDOG_HANDLE | h | ) |
m2mb_wDog_deinit
The function de-initializes the handle, releasing the associated resources. If a control ISR is associated to the handle, gpio resources are released. gpio resources are actually released only if they are not used by other handles
[in] | h | handle of watchdog instance to be de-initialized |
M2MB_RESULT_E m2mb_wDog_disable | ( | M2MB_WDOG_HANDLE | h | ) |
m2mb_wDog_disable
The function disables the watchdog instance, so it is no more evaluated by the system watchdog control. Instance can be later re-enabled or reset until it is not de-initialized
[in] | h | handle of the watchdog instance to be disabled |
M2MB_RESULT_E m2mb_wDog_enable | ( | M2MB_WDOG_HANDLE | h, |
MEM_W | wDogWakeUpTicks, | ||
MEM_W | ticksToReboot | ||
) |
m2mb_wDog_enable
The function enables the management of the specified watchdog instance inside the watchdog control. Instance is evaluated after the specified wDogWakeUpTicks has been elapsed inside control. It means that each control is performed at any wDogWakeUpTicks for the instance indicated. If the instance is managed by the default task control, handle is evaluated after every wDogWakeUpTicks calls of the internal system watchdog thread (see M2MB_WDOG_SELECT_CMD_TICK_DURATION_MS). If the instance is managed through ISR, it is evaluated every wDogWakeUpTicks of ISR, being ISR timing depending on user hardware design (signal timing provided on selected gpio)
[in] | h | handle of the watchdog instance to be enabled |
[in] | wDogWakeUpTicks | tick repetition rate for watchdog instance evaluation. Cannot be 0. |
[in] | ticksToReboot | in case no action is performed on timeout in callback (if system has chance to call it) the maximum number of ticks of control allowed in watchdog control (every wDogWakeUpTicks) after deadline timeout, before invoking the procedure to auto restart the application or rebooting the system. Parameter must be provided but it is not used in case callback is not provided. Cannot be 0 |
M2MB_RESULT_E m2mb_wDog_getItem | ( | M2MB_WDOG_HANDLE | h, |
M2MB_WDOG_SELECT_CMD_E | wDogCmd, | ||
M2MB_OS_TASK_HANDLE | hTask, | ||
MEM_W * | pOut | ||
) |
m2mb_wDog_getItem
m2mb_wDog_getItem retrieves item value from watchdog instance. See M2MB_WDOG_SELECT_CMD_E on the item that can be retrieved, some belonging to watchdog instance, others to task owned by the watchdog instance. So depending on the type of request, hTask needs to be provided or it is ignored
[in] | h | handle of the watchdog instance to retrieve an item from |
[in] | wDogCmd | select the command to specify the item to retrieve |
[in] | hTask | depending on the wDogCmd, it is the handle of task to be provided or it is ignored. E.g. if wDogCmd is related to specific task added to the watchdog instance, task handle of that task has to be provided (for instance M2MB_WDOG_SELECT_CMD_TASK_CNT requires task handle to be provided: see M2MB_WDOG_SELECT_CMD_E) |
[out] | pOut | address of the output to get |
M2MB_RESULT_E m2mb_wDog_init | ( | M2MB_WDOG_HANDLE * | h, |
M2MB_WDOG_IND_CALLBACK | wDogCallback, | ||
void * | userdata | ||
) |
m2mb_wDog_init
The function performs initialization of application handle of watchdog instance to be manage in system watchdog
[out] | h | address of the watchdog instance handle to be initialized |
[in] | wDogCallback | it is the watchdog callback that is invoked in case of watchdog event. If NULL is set, no callback is invoked |
[in] | userdata | some specific userdata that the callback provides when triggered |
M2MB_RESULT_E m2mb_wDog_isr | ( | M2MB_WDOG_HANDLE | h, |
const CHAR * | gpioPath, | ||
M2MB_GPIO_TRIGGER_E | edgeTrigger | ||
) |
m2mb_wDog_isr
m2mb_wDog_isr allows to set a gpio as interrupt driven by an hardware signal and triggered by its selected edge or front. If watchdog control is enabled, the specified instance is under watchdog control on each ISR event; in case wDogWakeUpTicks is elapsed, tasks timeouts of the handle are evaluated. Related Gpio is configured internally as input pull down
[in] | h | handle of the watchdog instance to set the ISR on |
[in] | gpioPath | string path of the gpio in the form /dev/GPIOx where "x" is in decimal format. See m2mb_gpio.h module |
[in] | edgeTrigger | define the edge of the hardware signal that triggers the interrupt. See m2mb_gpio module |
Example to set gpio as ISR sources for watchdog instance control
M2MB_RESULT_E m2mb_wDog_kick | ( | M2MB_WDOG_HANDLE | h, |
M2MB_OS_TASK_HANDLE | hTask | ||
) |
m2mb_wDog_kick
m2mb_wDog_kick performs watchdog kick for selected task inside watchdog instance. It means the counter for task is reset to its initially set wdTimeout value
[in] | h | handle of the watchdog instance the task belong to |
[in] | hTask | task handle to kick the watchdog on. It resets the counter of inactivity task |
Example using m2mb_wDog_kick inside a generic task
M2MB_RESULT_E m2mb_wDog_removeTask | ( | M2MB_WDOG_HANDLE | h, |
M2MB_OS_TASK_HANDLE | hTask | ||
) |
m2mb_wDog_removeTask
m2mb_wDog_removeTask removes a task under the provided watchdog instance
[in] | h | handle of the watchdog instance to remove task control on |
[in] | hTask | handle of task to be removed from watchdog instance |
Removing task from watchdog instance
M2MB_RESULT_E m2mb_wDog_reset | ( | M2MB_WDOG_HANDLE | h | ) |
m2mb_wDog_reset
The function resets the watchdog timeout counter for each task included in watchdog instance. In this way, if the watchdog instance is enabled, the counting and control process of the associated tasks, can restart from the beginning at the same way if the tasks were just added. It has the same effect of performing m2mb_wDog_kick() for each task included in the instance. m2mb_wDog_reset can be performed on running with instance enabled
[in] | h | handle of the watchdog instance to be reset |