Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add and update Timer requirements #75

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add and update Timer requirements #75

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37d1003
system: Add and update Timer requirements
simhein Jun 24, 2024
054a98d
software: Adept and add new timers requirements
simhein Jun 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
311 changes: 302 additions & 9 deletions docs/software_requirements/timers.sdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,9 @@ UID: ZEP-SRS-4-1
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Kernel Clock
TITLE: Timer definition at run time
STATEMENT: >>>
The Zephyr RTOS shall provide a interface for checking the current value of the real-time clock.
<<<
USER_STORY: >>>
As a Zephyr RTOS user, I want to be able to track the passed real time in the OS with a dedicated hardware counter and interrupt.
The Zephyr RTOS shall provide a mechanism to define and initialize timers at run time.
<<<
RELATIONS:
- TYPE: Parent
Expand All @@ -31,12 +28,308 @@ UID: ZEP-SRS-4-2
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Call functions in interrupt context
TITLE: Timer definition at compile time
STATEMENT: >>>
The Zephyr RTOS shall provide a mechanism to define and static initialize timers (compile time).
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-3
STATUS: Draft
TYPE: Non-Functional
tobiaskaestner marked this conversation as resolved.
Show resolved Hide resolved
COMPONENT: Timers
TITLE: Timer status
STATEMENT: >>>
A Zephyr RTOS timer shall have a status which indicates the expiration of the timer.
tobiaskaestner marked this conversation as resolved.
Show resolved Hide resolved
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-4
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer period
STATEMENT: >>>
A Zephyr RTOS timer shall support repeated expiration of the timer given by a timer-specific time period.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-5
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer duration
STATEMENT: >>>
The Zephyr RTOS shall provide an interface to schedule user mode call back function triggered by a real time clock value.
A Zephyr RTOS timer shall have a duration which indicates when the timer expires for the first time.
<<<
USER_STORY: >>>
As a Zephyr RTOS user, I want to be able to execute functions in the interrupt context and the interrupt context shall be base on a real-time counter.
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-6
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer expiry function
STATEMENT: >>>
A Zephyr RTOS timer shall support a user-settable expiry function that gets called whenever the timer expires.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-7
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer stop function
STATEMENT: >>>
A Zephyr RTOS timer shall support a user-settable stop function that gets called when the timer is stopped while running.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-8
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Initialialization with expiry function
STATEMENT: >>>
When initializing a Zephyr RTOS timer, the expiry function a timer can have shall be settable.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-9
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Initialialization with stop function
STATEMENT: >>>
When initializing a Zephyr RTOS timer, the stop function a timer can have shall be settable.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-10
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer start
STATEMENT: >>>
The Zephyr RTOS shall provide a mechanism to start a defined and initialized timer.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-11
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Start timer status reset
STATEMENT: >>>
Whenever a not running timer is started the timer's status shall be reset to zero.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-12
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Start timer counting values
STATEMENT: >>>
Whenever a Zephyr RTOS timer is started, the timer shall start running with the duration and period values provided during timer initialization.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-13
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer stop
STATEMENT: >>>
A Zephyr RTOS timer that is running shall be stoppable
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-14
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer status read
STATEMENT: >>>
The Zephyr RTOS shall provide a mechanism to read the number of times a timer that is running has already expired.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-15
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer status read reset
STATEMENT: >>>
When the timer is read via the timer status read mechanism, the status shall be reset.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-16
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer thread synchronization
STATEMENT: >>>
The Zephyr RTOS shall provide a mechanism to synchronize a thread with a defined and initialized timer.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-17
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Synchronized thread blocks until timer has expired
STATEMENT: >>>
When the thread synchronization mechanism is used, the thread shall be blocked until the timer expires.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: Something interesting to consider: Can more than one thread synchronize with a given timer? At first glance the implementation seems to allow for this. However, since synchronizing is not side-effect free (it resets the timer's status) is this (syncing more than one thread on a timer) a safe operation ?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that more than one thread can synchronize with a given timer. It might have a side-effect if another thread want's to read the "status" as well and will take some action towards that "status" but isn't that more like a risk of the application implementation itself how this can be used`?

What do you mean exactly with safe operation?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For me the API as we have it today in Zephyr is not ideal, e.g. the behaviour is somewhat ambiguous. Say, two threads synchronize on a given timer of which only one thread will be readied when the timer expires. But which of these two threads will that be? And is it deterministically always the same?
For me this boils down to poor semantics in the read status operation as it resets the status field as a side-effect.

That all said, probably not much we can do about it right now as we are trying to capture the RQTs as per the API as it is. Still, I wonder if for a functionally safe RTOS this needs changing first. Probably worth a discussion in a wider group.

<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-18
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Synchronized thread is unblocked when timer is stopped.
STATEMENT: >>>
When the thread synchronization mechanism is used, the synchronized thread shall be unblocked when the timer is stopped.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-19
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer thread synchronization status reset
STATEMENT: >>>
When the thread synchronization mechanism is used, the status of the timer shall be reset.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue: I know this captures the current design. However, this function is not clear to me. Again, it introduces a side-effect to a function that shouldn't have one and I also don't understand why unpending a thread from a wait list requires to reset the expiry counter.
@nashif would you be able to shed some light onto this?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps it's different views on semantics, I'd expect that syncing a thread on a timer should not affect the timer itself, since otherwise the operation will behave differently for the first and the following threads trying to sync at the same time. The current implementation in https://github.com/zephyrproject-rtos/zephyr/blob/911abc33e68b81c0490fa4b32a93d7d726640b73/kernel/timer.c#L295 resets the timer's status field after the timer expired and the first thread waiting for the timer runs again over this line. From the timer's perspective this happens at an arbitrary point in time as the (now running) thread might have spend an unspecified amount of time in the ready queue.

Not saying this is false per se, just that I am not really getting it yet, why things are the way they are.

<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-20
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Provide timer remaining expiration time in units of system ticks
STATEMENT: >>>
The Zephyr RTOS shall provide a mechanism to get the timer's remaining time until its next expiry in system ticks.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-21
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Provide timer remaining expiration time in milliseconds
STATEMENT: >>>
The Zephyr RTOS shall provide a mechanism to get the timer's remaining time until its next expiry in milliseconds.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-22
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer set user data
STATEMENT: >>>
The Zephyr RTOS shall provide a mechanism to set user data to a timer.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-23
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer get user data
STATEMENT: >>>
The Zephyr RTOS shall provide a mechanism to get user data from a timer.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-24
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Timer expire functions in interrupt context
STATEMENT: >>>
When the timer expiry function is defined, it shall be called in the interrupt context.
<<<
RELATIONS:
- TYPE: Parent
VALUE: ZEP-SYRS-18

[REQUIREMENT]
UID: ZEP-SRS-4-25
STATUS: Draft
TYPE: Functional
COMPONENT: Timers
TITLE: Provide timer next expiration time in units of system ticks
STATEMENT: >>>
The Zephyr RTOS shall provide a mechanism to get the timer's next time of expiration in system ticks.
<<<
RELATIONS:
- TYPE: Parent
Expand Down
14 changes: 8 additions & 6 deletions docs/system_requirements/index.sdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ The Zephyr RTOS shall provide a framework for interrupt and interrupt service ro
USER_STORY: >>>
As the Zephyr RTOS user I want the Kernel to provide abstracted interfaces to
the platform enabling me to implement standard interrupts interrupt service routines
without detailed knowledge of the platform architecture and programming model.
without detailed knowledge of the platform architecture and programming model.
<<<

[REQUIREMENT]
Expand Down Expand Up @@ -268,18 +268,20 @@ As a Zephyr RTOS user, I want to be able to give my threads different priorities

[/SECTION]

[SECTION]
TITLE: Timers

[REQUIREMENT]
UID: ZEP-SYRS-18
STATUS: Draft
TYPE: High Level
TYPE: Non-Functional
COMPONENT: Timers
TITLE: Timers
TITLE: Time based events
STATEMENT: >>>
The Zephyr RTOS shall provide a framework for managing time-based events.
<<<
USER_STORY: >>>
As a Zephyr RTOS user, I want to start, suspend, resume and stop timers which shall trigger an event on a set expiration time.
<<<

[/SECTION]

[REQUIREMENT]
UID: ZEP-SYRS-19
Expand Down
Loading