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
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
|
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
Directives
==========
This section details the partition manager's directives. A subsection is
dedicated to each of this manager's directives and describes the calling
sequence, related constants, usage, and status codes.
.. raw:: latex
\clearpage
.. index:: create a partition
.. index:: rtems_partition_create
.. _rtems_partition_create:
PARTITION_CREATE - Create a partition
-------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_partition_create(
rtems_name name,
void *starting_address,
uintptr_t length,
size_t buffer_size,
rtems_attribute attribute_set,
rtems_id *id
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- partition created successfully
* - ``RTEMS_INVALID_NAME``
- invalid partition ``name``
* - ``RTEMS_TOO_MANY``
- too many partitions created
* - ``RTEMS_INVALID_ADDRESS``
- ``starting_address`` is not on a pointer size boundary
* - ``RTEMS_INVALID_ADDRESS``
- ``starting_address`` is NULL
* - ``RTEMS_INVALID_ADDRESS``
- ``id`` is NULL
* - ``RTEMS_INVALID_SIZE``
- ``length`` or ``buffer_size`` is 0
* - ``RTEMS_INVALID_SIZE``
- ``length`` is less than the ``buffer_size``
* - ``RTEMS_INVALID_SIZE``
- ``buffer_size`` is not an integral multiple of the pointer size
* - ``RTEMS_INVALID_SIZE``
- ``buffer_size`` is less than two times the pointer size
* - ``RTEMS_TOO_MANY``
- too many global objects
DESCRIPTION:
This directive creates a partition of fixed size buffers from a physically
contiguous memory space which starts at starting_address and is length
bytes in size. Each allocated buffer is to be of ``buffer_size`` in bytes.
The assigned partition id is returned in ``id``. This partition id is used
to access the partition with other partition related directives. For
control and maintenance of the partition, RTEMS allocates a PTCB from the
local PTCB free pool and initializes it.
NOTES:
This directive may cause the calling task to be preempted due to an
obtain and release of the object allocator mutex.
The partition buffer area specified by the ``starting_address`` must be
properly aligned. It must be possible to directly store target
architecture pointers and the 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.
The ``buffer_size`` parameter must be an integral multiple of the pointer
size on the target architecture. Additionally, ``buffer_size`` 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.
Memory from the partition is not used by RTEMS to store the Partition
Control Block.
The following partition attribute constants are defined by RTEMS:
.. list-table::
:class: rtems-table
* - ``RTEMS_LOCAL``
- local partition (default)
* - ``RTEMS_GLOBAL``
- global partition
The PTCB for a global partition is allocated on the local node. The memory
space used for the partition must reside in shared memory. 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 id must be transmitted to every node in the system for insertion in the
local copy of the global object table.
The total number of global objects, including partitions, is limited by the
maximum_global_objects field in the Configuration Table.
EXAMPLE:
.. code-block:: c
#include <rtems.h>
#include <rtems/chain.h>
#include <assert.h>
typedef struct {
char less;
short more;
} item;
union {
item data;
rtems_chain_node node;
} items[ 13 ];
rtems_id create_partition(void)
{
rtems_id id;
rtems_status_code sc;
sc = rtems_partition_create(
rtems_build_name( 'P', 'A', 'R', 'T' ),
items,
sizeof( items ),
sizeof( items[ 0 ] ),
RTEMS_DEFAULT_ATTRIBUTES,
&id
);
assert(sc == RTEMS_SUCCESSFUL);
return id;
}
.. raw:: latex
\clearpage
.. index:: get ID of a partition
.. index:: obtain ID of a partition
.. index:: rtems_partition_ident
.. _rtems_partition_ident:
PARTITION_IDENT - Get ID of a partition
---------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_partition_ident(
rtems_name name,
uint32_t node,
rtems_id *id
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- partition identified successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``id`` is NULL
* - ``RTEMS_INVALID_NAME``
- partition name not found
* - ``RTEMS_INVALID_NODE``
- invalid node id
DESCRIPTION:
This directive obtains the partition id associated with the partition name.
If the partition name is not unique, then the partition id will match one
of the partitions with that name. However, this partition id is not
guaranteed to correspond to the desired partition. The partition id is
used with other partition related directives to access the partition.
NOTES:
This directive will not cause the running task to be preempted.
If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the
local node being searched first. All other nodes are searched with the
lowest numbered node searched first.
If node is a valid node number which does not represent the local node,
then only the partitions exported by the designated node are searched.
This directive does not generate activity on remote nodes. It accesses
only the local copy of the global object table.
.. raw:: latex
\clearpage
.. index:: delete a partition
.. index:: rtems_partition_delete
.. _rtems_partition_delete:
PARTITION_DELETE - Delete a partition
-------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_partition_delete(
rtems_id id
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- partition deleted successfully
* - ``RTEMS_INVALID_ID``
- invalid partition id
* - ``RTEMS_RESOURCE_IN_USE``
- buffers still in use
* - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
- cannot delete remote partition
DESCRIPTION:
This directive deletes the partition specified by id. The partition cannot
be deleted if any of its buffers are still allocated. The PTCB for the
deleted partition is reclaimed by RTEMS.
NOTES:
This directive may cause the calling task to be preempted due to an
obtain and release of the object allocator mutex.
The calling task does not have to be the task that created the partition.
Any local task that knows the partition id can delete the partition.
When a global partition is deleted, the partition id must be transmitted to
every node in the system for deletion from the local copy of the global
object table.
The partition must reside on the local node, even if the partition was
created with the ``RTEMS_GLOBAL`` option.
.. raw:: latex
\clearpage
.. index:: get buffer from partition
.. index:: obtain buffer from partition
.. index:: rtems_partition_get_buffer
.. _rtems_partition_get_buffer:
PARTITION_GET_BUFFER - Get buffer from a partition
--------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_partition_get_buffer(
rtems_id id,
void **buffer
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- buffer obtained successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``buffer`` is NULL
* - ``RTEMS_INVALID_ID``
- invalid partition id
* - ``RTEMS_UNSATISFIED``
- all buffers are allocated
DESCRIPTION:
This directive allows a buffer to be obtained from the partition specified
in id. The address of the allocated buffer is returned in buffer.
NOTES:
This directive will not cause the running task to be preempted.
All buffers begin on a four byte boundary.
A task cannot wait on a buffer to become available.
Getting a buffer from a global partition which does not reside on the local
node will generate a request telling the remote node to allocate a buffer
from the specified partition.
.. raw:: latex
\clearpage
.. index:: return buffer to partitition
.. index:: rtems_partition_return_buffer
.. _rtems_partition_return_buffer:
PARTITION_RETURN_BUFFER - Return buffer to a partition
------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_partition_return_buffer(
rtems_id id,
void *buffer
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- buffer returned successfully
* - ``RTEMS_INVALID_ADDRESS``
- ``buffer`` is NULL
* - ``RTEMS_INVALID_ID``
- invalid partition id
* - ``RTEMS_INVALID_ADDRESS``
- buffer address not in partition
DESCRIPTION:
This directive returns the buffer specified by buffer to the partition
specified by id.
NOTES:
This directive will not cause the running task to be preempted.
Returning a buffer to a global partition which does not reside on the local
node will generate a request telling the remote node to return the buffer
to the specified partition.
Returning a buffer multiple times is an error. It will corrupt the
internal state of the partition.
|