source: rtems-docs/c-user/partition_manager.rst @ 3384994

5am
Last change on this file since 3384994 was 3384994, checked in by Chris Johns <chrisj@…>, on 11/13/17 at 02:25:18

Clean up sphinx warnings.

  • Fix minor formatting issues.
  • Fix reference the gloassary TLS using ':term:'.
  • Make sure nothing is between an anchor and the heading where ':ref:' references the anchor. This meant moving all the recently added '.. index::' entries.

Update #3232.
Update #3229.

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