diff options
| author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-04-23 11:08:10 +0200 |
|---|---|---|
| committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-04-28 07:31:20 +0200 |
| commit | a5161ecede4c2a17f1184514d231e90b4f1cf7da (patch) | |
| tree | 5f3311c56302167c766c06e2b5e5513f946da22d | |
| parent | spec: Generalize may preempt constraints (diff) | |
| download | rtems-central-a5161ecede4c2a17f1184514d231e90b4f1cf7da.tar.bz2 | |
spec: Update /rtems/task/* documentation
41 files changed, 849 insertions, 159 deletions
diff --git a/spec/constraint/affinity-may-preempt.yml b/spec/constraint/affinity-may-preempt.yml new file mode 100644 index 00000000..99bbc135 --- /dev/null +++ b/spec/constraint/affinity-may-preempt.yml @@ -0,0 +1,11 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +links: [] +rationale: null +scope: user +text: | + The directive may change the processor affinity of a task. This may cause + the calling task to be preempted. +type: constraint diff --git a/spec/constraint/fatal-bad-thread-dispatch-disable-level.yml b/spec/constraint/fatal-bad-thread-dispatch-disable-level.yml new file mode 100644 index 00000000..be1b87c6 --- /dev/null +++ b/spec/constraint/fatal-bad-thread-dispatch-disable-level.yml @@ -0,0 +1,13 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +links: [] +rationale: null +scope: user +text: | + While thread dispatching is disabled, if the directive performs a thread + dispatch, then the fatal error with the fatal source + ${/score/interr/if/internal-error-core:/name} and the fatal code + ${/score/interr/if/bad-thread-dispatch-disable-level:/name} will occur. +type: constraint diff --git a/spec/constraint/fatal-bad-thread-dispatch-environment.yml b/spec/constraint/fatal-bad-thread-dispatch-environment.yml new file mode 100644 index 00000000..27140cd8 --- /dev/null +++ b/spec/constraint/fatal-bad-thread-dispatch-environment.yml @@ -0,0 +1,16 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +links: [] +rationale: null +scope: user +text: | + Where the ${/glossary/target-arch:/term} enabled robust thread dispatching, + or the system was built with SMP support enabled and inter-processor + interrupts are necessary, while thread dispatching is enabled, while maskable + interrupts are disabled, if the directive performs a thread dispatch, then + the fatal error with the fatal source + ${/score/interr/if/internal-error-core:/name} and the fatal code + ${/score/interr/if/bad-thread-dispatch-environment:/name} will occur. +type: constraint diff --git a/spec/rtems/task/if/argument.yml b/spec/rtems/task/if/argument.yml index e3eaba70..8391c081 100644 --- a/spec/rtems/task/if/argument.yml +++ b/spec/rtems/task/if/argument.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - This type is used to represent task argument values. + This integer type represents task argument values. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/task/if/configured-minimum-stack-size.yml b/spec/rtems/task/if/configured-minimum-stack-size.yml index 43878c9f..cc05a1c0 100644 --- a/spec/rtems/task/if/configured-minimum-stack-size.yml +++ b/spec/rtems/task/if/configured-minimum-stack-size.yml @@ -1,12 +1,24 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This constant can be used to indicate that the task should be created with + the configured minimum stack size. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: '0' variants: [] -description: null +description: | + Using this constant when specifying the task stack size indicates that this + task is to be created with a stack size of the minimum stack size that was + configured by the application. If not explicitly configured by the + application, the default configured minimum stack size is + ${minimum-stack-size:/name} which depends on the + ${/glossary/target-arch:/term}. Since this uses the configured minimum stack + size value, you may get a stack size that is smaller or larger than the + recommended minimum. This can be used to provide large stacks for all tasks + on complex applications or small stacks on applications that are trying to + conserve memory. enabled-by: true index-entries: [] interface-type: define diff --git a/spec/rtems/task/if/construct.yml b/spec/rtems/task/if/construct.yml index 4cacfe48..5b97b6f1 100644 --- a/spec/rtems/task/if/construct.yml +++ b/spec/rtems/task/if/construct.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Constructs a task from the specified the task configuration. + Constructs a task from the specified task configuration. copyrights: - Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/task/if/current-priority.yml b/spec/rtems/task/if/current-priority.yml index 8911c300..e82a515f 100644 --- a/spec/rtems/task/if/current-priority.yml +++ b/spec/rtems/task/if/current-priority.yml @@ -1,6 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - This constant is passed to {set-priority:/name}() when the caller wants to + This constant is passed to {set-priority:/name} when the caller wants to obtain the current priority. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) diff --git a/spec/rtems/task/if/delete.yml b/spec/rtems/task/if/delete.yml index 0e3678aa..af5207c3 100644 --- a/spec/rtems/task/if/delete.yml +++ b/spec/rtems/task/if/delete.yml @@ -65,7 +65,8 @@ notes: | ${../../attr/if/global:/name} attribute. params: - description: | - is the task identifier. + is the task identifier. The constant ${self-define:/name} may be used to + specify the calling task. dir: null name: id return: diff --git a/spec/rtems/task/if/exit.yml b/spec/rtems/task/if/exit.yml index 3c547e8f..de6592d3 100644 --- a/spec/rtems/task/if/exit.yml +++ b/spec/rtems/task/if/exit.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Deletes the calling task. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -10,17 +11,43 @@ definition: params: [] return: void variants: [] -description: null +description: | + This directive deletes the calling task. enabled-by: true -index-entries: [] +index-entries: +- deleting a task interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/directive-no-return +- role: constraint + uid: /constraint/fatal-bad-thread-dispatch-disable-level name: rtems_task_exit -notes: null +notes: | + The directive is an optimized variant of the following code sequences, see + also ${delete:/name}: + + .. code-block:: c + + #include <pthread.h> + #include <rtems.h> + + void classic_delete_self( void ) + { + (void) rtems_task_delete( RTEMS_SELF ); + } + + void posix_delete_self( void ) + { + (void) pthread_detach( pthread_self() ); + (void) pthread_exit( NULL); + } params: [] return: return: null diff --git a/spec/rtems/task/if/get-affinity.yml b/spec/rtems/task/if/get-affinity.yml index 06476ae8..b28df7b5 100644 --- a/spec/rtems/task/if/get-affinity.yml +++ b/spec/rtems/task/if/get-affinity.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the processor affinity of the task. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -13,7 +14,9 @@ definition: - ${/c/if/cpu_set_t:/name} *${.:/params[2]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive returns the processor affinity of the task in + ${.:/params[2]/name} of the task specified by ${.:/params[0]/name}. enabled-by: true index-entries: [] interface-type: function @@ -22,19 +25,51 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-isr +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/directive-no-preempt name: rtems_task_get_affinity notes: null params: -- description: '%' +- description: | + is the task identifier. The constant ${self-define:/name} may be used to + specify the calling task. dir: null name: id -- description: '%' +- description: | + is the size of the referenced processor set variable in bytes. dir: null name: cpusetsize -- description: '%' - dir: null +- description: | + is the pointer to a processor set variable. When the directive call is + successful, the processor affinity set of the task will be stored in this + variable. A set bit in the processor set means that the corresponding + processor is in the processor affinity set of the task, otherwise the bit + is cleared. + dir: out name: cpuset return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + The ${.:/params[2]/name} parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + There was no task associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The provided processor set was too small for the processor affinity set of the task. + value: ${../../status/if/invalid-size:/name} + - description: | + The task resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} type: interface diff --git a/spec/rtems/task/if/get-priority.yml b/spec/rtems/task/if/get-priority.yml index 07af9049..cdaf4cfb 100644 --- a/spec/rtems/task/if/get-priority.yml +++ b/spec/rtems/task/if/get-priority.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the current priority of the task with respect to the scheduler. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -13,28 +14,71 @@ definition: - ${../../type/if/priority:/name} *${.:/params[2]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive returns the current priority in ${.:/params[2]/name} of the + task specified by ${.:/params[0]/name} with respect to the scheduler + specified by ${.:/params[1]/name}. enabled-by: true -index-entries: [] +index-entries: +- current task priority +- get task priority +- obtain task priority interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-isr +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/directive-no-preempt name: rtems_task_get_priority -notes: null +notes: | + The current priority reflects temporary priority adjustments due to locking + protocols, the rate-monotonic period objects on some schedulers, and other + mechanisms. params: -- description: '%' +- description: | + is the task identifier. The constant ${self-define:/name} may be used to + specify the calling task. dir: null name: task_id -- description: '%' +- description: | + is the scheduler identifier. dir: null name: scheduler_id -- description: '%' - dir: null +- description: | + is the pointer to an ${../../type/if/priority:/name} variable. When the + directive call is successful, the current priority of the task with respect + to the specified scheduler will be stored in this variable. + dir: out name: priority return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + The ${.:/params[2]/name} parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + There was no task associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + There was no scheduler associated with the identifier specified by + ${.:/params[1]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The task had no priority with respect to the scheduler. + value: ${../../status/if/not-defined:/name} + - description: | + The task resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} type: interface diff --git a/spec/rtems/task/if/get-scheduler.yml b/spec/rtems/task/if/get-scheduler.yml index 63be27e4..f3dbc54d 100644 --- a/spec/rtems/task/if/get-scheduler.yml +++ b/spec/rtems/task/if/get-scheduler.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the home scheduler of the task. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -12,7 +13,10 @@ definition: - ${../../type/if/id:/name} *${.:/params[1]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive returns the identifier of the + ${/glossary/scheduler-home:/term} of the task specified by + ${.:/params[0]/name} in ${.:/params[1]/name}. enabled-by: true index-entries: [] interface-type: function @@ -21,16 +25,43 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-isr +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/directive-no-preempt name: rtems_task_get_scheduler notes: null params: -- description: '%' +- description: | + is the task identifier. The constant ${self-define:/name} may be used to + specify the calling task. dir: null name: task_id -- description: '%' - dir: null +- description: | + is the pointer to an ${../../type/if/id:/name} variable. When the + directive call is successful, the identifier of the + ${/glossary/scheduler-home:/term} of the task will be stored in this + variable. + dir: out name: scheduler_id 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 task associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The task resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} type: interface diff --git a/spec/rtems/task/if/group.yml b/spec/rtems/task/if/group.yml index da6d069c..d1a5e4d6 100644 --- a/spec/rtems/task/if/group.yml +++ b/spec/rtems/task/if/group.yml @@ -15,6 +15,48 @@ links: uid: header - role: interface-ingroup uid: ../../if/group +- role: placement-order + uid: create +- role: placement-order + uid: construct +- role: placement-order + uid: ident +- role: placement-order + uid: self +- role: placement-order + uid: start +- role: placement-order + uid: restart +- role: placement-order + uid: delete +- role: placement-order + uid: exit +- role: placement-order + uid: suspend +- role: placement-order + uid: resume +- role: placement-order + uid: is-suspended +- role: placement-order + uid: set-priority +- role: placement-order + uid: get-priority +- role: placement-order + uid: mode +- role: placement-order + uid: wake-after +- role: placement-order + uid: wake-when +- role: placement-order + uid: get-scheduler +- role: placement-order + uid: set-scheduler +- role: placement-order + uid: get-affinity +- role: placement-order + uid: set-affinity +- role: placement-order + uid: iterate name: Task Manager text: | The Classic API shall provide an interface to the Task Manager. diff --git a/spec/rtems/task/if/initialization-table.yml b/spec/rtems/task/if/initialization-table.yml index e7022cff..ba96c9b6 100644 --- a/spec/rtems/task/if/initialization-table.yml +++ b/spec/rtems/task/if/initialization-table.yml @@ -1,55 +1,64 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This structure defines the properties of the Classic API user initialization + task. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: - default: - brief: '%' + brief: | + This member defines the task name. definition: ${../../type/if/name:/name} ${.:name} - description: '%' + description: null kind: member name: name variants: [] - default: - brief: '%' + brief: | + This member defines the task stack size in bytes. definition: ${/c/if/size_t:/name} ${.:name} - description: '%' + description: null kind: member name: stack_size variants: [] - default: - brief: '%' + brief: | + This member defines the initial task priority. definition: ${../../type/if/priority:/name} ${.:name} - description: '%' + description: null kind: member name: initial_priority variants: [] - default: - brief: '%' + brief: | + This member defines the attribute set of the task. definition: ${../../attr/if/attribute:/name} ${.:name} - description: '%' + description: null kind: member name: attribute_set variants: [] - default: - brief: '%' + brief: | + This member defines the entry point of the task. definition: ${entry:/name} ${.:name} - description: '%' + description: null kind: member name: entry_point variants: [] - default: - brief: '%' + brief: | + This member defines the initial modes of the task. definition: ${../../mode/if/mode:/name} ${.:name} - description: '%' + description: null kind: member name: mode_set variants: [] - default: - brief: '%' + brief: | + This member defines the entry point argument of the task. definition: ${argument:/name} ${.:name} - description: '%' + description: null kind: member name: argument variants: [] diff --git a/spec/rtems/task/if/is-suspended.yml b/spec/rtems/task/if/is-suspended.yml index b7835cf4..fbfd8c0c 100644 --- a/spec/rtems/task/if/is-suspended.yml +++ b/spec/rtems/task/if/is-suspended.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Checks if the task is suspended. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -11,7 +12,9 @@ definition: - ${../../type/if/id:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive returns a status code indicating whether or not the task + specified by ${.:/params[0]/name} is currently suspended. enabled-by: true index-entries: [] interface-type: function @@ -20,13 +23,36 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-isr +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/directive-no-preempt name: rtems_task_is_suspended notes: null params: -- description: '%' +- description: | + is the task identifier. The constant ${self-define:/name} may be used to + specify the calling task. dir: null name: id return: return: null - return-values: [] + return-values: + - description: | + The task was **not** suspended. + value: ${../../status/if/successful:/name} + - description: | + There was no task associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The task was suspended. + value: ${../../status/if/already-suspended:/name} + - description: | + The task resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} type: interface diff --git a/spec/rtems/task/if/iterate.yml b/spec/rtems/task/if/iterate.yml index 40efa094..e6eed471 100644 --- a/spec/rtems/task/if/iterate.yml +++ b/spec/rtems/task/if/iterate.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Iterates over all tasks and invokes the visitor routine for each task. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -12,7 +13,12 @@ definition: - void *${.:/params[1]/name} return: void variants: [] -description: null +description: | + This directive iterates over all tasks in the system. This operation covers + all tasks of all APIs. The user should be careful in accessing the contents + of the ${/glossary/tcb:/term}. The visitor argument ${.:/params[1]/name} is + passed to all invocations of ${.:/params[0]/name} in addition to the TCB. + The iteration stops immediately in case the visitor routine returns true. enabled-by: true index-entries: [] interface-type: function @@ -21,13 +27,26 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/object-allocator name: rtems_task_iterate -notes: null +notes: | + The visitor routine is invoked while owning the objects allocator lock. It + is allowed to perform blocking operations in the visitor routine, however, + care must be taken so that no deadlocks via the object allocator lock can + occur. params: -- description: '%' +- description: | + is the visitor routine invoked for each task. dir: null name: visitor -- description: '%' +- description: | + is the argument passed to each visitor routine invocation during the + iteration. dir: null name: arg return: diff --git a/spec/rtems/task/if/maximum-priority.yml b/spec/rtems/task/if/maximum-priority.yml index 4da3aa1b..fccfc5f6 100644 --- a/spec/rtems/task/if/maximum-priority.yml +++ b/spec/rtems/task/if/maximum-priority.yml @@ -1,7 +1,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This constant variable provides the lowest (least important) task priority of + the first configured scheduler. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: ${/score/if/maximum-priority:/name}() diff --git a/spec/rtems/task/if/minimum-priority.yml b/spec/rtems/task/if/minimum-priority.yml index f4ca4c12..7dfbd7a6 100644 --- a/spec/rtems/task/if/minimum-priority.yml +++ b/spec/rtems/task/if/minimum-priority.yml @@ -1,5 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This compile time constant provides the highest (most important) task + priority settable by the ${/glossary/api:/term}. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) diff --git a/spec/rtems/task/if/minimum-stack-size.yml b/spec/rtems/task/if/minimum-stack-size.yml index 6239ea30..280f9d8e 100644 --- a/spec/rtems/task/if/minimum-stack-size.yml +++ b/spec/rtems/task/if/minimum-stack-size.yml @@ -1,12 +1,21 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This compile time constant provides the minimum task stack size recommended + for the ${/glossary/target-arch:/term}. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) definition: default: ${/score/stack/if/minimum-size:/name} variants: [] -description: null +description: | + It is the minimum stack size recommended for use on this processor. This + value is selected by the RTEMS maintainers conservatively to minimize the risk + of blown stacks for most user applications. Using this constant when + specifying the task stack size, indicates that the stack size will be at + least RTEMS_MINIMUM_STACK_SIZE bytes in size. If the user configured minimum + stack size (see ${/acfg/if/min-task-stack-size:/name}) is larger than the + recommended minimum, then it will be used. enabled-by: true index-entries: [] interface-type: define diff --git a/spec/rtems/task/if/mode.yml b/spec/rtems/task/if/mode.yml index 8b1957a3..5cfb0e6b 100644 --- a/spec/rtems/task/if/mode.yml +++ b/spec/rtems/task/if/mode.yml @@ -112,6 +112,8 @@ links: uid: /constraint/directive-ctx-task - role: constraint uid: ../constraint/preempt-enable +- role: constraint + uid: /constraint/fatal-bad-thread-dispatch-disable-level name: rtems_task_mode notes: null params: diff --git a/spec/rtems/task/if/no-priority.yml b/spec/rtems/task/if/no-priority.yml index 70fbda7c..6708e9f6 100644 --- a/spec/rtems/task/if/no-priority.yml +++ b/spec/rtems/task/if/no-priority.yml @@ -1,7 +1,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This compile time constant may be used for the ${set-priority:/name} + directive to get the current task priority. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: ${current-priority:/name} diff --git a/spec/rtems/task/if/restart.yml b/spec/rtems/task/if/restart.yml index 5a174ba3..266616e9 100644 --- a/spec/rtems/task/if/restart.yml +++ b/spec/rtems/task/if/restart.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Restarts the task. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) @@ -12,25 +13,71 @@ definition: - ${argument:/name} ${.:/params[1]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive resets the task specified by ${.:/params[0]/name} to begin + execution at its original entry point. The task's priority and execution + mode are set to the original creation values. If the task is currently + blocked, RTEMS automatically makes the task ready. A task can be restarted + from any state, except the dormant state. The task's entry point argument is + contained in ${.:/params[1]/name}. enabled-by: true -index-entries: [] +index-entries: +- restarting a task interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-isr +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/priority-may-preempt +- role: constraint + uid: /constraint/unblock-may-preempt name: rtems_task_restart -notes: null +notes: | + The type of the entry point argument is an unsigned integer type. However, + the integer type has the property that any valid pointer to ``void`` can be + converted to this type and then converted back to a pointer to ``void``. The + result will compare equal to the original pointer. The type can represent at + least 32 bits. Some applications use the entry point argument as an index + into a parameter table to get task-specific parameters. + + A new entry point argument may be used to distinguish between the initial + ${start:/name} of the task and any ensuing calls to ${restart:/name} of the + task. This can be beneficial in deleting a task. Instead of deleting a task + using the ${delete:/name} directive, a task can delete another task by + restarting that task, and allowing that task to release resources back to + RTEMS and then delete itself. params: -- description: '%' +- description: | + is the task identifier. The constant ${self-define:/name} may be used to + specify the calling task. dir: null name: id -- description: '%' +- description: | + is the task entry point argument. dir: null name: argument return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no task associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The task never started. + value: ${../../status/if/incorrect-state:/name} + - description: | + The task resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} type: interface diff --git a/spec/rtems/task/if/resume.yml b/spec/rtems/task/if/resume.yml index 5bc4077f..e02aec24 100644 --- a/spec/rtems/task/if/resume.yml +++ b/spec/rtems/task/if/resume.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Resumes the task. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -11,22 +12,49 @@ definition: - ${../../type/if/id:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive removes the task specified by ${.:/params[0]/name} from the + suspended state. If the task is in the ready state after the suspension is + removed, then it will be scheduled to run. If the task is still in a blocked + state after the suspension is removed, then it will remain in that blocked + state. enabled-by: true -index-entries: [] +index-entries: +- resuming a task interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-isr +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/unblock-may-preempt +- role: constraint + uid: /constraint/directive-remote name: rtems_task_resume notes: null params: -- description: '%' +- description: | + is the task 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 task associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The task was not suspended. + value: ${../../status/if/incorrect-state:/name} type: interface diff --git a/spec/rtems/task/if/self-define.yml b/spec/rtems/task/if/self-define.yml index 8abe639b..6511cb6d 100644 --- a/spec/rtems/task/if/self-define.yml +++ b/spec/rtems/task/if/self-define.yml @@ -1,7 +1,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This compile time constant may be used to identify the calling task in task + related directives. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: ${/score/object/if/id-of-self:/name} diff --git a/spec/rtems/task/if/self.yml b/spec/rtems/task/if/self.yml index 0542ed43..cb9daad9 100644 --- a/spec/rtems/task/if/self.yml +++ b/spec/rtems/task/if/self.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Gets the task identifier of the calling task. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -10,19 +11,28 @@ definition: params: [] return: ${../../type/if/id:/name} variants: [] -description: null +description: | + This directive returns the task identifier of the calling task. enabled-by: true -index-entries: [] +index-entries: +- obtain ID of caller interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/directive-no-preempt name: rtems_task_self notes: null params: [] return: - return: null + return: | + Returns the task identifier of the calling task. return-values: [] type: interface diff --git a/spec/rtems/task/if/set-affinity.yml b/spec/rtems/task/if/set-affinity.yml index d0457a46..6323dab9 100644 --- a/spec/rtems/task/if/set-affinity.yml +++ b/spec/rtems/task/if/set-affinity.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Sets the processor affinity of the task. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -13,7 +14,9 @@ definition: - const ${/c/if/cpu_set_t:/name} *${.:/params[2]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive sets the processor affinity of the task specified by + ${.:/params[0]/name}. enabled-by: true index-entries: [] interface-type: function @@ -22,19 +25,51 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-isr +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/affinity-may-preempt name: rtems_task_set_affinity notes: null params: -- description: '%' +- description: | + is the task identifier. The constant ${self-define:/name} may be used to + specify the calling task. dir: null name: id -- description: '%' +- description: | + is the size of the referenced processor set variable in bytes. dir: null name: cpusetsize -- description: '%' +- description: | + is the pointer to a processor set variable. The processor set defines the + new processor affinity set of the task. A set bit in the processor set + means that the corresponding processor shall be in the processor affinity + set of the task, otherwise the bit shall be cleared. dir: null name: cpuset return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + The ${.:/params[2]/name} parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + There was no task associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The referenced processor set was not a valid new processor affinity set + for the task. + value: ${../../status/if/invalid-number:/name} + - description: | + The task resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} type: interface diff --git a/spec/rtems/task/if/set-priority.yml b/spec/rtems/task/if/set-priority.yml index c749c8ed..d667bd8e 100644 --- a/spec/rtems/task/if/set-priority.yml +++ b/spec/rtems/task/if/set-priority.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Sets the real priority or gets the current priority of the task. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -13,28 +14,82 @@ definition: - ${../../type/if/priority:/name} *${.:/params[2]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive manipulates the priority of the task specified by + ${.:/params[0]/name}. When ${.:/params[1]/name} is not equal to + ${current-priority:/name}, the specified task's previous priority is returned + in ${.:/params[2]/name}. When ${.:/params[1]/name} is + ${current-priority:/name}, the specified task's current priority is returned + in ${.:/params[2]/name}. enabled-by: true -index-entries: [] +index-entries: +- current task priority +- set task priority +- get task priority +- obtain task priority interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-isr +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/priority-may-preempt +- role: constraint + uid: /constraint/directive-remote name: rtems_task_set_priority -notes: null +notes: | + Valid priorities range from one to a maximum value which depends on the + configured scheduler. The lower the priority value the higher is the + importance of the task. + + If the task is currently holding any binary semaphores which use a locking + protocol, then the task's priority cannot be lowered immediately. If the + task's priority were lowered immediately, then this could violate properties + of the locking protocol and may result in priority inversion. The requested + lowering of the task's priority will occur when the task has released all + binary semaphores which make the task more important. The task's priority + can be increased regardless of the task's use of binary semaphores with + locking protocols. params: -- description: '%' +- description: | + is the task identifier. The constant ${self-define:/name} may be used to + specify the calling task. dir: null name: id -- description: '%' +- description: | + is the new real priority or ${current-priority:/name} to get the current + priority. dir: null name: new_priority -- description: '%' - dir: null +- description: | + is the pointer to an ${../../type/if/priority:/name} variable. When the + directive call is successful, the current or previous priority of the task + with respect to its ${/glossary/scheduler-home:/term} will be stored in + this variable. + dir: out name: old_priority return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + The ${.:/params[2]/name} parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + There was no task associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The task priority specified in ${.:/params[1]/name} was invalid with + respect to the ${/glossary/scheduler-home:/term} of the task. + value: ${../../status/if/invalid-priority:/name} type: interface diff --git a/spec/rtems/task/if/set-scheduler.yml b/spec/rtems/task/if/set-scheduler.yml index 1de8dbbc..11c829d4 100644 --- a/spec/rtems/task/if/set-scheduler.yml +++ b/spec/rtems/task/if/set-scheduler.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Sets the home scheduler for the task. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -13,7 +14,10 @@ definition: - ${../../type/if/priority:/name} ${.:/params[2]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive sets the ${/glossary/scheduler-home:/term} to the scheduler + specified by ${.:/params[1]/name} for the task specified by + ${.:/params[0]/name}. enabled-by: true index-entries: [] interface-type: function @@ -22,19 +26,51 @@ links: uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-isr +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/priority-may-preempt name: rtems_task_set_scheduler notes: null params: -- description: '%' +- description: | + is the task identifier. The constant ${self-define:/name} may be used to + specify the calling task. dir: null name: task_id -- description: '%' +- description: | + is the scheduler identifier of the new ${/glossary/scheduler-home:/term} for + the task specified by ${.:/params[0]/name}. dir: null name: scheduler_id -- description: '%' +- description: | + is the new real priority for the task with respect to the scheduler + specified by ${.:/params[1]/name}. dir: null name: priority return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + There was no scheduler associated with the identifier specified by + ${.:/params[1]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + There task priority specified in ${.:/params[2]/name} was invalid with + respect to the scheduler specified by ${.:/params[1]/name}. + value: ${../../status/if/invalid-priority:/name} + - description: | + There was no task associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The task resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} type: interface diff --git a/spec/rtems/task/if/start.yml b/spec/rtems/task/if/start.yml index 75ad2d26..194d4a41 100644 --- a/spec/rtems/task/if/start.yml +++ b/spec/rtems/task/if/start.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Starts the task. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -13,28 +14,71 @@ definition: - ${argument:/name} ${.:/params[2]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive readies the task, specified by ${.:/params[0]/name}, for + execution based on the priority and execution mode specified when the task + was created. The entry point of the task is given in ${.:/params[1]/name}. + The task's entry point argument is contained in ${.:/params[2]/name}. enabled-by: true -index-entries: [] +index-entries: +- starting a task interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-isr +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/unblock-may-preempt name: rtems_task_start -notes: null +notes: | + The type of the entry point argument is an unsigned integer type. However, + the integer type has the property that any valid pointer to ``void`` can be + converted to this type and then converted back to a pointer to ``void``. The + result will compare equal to the original pointer. The type can represent at + least 32 bits. Some applications use the entry point argument as an index + into a parameter table to get task-specific parameters. + + Any actions performed on a dormant task such as suspension or change of + priority are nullified when the task is initiated via the ${start:/name} + directive. params: -- description: '%' +- description: | + is the task identifier. The constant ${self-define:/name} may be used to + specify the calling task. dir: null name: id -- description: '%' +- description: | + is the task entry point. dir: null name: entry_point -- description: '%' +- description: | + is the task entry point argument. dir: null name: argument 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 task associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The task was not in the dormant state. + value: ${../../status/if/incorrect-state:/name} + - description: | + The task resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} type: interface diff --git a/spec/rtems/task/if/storage-alignment.yml b/spec/rtems/task/if/storage-alignment.yml index 8ce31472..fbc04683 100644 --- a/spec/rtems/task/if/storage-alignment.yml +++ b/spec/rtems/task/if/storage-alignment.yml @@ -1,7 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - This constant defines the recommended alignment of a task storage area in - bytes. + This compile time constant defines the recommended alignment of a task + storage area in bytes. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: diff --git a/spec/rtems/task/if/storage-size.yml b/spec/rtems/task/if/storage-size.yml index 07926513..964ddee4 100644 --- a/spec/rtems/task/if/storage-size.yml +++ b/spec/rtems/task/if/storage-size.yml @@ -1,7 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: | - Returns the recommended task storage area size for the specified size and task - attributes. + Gets the recommended task storage area size for the size and task attributes. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) definition: @@ -36,7 +35,7 @@ params: name: _attributes return: return: | - The recommended task storage area size calculated from the input parameters - is returned. + Returns the recommended task storage area size calculated from the input + parameters. return-values: [] type: interface diff --git a/spec/rtems/task/if/suspend.yml b/spec/rtems/task/if/suspend.yml index 1870f7fd..0943f25b 100644 --- a/spec/rtems/task/if/suspend.yml +++ b/spec/rtems/task/if/suspend.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Suspends the task. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -11,22 +12,56 @@ definition: - ${../../type/if/id:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive suspends the task specified by ${.:/params[0]/name} from + further execution by placing it in the suspended state. This state is + additive to any other blocked state that the task may already be in. The + task will not execute again until another task issues the ${resume:/name} + directive for this task and any blocked state has been removed. The + ${restart:/name} directive will also remove the suspended state. enabled-by: true -index-entries: [] +index-entries: +- suspending a task interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-isr +- role: constraint + uid: /constraint/directive-ctx-devinit +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/directive-remote name: rtems_task_suspend -notes: null +notes: | + The requesting task can suspend itself for example by specifying + ${self-define:/name} as ${.:/params[0]/name}. In this case, the task will be + suspended and a successful return code will be returned when the task is + resumed. params: -- description: '%' +- description: | + is the task identifier. The constant ${self-define:/name} may be used to + specify the calling task. 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 task associated with the identifier specified by + ${.:/params[0]/name}. + value: ${../../status/if/invalid-id:/name} + - description: | + The task was already suspended. + value: ${../../status/if/already-suspended:/name} + - description: | + The task resided on a remote node. + value: ${../../status/if/illegal-on-remote-object:/name} type: interface diff --git a/spec/rtems/task/if/task.yml b/spec/rtems/task/if/task.yml index c563ca0b..951d166d 100644 --- a/spec/rtems/task/if/task.yml +++ b/spec/rtems/task/if/task.yml @@ -1,12 +1,14 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This type defines the return type of task entry points. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: void ${.:/name} variants: [] -description: null +description: | + This type can be used to document task entry points in the source code. enabled-by: true index-entries: [] interface-type: typedef diff --git a/spec/rtems/task/if/tcb.yml b/spec/rtems/task/if/tcb.yml index ce89e258..98831745 100644 --- a/spec/rtems/task/if/tcb.yml +++ b/spec/rtems/task/if/tcb.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This structure represents the ${/glossary/tcb:/term}. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: struct _Thread_Control ${.:/name} diff --git a/spec/rtems/task/if/visitor.yml b/spec/rtems/task/if/visitor.yml index f0f949f6..6a417a6c 100644 --- a/spec/rtems/task/if/visitor.yml +++ b/spec/rtems/task/if/visitor.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Visitor routines invoked by ${iterate:/name} shall have this type. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) diff --git a/spec/rtems/task/if/wake-after.yml b/spec/rtems/task/if/wake-after.yml index 4e2b0f74..b3805251 100644 --- a/spec/rtems/task/if/wake-after.yml +++ b/spec/rtems/task/if/wake-after.yml @@ -1,7 +1,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Wakes up after an interval in ${/glossary/clock-tick:/plural} or yields the + processor. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -11,22 +13,44 @@ definition: - ${../../type/if/interval:/name} ${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive blocks the calling task for the specified ${.:/params[0]/name} + of clock ticks if the value is not equal to ${yield-processor:/name}. When + the requested interval has elapsed, the task is made ready. The clock tick + directives automatically updates the delay period. The calling task may give + up the processor and remain in the ready state by specifying a value of + ${yield-processor:/name} in ${.:/params[0]/name}. enabled-by: true -index-entries: [] +index-entries: +- delay a task for an interval +- wake up after an interval interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/clock-driver +- role: constraint + uid: /constraint/fatal-bad-thread-dispatch-disable-level name: rtems_task_wake_after -notes: null +notes: | + Setting the system date and time with the ${../../clock/if/set:/name} + directive and similar directives which set ${/glossary/clock-realtime:/term} + have no effect on a ${wake-after:/name} blocked task. params: -- description: '%' +- description: | + is the interval in ${/glossary/clock-tick:/plural} to delay the task or + ${yield-processor:/name} to yield the processor. dir: null name: ticks return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} type: interface diff --git a/spec/rtems/task/if/wake-when.yml b/spec/rtems/task/if/wake-when.yml index da7dfb50..90be9d50 100644 --- a/spec/rtems/task/if/wake-when.yml +++ b/spec/rtems/task/if/wake-when.yml @@ -1,7 +1,8 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Wakes up when specified. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: @@ -11,22 +12,48 @@ definition: - ${../../type/if/time-of-day:/name} *${.:/params[0]/name} return: ${../../status/if/code:/name} variants: [] -description: null +description: | + This directive blocks a task until the date and time specified in + ${.:/params[0]/name}. At the requested date and time, the calling task will + be unblocked and made ready to execute. enabled-by: true -index-entries: [] +index-entries: +- delay a task until a wall time +- wake up at a wall time interface-type: function links: - role: interface-placement uid: header - role: interface-ingroup uid: group +- role: constraint + uid: /constraint/directive-ctx-task +- role: constraint + uid: /constraint/clock-driver +- role: constraint + uid: /constraint/fatal-bad-thread-dispatch-disable-level name: rtems_task_wake_when -notes: null +notes: | + The ticks portion of ${.:/params[0]/name} structure is ignored. The timing + granularity of this directive is a second. params: -- description: '%' +- description: | + is the date and time to wake up. dir: null name: time_buffer 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[0]/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} type: interface diff --git a/spec/rtems/task/if/yield-processor.yml b/spec/rtems/task/if/yield-processor.yml index b2d1b289..f72f3fca 100644 --- a/spec/rtems/task/if/yield-processor.yml +++ b/spec/rtems/task/if/yield-processor.yml @@ -1,7 +1,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This compile time constant may be passed to the ${wake-after:/name} directive + as the interval when a task wishes to yield the processor. copyrights: -- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) definition: default: ${/score/watchdog/if/no-timeout:/name} diff --git a/spec/score/interr/if/bad-thread-dispatch-disable-level.yml b/spec/score/interr/if/bad-thread-dispatch-disable-level.yml new file mode 100644 index 00000000..91269bf7 --- /dev/null +++ b/spec/score/interr/if/bad-thread-dispatch-disable-level.yml @@ -0,0 +1,13 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +index-entries: [] +interface-type: unspecified-define +links: +- role: interface-placement + uid: header +name: INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL +references: + c-user: internal_errors +type: interface diff --git a/spec/score/interr/if/bad-thread-dispatch-environment.yml b/spec/score/interr/if/bad-thread-dispatch-environment.yml new file mode 100644 index 00000000..7b4e17b6 --- /dev/null +++ b/spec/score/interr/if/bad-thread-dispatch-environment.yml @@ -0,0 +1,13 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +index-entries: [] +interface-type: unspecified-define +links: +- role: interface-placement + uid: header +name: INTERNAL_ERROR_BAD_THREAD_DISPATCH_ENVIRONMENT +references: + c-user: internal_errors +type: interface diff --git a/spec/score/interr/if/internal-error-core.yml b/spec/score/interr/if/internal-error-core.yml new file mode 100644 index 00000000..1530520f --- /dev/null +++ b/spec/score/interr/if/internal-error-core.yml @@ -0,0 +1,13 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +copyrights: +- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) +enabled-by: true +index-entries: [] +interface-type: unspecified-define +links: +- role: interface-placement + uid: header +name: INTERNAL_ERROR_CORE +references: + c-user: FatalErrorSources +type: interface |