[rtems-central commit] spec: Update /rtems/task/* documentation
Sebastian Huber
sebh at rtems.org
Wed Apr 28 07:04:36 UTC 2021
Module: rtems-central
Branch: master
Commit: a5161ecede4c2a17f1184514d231e90b4f1cf7da
Changeset: http://git.rtems.org/rtems-central/commit/?id=a5161ecede4c2a17f1184514d231e90b4f1cf7da
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Fri Apr 23 11:08:10 2021 +0200
spec: Update /rtems/task/* documentation
---
spec/constraint/affinity-may-preempt.yml | 11 ++++
.../fatal-bad-thread-dispatch-disable-level.yml | 13 ++++
.../fatal-bad-thread-dispatch-environment.yml | 16 +++++
spec/rtems/task/if/argument.yml | 2 +-
.../task/if/configured-minimum-stack-size.yml | 18 +++++-
spec/rtems/task/if/construct.yml | 2 +-
spec/rtems/task/if/current-priority.yml | 2 +-
spec/rtems/task/if/delete.yml | 3 +-
spec/rtems/task/if/exit.yml | 37 +++++++++--
spec/rtems/task/if/get-affinity.yml | 51 ++++++++++++---
spec/rtems/task/if/get-priority.yml | 64 +++++++++++++++---
spec/rtems/task/if/get-scheduler.yml | 45 +++++++++++--
spec/rtems/task/if/group.yml | 42 ++++++++++++
spec/rtems/task/if/initialization-table.yml | 39 ++++++-----
spec/rtems/task/if/is-suspended.yml | 36 +++++++++--
spec/rtems/task/if/iterate.yml | 31 +++++++--
spec/rtems/task/if/maximum-priority.yml | 6 +-
spec/rtems/task/if/minimum-priority.yml | 4 +-
spec/rtems/task/if/minimum-stack-size.yml | 15 ++++-
spec/rtems/task/if/mode.yml | 2 +
spec/rtems/task/if/no-priority.yml | 6 +-
spec/rtems/task/if/restart.yml | 61 ++++++++++++++++--
spec/rtems/task/if/resume.yml | 40 ++++++++++--
spec/rtems/task/if/self-define.yml | 6 +-
spec/rtems/task/if/self.yml | 20 ++++--
spec/rtems/task/if/set-affinity.yml | 49 ++++++++++++--
spec/rtems/task/if/set-priority.yml | 75 +++++++++++++++++++---
spec/rtems/task/if/set-scheduler.yml | 50 +++++++++++++--
spec/rtems/task/if/start.yml | 62 +++++++++++++++---
spec/rtems/task/if/storage-alignment.yml | 4 +-
spec/rtems/task/if/storage-size.yml | 7 +-
spec/rtems/task/if/suspend.yml | 49 ++++++++++++--
spec/rtems/task/if/task.yml | 8 ++-
spec/rtems/task/if/tcb.yml | 5 +-
spec/rtems/task/if/visitor.yml | 3 +-
spec/rtems/task/if/wake-after.yml | 38 +++++++++--
spec/rtems/task/if/wake-when.yml | 41 ++++++++++--
spec/rtems/task/if/yield-processor.yml | 6 +-
.../if/bad-thread-dispatch-disable-level.yml | 13 ++++
.../interr/if/bad-thread-dispatch-environment.yml | 13 ++++
spec/score/interr/if/internal-error-core.yml | 13 ++++
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 0000000..99bbc13
--- /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 0000000..be1b87c
--- /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 0000000..27140cd
--- /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 e3eaba7..8391c08 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 43878c9..cc05a1c 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 4cacfe4..5b97b6f 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 8911c30..e82a515 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 0e3678a..af5207c 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 3c547e8..de6592d 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 06476ae..b28df7b 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 07af904..cdaf4cf 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 63be27e..f3dbc54 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 da6d069..d1a5e4d 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 e7022cf..ba96c9b 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 b7835cf..fbfd8c0 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 40efa09..e6eed47 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 4da3aa1..fccfc5f 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 f4ca4c1..7dfbd7a 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 6239ea3..280f9d8 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 8b1957a..5cfb0e6 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 70fbda7..6708e9f 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 5a174ba..266616e 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 5bc4077..e02aec2 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 8abe639..6511cb6 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 0542ed4..cb9daad 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 d0457a4..6323dab 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 c749c8e..d667bd8 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 1de8dbb..11c829d 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 75ad2d2..194d4a4 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 8ce3147..fbc0468 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 0792651..964ddee 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 1870f7f..0943f25 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 c563ca0..951d166 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 ce89e25..9883174 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 f0f949f..6a417a6 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 4e2b0f7..b380525 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 da7dfb5..90be9d5 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 b2d1b28..f72f3fc 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 0000000..91269bf
--- /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 0000000..7b4e17b
--- /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 0000000..1530520
--- /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
More information about the vc
mailing list