source: rtems-central/spec/rtems/barrier/if/create.yml @ 45b6997

Last change on this file since 45b6997 was 45b6997, checked in by Sebastian Huber <sebastian.huber@…>, on 01/13/21 at 13:05:42

spec: Document all create directives

  • Property mode set to 100644
File size: 4.3 KB
Line 
1SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
2brief: |
3  Creates a barrier.
4copyrights:
5- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
6- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
7definition:
8  default:
9    attributes: null
10    body: null
11    params:
12    - ${../../type/if/name:/name} ${.:/params[0]/name}
13    - ${../../attr/if/attribute:/name} ${.:/params[1]/name}
14    - ${/c/if/uint32_t:/name} ${.:/params[2]/name}
15    - ${../../type/if/id:/name} *${.:/params[3]/name}
16    return: ${../../status/if/code:/name}
17  variants: []
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.
50enabled-by: true
51index-entries:
52- create a barrier
53interface-type: function
54links:
55- role: interface-placement
56  uid: header
57- role: interface-ingroup
58  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
69name: rtems_barrier_create
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.
73params:
74- description: |
75    is the object name of the barrier.
76  dir: null
77  name: name
78- description: |
79    is the attribute set of the barrier.
80  dir: null
81  name: attribute_set
82- description: |
83    is the maximum count of waiters on an automatic release barrier.
84  dir: null
85  name: maximum_waiters
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.
90  dir: null
91  name: id
92return:
93  return: null
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}
113type: interface
Note: See TracBrowser for help on using the repository browser.