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/linker_sets.rst | 517 +++++++++++++++++++++++++------------------------ 1 file changed, 267 insertions(+), 250 deletions(-) (limited to 'c-user/linker_sets.rst') diff --git a/c-user/linker_sets.rst b/c-user/linker_sets.rst index ad45fea..37f863e 100644 --- a/c-user/linker_sets.rst +++ b/c-user/linker_sets.rst @@ -113,408 +113,425 @@ For an example see test program :file:`sptests/splinkersets01`. Directives ========== +.. raw:: latex + + \clearpage + .. _RTEMS_LINKER_SET_BEGIN: RTEMS_LINKER_SET_BEGIN - Designator of the linker set begin marker ------------------------------------------------------------------ - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_SET_BEGIN -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - volatile type *begin = RTEMS_LINKER_SET_BEGIN( set ); + volatile type *begin = RTEMS_LINKER_SET_BEGIN( set ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates the designator of the begin marker of the linker set + identified by ``set``. The item at the begin marker address is the first + member of the linker set if it exists, e.g. the linker set is not empty. A + linker set is empty, if and only if the begin and end markers have the same + address. -This macro generates the designator of the begin marker of the linker set -identified by ``set``. The item at the begin marker address is the first -member of the linker set if it exists, e.g. the linker set is not empty. A -linker set is empty, if and only if the begin and end markers have the same -address. + The ``set`` parameter itself must be a valid C designator on which no macro + expansion is performed. It uniquely identifies the linker set. -The ``set`` parameter itself must be a valid C designator on which no macro -expansion is performed. It uniquely identifies the linker set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_SET_END: RTEMS_LINKER_SET_END - Designator of the linker set end marker -------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_SET_END -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - volatile type *end = RTEMS_LINKER_SET_END( set ); + volatile type *end = RTEMS_LINKER_SET_END( set ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates the designator of the end marker of the linker set + identified by ``set``. The item at the end marker address is not a member + of the linker set. The ``set`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies the linker set. -This macro generates the designator of the end marker of the linker set -identified by ``set``. The item at the end marker address is not a member of -the linker set. The ``set`` parameter itself must be a valid C designator on -which no macro expansion is performed. It uniquely identifies the linker set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_SET_SIZE: RTEMS_LINKER_SET_SIZE - The linker set size in characters --------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_SET_SIZE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + size_t size = RTEMS_LINKER_SET_SIZE( set ); - size_t size = RTEMS_LINKER_SET_SIZE( set ); +DESCRIPTION: + This macro returns the size of the linker set identified by ``set`` in + characters. The ``set`` parameter itself must be a valid C designator on + which no macro expansion is performed. It uniquely identifies the linker + set. -**DESCRIPTION:** +.. raw:: latex -This macro returns the size of the linker set identified by ``set`` in -characters. The ``set`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies the linker set. + \clearpage .. _RTEMS_LINKER_ROSET_DECLARE: RTEMS_LINKER_ROSET_DECLARE - Declares a read-only linker set ------------------------------------------------------------ - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_ROSET_DECLARE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + RTEMS_LINKER_ROSET_DECLARE( set, type ); - RTEMS_LINKER_ROSET_DECLARE( set, type ); +DESCRIPTION: + This macro generates declarations for the begin and end markers of a + read-only linker set identified by ``set``. The ``set`` parameter itself + must be a valid C designator on which no macro expansion is performed. It + uniquely identifies the linker set. The ``type`` parameter defines the type + of the linker set items. The type must be the same for all macro + invocations of a particular linker set. -**DESCRIPTION:** +.. raw:: latex -This macro generates declarations for the begin and end markers of a read-only -linker set identified by ``set``. The ``set`` parameter itself must be a valid -C designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. + \clearpage .. _RTEMS_LINKER_ROSET: RTEMS_LINKER_ROSET - Defines a read-only linker set --------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_ROSET -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - RTEMS_LINKER_ROSET( set, type ); + RTEMS_LINKER_ROSET( set, type ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates definitions for the begin and end markers of a + read-only linker set identified by ``set``. The ``set`` parameter itself + must be a valid C designator on which no macro expansion is performed. It + uniquely identifies the linker set. The ``type`` parameter defines the type + of the linker set items. The type must be the same for all macro + invocations of a particular linker set. -This macro generates definitions for the begin and end markers of a read-only -linker set identified by ``set``. The ``set`` parameter itself must be a valid -C designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_ROSET_ITEM_DECLARE: RTEMS_LINKER_ROSET_ITEM_DECLARE - Declares a read-only linker set item ---------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_ROSET_ITEM_DECLARE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - RTEMS_LINKER_ROSET_ITEM_DECLARE( set, type, item ); + RTEMS_LINKER_ROSET_ITEM_DECLARE( set, type, item ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates a declaration of an item contained in the read-only + linker set identified by ``set``. The ``set`` parameter itself must be a + valid C designator on which no macro expansion is performed. It uniquely + identifies the linker set. The ``type`` parameter defines the type of the + linker set items. The type must be the same for all macro invocations of a + particular linker set. The ``item`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies an item in the linker set. -This macro generates a declaration of an item contained in the read-only linker -set identified by ``set``. The ``set`` parameter itself must be a valid C -designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies an item in the linker -set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_ROSET_ITEM_REFERENCE: RTEMS_LINKER_ROSET_ITEM_REFERENCE - References a read-only linker set item -------------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_ROSET_ITEM_REFERENCE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - RTEMS_LINKER_ROSET_ITEM_REFERENCE( set, type, item ); + RTEMS_LINKER_ROSET_ITEM_REFERENCE( set, type, item ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates a reference to an item contained in the read-only + linker set identified by ``set``. The ``set`` parameter itself must be a + valid C designator on which no macro expansion is performed. It uniquely + identifies the linker set. The ``type`` parameter defines the type of the + linker set items. The type must be the same for all macro invocations of a + particular linker set. The ``item`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies an item in the linker set. -This macro generates a reference to an item contained in the read-only linker -set identified by ``set``. The ``set`` parameter itself must be a valid C -designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies an item in the linker -set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_ROSET_ITEM: RTEMS_LINKER_ROSET_ITEM - Defines a read-only linker set item ------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_ROSET_ITEM -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - RTEMS_LINKER_ROSET_ITEM( set, type, item ); + RTEMS_LINKER_ROSET_ITEM( set, type, item ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates a definition of an item contained in the read-only + linker set identified by ``set``. The ``set`` parameter itself must be a + valid C designator on which no macro expansion is performed. It uniquely + identifies the linker set. The ``type`` parameter defines the type of the + linker set items. The type must be the same for all macro invocations of a + particular linker set. The ``item`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies an item in the linker set. -This macro generates a definition of an item contained in the read-only linker -set identified by ``set``. The ``set`` parameter itself must be a valid C -designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies an item in the linker -set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_ROSET_ITEM_ORDERED: RTEMS_LINKER_ROSET_ITEM_ORDERED - Defines an ordered read-only linker set item ------------------------------------------------------------------------------ - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_ROSET_ITEM_ORDERED -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - RTEMS_LINKER_ROSET_ITEM_ORDERED( set, type, item, order ); + RTEMS_LINKER_ROSET_ITEM_ORDERED( set, type, item, order ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates a definition of an ordered item contained in the + read-only linker set identified by ``set``. The ``set`` parameter itself + must be a valid C designator on which no macro expansion is performed. It + uniquely identifies the linker set. The ``type`` parameter defines the type + of the linker set items. The type must be the same for all macro + invocations of a particular linker set. The ``item`` parameter itself must + be a valid C designator on which no macro expansion is performed. It + uniquely identifies an item in the linker set. The ``order`` parameter must + be a valid linker input section name part on which macro expansion is + performed. The items are lexicographically ordered according to the + ``order`` parameter within a linker set. Ordered items are placed before + unordered items in the linker set. -This macro generates a definition of an ordered item contained in the read-only -linker set identified by ``set``. The ``set`` parameter itself must be a valid -C designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on -which no macro expansion is performed. It uniquely identifies an item in the -linker set. The ``order`` parameter must be a valid linker input section name -part on which macro expansion is performed. The items are lexicographically -ordered according to the ``order`` parameter within a linker set. Ordered -items are placed before unordered items in the linker set. +NOTES: + To be resilient to typos in the order parameter, it is recommended to use + the following construct in macros defining items for a particular linker + set (see enum in ``XYZ_ITEM()``). -**NOTES:** + .. code-block:: c -To be resilient to typos in the order parameter, it is recommended to use the -following construct in macros defining items for a particular linker set (see -enum in ``XYZ_ITEM()``). + #include -.. code-block:: c + typedef struct { + int foo; + } xyz_item; - #include + /* The XYZ-order defines */ + #define XYZ_ORDER_FIRST 0x00001000 + #define XYZ_ORDER_AND_SO_ON 0x00002000 - typedef struct { - int foo; - } xyz_item; + /* Defines an ordered XYZ-item */ + #define XYZ_ITEM( item, order ) \ + enum { xyz_##item = order - order }; \ + RTEMS_LINKER_ROSET_ITEM_ORDERED( \ + xyz, const xyz_item *, item, order \ + ) = { &item } - /* The XYZ-order defines */ - #define XYZ_ORDER_FIRST 0x00001000 - #define XYZ_ORDER_AND_SO_ON 0x00002000 + /* Example item */ + static const xyz_item some_item = { 123 }; + XYZ_ITEM( some_item, XYZ_ORDER_FIRST ); - /* Defines an ordered XYZ-item */ - #define XYZ_ITEM( item, order ) \ - enum { xyz_##item = order - order }; \ - RTEMS_LINKER_ROSET_ITEM_ORDERED( \ - xyz, const xyz_item *, item, order \ - ) = { &item } +.. raw:: latex - /* Example item */ - static const xyz_item some_item = { 123 }; - XYZ_ITEM( some_item, XYZ_ORDER_FIRST ); + \clearpage .. _RTEMS_LINKER_RWSET_DECLARE: RTEMS_LINKER_RWSET_DECLARE - Declares a read-write linker set ------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_RWSET_DECLARE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + RTEMS_LINKER_RWSET_DECLARE( set, type ); - RTEMS_LINKER_RWSET_DECLARE( set, type ); +DESCRIPTION: + This macro generates declarations for the begin and end markers of a + read-write linker set identified by ``set``. The ``set`` parameter itself + must be a valid C designator on which no macro expansion is performed. It + uniquely identifies the linker set. The ``type`` parameter defines the type + of the linker set items. The type must be the same for all macro + invocations of a particular linker set. -**DESCRIPTION:** +.. raw:: latex -This macro generates declarations for the begin and end markers of a read-write -linker set identified by ``set``. The ``set`` parameter itself must be a valid -C designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. + \clearpage .. _RTEMS_LINKER_RWSET: RTEMS_LINKER_RWSET - Defines a read-write linker set ---------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_RWSET -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + RTEMS_LINKER_RWSET( set, type ); - RTEMS_LINKER_RWSET( set, type ); +DESCRIPTION: + This macro generates definitions for the begin and end markers of a + read-write linker set identified by ``set``. The ``set`` parameter itself + must be a valid C designator on which no macro expansion is performed. It + uniquely identifies the linker set. The ``type`` parameter defines the type + of the linker set items. The type must be the same for all macro + invocations of a particular linker set. -**DESCRIPTION:** +.. raw:: latex -This macro generates definitions for the begin and end markers of a read-write -linker set identified by ``set``. The ``set`` parameter itself must be a valid -C designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. + \clearpage .. _RTEMS_LINKER_RWSET_ITEM_DECLARE: RTEMS_LINKER_RWSET_ITEM_DECLARE - Declares a read-write linker set item ----------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_RWSET_ITEM_DECLARE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + RTEMS_LINKER_RWSET_ITEM_DECLARE( set, type, item ); - RTEMS_LINKER_RWSET_ITEM_DECLARE( set, type, item ); +DESCRIPTION: + This macro generates a declaration of an item contained in the read-write + linker set identified by ``set``. The ``set`` parameter itself must be a + valid C designator on which no macro expansion is performed. It uniquely + identifies the linker set. The ``type`` parameter defines the type of the + linker set items. The type must be the same for all macro invocations of a + particular linker set. The ``item`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies an item in the linker set. -**DESCRIPTION:** +.. raw:: latex -This macro generates a declaration of an item contained in the read-write -linker set identified by ``set``. The ``set`` parameter itself must be a valid -C designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies an item in the linker -set. + \clearpage .. _RTEMS_LINKER_RWSET_ITEM_REFERENCE: RTEMS_LINKER_RWSET_ITEM_REFERENCE - References a read-write linker set item --------------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_RWSET_ITEM_REFERENCE -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c + + RTEMS_LINKER_RWSET_ITEM_REFERENCE( set, type, item ); - RTEMS_LINKER_RWSET_ITEM_REFERENCE( set, type, item ); +DESCRIPTION: + This macro generates a reference to an item contained in the read-write + linker set identified by ``set``. The ``set`` parameter itself must be a + valid C designator on which no macro expansion is performed. It uniquely + identifies the linker set. The ``type`` parameter defines the type of the + linker set items. The type must be the same for all macro invocations of a + particular linker set. The ``item`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies an item in the linker set. -**DESCRIPTION:** +.. raw:: latex -This macro generates a reference to an item contained in the read-write linker -set identified by ``set``. The ``set`` parameter itself must be a valid C -designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies an item in the linker -set. + \clearpage .. _RTEMS_LINKER_RWSET_ITEM: RTEMS_LINKER_RWSET_ITEM - Defines a read-write linker set item -------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_RWSET_ITEM -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - RTEMS_LINKER_RWSET_ITEM( set, type, item ); + RTEMS_LINKER_RWSET_ITEM( set, type, item ); -**DESCRIPTION:** +DESCRIPTION: + This macro generates a definition of an item contained in the read-write + linker set identified by ``set``. The ``set`` parameter itself must be a + valid C designator on which no macro expansion is performed. It uniquely + identifies the linker set. The ``type`` parameter defines the type of the + linker set items. The type must be the same for all macro invocations of a + particular linker set. The ``item`` parameter itself must be a valid C + designator on which no macro expansion is performed. It uniquely + identifies an item in the linker set. -This macro generates a definition of an item contained in the read-write linker -set identified by ``set``. The ``set`` parameter itself must be a valid C -designator on which no macro expansion is performed. It uniquely identifies -the linker set. The ``type`` parameter defines the type of the linker set -items. The type must be the same for all macro invocations of a particular -linker set. The ``item`` parameter itself must be a valid C designator on which -no macro expansion is performed. It uniquely identifies an item in the linker -set. +.. raw:: latex + + \clearpage .. _RTEMS_LINKER_RWSET_ITEM_ORDERED: RTEMS_LINKER_RWSET_ITEM_ORDERED - Defines an ordered read-write linker set item ------------------------------------------------------------------------------- - -**CALLING SEQUENCE:** - .. index:: RTEMS_LINKER_RWSET_ITEM_ORDERED -.. code-block:: c - - RTEMS_LINKER_RWSET_ITEM_ORDERED( set, type, item, order ); - -**DESCRIPTION:** - -This macro generates a definition of an ordered item contained in the -read-write linker set identified by ``set``. The ``set`` parameter itself must -be a valid C designator on which no macro expansion is performed. It uniquely -identifies the linker set. The ``type`` parameter defines the type of the -linker set items. The type must be the same for all macro invocations of a -particular linker set. The ``item`` parameter itself must be a valid C -designator on which no macro expansion is performed. It uniquely identifies an -item in the linker set. The ``order`` parameter must be a valid linker input -section name part on which macro expansion is performed. The items are -lexicographically ordered according to the ``order`` parameter within a linker -set. Ordered items are placed before unordered items in the linker set. - -**NOTES:** - -To be resilient to typos in the order parameter, it is recommended to use the -following construct in macros defining items for a particular linker set (see -enum in ``XYZ_ITEM()``). - -.. code-block:: c - - #include - - typedef struct { - int foo; - } xyz_item; - - /* The XYZ-order defines */ - #define XYZ_ORDER_FIRST 0x00001000 - #define XYZ_ORDER_AND_SO_ON 0x00002000 - - /* Defines an ordered XYZ-item */ - #define XYZ_ITEM( item, order ) \ - enum { xyz_##item = order - order }; \ - RTEMS_LINKER_RWSET_ITEM_ORDERED( \ - xyz, const xyz_item *, item, order \ - ) = { &item } - /* Example item */ - static const xyz_item some_item = { 123 }; - XYZ_ITEM( some_item, XYZ_ORDER_FIRST ); +CALLING SEQUENCE: + .. code-block:: c + + RTEMS_LINKER_RWSET_ITEM_ORDERED( set, type, item, order ); + +DESCRIPTION: + This macro generates a definition of an ordered item contained in the + read-write linker set identified by ``set``. The ``set`` parameter itself + must be a valid C designator on which no macro expansion is performed. It + uniquely identifies the linker set. The ``type`` parameter defines the type + of the linker set items. The type must be the same for all macro + invocations of a particular linker set. The ``item`` parameter itself must + be a valid C designator on which no macro expansion is performed. It + uniquely identifies an item in the linker set. The ``order`` parameter must + be a valid linker input section name part on which macro expansion is + performed. The items are lexicographically ordered according to the + ``order`` parameter within a linker set. Ordered items are placed before + unordered items in the linker set. + +NOTES: + To be resilient to typos in the order parameter, it is recommended to use + the following construct in macros defining items for a particular linker + set (see enum in ``XYZ_ITEM()``). + + .. code-block:: c + + #include + + typedef struct { + int foo; + } xyz_item; + + /* The XYZ-order defines */ + #define XYZ_ORDER_FIRST 0x00001000 + #define XYZ_ORDER_AND_SO_ON 0x00002000 + + /* Defines an ordered XYZ-item */ + #define XYZ_ITEM( item, order ) \ + enum { xyz_##item = order - order }; \ + RTEMS_LINKER_RWSET_ITEM_ORDERED( \ + xyz, const xyz_item *, item, order \ + ) = { &item } + /* Example item */ + static const xyz_item some_item = { 123 }; + XYZ_ITEM( some_item, XYZ_ORDER_FIRST ); -- cgit v1.2.3