[e27600e] | 1 | SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause |
---|
[45b6997] | 2 | brief: | |
---|
| 3 | Creates a barrier. |
---|
[e27600e] | 4 | copyrights: |
---|
[45b6997] | 5 | - Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) |
---|
[e27600e] | 6 | - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) |
---|
| 7 | definition: |
---|
| 8 | default: |
---|
[d3edaca] | 9 | attributes: null |
---|
[e27600e] | 10 | body: null |
---|
| 11 | params: |
---|
[3bdf817] | 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} |
---|
[e27600e] | 17 | variants: [] |
---|
[45b6997] | 18 | description: | |
---|
| 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. |
---|
[e27600e] | 50 | enabled-by: true |
---|
[45b6997] | 51 | index-entries: |
---|
| 52 | - create a barrier |
---|
[e27600e] | 53 | interface-type: function |
---|
| 54 | links: |
---|
| 55 | - role: interface-placement |
---|
| 56 | uid: header |
---|
| 57 | - role: interface-ingroup |
---|
[cead53e] | 58 | uid: group |
---|
[45b6997] | 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 |
---|
[e27600e] | 69 | name: rtems_barrier_create |
---|
[45b6997] | 70 | notes: | |
---|
| 71 | For control and maintenance of the barrier, RTEMS allocates a |
---|
| 72 | ${/glossary/bcb:/term} from the local BCB free pool and initializes it. |
---|
[e27600e] | 73 | params: |
---|
[45b6997] | 74 | - description: | |
---|
| 75 | is the object name of the barrier. |
---|
[e27600e] | 76 | dir: null |
---|
| 77 | name: name |
---|
[45b6997] | 78 | - description: | |
---|
| 79 | is the attribute set of the barrier. |
---|
[e27600e] | 80 | dir: null |
---|
| 81 | name: attribute_set |
---|
[45b6997] | 82 | - description: | |
---|
| 83 | is the maximum count of waiters on an automatic release barrier. |
---|
[e27600e] | 84 | dir: null |
---|
| 85 | name: maximum_waiters |
---|
[45b6997] | 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. |
---|
[e27600e] | 90 | dir: null |
---|
| 91 | name: id |
---|
| 92 | return: |
---|
| 93 | return: null |
---|
[45b6997] | 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} |
---|
[e27600e] | 113 | type: interface |
---|