diff options
| author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-01-13 14:05:42 +0100 |
|---|---|---|
| committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2021-02-03 06:26:37 +0100 |
| commit | 45b6997194fb578d0330bb232040a0d05c9676a4 (patch) | |
| tree | 13899a603201768a10a2cb5e15faac0d4ae6bc08 | |
| parent | spec: Use constraints for partition manager (diff) | |
| download | rtems-central-45b6997194fb578d0330bb232040a0d05c9676a4.tar.bz2 | |
spec: Document all create directives
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 00000000..379fa66c --- /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 00000000..9a2efb42 --- /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 00000000..b3ff4b78 --- /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 00000000..e4fadfad --- /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 00000000..7cd39c3b --- /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 3aff39e7..74deb817 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 00000000..b9e6c6fb --- /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 2780ade6..b4c78bf8 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 00000000..6c3f2336 --- /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 0d936a26..c8e52757 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 c6822587..57d804e9 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 00000000..ccf39f92 --- /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 ea8419ab..88022ab0 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 00000000..8db642e5 --- /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 f8d842a6..abaf911a 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 00000000..61dd5527 --- /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 cbe1dbc7..572f3eb0 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 6ccc6797..d9ba2392 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 00000000..f072f03a --- /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 661d27a1..fa2ae2a7 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 1ff4dda3..a05c765a 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 00000000..f0505bfb --- /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 71ae5ddf..ba8be42a 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 00000000..6e9294be --- /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 5b61f944..245fca32 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 |