source: rtems-docs/c_user/linker_sets.rst @ 9aafb39

4.11
Last change on this file since 9aafb39 was 9aafb39, checked in by Chris Johns <chrisj@…>, on Oct 28, 2016 at 12:56:02 PM

c_user: Remove errors and warnings.

  • Property mode set to 100644
File size: 17.9 KB
RevLine 
[489740f]1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
[0d86b71]3.. COMMENT: COPYRIGHT (c) 1989-2014.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
6
[9aafb39]7.. _Linker Sets:
8
[fd6dc8c]9Linker Sets
10###########
11
12.. index:: linkersets
13
14Introduction
15============
16
17Linker sets are a flexible means to create arrays of items out of a set of
[0d86b71]18object files at link-time.  For example its possible to define an item *I* of
19type *T* in object file *A* and an item *J* of type *T* in object file *B* to
20be a member of a linker set *S*.  The linker will then collect these two items
21*I* and *J* and place them in consecutive memory locations, so that they can be
22accessed like a normal array defined in one object file.  The size of a linker
23set is defined by its begin and end markers.  A linker set may be empty.  It
24should only contain items of the same type.
[fd6dc8c]25
26The following macros are provided to create, populate and use linker sets.
27
[0d86b71]28- RTEMS_LINKER_SET_BEGIN_ - Designator of the linker set begin marker
[fd6dc8c]29
[0d86b71]30- RTEMS_LINKER_SET_END_ - Designator of the linker set end marker
[fd6dc8c]31
[0d86b71]32- RTEMS_LINKER_SET_SIZE_ - The linker set size in characters
[fd6dc8c]33
[0d86b71]34- RTEMS_LINKER_ROSET_DECLARE_ - Declares a read-only linker set
[fd6dc8c]35
[0d86b71]36- RTEMS_LINKER_ROSET_ - Defines a read-only linker set
[fd6dc8c]37
[0d86b71]38- RTEMS_LINKER_ROSET_ITEM_DECLARE_ - Declares a read-only linker set item
[fd6dc8c]39
[0d86b71]40- RTEMS_LINKER_ROSET_ITEM_REFERENCE_ - References a read-only linker set item
[fd6dc8c]41
[0d86b71]42- RTEMS_LINKER_ROSET_ITEM_ - Defines a read-only linker set item
[fd6dc8c]43
[0d86b71]44- RTEMS_LINKER_ROSET_ITEM_ORDERED_ - Defines an ordered read-only linker set item
[fd6dc8c]45
[0d86b71]46- RTEMS_LINKER_RWSET_DECLARE_ - Declares a read-write linker set
[fd6dc8c]47
[0d86b71]48- RTEMS_LINKER_RWSET_ - Defines a read-write linker set
[fd6dc8c]49
[0d86b71]50- RTEMS_LINKER_RWSET_ITEM_DECLARE_ - Declares a read-write linker set item
[fd6dc8c]51
[0d86b71]52- RTEMS_LINKER_RWSET_ITEM_REFERENCE_ - References a read-write linker set item
[fd6dc8c]53
[0d86b71]54- RTEMS_LINKER_RWSET_ITEM_ - Defines a read-write linker set item
[fd6dc8c]55
[0d86b71]56- RTEMS_LINKER_RWSET_ITEM_ORDERED_ - Defines an ordered read-write linker set item
[fd6dc8c]57
58Background
59==========
60
61Linker sets are used not only in RTEMS, but also for example in Linux, in
62FreeBSD, for the GNU C constructor extension and for global C++ constructors.
63They provide a space efficient and flexible means to initialize modules.  A
64linker set consists of
65
[0d86b71]66- dedicated input sections for the linker (e.g. ``.ctors`` and ``.ctors.*`` in
67  the case of global constructors),
[fd6dc8c]68
69- a begin marker (e.g. provided by ``crtbegin.o``, and
70
71- an end marker (e.g. provided by ``ctrend.o``).
72
73A module may place a certain data item into the dedicated input section.  The
74linker will collect all such data items in this section and creates a begin and
75end marker.  The initialization code can then use the begin and end markers to
76find all the collected data items (e.g. pointers to initialization functions).
77
78In the linker command file of the GNU linker we need the following output
79section descriptions.
80
[0d86b71]81.. code-block:: c
82
83    /* To be placed in a read-only memory region */
[fd6dc8c]84    .rtemsroset : {
[bcd64c6]85        KEEP (*(SORT(.rtemsroset.*)))
[fd6dc8c]86    }
[0d86b71]87    /* To be placed in a read-write memory region */
[fd6dc8c]88    .rtemsrwset : {
[bcd64c6]89        KEEP (*(SORT(.rtemsrwset.*)))
[fd6dc8c]90    }
91
[0d86b71]92The ``KEEP()`` ensures that a garbage collection by the linker will not discard
93the content of this section.  This would normally be the case since the linker
94set items are not referenced directly.  The ``SORT()`` directive sorts the
95input sections lexicographically.  Please note the lexicographical order of the
96``.begin``, ``.content`` and ``.end`` section name parts in the RTEMS linker
97sets macros which ensures that the position of the begin and end markers are
98right.
[fd6dc8c]99
100So, what is the benefit of using linker sets to initialize modules?  It can be
101used to initialize and include only those RTEMS managers and other components
102which are used by the application.  For example, in case an application uses
[0d86b71]103message queues, it must call ``rtems_message_queue_create()``.  In the module
104implementing this function, we can place a linker set item and register the
105message queue handler constructor.  Otherwise, in case the application does not
106use message queues, there will be no reference to the
107``rtems_message_queue_create()`` function and the constructor is not
[fd6dc8c]108registered, thus nothing of the message queue handler will be in the final
109executable.
110
111For an example see test program :file:`sptests/splinkersets01`.
112
113Directives
114==========
115
[0d86b71]116.. _RTEMS_LINKER_SET_BEGIN:
117
[fd6dc8c]118RTEMS_LINKER_SET_BEGIN - Designator of the linker set begin marker
119------------------------------------------------------------------
120
121**CALLING SEQUENCE:**
122
123.. index:: RTEMS_LINKER_SET_BEGIN
124
[0d86b71]125.. code-block:: c
[fd6dc8c]126
[0d86b71]127    volatile type *begin = RTEMS_LINKER_SET_BEGIN( set );
[fd6dc8c]128
129**DESCRIPTION:**
130
131This macro generates the designator of the begin marker of the linker set
132identified by ``set``.  The item at the begin marker address is the first
133member of the linker set if it exists, e.g. the linker set is not empty.  A
134linker set is empty, if and only if the begin and end markers have the same
135address.
[0d86b71]136
[fd6dc8c]137The ``set`` parameter itself must be a valid C designator on which no macro
138expansion is performed.  It uniquely identifies the linker set.
139
[0d86b71]140.. _RTEMS_LINKER_SET_END:
141
[fd6dc8c]142RTEMS_LINKER_SET_END - Designator of the linker set end marker
143--------------------------------------------------------------
144
145**CALLING SEQUENCE:**
146
147.. index:: RTEMS_LINKER_SET_END
148
[0d86b71]149.. code-block:: c
[fd6dc8c]150
[0d86b71]151    volatile type *end = RTEMS_LINKER_SET_END( set );
[fd6dc8c]152
153**DESCRIPTION:**
154
155This macro generates the designator of the end marker of the linker set
[0d86b71]156identified by ``set``.  The item at the end marker address is not a member of
157the linker set.  The ``set`` parameter itself must be a valid C designator on
158which no macro expansion is performed.  It uniquely identifies the linker set.
159
160.. _RTEMS_LINKER_SET_SIZE:
[fd6dc8c]161
162RTEMS_LINKER_SET_SIZE - The linker set size in characters
163---------------------------------------------------------
164
165**CALLING SEQUENCE:**
166
167.. index:: RTEMS_LINKER_SET_SIZE
168
[0d86b71]169.. code-block:: c
[fd6dc8c]170
171    size_t size = RTEMS_LINKER_SET_SIZE( set );
172
173**DESCRIPTION:**
174
175This macro returns the size of the linker set identified by ``set`` in
[0d86b71]176characters.  The ``set`` parameter itself must be a valid C designator on which
177no macro expansion is performed.  It uniquely identifies the linker set.
178
179.. _RTEMS_LINKER_ROSET_DECLARE:
[fd6dc8c]180
181RTEMS_LINKER_ROSET_DECLARE - Declares a read-only linker set
182------------------------------------------------------------
183
184**CALLING SEQUENCE:**
185
186.. index:: RTEMS_LINKER_ROSET_DECLARE
187
[0d86b71]188.. code-block:: c
[fd6dc8c]189
190    RTEMS_LINKER_ROSET_DECLARE( set, type );
191
192**DESCRIPTION:**
193
194This macro generates declarations for the begin and end markers of a read-only
[0d86b71]195linker set identified by ``set``.  The ``set`` parameter itself must be a valid
196C designator on which no macro expansion is performed.  It uniquely identifies
197the linker set. The ``type`` parameter defines the type of the linker set
198items.  The type must be the same for all macro invocations of a particular
199linker set.
200
201.. _RTEMS_LINKER_ROSET:
[fd6dc8c]202
203RTEMS_LINKER_ROSET - Defines a read-only linker set
204---------------------------------------------------
205
206**CALLING SEQUENCE:**
207
208.. index:: RTEMS_LINKER_ROSET
209
[0d86b71]210.. code-block:: c
[fd6dc8c]211
212    RTEMS_LINKER_ROSET( set, type );
213
214**DESCRIPTION:**
215
216This macro generates definitions for the begin and end markers of a read-only
[0d86b71]217linker set identified by ``set``.  The ``set`` parameter itself must be a valid
218C designator on which no macro expansion is performed.  It uniquely identifies
219the linker set. The ``type`` parameter defines the type of the linker set
220items.  The type must be the same for all macro invocations of a particular
221linker set.
222
223.. _RTEMS_LINKER_ROSET_ITEM_DECLARE:
[fd6dc8c]224
225RTEMS_LINKER_ROSET_ITEM_DECLARE - Declares a read-only linker set item
226----------------------------------------------------------------------
227
228**CALLING SEQUENCE:**
229
230.. index:: RTEMS_LINKER_ROSET_ITEM_DECLARE
231
[0d86b71]232.. code-block:: c
[fd6dc8c]233
234    RTEMS_LINKER_ROSET_ITEM_DECLARE( set, type, item );
235
236**DESCRIPTION:**
237
238This macro generates a declaration of an item contained in the read-only linker
[0d86b71]239set identified by ``set``.  The ``set`` parameter itself must be a valid C
240designator on which no macro expansion is performed.  It uniquely identifies
241the linker set. The ``type`` parameter defines the type of the linker set
242items.  The type must be the same for all macro invocations of a particular
243linker set. The ``item`` parameter itself must be a valid C designator on which
244no macro expansion is performed.  It uniquely identifies an item in the linker
245set.
246
247.. _RTEMS_LINKER_ROSET_ITEM_REFERENCE:
[fd6dc8c]248
249RTEMS_LINKER_ROSET_ITEM_REFERENCE - References a read-only linker set item
250--------------------------------------------------------------------------
251
252**CALLING SEQUENCE:**
253
254.. index:: RTEMS_LINKER_ROSET_ITEM_REFERENCE
255
[0d86b71]256.. code-block:: c
[fd6dc8c]257
258    RTEMS_LINKER_ROSET_ITEM_REFERENCE( set, type, item );
259
260**DESCRIPTION:**
261
[0d86b71]262This macro generates a reference to an item contained in the read-only linker
263set identified by ``set``.  The ``set`` parameter itself must be a valid C
264designator on which no macro expansion is performed.  It uniquely identifies
265the linker set. The ``type`` parameter defines the type of the linker set
266items.  The type must be the same for all macro invocations of a particular
267linker set. The ``item`` parameter itself must be a valid C designator on which
268no macro expansion is performed.  It uniquely identifies an item in the linker
269set.
270
271.. _RTEMS_LINKER_ROSET_ITEM:
[fd6dc8c]272
273RTEMS_LINKER_ROSET_ITEM - Defines a read-only linker set item
274-------------------------------------------------------------
275
276**CALLING SEQUENCE:**
277
278.. index:: RTEMS_LINKER_ROSET_ITEM
279
[0d86b71]280.. code-block:: c
[fd6dc8c]281
282    RTEMS_LINKER_ROSET_ITEM( set, type, item );
283
284**DESCRIPTION:**
285
[0d86b71]286This macro generates a definition of an item contained in the read-only linker
287set identified by ``set``.  The ``set`` parameter itself must be a valid C
288designator on which no macro expansion is performed.  It uniquely identifies
289the linker set. The ``type`` parameter defines the type of the linker set
290items.  The type must be the same for all macro invocations of a particular
291linker set. The ``item`` parameter itself must be a valid C designator on which
292no macro expansion is performed.  It uniquely identifies an item in the linker
293set.
294
295.. _RTEMS_LINKER_ROSET_ITEM_ORDERED:
[fd6dc8c]296
297RTEMS_LINKER_ROSET_ITEM_ORDERED - Defines an ordered read-only linker set item
298------------------------------------------------------------------------------
299
300**CALLING SEQUENCE:**
301
302.. index:: RTEMS_LINKER_ROSET_ITEM_ORDERED
303
[0d86b71]304.. code-block:: c
[fd6dc8c]305
306    RTEMS_LINKER_ROSET_ITEM_ORDERED( set, type, item, order );
307
308**DESCRIPTION:**
309
310This macro generates a definition of an ordered item contained in the read-only
[0d86b71]311linker set identified by ``set``.  The ``set`` parameter itself must be a valid
312C designator on which no macro expansion is performed.  It uniquely identifies
313the linker set. The ``type`` parameter defines the type of the linker set
314items.  The type must be the same for all macro invocations of a particular
315linker set.  The ``item`` parameter itself must be a valid C designator on
316which no macro expansion is performed.  It uniquely identifies an item in the
317linker set. The ``order`` parameter must be a valid linker input section name
318part on which macro expansion is performed.  The items are lexicographically
319ordered according to the ``order`` parameter within a linker set.  Ordered
320items are placed before unordered items in the linker set.
[fd6dc8c]321
322**NOTES:**
323
324To be resilient to typos in the order parameter, it is recommended to use the
325following construct in macros defining items for a particular linker set (see
326enum in ``XYZ_ITEM()``).
[0d86b71]327
328.. code-block:: c
[fd6dc8c]329
330    #include <rtems/linkersets.h>
[0d86b71]331
[fd6dc8c]332    typedef struct {
[0d86b71]333        int foo;
[fd6dc8c]334    } xyz_item;
[0d86b71]335
336    /* The XYZ-order defines */
[fd6dc8c]337    #define XYZ_ORDER_FIRST 0x00001000
338    #define XYZ_ORDER_AND_SO_ON 0x00002000
[0d86b71]339
340    /* Defines an ordered XYZ-item */
341    #define XYZ_ITEM( item, order ) \
342                enum { xyz_##item = order - order }; \
343                RTEMS_LINKER_ROSET_ITEM_ORDERED( \
344                    xyz, const xyz_item *, item, order \
345                ) = { &item }
346
347    /* Example item */
[fd6dc8c]348    static const xyz_item some_item = { 123 };
349    XYZ_ITEM( some_item, XYZ_ORDER_FIRST );
350
[0d86b71]351.. _RTEMS_LINKER_RWSET_DECLARE:
352
[fd6dc8c]353RTEMS_LINKER_RWSET_DECLARE - Declares a read-write linker set
354-------------------------------------------------------------
355
356**CALLING SEQUENCE:**
357
358.. index:: RTEMS_LINKER_RWSET_DECLARE
359
[0d86b71]360.. code-block:: c
[fd6dc8c]361
362    RTEMS_LINKER_RWSET_DECLARE( set, type );
363
364**DESCRIPTION:**
365
366This macro generates declarations for the begin and end markers of a read-write
[0d86b71]367linker set identified by ``set``.  The ``set`` parameter itself must be a valid
368C designator on which no macro expansion is performed.  It uniquely identifies
369the linker set. The ``type`` parameter defines the type of the linker set
370items.  The type must be the same for all macro invocations of a particular
371linker set.
372
373.. _RTEMS_LINKER_RWSET:
[fd6dc8c]374
375RTEMS_LINKER_RWSET - Defines a read-write linker set
376----------------------------------------------------
377
378**CALLING SEQUENCE:**
379
380.. index:: RTEMS_LINKER_RWSET
381
[0d86b71]382.. code-block:: c
[fd6dc8c]383
384    RTEMS_LINKER_RWSET( set, type );
385
386**DESCRIPTION:**
387
388This macro generates definitions for the begin and end markers of a read-write
[0d86b71]389linker set identified by ``set``.  The ``set`` parameter itself must be a valid
390C designator on which no macro expansion is performed.  It uniquely identifies
391the linker set. The ``type`` parameter defines the type of the linker set
392items.  The type must be the same for all macro invocations of a particular
393linker set.
394
395.. _RTEMS_LINKER_RWSET_ITEM_DECLARE:
[fd6dc8c]396
397RTEMS_LINKER_RWSET_ITEM_DECLARE - Declares a read-write linker set item
398-----------------------------------------------------------------------
399
400**CALLING SEQUENCE:**
401
402.. index:: RTEMS_LINKER_RWSET_ITEM_DECLARE
403
[0d86b71]404.. code-block:: c
[fd6dc8c]405
406    RTEMS_LINKER_RWSET_ITEM_DECLARE( set, type, item );
407
408**DESCRIPTION:**
409
[0d86b71]410This macro generates a declaration of an item contained in the read-write
411linker set identified by ``set``.  The ``set`` parameter itself must be a valid
412C designator on which no macro expansion is performed.  It uniquely identifies
413the linker set. The ``type`` parameter defines the type of the linker set
414items.  The type must be the same for all macro invocations of a particular
415linker set. The ``item`` parameter itself must be a valid C designator on which
416no macro expansion is performed.  It uniquely identifies an item in the linker
417set.
418
419.. _RTEMS_LINKER_RWSET_ITEM_REFERENCE:
[fd6dc8c]420
421RTEMS_LINKER_RWSET_ITEM_REFERENCE - References a read-write linker set item
422---------------------------------------------------------------------------
423
424**CALLING SEQUENCE:**
425
426.. index:: RTEMS_LINKER_RWSET_ITEM_REFERENCE
427
[0d86b71]428.. code-block:: c
[fd6dc8c]429
430    RTEMS_LINKER_RWSET_ITEM_REFERENCE( set, type, item );
431
432**DESCRIPTION:**
433
[0d86b71]434This macro generates a reference to an item contained in the read-write linker
435set identified by ``set``.  The ``set`` parameter itself must be a valid C
436designator on which no macro expansion is performed.  It uniquely identifies
437the linker set. The ``type`` parameter defines the type of the linker set
438items.  The type must be the same for all macro invocations of a particular
439linker set. The ``item`` parameter itself must be a valid C designator on which
440no macro expansion is performed.  It uniquely identifies an item in the linker
441set.
442
443.. _RTEMS_LINKER_RWSET_ITEM:
[fd6dc8c]444
445RTEMS_LINKER_RWSET_ITEM - Defines a read-write linker set item
446--------------------------------------------------------------
447
448**CALLING SEQUENCE:**
449
450.. index:: RTEMS_LINKER_RWSET_ITEM
451
[0d86b71]452.. code-block:: c
[fd6dc8c]453
454    RTEMS_LINKER_RWSET_ITEM( set, type, item );
455
456**DESCRIPTION:**
457
[0d86b71]458This macro generates a definition of an item contained in the read-write linker
459set identified by ``set``.  The ``set`` parameter itself must be a valid C
460designator on which no macro expansion is performed.  It uniquely identifies
461the linker set. The ``type`` parameter defines the type of the linker set
462items.  The type must be the same for all macro invocations of a particular
463linker set. The ``item`` parameter itself must be a valid C designator on which
464no macro expansion is performed.  It uniquely identifies an item in the linker
465set.
466
467.. _RTEMS_LINKER_RWSET_ITEM_ORDERED:
[fd6dc8c]468
469RTEMS_LINKER_RWSET_ITEM_ORDERED - Defines an ordered read-write linker set item
470-------------------------------------------------------------------------------
471
472**CALLING SEQUENCE:**
473
474.. index:: RTEMS_LINKER_RWSET_ITEM_ORDERED
475
[0d86b71]476.. code-block:: c
[fd6dc8c]477
478    RTEMS_LINKER_RWSET_ITEM_ORDERED( set, type, item, order );
479
480**DESCRIPTION:**
481
[0d86b71]482This macro generates a definition of an ordered item contained in the
483read-write linker set identified by ``set``.  The ``set`` parameter itself must
484be a valid C designator on which no macro expansion is performed.  It uniquely
485identifies the linker set. The ``type`` parameter defines the type of the
486linker set items.  The type must be the same for all macro invocations of a
487particular linker set.  The ``item`` parameter itself must be a valid C
488designator on which no macro expansion is performed.  It uniquely identifies an
489item in the linker set. The ``order`` parameter must be a valid linker input
490section name part on which macro expansion is performed.  The items are
491lexicographically ordered according to the ``order`` parameter within a linker
492set.  Ordered items are placed before unordered items in the linker set.
[fd6dc8c]493
494**NOTES:**
495
496To be resilient to typos in the order parameter, it is recommended to use the
497following construct in macros defining items for a particular linker set (see
498enum in ``XYZ_ITEM()``).
[0d86b71]499
500.. code-block:: c
[fd6dc8c]501
502    #include <rtems/linkersets.h>
[0d86b71]503
[fd6dc8c]504    typedef struct {
[0d86b71]505        int foo;
[fd6dc8c]506    } xyz_item;
[0d86b71]507
508    /* The XYZ-order defines */
[fd6dc8c]509    #define XYZ_ORDER_FIRST 0x00001000
510    #define XYZ_ORDER_AND_SO_ON 0x00002000
[0d86b71]511
512    /* Defines an ordered XYZ-item */
513    #define XYZ_ITEM( item, order ) \
514                enum { xyz_##item = order - order }; \
515                RTEMS_LINKER_RWSET_ITEM_ORDERED( \
[bcd64c6]516                    xyz, const xyz_item *, item, order \
[0d86b71]517                ) = { &item }
518    /* Example item */
[fd6dc8c]519    static const xyz_item some_item = { 123 };
520    XYZ_ITEM( some_item, XYZ_ORDER_FIRST );
Note: See TracBrowser for help on using the repository browser.