qemu/roms/ipxe/src/include/compiler.h

   1 #ifndef COMPILER_H
   2 #define COMPILER_H
   3
   4 /*
   5  * Doxygen can't cope with some of the more esoteric areas of C, so we
   6  * make its life simpler.
   7  *
   8  */
   9 #ifdef DOXYGEN
  10 #define __attribute__(x)
  11 #endif
  12
  13 /** @file
  14  *
  15  * Global compiler definitions.
  16  *
  17  * This file is implicitly included by every @c .c file in Etherboot.
  18  * It defines global macros such as DBG().
  19  *
  20  * We arrange for each object to export the symbol @c obj_OBJECT
  21  * (where @c OBJECT is the object name, e.g. @c rtl8139) as a global
  22  * symbol, so that the linker can drag in selected object files from
  23  * the library using <tt> -u obj_OBJECT </tt>.
  24  *
  25  */
  26
  27 /* Force visibility of all symbols to "hidden", i.e. inform gcc that
  28  * all symbol references resolve strictly within our final binary.
  29  * This avoids unnecessary PLT/GOT entries on x86_64.
  30  *
  31  * This is a stronger claim than specifying "-fvisibility=hidden",
  32  * since it also affects symbols marked with "extern".
  33  */
  34 #ifndef ASSEMBLY
  35 #if __GNUC__ >= 4
  36 #pragma GCC visibility push(hidden)
  37 #endif
  38 #endif /* ASSEMBLY */
  39
  40 #undef _S1
  41 #undef _S2
  42 #undef _C1
  43 #undef _C2
  44
  45 /** Concatenate non-expanded arguments */
  46 #define _C1( x, y ) x ## y
  47 /** Concatenate expanded arguments */
  48 #define _C2( x, y ) _C1 ( x, y )
  49
  50 /** Stringify non-expanded argument */
  51 #define _S1( x ) #x
  52 /** Stringify expanded argument */
  53 #define _S2( x ) _S1 ( x )
  54
  55 /**
  56  * @defgroup symmacros Macros to provide or require explicit symbols
  57  * @{
  58  */
  59
  60 /**
  61  * Provide a symbol within this object file
  62  *
  63  * @v symbol            Symbol name
  64  */
  65 #ifdef ASSEMBLY
  66 #define PROVIDE_SYMBOL( symbol )                                \
  67         .section ".provided", "a", @nobits ;                    \
  68         .hidden symbol ;                                        \
  69         .globl  symbol ;                                        \
  70         symbol: ;                                               \
  71         .previous
  72 #else
  73 #define PROVIDE_SYMBOL( symbol )                                \
  74         char symbol[0]                                          \
  75           __attribute__ (( section ( ".provided" ) ))
  76 #endif
  77
  78 /**
  79  * Request a symbol
  80  *
  81  * @v symbol            Symbol name
  82  *
  83  * Request a symbol to be included within the link.  If the symbol
  84  * cannot be found, the link will succeed anyway.
  85  */
  86 #ifdef ASSEMBLY
  87 #define REQUEST_SYMBOL( symbol )                                \
  88         .equ __request_ ## symbol, symbol
  89 #else
  90 #define REQUEST_SYMBOL( symbol )                                \
  91         __asm__ ( ".equ __request_" #symbol ", " #symbol )
  92 #endif
  93
  94 /**
  95  * Require a symbol
  96  *
  97  * @v symbol            Symbol name
  98  *
  99  * Require a symbol to be included within the link.  If the symbol
 100  * cannot be found, the link will fail.
 101  *
 102  * To use this macro within a file, you must also specify the file's
 103  * "requiring symbol" using the REQUIRING_SYMBOL() or
 104  * PROVIDE_REQUIRING_SYMBOL() macros.
 105  */
 106 #ifdef ASSEMBLY
 107 #define REQUIRE_SYMBOL( symbol )                                \
 108         .reloc __requiring_symbol__, RELOC_TYPE_NONE, symbol
 109 #else
 110 #define REQUIRE_SYMBOL( symbol )                                \
 111         __asm__ ( ".reloc __requiring_symbol__, "               \
 112                   _S2 ( RELOC_TYPE_NONE ) ", " #symbol )
 113 #endif
 114
 115 /**
 116  * Specify the file's requiring symbol
 117  *
 118  * @v symbol            Symbol name
 119  *
 120  * REQUIRE_SYMBOL() works by defining a dummy relocation record
 121  * against a nominated "requiring symbol".  The presence of the
 122  * nominated requiring symbol will drag in all of the symbols
 123  * specified using REQUIRE_SYMBOL().
 124  */
 125 #ifdef ASSEMBLY
 126 #define REQUIRING_SYMBOL( symbol )                              \
 127         .equ __requiring_symbol__, symbol
 128 #else
 129 #define REQUIRING_SYMBOL( symbol )                              \
 130         __asm__ ( ".equ __requiring_symbol__, " #symbol )
 131 #endif
 132
 133 /**
 134  * Provide a file's requiring symbol
 135  *
 136  * If the file contains no symbols that can be used as the requiring
 137  * symbol, you can provide a dummy one-byte-long symbol using
 138  * PROVIDE_REQUIRING_SYMBOL().
 139  */
 140 #ifdef ASSEMBLY
 141 #define PROVIDE_REQUIRING_SYMBOL()                              \
 142         .section ".tbl.requiring_symbols", "a", @progbits ;     \
 143         __requiring_symbol__:   .byte 0 ;                       \
 144         .size __requiring_symbol__, . - __requiring_symbol__ ;  \
 145         .previous
 146 #else
 147 #define PROVIDE_REQUIRING_SYMBOL()                              \
 148         __asm__ ( ".section \".tbl.requiring_symbols\", "       \
 149                   "         \"a\", @progbits\n"                 \
 150                   "__requiring_symbol__:\t.byte 0\n"            \
 151                   ".size __requiring_symbol__, "                \
 152                   "      . - __requiring_symbol__\n"            \
 153                   ".previous" )
 154 #endif
 155
 156 /** @} */
 157
 158 /**
 159  * @defgroup objmacros Macros to provide or require explicit objects
 160  * @{
 161  */
 162
 163 #define PREFIX_OBJECT( _prefix ) _C2 ( _prefix, OBJECT )
 164 #define OBJECT_SYMBOL PREFIX_OBJECT ( obj_ )
 165
 166 /** Always provide the symbol for the current object (defined by -DOBJECT) */
 167 PROVIDE_SYMBOL ( OBJECT_SYMBOL );
 168
 169 /**
 170  * Request an object
 171  *
 172  * @v object            Object name
 173  *
 174  * Request an object to be included within the link.  If the object
 175  * cannot be found, the link will succeed anyway.
 176  */
 177 #define REQUEST_OBJECT( object ) REQUEST_SYMBOL ( obj_ ## object )
 178
 179 /**
 180  * Require an object
 181  *
 182  * @v object            Object name
 183  *
 184  * Require an object to be included within the link.  If the object
 185  * cannot be found, the link will fail.
 186  *
 187  * To use this macro within a file, you must also specify the file's
 188  * "requiring symbol" using the REQUIRING_SYMBOL() or
 189  * PROVIDE_REQUIRING_SYMBOL() macros.
 190  */
 191 #define REQUIRE_OBJECT( object ) REQUIRE_SYMBOL ( obj_ ## object )
 192
 193 /** @} */
 194
 195 /** Select file identifier for errno.h (if used) */
 196 #define ERRFILE PREFIX_OBJECT ( ERRFILE_ )
 197
 198 #ifndef ASSEMBLY
 199
 200 /** Declare a function as weak (use *before* the definition)
 201  *
 202  * Due to a bug in at least GCC 4.4.4 and earlier, weak symbols may be
 203  * inlined if they have hidden visibility (see above for why hidden
 204  * visibility is used).  This results in the non-weak symbol never
 205  * being used, so explicitly mark the function as noinline to prevent
 206  * inlining.
 207  */
 208 #define __weak          __attribute__ (( weak, noinline ))
 209
 210 #endif
 211
 212 /** @defgroup dbg Debugging infrastructure
 213  * @{
 214  */
 215
 216 /** @def DBG
 217  *
 218  * Print a debugging message.
 219  *
 220  * The debug level is set at build time by specifying the @c DEBUG=
 221  * parameter on the @c make command line.  For example, to enable
 222  * debugging for the PCI bus functions (in pci.c) in a @c .dsk image
 223  * for the @c rtl8139 card, you could use the command line
 224  *
 225  * @code
 226  *
 227  *   make bin/rtl8139.dsk DEBUG=pci
 228  *
 229  * @endcode
 230  *
 231  * This will enable the debugging statements (DBG()) in pci.c.  If
 232  * debugging is not enabled, DBG() statements will be ignored.
 233  *
 234  * You can enable debugging in several objects simultaneously by
 235  * separating them with commas, as in
 236  *
 237  * @code
 238  *
 239  *   make bin/rtl8139.dsk DEBUG=pci,buffer,heap
 240  *
 241  * @endcode
 242  *
 243  * You can increase the debugging level for an object by specifying it
 244  * with @c :N, where @c N is the level, as in
 245  *
 246  * @code
 247  *
 248  *   make bin/rtl8139.dsk DEBUG=pci,buffer:2,heap
 249  *
 250  * @endcode
 251  *
 252  * which would enable debugging for the PCI, buffer-handling and
 253  * heap-allocation code, with the buffer-handling code at level 2.
 254  *
 255  */
 256
 257 #ifndef DBGLVL_MAX
 258 #define NDEBUG
 259 #define DBGLVL_MAX 0
 260 #endif
 261
 262 #ifndef ASSEMBLY
 263
 264 /** printf() for debugging */
 265 extern void __attribute__ (( format ( printf, 1, 2 ) ))
 266 dbg_printf ( const char *fmt, ... );
 267 extern void dbg_autocolourise ( unsigned long id );
 268 extern void dbg_decolourise ( void );
 269 extern void dbg_hex_dump_da ( unsigned long dispaddr,
 270                               const void *data, unsigned long len );
 271 extern void dbg_md5_da ( unsigned long dispaddr,
 272                          const void *data, unsigned long len );
 273 extern void dbg_pause ( void );
 274 extern void dbg_more ( void );
 275
 276 /* Allow for selective disabling of enabled debug levels */
 277 #if DBGLVL_MAX
 278 int __debug_disable;
 279 #define DBGLVL ( DBGLVL_MAX & ~__debug_disable )
 280 #define DBG_DISABLE( level ) do {                               \
 281         __debug_disable |= (level);                             \
 282         } while ( 0 )
 283 #define DBG_ENABLE( level ) do {                                \
 284         __debug_disable &= ~(level);                            \
 285         } while ( 0 )
 286 #else
 287 #define DBGLVL 0
 288 #define DBG_DISABLE( level ) do { } while ( 0 )
 289 #define DBG_ENABLE( level ) do { } while ( 0 )
 290 #endif
 291
 292 #define DBGLVL_LOG      1
 293 #define DBG_LOG         ( DBGLVL & DBGLVL_LOG )
 294 #define DBGLVL_EXTRA    2
 295 #define DBG_EXTRA       ( DBGLVL & DBGLVL_EXTRA )
 296 #define DBGLVL_PROFILE  4
 297 #define DBG_PROFILE     ( DBGLVL & DBGLVL_PROFILE )
 298 #define DBGLVL_IO       8
 299 #define DBG_IO          ( DBGLVL & DBGLVL_IO )
 300
 301 /**
 302  * Print debugging message if we are at a certain debug level
 303  *
 304  * @v level             Debug level
 305  * @v ...               printf() argument list
 306  */
 307 #define DBG_IF( level, ... ) do {                               \
 308                 if ( DBG_ ## level ) {                          \
 309                         dbg_printf ( __VA_ARGS__ );             \
 310                 }                                               \
 311         } while ( 0 )
 312
 313 /**
 314  * Print a hex dump if we are at a certain debug level
 315  *
 316  * @v level             Debug level
 317  * @v dispaddr          Display address
 318  * @v data              Data to print
 319  * @v len               Length of data
 320  */
 321 #define DBG_HDA_IF( level, dispaddr, data, len )  do {          \
 322                 if ( DBG_ ## level ) {                          \
 323                         union {                                 \
 324                                 unsigned long ul;               \
 325                                 typeof ( dispaddr ) raw;        \
 326                         } da;                                   \
 327                         da.ul = 0;                              \
 328                         da.raw = dispaddr;                      \
 329                         dbg_hex_dump_da ( da.ul, data, len );   \
 330                 }                                               \
 331         } while ( 0 )
 332
 333 /**
 334  * Print a hex dump if we are at a certain debug level
 335  *
 336  * @v level             Debug level
 337  * @v data              Data to print
 338  * @v len               Length of data
 339  */
 340 #define DBG_HD_IF( level, data, len ) do {                      \
 341                 const void *_data = data;                       \
 342                 DBG_HDA_IF ( level, _data, _data, len );        \
 343         } while ( 0 )
 344
 345 /**
 346  * Print an MD5 checksum if we are at a certain debug level
 347  *
 348  * @v level             Debug level
 349  * @v dispaddr          Display address
 350  * @v data              Data to print
 351  * @v len               Length of data
 352  */
 353 #define DBG_MD5A_IF( level, dispaddr, data, len )  do {         \
 354                 if ( DBG_ ## level ) {                          \
 355                         union {                                 \
 356                                 unsigned long ul;               \
 357                                 typeof ( dispaddr ) raw;        \
 358                         } da;                                   \
 359                         da.ul = 0;                              \
 360                         da.raw = dispaddr;                      \
 361                         dbg_md5_da ( da.ul, data, len );        \
 362                 }                                               \
 363         } while ( 0 )
 364
 365 /**
 366  * Print an MD5 checksum if we are at a certain debug level
 367  *
 368  * @v level             Debug level
 369  * @v data              Data to print
 370  * @v len               Length of data
 371  */
 372 #define DBG_MD5_IF( level, data, len ) do {                     \
 373                 const void *_data = data;                       \
 374                 DBG_MD5A_IF ( level, _data, _data, len );       \
 375         } while ( 0 )
 376
 377 /**
 378  * Prompt for key press if we are at a certain debug level
 379  *
 380  * @v level             Debug level
 381  */
 382 #define DBG_PAUSE_IF( level ) do {                              \
 383                 if ( DBG_ ## level ) {                          \
 384                         dbg_pause();                            \
 385                 }                                               \
 386         } while ( 0 )
 387
 388 /**
 389  * Prompt for more output data if we are at a certain debug level
 390  *
 391  * @v level             Debug level
 392  */
 393 #define DBG_MORE_IF( level ) do {                               \
 394                 if ( DBG_ ## level ) {                          \
 395                         dbg_more();                             \
 396                 }                                               \
 397         } while ( 0 )
 398
 399 /**
 400  * Select colour for debug messages if we are at a certain debug level
 401  *
 402  * @v level             Debug level
 403  * @v id                Message stream ID
 404  */
 405 #define DBG_AC_IF( level, id ) do {                             \
 406                 if ( DBG_ ## level ) {                          \
 407                         union {                                 \
 408                                 unsigned long ul;               \
 409                                 typeof ( id ) raw;              \
 410                         } dbg_stream;                           \
 411                         dbg_stream.ul = 0;                      \
 412                         dbg_stream.raw = id;                    \
 413                         dbg_autocolourise ( dbg_stream.ul );    \
 414                 }                                               \
 415         } while ( 0 )
 416
 417 /**
 418  * Revert colour for debug messages if we are at a certain debug level
 419  *
 420  * @v level             Debug level
 421  */
 422 #define DBG_DC_IF( level ) do {                                 \
 423                 if ( DBG_ ## level ) {                          \
 424                         dbg_decolourise();                      \
 425                 }                                               \
 426         } while ( 0 )
 427
 428 /* Autocolourising versions of the DBGxxx_IF() macros */
 429
 430 #define DBGC_IF( level, id, ... ) do {                          \
 431                 DBG_AC_IF ( level, id );                        \
 432                 DBG_IF ( level, __VA_ARGS__ );                  \
 433                 DBG_DC_IF ( level );                            \
 434         } while ( 0 )
 435
 436 #define DBGC_HDA_IF( level, id, ... ) do {                      \
 437                 DBG_AC_IF ( level, id );                        \
 438                 DBG_HDA_IF ( level, __VA_ARGS__ );              \
 439                 DBG_DC_IF ( level );                            \
 440         } while ( 0 )
 441
 442 #define DBGC_HD_IF( level, id, ... ) do {                       \
 443                 DBG_AC_IF ( level, id );                        \
 444                 DBG_HD_IF ( level, __VA_ARGS__ );               \
 445                 DBG_DC_IF ( level );                            \
 446         } while ( 0 )
 447
 448 #define DBGC_MD5A_IF( level, id, ... ) do {                     \
 449                 DBG_AC_IF ( level, id );                        \
 450                 DBG_MD5A_IF ( level, __VA_ARGS__ );             \
 451                 DBG_DC_IF ( level );                            \
 452         } while ( 0 )
 453
 454 #define DBGC_MD5_IF( level, id, ... ) do {                      \
 455                 DBG_AC_IF ( level, id );                        \
 456                 DBG_MD5_IF ( level, __VA_ARGS__ );              \
 457                 DBG_DC_IF ( level );                            \
 458         } while ( 0 )
 459
 460 #define DBGC_PAUSE_IF( level, id ) do {                         \
 461                 DBG_AC_IF ( level, id );                        \
 462                 DBG_PAUSE_IF ( level );                         \
 463                 DBG_DC_IF ( level );                            \
 464         } while ( 0 )
 465
 466 #define DBGC_MORE_IF( level, id ) do {                          \
 467                 DBG_AC_IF ( level, id );                        \
 468                 DBG_MORE_IF ( level );                          \
 469                 DBG_DC_IF ( level );                            \
 470         } while ( 0 )
 471
 472 /* Versions of the DBGxxx_IF() macros that imply DBGxxx_IF( LOG, ... )*/
 473
 474 #define DBG( ... )              DBG_IF          ( LOG, ##__VA_ARGS__ )
 475 #define DBG_HDA( ... )          DBG_HDA_IF      ( LOG, ##__VA_ARGS__ )
 476 #define DBG_HD( ... )           DBG_HD_IF       ( LOG, ##__VA_ARGS__ )
 477 #define DBG_MD5A( ... )         DBG_MD5A_IF     ( LOG, ##__VA_ARGS__ )
 478 #define DBG_MD5( ... )          DBG_MD5_IF      ( LOG, ##__VA_ARGS__ )
 479 #define DBG_PAUSE( ... )        DBG_PAUSE_IF    ( LOG, ##__VA_ARGS__ )
 480 #define DBG_MORE( ... )         DBG_MORE_IF     ( LOG, ##__VA_ARGS__ )
 481 #define DBGC( ... )             DBGC_IF         ( LOG, ##__VA_ARGS__ )
 482 #define DBGC_HDA( ... )         DBGC_HDA_IF     ( LOG, ##__VA_ARGS__ )
 483 #define DBGC_HD( ... )          DBGC_HD_IF      ( LOG, ##__VA_ARGS__ )
 484 #define DBGC_MD5A( ... )        DBGC_MD5A_IF    ( LOG, ##__VA_ARGS__ )
 485 #define DBGC_MD5( ... )         DBGC_MD5_IF     ( LOG, ##__VA_ARGS__ )
 486 #define DBGC_PAUSE( ... )       DBGC_PAUSE_IF   ( LOG, ##__VA_ARGS__ )
 487 #define DBGC_MORE( ... )        DBGC_MORE_IF    ( LOG, ##__VA_ARGS__ )
 488
 489 /* Versions of the DBGxxx_IF() macros that imply DBGxxx_IF( EXTRA, ... )*/
 490
 491 #define DBG2( ... )             DBG_IF          ( EXTRA, ##__VA_ARGS__ )
 492 #define DBG2_HDA( ... )         DBG_HDA_IF      ( EXTRA, ##__VA_ARGS__ )
 493 #define DBG2_HD( ... )          DBG_HD_IF       ( EXTRA, ##__VA_ARGS__ )
 494 #define DBG2_MD5A( ... )        DBG_MD5A_IF     ( EXTRA, ##__VA_ARGS__ )
 495 #define DBG2_MD5( ... )         DBG_MD5_IF      ( EXTRA, ##__VA_ARGS__ )
 496 #define DBG2_PAUSE( ... )       DBG_PAUSE_IF    ( EXTRA, ##__VA_ARGS__ )
 497 #define DBG2_MORE( ... )        DBG_MORE_IF     ( EXTRA, ##__VA_ARGS__ )
 498 #define DBGC2( ... )            DBGC_IF         ( EXTRA, ##__VA_ARGS__ )
 499 #define DBGC2_HDA( ... )        DBGC_HDA_IF     ( EXTRA, ##__VA_ARGS__ )
 500 #define DBGC2_HD( ... )         DBGC_HD_IF      ( EXTRA, ##__VA_ARGS__ )
 501 #define DBGC2_MD5A( ... )       DBGC_MD5A_IF    ( EXTRA, ##__VA_ARGS__ )
 502 #define DBGC2_MD5( ... )        DBGC_MD5_IF     ( EXTRA, ##__VA_ARGS__ )
 503 #define DBGC2_PAUSE( ... )      DBGC_PAUSE_IF   ( EXTRA, ##__VA_ARGS__ )
 504 #define DBGC2_MORE( ... )       DBGC_MORE_IF    ( EXTRA, ##__VA_ARGS__ )
 505
 506 /* Versions of the DBGxxx_IF() macros that imply DBGxxx_IF( PROFILE, ... )*/
 507
 508 #define DBGP( ... )             DBG_IF          ( PROFILE, ##__VA_ARGS__ )
 509 #define DBGP_HDA( ... )         DBG_HDA_IF      ( PROFILE, ##__VA_ARGS__ )
 510 #define DBGP_HD( ... )          DBG_HD_IF       ( PROFILE, ##__VA_ARGS__ )
 511 #define DBGP_MD5A( ... )        DBG_MD5A_IF     ( PROFILE, ##__VA_ARGS__ )
 512 #define DBGP_MD5( ... )         DBG_MD5_IF      ( PROFILE, ##__VA_ARGS__ )
 513 #define DBGP_PAUSE( ... )       DBG_PAUSE_IF    ( PROFILE, ##__VA_ARGS__ )
 514 #define DBGP_MORE( ... )        DBG_MORE_IF     ( PROFILE, ##__VA_ARGS__ )
 515 #define DBGCP( ... )            DBGC_IF         ( PROFILE, ##__VA_ARGS__ )
 516 #define DBGCP_HDA( ... )        DBGC_HDA_IF     ( PROFILE, ##__VA_ARGS__ )
 517 #define DBGCP_HD( ... )         DBGC_HD_IF      ( PROFILE, ##__VA_ARGS__ )
 518 #define DBGCP_MD5A( ... )       DBGC_MD5A_IF    ( PROFILE, ##__VA_ARGS__ )
 519 #define DBGCP_MD5( ... )        DBGC_MD5_IF     ( PROFILE, ##__VA_ARGS__ )
 520 #define DBGCP_PAUSE( ... )      DBGC_PAUSE_IF   ( PROFILE, ##__VA_ARGS__ )
 521 #define DBGCP_MORE( ... )       DBGC_MORE_IF    ( PROFILE, ##__VA_ARGS__ )
 522
 523 /* Versions of the DBGxxx_IF() macros that imply DBGxxx_IF( IO, ... )*/
 524
 525 #define DBGIO( ... )            DBG_IF          ( IO, ##__VA_ARGS__ )
 526 #define DBGIO_HDA( ... )        DBG_HDA_IF      ( IO, ##__VA_ARGS__ )
 527 #define DBGIO_HD( ... )         DBG_HD_IF       ( IO, ##__VA_ARGS__ )
 528 #define DBGIO_MD5A( ... )       DBG_MD5A_IF     ( IO, ##__VA_ARGS__ )
 529 #define DBGIO_MD5( ... )        DBG_MD5_IF      ( IO, ##__VA_ARGS__ )
 530 #define DBGIO_PAUSE( ... )      DBG_PAUSE_IF    ( IO, ##__VA_ARGS__ )
 531 #define DBGIO_MORE( ... )       DBG_MORE_IF     ( IO, ##__VA_ARGS__ )
 532 #define DBGCIO( ... )           DBGC_IF         ( IO, ##__VA_ARGS__ )
 533 #define DBGCIO_HDA( ... )       DBGC_HDA_IF     ( IO, ##__VA_ARGS__ )
 534 #define DBGCIO_HD( ... )        DBGC_HD_IF      ( IO, ##__VA_ARGS__ )
 535 #define DBGCIO_MD5A( ... )      DBGC_MD5A_IF    ( IO, ##__VA_ARGS__ )
 536 #define DBGCIO_MD5( ... )       DBGC_MD5_IF     ( IO, ##__VA_ARGS__ )
 537 #define DBGCIO_PAUSE( ... )     DBGC_PAUSE_IF   ( IO, ##__VA_ARGS__ )
 538 #define DBGCIO_MORE( ... )      DBGC_MORE_IF    ( IO, ##__VA_ARGS__ )
 539
 540 #endif /* ASSEMBLY */
 541 /** @} */
 542
 543 /** @defgroup attrs Miscellaneous attributes
 544  * @{
 545  */
 546 #ifndef ASSEMBLY
 547
 548 /** Declare a variable or data structure as unused. */
 549 #define __unused __attribute__ (( unused ))
 550
 551 /**
 552  * Declare a function as pure - i.e. without side effects
 553  */
 554 #define __pure __attribute__ (( pure ))
 555
 556 /**
 557  * Declare a function as const - i.e. it does not access global memory
 558  * (including dereferencing pointers passed to it) at all.
 559  * Must also not call any non-const functions.
 560  */
 561 #define __const __attribute__ (( const ))
 562
 563 /**
 564  * Declare a function's pointer parameters as non-null - i.e. force
 565  * compiler to check pointers at compile time and enable possible
 566  * optimizations based on that fact
 567  */
 568 #define __nonnull __attribute__ (( nonnull ))
 569
 570 /**
 571  * Declare a pointer returned by a function as a unique memory address
 572  * as returned by malloc-type functions.
 573  */
 574 #define __malloc __attribute__ (( malloc ))
 575
 576 /**
 577  * Declare a function as used.
 578  *
 579  * Necessary only if the function is called only from assembler code.
 580  */
 581 #define __used __attribute__ (( used ))
 582
 583 /** Declare a data structure to be aligned with 16-byte alignment */
 584 #define __aligned __attribute__ (( aligned ( 16 ) ))
 585
 586 /** Declare a function to be always inline */
 587 #define __always_inline __attribute__ (( always_inline ))
 588
 589 /* Force all inline functions to not be instrumented
 590  *
 591  * This is required to cope with what seems to be a long-standing gcc
 592  * bug, in which -finstrument-functions will cause instances of
 593  * inlined functions to be reported as further calls to the
 594  * *containing* function.  This makes instrumentation very difficult
 595  * to use.
 596  *
 597  * Work around this problem by adding the no_instrument_function
 598  * attribute to all inlined functions.
 599  */
 600 #define inline inline __attribute__ (( no_instrument_function ))
 601
 602 /**
 603  * Shared data.
 604  *
 605  * To save space in the binary when multiple-driver images are
 606  * compiled, uninitialised data areas can be shared between drivers.
 607  * This will typically be used to share statically-allocated receive
 608  * and transmit buffers between drivers.
 609  *
 610  * Use as e.g.
 611  *
 612  * @code
 613  *
 614  *   struct {
 615  *      char    rx_buf[NUM_RX_BUF][RX_BUF_SIZE];
 616  *      char    tx_buf[TX_BUF_SIZE];
 617  *   } my_static_data __shared;
 618  *
 619  * @endcode
 620  *
 621  */
 622 #define __shared __asm__ ( "_shared_bss" ) __aligned
 623
 624 #endif /* ASSEMBLY */
 625 /** @} */
 626
 627 /**
 628  * Optimisation barrier
 629  */
 630 #ifndef ASSEMBLY
 631 #define barrier() __asm__ __volatile__ ( "" : : : "memory" )
 632 #endif /* ASSEMBLY */
 633
 634 /**
 635  * @defgroup licences Licence declarations
 636  *
 637  * For reasons that are partly historical, various different files
 638  * within the iPXE codebase have differing licences.
 639  *
 640  * @{
 641  */
 642
 643 /** Declare a file as being in the public domain
 644  *
 645  * This licence declaration is applicable when a file states itself to
 646  * be in the public domain.
 647  */
 648 #define FILE_LICENCE_PUBLIC_DOMAIN \
 649         PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__public_domain__ ) )
 650
 651 /** Declare a file as being under version 2 (or later) of the GNU GPL
 652  *
 653  * This licence declaration is applicable when a file states itself to
 654  * be licensed under the GNU GPL; "either version 2 of the License, or
 655  * (at your option) any later version".
 656  */
 657 #define FILE_LICENCE_GPL2_OR_LATER \
 658         PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__gpl2_or_later__ ) )
 659
 660 /** Declare a file as being under version 2 of the GNU GPL
 661  *
 662  * This licence declaration is applicable when a file states itself to
 663  * be licensed under version 2 of the GPL, and does not include the
 664  * "or, at your option, any later version" clause.
 665  */
 666 #define FILE_LICENCE_GPL2_ONLY \
 667         PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__gpl2_only__ ) )
 668
 669 /** Declare a file as being under any version of the GNU GPL
 670  *
 671  * This licence declaration is applicable when a file states itself to
 672  * be licensed under the GPL, but does not specify a version.
 673  *
 674  * According to section 9 of the GPLv2, "If the Program does not
 675  * specify a version number of this License, you may choose any
 676  * version ever published by the Free Software Foundation".
 677  */
 678 #define FILE_LICENCE_GPL_ANY \
 679         PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__gpl_any__ ) )
 680
 681 /** Declare a file as being under the three-clause BSD licence
 682  *
 683  * This licence declaration is applicable when a file states itself to
 684  * be licensed under terms allowing redistribution in source and
 685  * binary forms (with or without modification) provided that:
 686  *
 687  *     redistributions of source code retain the copyright notice,
 688  *     list of conditions and any attached disclaimers
 689  *
 690  *     redistributions in binary form reproduce the copyright notice,
 691  *     list of conditions and any attached disclaimers in the
 692  *     documentation and/or other materials provided with the
 693  *     distribution
 694  *
 695  *     the name of the author is not used to endorse or promote
 696  *     products derived from the software without specific prior
 697  *     written permission
 698  *
 699  * It is not necessary for the file to explicitly state that it is
 700  * under a "BSD" licence; only that the licensing terms be
 701  * functionally equivalent to the standard three-clause BSD licence.
 702  */
 703 #define FILE_LICENCE_BSD3 \
 704         PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__bsd3__ ) )
 705
 706 /** Declare a file as being under the two-clause BSD licence
 707  *
 708  * This licence declaration is applicable when a file states itself to
 709  * be licensed under terms allowing redistribution in source and
 710  * binary forms (with or without modification) provided that:
 711  *
 712  *     redistributions of source code retain the copyright notice,
 713  *     list of conditions and any attached disclaimers
 714  *
 715  *     redistributions in binary form reproduce the copyright notice,
 716  *     list of conditions and any attached disclaimers in the
 717  *     documentation and/or other materials provided with the
 718  *     distribution
 719  *
 720  * It is not necessary for the file to explicitly state that it is
 721  * under a "BSD" licence; only that the licensing terms be
 722  * functionally equivalent to the standard two-clause BSD licence.
 723  */
 724 #define FILE_LICENCE_BSD2 \
 725         PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__bsd2__ ) )
 726
 727 /** Declare a file as being under the one-clause MIT-style licence
 728  *
 729  * This licence declaration is applicable when a file states itself to
 730  * be licensed under terms allowing redistribution for any purpose
 731  * with or without fee, provided that the copyright notice and
 732  * permission notice appear in all copies.
 733  */
 734 #define FILE_LICENCE_MIT \
 735         PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__mit__ ) )
 736
 737 /** Declare a file as being under GPLv2+ or UBDL
 738  *
 739  * This licence declaration is applicable when a file states itself to
 740  * be licensed under the GNU GPL; "either version 2 of the License, or
 741  * (at your option) any later version" and also states that it may be
 742  * distributed under the terms of the Unmodified Binary Distribution
 743  * Licence (as given in the file COPYING.UBDL).
 744  */
 745 #define FILE_LICENCE_GPL2_OR_LATER_OR_UBDL \
 746         PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__gpl2_or_later_or_ubdl__ ) )
 747
 748 /** Declare a particular licence as applying to a file */
 749 #define FILE_LICENCE( _licence ) FILE_LICENCE_ ## _licence
 750
 751 /** @} */
 752
 753 /* This file itself is under GPLv2+/UBDL */
 754 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
 755
 756 #include <bits/compiler.h>
 757
 758 #endif /* COMPILER_H */