[rtems-central commit] spec: Document all create directives
Sebastian Huber
sebh at rtems.org
Wed Feb 3 05:28:01 UTC 2021
Module: rtems-central
Branch: master
Commit: 45b6997194fb578d0330bb232040a0d05c9676a4
Changeset: http://git.rtems.org/rtems-central/commit/?id=45b6997194fb578d0330bb232040a0d05c9676a4
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Wed Jan 13 14:05:42 2021 +0100
spec: Document all create directives
---
spec-glossary/glossary/bcb.yml | 12 ++
spec-glossary/glossary/dpcb.yml | 12 ++
spec-glossary/glossary/escb.yml | 12 ++
spec-glossary/glossary/pcb.yml | 12 ++
spec/rtems/barrier/constraint/max.yml | 11 ++
spec/rtems/barrier/if/create.yml | 89 +++++++++++--
spec/rtems/dpmem/constraint/max.yml | 11 ++
spec/rtems/dpmem/if/create.yml | 73 +++++++++--
spec/rtems/message/constraint/max.yml | 12 ++
spec/rtems/message/if/construct.yml | 4 +-
spec/rtems/message/if/create.yml | 138 ++++++++++++++++++--
spec/rtems/part/constraint/max.yml | 11 ++
spec/rtems/part/if/create.yml | 66 ++++++----
spec/rtems/ratemon/constraint/max.yml | 11 ++
spec/rtems/ratemon/if/create.yml | 55 ++++++--
spec/rtems/region/constraint/max.yml | 11 ++
spec/rtems/region/if/create.yml | 105 ++++++++++++++--
spec/rtems/sem/if/create.yml | 226 ++++++++++++++++++---------------
spec/rtems/task/constraint/max.yml | 11 ++
spec/rtems/task/if/construct.yml | 4 +-
spec/rtems/task/if/create.yml | 231 +++++++++++++++++++++++++++++-----
spec/rtems/timer/constraint/max.yml | 11 ++
spec/rtems/timer/if/create.yml | 42 ++++---
spec/rtems/userext/constraint/max.yml | 12 ++
spec/rtems/userext/if/create.yml | 72 +++++++++--
25 files changed, 1009 insertions(+), 245 deletions(-)
diff --git a/spec-glossary/glossary/bcb.yml b/spec-glossary/glossary/bcb.yml
new file mode 100644
index 0000000..379fa66
--- /dev/null
+++ b/spec-glossary/glossary/bcb.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: ../glossary-general
+term: BCB
+text: |
+ This term is an acronym for Barrier Control Block.
+type: glossary
diff --git a/spec-glossary/glossary/dpcb.yml b/spec-glossary/glossary/dpcb.yml
new file mode 100644
index 0000000..9a2efb4
--- /dev/null
+++ b/spec-glossary/glossary/dpcb.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: ../glossary-general
+term: DPCB
+text: |
+ This term is an acronym for Dual-Ported Memory Control Block.
+type: glossary
diff --git a/spec-glossary/glossary/escb.yml b/spec-glossary/glossary/escb.yml
new file mode 100644
index 0000000..b3ff4b7
--- /dev/null
+++ b/spec-glossary/glossary/escb.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: ../glossary-general
+term: ESCB
+text: |
+ This term is an acronym for Extension Set Control Block.
+type: glossary
diff --git a/spec-glossary/glossary/pcb.yml b/spec-glossary/glossary/pcb.yml
new file mode 100644
index 0000000..e4fadfa
--- /dev/null
+++ b/spec-glossary/glossary/pcb.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: ../glossary-general
+term: PCB
+text: |
+ This term is an acronym for Period Control Block.
+type: glossary
diff --git a/spec/rtems/barrier/constraint/max.yml b/spec/rtems/barrier/constraint/max.yml
new file mode 100644
index 0000000..7cd39c3
--- /dev/null
+++ b/spec/rtems/barrier/constraint/max.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 number of barriers available to the application is configured through
+ the ${/acfg/if/max-barriers:/name} application configuration option.
+type: constraint
diff --git a/spec/rtems/barrier/if/create.yml b/spec/rtems/barrier/if/create.yml
index 3aff39e..74deb81 100644
--- a/spec/rtems/barrier/if/create.yml
+++ b/spec/rtems/barrier/if/create.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Creates a barrier.
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:
@@ -14,31 +15,99 @@ definition:
- ${../../type/if/id:/name} *${.:/params[3]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive creates a barrier which resides on the local node. The
+ barrier has the user-defined object name specified in ${.:/params[0]/name}
+ and the initial count specified in ${.:/params[1]/name}. The assigned object
+ identifier is returned in ${.:/params[3]/name}. This identifier is used to
+ access the barrier with other barrier related directives.
+
+ The **attribute set** specified in ${.:/params[1]/name} is built through a
+ *bitwise or* of the attribute constants described below. Not all
+ combinations of attributes are allowed. Some attributes are mutually
+ exclusive. If mutually exclusive attributes are combined, the behaviour is
+ undefined. Attributes not mentioned below are not evaluated by this
+ directive and have no effect. Default attributes can be selected by using
+ the ${../../attr/if/default:/name} constant.
+
+ The **barrier class** is selected by the mutually exclusive
+ ${../../attr/if/barrier-manual-release:/name} and
+ ${../../attr/if/barrier-automatic-release:/name} attributes.
+
+ * The **manual release class** is the default and can be emphasized through
+ use of the ${../../attr/if/barrier-manual-release:/name} attribute. For
+ this class, there is no limit on the number of tasks that will block at the
+ barrier. Only when the ${release:/name} directive is invoked, are the tasks
+ waiting at the barrier unblocked.
+
+ * The **automatic release class** is selected by the
+ ${../../attr/if/barrier-automatic-release:/name} attribute. For this
+ class, tasks calling the ${wait:/name} directive will block until there are
+ ${.:/params[2]/name} minus one tasks waiting at the barrier. When the
+ ${.:/params[2]/name} task invokes the ${wait:/name} directive, the previous
+ ${.:/params[2]/name} - 1 tasks are automatically released and the caller
+ returns.
enabled-by: true
-index-entries: []
+index-entries:
+- create a barrier
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/object-allocator
+- role: constraint
+ uid: ../constraint/max
+- role: constraint
+ uid: /constraint/obj-unlimited-alloc
name: rtems_barrier_create
-notes: null
+notes: |
+ For control and maintenance of the barrier, RTEMS allocates a
+ ${/glossary/bcb:/term} from the local BCB free pool and initializes it.
params:
-- description: '%'
+- description: |
+ is the object name of the barrier.
dir: null
name: name
-- description: '%'
+- description: |
+ is the attribute set of the barrier.
dir: null
name: attribute_set
-- description: '%'
+- description: |
+ is the maximum count of waiters on an automatic release barrier.
dir: null
name: maximum_waiters
-- description: '%'
+- description: |
+ is the pointer to an object identifier variable. The identifier of the
+ created barrier will be stored in this variable, in case of a successful
+ operation.
dir: null
name: id
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The ${.:/params[0]/name} parameter was invalid.
+ value: ${../../status/if/invalid-name:/name}
+ - description: |
+ The ${.:/params[3]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ The ${.:/params[2]/name} parameter was 0 for an automatic release
+ barrier.
+ value: ${../../status/if/invalid-number:/name}
+ - description: |
+ There was no inactive object available to create a barrier. The number
+ of barriers available to the application is configured through the
+ ${/acfg/if/max-barriers:/name} application configuration option.
+ value: ${../../status/if/too-many:/name}
type: interface
diff --git a/spec/rtems/dpmem/constraint/max.yml b/spec/rtems/dpmem/constraint/max.yml
new file mode 100644
index 0000000..b9e6c6f
--- /dev/null
+++ b/spec/rtems/dpmem/constraint/max.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 number of ports available to the application is configured through
+ the ${/acfg/if/max-ports:/name} application configuration option.
+type: constraint
diff --git a/spec/rtems/dpmem/if/create.yml b/spec/rtems/dpmem/if/create.yml
index 2780ade..b4c78bf 100644
--- a/spec/rtems/dpmem/if/create.yml
+++ b/spec/rtems/dpmem/if/create.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Creates a port.
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:
@@ -15,34 +16,82 @@ definition:
- ${../../type/if/id:/name} *${.:/params[4]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive creates a port which resides on the local node. The port has
+ the user-defined object name specified in ${.:/params[0]/name}. The assigned
+ object identifier is returned in ${.:/params[4]/name}. This identifier is
+ used to access the port with other dual-ported memory port related
+ directives.
enabled-by: true
-index-entries: []
+index-entries:
+- create a port
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/object-allocator
+- role: constraint
+ uid: ../constraint/max
+- role: constraint
+ uid: /constraint/obj-unlimited-alloc
name: rtems_port_create
-notes: null
+notes: |
+ The ${.:/params[1]/name} and ${.:/params[2]/name} parameters must be on a
+ boundary defined by the target processor architecture.
+
+ For control and maintenance of the port, RTEMS allocates a
+ ${/glossary/dpcb:/term} from the local DPCB free pool and initializes it.
params:
-- description: '%'
+- description: |
+ is the object name of the port.
dir: null
name: name
-- description: '%'
+- description: |
+ is the internal start address of the memory area.
dir: null
name: internal_start
-- description: '%'
+- description: |
+ is the external start address of the memory area.
dir: null
name: external_start
-- description: '%'
+- description: |
+ is the length in bytes of the memory area.
dir: null
name: length
-- description: '%'
- dir: null
+- description: |
+ is the pointer to an object identifier variable. The identifier of the
+ created port will be stored in this variable, in case of a successful
+ operation.
+ dir: out
name: id
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The ${.:/params[0]/name} parameter was invalid.
+ value: ${../../status/if/invalid-name:/name}
+ - description: |
+ The ${.:/params[3]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ The ${.:/params[1]/name} parameter was not properly aligned.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ The ${.:/params[2]/name} parameter was not properly aligned.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ There was no inactive object available to create a port. The number of
+ port available to the application is configured through the
+ ${/acfg/if/max-ports:/name} application configuration option.
+ value: ${../../status/if/too-many:/name}
type: interface
diff --git a/spec/rtems/message/constraint/max.yml b/spec/rtems/message/constraint/max.yml
new file mode 100644
index 0000000..6c3f233
--- /dev/null
+++ b/spec/rtems/message/constraint/max.yml
@@ -0,0 +1,12 @@
+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 number of message queues available to the application is configured
+ through the ${/acfg/if/max-message-queues:/name} application configuration
+ option.
+type: constraint
diff --git a/spec/rtems/message/if/construct.yml b/spec/rtems/message/if/construct.yml
index 0d936a2..c8e5275 100644
--- a/spec/rtems/message/if/construct.yml
+++ b/spec/rtems/message/if/construct.yml
@@ -42,8 +42,8 @@ params:
name: config
- description: |
is the pointer to an object identifier variable. The identifier of the
- constructed message queue object will be stored in this variable, in case
- of a successful operation.
+ constructed message queue will be stored in this variable, in case of a
+ successful operation.
dir: out
name: id
return:
diff --git a/spec/rtems/message/if/create.yml b/spec/rtems/message/if/create.yml
index c682258..57d804e 100644
--- a/spec/rtems/message/if/create.yml
+++ b/spec/rtems/message/if/create.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Creates a message queue.
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:
@@ -15,34 +16,147 @@ definition:
- ${../../type/if/id:/name} *${.:/params[4]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive creates a message queue which resides on the local node. The
+ message queue has the user-defined object name specified in
+ ${.:/params[0]/name}. Memory is allocated from the RTEMS Workspace for the
+ count of messages specified in ${.:/params[1]/name}, each of
+ ${.:/params[2]/name} bytes in length. The assigned object identifier is
+ returned in ${.:/params[4]/name}. This identifier is used to access the
+ message queue with other message queue related directives.
+
+ The **attribute set** specified in ${.:/params[3]/name} is built through a
+ *bitwise or* of the attribute constants described below. Not all
+ combinations of attributes are allowed. Some attributes are mutually
+ exclusive. If mutually exclusive attributes are combined, the behaviour is
+ undefined. Attributes not mentioned below are not evaluated by this
+ directive and have no effect. Default attributes can be selected by using
+ the ${../../attr/if/default:/name} constant. The attribute set defines
+
+ * the scope of the message queue: ${../../attr/if/local:/name} (default) or
+ ${../../attr/if/global:/name} and
+
+ * the task wait queue discipline used by the message queue:
+ ${../../attr/if/fifo:/name} (default) or ${../../attr/if/priority:/name}.
+
+ The message queue has a local or global **scope** in a multiprocessing network
+ (this attribute does not refer to SMP systems). The scope is selected by the
+ mutually exclusive ${../../attr/if/local:/name} and
+ ${../../attr/if/global:/name} attributes.
+
+ * A **local scope** is the default and can be emphasized through the use of
+ the ${../../attr/if/local:/name} attribute. A local message queue can be
+ only used by the node which created it.
+
+ * A **global scope** is established if the ${../../attr/if/global:/name}
+ attribute is set. Setting the global attribute in a single node system has
+ no effect.
+
+ The **task wait queue discipline** is selected by the mutually exclusive
+ ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
+ The discipline defines the order in which tasks wait for a message to receive
+ on a currently empty message queue.
+
+ * The **FIFO discipline** is the default and can be emphasized
+ through use of the ${../../attr/if/fifo:/name} attribute.
+
+ * The **priority discipline** is selected by the
+ ${../../attr/if/priority:/name} attribute.
enabled-by: true
-index-entries: []
+index-entries:
+- create a message queue
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/object-allocator
+- role: constraint
+ uid: ../constraint/max
+- role: constraint
+ uid: /constraint/obj-unlimited-alloc
+- role: constraint
+ uid: ../../constraint/mp-max-global-objects
name: rtems_message_queue_create
-notes: null
+notes: |
+ For message queues with a global scope, the maximum message size is
+ effectively limited to the longest message which the ${/glossary/mpci:/term}
+ is capable of transmitting.
+
+ For control and maintenance of the message queue, RTEMS allocates a
+ ${/glossary/qcb:/term} from the local QCB free pool and initializes it.
+
+ The QCB for a global message queue is allocated on the local node. Message
+ queues should not be made global unless remote tasks must interact with the
+ message queue. This is to avoid the system overhead incurred by the creation
+ of a global message queue. When a global message queue is created, the
+ message queue's name and identifier must be transmitted to every node in the
+ system for insertion in the local copy of the global object table.
params:
-- description: '%'
+- description: |
+ is the object name of the message queue.
dir: null
name: name
-- description: '%'
+- description: |
+ is the maximum count of pending messages supported by the message queue.
dir: null
name: count
-- description: '%'
+- description: |
+ is the maximum size in bytes of a message supported by the message queue.
dir: null
name: max_message_size
-- description: '%'
+- description: |
+ is the attribute set of the message queue.
dir: null
name: attribute_set
-- description: '%'
- dir: null
+- description: |
+ is the pointer to an object identifier variable. The identifier of the
+ created message queue will be stored in this variable, in case of a
+ successful operation.
+ dir: out
name: id
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The ${.:/params[0]/name} parameter was invalid.
+ value: ${../../status/if/invalid-name:/name}
+ - description: |
+ The ${.:/params[4]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ The ${.:/params[1]/name} parameter was invalid.
+ value: ${../../status/if/invalid-number:/name}
+ - description: |
+ The ${.:/params[2]/name} parameter was invalid.
+ value: ${../../status/if/invalid-size:/name}
+ - description: |
+ There was no inactive object available to create a message queue. The
+ number of message queue available to the application is configured
+ through the ${/acfg/if/max-message-queues:/name} application
+ configuration option.
+ value: ${../../status/if/too-many:/name}
+ - description: |
+ In multiprocessing configurations, there was no inactive global object
+ available to create a global message queue. The number of global objects
+ available to the application is configured through the
+ ${/acfg/if/mp-max-global-objects:/name} application configuration option.
+ value: ${../../status/if/too-many:/name}
+ - description: |
+ The product of ${.:/params[1]/name} and ${.:/params[2]/name} is greater
+ than the maximum storage size.
+ value: ${../../status/if/invalid-number:/name}
+ - description: |
+ There was not enough memory available in the RTEMS Workspace to allocate
+ the message buffers for the message queue.
+ value: ${../../status/if/unsatisfied:/name}
type: interface
diff --git a/spec/rtems/part/constraint/max.yml b/spec/rtems/part/constraint/max.yml
new file mode 100644
index 0000000..ccf39f9
--- /dev/null
+++ b/spec/rtems/part/constraint/max.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 number of partitions available to the application is configured through
+ the ${/acfg/if/max-partitions:/name} application configuration option.
+type: constraint
diff --git a/spec/rtems/part/if/create.yml b/spec/rtems/part/if/create.yml
index ea8419a..88022ab 100644
--- a/spec/rtems/part/if/create.yml
+++ b/spec/rtems/part/if/create.yml
@@ -21,22 +21,29 @@ description: |
This directive creates a partition of fixed size buffers from a physically
contiguous memory space which starts at ${.:/params[1]/name} and is
${.:/params[2]/name} bytes in size. Each allocated buffer is to be of
- ${.:/params[3]/name} in bytes. The assigned object identifier is returned in
- ${.:/params[5]/name}. This identifier is used to access the partition with
- other partition related directives.
+ ${.:/params[3]/name} in bytes. The partition has the user-defined object
+ name specified in ${.:/params[0]/name}. The assigned object identifier is
+ returned in ${.:/params[5]/name}. This identifier is used to access the
+ partition with other partition related directives.
- The **attribute set** specified in ${.:/params[4]/name} is built through
- a *bitwise or* of the attribute constants described below. Attributes not
- mentioned below are not evaluated by this directive and have no effect.
+ The **attribute set** specified in ${.:/params[4]/name} is built through a
+ *bitwise or* of the attribute constants described below. Not all
+ combinations of attributes are allowed. Some attributes are mutually
+ exclusive. If mutually exclusive attributes are combined, the behaviour is
+ undefined. Attributes not mentioned below are not evaluated by this
+ directive and have no effect. Default attributes can be selected by using
+ the ${../../attr/if/default:/name} constant.
- The partition can have **local** or **global** scope in a multiprocessing
- network (this attribute does not refer to SMP systems).
+ The partition has a local or global **scope** in a multiprocessing network
+ (this attribute does not refer to SMP systems). The scope is selected by the
+ mutually exclusive ${../../attr/if/local:/name} and
+ ${../../attr/if/global:/name} attributes.
- * A **local** scope is the default and can be emphasized through the use of
+ * A **local scope** is the default and can be emphasized through the use of
the ${../../attr/if/local:/name} attribute. A local partition can be only
used by the node which created it.
- * A **global** scope is established if the ${../../attr/if/global:/name}
+ * A **global scope** is established if the ${../../attr/if/global:/name}
attribute is set. The memory space used for the partition must reside in
shared memory. Setting the global attribute in a single node system has no
effect.
@@ -49,11 +56,20 @@ 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
+- role: constraint
+ uid: ../constraint/max
+- role: constraint
+ uid: /constraint/obj-unlimited-alloc
+- role: constraint
+ uid: ../../constraint/mp-max-global-objects
name: rtems_partition_create
notes: |
- This directive may cause the calling task to be preempted due to an obtain
- and release of the object allocator mutex.
-
The partition buffer area specified by the ${.:/params[1]/name} must be
properly aligned. It must be possible to directly store target architecture
pointers and also the user data. For example, if the user data contains some
@@ -79,12 +95,8 @@ notes: |
global partition. When a global partition is created, the partition's name
and identifier must be transmitted to every node in the system for insertion
in the local copy of the global object table.
-
- The total number of global objects, including partitions, is limited by the
- value of the ${/acfg/if/mp-max-global-objects:/name} application
- configuration option.
params:
-- description: is the name of the partition.
+- description: is the object name of the partition.
dir: null
name: name
- description: is the starting address of the buffer area used by the partition.
@@ -101,8 +113,8 @@ params:
name: attribute_set
- description: |
is the pointer to an object identifier variable. The identifier of the
- created partition object will be stored in this variable, in case of a
- successful operation.
+ created partition will be stored in this variable, in case of a successful
+ operation.
dir: out
name: id
return:
@@ -112,7 +124,7 @@ return:
The requested operation was successful.
value: ${../../status/if/successful:/name}
- description: |
- The partition name was invalid.
+ The ${.:/params[0]/name} parameter was invalid.
value: ${../../status/if/invalid-name:/name}
- description: |
The ${.:/params[5]/name} parameter was ${/c/if/null:/name}.
@@ -140,8 +152,14 @@ return:
boundary.
value: ${../../status/if/invalid-address:/name}
- description: |
- There was no inactive object available to create a new partition. The
- number of partitions available to the application is configured through
- the ${/acfg/if/max-partitions:/name} configuration option.
+ There was no inactive object available to create a partition. The number
+ of partitions available to the application is configured through the
+ ${/acfg/if/max-partitions:/name} application configuration option.
+ value: ${../../status/if/too-many:/name}
+ - description: |
+ In multiprocessing configurations, there was no inactive global object
+ available to create a global semaphore. The number of global objects
+ available to the application is configured through the
+ ${/acfg/if/mp-max-global-objects:/name} application configuration option.
value: ${../../status/if/too-many:/name}
type: interface
diff --git a/spec/rtems/ratemon/constraint/max.yml b/spec/rtems/ratemon/constraint/max.yml
new file mode 100644
index 0000000..8db642e
--- /dev/null
+++ b/spec/rtems/ratemon/constraint/max.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 number of periods available to the application is configured through the
+ ${/acfg/if/max-periods:/name} application configuration option.
+type: constraint
diff --git a/spec/rtems/ratemon/if/create.yml b/spec/rtems/ratemon/if/create.yml
index f8d842a..abaf911 100644
--- a/spec/rtems/ratemon/if/create.yml
+++ b/spec/rtems/ratemon/if/create.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Creates a period.
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:
@@ -12,25 +13,61 @@ definition:
- ${../../type/if/id:/name} *${.:/params[1]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive creates a period which resides on the local node. The period
+ has the user-defined object name specified in ${.:/params[0]/name} The
+ assigned object identifier is returned in ${.:/params[1]/name}. This
+ identifier is used to access the period with other rate monotonic related
+ directives.
enabled-by: true
-index-entries: []
+index-entries:
+- create a period
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/object-allocator
+- role: constraint
+ uid: ../constraint/max
+- role: constraint
+ uid: /constraint/obj-unlimited-alloc
name: rtems_rate_monotonic_create
-notes: null
+notes: |
+ The calling task is registered as the owner of the created period. Some
+ directives can be only used by this task for the created period.
+
+ For control and maintenance of the period, RTEMS allocates a
+ ${/glossary/pcb:/term} from the local PCB free pool and initializes it.
params:
-- description: '%'
+- description: |
+ is the object name of the period.
dir: null
name: name
-- description: '%'
- dir: null
+- description: |
+ is the pointer to an object identifier variable. The identifier of the
+ created period will be stored in this variable, in case of a successful
+ operation.
+ dir: out
name: id
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The ${.:/params[0]/name} parameter was invalid.
+ value: ${../../status/if/invalid-name:/name}
+ - description: |
+ There was no inactive object available to create a period. The number of
+ periods available to the application is configured through the
+ ${/acfg/if/max-periods:/name} application configuration option.
+ value: ${../../status/if/too-many:/name}
type: interface
diff --git a/spec/rtems/region/constraint/max.yml b/spec/rtems/region/constraint/max.yml
new file mode 100644
index 0000000..61dd552
--- /dev/null
+++ b/spec/rtems/region/constraint/max.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 number of regions available to the application is configured through
+ the ${/acfg/if/max-regions:/name} application configuration option.
+type: constraint
diff --git a/spec/rtems/region/if/create.yml b/spec/rtems/region/if/create.yml
index cbe1dbc..572f3eb 100644
--- a/spec/rtems/region/if/create.yml
+++ b/spec/rtems/region/if/create.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Creates a region.
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:
@@ -16,37 +17,115 @@ definition:
- ${../../type/if/id:/name} *${.:/params[5]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive creates a region which resides on the local node. The region
+ has the user-defined object name specified in ${.:/params[0]/name}. The
+ assigned object identifier is returned in ${.:/params[5]/name}. This
+ identifier is used to access the region with other region related directives.
+
+ The region manages the **contiguous memory area** which starts at
+ ${.:/params[1]/name} and is ${.:/params[2]/name} bytes long. The memory area
+ shall be large enough to contain some internal region administration data.
+
+ The **starting address and length of segments** allocated from the region
+ will be an integral multiple of ${.:/params[3]/name}. The specified page
+ size will be aligned to an implementation-dependent minimum alignment if
+ necessary.
+
+ The **attribute set** specified in ${.:/params[4]/name} is built through a
+ *bitwise or* of the attribute constants described below. Not all
+ combinations of attributes are allowed. Some attributes are mutually
+ exclusive. If mutually exclusive attributes are combined, the behaviour is
+ undefined. Attributes not mentioned below are not evaluated by this
+ directive and have no effect. Default attributes can be selected by using
+ the ${../../attr/if/default:/name} constant.
+
+ The **task wait queue discipline** is selected by the mutually exclusive
+ ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
+ The discipline defines the order in which tasks wait for allocatable segments
+ on a currently empty region.
+
+ * The **FIFO discipline** is the default and can be emphasized
+ through use of the ${../../attr/if/fifo:/name} attribute.
+
+ * The **priority discipline** is selected by the
+ ${../../attr/if/priority:/name} attribute.
enabled-by: true
-index-entries: []
+index-entries:
+- create a region
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/object-allocator
+- role: constraint
+ uid: ../constraint/max
+- role: constraint
+ uid: /constraint/obj-unlimited-alloc
name: rtems_region_create
-notes: null
+notes: |
+ For control and maintenance of the region, RTEMS allocates a
+ ${/glossary/rncb:/term} from the local RNCB free pool and initializes it.
params:
-- description: '%'
+- description: |
+ is the object name of the region.
dir: null
name: name
-- description: '%'
+- description: |
+ is the starting address of the memory area managed by the region.
dir: null
name: starting_address
-- description: '%'
+- description: |
+ is the length in bytes of the memory area managed by the region.
dir: null
name: length
-- description: '%'
+- description: |
+ is the alignment of the starting address and length of each allocated
+ segment of the region.
dir: null
name: page_size
-- description: '%'
+- description: |
+ is the attribute set of the region.
dir: null
name: attribute_set
-- description: '%'
- dir: null
+- description: |
+ is the pointer to an object identifier variable. The identifier of the
+ created region will be stored in this variable, in case of a successful
+ operation.
+ dir: out
name: id
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The ${.:/params[0]/name} parameter was invalid.
+ value: ${../../status/if/invalid-name:/name}
+ - description: |
+ The ${.:/params[5]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ There was no inactive object available to create a region. The number
+ of regions available to the application is configured through the
+ ${/acfg/if/max-regions:/name} application configuration option.
+ value: ${../../status/if/too-many:/name}
+ - description: |
+ The ${.:/params[3]/name} parameter was invalid.
+ value: ${../../status/if/invalid-size:/name}
+ - description: |
+ The memory area specified in ${.:/params[1]/name} and
+ ${.:/params[2]/name} was too small.
+ value: ${../../status/if/invalid-size:/name}
type: interface
diff --git a/spec/rtems/sem/if/create.yml b/spec/rtems/sem/if/create.yml
index 6ccc679..d9ba239 100644
--- a/spec/rtems/sem/if/create.yml
+++ b/spec/rtems/sem/if/create.yml
@@ -1,6 +1,6 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
- Creates a semaphore with the specified properties and returns its identifier.
+ Creates a semaphore.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -17,141 +17,158 @@ definition:
return: ${../../status/if/code:/name}
variants: []
description: |
- This directive creates a semaphore which resides on the local node. The new
- semaphore has the user-defined name specified in ``name`` and the initial
- count specified in ``count``. For control and maintenance of the semaphore,
- RTEMS allocates and initializes a ${/glossary/smcb:/term}. The
- RTEMS-assigned semaphore identifier is returned in ``id``. This semaphore
- identifier is used with other semaphore related directives to access the
- semaphore.
-
- The attribute set specified in ``attribute_set`` defines
-
- * the scope of the semaphore (local or global),
-
- * the discipline of the task wait queue used by the semaphore (FIFO or
- priority),
-
- * the class of the semaphore (counting, binary, or simple binary), and
-
- * the locking protocol of a binary semaphore (priority inheritance, priority
- ceiling or MrsP).
-
- The attribute set is built through a *bitwise or* of the attribute constants
- described below. Not all combinations of attributes are allowed. Some
- attributes are mutually exclusive. If mutually exclusive attributes are
- combined, the behaviour is undefined.
-
- The *scope of a semaphore* is either the local node only (local scope) or all
- nodes in a multiprocessing network (global scope). The scope is selected by
- the mutually exclusive ${../../attr/if/local:/name} and
+ This directive creates a semaphore which resides on the local node. The
+ semaphore has the user-defined object name specified in ${.:/params[0]/name}
+ and the initial count specified in ${.:/params[1]/name}. The assigned object
+ identifier is returned in ${.:/params[4]/name}. This identifier is used to
+ access the semaphore with other semaphore related directives.
+
+ The **attribute set** specified in ${.:/params[2]/name} is built through a
+ *bitwise or* of the attribute constants described below. Not all
+ combinations of attributes are allowed. Some attributes are mutually
+ exclusive. If mutually exclusive attributes are combined, the behaviour is
+ undefined. Attributes not mentioned below are not evaluated by this
+ directive and have no effect. Default attributes can be selected by using
+ the ${../../attr/if/default:/name} constant. The attribute set defines
+
+ * the scope of the semaphore: ${../../attr/if/local:/name} (default) or
+ ${../../attr/if/global:/name},
+
+ * the task wait queue discipline used by the semaphore:
+ ${../../attr/if/fifo:/name} (default) or ${../../attr/if/priority:/name},
+
+ * the class of the semaphore: ${../../attr/if/counting-semaphore:/name}
+ (default), ${../../attr/if/binary-semaphore:/name}, or
+ ${../../attr/if/simple-binary-semaphore:/name}, and
+
+ * the locking protocol of a binary semaphore: no locking protocol (default),
+ ${../../attr/if/inherit-priority:/name},
+ ${../../attr/if/priority-ceiling:/name}, or
+ ${../../attr/if/multiprocessor-resource-sharing:/name}.
+
+ The semaphore has a local or global **scope** in a multiprocessing network
+ (this attribute does not refer to SMP systems). The scope is selected by the
+ mutually exclusive ${../../attr/if/local:/name} and
${../../attr/if/global:/name} attributes.
- * The local scope is the default and can be emphasized through use
- of the ${../../attr/if/local:/name} attribute.
+ * A **local scope** is the default and can be emphasized through the use of
+ the ${../../attr/if/local:/name} attribute. A local semaphore can be only
+ used by the node which created it.
- * The global scope is selected by the ${../../attr/if/global:/name} attribute. In
- a single node system and the local and global scope are identical.
+ * A **global scope** is established if the ${../../attr/if/global:/name}
+ attribute is set. Setting the global attribute in a single node system has
+ no effect.
- The *task wait queue discipline* is selected by the mutually exclusive
+ The **task wait queue discipline** is selected by the mutually exclusive
${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
- * The ${/glossary/fifo:/term} discipline is the default and can be emphasized
+ * The **FIFO discipline** is the default and can be emphasized
through use of the ${../../attr/if/fifo:/name} attribute.
- * The priority discipline is selected by the ${../../attr/if/priority:/name}
- attribute. Some locking protocols require the priority discipline.
+ * The **priority discipline** is selected by the
+ ${../../attr/if/priority:/name} attribute. The locking protocols require
+ the priority discipline.
- The *semaphore class* is selected by the mutually exclusive
+ The **semaphore class** is selected by the mutually exclusive
${../../attr/if/counting-semaphore:/name},
${../../attr/if/binary-semaphore:/name}, and
${../../attr/if/simple-binary-semaphore:/name} attributes.
- * Counting semaphores are the default and can be emphasized through use of
- the ${../../attr/if/counting-semaphore:/name} attribute.
+ * The **counting semaphore class** is the default and can be emphasized
+ through use of the ${../../attr/if/counting-semaphore:/name} attribute.
- * Binary semaphores are mutual exclusion (mutex) synchronization primitives
- which may have an owner. The count of a binary semaphore is restricted to
- 0 and 1. The binary semaphore class is selected by the
- ${../../attr/if/binary-semaphore:/name} attribute.
+ * The **binary semaphore class** is selected by the
+ ${../../attr/if/binary-semaphore:/name} attribute. Binary semaphores are
+ mutual exclusion (mutex) synchronization primitives which may have an
+ owner. The count of a binary semaphore is restricted to 0 and 1 values.
- * Simple binary semaphores have no owner. The count of a simple binary
- semaphore is restricted to 0 and 1. They may be used for task and
- interrupt synchronization. The simple binary semaphore class is selected
- by the ${../../attr/if/simple-binary-semaphore:/name} attribute.
+ * The **simple binary semaphore class** is selected by the
+ ${../../attr/if/simple-binary-semaphore:/name} attribute. Simple binary
+ semaphores have no owner. They may be used for task and interrupt
+ synchronization. The count of a simple binary semaphore is restricted to 0
+ and 1 values.
- Binary semaphores may use a *locking protocol*. If a locking protocol is
+ Binary semaphores may use a **locking protocol**. If a locking protocol is
selected, then the scope shall be local and the priority task wait queue
discipline shall be selected. The locking protocol is selected by the
mutually exclusive ${../../attr/if/inherit-priority:/name},
${../../attr/if/priority-ceiling:/name}, and
${../../attr/if/multiprocessor-resource-sharing:/name} attributes.
- * The default is to use no locking protocol.
-
- * The ${../../attr/if/inherit-priority:/name} attribute selects the priority
- inheritance locking protocol.
-
- * The ${../../attr/if/priority-ceiling:/name} attribute selects the priority
- ceiling locking protocol. For this locking protocol a priority ceiling
- shall be specified in ``priority_ceiling``.
-
- * The ${../../attr/if/multiprocessor-resource-sharing:/name} attribute selects the
- MrsP locking protocol in SMP configurations, otherwise it selects the
- priority ceiling protocol. For this locking protocol a priority ceiling
- shall be specified in ``priority_ceiling``. This priority is used to set
- the priority ceiling in all scheduler instances. This can be changed later
- with the ${set-priority:/name} directive using the returned semaphore
- identifier.
+ * The default is **no locking protocol**. This can be emphasized
+ through use of the ${../../attr/if/no-inherit-priority:/name},
+ ${../../attr/if/no-multiprocessor-resource-sharing:/name}, and
+ ${../../attr/if/no-priority-ceiling:/name} attributes.
+
+ * The **priority inheritance locking protocol** is selected by the
+ ${../../attr/if/inherit-priority:/name} attribute.
+
+ * The **priority ceiling locking protocol** is selected by the
+ ${../../attr/if/priority-ceiling:/name} attribute. For this locking protocol
+ a priority ceiling shall be specified in ${.:/params[3]/name}.
+
+ * The **MrsP locking protocol** is selected by the
+ ${../../attr/if/multiprocessor-resource-sharing:/name} attribute in SMP
+ configurations, otherwise this attribute selects the **priority ceiling
+ locking protocol**. For these locking protocols a priority ceiling shall be
+ specified in ${.:/params[3]/name}. This priority is used to set the
+ priority ceiling for all schedulers. This can be changed later with the
+ ${set-priority:/name} directive using the returned object identifier.
enabled-by: true
-index-entries: []
+index-entries:
+- create a semaphore
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/object-allocator
+- role: constraint
+ uid: ../constraint/max
+- role: constraint
+ uid: /constraint/obj-unlimited-alloc
+- role: constraint
+ uid: ../../constraint/mp-max-global-objects
name: rtems_semaphore_create
notes: |
- This directive may cause the calling task to be preempted due to an obtain
- and release of the object allocator mutex.
-
- Semaphores should not be made global unless remote tasks must interact with
- the new semaphore. This is to avoid the system overhead incurred by the
- creation of a global semaphore. When a global semaphore is created, the
- semaphore's name and identifier must be transmitted to every node in the
- system for insertion in the local copy of the global object table.
-
- The total number of global objects, including semaphores, is limited by the
- ${/acfg/if/mp-max-global-objects:/name} application configuration option.
-
- It is not allowed to create an initially locked MrsP semaphore and the
- ${../../status/if/invalid-number:/name} status code will be returned in SMP
- configurations in this case. This prevents lock order reversal problems
- with the allocator mutex.
+ For control and maintenance of the semaphore, RTEMS allocates a
+ ${/glossary/smcb:/term} from the local SMCB free pool and initializes it.
+
+ The SMCB for a global semaphore is allocated on the local node. Semaphores
+ should not be made global unless remote tasks must interact with the
+ semaphore. This is to avoid the system overhead incurred by the creation of
+ a global semaphore. When a global semaphore is created, the semaphore's name
+ and identifier must be transmitted to every node in the system for insertion
+ in the local copy of the global object table.
params:
-- description: is the object name of the new semaphore.
+- description: |
+ is the object name of the semaphore.
dir: null
name: name
- description: |
- is the initial count of the new semaphore. If the semaphore is a mutex,
- then a count of 0 will make the calling task the owner of the new mutex and
- a count of 1 will create a mutex without an owner.
+ is the initial count of the semaphore. If the semaphore is a binary semaphore,
+ then a count of 0 will make the calling task the owner of the binary semaphore and
+ a count of 1 will create a binary semaphore without an owner.
dir: null
name: count
- description: |
- is the attribute set which defines the properties of the new semaphore.
+ is the attribute set of the semaphore.
dir: null
name: attribute_set
- description: |
- is the priority ceiling if the new semaphore is a binary semaphore with the
- priority ceiling or MrsP semaphore locking protocol as defined by the
- attribute set.
+ is the priority ceiling if the semaphore is a binary semaphore with the
+ priority ceiling or MrsP locking protocol as defined by the attribute set.
dir: null
name: priority_ceiling
- description: |
- is the pointer to an object identifier variable. The object identifier of
- the new semaphore will be stored in this variable, in case of a successful
+ is the pointer to an object identifier variable. The identifier of the
+ created semaphore will be stored in this variable, in case of a successful
operation.
dir: out
name: id
@@ -162,24 +179,29 @@ return:
The requested operation was successful.
value: ${../../status/if/successful:/name}
- description: |
- The ${.:/params[3]/name} parameter was ${/c/if/null:/name}.
- value: ${../../status/if/invalid-address:/name}
- - description: |
- The semaphore name was invalid.
+ The ${.:/params[0]/name} parameter was invalid.
value: ${../../status/if/invalid-name:/name}
- description: |
- The priority ceiling was invalid.
- value: ${../../status/if/invalid-priority:/name}
+ The ${.:/params[4]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ The ${.:/params[1]/name} parameter was invalid.
+ value: ${../../status/if/invalid-number:/name}
- description: |
- The attribute set was invalid.
+ The ${.:/params[2]/name} parameter was invalid.
value: ${../../status/if/not-defined:/name}
- description: |
- There was no inactive semaphore object available to create a new
- semaphore. The semaphore object maximum is defined by the
+ There was no inactive object available to create a semaphore. The number
+ of semaphores available to the application is configured through the
${/acfg/if/max-semaphores:/name} application configuration option.
value: ${../../status/if/too-many:/name}
- description: |
In multiprocessing configurations, there was no inactive global object
- available to create a new global semaphore.
+ available to create a global semaphore. The number of global objects
+ available to the application is configured through the
+ ${/acfg/if/mp-max-global-objects:/name} application configuration option.
value: ${../../status/if/too-many:/name}
+ - description: |
+ The ${.:/params[3]/name} parameter was invalid.
+ value: ${../../status/if/invalid-priority:/name}
type: interface
diff --git a/spec/rtems/task/constraint/max.yml b/spec/rtems/task/constraint/max.yml
new file mode 100644
index 0000000..f072f03
--- /dev/null
+++ b/spec/rtems/task/constraint/max.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 number of tasks available to the application is configured through
+ the ${/acfg/if/max-tasks:/name} application configuration option.
+type: constraint
diff --git a/spec/rtems/task/if/construct.yml b/spec/rtems/task/if/construct.yml
index 661d27a..fa2ae2a 100644
--- a/spec/rtems/task/if/construct.yml
+++ b/spec/rtems/task/if/construct.yml
@@ -54,8 +54,8 @@ params:
name: config
- description: |
is the pointer to an object identifier variable. The identifier of the
- constructed task object will be stored in this variable, in case of a
- successful operation.
+ constructed task will be stored in this variable, in case of a successful
+ operation.
dir: out
name: id
return:
diff --git a/spec/rtems/task/if/create.yml b/spec/rtems/task/if/create.yml
index 1ff4dda..a05c765 100644
--- a/spec/rtems/task/if/create.yml
+++ b/spec/rtems/task/if/create.yml
@@ -1,8 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
- Creates a task object.
+ Creates a task.
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, 2017 On-Line Applications Research Corporation (OAR)
definition:
default:
@@ -18,46 +18,212 @@ definition:
return: ${../../status/if/code:/name}
variants: []
description: |
- This directive creates a task which resides on the local node. It allocates
- and initializes a TCB, a stack, and an optional floating point context area.
- The mode parameter contains values which sets the task’s initial execution
- mode. The RTEMS_FLOATING_POINT attribute should be specified if the created
- task is to use a numeric coprocessor. For performance reasons, it is
- recommended that tasks not using the numeric coprocessor should specify the
- RTEMS_NO_FLOATING_POINT attribute. If the RTEMS_GLOBAL attribute is
- specified, the task can be accessed from remote nodes. The task id, returned
- in id, is used in other task related directives to access the task. When
- created, a task is placed in the dormant state and can only be made ready to
- execute using the directive rtems_task_start().
+ This directive creates a task which resides on the local node. The task has
+ the user-defined object name specified in ${.:/params[0]/name}. The assigned
+ object identifier is returned in ${.:/params[5]/name}. This identifier is
+ used to access the task with other task related directives.
+
+ The **initial priority** of the task is specified in ${.:/params[1]/name}.
+ The scheduler of the created task is the scheduler of the calling task at
+ some point during the task creation. The initial task priority specified in
+ ${.:/params[1]/name} shall be valid for this scheduler.
+
+ The **stack size** of the task is specified in ${.:/params[2]/name}. If the
+ requested stack size is less than the configured minimum stack size, then
+ RTEMS will use the configured minimum as the stack size for this task. The
+ configured minimum stack size is defined by the
+ ${/acfg/if/min-task-stack-size:/name} application configuration option. In
+ addition to being able to specify the task stack size as a integer, there are
+ two constants which may be specified:
+
+ * The ${minimum-stack-size:/name} constant can be specified to use the
+ **recommended minimum stack size** for the target 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 ${minimum-stack-size:/name} bytes in size. If the user configured
+ minimum stack size is larger than the recommended minimum, then it will be
+ used.
+
+ * The ${configured-minimum-stack-size:/name} constant can be specified to use
+ the minimum stack size that was configured by the application. If not
+ explicitly configured by the application, the default configured minimum
+ stack size is the target processor dependent value
+ ${minimum-stack-size:/name}. 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.
+
+ The **initial mode set** specified in ${.:/params[3]/name} is built through a
+ *bitwise or* of the mode constants described below. Not all combinations of
+ modes are allowed. Some modes are mutually exclusive. If mutually exclusive
+ modes are combined, the behaviour is undefined. Default task modes can be
+ selected by using the ${../../mode/if/default:/name} constant. The task mode
+ set defines
+
+ * the preemption mode of the task: ${../../mode/if/preempt:/name} (default)
+ or ${../../mode/if/no-preempt:/name},
+
+ * the timeslicing mode of the task: ${../../mode/if/timeslice:/name} or
+ ${../../mode/if/no-timeslice:/name} (default),
+
+ * the ${/glossary/asr:/term} processing mode of the task:
+ ${../../mode/if/asr:/name} (default) or ${../../mode/if/no-asr:/name},
+
+ * the interrupt level mode of the task:
+ ${../../mode/if/interrupt-level:/name}.
+
+ The **initial preemption mode** of the task is enabled or disabled.
+
+ * An **enabled preemption** is the default and can be emphasized through the
+ use of the ${../../mode/if/preempt:/name} mode constant.
+
+ * A **disabled preemption** is set by the ${../../mode/if/no-preempt:/name}
+ mode constant.
+
+ The **initial timeslicing mode** of the task is enabled or disabled.
+
+ * A **disabled timeslicing** is the default and can be emphasized through the
+ use of the ${../../mode/if/no-timeslice:/name} mode constant.
+
+ * An **enabled timeslicing** is set by the ${../../mode/if/timeslice:/name}
+ mode constant.
+
+ The **initial ASR processing mode** of the task is enabled or disabled.
+
+ * An **enabled ASR processing** is the default and can be emphasized through
+ the use of the ${../../mode/if/asr:/name} mode constant.
+
+ * A **disabled ASR processing** is set by the ${../../mode/if/no-asr:/name}
+ mode constant.
+
+ The **initial interrupt level mode** of the task is defined by
+ ${../../mode/if/interrupt-level:/name}.
+
+ * Task execution with **interrupts enabled** the default and can be
+ emphasized through the use of the ${../../mode/if/interrupt-level:/name}
+ mode macro with a value of zero (0) for the parameter. An interrupt level
+ of zero is associated with enabled interrupts on all target processors.
+
+ * Task execution at a **non-zero interrupt level** can be specified by the
+ ${../../mode/if/interrupt-level:/name} mode macro with a non-zero value for
+ the parameter. The interrupt level portion of the task mode supports a
+ maximum of 256 interrupt levels. These levels are mapped onto the
+ interrupt levels actually supported by the target processor in a processor
+ dependent fashion.
+
+ The **attribute set** specified in ${.:/params[4]/name} is built through a
+ *bitwise or* of the attribute constants described below. Not all
+ combinations of attributes are allowed. Some attributes are mutually
+ exclusive. If mutually exclusive attributes are combined, the behaviour is
+ undefined. Attributes not mentioned below are not evaluated by this
+ directive and have no effect. Default attributes can be selected by using
+ the ${../../attr/if/default:/name} constant. The attribute set defines
+
+ * the scope of the task: ${../../attr/if/local:/name} (default) or
+ ${../../attr/if/global:/name} and
+
+ * the floating-point unit use of the task:
+ ${../../attr/if/floating-point:/name} or
+ ${../../attr/if/no-floating-point:/name} (default).
+
+ The task has a local or global **scope** in a multiprocessing network
+ (this attribute does not refer to SMP systems). The scope is selected by the
+ mutually exclusive ${../../attr/if/local:/name} and
+ ${../../attr/if/global:/name} attributes.
+
+ * A **local scope** is the default and can be emphasized through the use of
+ the ${../../attr/if/local:/name} attribute. A local task can be only used
+ by the node which created it.
+
+ * A **global scope** is established if the ${../../attr/if/global:/name}
+ attribute is set. Setting the global attribute in a single node system has
+ no effect.the
+
+ The **use of the floating-point unit** is selected by the mutually exclusive
+ ${../../attr/if/floating-point:/name} and
+ ${../../attr/if/no-floating-point:/name} attributes. On some target
+ processors, the use of the floating-point unit can be enabled or disabled for
+ each task. Other target processors may have no hardware floating-point unit
+ or enable the use of the floating-point unit for all tasks. Consult the
+ *RTEMS CPU Architecture Supplement* for the details.
+
+ * A **disabled floating-point unit** is the default and can be emphasized
+ through use of the ${../../attr/if/no-floating-point:/name} attribute. For
+ performance reasons, it is recommended that tasks not using the
+ floating-point unit should specify this attribute.
+
+ * An **enabled floating-point unit** is selected by the
+ ${../../attr/if/floating-point:/name} attribute.
enabled-by: true
-index-entries: []
+index-entries:
+- create a task
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/object-allocator
+- role: constraint
+ uid: ../constraint/max
+- role: constraint
+ uid: /constraint/obj-unlimited-alloc
+- role: constraint
+ uid: ../../constraint/mp-max-global-objects
name: rtems_task_create
-notes: null
+notes: |
+ The task processor affinity is initialized to the set of online processors.
+
+ When created, a task is placed in the dormant state and can only be made
+ ready to execute using the directive ${start:/name}.
+
+ Application developers should consider the stack usage of the device drivers
+ when calculating the stack size required for tasks which utilize the driver.
+ The task stack size shall account for an target processor dependent interrupt
+ stack frame which may be placed on the stack of the interrupted task while
+ servicing an interrupt. The stack checker may be used to monitor the stack
+ usage, see ${/acfg/if/stack-checker-enabled:/name}.
+
+ For control and maintenance of the task, RTEMS allocates a
+ ${/glossary/tcb:/term} from the local TCB free pool and initializes it.
+
+ The TCB for a global task is allocated on the local node. Task should not be
+ made global unless remote tasks must interact with the task. This is to
+ avoid the system overhead incurred by the creation of a global task. When a
+ global task is created, the task's name and identifier must be transmitted to
+ every node in the system for insertion in the local copy of the global object
+ table.
params:
-- description: is the user-defined task name.
+- description: |
+ is the object name of the task.
dir: null
name: name
-- description: is the initial task priority.
+- description: |
+ is the initial task priority.
dir: null
name: initial_priority
-- description: is the task stack size in bytes.
+- description: |
+ is the task stack size in bytes.
dir: null
name: stack_size
-- description: is the initial task mode.
+- description: |
+ is the initial mode set of the task.
dir: null
name: initial_modes
-- description: is the task attribute set.
+- description: |
+ is the attribute set of the task.
dir: null
name: attribute_set
- description: |
- is the pointer to an object identifier variable. The object identifier of
- the new task will be stored in this variable, in case of a successful
+ is the pointer to an object identifier variable. The identifier of the
+ created task will be stored in this variable, in case of a successful
operation.
dir: out
name: id
@@ -68,23 +234,24 @@ return:
The requested operation was successful.
value: ${../../status/if/successful:/name}
- description: |
+ The ${.:/params[0]/name} parameter was invalid.
+ value: ${../../status/if/invalid-name:/name}
+ - description: |
The ${.:/params[5]/name} parameter was ${/c/if/null:/name}.
value: ${../../status/if/invalid-address:/name}
- description: |
- The task name was invalid.
- value: ${../../status/if/invalid-name:/name}
- - description: |
- The initial task priority was invalid.
+ The ${.:/params[1]/name} was invalid.
value: ${../../status/if/invalid-priority:/name}
- description: |
- The multiprocessing support was not configured.
- value: ${../../status/if/mp-not-configured:/name}
- - description: |
- There was no inactive task object available to create a new task.
+ There was no inactive object available to create a task. The number of
+ tasks available to the application is configured through the
+ ${/acfg/if/max-tasks:/name} application configuration option.
value: ${../../status/if/too-many:/name}
- description: |
In multiprocessing configurations, there was no inactive global object
- available to create a new global task.
+ available to create a global task. The number of global objects
+ available to the application is configured through the
+ ${/acfg/if/mp-max-global-objects:/name} application configuration option.
value: ${../../status/if/too-many:/name}
- description: |
There was not enough memory to allocate the task storage area. The task
@@ -92,7 +259,7 @@ return:
floating point context.
value: ${../../status/if/unsatisfied:/name}
- description: |
- One of the task create extensions failed to create the new task.
+ One of the task create extensions failed to create the task.
value: ${../../status/if/unsatisfied:/name}
- description: |
In SMP configurations, the non-preemption mode was not supported.
diff --git a/spec/rtems/timer/constraint/max.yml b/spec/rtems/timer/constraint/max.yml
new file mode 100644
index 0000000..f0505bf
--- /dev/null
+++ b/spec/rtems/timer/constraint/max.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 number of timers available to the application is configured through
+ the ${/acfg/if/max-timers:/name} application configuration option.
+type: constraint
diff --git a/spec/rtems/timer/if/create.yml b/spec/rtems/timer/if/create.yml
index 71ae5dd..ba8be42 100644
--- a/spec/rtems/timer/if/create.yml
+++ b/spec/rtems/timer/if/create.yml
@@ -2,7 +2,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
Creates a timer.
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:
@@ -14,9 +14,10 @@ definition:
return: ${../../status/if/code:/name}
variants: []
description: |
- This directive creates a timer. The assigned object identifier is returned
- in ${.:/params[1]/name}. This identifier is used to access the timer with
- other timer related directives.
+ This directive creates a timer which resides on the local node. The timer
+ has the user-defined object name specified in ${.:/params[0]/name}. The
+ assigned object identifier is returned in ${.:/params[1]/name}. This
+ identifier is used to access the timer with other timer related directives.
enabled-by: true
index-entries:
- create a timer
@@ -26,25 +27,32 @@ 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
+- role: constraint
+ uid: ../constraint/max
+- role: constraint
+ uid: /constraint/obj-unlimited-alloc
name: rtems_timer_create
notes: |
- This directive may cause the calling task to be preempted due to an obtain
- and release of the object allocator mutex.
+ The processor used to maintain the timer is the processor of the calling task
+ at some point during the timer creation.
For control and maintenance of the timer, RTEMS allocates a
${/glossary/tmcb:/term} from the local TMCB free pool and initializes it.
-
- In SMP configurations, the processor of the currently executing thread
- determines the processor used for the created timer. During the life-time of
- the timer this processor is used to manage the timer internally.
params:
-- description: is the name of the timer.
+- description: |
+ is the object name of the timer.
dir: null
name: name
- description: |
is the pointer to an object identifier variable. The identifier of the
- created timer object will be stored in this variable, in case of a
- successful operation.
+ created timer will be stored in this variable, in case of a successful
+ operation.
dir: out
name: id
return:
@@ -54,14 +62,14 @@ return:
The requested operation was successful.
value: ${../../status/if/successful:/name}
- description: |
- The timer name was invalid.
+ The ${.:/params[0]/name} parameter was invalid.
value: ${../../status/if/invalid-name:/name}
- description: |
The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
value: ${../../status/if/invalid-address:/name}
- description: |
- There was no inactive object available to create a new timer. The number
- of timers available to the application is configured through the
- ${/acfg/if/max-timers:/name} configuration option.
+ There was no inactive object available to create a timer. The number of
+ timers available to the application is configured through the
+ ${/acfg/if/max-timers:/name} application configuration option.
value: ${../../status/if/too-many:/name}
type: interface
diff --git a/spec/rtems/userext/constraint/max.yml b/spec/rtems/userext/constraint/max.yml
new file mode 100644
index 0000000..6e9294b
--- /dev/null
+++ b/spec/rtems/userext/constraint/max.yml
@@ -0,0 +1,12 @@
+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 number of extension sets available to the application is configured
+ through the ${/acfg/if/max-user-extensions:/name} application configuration
+ option.
+type: constraint
diff --git a/spec/rtems/userext/if/create.yml b/spec/rtems/userext/if/create.yml
index 5b61f94..245fca3 100644
--- a/spec/rtems/userext/if/create.yml
+++ b/spec/rtems/userext/if/create.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Creates an extension set.
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:
@@ -13,28 +14,79 @@ definition:
- ${../../type/if/id:/name} *${.:/params[2]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive creates an extension set which resides on the local node. The
+ extension set has the user-defined object name specified in
+ ${.:/params[0]/name}. The assigned object identifier is returned in
+ ${.:/params[2]/name}. This identifier is used to access the extension set
+ with other extension set related directives.
+
+ The extension set is initialized using the extension table specified in
+ ${.:/params[1]/name}.
enabled-by: true
-index-entries: []
+index-entries:
+- create an extension set
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/object-allocator
+- role: constraint
+ uid: ../constraint/max
name: rtems_extension_create
-notes: null
+notes: |
+ The user-provided extension set table is not used after the return of the
+ directive.
+
+ Newly created extension sets are immediately installed and are invoked upon
+ the next system event supporting an extension.
+
+ An alternative to dynamically created extension sets are initial extensions,
+ see ${/acfg/if/initial-extensions:/name}. Initial extensions are recommended
+ for extension sets which provide a fatal error extension.
+
+ For control and maintenance of the extension set, RTEMS allocates a
+ ${/glossary/escb:/term} from the local ESCB free pool and initializes it.
params:
-- description: '%'
+- description: |
+ is the object name of the extension set.
dir: null
name: name
-- description: '%'
+- description: |
dir: null
name: extension_table
-- description: '%'
- dir: null
+- description: |
+ is the pointer to an object identifier variable. The identifier of the
+ created extension set will be stored in this variable, in case of a
+ successful operation.
+ dir: out
name: id
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The ${.:/params[0]/name} parameter was invalid.
+ value: ${../../status/if/invalid-name:/name}
+ - description: |
+ The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ There was no inactive object available to create an extension set. The
+ number of extension sets available to the application is configured
+ through the ${/acfg/if/max-user-extensions:/name} application
+ configuration option.
+ value: ${../../status/if/too-many:/name}
type: interface
More information about the vc
mailing list