source: rtems/doc/user/part.t @ 014d541f

4.8
Last change on this file since 014d541f was 014d541f, checked in by Joel Sherrill <joel.sherrill@…>, on Aug 4, 2008 at 8:45:31 PM

2008-08-04 Joel Sherrill <joel.sherrill@…>

PR 1263/doc

  • user/part.t: Improve discussion of alignment and minimum buffer sizes.
  • Property mode set to 100644
File size: 13.8 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2008.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Partition Manager
10
11@cindex partitions
12
13@section Introduction
14
15The partition manager provides facilities to
16dynamically allocate memory in fixed-size units.  The directives
17provided by the partition manager are:
18
19@itemize @bullet
20@item @code{@value{DIRPREFIX}partition_create} - Create a partition
21@item @code{@value{DIRPREFIX}partition_ident} - Get ID of a partition
22@item @code{@value{DIRPREFIX}partition_delete} - Delete a partition
23@item @code{@value{DIRPREFIX}partition_get_buffer} - Get buffer from a partition
24@item @code{@value{DIRPREFIX}partition_return_buffer} - Return buffer to a partition
25@end itemize
26
27@section Background
28
29@subsection Partition Manager Definitions
30
31@cindex partition, definition
32
33A partition is a physically contiguous memory area
34divided into fixed-size buffers that can be dynamically
35allocated and deallocated.
36
37@cindex buffers, definition
38
39Partitions are managed and maintained as a list of
40buffers.  Buffers are obtained from the front of the partition's
41free buffer chain and returned to the rear of the same chain.
42When a buffer is on the free buffer chain, RTEMS uses two
43pointers of memory from each buffer as the free buffer chain. 
44When a buffer is allocated, the entire buffer is available for application use.
45Therefore, modifying memory that is outside of an allocated
46buffer could destroy the free buffer chain or the contents of an
47adjacent allocated buffer.
48
49@subsection Building a Partition Attribute Set
50
51@cindex partition attribute set, building
52
53In general, an attribute set is built by a bitwise OR
54of the desired attribute components.  The set of valid partition
55attributes is provided in the following table:
56
57@itemize @bullet
58@item @code{@value{RPREFIX}LOCAL} - local task (default)
59@item @code{@value{RPREFIX}GLOBAL} - global task
60@end itemize
61
62Attribute values are specifically designed to be
63mutually exclusive, therefore bitwise OR and addition operations
64are equivalent as long as each attribute appears exactly once in
65the component list.  An attribute listed as a default is not
66required to appear in the attribute list, although it is a good
67programming practice to specify default attributes.  If all
68defaults are desired, the attribute
69@code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be
70specified on this call.  The attribute_set parameter should be
71@code{@value{RPREFIX}GLOBAL} to indicate that the partition
72is to be known globally.
73
74@section Operations
75
76@subsection Creating a Partition
77
78The @code{@value{DIRPREFIX}partition_create} directive creates a partition
79with a user-specified name.  The partition's name, starting
80address, length and buffer size are all specified to the
81@code{@value{DIRPREFIX}partition_create} directive. 
82RTEMS allocates a Partition Control
83Block (PTCB) from the PTCB free list.  This data structure is
84used by RTEMS to manage the newly created partition.  The number
85of buffers in the partition is calculated based upon the
86specified partition length and buffer size, and returned to the
87calling task along with a unique partition ID.
88
89@subsection Obtaining Partition IDs
90
91When a partition is created, RTEMS generates a unique
92partition ID and assigned it to the created partition until it
93is deleted.  The partition ID may be obtained by either of two
94methods.  First, as the result of an invocation of the
95@code{@value{DIRPREFIX}partition_create} directive, the partition
96ID is stored in a user provided location.  Second, the partition
97ID may be obtained later using the @code{@value{DIRPREFIX}partition_ident}
98directive.  The partition ID is used by other partition manager directives
99to access this partition.
100
101@subsection Acquiring a Buffer
102
103A buffer can be obtained by calling the
104@code{@value{DIRPREFIX}partition_get_buffer} directive. 
105If a buffer is available, then
106it is returned immediately with a successful return code.
107Otherwise, an unsuccessful return code is returned immediately
108to the caller.  Tasks cannot block to wait for a buffer to
109become available.
110
111@subsection Releasing a Buffer
112
113Buffers are returned to a partition's free buffer
114chain with the @code{@value{DIRPREFIX}partition_return_buffer} directive.  This
115directive returns an error status code if the returned buffer
116was not previously allocated from this partition.
117
118@subsection Deleting a Partition
119
120The @code{@value{DIRPREFIX}partition_delete} directive allows a partition to
121be removed and returned to RTEMS.  When a partition is deleted,
122the PTCB for that partition is returned to the PTCB free list.
123A partition with buffers still allocated cannot be deleted.  Any
124task attempting to do so will be returned an error status code.
125
126@section Directives
127
128This section details the partition manager's
129directives.  A subsection is dedicated to each of this manager's
130directives and describes the calling sequence, related
131constants, usage, and status codes.
132
133@c
134@c
135@c
136@page
137@subsection PARTITION_CREATE - Create a partition
138
139@cindex create a partition
140
141@subheading CALLING SEQUENCE:
142
143@ifset is-C
144@findex rtems_partition_create
145@example
146rtems_status_code rtems_partition_create(
147  rtems_name       name,
148  void            *starting_address,
149  uint32_t         length,
150  uint32_t         buffer_size,
151  rtems_attribute  attribute_set,
152  rtems_id        *id
153);
154@end example
155@end ifset
156
157@ifset is-Ada
158@example
159procedure Partition_Create (
160   Name             : in     RTEMS.Name;
161   Starting_Address : in     RTEMS.Address;
162   Length           : in     RTEMS.Unsigned32;
163   Buffer_Size      : in     RTEMS.Unsigned32;
164   Attribute_Set    : in     RTEMS.Attribute;
165   ID               :    out RTEMS.ID;
166   Result           :    out RTEMS.Status_Codes
167);
168@end example
169@end ifset
170
171@subheading DIRECTIVE STATUS CODES:
172@code{@value{RPREFIX}SUCCESSFUL} - partition created successfully@*
173@code{@value{RPREFIX}INVALID_NAME} - invalid partition name@*
174@code{@value{RPREFIX}TOO_MANY} - too many partitions created@*
175@code{@value{RPREFIX}INVALID_ADDRESS} - address not on four byte boundary@*
176@code{@value{RPREFIX}INVALID_ADDRESS} - @code{starting_address} is NULL@*
177@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
178@code{@value{RPREFIX}INVALID_SIZE} - length or buffer size is 0@*
179@code{@value{RPREFIX}INVALID_SIZE} - length is less than the buffer size@*
180@code{@value{RPREFIX}INVALID_SIZE} - buffer size not a multiple of 4@*
181@code{@value{RPREFIX}MP_NOT_CONFIGURED} - multiprocessing not configured@*
182@code{@value{RPREFIX}TOO_MANY} - too many global objects
183
184@subheading DESCRIPTION:
185
186This directive creates a partition of fixed size
187buffers from a physically contiguous memory space which starts
188at starting_address and is length bytes in size.  Each allocated
189buffer is to be of @code{buffer_size} in bytes.  The assigned
190partition id is returned in @code{id}.  This partition id is used to
191access the partition with other partition related directives.
192For control and maintenance of the partition, RTEMS allocates a
193PTCB from the local PTCB free pool and initializes it.
194
195@subheading NOTES:
196
197This directive will not cause the calling task to be
198preempted.
199
200The @code{starting_address} must be properly aligned for the
201target architecture.
202
203Th @code{buffer_size} parameter must be a multiple of
204the CPU alignment factor.  Additionally, @code{buffer_size}
205must be large enough to hold two pointers on the target
206architecture.  This is required for RTEMS to manage the
207buffers when they are free.
208
209Memory from the partition is not used by RTEMS to
210store the Partition Control Block.
211
212The following partition attribute constants are
213defined by RTEMS:
214
215@itemize @bullet
216@item @code{@value{RPREFIX}LOCAL} - local task (default)
217@item @code{@value{RPREFIX}GLOBAL} - global task
218@end itemize
219
220The PTCB for a global partition is allocated on the
221local node.  The memory space used for the partition must reside
222in shared memory. Partitions should not be made global unless
223remote tasks must interact with the partition.  This is to avoid
224the overhead incurred by the creation of a global partition.
225When a global partition is created, the partition's name and id
226must be transmitted to every node in the system for insertion in
227the local copy of the global object table.
228
229The total number of global objects, including
230partitions, is limited by the maximum_global_objects field in
231the Configuration Table.
232
233@c
234@c
235@c
236@page
237@subsection PARTITION_IDENT - Get ID of a partition
238
239@cindex get ID of a partition
240@cindex obtain ID of a partition
241
242@subheading CALLING SEQUENCE:
243
244@ifset is-C
245@findex rtems_partition_ident
246@example
247rtems_status_code rtems_partition_ident(
248  rtems_name  name,
249  uint32_t    node,
250  rtems_id   *id
251);
252@end example
253@end ifset
254
255@ifset is-Ada
256@example
257procedure Partition_Ident (
258   Name   : in     RTEMS.Name;
259   Node   : in     RTEMS.Unsigned32;
260   ID     :    out RTEMS.ID;
261   Result :    out RTEMS.Status_Codes
262);
263@end example
264@end ifset
265
266@subheading DIRECTIVE STATUS CODES:
267@code{@value{RPREFIX}SUCCESSFUL} - partition identified successfully@*
268@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
269@code{@value{RPREFIX}INVALID_NAME} - partition name not found@*
270@code{@value{RPREFIX}INVALID_NODE} - invalid node id
271
272@subheading DESCRIPTION:
273
274This directive obtains the partition id associated
275with the partition name.  If the partition name is not unique,
276then the partition id will match one of the partitions with that
277name.  However, this partition id is not guaranteed to
278correspond to the desired partition.  The partition id is used
279with other partition related directives to access the partition.
280
281@subheading NOTES:
282
283This directive will not cause the running task to be
284preempted.
285
286If node is @code{@value{RPREFIX}SEARCH_ALL_NODES}, all nodes are searched
287with the local node being searched first.  All other nodes are
288searched with the lowest numbered node searched first.
289
290If node is a valid node number which does not
291represent the local node, then only the partitions exported by
292the designated node are searched.
293
294This directive does not generate activity on remote
295nodes.  It accesses only the local copy of the global object
296table.
297
298@c
299@c
300@c
301@page
302@subsection PARTITION_DELETE - Delete a partition
303
304@cindex delete a partition
305
306@subheading CALLING SEQUENCE:
307
308@ifset is-C
309@findex rtems_partition_delete
310@example
311rtems_status_code rtems_partition_delete(
312  rtems_id id
313);
314@end example
315@end ifset
316
317@ifset is-Ada
318@example
319procedure Partition_Delete (
320   ID     : in     RTEMS.ID;
321   Result :    out RTEMS.Status_Codes
322);
323@end example
324@end ifset
325
326@subheading DIRECTIVE STATUS CODES:
327@code{@value{RPREFIX}SUCCESSFUL} - partition deleted successfully@*
328@code{@value{RPREFIX}INVALID_ID} - invalid partition id@*
329@code{@value{RPREFIX}RESOURCE_IN_USE} - buffers still in use@*
330@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote partition
331
332@subheading DESCRIPTION:
333
334This directive deletes the partition specified by id.
335The partition cannot be deleted if any of its buffers are still
336allocated.  The PTCB for the deleted partition is reclaimed by
337RTEMS.
338
339@subheading NOTES:
340
341This directive will not cause the calling task to be
342preempted.
343
344The calling task does not have to be the task that
345created the partition.  Any local task that knows the partition
346id can delete the partition.
347
348When a global partition is deleted, the partition id
349must be transmitted to every node in the system for deletion
350from the local copy of the global object table.
351
352The partition must reside on the local node, even if
353the partition was created with the @code{@value{RPREFIX}GLOBAL} option.
354
355@c
356@c
357@c
358@page
359@subsection PARTITION_GET_BUFFER - Get buffer from a partition
360
361@cindex get buffer from partition
362@cindex obtain buffer from partition
363
364@subheading CALLING SEQUENCE:
365
366@ifset is-C
367@findex rtems_partition_get_buffer
368@example
369rtems_status_code rtems_partition_get_buffer(
370  rtems_id   id,
371  void     **buffer
372);
373@end example
374@end ifset
375
376@ifset is-Ada
377@example
378procedure Partition_Get_Buffer (
379   ID     : in     RTEMS.ID;
380   Buffer :    out RTEMS.Address;
381   Result :    out RTEMS.Status_Codes
382);
383@end example
384@end ifset
385
386@subheading DIRECTIVE STATUS CODES:
387@code{@value{RPREFIX}SUCCESSFUL} - buffer obtained successfully@*
388@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@*
389@code{@value{RPREFIX}INVALID_ID} - invalid partition id@*
390@code{@value{RPREFIX}UNSATISFIED} - all buffers are allocated
391
392@subheading DESCRIPTION:
393
394This directive allows a buffer to be obtained from
395the partition specified in id.  The address of the allocated
396buffer is returned in buffer.
397
398@subheading NOTES:
399
400This directive will not cause the running task to be
401preempted.
402
403All buffers begin on a four byte boundary.
404
405A task cannot wait on a buffer to become available.
406
407Getting a buffer from a global partition which does
408not reside on the local node will generate a request telling the
409remote node to allocate a buffer from the specified partition.
410
411@c
412@c
413@c
414@page
415@subsection PARTITION_RETURN_BUFFER - Return buffer to a partition
416
417@cindex return buffer to partitition
418
419@subheading CALLING SEQUENCE:
420
421@ifset is-C
422@findex rtems_partition_return_buffer
423@example
424rtems_status_code rtems_partition_return_buffer(
425  rtems_id  id,
426  void     *buffer
427);
428@end example
429@end ifset
430
431@ifset is-Ada
432@example
433procedure Partition_Return_Buffer (
434   ID     : in     RTEMS.ID;
435   Buffer : in     RTEMS.Address;
436   Result :    out RTEMS.Status_Codes
437);
438@end example
439@end ifset
440
441@subheading DIRECTIVE STATUS CODES:
442@code{@value{RPREFIX}SUCCESSFUL} - buffer returned successfully@*
443@code{@value{RPREFIX}INVALID_ADDRESS} - @code{buffer} is NULL@*
444@code{@value{RPREFIX}INVALID_ID} - invalid partition id@*
445@code{@value{RPREFIX}INVALID_ADDRESS} - buffer address not in partition
446
447@subheading DESCRIPTION:
448
449This directive returns the buffer specified by buffer
450to the partition specified by id.
451
452@subheading NOTES:
453
454This directive will not cause the running task to be
455preempted.
456
457Returning a buffer to a global partition which does
458not reside on the local node will generate a request telling the
459remote node to return the buffer to the specified partition.
Note: See TracBrowser for help on using the repository browser.