From c970d6373fefc6cbb73f0c91dff03865fd2be07c Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Tue, 1 Dec 2020 14:57:03 +0100 Subject: 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 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 -- cgit v1.2.3