[rtems-central commit] spec: Review Timer Manager API
Sebastian Huber
sebh at rtems.org
Wed Dec 2 10:16:37 UTC 2020
Module: rtems-central
Branch: master
Commit: c970d6373fefc6cbb73f0c91dff03865fd2be07c
Changeset: http://git.rtems.org/rtems-central/commit/?id=c970d6373fefc6cbb73f0c91dff03865fd2be07c
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Tue Dec 1 14:57:03 2020 +0100
spec: Review Timer Manager API
---
config.yml | 3 ++
spec/rtems/timer/if/cancel.yml | 26 ++++++++++---
spec/rtems/timer/if/class-bit-not-dormant.yml | 3 +-
spec/rtems/timer/if/class-bit-on-task.yml | 4 +-
spec/rtems/timer/if/class-bit-time-of-day.yml | 3 +-
spec/rtems/timer/if/classes.yml | 3 +-
spec/rtems/timer/if/create.yml | 47 ++++++++++++++++++++----
spec/rtems/timer/if/delete.yml | 29 ++++++++++++---
spec/rtems/timer/if/dormant.yml | 3 +-
spec/rtems/timer/if/fire-after.yml | 40 +++++++++++++++-----
spec/rtems/timer/if/fire-when.yml | 46 ++++++++++++++++++-----
spec/rtems/timer/if/get-information.yml | 29 +++++++++++----
spec/rtems/timer/if/group.yml | 20 ++++++++++
spec/rtems/timer/if/header.yml | 5 ++-
spec/rtems/timer/if/ident.yml | 5 ++-
spec/rtems/timer/if/information.yml | 23 +++++++-----
spec/rtems/timer/if/initiate-server.yml | 47 ++++++++++++++++++++----
spec/rtems/timer/if/interval-on-task.yml | 4 +-
spec/rtems/timer/if/interval.yml | 5 ++-
spec/rtems/timer/if/reset.yml | 38 ++++++++++++++++---
spec/rtems/timer/if/server-default-priority.yml | 8 +++-
spec/rtems/timer/if/server-fire-after.yml | 43 +++++++++++++++++-----
spec/rtems/timer/if/server-fire-when.yml | 49 ++++++++++++++++++++-----
spec/rtems/timer/if/service-routine-entry.yml | 4 +-
spec/rtems/timer/if/service-routine.yml | 7 +++-
spec/rtems/timer/if/time-of-day-on-task.yml | 4 +-
spec/rtems/timer/if/time-of-day.yml | 5 ++-
spec/rtems/timer/req/group.yml | 18 ++++-----
28 files changed, 408 insertions(+), 113 deletions(-)
diff --git a/config.yml b/config.yml
index 77eb7be..98e8f0e 100644
--- a/config.yml
+++ b/config.yml
@@ -100,6 +100,9 @@ interface:
domains:
/if/domain: modules/rtems
interface-documentation:
+- directives-target: modules/rtems-docs/c-user/timer/directives.rst
+ group: /rtems/timer/if/group
+ introduction-target: modules/rtems-docs/c-user/timer/introduction.rst
- directives-target: modules/rtems-docs/c-user/io/directives.rst
group: /rtems/io/if/group
introduction-target: modules/rtems-docs/c-user/io/introduction.rst
diff --git a/spec/rtems/timer/if/cancel.yml b/spec/rtems/timer/if/cancel.yml
index 0a302c1..a582c33 100644
--- a/spec/rtems/timer/if/cancel.yml
+++ b/spec/rtems/timer/if/cancel.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Cancels the timer.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -11,9 +12,14 @@ definition:
- ${../../type/if/id:/name} ${.:/params[0]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive cancels the timer specified in the ${.:/params[0]/name}
+ parameter. This timer will be reinitiated by the next invocation of
+ ${reset:/name}, ${fire-after:/name}, or ${fire-when:/name} with the same
+ timer identifier.
enabled-by: true
-index-entries: []
+index-entries:
+- cancel a timer
interface-type: function
links:
- role: interface-placement
@@ -21,12 +27,20 @@ links:
- role: interface-ingroup
uid: group
name: rtems_timer_cancel
-notes: null
+notes: |
+ This directive will not cause the running task to be preempted.
params:
-- description: '%'
+- description: is the timer identifier.
dir: null
name: id
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ There was no timer associated with the identifier specified by
+ ${.:/params[0]/name}.
+ value: ${../../status/if/invalid-id:/name}
type: interface
diff --git a/spec/rtems/timer/if/class-bit-not-dormant.yml b/spec/rtems/timer/if/class-bit-not-dormant.yml
index edfb12e..712cb41 100644
--- a/spec/rtems/timer/if/class-bit-not-dormant.yml
+++ b/spec/rtems/timer/if/class-bit-not-dormant.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This timer class bit indicates that the timer is not dormant.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/rtems/timer/if/class-bit-on-task.yml b/spec/rtems/timer/if/class-bit-on-task.yml
index 5ce8a37..3cc852e 100644
--- a/spec/rtems/timer/if/class-bit-on-task.yml
+++ b/spec/rtems/timer/if/class-bit-on-task.yml
@@ -1,5 +1,7 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This timer class bit indicates that the timer routine executes in a task
+ context.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/rtems/timer/if/class-bit-time-of-day.yml b/spec/rtems/timer/if/class-bit-time-of-day.yml
index 3a425e0..e5bedea 100644
--- a/spec/rtems/timer/if/class-bit-time-of-day.yml
+++ b/spec/rtems/timer/if/class-bit-time-of-day.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This timer class bit indicates that the timer uses a time of day.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/rtems/timer/if/classes.yml b/spec/rtems/timer/if/classes.yml
index eaee1d1..f09a6d6 100644
--- a/spec/rtems/timer/if/classes.yml
+++ b/spec/rtems/timer/if/classes.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ The timer class indicates how the timer was most recently fired.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/rtems/timer/if/create.yml b/spec/rtems/timer/if/create.yml
index 64ddc5a..71ae5dd 100644
--- a/spec/rtems/timer/if/create.yml
+++ b/spec/rtems/timer/if/create.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Creates a timer.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,9 +13,13 @@ definition:
- ${../../type/if/id:/name} *${.:/params[1]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive creates a timer. The assigned object identifier is returned
+ in ${.:/params[1]/name}. This identifier is used to access the timer with
+ other timer related directives.
enabled-by: true
-index-entries: []
+index-entries:
+- create a timer
interface-type: function
links:
- role: interface-placement
@@ -22,15 +27,41 @@ links:
- role: interface-ingroup
uid: group
name: rtems_timer_create
-notes: null
+notes: |
+ This directive may cause the calling task to be preempted due to an obtain
+ and release of the object allocator mutex.
+
+ For control and maintenance of the timer, RTEMS allocates a
+ ${/glossary/tmcb:/term} from the local TMCB free pool and initializes it.
+
+ In SMP configurations, the processor of the currently executing thread
+ determines the processor used for the created timer. During the life-time of
+ the timer this processor is used to manage the timer internally.
params:
-- description: '%'
+- description: is the name of the timer.
dir: null
name: name
-- description: '%'
- dir: null
+- description: |
+ is the pointer to an object identifier variable. The identifier of the
+ created timer object will be stored in this variable, in case of a
+ successful operation.
+ dir: out
name: id
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The timer name was invalid.
+ value: ${../../status/if/invalid-name:/name}
+ - description: |
+ The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ There was no inactive object available to create a new timer. The number
+ of timers available to the application is configured through the
+ ${/acfg/if/max-timers:/name} configuration option.
+ value: ${../../status/if/too-many:/name}
type: interface
diff --git a/spec/rtems/timer/if/delete.yml b/spec/rtems/timer/if/delete.yml
index 1155e20..5bc65bd 100644
--- a/spec/rtems/timer/if/delete.yml
+++ b/spec/rtems/timer/if/delete.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Deletes the timer.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -11,9 +12,12 @@ definition:
- ${../../type/if/id:/name} ${.:/params[0]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive deletes the timer specified by the ${.:/params[0]/name}
+ parameter. If the timer is running, it is automatically canceled.
enabled-by: true
-index-entries: []
+index-entries:
+- delete a timer
interface-type: function
links:
- role: interface-placement
@@ -21,12 +25,25 @@ links:
- role: interface-ingroup
uid: group
name: rtems_timer_delete
-notes: null
+notes: |
+ This directive may cause the calling task to be preempted due to an obtain
+ and release of the object allocator mutex.
+
+ The ${/glossary/tmcb:/term} for the deleted timer is reclaimed by RTEMS.
+
+ A timer can be deleted by a task other than the task which created the timer.
params:
-- description: '%'
+- description: is the timer identifier.
dir: null
name: id
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ There was no timer associated with the identifier specified by
+ ${.:/params[0]/name}.
+ value: ${../../status/if/invalid-id:/name}
type: interface
diff --git a/spec/rtems/timer/if/dormant.yml b/spec/rtems/timer/if/dormant.yml
index 003c004..7b54398 100644
--- a/spec/rtems/timer/if/dormant.yml
+++ b/spec/rtems/timer/if/dormant.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This timer class indicates that the timer was never in use.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/rtems/timer/if/fire-after.yml b/spec/rtems/timer/if/fire-after.yml
index 6664a7c..6364789 100644
--- a/spec/rtems/timer/if/fire-after.yml
+++ b/spec/rtems/timer/if/fire-after.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Fires the timer after the interval.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -14,9 +15,16 @@ definition:
- void *${.:/params[3]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive initiates the timer specified by ${.:/params[0]/name}. If the
+ timer is running, it is automatically canceled before being initiated. The
+ timer is scheduled to fire after an interval of clock ticks has passed
+ specified by ${.:/params[1]/name}. When the timer fires, the timer service
+ routine ${.:/params[2]/name} will be invoked with the argument
+ ${.:/params[3]/name} in the context of the clock tick ${/glossary/isr:/term}.
enabled-by: true
-index-entries: []
+index-entries:
+- fire a timer after an interval
interface-type: function
links:
- role: interface-placement
@@ -24,21 +32,35 @@ links:
- role: interface-ingroup
uid: group
name: rtems_timer_fire_after
-notes: null
+notes: |
+ This directive will not cause the running task to be preempted.
params:
-- description: '%'
+- description: is the timer identifier.
dir: null
name: id
-- description: '%'
+- description: is the interval until the routine is fired in clock ticks.
dir: null
name: ticks
-- description: '%'
+- description: is the routine to schedule.
dir: null
name: routine
-- description: '%'
+- description: is the argument passed to the routine when it is fired.
dir: null
name: user_data
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The ${.:/params[1]/name} parameter was 0.
+ value: ${../../status/if/invalid-number:/name}
+ - description: |
+ The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ There was no timer associated with the identifier specified by
+ ${.:/params[0]/name}.
+ value: ${../../status/if/invalid-id:/name}
type: interface
diff --git a/spec/rtems/timer/if/fire-when.yml b/spec/rtems/timer/if/fire-when.yml
index 556f48a..a6fde1c 100644
--- a/spec/rtems/timer/if/fire-when.yml
+++ b/spec/rtems/timer/if/fire-when.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Fires the timer at the time of day.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -14,9 +15,16 @@ definition:
- void *${.:/params[3]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive initiates the timer specified by ${.:/params[0]/name}. If the
+ timer is running, it is automatically canceled before being initiated. The
+ timer is scheduled to fire at the time of day specified by
+ ${.:/params[1]/name}. When the timer fires, the timer service routine
+ ${.:/params[2]/name} will be invoked with the argument ${.:/params[3]/name}
+ in the context of the clock tick ${/glossary/isr:/term}.
enabled-by: true
-index-entries: []
+index-entries:
+- fire a timer at time of day
interface-type: function
links:
- role: interface-placement
@@ -24,21 +32,41 @@ links:
- role: interface-ingroup
uid: group
name: rtems_timer_fire_when
-notes: null
+notes: |
+ This directive will not cause the running task to be preempted.
params:
-- description: '%'
+- description: is the timer identifier.
dir: null
name: id
-- description: '%'
+- description: is the time of day when the routine is fired.
dir: null
name: wall_time
-- description: '%'
+- description: is the routine to schedule.
dir: null
name: routine
-- description: '%'
+- description: is the argument passed to the routine when it is fired.
dir: null
name: user_data
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The system date and time was not set.
+ value: ${../../status/if/not-defined:/name}
+ - description: |
+ The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ The time of day was invalid.
+ value: ${../../status/if/invalid-clock:/name}
+ - description: |
+ There was no timer associated with the identifier specified by
+ ${.:/params[0]/name}.
+ value: ${../../status/if/invalid-id:/name}
type: interface
diff --git a/spec/rtems/timer/if/get-information.yml b/spec/rtems/timer/if/get-information.yml
index 6d89a72..b4a414e 100644
--- a/spec/rtems/timer/if/get-information.yml
+++ b/spec/rtems/timer/if/get-information.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Gets information about the timer.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -12,7 +13,8 @@ definition:
- ${information:/name} *${.:/params[1]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive returns information about the timer.
enabled-by: true
index-entries: []
interface-type: function
@@ -22,15 +24,28 @@ links:
- role: interface-ingroup
uid: group
name: rtems_timer_get_information
-notes: null
+notes: |
+ This directive will not cause the running task to be preempted.
params:
-- description: '%'
+- description: is the timer identifier.
dir: null
name: id
-- description: '%'
- dir: null
+- description: |
+ is the pointer to a timer information variable. The information about the
+ timer will be stored in this variable, in case of a successful operation.
+ dir: out
name: the_info
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ There was no timer associated with the identifier specified by
+ ${.:/params[0]/name}.
+ value: ${../../status/if/invalid-id:/name}
type: interface
diff --git a/spec/rtems/timer/if/group.yml b/spec/rtems/timer/if/group.yml
index d6044a4..a37beb1 100644
--- a/spec/rtems/timer/if/group.yml
+++ b/spec/rtems/timer/if/group.yml
@@ -14,6 +14,26 @@ links:
uid: header
- role: interface-ingroup
uid: ../../if/group
+- role: placement-order
+ uid: create
+- role: placement-order
+ uid: ident
+- role: placement-order
+ uid: cancel
+- role: placement-order
+ uid: delete
+- role: placement-order
+ uid: fire-after
+- role: placement-order
+ uid: fire-when
+- role: placement-order
+ uid: initiate-server
+- role: placement-order
+ uid: server-fire-after
+- role: placement-order
+ uid: server-fire-when
+- role: placement-order
+ uid: reset
name: Timer Manager
text: |
The Classic API shall provide an interface to the Timer Manager.
diff --git a/spec/rtems/timer/if/header.yml b/spec/rtems/timer/if/header.yml
index be9b949..13f183e 100644
--- a/spec/rtems/timer/if/header.yml
+++ b/spec/rtems/timer/if/header.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: This header file defines the Timer Manager API.
+brief: |
+ This header file provides the Timer Manager API.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
@@ -8,6 +9,8 @@ interface-type: header-file
links:
- role: interface-placement
uid: /if/domain
+- role: interface-ingroup
+ uid: ../req/group
path: rtems/rtems/timer.h
prefix: cpukit/include
type: interface
diff --git a/spec/rtems/timer/if/ident.yml b/spec/rtems/timer/if/ident.yml
index c119ab6..4218efa 100644
--- a/spec/rtems/timer/if/ident.yml
+++ b/spec/rtems/timer/if/ident.yml
@@ -1,6 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
- Identifies a timer object by the specified object name.
+ Identifies a timer by the object name.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -17,7 +17,8 @@ description: |
This directive obtains the timer identifier associated with the timer name
specified in ${.:/params[0]/name}.
enabled-by: true
-index-entries: []
+index-entries:
+- obtain the ID of a timer
interface-type: function
links:
- role: interface-placement
diff --git a/spec/rtems/timer/if/information.yml b/spec/rtems/timer/if/information.yml
index ddccba2..4cac081 100644
--- a/spec/rtems/timer/if/information.yml
+++ b/spec/rtems/timer/if/information.yml
@@ -1,38 +1,43 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ The structure contains information about a timer.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
- default:
brief: |
- This member is
+ The timer class member indicates how the timer was most recently fired.
definition: ${classes:/name} ${.:name}
- description: '%'
+ description: null
kind: member
name: the_class
variants: []
- default:
brief: |
- This member is
+ This member indicates the initial requested interval.
definition: ${/score/watchdog/if/interval:/name} ${.:name}
- description: '%'
+ description: null
kind: member
name: initial
variants: []
- default:
brief: |
- This member is
+ This member indicates the time the timer was initially scheduled.
definition: ${/score/watchdog/if/interval:/name} ${.:name}
- description: '%'
+ description: |
+ The time is in clock ticks since the clock driver initialization or the
+ last clock tick counter overflow.
kind: member
name: start_time
variants: []
- default:
brief: |
- This member is
+ This member indicates the time the timer was scheduled to fire.
definition: ${/score/watchdog/if/interval:/name} ${.:name}
- description: '%'
+ description: |
+ The time is in clock ticks since the clock driver initialization or the
+ last clock tick counter overflow.
kind: member
name: stop_time
variants: []
diff --git a/spec/rtems/timer/if/initiate-server.yml b/spec/rtems/timer/if/initiate-server.yml
index 78b99e8..0f58d53 100644
--- a/spec/rtems/timer/if/initiate-server.yml
+++ b/spec/rtems/timer/if/initiate-server.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Initiates the Timer Server.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -13,9 +14,13 @@ definition:
- ${../../attr/if/attribute:/name} ${.:/params[2]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive initiates the Timer Server task. This task is responsible for
+ executing all timers initiated via the ${server-fire-after:/name} or
+ ${server-fire-when:/name} directives.
enabled-by: true
-index-entries: []
+index-entries:
+- initiate the Timer Server
interface-type: function
links:
- role: interface-placement
@@ -23,18 +28,44 @@ links:
- role: interface-ingroup
uid: group
name: rtems_timer_initiate_server
-notes: null
+notes: |
+ This directive may cause the calling task to be preempted due to an obtain
+ and release of the object allocator mutex.
+
+ The Timer Server task is created using the ${../../task/if/create:/name}
+ directive and must be accounted for when configuring the system.
params:
-- description: '%'
+- description: is the task priority.
dir: null
name: priority
-- description: '%'
+- description: is the task stack size in bytes.
dir: null
name: stack_size
-- description: '%'
+- description: is the task attribute set.
dir: null
name: attribute_set
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The Timer Server was already initiated.
+ value: ${../../status/if/incorrect-state:/name}
+ - description: |
+ The task priority was invalid.
+ value: ${../../status/if/invalid-priority:/name}
+ - description: |
+ There was no inactive task object available to create the Timer Server
+ task.
+ value: ${../../status/if/too-many:/name}
+ - description: |
+ There was not enough memory to allocate the task storage area. The task
+ storage area contains the task stack, the thread-local storage, and the
+ floating point context.
+ value: ${../../status/if/unsatisfied:/name}
+ - description: |
+ One of the task create extensions failed to create the Timer Server task.
+ value: ${../../status/if/unsatisfied:/name}
type: interface
diff --git a/spec/rtems/timer/if/interval-on-task.yml b/spec/rtems/timer/if/interval-on-task.yml
index e44ec45..902ccc5 100644
--- a/spec/rtems/timer/if/interval-on-task.yml
+++ b/spec/rtems/timer/if/interval-on-task.yml
@@ -1,5 +1,7 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This timer class indicates that the timer is currently in use as an interval
+ timer which will fire in the context of the Timer Server task.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/rtems/timer/if/interval.yml b/spec/rtems/timer/if/interval.yml
index 925ccbf..9a34aab 100644
--- a/spec/rtems/timer/if/interval.yml
+++ b/spec/rtems/timer/if/interval.yml
@@ -1,5 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This timer class indicates that the timer is currently in use as an interval
+ timer which will fire in the context of the clock tick
+ ${/glossary/isr:/term}.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/rtems/timer/if/reset.yml b/spec/rtems/timer/if/reset.yml
index 3002027..6bbac0f 100644
--- a/spec/rtems/timer/if/reset.yml
+++ b/spec/rtems/timer/if/reset.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Resets the timer.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -11,9 +12,16 @@ definition:
- ${../../type/if/id:/name} ${.:/params[0]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive resets the timer specified by ${.:/params[0]/name}. This
+ timer must have been previously initiated with either the ${fire-after:/name}
+ or ${server-fire-after:/name} directive. If active the timer is canceled,
+ after which the timer is reinitiated using the same interval and timer
+ service routine which the original ${fire-after:/name} or
+ ${server-fire-after:/name} directive used.
enabled-by: true
-index-entries: []
+index-entries:
+- reset a timer
interface-type: function
links:
- role: interface-placement
@@ -21,12 +29,30 @@ links:
- role: interface-ingroup
uid: group
name: rtems_timer_reset
-notes: null
+notes: |
+ This directive will not cause the running task to be preempted.
+
+ If the timer has not been used or the last usage of this timer was by a
+ ${fire-when:/name} or ${server-fire-when:/name} directive, then the
+ ${../../status/if/not-defined:/name} error is returned.
+
+ Restarting a cancelled after timer results in the timer being reinitiated
+ with its previous timer service routine and interval.
params:
-- description: '%'
+- description: is the timer identifier.
dir: null
name: id
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ There was no timer associated with the identifier specified by
+ ${.:/params[0]/name}.
+ value: ${../../status/if/invalid-id:/name}
+ - description: |
+ The timer was not of the interval class.
+ value: ${../../status/if/not-defined:/name}
type: interface
diff --git a/spec/rtems/timer/if/server-default-priority.yml b/spec/rtems/timer/if/server-default-priority.yml
index 5589b44..3631f4a 100644
--- a/spec/rtems/timer/if/server-default-priority.yml
+++ b/spec/rtems/timer/if/server-default-priority.yml
@@ -1,12 +1,16 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This constant represents the default value for the task priority of the Timer
+ Server.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ( (${../../task/if/priority:/name}) -1 )
variants: []
-description: null
+description: |
+ When given this priority, a special high priority not accessible via the
+ Classic API is used.
enabled-by: true
index-entries: []
interface-type: define
diff --git a/spec/rtems/timer/if/server-fire-after.yml b/spec/rtems/timer/if/server-fire-after.yml
index cefb873..086ce8d 100644
--- a/spec/rtems/timer/if/server-fire-after.yml
+++ b/spec/rtems/timer/if/server-fire-after.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Fires the timer after the interval using the Timer Server.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -14,9 +15,16 @@ definition:
- void *${.:/params[3]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive initiates the timer specified by ${.:/params[0]/name}. If the
+ timer is running, it is automatically canceled before being initiated. The
+ timer is scheduled to fire after an interval of clock ticks has passed
+ specified by ${.:/params[1]/name}. When the timer fires, the timer service
+ routine ${.:/params[2]/name} will be invoked with the argument
+ ${.:/params[3]/name} in the context of the Timer Server task.
enabled-by: true
-index-entries: []
+index-entries:
+- fire task-based a timer after an interval
interface-type: function
links:
- role: interface-placement
@@ -24,21 +32,38 @@ links:
- role: interface-ingroup
uid: group
name: rtems_timer_server_fire_after
-notes: null
+notes: |
+ This directive will not cause the running task to be preempted.
params:
-- description: '%'
+- description: is the timer identifier.
dir: null
name: id
-- description: '%'
+- description: is the interval until the routine is fired in clock ticks.
dir: null
name: ticks
-- description: '%'
+- description: is the routine to schedule.
dir: null
name: routine
-- description: '%'
+- description: is the argument passed to the routine when it is fired.
dir: null
name: user_data
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The Timer Server was not initiated.
+ value: ${../../status/if/incorrect-state:/name}
+ - description: |
+ The ${.:/params[1]/name} parameter was 0.
+ value: ${../../status/if/invalid-number:/name}
+ - description: |
+ The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ There was no timer associated with the identifier specified by
+ ${.:/params[0]/name}.
+ value: ${../../status/if/invalid-id:/name}
type: interface
diff --git a/spec/rtems/timer/if/server-fire-when.yml b/spec/rtems/timer/if/server-fire-when.yml
index 714d8ab..037283b 100644
--- a/spec/rtems/timer/if/server-fire-when.yml
+++ b/spec/rtems/timer/if/server-fire-when.yml
@@ -1,5 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Fires the timer at the time of day using the Timer Server.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -14,9 +15,16 @@ definition:
- void *${.:/params[3]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive initiates the timer specified by ${.:/params[0]/name}. If the
+ timer is running, it is automatically canceled before being initiated. The
+ timer is scheduled to fire at the time of day specified by
+ ${.:/params[1]/name}. When the timer fires, the timer service routine
+ ${.:/params[2]/name} will be invoked with the argument ${.:/params[3]/name}
+ in the context of the Timer Server task.
enabled-by: true
-index-entries: []
+index-entries:
+- fire a task-based timer at time of day
interface-type: function
links:
- role: interface-placement
@@ -24,21 +32,44 @@ links:
- role: interface-ingroup
uid: group
name: rtems_timer_server_fire_when
-notes: null
+notes: |
+ This directive will not cause the running task to be preempted.
params:
-- description: '%'
+- description: is the timer identifier.
dir: null
name: id
-- description: '%'
+- description: is the time of day when the routine is fired.
dir: null
name: wall_time
-- description: '%'
+- description: is the routine to schedule.
dir: null
name: routine
-- description: '%'
+- description: is the argument passed to the routine when it is fired.
dir: null
name: user_data
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The Timer Server was not initiated.
+ value: ${../../status/if/incorrect-state:/name}
+ - description: |
+ The system date and time was not set.
+ value: ${../../status/if/not-defined:/name}
+ - description: |
+ The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ The time of day was invalid.
+ value: ${../../status/if/invalid-clock:/name}
+ - description: |
+ There was no timer associated with the identifier specified by
+ ${.:/params[0]/name}.
+ value: ${../../status/if/invalid-id:/name}
type: interface
diff --git a/spec/rtems/timer/if/service-routine-entry.yml b/spec/rtems/timer/if/service-routine-entry.yml
index 9d5a851..02378cf 100644
--- a/spec/rtems/timer/if/service-routine-entry.yml
+++ b/spec/rtems/timer/if/service-routine-entry.yml
@@ -1,5 +1,7 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This type defines the prototype of routines which can be fired by directives
+ of the Timer Manager.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/rtems/timer/if/service-routine.yml b/spec/rtems/timer/if/service-routine.yml
index 058ab5a..c376d9e 100644
--- a/spec/rtems/timer/if/service-routine.yml
+++ b/spec/rtems/timer/if/service-routine.yml
@@ -1,12 +1,15 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This type defines the return type of routines which can be fired by
+ directives of the Timer Manager.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: void ${.:/name}
variants: []
-description: null
+description: |
+ This type can be used to document timer service routines in the source code.
enabled-by: true
index-entries: []
interface-type: typedef
diff --git a/spec/rtems/timer/if/time-of-day-on-task.yml b/spec/rtems/timer/if/time-of-day-on-task.yml
index 0c4880d..e9ac6b8 100644
--- a/spec/rtems/timer/if/time-of-day-on-task.yml
+++ b/spec/rtems/timer/if/time-of-day-on-task.yml
@@ -1,5 +1,7 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This timer class indicates that the timer is currently in use as an time of
+ day timer which will fire in the context of the Timer Server task.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/rtems/timer/if/time-of-day.yml b/spec/rtems/timer/if/time-of-day.yml
index 3717e67..10e90ef 100644
--- a/spec/rtems/timer/if/time-of-day.yml
+++ b/spec/rtems/timer/if/time-of-day.yml
@@ -1,5 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This timer class indicates that the timer is currently in use as an time of
+ day timer which will fire in the context of the clock tick
+ ${/glossary/isr:/term}.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
diff --git a/spec/rtems/timer/req/group.yml b/spec/rtems/timer/req/group.yml
index cec56b3..1164868 100644
--- a/spec/rtems/timer/req/group.yml
+++ b/spec/rtems/timer/req/group.yml
@@ -1,18 +1,16 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: |
- This group contains the Timer Manager implementation.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
-description: null
enabled-by: true
-identifier: ClassicTimerImpl
-index-entries: []
-interface-type: group
+identifier: RTEMSImplClassicTimer
links:
- role: interface-ingroup
- uid: ../../if/group
-name: Timer Manager
+ uid: /req/impl
+non-functional-type: design-group
+rationale: null
+references: []
+requirement-type: non-functional
text: |
- There shall be a software architecture component containing the Timer Manager
+ The software architecture shall have a component containing the Timer Manager
implementation.
-type: interface
+type: requirement
More information about the vc
mailing list