blob: 4f0133ae6d24062b3178256f384495bc3b2ffb22 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
Creates a barrier.
copyrights:
- Copyright (C) 2021 embedded brains GmbH & Co. KG
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default:
attributes: null
body: null
params:
- ${../../type/if/name:/name} ${.:/params[0]/name}
- ${../../attr/if/attribute:/name} ${.:/params[1]/name}
- ${/c/if/uint32_t:/name} ${.:/params[2]/name}
- ${../../type/if/id:/name} *${.:/params[3]/name}
return: ${../../status/if/code:/name}
variants: []
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:
- 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: |
For control and maintenance of the barrier, RTEMS allocates a
${/glossary/bcb:/term} from the local BCB free pool and initializes it.
params:
- description: |
is the object name of the barrier.
dir: null
name: name
- description: |
is the attribute set of the barrier.
dir: null
name: attribute_set
- description: |
is the maximum count of waiters on an automatic release barrier.
dir: null
name: maximum_waiters
- description: |
is the pointer to an ${../../type/if/id:/name} object. When the directive call
is successful, the identifier of the created barrier will be stored in this
object.
dir: null
name: id
return:
return: null
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
|
