Changeset 45b6997 in rtems-central


Ignore:
Timestamp:
Jan 13, 2021, 1:05:42 PM (3 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
f665caf
Parents:
f3be101
git-author:
Sebastian Huber <sebastian.huber@…> (01/13/21 13:05:42)
git-committer:
Sebastian Huber <sebastian.huber@…> (02/03/21 05:26:37)
Message:

spec: Document all create directives

Files:
13 added
12 edited

Legend:

Unmodified
Added
Removed
  • spec/rtems/barrier/if/create.yml

    rf3be101 r45b6997  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  Creates a barrier.
    34copyrights:
    4 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     5- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
    56- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
    67definition:
     
    1516    return: ${../../status/if/code:/name}
    1617  variants: []
    17 description: null
     18description: |
     19  This directive creates a barrier which resides on the local node.  The
     20  barrier has the user-defined object name specified in ${.:/params[0]/name}
     21  and the initial count specified in ${.:/params[1]/name}.  The assigned object
     22  identifier is returned in ${.:/params[3]/name}.  This identifier is used to
     23  access the barrier with other barrier related directives.
     24
     25  The **attribute set** specified in ${.:/params[1]/name} is built through a
     26  *bitwise or* of the attribute constants described below.  Not all
     27  combinations of attributes are allowed.  Some attributes are mutually
     28  exclusive.  If mutually exclusive attributes are combined, the behaviour is
     29  undefined.  Attributes not mentioned below are not evaluated by this
     30  directive and have no effect.  Default attributes can be selected by using
     31  the ${../../attr/if/default:/name} constant.
     32
     33  The **barrier class** is selected by the mutually exclusive
     34  ${../../attr/if/barrier-manual-release:/name} and
     35  ${../../attr/if/barrier-automatic-release:/name} attributes.
     36
     37  * The **manual release class** is the default and can be emphasized through
     38    use of the ${../../attr/if/barrier-manual-release:/name} attribute.  For
     39    this class, there is no limit on the number of tasks that will block at the
     40    barrier. Only when the ${release:/name} directive is invoked, are the tasks
     41    waiting at the barrier unblocked.
     42
     43  * The **automatic release class** is selected by the
     44    ${../../attr/if/barrier-automatic-release:/name} attribute.  For this
     45    class, tasks calling the ${wait:/name} directive will block until there are
     46    ${.:/params[2]/name} minus one tasks waiting at the barrier.  When the
     47    ${.:/params[2]/name} task invokes the ${wait:/name} directive, the previous
     48    ${.:/params[2]/name} - 1 tasks are automatically released and the caller
     49    returns.
    1850enabled-by: true
    19 index-entries: []
     51index-entries:
     52- create a barrier
    2053interface-type: function
    2154links:
     
    2457- role: interface-ingroup
    2558  uid: group
     59- role: constraint
     60  uid: /constraint/directive-ctx-devinit
     61- role: constraint
     62  uid: /constraint/directive-ctx-task
     63- role: constraint
     64  uid: /constraint/object-allocator
     65- role: constraint
     66  uid: ../constraint/max
     67- role: constraint
     68  uid: /constraint/obj-unlimited-alloc
    2669name: rtems_barrier_create
    27 notes: null
     70notes: |
     71  For control and maintenance of the barrier, RTEMS allocates a
     72  ${/glossary/bcb:/term} from the local BCB free pool and initializes it.
    2873params:
    29 - description: '%'
     74- description: |
     75    is the object name of the barrier.
    3076  dir: null
    3177  name: name
    32 - description: '%'
     78- description: |
     79    is the attribute set of the barrier.
    3380  dir: null
    3481  name: attribute_set
    35 - description: '%'
     82- description: |
     83    is the maximum count of waiters on an automatic release barrier.
    3684  dir: null
    3785  name: maximum_waiters
    38 - description: '%'
     86- description: |
     87    is the pointer to an object identifier variable.  The identifier of the
     88    created barrier will be stored in this variable, in case of a successful
     89    operation.
    3990  dir: null
    4091  name: id
    4192return:
    4293  return: null
    43   return-values: []
     94  return-values:
     95  - description: |
     96      The requested operation was successful.
     97    value: ${../../status/if/successful:/name}
     98  - description: |
     99      The ${.:/params[0]/name} parameter was invalid.
     100    value: ${../../status/if/invalid-name:/name}
     101  - description: |
     102      The ${.:/params[3]/name} parameter was ${/c/if/null:/name}.
     103    value: ${../../status/if/invalid-address:/name}
     104  - description: |
     105      The ${.:/params[2]/name} parameter was 0 for an automatic release
     106      barrier.
     107    value: ${../../status/if/invalid-number:/name}
     108  - description: |
     109      There was no inactive object available to create a barrier.  The number
     110      of barriers available to the application is configured through the
     111      ${/acfg/if/max-barriers:/name} application configuration option.
     112    value: ${../../status/if/too-many:/name}
    44113type: interface
  • spec/rtems/dpmem/if/create.yml

    rf3be101 r45b6997  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  Creates a port.
    34copyrights:
    4 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     5- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
    56- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
    67definition:
     
    1617    return: ${../../status/if/code:/name}
    1718  variants: []
    18 description: null
     19description: |
     20  This directive creates a port which resides on the local node.  The port has
     21  the user-defined object name specified in ${.:/params[0]/name}.  The assigned
     22  object identifier is returned in ${.:/params[4]/name}.  This identifier is
     23  used to access the port with other dual-ported memory port related
     24  directives.
    1925enabled-by: true
    20 index-entries: []
     26index-entries:
     27- create a port
    2128interface-type: function
    2229links:
     
    2532- role: interface-ingroup
    2633  uid: group
     34- role: constraint
     35  uid: /constraint/directive-ctx-devinit
     36- role: constraint
     37  uid: /constraint/directive-ctx-task
     38- role: constraint
     39  uid: /constraint/object-allocator
     40- role: constraint
     41  uid: ../constraint/max
     42- role: constraint
     43  uid: /constraint/obj-unlimited-alloc
    2744name: rtems_port_create
    28 notes: null
     45notes: |
     46  The ${.:/params[1]/name} and ${.:/params[2]/name} parameters must be on a
     47  boundary defined by the target processor architecture.
     48
     49  For control and maintenance of the port, RTEMS allocates a
     50  ${/glossary/dpcb:/term} from the local DPCB free pool and initializes it.
    2951params:
    30 - description: '%'
     52- description: |
     53    is the object name of the port.
    3154  dir: null
    3255  name: name
    33 - description: '%'
     56- description: |
     57    is the internal start address of the memory area.
    3458  dir: null
    3559  name: internal_start
    36 - description: '%'
     60- description: |
     61    is the external start address of the memory area.
    3762  dir: null
    3863  name: external_start
    39 - description: '%'
     64- description: |
     65    is the length in bytes of the memory area.
    4066  dir: null
    4167  name: length
    42 - description: '%'
    43   dir: null
     68- description: |
     69    is the pointer to an object identifier variable.  The identifier of the
     70    created port will be stored in this variable, in case of a successful
     71    operation.
     72  dir: out
    4473  name: id
    4574return:
    4675  return: null
    47   return-values: []
     76  return-values:
     77  - description: |
     78      The requested operation was successful.
     79    value: ${../../status/if/successful:/name}
     80  - description: |
     81      The ${.:/params[0]/name} parameter was invalid.
     82    value: ${../../status/if/invalid-name:/name}
     83  - description: |
     84      The ${.:/params[3]/name} parameter was ${/c/if/null:/name}.
     85    value: ${../../status/if/invalid-address:/name}
     86  - description: |
     87      The ${.:/params[1]/name} parameter was not properly aligned.
     88    value: ${../../status/if/invalid-address:/name}
     89  - description: |
     90      The ${.:/params[2]/name} parameter was not properly aligned.
     91    value: ${../../status/if/invalid-address:/name}
     92  - description: |
     93      There was no inactive object available to create a port.  The number of
     94      port available to the application is configured through the
     95      ${/acfg/if/max-ports:/name} application configuration option.
     96    value: ${../../status/if/too-many:/name}
    4897type: interface
  • spec/rtems/message/if/construct.yml

    rf3be101 r45b6997  
    4343- description: |
    4444    is the pointer to an object identifier variable.  The identifier of the
    45     constructed message queue object will be stored in this variable, in case
    46     of a successful operation.
     45    constructed message queue will be stored in this variable, in case of a
     46    successful operation.
    4747  dir: out
    4848  name: id
  • spec/rtems/message/if/create.yml

    rf3be101 r45b6997  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  Creates a message queue.
    34copyrights:
    4 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     5- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
    56- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
    67definition:
     
    1617    return: ${../../status/if/code:/name}
    1718  variants: []
    18 description: null
     19description: |
     20  This directive creates a message queue which resides on the local node.  The
     21  message queue has the user-defined object name specified in
     22  ${.:/params[0]/name}.  Memory is allocated from the RTEMS Workspace for the
     23  count of messages specified in ${.:/params[1]/name}, each of
     24  ${.:/params[2]/name} bytes in length.  The assigned object identifier is
     25  returned in ${.:/params[4]/name}.  This identifier is used to access the
     26  message queue with other message queue related directives.
     27
     28  The **attribute set** specified in ${.:/params[3]/name} is built through a
     29  *bitwise or* of the attribute constants described below.  Not all
     30  combinations of attributes are allowed.  Some attributes are mutually
     31  exclusive.  If mutually exclusive attributes are combined, the behaviour is
     32  undefined.  Attributes not mentioned below are not evaluated by this
     33  directive and have no effect.  Default attributes can be selected by using
     34  the ${../../attr/if/default:/name} constant.  The attribute set defines
     35
     36  * the scope of the message queue: ${../../attr/if/local:/name} (default) or
     37    ${../../attr/if/global:/name} and
     38
     39  * the task wait queue discipline used by the message queue:
     40    ${../../attr/if/fifo:/name} (default) or ${../../attr/if/priority:/name}.
     41
     42  The message queue has a local or global **scope** in a multiprocessing network
     43  (this attribute does not refer to SMP systems).  The scope is selected by the
     44  mutually exclusive ${../../attr/if/local:/name} and
     45  ${../../attr/if/global:/name} attributes.
     46
     47  * A **local scope** is the default and can be emphasized through the use of
     48    the ${../../attr/if/local:/name} attribute.  A local message queue can be
     49    only used by the node which created it.
     50
     51  * A **global scope** is established if the ${../../attr/if/global:/name}
     52    attribute is set.  Setting the global attribute in a single node system has
     53    no effect.
     54
     55  The **task wait queue discipline** is selected by the mutually exclusive
     56  ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
     57  The discipline defines the order in which tasks wait for a message to receive
     58  on a currently empty message queue.
     59
     60  * The **FIFO discipline** is the default and can be emphasized
     61    through use of the ${../../attr/if/fifo:/name} attribute.
     62
     63  * The **priority discipline** is selected by the
     64    ${../../attr/if/priority:/name} attribute.
    1965enabled-by: true
    20 index-entries: []
     66index-entries:
     67- create a message queue
    2168interface-type: function
    2269links:
     
    2572- role: interface-ingroup
    2673  uid: group
     74- role: constraint
     75  uid: /constraint/directive-ctx-devinit
     76- role: constraint
     77  uid: /constraint/directive-ctx-task
     78- role: constraint
     79  uid: /constraint/object-allocator
     80- role: constraint
     81  uid: ../constraint/max
     82- role: constraint
     83  uid: /constraint/obj-unlimited-alloc
     84- role: constraint
     85  uid: ../../constraint/mp-max-global-objects
    2786name: rtems_message_queue_create
    28 notes: null
     87notes: |
     88  For message queues with a global scope, the maximum message size is
     89  effectively limited to the longest message which the ${/glossary/mpci:/term}
     90  is capable of transmitting.
     91
     92  For control and maintenance of the message queue, RTEMS allocates a
     93  ${/glossary/qcb:/term} from the local QCB free pool and initializes it.
     94
     95  The QCB for a global message queue is allocated on the local node.  Message
     96  queues should not be made global unless remote tasks must interact with the
     97  message queue.  This is to avoid the system overhead incurred by the creation
     98  of a global message queue.  When a global message queue is created, the
     99  message queue's name and identifier must be transmitted to every node in the
     100  system for insertion in the local copy of the global object table.
    29101params:
    30 - description: '%'
     102- description: |
     103    is the object name of the message queue.
    31104  dir: null
    32105  name: name
    33 - description: '%'
     106- description: |
     107    is the maximum count of pending messages supported by the message queue.
    34108  dir: null
    35109  name: count
    36 - description: '%'
     110- description: |
     111    is the maximum size in bytes of a message supported by the message queue.
    37112  dir: null
    38113  name: max_message_size
    39 - description: '%'
     114- description: |
     115    is the attribute set of the message queue.
    40116  dir: null
    41117  name: attribute_set
    42 - description: '%'
    43   dir: null
     118- description: |
     119    is the pointer to an object identifier variable.  The identifier of the
     120    created message queue will be stored in this variable, in case of a
     121    successful operation.
     122  dir: out
    44123  name: id
    45124return:
    46125  return: null
    47   return-values: []
     126  return-values:
     127  - description: |
     128      The requested operation was successful.
     129    value: ${../../status/if/successful:/name}
     130  - description: |
     131      The ${.:/params[0]/name} parameter was invalid.
     132    value: ${../../status/if/invalid-name:/name}
     133  - description: |
     134      The ${.:/params[4]/name} parameter was ${/c/if/null:/name}.
     135    value: ${../../status/if/invalid-address:/name}
     136  - description: |
     137      The ${.:/params[1]/name} parameter was invalid.
     138    value: ${../../status/if/invalid-number:/name}
     139  - description: |
     140      The ${.:/params[2]/name} parameter was invalid.
     141    value: ${../../status/if/invalid-size:/name}
     142  - description: |
     143      There was no inactive object available to create a message queue.  The
     144      number of message queue available to the application is configured
     145      through the ${/acfg/if/max-message-queues:/name} application
     146      configuration option.
     147    value: ${../../status/if/too-many:/name}
     148  - description: |
     149      In multiprocessing configurations, there was no inactive global object
     150      available to create a global message queue.  The number of global objects
     151      available to the application is configured through the
     152      ${/acfg/if/mp-max-global-objects:/name} application configuration option.
     153    value: ${../../status/if/too-many:/name}
     154  - description: |
     155      The product of ${.:/params[1]/name} and ${.:/params[2]/name} is greater
     156      than the maximum storage size.
     157    value: ${../../status/if/invalid-number:/name}
     158  - description: |
     159      There was not enough memory available in the RTEMS Workspace to allocate
     160      the message buffers for the message queue.
     161    value: ${../../status/if/unsatisfied:/name}
    48162type: interface
  • spec/rtems/part/if/create.yml

    rf3be101 r45b6997  
    2222  contiguous memory space which starts at ${.:/params[1]/name} and is
    2323  ${.:/params[2]/name} bytes in size.  Each allocated buffer is to be of
    24   ${.:/params[3]/name} in bytes.  The assigned object identifier is returned in
    25   ${.:/params[5]/name}.  This identifier is used to access the partition with
    26   other partition related directives.
     24  ${.:/params[3]/name} in bytes.  The partition has the user-defined object
     25  name specified in ${.:/params[0]/name}.  The assigned object identifier is
     26  returned in ${.:/params[5]/name}.  This identifier is used to access the
     27  partition with other partition related directives.
    2728
    28   The **attribute set** specified in ${.:/params[4]/name} is built through
    29   a *bitwise or* of the attribute constants described below.  Attributes not
    30   mentioned below are not evaluated by this directive and have no effect.
     29  The **attribute set** specified in ${.:/params[4]/name} is built through a
     30  *bitwise or* of the attribute constants described below.  Not all
     31  combinations of attributes are allowed.  Some attributes are mutually
     32  exclusive.  If mutually exclusive attributes are combined, the behaviour is
     33  undefined.  Attributes not mentioned below are not evaluated by this
     34  directive and have no effect.  Default attributes can be selected by using
     35  the ${../../attr/if/default:/name} constant.
    3136
    32   The partition can have **local** or **global** scope in a multiprocessing
    33   network (this attribute does not refer to SMP systems).
     37  The partition has a local or global **scope** in a multiprocessing network
     38  (this attribute does not refer to SMP systems).  The scope is selected by the
     39  mutually exclusive ${../../attr/if/local:/name} and
     40  ${../../attr/if/global:/name} attributes.
    3441
    35   * A **local** scope is the default and can be emphasized through the use of
     42  * A **local scope** is the default and can be emphasized through the use of
    3643    the ${../../attr/if/local:/name} attribute.  A local partition can be only
    3744    used by the node which created it.
    3845
    39   * A **global** scope is established if the ${../../attr/if/global:/name}
     46  * A **global scope** is established if the ${../../attr/if/global:/name}
    4047    attribute is set.  The memory space used for the partition must reside in
    4148    shared memory.  Setting the global attribute in a single node system has no
     
    5057- role: interface-ingroup
    5158  uid: group
     59- role: constraint
     60  uid: /constraint/directive-ctx-devinit
     61- role: constraint
     62  uid: /constraint/directive-ctx-task
     63- role: constraint
     64  uid: /constraint/object-allocator
     65- role: constraint
     66  uid: ../constraint/max
     67- role: constraint
     68  uid: /constraint/obj-unlimited-alloc
     69- role: constraint
     70  uid: ../../constraint/mp-max-global-objects
    5271name: rtems_partition_create
    5372notes: |
    54   This directive may cause the calling task to be preempted due to an obtain
    55   and release of the object allocator mutex.
    56 
    5773  The partition buffer area specified by the ${.:/params[1]/name} must be
    5874  properly aligned.  It must be possible to directly store target architecture
     
    8096  and identifier must be transmitted to every node in the system for insertion
    8197  in the local copy of the global object table.
    82 
    83   The total number of global objects, including partitions, is limited by the
    84   value of the ${/acfg/if/mp-max-global-objects:/name} application
    85   configuration option.
    8698params:
    87 - description: is the name of the partition.
     99- description: is the object name of the partition.
    88100  dir: null
    89101  name: name
     
    102114- description: |
    103115    is the pointer to an object identifier variable.  The identifier of the
    104     created partition object will be stored in this variable, in case of a
    105     successful operation.
     116    created partition will be stored in this variable, in case of a successful
     117    operation.
    106118  dir: out
    107119  name: id
     
    113125    value: ${../../status/if/successful:/name}
    114126  - description: |
    115       The partition name was invalid.
     127      The ${.:/params[0]/name} parameter was invalid.
    116128    value: ${../../status/if/invalid-name:/name}
    117129  - description: |
     
    141153    value: ${../../status/if/invalid-address:/name}
    142154  - description: |
    143       There was no inactive object available to create a new partition.  The
    144       number of partitions available to the application is configured through
    145       the ${/acfg/if/max-partitions:/name} configuration option.
     155      There was no inactive object available to create a partition.  The number
     156      of partitions available to the application is configured through the
     157      ${/acfg/if/max-partitions:/name} application configuration option.
     158    value: ${../../status/if/too-many:/name}
     159  - description: |
     160      In multiprocessing configurations, there was no inactive global object
     161      available to create a global semaphore.  The number of global objects
     162      available to the application is configured through the
     163      ${/acfg/if/mp-max-global-objects:/name} application configuration option.
    146164    value: ${../../status/if/too-many:/name}
    147165type: interface
  • spec/rtems/ratemon/if/create.yml

    rf3be101 r45b6997  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  Creates a period.
    34copyrights:
    4 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     5- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
    56- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
    67definition:
     
    1314    return: ${../../status/if/code:/name}
    1415  variants: []
    15 description: null
     16description: |
     17  This directive creates a period which resides on the local node.  The period
     18  has the user-defined object name specified in ${.:/params[0]/name} The
     19  assigned object identifier is returned in ${.:/params[1]/name}.  This
     20  identifier is used to access the period with other rate monotonic related
     21  directives.
    1622enabled-by: true
    17 index-entries: []
     23index-entries:
     24- create a period
    1825interface-type: function
    1926links:
     
    2229- role: interface-ingroup
    2330  uid: group
     31- role: constraint
     32  uid: /constraint/directive-ctx-devinit
     33- role: constraint
     34  uid: /constraint/directive-ctx-task
     35- role: constraint
     36  uid: /constraint/object-allocator
     37- role: constraint
     38  uid: ../constraint/max
     39- role: constraint
     40  uid: /constraint/obj-unlimited-alloc
    2441name: rtems_rate_monotonic_create
    25 notes: null
     42notes: |
     43  The calling task is registered as the owner of the created period.  Some
     44  directives can be only used by this task for the created period.
     45
     46  For control and maintenance of the period, RTEMS allocates a
     47  ${/glossary/pcb:/term} from the local PCB free pool and initializes it.
    2648params:
    27 - description: '%'
     49- description: |
     50    is the object name of the period.
    2851  dir: null
    2952  name: name
    30 - description: '%'
    31   dir: null
     53- description: |
     54    is the pointer to an object identifier variable.  The identifier of the
     55    created period will be stored in this variable, in case of a successful
     56    operation.
     57  dir: out
    3258  name: id
    3359return:
    3460  return: null
    35   return-values: []
     61  return-values:
     62  - description: |
     63      The requested operation was successful.
     64    value: ${../../status/if/successful:/name}
     65  - description: |
     66      The ${.:/params[0]/name} parameter was invalid.
     67    value: ${../../status/if/invalid-name:/name}
     68  - description: |
     69      There was no inactive object available to create a period.  The number of
     70      periods available to the application is configured through the
     71      ${/acfg/if/max-periods:/name} application configuration option.
     72    value: ${../../status/if/too-many:/name}
    3673type: interface
  • spec/rtems/region/if/create.yml

    rf3be101 r45b6997  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  Creates a region.
    34copyrights:
    4 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     5- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
    56- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
    67definition:
     
    1718    return: ${../../status/if/code:/name}
    1819  variants: []
    19 description: null
     20description: |
     21  This directive creates a region which resides on the local node.  The region
     22  has the user-defined object name specified in ${.:/params[0]/name}.  The
     23  assigned object identifier is returned in ${.:/params[5]/name}.  This
     24  identifier is used to access the region with other region related directives.
     25
     26  The region manages the **contiguous memory area** which starts at
     27  ${.:/params[1]/name} and is ${.:/params[2]/name} bytes long.  The memory area
     28  shall be large enough to contain some internal region administration data.
     29
     30  The **starting address and length of segments** allocated from the region
     31  will be an integral multiple of ${.:/params[3]/name}.  The specified page
     32  size will be aligned to an implementation-dependent minimum alignment if
     33  necessary.
     34
     35  The **attribute set** specified in ${.:/params[4]/name} is built through a
     36  *bitwise or* of the attribute constants described below.  Not all
     37  combinations of attributes are allowed.  Some attributes are mutually
     38  exclusive.  If mutually exclusive attributes are combined, the behaviour is
     39  undefined.  Attributes not mentioned below are not evaluated by this
     40  directive and have no effect.  Default attributes can be selected by using
     41  the ${../../attr/if/default:/name} constant.
     42
     43  The **task wait queue discipline** is selected by the mutually exclusive
     44  ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
     45  The discipline defines the order in which tasks wait for allocatable segments
     46  on a currently empty region.
     47
     48  * The **FIFO discipline** is the default and can be emphasized
     49    through use of the ${../../attr/if/fifo:/name} attribute.
     50
     51  * The **priority discipline** is selected by the
     52    ${../../attr/if/priority:/name} attribute.
    2053enabled-by: true
    21 index-entries: []
     54index-entries:
     55- create a region
    2256interface-type: function
    2357links:
     
    2660- role: interface-ingroup
    2761  uid: group
     62- role: constraint
     63  uid: /constraint/directive-ctx-devinit
     64- role: constraint
     65  uid: /constraint/directive-ctx-task
     66- role: constraint
     67  uid: /constraint/object-allocator
     68- role: constraint
     69  uid: ../constraint/max
     70- role: constraint
     71  uid: /constraint/obj-unlimited-alloc
    2872name: rtems_region_create
    29 notes: null
     73notes: |
     74  For control and maintenance of the region, RTEMS allocates a
     75  ${/glossary/rncb:/term} from the local RNCB free pool and initializes it.
    3076params:
    31 - description: '%'
     77- description: |
     78    is the object name of the region.
    3279  dir: null
    3380  name: name
    34 - description: '%'
     81- description: |
     82    is the starting address of the memory area managed by the region.
    3583  dir: null
    3684  name: starting_address
    37 - description: '%'
     85- description: |
     86    is the length in bytes of the memory area managed by the region.
    3887  dir: null
    3988  name: length
    40 - description: '%'
     89- description: |
     90    is the alignment of the starting address and length of each allocated
     91    segment of the region.
    4192  dir: null
    4293  name: page_size
    43 - description: '%'
     94- description: |
     95    is the attribute set of the region.
    4496  dir: null
    4597  name: attribute_set
    46 - description: '%'
    47   dir: null
     98- description: |
     99    is the pointer to an object identifier variable.  The identifier of the
     100    created region will be stored in this variable, in case of a successful
     101    operation.
     102  dir: out
    48103  name: id
    49104return:
    50105  return: null
    51   return-values: []
     106  return-values:
     107  - description: |
     108      The requested operation was successful.
     109    value: ${../../status/if/successful:/name}
     110  - description: |
     111      The ${.:/params[0]/name} parameter was invalid.
     112    value: ${../../status/if/invalid-name:/name}
     113  - description: |
     114      The ${.:/params[5]/name} parameter was ${/c/if/null:/name}.
     115    value: ${../../status/if/invalid-address:/name}
     116  - description: |
     117      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
     118    value: ${../../status/if/invalid-address:/name}
     119  - description: |
     120      There was no inactive object available to create a region.  The number
     121      of regions available to the application is configured through the
     122      ${/acfg/if/max-regions:/name} application configuration option.
     123    value: ${../../status/if/too-many:/name}
     124  - description: |
     125      The ${.:/params[3]/name} parameter was invalid.
     126    value: ${../../status/if/invalid-size:/name}
     127  - description: |
     128      The memory area specified in ${.:/params[1]/name} and
     129      ${.:/params[2]/name} was too small.
     130    value: ${../../status/if/invalid-size:/name}
    52131type: interface
  • spec/rtems/sem/if/create.yml

    rf3be101 r45b6997  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    22brief: |
    3   Creates a semaphore with the specified properties and returns its identifier.
     3  Creates a semaphore.
    44copyrights:
    55- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     
    1818  variants: []
    1919description: |
    20   This directive creates a semaphore which resides on the local node.  The new
    21   semaphore has the user-defined name specified in ``name`` and the initial
    22   count specified in ``count``.  For control and maintenance of the semaphore,
    23   RTEMS allocates and initializes a ${/glossary/smcb:/term}.  The
    24   RTEMS-assigned semaphore identifier is returned in ``id``.  This semaphore
    25   identifier is used with other semaphore related directives to access the
    26   semaphore.
    27 
    28   The attribute set specified in ``attribute_set`` defines
    29 
    30   * the scope of the semaphore (local or global),
    31 
    32   * the discipline of the task wait queue used by the semaphore (FIFO or
    33     priority),
    34 
    35   * the class of the semaphore (counting, binary, or simple binary), and
    36 
    37   * the locking protocol of a binary semaphore (priority inheritance, priority
    38     ceiling or MrsP).
    39 
    40   The attribute set is built through a *bitwise or* of the attribute constants
    41   described below.  Not all combinations of attributes are allowed.  Some
    42   attributes are mutually exclusive.  If mutually exclusive attributes are
    43   combined, the behaviour is undefined.
    44 
    45   The *scope of a semaphore* is either the local node only (local scope) or all
    46   nodes in a multiprocessing network (global scope).  The scope is selected by
    47   the mutually exclusive ${../../attr/if/local:/name} and
     20  This directive creates a semaphore which resides on the local node.  The
     21  semaphore has the user-defined object name specified in ${.:/params[0]/name}
     22  and the initial count specified in ${.:/params[1]/name}.  The assigned object
     23  identifier is returned in ${.:/params[4]/name}.  This identifier is used to
     24  access the semaphore with other semaphore related directives.
     25
     26  The **attribute set** specified in ${.:/params[2]/name} is built through a
     27  *bitwise or* of the attribute constants described below.  Not all
     28  combinations of attributes are allowed.  Some attributes are mutually
     29  exclusive.  If mutually exclusive attributes are combined, the behaviour is
     30  undefined.  Attributes not mentioned below are not evaluated by this
     31  directive and have no effect.  Default attributes can be selected by using
     32  the ${../../attr/if/default:/name} constant.  The attribute set defines
     33
     34  * the scope of the semaphore: ${../../attr/if/local:/name} (default) or
     35    ${../../attr/if/global:/name},
     36
     37  * the task wait queue discipline used by the semaphore:
     38    ${../../attr/if/fifo:/name} (default) or ${../../attr/if/priority:/name},
     39
     40  * the class of the semaphore: ${../../attr/if/counting-semaphore:/name}
     41    (default), ${../../attr/if/binary-semaphore:/name}, or
     42    ${../../attr/if/simple-binary-semaphore:/name}, and
     43
     44  * the locking protocol of a binary semaphore: no locking protocol (default),
     45    ${../../attr/if/inherit-priority:/name},
     46    ${../../attr/if/priority-ceiling:/name}, or
     47    ${../../attr/if/multiprocessor-resource-sharing:/name}.
     48
     49  The semaphore has a local or global **scope** in a multiprocessing network
     50  (this attribute does not refer to SMP systems).  The scope is selected by the
     51  mutually exclusive ${../../attr/if/local:/name} and
    4852  ${../../attr/if/global:/name} attributes.
    4953
    50   * The local scope is the default and can be emphasized through use
    51     of the ${../../attr/if/local:/name} attribute.
    52 
    53   * The global scope is selected by the ${../../attr/if/global:/name} attribute.  In
    54     a single node system and the local and global scope are identical.
    55 
    56   The *task wait queue discipline* is selected by the mutually exclusive
     54  * A **local scope** is the default and can be emphasized through the use of
     55    the ${../../attr/if/local:/name} attribute.  A local semaphore can be only
     56    used by the node which created it.
     57
     58  * A **global scope** is established if the ${../../attr/if/global:/name}
     59    attribute is set.  Setting the global attribute in a single node system has
     60    no effect.
     61
     62  The **task wait queue discipline** is selected by the mutually exclusive
    5763  ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
    5864
    59   * The ${/glossary/fifo:/term} discipline is the default and can be emphasized
     65  * The **FIFO discipline** is the default and can be emphasized
    6066    through use of the ${../../attr/if/fifo:/name} attribute.
    6167
    62   * The priority discipline is selected by the ${../../attr/if/priority:/name}
    63     attribute.  Some locking protocols require the priority discipline.
    64 
    65   The *semaphore class* is selected by the mutually exclusive
     68  * The **priority discipline** is selected by the
     69    ${../../attr/if/priority:/name} attribute.  The locking protocols require
     70    the priority discipline.
     71
     72  The **semaphore class** is selected by the mutually exclusive
    6673  ${../../attr/if/counting-semaphore:/name},
    6774  ${../../attr/if/binary-semaphore:/name}, and
    6875  ${../../attr/if/simple-binary-semaphore:/name} attributes.
    6976
    70   * Counting semaphores are the default and can be emphasized through use of
    71     the ${../../attr/if/counting-semaphore:/name} attribute.
    72 
    73   * Binary semaphores are mutual exclusion (mutex) synchronization primitives
    74     which may have an owner.  The count of a binary semaphore is restricted to
    75     0 and 1.  The binary semaphore class is selected by the
    76     ${../../attr/if/binary-semaphore:/name} attribute.
    77 
    78   * Simple binary semaphores have no owner.  The count of a simple binary
    79     semaphore is restricted to 0 and 1.  They may be used for task and
    80     interrupt synchronization.  The simple binary semaphore class is selected
    81     by the ${../../attr/if/simple-binary-semaphore:/name} attribute.
    82 
    83   Binary semaphores may use a *locking protocol*.  If a locking protocol is
     77  * The **counting semaphore class** is the default and can be emphasized
     78    through use of the ${../../attr/if/counting-semaphore:/name} attribute.
     79
     80  * The **binary semaphore class** is selected by the
     81    ${../../attr/if/binary-semaphore:/name} attribute.  Binary semaphores are
     82    mutual exclusion (mutex) synchronization primitives which may have an
     83    owner.  The count of a binary semaphore is restricted to 0 and 1 values.
     84
     85  * The **simple binary semaphore class** is selected by the
     86    ${../../attr/if/simple-binary-semaphore:/name} attribute.  Simple binary
     87    semaphores have no owner.  They may be used for task and interrupt
     88    synchronization.  The count of a simple binary semaphore is restricted to 0
     89    and 1 values.
     90
     91  Binary semaphores may use a **locking protocol**.  If a locking protocol is
    8492  selected, then the scope shall be local and the priority task wait queue
    8593  discipline shall be selected.  The locking protocol is selected by the
     
    8896  ${../../attr/if/multiprocessor-resource-sharing:/name} attributes.
    8997
    90   * The default is to use no locking protocol.
    91 
    92   * The ${../../attr/if/inherit-priority:/name} attribute selects the priority
    93     inheritance locking protocol.
    94 
    95   * The ${../../attr/if/priority-ceiling:/name} attribute selects the priority
    96     ceiling locking protocol.  For this locking protocol a priority ceiling
    97     shall be specified in ``priority_ceiling``.
    98 
    99   * The ${../../attr/if/multiprocessor-resource-sharing:/name} attribute selects the
    100     MrsP locking protocol in SMP configurations, otherwise it selects the
    101     priority ceiling protocol.  For this locking protocol a priority ceiling
    102     shall be specified in ``priority_ceiling``.  This priority is used to set
    103     the priority ceiling in all scheduler instances.  This can be changed later
    104     with the ${set-priority:/name} directive using the returned semaphore
    105     identifier.
     98  * The default is **no locking protocol**.  This can be emphasized
     99    through use of the ${../../attr/if/no-inherit-priority:/name},
     100    ${../../attr/if/no-multiprocessor-resource-sharing:/name}, and
     101    ${../../attr/if/no-priority-ceiling:/name} attributes.
     102
     103  * The **priority inheritance locking protocol** is selected by the
     104    ${../../attr/if/inherit-priority:/name} attribute.
     105
     106  * The **priority ceiling locking protocol** is selected by the
     107    ${../../attr/if/priority-ceiling:/name} attribute.  For this locking protocol
     108    a priority ceiling shall be specified in ${.:/params[3]/name}.
     109
     110  * The **MrsP locking protocol** is selected by the
     111    ${../../attr/if/multiprocessor-resource-sharing:/name} attribute in SMP
     112    configurations, otherwise this attribute selects the **priority ceiling
     113    locking protocol**.  For these locking protocols a priority ceiling shall be
     114    specified in ${.:/params[3]/name}.  This priority is used to set the
     115    priority ceiling for all schedulers.  This can be changed later with the
     116    ${set-priority:/name} directive using the returned object identifier.
    106117enabled-by: true
    107 index-entries: []
     118index-entries:
     119- create a semaphore
    108120interface-type: function
    109121links:
     
    112124- role: interface-ingroup
    113125  uid: group
     126- role: constraint
     127  uid: /constraint/directive-ctx-devinit
     128- role: constraint
     129  uid: /constraint/directive-ctx-task
     130- role: constraint
     131  uid: /constraint/object-allocator
     132- role: constraint
     133  uid: ../constraint/max
     134- role: constraint
     135  uid: /constraint/obj-unlimited-alloc
     136- role: constraint
     137  uid: ../../constraint/mp-max-global-objects
    114138name: rtems_semaphore_create
    115139notes: |
    116   This directive may cause the calling task to be preempted due to an obtain
    117   and release of the object allocator mutex.
    118 
    119   Semaphores should not be made global unless remote tasks must interact with
    120   the new semaphore.  This is to avoid the system overhead incurred by the
    121   creation of a global semaphore.  When a global semaphore is created, the
    122   semaphore's name and identifier must be transmitted to every node in the
    123   system for insertion in the local copy of the global object table.
    124 
    125   The total number of global objects, including semaphores, is limited by the
    126   ${/acfg/if/mp-max-global-objects:/name} application configuration option.
    127 
    128   It is not allowed to create an initially locked MrsP semaphore and the
    129   ${../../status/if/invalid-number:/name} status code will be returned in SMP
    130   configurations in this case.  This prevents lock order reversal problems
    131   with the allocator mutex.
     140  For control and maintenance of the semaphore, RTEMS allocates a
     141  ${/glossary/smcb:/term} from the local SMCB free pool and initializes it.
     142
     143  The SMCB for a global semaphore is allocated on the local node.  Semaphores
     144  should not be made global unless remote tasks must interact with the
     145  semaphore.  This is to avoid the system overhead incurred by the creation of
     146  a global semaphore.  When a global semaphore is created, the semaphore's name
     147  and identifier must be transmitted to every node in the system for insertion
     148  in the local copy of the global object table.
    132149params:
    133 - description: is the object name of the new semaphore.
     150- description: |
     151    is the object name of the semaphore.
    134152  dir: null
    135153  name: name
    136154- description: |
    137     is the initial count of the new semaphore.  If the semaphore is a mutex,
    138     then a count of 0 will make the calling task the owner of the new mutex and
    139     a count of 1 will create a mutex without an owner.
     155    is the initial count of the semaphore.  If the semaphore is a binary semaphore,
     156    then a count of 0 will make the calling task the owner of the binary semaphore and
     157    a count of 1 will create a binary semaphore without an owner.
    140158  dir: null
    141159  name: count
    142160- description: |
    143     is the attribute set which defines the properties of the new semaphore.
     161    is the attribute set of the semaphore.
    144162  dir: null
    145163  name: attribute_set
    146164- description: |
    147     is the priority ceiling if the new semaphore is a binary semaphore with the
    148     priority ceiling or MrsP semaphore locking protocol as defined by the
    149     attribute set.
     165    is the priority ceiling if the semaphore is a binary semaphore with the
     166    priority ceiling or MrsP locking protocol as defined by the attribute set.
    150167  dir: null
    151168  name: priority_ceiling
    152169- description: |
    153     is the pointer to an object identifier variable.  The object identifier of
    154     the new semaphore will be stored in this variable, in case of a successful
     170    is the pointer to an object identifier variable.  The identifier of the
     171    created semaphore will be stored in this variable, in case of a successful
    155172    operation.
    156173  dir: out
     
    163180    value: ${../../status/if/successful:/name}
    164181  - description: |
    165       The ${.:/params[3]/name} parameter was ${/c/if/null:/name}.
     182      The ${.:/params[0]/name} parameter was invalid.
     183    value: ${../../status/if/invalid-name:/name}
     184  - description: |
     185      The ${.:/params[4]/name} parameter was ${/c/if/null:/name}.
    166186    value: ${../../status/if/invalid-address:/name}
    167187  - description: |
    168       The semaphore name was invalid.
    169     value: ${../../status/if/invalid-name:/name}
    170   - description: |
    171       The priority ceiling was invalid.
    172     value: ${../../status/if/invalid-priority:/name}
    173   - description: |
    174       The attribute set was invalid.
     188      The ${.:/params[1]/name} parameter was invalid.
     189    value: ${../../status/if/invalid-number:/name}
     190  - description: |
     191      The ${.:/params[2]/name} parameter was invalid.
    175192    value: ${../../status/if/not-defined:/name}
    176193  - description: |
    177       There was no inactive semaphore object available to create a new
    178       semaphore.  The semaphore object maximum is defined by the
     194      There was no inactive object available to create a semaphore.  The number
     195      of semaphores available to the application is configured through the
    179196      ${/acfg/if/max-semaphores:/name} application configuration option.
    180197    value: ${../../status/if/too-many:/name}
    181198  - description: |
    182199      In multiprocessing configurations, there was no inactive global object
    183       available to create a new global semaphore.
     200      available to create a global semaphore.  The number of global objects
     201      available to the application is configured through the
     202      ${/acfg/if/mp-max-global-objects:/name} application configuration option.
    184203    value: ${../../status/if/too-many:/name}
     204  - description: |
     205      The ${.:/params[3]/name} parameter was invalid.
     206    value: ${../../status/if/invalid-priority:/name}
    185207type: interface
  • spec/rtems/task/if/construct.yml

    rf3be101 r45b6997  
    5555- description: |
    5656    is the pointer to an object identifier variable.  The identifier of the
    57     constructed task object will be stored in this variable, in case of a
    58     successful operation.
     57    constructed task will be stored in this variable, in case of a successful
     58    operation.
    5959  dir: out
    6060  name: id
  • spec/rtems/task/if/create.yml

    rf3be101 r45b6997  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    22brief: |
    3   Creates a task object.
     3  Creates a task.
    44copyrights:
    5 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     5- Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
    66- Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
    77definition:
     
    1919  variants: []
    2020description: |
    21   This directive creates a task which resides on the local node. It allocates
    22   and initializes a TCB, a stack, and an optional floating point context area.
    23   The mode parameter contains values which sets the task’s initial execution
    24   mode. The RTEMS_FLOATING_POINT attribute should be specified if the created
    25   task is to use a numeric coprocessor. For performance reasons, it is
    26   recommended that tasks not using the numeric coprocessor should specify the
    27   RTEMS_NO_FLOATING_POINT attribute. If the RTEMS_GLOBAL attribute is
    28   specified, the task can be accessed from remote nodes. The task id, returned
    29   in id, is used in other task related directives to access the task. When
    30   created, a task is placed in the dormant state and can only be made ready to
    31   execute using the directive rtems_task_start().
     21  This directive creates a task which resides on the local node.  The task has
     22  the user-defined object name specified in ${.:/params[0]/name}.  The assigned
     23  object identifier is returned in ${.:/params[5]/name}.  This identifier is
     24  used to access the task with other task related directives.
     25
     26  The **initial priority** of the task is specified in ${.:/params[1]/name}.
     27  The scheduler of the created task is the scheduler of the calling task at
     28  some point during the task creation.  The initial task priority specified in
     29  ${.:/params[1]/name} shall be valid for this scheduler.
     30
     31  The **stack size** of the task is specified in ${.:/params[2]/name}.  If the
     32  requested stack size is less than the configured minimum stack size, then
     33  RTEMS will use the configured minimum as the stack size for this task.  The
     34  configured minimum stack size is defined by the
     35  ${/acfg/if/min-task-stack-size:/name} application configuration option.  In
     36  addition to being able to specify the task stack size as a integer, there are
     37  two constants which may be specified:
     38
     39  * The ${minimum-stack-size:/name} constant can be specified to use the
     40    **recommended minimum stack size** for the target processor.  This value is
     41    selected by the RTEMS maintainers conservatively to minimize the risk of
     42    blown stacks for most user applications.  Using this constant when
     43    specifying the task stack size, indicates that the stack size will be at
     44    least ${minimum-stack-size:/name} bytes in size.  If the user configured
     45    minimum stack size is larger than the recommended minimum, then it will be
     46    used.
     47
     48  * The ${configured-minimum-stack-size:/name} constant can be specified to use
     49    the minimum stack size that was configured by the application.  If not
     50    explicitly configured by the application, the default configured minimum
     51    stack size is the target processor dependent value
     52    ${minimum-stack-size:/name}.  Since this uses the configured minimum stack
     53    size value, you may get a stack size that is smaller or larger than the
     54    recommended minimum.  This can be used to provide large stacks for all
     55    tasks on complex applications or small stacks on applications that are
     56    trying to conserve memory.
     57
     58  The **initial mode set** specified in ${.:/params[3]/name} is built through a
     59  *bitwise or* of the mode constants described below.  Not all combinations of
     60  modes are allowed.  Some modes are mutually exclusive.  If mutually exclusive
     61  modes are combined, the behaviour is undefined.  Default task modes can be
     62  selected by using the ${../../mode/if/default:/name} constant.  The task mode
     63  set defines
     64
     65  * the preemption mode of the task: ${../../mode/if/preempt:/name} (default)
     66    or ${../../mode/if/no-preempt:/name},
     67
     68  * the timeslicing mode of the task: ${../../mode/if/timeslice:/name} or
     69    ${../../mode/if/no-timeslice:/name} (default),
     70
     71  * the ${/glossary/asr:/term} processing mode of the task:
     72    ${../../mode/if/asr:/name} (default) or ${../../mode/if/no-asr:/name},
     73
     74  * the interrupt level mode of the task:
     75    ${../../mode/if/interrupt-level:/name}.
     76
     77  The **initial preemption mode** of the task is enabled or disabled.
     78
     79  * An **enabled preemption** is the default and can be emphasized through the
     80    use of the ${../../mode/if/preempt:/name} mode constant.
     81
     82  * A **disabled preemption** is set by the ${../../mode/if/no-preempt:/name}
     83    mode constant.
     84
     85  The **initial timeslicing mode** of the task is enabled or disabled.
     86
     87  * A **disabled timeslicing** is the default and can be emphasized through the
     88    use of the ${../../mode/if/no-timeslice:/name} mode constant.
     89
     90  * An **enabled timeslicing** is set by the ${../../mode/if/timeslice:/name}
     91    mode constant.
     92
     93  The **initial ASR processing mode** of the task is enabled or disabled.
     94
     95  * An **enabled ASR processing** is the default and can be emphasized through
     96    the use of the ${../../mode/if/asr:/name} mode constant.
     97
     98  * A **disabled ASR processing** is set by the ${../../mode/if/no-asr:/name}
     99    mode constant.
     100
     101  The **initial interrupt level mode** of the task is defined by
     102  ${../../mode/if/interrupt-level:/name}.
     103
     104  * Task execution with **interrupts enabled** the default and can be
     105    emphasized through the use of the ${../../mode/if/interrupt-level:/name}
     106    mode macro with a value of zero (0) for the parameter.  An interrupt level
     107    of zero is associated with enabled interrupts on all target processors.
     108
     109  * Task execution at a **non-zero interrupt level** can be specified by the
     110    ${../../mode/if/interrupt-level:/name} mode macro with a non-zero value for
     111    the parameter.  The interrupt level portion of the task mode supports a
     112    maximum of 256 interrupt levels.  These levels are mapped onto the
     113    interrupt levels actually supported by the target processor in a processor
     114    dependent fashion.
     115
     116  The **attribute set** specified in ${.:/params[4]/name} is built through a
     117  *bitwise or* of the attribute constants described below.  Not all
     118  combinations of attributes are allowed.  Some attributes are mutually
     119  exclusive.  If mutually exclusive attributes are combined, the behaviour is
     120  undefined.  Attributes not mentioned below are not evaluated by this
     121  directive and have no effect.  Default attributes can be selected by using
     122  the ${../../attr/if/default:/name} constant.  The attribute set defines
     123
     124  * the scope of the task: ${../../attr/if/local:/name} (default) or
     125    ${../../attr/if/global:/name} and
     126
     127  * the floating-point unit use of the task:
     128    ${../../attr/if/floating-point:/name} or
     129    ${../../attr/if/no-floating-point:/name} (default).
     130
     131  The task has a local or global **scope** in a multiprocessing network
     132  (this attribute does not refer to SMP systems).  The scope is selected by the
     133  mutually exclusive ${../../attr/if/local:/name} and
     134  ${../../attr/if/global:/name} attributes.
     135
     136  * A **local scope** is the default and can be emphasized through the use of
     137    the ${../../attr/if/local:/name} attribute.  A local task can be only used
     138    by the node which created it.
     139
     140  * A **global scope** is established if the ${../../attr/if/global:/name}
     141    attribute is set.  Setting the global attribute in a single node system has
     142    no effect.the
     143
     144  The **use of the floating-point unit** is selected by the mutually exclusive
     145  ${../../attr/if/floating-point:/name} and
     146  ${../../attr/if/no-floating-point:/name} attributes.  On some target
     147  processors, the use of the floating-point unit can be enabled or disabled for
     148  each task.  Other target processors may have no hardware floating-point unit
     149  or enable the use of the floating-point unit for all tasks.  Consult the
     150  *RTEMS CPU Architecture Supplement* for the details.
     151
     152  * A **disabled floating-point unit** is the default and can be emphasized
     153    through use of the ${../../attr/if/no-floating-point:/name} attribute.  For
     154    performance reasons, it is recommended that tasks not using the
     155    floating-point unit should specify this attribute.
     156
     157  * An **enabled floating-point unit** is selected by the
     158    ${../../attr/if/floating-point:/name} attribute.
    32159enabled-by: true
    33 index-entries: []
     160index-entries:
     161- create a task
    34162interface-type: function
    35163links:
     
    38166- role: interface-ingroup
    39167  uid: group
     168- role: constraint
     169  uid: /constraint/directive-ctx-devinit
     170- role: constraint
     171  uid: /constraint/directive-ctx-task
     172- role: constraint
     173  uid: /constraint/object-allocator
     174- role: constraint
     175  uid: ../constraint/max
     176- role: constraint
     177  uid: /constraint/obj-unlimited-alloc
     178- role: constraint
     179  uid: ../../constraint/mp-max-global-objects
    40180name: rtems_task_create
    41 notes: null
     181notes: |
     182  The task processor affinity is initialized to the set of online processors.
     183
     184  When created, a task is placed in the dormant state and can only be made
     185  ready to execute using the directive ${start:/name}.
     186
     187  Application developers should consider the stack usage of the device drivers
     188  when calculating the stack size required for tasks which utilize the driver.
     189  The task stack size shall account for an target processor dependent interrupt
     190  stack frame which may be placed on the stack of the interrupted task while
     191  servicing an interrupt.  The stack checker may be used to monitor the stack
     192  usage, see ${/acfg/if/stack-checker-enabled:/name}.
     193
     194  For control and maintenance of the task, RTEMS allocates a
     195  ${/glossary/tcb:/term} from the local TCB free pool and initializes it.
     196
     197  The TCB for a global task is allocated on the local node.  Task should not be
     198  made global unless remote tasks must interact with the task.  This is to
     199  avoid the system overhead incurred by the creation of a global task.  When a
     200  global task is created, the task's name and identifier must be transmitted to
     201  every node in the system for insertion in the local copy of the global object
     202  table.
    42203params:
    43 - description: is the user-defined task name.
     204- description: |
     205    is the object name of the task.
    44206  dir: null
    45207  name: name
    46 - description: is the initial task priority.
     208- description: |
     209    is the initial task priority.
    47210  dir: null
    48211  name: initial_priority
    49 - description: is the task stack size in bytes.
     212- description: |
     213    is the task stack size in bytes.
    50214  dir: null
    51215  name: stack_size
    52 - description: is the initial task mode.
     216- description: |
     217    is the initial mode set of the task.
    53218  dir: null
    54219  name: initial_modes
    55 - description: is the task attribute set.
     220- description: |
     221    is the attribute set of the task.
    56222  dir: null
    57223  name: attribute_set
    58224- description: |
    59     is the pointer to an object identifier variable.  The object identifier of
    60     the new task will be stored in this variable, in case of a successful
     225    is the pointer to an object identifier variable.  The identifier of the
     226    created task will be stored in this variable, in case of a successful
    61227    operation.
    62228  dir: out
     
    69235    value: ${../../status/if/successful:/name}
    70236  - description: |
     237      The ${.:/params[0]/name} parameter was invalid.
     238    value: ${../../status/if/invalid-name:/name}
     239  - description: |
    71240      The ${.:/params[5]/name} parameter was ${/c/if/null:/name}.
    72241    value: ${../../status/if/invalid-address:/name}
    73242  - description: |
    74       The task name was invalid.
    75     value: ${../../status/if/invalid-name:/name}
    76   - description: |
    77       The initial task priority was invalid.
     243      The ${.:/params[1]/name} was invalid.
    78244    value: ${../../status/if/invalid-priority:/name}
    79245  - description: |
    80       The multiprocessing support was not configured.
    81     value: ${../../status/if/mp-not-configured:/name}
    82   - description: |
    83       There was no inactive task object available to create a new task.
     246      There was no inactive object available to create a task.  The number of
     247      tasks available to the application is configured through the
     248      ${/acfg/if/max-tasks:/name} application configuration option.
    84249    value: ${../../status/if/too-many:/name}
    85250  - description: |
    86251      In multiprocessing configurations, there was no inactive global object
    87       available to create a new global task.
     252      available to create a global task.  The number of global objects
     253      available to the application is configured through the
     254      ${/acfg/if/mp-max-global-objects:/name} application configuration option.
    88255    value: ${../../status/if/too-many:/name}
    89256  - description: |
     
    93260    value: ${../../status/if/unsatisfied:/name}
    94261  - description: |
    95       One of the task create extensions failed to create the new task.
     262      One of the task create extensions failed to create the task.
    96263    value: ${../../status/if/unsatisfied:/name}
    97264  - description: |
  • spec/rtems/timer/if/create.yml

    rf3be101 r45b6997  
    33  Creates a timer.
    44copyrights:
    5 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     5- Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
    66- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
    77definition:
     
    1515  variants: []
    1616description: |
    17   This directive creates a timer.  The assigned object identifier is returned
    18   in ${.:/params[1]/name}.  This identifier is used to access the timer with
    19   other timer related directives.
     17  This directive creates a timer which resides on the local node.  The timer
     18  has the user-defined object name specified in ${.:/params[0]/name}.  The
     19  assigned object identifier is returned in ${.:/params[1]/name}.  This
     20  identifier is used to access the timer with other timer related directives.
    2021enabled-by: true
    2122index-entries:
     
    2728- role: interface-ingroup
    2829  uid: group
     30- role: constraint
     31  uid: /constraint/directive-ctx-devinit
     32- role: constraint
     33  uid: /constraint/directive-ctx-task
     34- role: constraint
     35  uid: /constraint/object-allocator
     36- role: constraint
     37  uid: ../constraint/max
     38- role: constraint
     39  uid: /constraint/obj-unlimited-alloc
    2940name: rtems_timer_create
    3041notes: |
    31   This directive may cause the calling task to be preempted due to an obtain
    32   and release of the object allocator mutex.
     42  The processor used to maintain the timer is the processor of the calling task
     43  at some point during the timer creation.
    3344
    3445  For control and maintenance of the timer, RTEMS allocates a
    3546  ${/glossary/tmcb:/term} from the local TMCB free pool and initializes it.
    36 
    37   In SMP configurations, the processor of the currently executing thread
    38   determines the processor used for the created timer.  During the life-time of
    39   the timer this processor is used to manage the timer internally.
    4047params:
    41 - description: is the name of the timer.
     48- description: |
     49    is the object name of the timer.
    4250  dir: null
    4351  name: name
    4452- description: |
    4553    is the pointer to an object identifier variable.  The identifier of the
    46     created timer object will be stored in this variable, in case of a
    47     successful operation.
     54    created timer will be stored in this variable, in case of a successful
     55    operation.
    4856  dir: out
    4957  name: id
     
    5563    value: ${../../status/if/successful:/name}
    5664  - description: |
    57       The timer name was invalid.
     65      The ${.:/params[0]/name} parameter was invalid.
    5866    value: ${../../status/if/invalid-name:/name}
    5967  - description: |
     
    6169    value: ${../../status/if/invalid-address:/name}
    6270  - description: |
    63       There was no inactive object available to create a new timer.  The number
    64       of timers available to the application is configured through the
    65       ${/acfg/if/max-timers:/name} configuration option.
     71      There was no inactive object available to create a timer.  The number of
     72      timers available to the application is configured through the
     73      ${/acfg/if/max-timers:/name} application configuration option.
    6674    value: ${../../status/if/too-many:/name}
    6775type: interface
  • spec/rtems/userext/if/create.yml

    rf3be101 r45b6997  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  Creates an extension set.
    34copyrights:
    4 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     5- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
    56- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
    67definition:
     
    1415    return: ${../../status/if/code:/name}
    1516  variants: []
    16 description: null
     17description: |
     18  This directive creates an extension set which resides on the local node.  The
     19  extension set has the user-defined object name specified in
     20  ${.:/params[0]/name}.  The assigned object identifier is returned in
     21  ${.:/params[2]/name}.  This identifier is used to access the extension set
     22  with other extension set related directives.
     23
     24  The extension set is initialized using the extension table specified in
     25  ${.:/params[1]/name}.
    1726enabled-by: true
    18 index-entries: []
     27index-entries:
     28- create an extension set
    1929interface-type: function
    2030links:
     
    2333- role: interface-ingroup
    2434  uid: group
     35- role: constraint
     36  uid: /constraint/directive-ctx-devinit
     37- role: constraint
     38  uid: /constraint/directive-ctx-task
     39- role: constraint
     40  uid: /constraint/object-allocator
     41- role: constraint
     42  uid: ../constraint/max
    2543name: rtems_extension_create
    26 notes: null
     44notes: |
     45  The user-provided extension set table is not used after the return of the
     46  directive.
     47
     48  Newly created extension sets are immediately installed and are invoked upon
     49  the next system event supporting an extension.
     50
     51  An alternative to dynamically created extension sets are initial extensions,
     52  see ${/acfg/if/initial-extensions:/name}.  Initial extensions are recommended
     53  for extension sets which provide a fatal error extension.
     54
     55  For control and maintenance of the extension set, RTEMS allocates a
     56  ${/glossary/escb:/term} from the local ESCB free pool and initializes it.
    2757params:
    28 - description: '%'
     58- description: |
     59    is the object name of the extension set.
    2960  dir: null
    3061  name: name
    31 - description: '%'
     62- description: |
    3263  dir: null
    3364  name: extension_table
    34 - description: '%'
    35   dir: null
     65- description: |
     66    is the pointer to an object identifier variable.  The identifier of the
     67    created extension set will be stored in this variable, in case of a
     68    successful operation.
     69  dir: out
    3670  name: id
    3771return:
    3872  return: null
    39   return-values: []
     73  return-values:
     74  - description: |
     75      The requested operation was successful.
     76    value: ${../../status/if/successful:/name}
     77  - description: |
     78      The ${.:/params[0]/name} parameter was invalid.
     79    value: ${../../status/if/invalid-name:/name}
     80  - description: |
     81      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
     82    value: ${../../status/if/invalid-address:/name}
     83  - description: |
     84      The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
     85    value: ${../../status/if/invalid-address:/name}
     86  - description: |
     87      There was no inactive object available to create an extension set.  The
     88      number of extension sets available to the application is configured
     89      through the ${/acfg/if/max-user-extensions:/name} application
     90      configuration option.
     91    value: ${../../status/if/too-many:/name}
    4092type: interface
Note: See TracChangeset for help on using the changeset viewer.