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