diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-08-20 10:00:14 +0200 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-09-02 17:55:31 +0200 |
commit | a4119a9f1ce98f753ac6b9cfa0a5555f7c6a7c5e (patch) | |
tree | b61ec6efe73cddce31651450c00f66bf9081274b /c-user/partition_manager.rst | |
parent | c-user: Split up message manager (diff) | |
download | rtems-docs-a4119a9f1ce98f753ac6b9cfa0a5555f7c6a7c5e.tar.bz2 |
c-user: Split up partition manager
This makes it easier to automatically generate parts of the manager
documentation in the future.
Update #3993.
Diffstat (limited to '')
-rw-r--r-- | c-user/partition/directives.rst (renamed from c-user/partition_manager.rst) | 120 |
1 files changed, 0 insertions, 120 deletions
diff --git a/c-user/partition_manager.rst b/c-user/partition/directives.rst index bc30de2..f81c37f 100644 --- a/c-user/partition_manager.rst +++ b/c-user/partition/directives.rst @@ -2,126 +2,6 @@ .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -.. index:: partitions - -Partition Manager -***************** - -Introduction -============ - -The partition manager provides facilities to dynamically allocate memory in -fixed-size units. The directives provided by the partition manager are: - -- rtems_partition_create_ - Create a partition - -- rtems_partition_ident_ - Get ID of a partition - -- rtems_partition_delete_ - Delete a partition - -- rtems_partition_get_buffer_ - Get buffer from a partition - -- rtems_partition_return_buffer_ - Return buffer to a partition - -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: - -.. list-table:: - :class: rtems-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 ========== |