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

5am
Last change on this file since a0e6488 was a0e6488, checked in by Sebastian Huber <sebastian.huber@…>, on Aug 2, 2018 at 1:25:43 PM

c-user: Update partition create documentation

Add an example.

Close #3482.

  • Property mode set to 100644
File size: 14.9 KB

Partition Manager

?
.. index:: partitions

Introduction

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

Background

?
.. index:: partition, definition

Partition Manager Definitions

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

?
.. index:: buffers, definition

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 two pointers of memory from 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.

?
.. index:: partition attribute set, building

Building a Partition 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:

RTEMS_LOCAL local partition (default)
RTEMS_GLOBAL global partition

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 RTEMS_DEFAULT_ATTRIBUTES should be specified on this call. The attribute_set parameter should be RTEMS_GLOBAL to indicate that the partition is to be known globally.

Operations

Creating a Partition

The rtems_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 rtems_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. If successful,the unique partition ID is returned to the calling task.

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 rtems_partition_create directive, the partition ID is stored in a user provided location. Second, the partition ID may be obtained later using the rtems_partition_ident directive. The partition ID is used by other partition manager directives to access this partition.

Acquiring a Buffer

A buffer can be obtained by calling the rtems_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.

Releasing a Buffer

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

Deleting a Partition

The rtems_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.

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

PARTITION_CREATE - Create a partition

CALLING SEQUENCE:
rtems_status_code rtems_partition_create(
    rtems_name       name,
    void            *starting_address,
    uint32_t         length,
    uint32_t         buffer_size,
    rtems_attribute  attribute_set,
    rtems_id        *id
);
DIRECTIVE STATUS CODES:
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_MP_NOT_CONFIGURED multiprocessing not configured
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 will not cause the calling task to be preempted.

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:

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:
#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

PARTITION_IDENT - Get ID of a partition

CALLING SEQUENCE:
rtems_status_code rtems_partition_ident(
    rtems_name  name,
    uint32_t    node,
    rtems_id   *id
);
DIRECTIVE STATUS CODES:
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

PARTITION_DELETE - Delete a partition

CALLING SEQUENCE:
rtems_status_code rtems_partition_delete(
    rtems_id id
);
DIRECTIVE STATUS CODES:
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 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 RTEMS_GLOBAL option.

?
.. raw:: latex
   \clearpage
?
.. index:: get buffer from partition
?
.. index:: obtain buffer from partition
?
.. index:: rtems_partition_get_buffer

PARTITION_GET_BUFFER - Get buffer from a partition

CALLING SEQUENCE:
rtems_status_code rtems_partition_get_buffer(
    rtems_id   id,
    void     **buffer
);
DIRECTIVE STATUS CODES:
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

PARTITION_RETURN_BUFFER - Return buffer to a partition

CALLING SEQUENCE:
rtems_status_code rtems_partition_return_buffer(
    rtems_id  id,
    void     *buffer
);
DIRECTIVE STATUS CODES:
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.

Note: See TracBrowser for help on using the repository browser.