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/dual_ports_memory_manager.rst | 270 +++++++++++++++++------------------ 1 file changed, 133 insertions(+), 137 deletions(-) (limited to 'c-user/dual_ports_memory_manager.rst') diff --git a/c-user/dual_ports_memory_manager.rst b/c-user/dual_ports_memory_manager.rst index 0502e42..7af67c6 100644 --- a/c-user/dual_ports_memory_manager.rst +++ b/c-user/dual_ports_memory_manager.rst @@ -94,59 +94,62 @@ This section details the dual-ported memory 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_port_create: PORT_CREATE - Create a port --------------------------- .. index:: create a port - -**CALLING SEQUENCE:** - .. index:: rtems_port_create -.. code-block:: c - - rtems_status_code rtems_port_create( - rtems_name name, - void *internal_start, - void *external_start, - uint32_t length, - rtems_id *id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_port_create( + rtems_name name, + void *internal_start, + void *external_start, + uint32_t length, + rtems_id *id + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - port created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid port name - * - ``RTEMS_INVALID_ADDRESS`` - - address not on four byte boundary - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_TOO_MANY`` - - too many DP memory areas created + * - ``RTEMS_SUCCESSFUL`` + - port created successfully + * - ``RTEMS_INVALID_NAME`` + - invalid port name + * - ``RTEMS_INVALID_ADDRESS`` + - address not on four byte boundary + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_TOO_MANY`` + - too many DP memory areas created -**DESCRIPTION:** +DESCRIPTION: + This directive creates a port which resides on the local node for the + specified DPMA. The assigned port id is returned in id. This port id is + used as an argument to other dual-ported memory manager directives to + convert addresses within this DPMA. -This directive creates a port which resides on the local node for the specified -DPMA. The assigned port id is returned in id. This port id is used as an -argument to other dual-ported memory manager directives to convert addresses -within this DPMA. + For control and maintenance of the port, RTEMS allocates and initializes an + DPCB from the DPCB free pool. Thus memory from the dual-ported memory area + is not used to store the DPCB. -For control and maintenance of the port, RTEMS allocates and initializes an -DPCB from the DPCB free pool. Thus memory from the dual-ported memory area is -not used to store the DPCB. +NOTES: + The internal_address and external_address parameters must be on a four byte + boundary. -**NOTES:** + This directive will not cause the calling task to be preempted. -The internal_address and external_address parameters must be on a four byte -boundary. +.. raw:: latex -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_port_ident: @@ -154,158 +157,151 @@ PORT_IDENT - Get ID of a port ----------------------------- .. index:: get ID of a port .. index:: obtain ID of a port - -**CALLING SEQUENCE:** - .. index:: rtems_port_ident -.. code-block:: c - - rtems_status_code rtems_port_ident( - rtems_name name, - rtems_id *id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_port_ident( + rtems_name name, + rtems_id *id + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - port identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - port name not found + * - ``RTEMS_SUCCESSFUL`` + - port identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - port name not found -**DESCRIPTION:** +DESCRIPTION: + This directive obtains the port id associated with the specified name to be + acquired. If the port name is not unique, then the port id will match one + of the DPMAs with that name. However, this port id is not guaranteed to + correspond to the desired DPMA. The port id is used to access this DPMA in + other dual-ported memory area related directives. -This directive obtains the port id associated with the specified name to be -acquired. If the port name is not unique, then the port id will match one of -the DPMAs with that name. However, this port id is not guaranteed to -correspond to the desired DPMA. The port id is used to access this DPMA in -other dual-ported memory area related 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_port_delete: PORT_DELETE - Delete a port --------------------------- .. index:: delete a port - -**CALLING SEQUENCE:** - .. index:: rtems_port_delete -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_port_delete( - rtems_id id - ); + rtems_status_code rtems_port_delete( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_SUCCESSFUL`` + - port deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid port id - * - ``RTEMS_SUCCESSFUL`` - - port deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid port id +DESCRIPTION: + This directive deletes the dual-ported memory area specified by id. The + DPCB for the deleted dual-ported memory area is reclaimed by RTEMS. -**DESCRIPTION:** +NOTES: + This directive will not cause the calling task to be preempted. -This directive deletes the dual-ported memory area specified by id. The DPCB -for the deleted dual-ported memory area is reclaimed by RTEMS. + The calling task does not have to be the task that created the port. Any + local task that knows the port id can delete the port. -**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 port. Any local -task that knows the port id can delete the port. + \clearpage .. _rtems_port_external_to_internal: PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address ---------------------------------------------------------------- .. index:: convert external to internal address - -**CALLING SEQUENCE:** - .. index:: rtems_port_external_to_internal -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_port_external_to_internal( - rtems_id id, - void *external, - void **internal - ); + rtems_status_code rtems_port_external_to_internal( + rtems_id id, + void *external, + void **internal + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. list-table:: - :class: rtems-table + * - ``RTEMS_INVALID_ADDRESS`` + - ``internal`` is NULL + * - ``RTEMS_SUCCESSFUL`` + - successful conversion - * - ``RTEMS_INVALID_ADDRESS`` - - ``internal`` is NULL - * - ``RTEMS_SUCCESSFUL`` - - successful conversion +DESCRIPTION: + This directive converts a dual-ported memory address from external to + internal representation for the specified port. If the given external + address is invalid for the specified port, then the internal address is set + to the given external address. -**DESCRIPTION:** +NOTES: + This directive is callable from an ISR. -This directive converts a dual-ported memory address from external to internal -representation for the specified port. If the given external address is -invalid for the specified port, then the internal address is set to the given -external address. + This directive will not cause the calling task to be preempted. -**NOTES:** +.. raw:: latex -This directive is callable from an ISR. - -This directive will not cause the calling task to be preempted. + \clearpage .. _rtems_port_internal_to_external: PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address ---------------------------------------------------------------- .. index:: convert internal to external address - -**CALLING SEQUENCE:** - .. index:: rtems_port_internal_to_external -.. code-block:: c - - rtems_status_code rtems_port_internal_to_external( - rtems_id id, - void *internal, - void **external - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +CALLING SEQUENCE: + .. code-block:: c - * - ``RTEMS_INVALID_ADDRESS`` - - ``external`` is NULL - * - ``RTEMS_SUCCESSFUL`` - - successful conversion + rtems_status_code rtems_port_internal_to_external( + rtems_id id, + void *internal, + void **external + ); -**DESCRIPTION:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -This directive converts a dual-ported memory address from internal to external -representation so that it can be passed to owner of the DPMA represented by the -specified port. If the given internal address is an invalid dual-ported -address, then the external address is set to the given internal address. + * - ``RTEMS_INVALID_ADDRESS`` + - ``external`` is NULL + * - ``RTEMS_SUCCESSFUL`` + - successful conversion -**NOTES:** +DESCRIPTION: + This directive converts a dual-ported memory address from internal to + external representation so that it can be passed to owner of the DPMA + represented by the specified port. If the given internal address is an + invalid dual-ported address, then the external address is set to the given + internal address. -This directive is callable from an ISR. +NOTES: + This directive is callable from an ISR. -This directive will not cause the calling task to be preempted. + This directive will not cause the calling task to be preempted. -- cgit v1.2.3