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..ef0e74c1 --- /dev/null +++ b/docs/software_requirements/task_watchdog.sdoc @@ -0,0 +1,197 @@ +[DOCUMENT] +TITLE: Task Watchdog +PREFIX: ZEP-SRS-20- + +[GRAMMAR] +IMPORT_FROM_FILE: software_requirements.sgra + +[TEXT] +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 +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Start monitoring task +STATEMENT: >>> +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 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] +UID: ZEP-SRS-20-2 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Stop monitoring task +STATEMENT: >>> +The Task Watchdog shall provide a method to stop monitoring a task watchdog timer. +<<< +USER_STORY: >>> +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] +UID: ZEP-SRS-20-3 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Feed task watchdog timer +STATEMENT: >>> +The Task Watchdog shall provide a method to feed the task watchdog timer. +<<< +USER_STORY: >>> +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] +UID: ZEP-SRS-20-4 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Callback on task failure +STATEMENT: >>> +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 my registered callback function to be executed when a watchdog expires so that my custom error-handling logic is triggered automatically. +<<< + +[REQUIREMENT] +UID: ZEP-SRS-20-5 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Reset on task failure +STATEMENT: >>> +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 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] +UID: ZEP-SRS-20-6 +STATUS: Draft +TYPE: Functional +COMPONENT: Task Watchdog +TITLE: Auto feed hardware watchdog +STATEMENT: >>> +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 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. +<<<