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