blob: ba66e825579bbf5a3a50934213e27714fd26f6f5 (
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
Creates a partition.
copyrights:
- Copyright (C) 2020 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}
- void *${.:/params[1]/name}
- ${/c/if/uintptr_t:/name} ${.:/params[2]/name}
- ${/c/if/size_t:/name} ${.:/params[3]/name}
- ${../../attr/if/attribute:/name} ${.:/params[4]/name}
- ${../../type/if/id:/name} *${.:/params[5]/name}
return: ${../../status/if/code:/name}
variants: []
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 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. 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 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 partition can be only
used by the node which created it.
* 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.
enabled-by: true
index-entries:
- create a partition
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/mp-send
- 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: |
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
long double or vector data types, the partition buffer area and the buffer
size must take the alignment of these types into account which is usually
larger than the pointer alignment. A cache line alignment may be also a
factor. Use ${alignment:/name} to specify the minimum alignment of a
partition buffer type.
The ${.:/params[3]/name} parameter must be an integral multiple of the
pointer size on the target architecture. Additionally,
${.:/params[3]/name} must be large enough to hold two pointers on the
target architecture. This is required for RTEMS to manage the buffers when
they are free.
For control and maintenance of the partition, RTEMS allocates a
${/glossary/ptcb:/term} from the local PTCB free pool and initializes it.
Memory from the partition buffer area is not used by RTEMS to store the PTCB.
The PTCB for a global partition is allocated on the local node. Partitions
should not be made global unless remote tasks must interact with the
partition. This is to avoid the overhead incurred by the creation of a
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.
params:
- 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.
dir: null
name: starting_address
- description: is the length in bytes of the buffer area used by the partition.
dir: null
name: length
- description: is the size in bytes of a buffer managed by the partition.
dir: null
name: buffer_size
- description: is the attribute set of the partition.
dir: null
name: attribute_set
- description: |
is the pointer to an ${../../type/if/id:/name} object. When the directive
call is successful, the identifier of the created partition will be stored
in this object.
dir: out
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[5]/name} parameter was ${/c/if/null:/name}.
value: ${../../status/if/invalid-address:/name}
- description: |
The ${.:/params[2]/name} parameter was 0.
value: ${../../status/if/invalid-size:/name}
- description: |
The ${.:/params[3]/name} parameter was 0.
value: ${../../status/if/invalid-size:/name}
- description: |
The ${.:/params[2]/name} parameter was less than the
${.:/params[3]/name} parameter.
value: ${../../status/if/invalid-size:/name}
- description: |
The ${.:/params[3]/name} parameter was not an integral multiple of
the pointer size.
value: ${../../status/if/invalid-size:/name}
- description: |
The ${.:/params[3]/name} parameter was less than two times the
pointer size.
value: ${../../status/if/invalid-size:/name}
- description: |
The ${.:/params[1]/name} parameter was not on a pointer size
boundary.
value: ${../../status/if/invalid-address:/name}
- description: |
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
|
