From 21acaed65f1dda37d95619e7bce348c5b703c021 Mon Sep 17 00:00:00 2001 From: Nelson Ferragut Date: Sat, 8 Feb 2025 12:14:08 -0500 Subject: [PATCH 1/4] initial task watchdog requirements --- docs/software_requirements/index.sdoc | 3 + docs/software_requirements/task_watchdog.sdoc | 102 ++++++++++++++++++ 2 files changed, 105 insertions(+) create mode 100644 docs/software_requirements/task_watchdog.sdoc diff --git a/docs/software_requirements/index.sdoc b/docs/software_requirements/index.sdoc index 9a47f5c1..5418c2cc 100644 --- a/docs/software_requirements/index.sdoc +++ b/docs/software_requirements/index.sdoc @@ -52,6 +52,9 @@ FILE: semaphore.sdoc [DOCUMENT_FROM_FILE] FILE: power_management.sdoc +[DOCUMENT_FROM_FILE] +FILE: task_watchdog.sdoc + [DOCUMENT_FROM_FILE] FILE: thread_communication.sdoc diff --git a/docs/software_requirements/task_watchdog.sdoc b/docs/software_requirements/task_watchdog.sdoc new file mode 100644 index 00000000..7a6d44c8 --- /dev/null +++ b/docs/software_requirements/task_watchdog.sdoc @@ -0,0 +1,102 @@ +[DOCUMENT] +TITLE: Task Watchdog +REQ_PREFIX: ZEP-SRS-20- + +[GRAMMAR] +IMPORT_FROM_FILE: software_requirements.sgra + +[TEXT] +STATEMENT: >>> +SPDX-License-Identifier: Apache-2.0 +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-1 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Start monitoring task +STATEMENT: >>> +The Zephyr RTOS shall provide a method to create and start a watchdog channel's timer. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want to guarantee that my background task is running as intended. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-2 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Stop monitoring task +STATEMENT: >>> +The Zephyr RTOS shall provide a method to stop and destroy a watchdog channel's timer. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want the option of canceling the monitoring of my background task. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-3 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Restart monitoring task +STATEMENT: >>> +The Zephyr RTOS shall provide a method to restart a watchdog channel's timer. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want my background task to periodically inform the Task Watchdog feature that it is still running to avoid any corrective actions. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-4 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Notify on task failure +STATEMENT: >>> +When the application specifies a notification method, if a watchdog channel's timer expires, the Zephyr RTOS shall notify the application. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want the option to get a notification if my background task stops running as intended so that I can take corrective action. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-5 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Reset on task failure +STATEMENT: >>> +When the application does not specify a notification method, if a watchdog channel's timer expires, the Zephyr RTOS shall reset. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want the option of having the Zephyr RTOS reset if my background task stops running as intended. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-6 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Hardware watchdog fallback +STATEMENT: >>> +When the hardware watchdog fallback feature is enabled, if the Task Watchdog stops working, the Zephyr RTOS shall reset. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want a hardware watchdog to cause a reset if the Zephyr scheduler stops scheduling all tasks at once or if the watchdog channel timers stop running. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-7 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Detect RAM corruption +STATEMENT: >>> +When the RAM corruption detection feature is enabled, if any internal Task Watchdog variables are corrupted, the Zephyr RTOS shall reset. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want to guarantee that RAM corruption will not compromise the Task Watchdog module's ability to meet its requirements. +<<< From 3f8c830b620a80e60d9769aed21e27cf3028fc5c Mon Sep 17 00:00:00 2001 From: Nelson Ferragut Date: Sun, 16 Feb 2025 15:46:44 -0500 Subject: [PATCH 2/4] removed RAM corruption requirement; reworded HW watchdog requirement --- docs/software_requirements/task_watchdog.sdoc | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/docs/software_requirements/task_watchdog.sdoc b/docs/software_requirements/task_watchdog.sdoc index 7a6d44c8..51094894 100644 --- a/docs/software_requirements/task_watchdog.sdoc +++ b/docs/software_requirements/task_watchdog.sdoc @@ -82,21 +82,8 @@ TYPE: Functional COMPONENT: Task Watchdog TITLE: Hardware watchdog fallback STATEMENT: >>> -When the hardware watchdog fallback feature is enabled, if the Task Watchdog stops working, the Zephyr RTOS shall reset. +When the hardware watchdog fallback feature is enabled, if the Task Watchdog stops working, the hardware watchdog shall reset. <<< USER_STORY: >>> -As a Zephyr RTOS user, I want a hardware watchdog to cause a reset if the Zephyr scheduler stops scheduling all tasks at once or if the watchdog channel timers stop running. -<<< - -[REQUIREMENT] -UID: ZEP-SRS-20-7 -STATUS: Draft -TYPE: Functional -COMPONENT: Task Watchdog -TITLE: Detect RAM corruption -STATEMENT: >>> -When the RAM corruption detection feature is enabled, if any internal Task Watchdog variables are corrupted, the Zephyr RTOS shall reset. -<<< -USER_STORY: >>> -As a Zephyr RTOS user, I want to guarantee that RAM corruption will not compromise the Task Watchdog module's ability to meet its requirements. +As a Zephyr RTOS user, I want a hardware watchdog to force a reset if the Task Watchdog stops working due to a system failure. <<< From 11dc4220b09c9a7c50c57d9e2f046391c9e4446f Mon Sep 17 00:00:00 2001 From: Nelson Ferragut Date: Sun, 16 Feb 2025 15:53:25 -0500 Subject: [PATCH 3/4] removed "background" --- docs/software_requirements/task_watchdog.sdoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/software_requirements/task_watchdog.sdoc b/docs/software_requirements/task_watchdog.sdoc index 51094894..17f9bc72 100644 --- a/docs/software_requirements/task_watchdog.sdoc +++ b/docs/software_requirements/task_watchdog.sdoc @@ -20,7 +20,7 @@ STATEMENT: >>> The Zephyr RTOS shall provide a method to create and start a watchdog channel's timer. <<< USER_STORY: >>> -As a Zephyr RTOS user, I want to guarantee that my background task is running as intended. +As a Zephyr RTOS user, I want to guarantee that my task is running as intended. <<< [REQUIREMENT] @@ -33,7 +33,7 @@ STATEMENT: >>> The Zephyr RTOS shall provide a method to stop and destroy a watchdog channel's timer. <<< USER_STORY: >>> -As a Zephyr RTOS user, I want the option of canceling the monitoring of my background task. +As a Zephyr RTOS user, I want the option of canceling the monitoring of my task. <<< [REQUIREMENT] @@ -46,7 +46,7 @@ STATEMENT: >>> The Zephyr RTOS shall provide a method to restart a watchdog channel's timer. <<< USER_STORY: >>> -As a Zephyr RTOS user, I want my background task to periodically inform the Task Watchdog feature that it is still running to avoid any corrective actions. +As a Zephyr RTOS user, I want my task to periodically inform the Task Watchdog feature that it is still running to avoid any corrective actions. <<< [REQUIREMENT] @@ -59,7 +59,7 @@ STATEMENT: >>> When the application specifies a notification method, if a watchdog channel's timer expires, the Zephyr RTOS shall notify the application. <<< USER_STORY: >>> -As a Zephyr RTOS user, I want the option to get a notification if my background task stops running as intended so that I can take corrective action. +As a Zephyr RTOS user, I want the option to get a notification if my task stops running as intended so that I can take corrective action. <<< [REQUIREMENT] @@ -72,7 +72,7 @@ STATEMENT: >>> When the application does not specify a notification method, if a watchdog channel's timer expires, the Zephyr RTOS shall reset. <<< USER_STORY: >>> -As a Zephyr RTOS user, I want the option of having the Zephyr RTOS reset if my background task stops running as intended. +As a Zephyr RTOS user, I want the option of having the Zephyr RTOS reset if my task stops running as intended. <<< [REQUIREMENT] From 265057b41665f098108757f04a7cb28832a9f813 Mon Sep 17 00:00:00 2001 From: Nelson Ferragut Date: Tue, 15 Jul 2025 12:47:41 -0400 Subject: [PATCH 4/4] added new requirements; major updates --- docs/software_requirements/task_watchdog.sdoc | 140 ++++++++++++++++-- 1 file changed, 124 insertions(+), 16 deletions(-) diff --git a/docs/software_requirements/task_watchdog.sdoc b/docs/software_requirements/task_watchdog.sdoc index 17f9bc72..ef0e74c1 100644 --- a/docs/software_requirements/task_watchdog.sdoc +++ b/docs/software_requirements/task_watchdog.sdoc @@ -1,6 +1,6 @@ [DOCUMENT] TITLE: Task Watchdog -REQ_PREFIX: ZEP-SRS-20- +PREFIX: ZEP-SRS-20- [GRAMMAR] IMPORT_FROM_FILE: software_requirements.sgra @@ -10,6 +10,88 @@ STATEMENT: >>> SPDX-License-Identifier: Apache-2.0 <<< +[REQUIREMENT] +UID: ZEP-SRS-20-9 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Enable Task Watchdog feature +STATEMENT: >>> +The Task Watchdog feature shall be configurable to be enabled or disabled. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want to enable the Task Watchdog feature so that I can monitor the health of my tasks. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-11 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Enable hardware failsafe option +STATEMENT: >>> +The Task Watchdog shall provide a configuration option to enable or disable the hardware watchdog failsafe. +<<< +USER_STORY: >>> +As a safety system designer, I want a hardware watchdog failsafe so that the system can recover from a critical failure where the Task Watchdog itself stops operating. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-12 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Configure hardware watchdog timeout period +STATEMENT: >>> +Where the hardware watchdog failsafe is enabled, the Task Watchdog shall allow the hardware watchdog timeout period to be configured. +<<< +USER_STORY: >>> +As a safety system designer, I want to configure the hardware watchdog timeout period so that I can ensure the system resets within the time constraints required for functional safety. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-13 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Configure maximum feed period +STATEMENT: >>> +Where the hardware watchdog failsafe is enabled, the Task Watchdog shall allow the maximum hardware watchdog feed period to be configured. +<<< +USER_STORY: >>> +Information: The Task Watchdog schedules a timer to either feed the hardware watchdog, or detect the next software task timeout, whichever comes first. + +As a Zephyr RTOS user, I want to control the hardware watchdog feed period so that I can guarantee the hardware watchdog is serviced frequently enough to prevent an unintended reset. + +As a Zephyr RTOS user, I want to align the feed period with my task timeouts so that I can optimize system performance by avoiding unnecessary timer events. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-10 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Configure maximum task watchdog timers +STATEMENT: >>> +The Task Watchdog shall allow the maximum number of supported task watchdog timers to be configured. +<<< +USER_STORY: >>> +As a developer, I want to configure the maximum number of watchdog channels so that I can balance memory usage with the number of tasks I need to monitor. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-8 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Initialize feature +STATEMENT: >>> +Where the hardware watchdog failsafe is enabled, the Task Watchdog shall start the hardware watchdog upon initialization. +<<< +USER_STORY: >>> +As a safety system designer, I want the hardware watchdog to start automatically with the Task Watchdog so that the system is protected by the failsafe mechanism from the very beginning of operation. +<<< + [REQUIREMENT] UID: ZEP-SRS-20-1 STATUS: Draft @@ -17,10 +99,36 @@ TYPE: Functional COMPONENT: Task Watchdog TITLE: Start monitoring task STATEMENT: >>> -The Zephyr RTOS shall provide a method to create and start a watchdog channel's timer. +The Task Watchdog shall provide a method to start monitoring a task watchdog timer. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want to start monitoring a task with a watchdog timer so that I can guarantee the task is executing as intended. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-15 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Set callback function +STATEMENT: >>> +When starting a task watchdog timer, the Task Watchdog shall accept a callback function to be invoked if the timer expires. +<<< +USER_STORY: >>> +As a Zephyr RTOS user, I want to provide a custom callback function for a watchdog timer so that I can implement specific corrective actions if a task becomes unresponsive. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-16 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Set callback user data +STATEMENT: >>> +When starting a task watchdog timer, the Task Watchdog shall accept user data to be passed as an argument to the callback function. <<< USER_STORY: >>> -As a Zephyr RTOS user, I want to guarantee that my task is running as intended. +As a Zephyr RTOS user, I want to associate custom data with a watchdog timer so that I can receive context-specific information in my callback function to identify which task or instance failed. <<< [REQUIREMENT] @@ -30,10 +138,10 @@ TYPE: Functional COMPONENT: Task Watchdog TITLE: Stop monitoring task STATEMENT: >>> -The Zephyr RTOS shall provide a method to stop and destroy a watchdog channel's timer. +The Task Watchdog shall provide a method to stop monitoring a task watchdog timer. <<< USER_STORY: >>> -As a Zephyr RTOS user, I want the option of canceling the monitoring of my task. +As a Zephyr RTOS user, I want to stop monitoring a task so that I can prevent false timeouts when a task completes its work and is no longer expected to run. <<< [REQUIREMENT] @@ -41,12 +149,12 @@ UID: ZEP-SRS-20-3 STATUS: Draft TYPE: Functional COMPONENT: Task Watchdog -TITLE: Restart monitoring task +TITLE: Feed task watchdog timer STATEMENT: >>> -The Zephyr RTOS shall provide a method to restart a watchdog channel's timer. +The Task Watchdog shall provide a method to feed the task watchdog timer. <<< USER_STORY: >>> -As a Zephyr RTOS user, I want my task to periodically inform the Task Watchdog feature that it is still running to avoid any corrective actions. +As a Zephyr RTOS user, I want to periodically feed a task watchdog timer so that I can signal that my task is running correctly and prevent a timeout. <<< [REQUIREMENT] @@ -54,12 +162,12 @@ UID: ZEP-SRS-20-4 STATUS: Draft TYPE: Functional COMPONENT: Task Watchdog -TITLE: Notify on task failure +TITLE: Callback on task failure STATEMENT: >>> -When the application specifies a notification method, if a watchdog channel's timer expires, the Zephyr RTOS shall notify the application. +Where a callback function is configured for a monitored task watchdog timer, if the timer expires, then the Task Watchdog shall invoke that function. <<< USER_STORY: >>> -As a Zephyr RTOS user, I want the option to get a notification if my task stops running as intended so that I can take corrective action. +As a Zephyr RTOS user, I want my registered callback function to be executed when a watchdog expires so that my custom error-handling logic is triggered automatically. <<< [REQUIREMENT] @@ -69,10 +177,10 @@ TYPE: Functional COMPONENT: Task Watchdog TITLE: Reset on task failure STATEMENT: >>> -When the application does not specify a notification method, if a watchdog channel's timer expires, the Zephyr RTOS shall reset. +Where a callback function is not configured for a monitored task watchdog timer, if the timer expires, then the Task Watchdog shall reset the device. <<< USER_STORY: >>> -As a Zephyr RTOS user, I want the option of having the Zephyr RTOS reset if my task stops running as intended. +As a Zephyr RTOS user, I want the system to reset by default when a critical task hangs so that it can be returned to a known-good state without complex recovery code. <<< [REQUIREMENT] @@ -80,10 +188,10 @@ UID: ZEP-SRS-20-6 STATUS: Draft TYPE: Functional COMPONENT: Task Watchdog -TITLE: Hardware watchdog fallback +TITLE: Auto feed hardware watchdog STATEMENT: >>> -When the hardware watchdog fallback feature is enabled, if the Task Watchdog stops working, the hardware watchdog shall reset. +Where the hardware watchdog failsafe is enabled, while all monitored tasks are feeding their respective watchdog timers, the Task Watchdog shall periodically feed the hardware watchdog. <<< USER_STORY: >>> -As a Zephyr RTOS user, I want a hardware watchdog to force a reset if the Task Watchdog stops working due to a system failure. +As a safety system designer, I want the Task Watchdog to manage feeding the hardware watchdog so that a failure on any monitored task will still cause a corrective reset. <<<