diff options
Diffstat (limited to 'doc/user/part.t')
-rw-r--r-- | doc/user/part.t | 423 |
1 files changed, 423 insertions, 0 deletions
diff --git a/doc/user/part.t b/doc/user/part.t new file mode 100644 index 0000000000..302f426497 --- /dev/null +++ b/doc/user/part.t @@ -0,0 +1,423 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@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 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: + +@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 + +@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: + +@example +rtems_status_code rtems_partition_ident( + rtems_name name, + rtems_unsigned32 node, + rtems_id *id +); +@end example + +@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 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: + +@example +rtems_status_code rtems_partition_delete( + rtems_id id +); +@end example + +@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: + +@example +rtems_status_code rtems_partition_get_buffer( + rtems_id id, + void **buffer +); +@end example + +@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: + +@example +rtems_status_code rtems_partition_return_buffer( + rtems_id id, + void *buffer +); +@end example + +@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. |