From 53bb72e99669750ecbd7a418047711a21e32ac40 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Tue, 8 Nov 2016 15:26:50 +1100 Subject: c-user: Format the directives as descriptions. This change combined with the element list change in latex generates a much better looking PDF. Add a page break before each directive to like th previous versions of the manuals. --- c-user/region_manager.rst | 646 +++++++++++++++++++++++----------------------- 1 file changed, 320 insertions(+), 326 deletions(-) (limited to 'c-user/region_manager.rst') diff --git a/c-user/region_manager.rst b/c-user/region_manager.rst index 699a3a6..c5491cb 100644 --- a/c-user/region_manager.rst +++ b/c-user/region_manager.rst @@ -224,82 +224,83 @@ This section details the region 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 + .. _rtems_region_create: REGION_CREATE - Create a region ------------------------------- .. index:: create a region - -**CALLING SEQUENCE:** - -.. index:: rtems_region_create - -.. code-block:: c - - rtems_status_code rtems_region_create( - rtems_name name, - void *starting_address, - intptr_t length, - uint32_t page_size, - rtems_attribute attribute_set, - rtems_id *id - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - region created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid region name - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``starting_address`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - address not on four byte boundary - * - ``RTEMS_TOO_MANY`` - - too many regions created - * - ``RTEMS_INVALID_SIZE`` - - invalid page size - -**DESCRIPTION:** - -This directive creates a region from a physically contiguous memory space which -starts at starting_address and is length bytes long. Segments allocated from -the region will be a multiple of page_size bytes in length. The assigned -region id is returned in id. This region id is used as an argument to other -region related directives to access the region. - -For control and maintenance of the region, RTEMS allocates and initializes an -RNCB from the RNCB free pool. Thus memory from the region is not used to store -the RNCB. However, some overhead within the region is required by RTEMS each -time a segment is constructed in the region. - -Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a -segment to be serviced according to task priority. Specifying ``RTEMS_FIFO`` -in attribute_set or selecting ``RTEMS_DEFAULT_ATTRIBUTES`` will cause waiting -tasks to be serviced in First In-First Out order. - -The ``starting_address`` parameter must be aligned on a four byte boundary. -The ``page_size`` parameter must be a multiple of four greater than or equal to -eight. - -**NOTES:** - -This directive will not cause the calling task to be preempted. - -The following region attribute constants are defined by RTEMS: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_FIFO`` - - tasks wait by FIFO (default) - * - ``RTEMS_PRIORITY`` - - tasks wait by priority +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_region_create( + rtems_name name, + void *starting_address, + intptr_t length, + uint32_t page_size, + rtems_attribute attribute_set, + rtems_id *id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - region created successfully + * - ``RTEMS_INVALID_NAME`` + - invalid region name + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``starting_address`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - address not on four byte boundary + * - ``RTEMS_TOO_MANY`` + - too many regions created + * - ``RTEMS_INVALID_SIZE`` + - invalid page size + +DESCRIPTION: + This directive creates a region from a physically contiguous memory space + which starts at starting_address and is length bytes long. Segments + allocated from the region will be a multiple of page_size bytes in length. + The assigned region id is returned in id. This region id is used as an + argument to other region related directives to access the region. + + For control and maintenance of the region, RTEMS allocates and initializes + an RNCB from the RNCB free pool. Thus memory from the region is not used + to store the RNCB. However, some overhead within the region is required by + RTEMS each time a segment is constructed in the region. + + Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a + segment to be serviced according to task priority. Specifying + ``RTEMS_FIFO`` in attribute_set or selecting ``RTEMS_DEFAULT_ATTRIBUTES`` + will cause waiting tasks to be serviced in First In-First Out order. + + The ``starting_address`` parameter must be aligned on a four byte boundary. + The ``page_size`` parameter must be a multiple of four greater than or + equal to eight. + +NOTES: + This directive will not cause the calling task to be preempted. + + The following region attribute constants are defined by RTEMS: + + .. list-table:: + :class: rtems-table + + * - ``RTEMS_FIFO`` + - tasks wait by FIFO (default) + * - ``RTEMS_PRIORITY`` + - tasks wait by priority + +.. raw:: latex + + \clearpage .. _rtems_region_ident: @@ -307,82 +308,81 @@ REGION_IDENT - Get ID of a region --------------------------------- .. index:: get ID of a region .. index:: obtain ID of a region - -**CALLING SEQUENCE:** - .. index:: rtems_region_ident -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_region_ident( - rtems_name name, - rtems_id *id - ); + rtems_status_code rtems_region_ident( + rtems_name name, + rtems_id *id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - region identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - region name not found - * - ``RTEMS_SUCCESSFUL`` - - region identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - region name not found +DESCRIPTION: -**DESCRIPTION:** + This directive obtains the region id associated with the region name to be + acquired. If the region name is not unique, then the region id will match + one of the regions with that name. However, this region id is not + guaranteed to correspond to the desired region. The region id is used to + access this region in other region manager directives. -This directive obtains the region id associated with the region name to be -acquired. If the region name is not unique, then the region id will match one -of the regions with that name. However, this region id is not guaranteed to -correspond to the desired region. The region id is used to access this region -in other region manager directives. +NOTES: + This directive will not cause the running task to be preempted. -**NOTES:** +.. raw:: latex -This directive will not cause the running task to be preempted. + \clearpage .. _rtems_region_delete: REGION_DELETE - Delete a region ------------------------------- .. index:: delete a region - -**CALLING SEQUENCE:** - .. index:: rtems_region_delete -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_region_delete( - rtems_id id - ); + rtems_status_code rtems_region_delete( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - region deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_RESOURCE_IN_USE`` - - segments still in use + * - ``RTEMS_SUCCESSFUL`` + - region deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid region id + * - ``RTEMS_RESOURCE_IN_USE`` + - segments still in use -**DESCRIPTION:** +DESCRIPTION: + This directive deletes the region specified by id. The region cannot be + deleted if any of its segments are still allocated. The RNCB for the + deleted region is reclaimed by RTEMS. -This directive deletes the region specified by id. The region cannot be -deleted if any of its segments are still allocated. The RNCB for the deleted -region is reclaimed by RTEMS. +NOTES: + This directive will not cause the calling task to be preempted. -**NOTES:** + The calling task does not have to be the task that created the region. Any + local task that knows the region id can delete the region. -This directive will not cause the calling task to be preempted. +.. raw:: latex -The calling task does not have to be the task that created the region. Any -local task that knows the region id can delete the region. + \clearpage .. _rtems_region_extend: @@ -390,266 +390,260 @@ REGION_EXTEND - Add memory to a region -------------------------------------- .. index:: add memory to a region .. index:: region, add memory - -**CALLING SEQUENCE:** - .. index:: rtems_region_extend -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_region_extend( - rtems_id id, - void *starting_address, - intptr_t length - ); + rtems_status_code rtems_region_extend( + rtems_id id, + void *starting_address, + intptr_t length + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - region extended successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``starting_address`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid region id + * - ``RTEMS_INVALID_ADDRESS`` + - invalid address of area to add - * - ``RTEMS_SUCCESSFUL`` - - region extended successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``starting_address`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_ADDRESS`` - - invalid address of area to add +DESCRIPTION: + This directive adds the memory which starts at starting_address for length + bytes to the region specified by id. -**DESCRIPTION:** +NOTES: + This directive will not cause the calling task to be preempted. -This directive adds the memory which starts at starting_address for length -bytes to the region specified by id. + The calling task does not have to be the task that created the region. Any + local task that knows the region id can extend the region. -**NOTES:** +.. raw:: latex -This directive will not cause the calling task to be preempted. - -The calling task does not have to be the task that created the region. Any -local task that knows the region id can extend the region. + \clearpage .. _rtems_region_get_segment: REGION_GET_SEGMENT - Get segment from a region ---------------------------------------------- .. index:: get segment from region - -**CALLING SEQUENCE:** - .. index:: rtems_region_get_segment -.. code-block:: c - - rtems_status_code rtems_region_get_segment( - rtems_id id, - intptr_t size, - rtems_option option_set, - rtems_interval timeout, - void **segment - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - segment obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``segment`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_SIZE`` - - request is for zero bytes or exceeds the size of maximum segment which is - possible for this region - * - ``RTEMS_UNSATISFIED`` - - segment of requested size not available - * - ``RTEMS_TIMEOUT`` - - timed out waiting for segment - * - ``RTEMS_OBJECT_WAS_DELETED`` - - region deleted while waiting - -**DESCRIPTION:** - -This directive obtains a variable size segment from the region specified by -``id``. The address of the allocated segment is returned in segment. The -``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` components of the options parameter are -used to specify whether the calling tasks wish to wait for a segment to become -available or return immediately if no segment is available. For either option, -if a sufficiently sized segment is available, then the segment is successfully -acquired by returning immediately with the ``RTEMS_SUCCESSFUL`` status code. - -If the calling task chooses to return immediately and a segment large enough is -not available, then an error code indicating this fact is returned. If the -calling task chooses to wait for the segment and a segment large enough is not -available, then the calling task is placed on the region's segment wait queue -and blocked. If the region was created with the ``RTEMS_PRIORITY`` option, -then the calling task is inserted into the wait queue according to its -priority. However, if the region was created with the ``RTEMS_FIFO`` option, -then the calling task is placed at the rear of the wait queue. - -The timeout parameter specifies the maximum interval that a task is willing to -wait to obtain a segment. If timeout is set to ``RTEMS_NO_TIMEOUT``, then the -calling task will wait forever. - -**NOTES:** - -The actual length of the allocated segment may be larger than the requested -size because a segment size is always a multiple of the region's page size. - -The following segment acquisition option constants are defined by RTEMS: - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_WAIT`` - - task will wait for segment (default) - * - ``RTEMS_NO_WAIT`` - - task should not wait - -A clock tick is required to support the timeout functionality of this -directive. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_region_get_segment( + rtems_id id, + intptr_t size, + rtems_option option_set, + rtems_interval timeout, + void **segment + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - segment obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``segment`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid region id + * - ``RTEMS_INVALID_SIZE`` + - request is for zero bytes or exceeds the size of maximum segment which is + possible for this region + * - ``RTEMS_UNSATISFIED`` + - segment of requested size not available + * - ``RTEMS_TIMEOUT`` + - timed out waiting for segment + * - ``RTEMS_OBJECT_WAS_DELETED`` + - region deleted while waiting + +DESCRIPTION: + This directive obtains a variable size segment from the region specified by + ``id``. The address of the allocated segment is returned in segment. The + ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` components of the options parameter + are used to specify whether the calling tasks wish to wait for a segment to + become available or return immediately if no segment is available. For + either option, if a sufficiently sized segment is available, then the + segment is successfully acquired by returning immediately with the + ``RTEMS_SUCCESSFUL`` status code. + + If the calling task chooses to return immediately and a segment large + enough is not available, then an error code indicating this fact is + returned. If the calling task chooses to wait for the segment and a + segment large enough is not available, then the calling task is placed on + the region's segment wait queue and blocked. If the region was created + with the ``RTEMS_PRIORITY`` option, then the calling task is inserted into + the wait queue according to its priority. However, if the region was + created with the ``RTEMS_FIFO`` option, then the calling task is placed at + the rear of the wait queue. + + The timeout parameter specifies the maximum interval that a task is willing + to wait to obtain a segment. If timeout is set to ``RTEMS_NO_TIMEOUT``, + then the calling task will wait forever. + +NOTES: + The actual length of the allocated segment may be larger than the requested + size because a segment size is always a multiple of the region's page size. + + The following segment acquisition option constants are defined by RTEMS: + + .. list-table:: + :class: rtems-table + + * - ``RTEMS_WAIT`` + - task will wait for segment (default) + * - ``RTEMS_NO_WAIT`` + - task should not wait + + A clock tick is required to support the timeout functionality of this + directive. + +.. raw:: latex + + \clearpage .. _rtems_region_return_segment: REGION_RETURN_SEGMENT - Return segment to a region -------------------------------------------------- .. index:: return segment to region - -**CALLING SEQUENCE:** - .. index:: rtems_region_return_segment -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_region_return_segment( - rtems_id id, - void *segment - ); + rtems_status_code rtems_region_return_segment( + rtems_id id, + void *segment + ); -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - segment returned successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``segment`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_ADDRESS`` - - segment address not in region + * - ``RTEMS_SUCCESSFUL`` + - segment returned successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``segment`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid region id + * - ``RTEMS_INVALID_ADDRESS`` + - segment address not in region -**DESCRIPTION:** +DESCRIPTION: + This directive returns the segment specified by segment to the region + specified by id. The returned segment is merged with its neighbors to form + the largest possible segment. The first task on the wait queue is examined + to determine if its segment request can now be satisfied. If so, it is + given a segment and unblocked. This process is repeated until the first + task's segment request cannot be satisfied. -This directive returns the segment specified by segment to the region specified -by id. The returned segment is merged with its neighbors to form the largest -possible segment. The first task on the wait queue is examined to determine if -its segment request can now be satisfied. If so, it is given a segment and -unblocked. This process is repeated until the first task's segment request -cannot be satisfied. +NOTES: + This directive will cause the calling task to be preempted if one or more + local tasks are waiting for a segment and the following conditions exist: -**NOTES:** + - a waiting task has a higher priority than the calling task -This directive will cause the calling task to be preempted if one or more local -tasks are waiting for a segment and the following conditions exist: + - the size of the segment required by the waiting task is less than or + equal to the size of the segment returned. -- a waiting task has a higher priority than the calling task +.. raw:: latex -- the size of the segment required by the waiting task is less than or equal to - the size of the segment returned. + \clearpage .. _rtems_region_get_segment_size: REGION_GET_SEGMENT_SIZE - Obtain size of a segment -------------------------------------------------- .. index:: get size of segment - -**CALLING SEQUENCE:** - .. index:: rtems_region_get_segment_size -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_region_get_segment_size( - rtems_id id, - void *segment, - ssize_t *size - ); + rtems_status_code rtems_region_get_segment_size( + rtems_id id, + void *segment, + ssize_t *size + ); -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - segment obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``segment`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``size`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_ADDRESS`` - - segment address not in region + * - ``RTEMS_SUCCESSFUL`` + - segment obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``segment`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``size`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid region id + * - ``RTEMS_INVALID_ADDRESS`` + - segment address not in region -**DESCRIPTION:** +DESCRIPTION: + This directive obtains the size in bytes of the specified segment. -This directive obtains the size in bytes of the specified segment. +NOTES: + The actual length of the allocated segment may be larger than the requested + size because a segment size is always a multiple of the region's page size. -**NOTES:** +.. raw:: latex -The actual length of the allocated segment may be larger than the requested -size because a segment size is always a multiple of the region's page size. + \clearpage .. _rtems_region_resize_segment: REGION_RESIZE_SEGMENT - Change size of a segment ------------------------------------------------ .. index:: resize segment - -**CALLING SEQUENCE:** - .. index:: rtems_region_resize_segment -.. code-block:: c - - rtems_status_code rtems_region_resize_segment( - rtems_id id, - void *segment, - ssize_t size, - ssize_t *old_size - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - segment obtained successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``segment`` is NULL - * - ``RTEMS_INVALID_ADDRESS`` - - ``old_size`` is NULL - * - ``RTEMS_INVALID_ID`` - - invalid region id - * - ``RTEMS_INVALID_ADDRESS`` - - segment address not in region - * - ``RTEMS_UNSATISFIED`` - - unable to make segment larger - -**DESCRIPTION:** - -This directive is used to increase or decrease the size of a segment. When -increasing the size of a segment, it is possible that there is not memory -available contiguous to the segment. In this case, the request is unsatisfied. - -**NOTES:** - -If an attempt to increase the size of a segment fails, then the application may -want to allocate a new segment of the desired size, copy the contents of the -original segment to the new, larger segment and then return the original -segment. +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_region_resize_segment( + rtems_id id, + void *segment, + ssize_t size, + ssize_t *old_size + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - segment obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``segment`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``old_size`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid region id + * - ``RTEMS_INVALID_ADDRESS`` + - segment address not in region + * - ``RTEMS_UNSATISFIED`` + - unable to make segment larger + +DESCRIPTION: + This directive is used to increase or decrease the size of a segment. When + increasing the size of a segment, it is possible that there is not memory + available contiguous to the segment. In this case, the request is + unsatisfied. + +NOTES: + If an attempt to increase the size of a segment fails, then the application + may want to allocate a new segment of the desired size, copy the contents + of the original segment to the new, larger segment and then return the + original segment. -- cgit v1.2.3