[rtems-central commit] spec: Update /rtems/scheduler/* documentation
Sebastian Huber
sebh at rtems.org
Wed Apr 28 07:04:36 UTC 2021
Module: rtems-central
Branch: master
Commit: 4565c33e0ad06d7bf48459c4067c26b8f339113f
Changeset: http://git.rtems.org/rtems-central/commit/?id=4565c33e0ad06d7bf48459c4067c26b8f339113f
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Fri Apr 23 18:36:32 2021 +0200
spec: Update /rtems/scheduler/* documentation
---
spec/rtems/scheduler/if/add-processor.yml | 34 +++++++++++++---------
spec/rtems/scheduler/if/get-maximum-priority.yml | 17 +++++++----
spec/rtems/scheduler/if/get-processor-macro.yml | 21 +++++++++++++
.../scheduler/if/get-processor-maximum-macro.yml | 21 +++++++++++++
spec/rtems/scheduler/if/get-processor-maximum.yml | 33 +++++++++++++--------
spec/rtems/scheduler/if/get-processor-set.yml | 10 +++++--
spec/rtems/scheduler/if/get-processor.yml | 28 +++++++++++-------
spec/rtems/scheduler/if/group.yml | 26 +++++++++++++++++
spec/rtems/scheduler/if/ident-by-processor-set.yml | 18 +++++++-----
spec/rtems/scheduler/if/ident-by-processor.yml | 18 +++++++-----
spec/rtems/scheduler/if/ident.yml | 8 ++---
.../rtems/scheduler/if/map-priority-from-posix.yml | 10 +++++--
spec/rtems/scheduler/if/map-priority-to-posix.yml | 10 +++++--
spec/rtems/scheduler/if/remove-processor.yml | 34 +++++++++++++---------
14 files changed, 209 insertions(+), 79 deletions(-)
diff --git a/spec/rtems/scheduler/if/add-processor.yml b/spec/rtems/scheduler/if/add-processor.yml
index 5adc7b1..6a004fe 100644
--- a/spec/rtems/scheduler/if/add-processor.yml
+++ b/spec/rtems/scheduler/if/add-processor.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
- Adds the processor to the set of processors owned by the scheduler instance.
+ Adds the processor to the set of processors owned by the scheduler.
copyrights:
-- Copyright (C) 2016, 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2016, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -12,7 +12,9 @@ definition:
- ${/c/if/uint32_t:/name} ${.:/params[1]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive adds the processor specified by the ${.:/params[1]/name} to
+ the scheduler specified by ${.:/params[0]/name}.
enabled-by: true
index-entries: []
interface-type: function
@@ -21,15 +23,21 @@ links:
uid: ../../task/if/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_scheduler_add_processor
-notes: |
- This directive shall be called from task context. It obtains and releases
- the objects allocator lock.
+notes: null
params:
-- description: is the scheduler instance identifier.
+- description: |
+ is the scheduler identifier.
dir: null
name: scheduler_id
-- description: is the index of the processor to add.
+- description: |
+ is the index of the processor to add.
dir: null
name: cpu_index
return:
@@ -39,10 +47,6 @@ return:
The requested operation was successful.
value: ${../../status/if/successful:/name}
- description: |
- The processor was configured to be used by the application, however, it
- was not online.
- value: ${../../status/if/incorrect-state:/name}
- - description: |
There was no scheduler associated with the identifier specified by
${.:/params[0]/name}.
value: ${../../status/if/invalid-id:/name}
@@ -50,6 +54,10 @@ return:
The processor was not configured to be used by the application.
value: ${../../status/if/not-configured:/name}
- description: |
- The processor was already assigned to a scheduler instance.
+ The processor was configured to be used by the application, however, it
+ was not online.
+ value: ${../../status/if/incorrect-state:/name}
+ - description: |
+ The processor was already assigned to a scheduler.
value: ${../../status/if/resource-in-use:/name}
type: interface
diff --git a/spec/rtems/scheduler/if/get-maximum-priority.yml b/spec/rtems/scheduler/if/get-maximum-priority.yml
index e8bfb5a..f1517c4 100644
--- a/spec/rtems/scheduler/if/get-maximum-priority.yml
+++ b/spec/rtems/scheduler/if/get-maximum-priority.yml
@@ -1,6 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
- Gets the maximum task priority of the scheduler instance.
+ Gets the maximum task priority of the scheduler.
copyrights:
- Copyright (C) 2018, 2020 embedded brains GmbH (http://www.embedded-brains.de)
definition:
@@ -21,15 +21,20 @@ links:
uid: ../../task/if/header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_scheduler_get_maximum_priority
notes: null
params:
-- description: is the scheduler instance identifier.
+- description: |
+ is the scheduler identifier.
dir: null
name: scheduler_id
- description: |
is the pointer to a task priority variable. The maximum priority of the
- scheduler instance will be stored in this variable, if the operation is
+ scheduler will be stored in this variable, if the operation is
successful.
dir: out
name: priority
@@ -40,10 +45,10 @@ return:
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 scheduler associated with the identifier specified by
${.:/params[0]/name}.
value: ${../../status/if/invalid-id:/name}
+ - description: |
+ The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
type: interface
diff --git a/spec/rtems/scheduler/if/get-processor-macro.yml b/spec/rtems/scheduler/if/get-processor-macro.yml
new file mode 100644
index 0000000..623f8c1
--- /dev/null
+++ b/spec/rtems/scheduler/if/get-processor-macro.yml
@@ -0,0 +1,21 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: null
+copyrights:
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+ default: ${/score/smp/if/get-current-processor:/name}()
+ variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: macro
+links:
+- role: interface-placement
+ uid: ../../task/if/header
+name: rtems_scheduler_get_processor
+notes: null
+params: []
+return:
+ return: null
+ return-values: []
+type: interface
diff --git a/spec/rtems/scheduler/if/get-processor-maximum-macro.yml b/spec/rtems/scheduler/if/get-processor-maximum-macro.yml
new file mode 100644
index 0000000..c3f1b8a
--- /dev/null
+++ b/spec/rtems/scheduler/if/get-processor-maximum-macro.yml
@@ -0,0 +1,21 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: null
+copyrights:
+- Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+ default: ${/score/smp/if/get-processor-maximum:/name}()
+ variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: macro
+links:
+- role: interface-placement
+ uid: ../../task/if/header
+name: rtems_scheduler_get_processor_maximum
+notes: null
+params: []
+return:
+ return: null
+ return-values: []
+type: interface
diff --git a/spec/rtems/scheduler/if/get-processor-maximum.yml b/spec/rtems/scheduler/if/get-processor-maximum.yml
index e76d3a2..bc1a8fc 100644
--- a/spec/rtems/scheduler/if/get-processor-maximum.yml
+++ b/spec/rtems/scheduler/if/get-processor-maximum.yml
@@ -2,33 +2,42 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
Returns the processor maximum supported by the system.
copyrights:
-- Copyright (C) 2013, 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
- default: ${/score/smp/if/get-processor-maximum:/name}()
+ default:
+ attributes: null
+ body: null
+ params: []
+ return: ${/c/if/uint32_t:/name}
variants: []
description: |
- In uniprocessor configurations, this macro evaluates to a compile time
- constant of one.
+ Where the system was built with SMP support disabled, this directive
+ evaluates to a compile time constant of one.
- In SMP configurations, this macro returns the minimum of the processors
- (physically or virtually) available by the platform and the configured
- processor maximum. Not all processors in the range from processor index zero
- to the last processor index (which is the processor maximum minus one) may be
- configured to be used by a scheduler or may be online (online processors have
- a scheduler assigned).
+ Where the system was built with SMP support enabled, this directive returns
+ the minimum of the processors (physically or virtually) available at the
+ ${/glossary/target:/term} and the configured processor maximum
+ (see ${/acfg/if/max-processors:/name}). Not all processors in the range from
+ processor index zero to the last processor index (which is the processor
+ maximum minus one) may be configured to be used by a scheduler or may be
+ online (online processors have a scheduler assigned).
enabled-by: true
index-entries: []
-interface-type: macro
+interface-type: function
links:
- role: interface-placement
uid: ../../task/if/header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_scheduler_get_processor_maximum
notes: null
params: []
return:
return: |
- The processor maximum supported by the system is returned.
+ Returns the processor maximum supported by the system.
return-values: []
type: interface
diff --git a/spec/rtems/scheduler/if/get-processor-set.yml b/spec/rtems/scheduler/if/get-processor-set.yml
index 8d8acb2..ea7b732 100644
--- a/spec/rtems/scheduler/if/get-processor-set.yml
+++ b/spec/rtems/scheduler/if/get-processor-set.yml
@@ -23,15 +23,19 @@ links:
uid: ../../task/if/header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_scheduler_get_processor_set
notes: null
params:
-- description: is the scheduler identifier.
+- description: |
+ is the scheduler identifier.
dir: null
name: scheduler_id
- description: |
- is the size of the referenced processor set variable in bytes. This value
- shall be positive.
+ is the size of the referenced processor set variable in bytes.
dir: null
name: cpusetsize
- description: |
diff --git a/spec/rtems/scheduler/if/get-processor.yml b/spec/rtems/scheduler/if/get-processor.yml
index a0578d2..830cc17 100644
--- a/spec/rtems/scheduler/if/get-processor.yml
+++ b/spec/rtems/scheduler/if/get-processor.yml
@@ -2,26 +2,34 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
Returns the index of the current processor.
copyrights:
-- Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
- default: ${/score/smp/if/get-current-processor:/name}()
+ default:
+ attributes: null
+ body: null
+ params: []
+ return: ${/c/if/uint32_t:/name}
variants: []
description: |
- In uniprocessor configurations, this macro evaluates to a compile time
- constant of zero.
+ Where the system was built with SMP support disabled, this directive
+ evaluates to a compile time constant of zero.
- In SMP configurations, an architecture-specific method is used to obtain the
- index of the current processor in the system. The set of processor indices
- is the range of integers starting with zero up to
- ${get-processor-maximum:/name} minus one.
+ Where the system was built with SMP support enabled, this directive returns
+ the index of the current processor. The set of processor indices is the
+ range of integers starting with zero up to ${get-processor-maximum:/name}
+ minus one.
enabled-by: true
index-entries: []
-interface-type: macro
+interface-type: function
links:
- role: interface-placement
uid: ../../task/if/header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_scheduler_get_processor
notes: |
Outside of sections with disabled thread dispatching the current processor
@@ -31,6 +39,6 @@ notes: |
params: []
return:
return: |
- The index of the current processor is returned.
+ Returns the index of the current processor.
return-values: []
type: interface
diff --git a/spec/rtems/scheduler/if/group.yml b/spec/rtems/scheduler/if/group.yml
index 35f5798..6474c61 100644
--- a/spec/rtems/scheduler/if/group.yml
+++ b/spec/rtems/scheduler/if/group.yml
@@ -25,6 +25,32 @@ links:
uid: ../../task/if/header
- role: interface-ingroup
uid: ../../if/group
+- role: placement-order
+ uid: ident
+- role: placement-order
+ uid: ident-by-processor
+- role: placement-order
+ uid: ident-by-processor-set
+- role: placement-order
+ uid: get-maximum-priority
+- role: placement-order
+ uid: map-priority-to-posix
+- role: placement-order
+ uid: map-priority-from-posix
+- role: placement-order
+ uid: get-processor
+- role: placement-order
+ uid: get-processor-macro
+- role: placement-order
+ uid: get-processor-maximum
+- role: placement-order
+ uid: get-processor-maximum-macro
+- role: placement-order
+ uid: get-processor-set
+- role: placement-order
+ uid: add-processor
+- role: placement-order
+ uid: remove-processor
name: Scheduler Manager
text: |
The Classic API shall provide an interface to the Scheduler Manager.
diff --git a/spec/rtems/scheduler/if/ident-by-processor-set.yml b/spec/rtems/scheduler/if/ident-by-processor-set.yml
index 2405320..8646e08 100644
--- a/spec/rtems/scheduler/if/ident-by-processor-set.yml
+++ b/spec/rtems/scheduler/if/ident-by-processor-set.yml
@@ -1,6 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
- Identifies a scheduler by a processor set.
+ Identifies a scheduler by the processor set.
copyrights:
- Copyright (C) 2017, 2020 embedded brains GmbH (http://www.embedded-brains.de)
definition:
@@ -24,6 +24,10 @@ links:
uid: ../../task/if/header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_scheduler_ident_by_processor_set
notes: null
params:
@@ -50,16 +54,16 @@ return:
The requested operation was successful.
value: ${../../status/if/successful:/name}
- description: |
- The processor set was valid, however, the highest numbered online
- processor in the processor set was not owned by a scheduler.
- value: ${../../status/if/incorrect-state:/name}
- - description: |
The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
value: ${../../status/if/invalid-address:/name}
- description: |
+ The processor set size was invalid.
+ value: ${../../status/if/invalid-size:/name}
+ - description: |
The processor set contained no online processor.
value: ${../../status/if/invalid-name:/name}
- description: |
- The processor set size was invalid.
- value: ${../../status/if/invalid-size:/name}
+ The processor set was valid, however, the highest numbered online
+ processor in the processor set was not owned by a scheduler.
+ value: ${../../status/if/incorrect-state:/name}
type: interface
diff --git a/spec/rtems/scheduler/if/ident-by-processor.yml b/spec/rtems/scheduler/if/ident-by-processor.yml
index 881155e..cad616a 100644
--- a/spec/rtems/scheduler/if/ident-by-processor.yml
+++ b/spec/rtems/scheduler/if/ident-by-processor.yml
@@ -1,6 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
- Identifies a scheduler instance by a processor index.
+ Identifies a scheduler by the processor index.
copyrights:
- Copyright (C) 2017, 2020 embedded brains GmbH (http://www.embedded-brains.de)
definition:
@@ -21,16 +21,20 @@ links:
uid: ../../task/if/header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_scheduler_ident_by_processor
notes: null
params:
- description: |
- is the processor index to identify the scheduler instance.
+ is the processor index to identify the scheduler.
dir: null
name: cpu_index
- description: |
is the pointer to an object identifier variable. When the directive call
- is successful, the identifier of the scheduler instance will be stored in
+ is successful, the identifier of the scheduler will be stored in
this variable.
dir: out
name: id
@@ -41,13 +45,13 @@ return:
The requested operation was successful.
value: ${../../status/if/successful:/name}
- description: |
- The processor index was valid, however, the corresponding processor was
- not owned by a scheduler instance.
- value: ${../../status/if/incorrect-state:/name}
- - description: |
The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
value: ${../../status/if/invalid-address:/name}
- description: |
The processor index was invalid.
value: ${../../status/if/invalid-name:/name}
+ - description: |
+ The processor index was valid, however, the corresponding processor was
+ not owned by a scheduler.
+ value: ${../../status/if/incorrect-state:/name}
type: interface
diff --git a/spec/rtems/scheduler/if/ident.yml b/spec/rtems/scheduler/if/ident.yml
index 328040b..c7dfb1e 100644
--- a/spec/rtems/scheduler/if/ident.yml
+++ b/spec/rtems/scheduler/if/ident.yml
@@ -40,7 +40,7 @@ params:
name: name
- description: |
is the pointer to an object identifier variable. When the directive call
- is successful, the identifier of the scheduler instance will be stored in
+ is successful, the identifier of the scheduler will be stored in
this variable.
dir: out
name: id
@@ -51,9 +51,9 @@ return:
The requested operation was successful.
value: ${../../status/if/successful:/name}
- description: |
+ There was no scheduler associated with the name.
+ value: ${../../status/if/invalid-name:/name}
+ - description: |
The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
value: ${../../status/if/invalid-address:/name}
- - description: |
- The scheduler name was invalid.
- value: ${../../status/if/invalid-name:/name}
type: interface
diff --git a/spec/rtems/scheduler/if/map-priority-from-posix.yml b/spec/rtems/scheduler/if/map-priority-from-posix.yml
index 660d5b3..e6d06f3 100644
--- a/spec/rtems/scheduler/if/map-priority-from-posix.yml
+++ b/spec/rtems/scheduler/if/map-priority-from-posix.yml
@@ -22,13 +22,19 @@ links:
uid: ../../task/if/header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_scheduler_map_priority_from_posix
notes: null
params:
-- description: is the scheduler identifier.
+- description: |
+ is the scheduler identifier.
dir: null
name: scheduler_id
-- description: is the POSIX thread priority to map.
+- description: |
+ is the POSIX thread priority to map.
dir: null
name: posix_priority
- description: |
diff --git a/spec/rtems/scheduler/if/map-priority-to-posix.yml b/spec/rtems/scheduler/if/map-priority-to-posix.yml
index 9bd070e..3a98736 100644
--- a/spec/rtems/scheduler/if/map-priority-to-posix.yml
+++ b/spec/rtems/scheduler/if/map-priority-to-posix.yml
@@ -22,13 +22,19 @@ links:
uid: ../../task/if/header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_scheduler_map_priority_to_posix
notes: null
params:
-- description: is the scheduler instance identifier.
+- description: |
+ is the scheduler identifier.
dir: null
name: scheduler_id
-- description: is the Classic API task priority to map.
+- description: |
+ is the Classic API task priority to map.
dir: null
name: priority
- description: |
diff --git a/spec/rtems/scheduler/if/remove-processor.yml b/spec/rtems/scheduler/if/remove-processor.yml
index 654c4ec..dada93e 100644
--- a/spec/rtems/scheduler/if/remove-processor.yml
+++ b/spec/rtems/scheduler/if/remove-processor.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
- Removes a processor from set of processors owned by the scheduler instance.
+ Removes the processor from the set of processors owned by the scheduler.
copyrights:
-- Copyright (C) 2016, 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2016, 2021 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
attributes: null
@@ -12,7 +12,9 @@ definition:
- ${/c/if/uint32_t:/name} ${.:/params[1]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive removes the processor specified by the ${.:/params[1]/name}
+ from the scheduler specified by ${.:/params[0]/name}.
enabled-by: true
index-entries: []
interface-type: function
@@ -21,16 +23,23 @@ links:
uid: ../../task/if/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_scheduler_remove_processor
notes: |
- This directive shall be called from task context. It obtains and releases
- the objects allocator lock. Removing a processor from a scheduler instance
- is a complex operation that involves all tasks of the system.
+ Removing a processor from a scheduler is a complex operation that involves
+ all tasks of the system.
params:
-- description: is the scheduler instance identifier.
+- description: |
+ is the scheduler identifier.
dir: null
name: scheduler_id
-- description: is the index of the processor to remove.
+- description: |
+ is the index of the processor to remove.
dir: null
name: cpu_index
return:
@@ -44,12 +53,11 @@ return:
${.:/params[0]/name}.
value: ${../../status/if/invalid-id:/name}
- description: |
- The processor was not owned by the specified scheduler instance.
+ The processor was not owned by the scheduler.
value: ${../../status/if/invalid-number:/name}
- description: |
- The set of processors owned by the specified scheduler instance would
- have been empty after the processor removal and there was at least one
- non-idle task that used this scheduler instance as its home scheduler
- instance.
+ The set of processors owned by the scheduler would have been empty after
+ the processor removal and there was at least one non-idle task that used
+ this scheduler as its ${/glossary/scheduler-home:/term}.
value: ${../../status/if/resource-in-use:/name}
type: interface
More information about the vc
mailing list