source: rtems-docs/c_user/linker_sets.rst @ 4120668

4.11
Last change on this file since 4120668 was 489740f, checked in by Chris Johns <chrisj@…>, on May 20, 2016 at 2:47:09 AM

Set SPDX License Identifier in each source file.

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