summaryrefslogtreecommitdiffstats
path: root/doc/user/part.t
blob: 46046313d190bb7f9bebdd6561887f977bc5244c (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
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
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
@c
@c  COPYRIGHT (c) 1988-1998.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.
@c
@c  $Id$
@c

@ifinfo
@node Partition Manager, Partition Manager Introduction, SIGNAL_SEND - Send signal set to a task, Top
@end ifinfo
@chapter Partition Manager
@ifinfo
@menu
* Partition Manager Introduction::
* Partition Manager Background::
* Partition Manager Operations::
* Partition Manager Directives::
@end menu
@end ifinfo

@ifinfo
@node Partition Manager Introduction, Partition Manager Background, Partition Manager, Partition Manager
@end ifinfo
@section Introduction

The partition manager provides facilities to
dynamically allocate memory in fixed-size units.  The directives
provided by the partition manager are:

@itemize @bullet
@item @code{partition_create} - Create a partition
@item @code{partition_ident} - Get ID of a partition
@item @code{partition_delete} - Delete a partition
@item @code{partition_get_buffer} - Get buffer from a partition
@item @code{partition_return_buffer} - Return buffer to a partition
@end itemize

@ifinfo
@node Partition Manager Background, Partition Manager Definitions, Partition Manager Introduction, Partition Manager
@end ifinfo
@section Background
@ifinfo
@menu
* Partition Manager Definitions::
* Building a Partition's Attribute Set::
@end menu
@end ifinfo

@ifinfo
@node Partition Manager Definitions, Building a Partition's Attribute Set, Partition Manager Background, Partition Manager Background
@end ifinfo
@subsection Partition Manager Definitions

A partition is a physically contiguous memory area
divided into fixed-size buffers that can be dynamically
allocated and deallocated.

Partitions are managed and maintained as a list of
buffers.  Buffers are obtained from the front of the partition's
free buffer chain and returned to the rear of the same chain.
When a buffer is on the free buffer chain, RTEMS uses eight
bytes of each buffer as the free buffer chain.  When a buffer is
allocated, the entire buffer is available for application use.
Therefore, modifying memory that is outside of an allocated
buffer could destroy the free buffer chain or the contents of an
adjacent allocated buffer.

@ifinfo
@node Building a Partition's Attribute Set, Partition Manager Operations, Partition Manager Definitions, Partition Manager Background
@end ifinfo
@subsection Building a Partition's Attribute Set

In general, an attribute set is built by a bitwise OR
of the desired attribute components.  The set of valid partition
attributes is provided in the following table:

@itemize @bullet
@item LOCAL - local task (default)
@item GLOBAL - global task
@end itemize



Attribute values are specifically designed to be
mutually exclusive, therefore bitwise OR and addition operations
are equivalent as long as each attribute appears exactly once in
the component list.  An attribute listed as a default is not
required to appear in the attribute list, although it is a good
programming practice to specify default attributes.  If all
defaults are desired, the attribute @code{DEFAULT_ATTRIBUTES} should be
specified on this call.  The attribute_set parameter should be
GLOBAL to indicate that the partition is to be known globally.

@ifinfo
@node Partition Manager Operations, Creating a Partition, Building a Partition's Attribute Set, Partition Manager
@end ifinfo
@section Operations
@ifinfo
@menu
* Creating a Partition::
* Obtaining Partition IDs::
* Acquiring a Buffer::
* Releasing a Buffer::
* Deleting a Partition::
@end menu
@end ifinfo

@ifinfo
@node Creating a Partition, Obtaining Partition IDs, Partition Manager Operations, Partition Manager Operations
@end ifinfo
@subsection Creating a Partition

The partition_create directive creates a partition
with a user-specified name.  The partition's name, starting
address, length and buffer size are all specified to the
partition_create directive.  RTEMS allocates a Partition Control
Block (PTCB) from the PTCB free list.  This data structure is
used by RTEMS to manage the newly created partition.  The number
of buffers in the partition is calculated based upon the
specified partition length and buffer size, and returned to the
calling task along with a unique partition ID.

@ifinfo
@node Obtaining Partition IDs, Acquiring a Buffer, Creating a Partition, Partition Manager Operations
@end ifinfo
@subsection Obtaining Partition IDs

When a partition is created, RTEMS generates a unique
partition ID and assigned it to the created partition until it
is deleted.  The partition ID may be obtained by either of two
methods.  First, as the result of an invocation of the
partition_create directive, the partition ID is stored in a user
provided location.  Second, the partition ID may be obtained
later using the partition_ident directive.  The partition ID is
used by other partition manager directives to access this
partition.

@ifinfo
@node Acquiring a Buffer, Releasing a Buffer, Obtaining Partition IDs, Partition Manager Operations
@end ifinfo
@subsection Acquiring a Buffer

A buffer can be obtained by calling the
partition_get_buffer directive.  If a buffer is available, then
it is returned immediately with a successful return code.
Otherwise, an unsuccessful return code is returned immediately
to the caller.  Tasks cannot block to wait for a buffer to
become available.

@ifinfo
@node Releasing a Buffer, Deleting a Partition, Acquiring a Buffer, Partition Manager Operations
@end ifinfo
@subsection Releasing a Buffer

Buffers are returned to a partition's free buffer
chain with the partition_return_buffer directive.  This
directive returns an error status code if the returned buffer
was not previously allocated from this partition.

@ifinfo
@node Deleting a Partition, Partition Manager Directives, Releasing a Buffer, Partition Manager Operations
@end ifinfo
@subsection Deleting a Partition

The partition_delete directive allows a partition to
be removed and returned to RTEMS.  When a partition is deleted,
the PTCB for that partition is returned to the PTCB free list.
A partition with buffers still allocated cannot be deleted.  Any
task attempting to do so will be returned an error status code.

@ifinfo
@node Partition Manager Directives, PARTITION_CREATE - Create a partition, Deleting a Partition, Partition Manager
@end ifinfo
@section Directives
@ifinfo
@menu
* PARTITION_CREATE - Create a partition::
* PARTITION_IDENT - Get ID of a partition::
* PARTITION_DELETE - Delete a partition::
* PARTITION_GET_BUFFER - Get buffer from a partition::
* PARTITION_RETURN_BUFFER - Return buffer to a partition::
@end menu
@end ifinfo

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.

@page
@ifinfo
@node PARTITION_CREATE - Create a partition, PARTITION_IDENT - Get ID of a partition, Partition Manager Directives, Partition Manager Directives
@end ifinfo
@subsection PARTITION_CREATE - Create a partition

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_partition_create(
  rtems_name        name,
  void             *starting_address,
  rtems_unsigned32  length,
  rtems_unsigned32  buffer_size,
  rtems_attribute   attribute_set,
  rtems_id         *id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Partition_Create (
   Name             : in     RTEMS.Name;
   Starting_Address : in     RTEMS.Address;
   Length           : in     RTEMS.Unsigned32;
   Buffer_Size      : in     RTEMS.Unsigned32;
   Attribute_Set    : in     RTEMS.Attribute;
   ID               :    out RTEMS.ID;
   Result           :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{SUCCESSFUL} - partition created successfully@*
@code{INVALID_NAME} - invalid task name@*
@code{TOO_MANY} - too many partitions created@*
@code{INVALID_ADDRESS} - address not on four byte boundary@*
@code{INVALID_SIZE} - length or buffer size is 0@*
@code{INVALID_SIZE} - length is less than the buffer size@*
@code{INVALID_SIZE} - buffer size not a multiple of 4@*
@code{MP_NOT_CONFIGURED} - multiprocessing not configured@*
@code{TOO_MANY} - too many global objects

@subheading 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_length 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.

@subheading NOTES:

This directive will not cause the calling task to be
preempted.

The starting_address and buffer_size parameters must
be multiples of four.

Memory from the partition is not used by RTEMS to
store the Partition Control Block.

The following partition attribute constants are
defined by RTEMS:

@itemize @bullet
@item LOCAL - local task (default)
@item GLOBAL - global task
@end itemize

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.

@page
@ifinfo
@node PARTITION_IDENT - Get ID of a partition, PARTITION_DELETE - Delete a partition, PARTITION_CREATE - Create a partition, Partition Manager Directives
@end ifinfo
@subsection PARTITION_IDENT - Get ID of a partition

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_partition_ident(
  rtems_name        name,
  rtems_unsigned32  node,
  rtems_id         *id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Partition_Ident (
   Name   : in     RTEMS.Name;
   Node   : in     RTEMS.Unsigned32;
   ID     :    out RTEMS.ID;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{SUCCESSFUL} - partition identified successfully@*
@code{INVALID_NAME} - partition name not found@*
@code{INVALID_NODE} - invalid node id

@subheading 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.

@subheading NOTES:

This directive will not cause the running task to be
preempted.

If node is @code{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.

@page
@ifinfo
@node PARTITION_DELETE - Delete a partition, PARTITION_GET_BUFFER - Get buffer from a partition, PARTITION_IDENT - Get ID of a partition, Partition Manager Directives
@end ifinfo
@subsection PARTITION_DELETE - Delete a partition

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_partition_delete(
  rtems_id id
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Partition_Delete (
   ID     : in     RTEMS.ID;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{SUCCESSFUL} - partition deleted successfully@*
@code{INVALID_ID} - invalid partition id@*
@code{RESOURCE_IN_USE} - buffers still in use@*
@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote partition

@subheading 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.

@subheading NOTES:

This directive will not cause the calling task to be
preempted.

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 GLOBAL option.

@page
@ifinfo
@node PARTITION_GET_BUFFER - Get buffer from a partition, PARTITION_RETURN_BUFFER - Return buffer to a partition, PARTITION_DELETE - Delete a partition, Partition Manager Directives
@end ifinfo
@subsection PARTITION_GET_BUFFER - Get buffer from a partition

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_partition_get_buffer(
  rtems_id   id,
  void     **buffer
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Partition_Get_Buffer (
   ID     : in     RTEMS.ID;
   Buffer :    out RTEMS.Address;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{SUCCESSFUL} - buffer obtained successfully@*
@code{INVALID_ID} - invalid partition id@*
@code{UNSATISFIED} - all buffers are allocated

@subheading 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.

@subheading 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.

@page
@ifinfo
@node PARTITION_RETURN_BUFFER - Return buffer to a partition, Region Manager, PARTITION_GET_BUFFER - Get buffer from a partition, Partition Manager Directives
@end ifinfo
@subsection PARTITION_RETURN_BUFFER - Return buffer to a partition

@subheading CALLING SEQUENCE:

@ifset is-C
@example
rtems_status_code rtems_partition_return_buffer(
  rtems_id  id,
  void     *buffer
);
@end example
@end ifset

@ifset is-Ada
@example
procedure Partition_Return_Buffer (
   ID     : in     RTEMS.ID;
   Buffer : in     RTEMS.Address;
   Result :    out RTEMS.Status_Codes
);
@end example
@end ifset

@subheading DIRECTIVE STATUS CODES:
@code{SUCCESSFUL} - buffer returned successfully@*
@code{INVALID_ID} - invalid partition id@*
@code{INVALID_ADDRESS} - buffer address not in partition

@subheading DESCRIPTION:

This directive returns the buffer specified by buffer
to the partition specified by id.

@subheading 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.