spec: Review Timer Manager API

28 files changed, 408 insertions, 113 deletions

diff --git a/config.yml b/config.yml
index 77eb7be6..98e8f0ed 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 0a302c15..a582c337 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 edfb12eb..712cb416 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 5ce8a376..3cc852ea 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 3a425e0c..e5bedead 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 eaee1d15..f09a6d67 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 64ddc5a7..71ae5ddf 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 1155e20f..5bc65bdc 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 003c0041..7b543987 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 6664a7ce..63647897 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 556f48a9..a6fde1c0 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 6d89a721..b4a414ea 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 d6044a45..a37beb1c 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 be9b9492..13f183ed 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 c119ab6c..4218efa1 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 ddccba28..4cac081c 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 78b99e83..0f58d53d 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 e44ec45c..902ccc5c 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 925ccbf7..9a34aabd 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 3002027e..6bbac0fe 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 5589b447..3631f4a4 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 cefb8731..086ce8d2 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 714d8abf..037283b8 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 9d5a8510..02378cf3 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 058ab5ae..c376d9ec 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 0c4880d4..e9ac6b8d 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 3717e67f..10e90efa 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 cec56b3a..11648682 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