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

4.115
Last change on this file since fd6dc8c8 was fd6dc8c8, checked in by Amar Takhar <amar@…>, on 01/18/16 at 00:19:43

Split document into seperate files by section.

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