compiler.h

Go to the documentation of this file.

#ifndef COMPILER_H
#define COMPILER_H
 
/*
 * Doxygen can't cope with some of the more esoteric areas of C, so we
 * make its life simpler.
 *
 */
#ifdef DOXYGEN
#define __attribute__(x)
#endif
 
/** @file
 *
 * Global compiler definitions.
 *
 * This file is implicitly included by every @c .c file in Etherboot.
 * It defines global macros such as DBG().
 *
 * We arrange for each object to export the symbol @c obj_OBJECT
 * (where @c OBJECT is the object name, e.g. @c rtl8139) as a global
 * symbol, so that the linker can drag in selected object files from
 * the library using <tt> -u obj_OBJECT </tt>.
 *
 */
 
/* Force visibility of all symbols to "hidden", i.e. inform gcc that
 * all symbol references resolve strictly within our final binary.
 * This avoids unnecessary PLT/GOT entries on x86_64.
 *
 * This is a stronger claim than specifying "-fvisibility=hidden",
 * since it also affects symbols marked with "extern".
 */
#ifndef ASSEMBLY
#if __GNUC__ >= 4
#pragma GCC visibility push(hidden)
#endif
#endif /* ASSEMBLY */
 
#undef _S1
#undef _S2
#undef _C1
#undef _C2
 
/** Concatenate non-expanded arguments */
#define _C1( x, y ) x ## y
/** Concatenate expanded arguments */
#define _C2( x, y ) _C1 ( x, y )
 
/** Stringify non-expanded argument */
#define _S1( x ) #x
/** Stringify expanded argument */
#define _S2( x ) _S1 ( x )
 
/* Assembler section types */
#ifdef ASSEMBLY
#define PROGBITS _C2 ( ASM_TCHAR, progbits )
#define NOBITS _C2 ( ASM_TCHAR, nobits )
#else
#define PROGBITS_OPS _S2 ( ASM_TCHAR_OPS ) "progbits"
#define PROGBITS _S2 ( ASM_TCHAR ) "progbits"
#define NOBITS_OPS _S2 ( ASM_TCHAR_OPS ) "nobits"
#define NOBITS _S2 ( ASM_TCHAR ) "nobits"
#endif
 
/**
 * @defgroup symmacros Macros to provide or require explicit symbols
 * @{
 */
 
/**
 * Provide a symbol within this object file
 *
 * @v symbol            Symbol name
 */
#ifdef ASSEMBLY
#define PROVIDE_SYMBOL( symbol )                                \
        .section ".provided", "a", NOBITS ;                     \
        .hidden symbol ;                                        \
        .globl  symbol ;                                        \
        symbol: ;                                               \
        .previous
#else
#define PROVIDE_SYMBOL( symbol )                                \
        char symbol[0]                                          \
          __attribute__ (( section ( ".provided" ) ))
#endif
 
/**
 * Request a symbol
 *
 * @v symbol            Symbol name
 *
 * Request a symbol to be included within the link.  If the symbol
 * cannot be found, the link will succeed anyway.
 */
#ifdef ASSEMBLY
#define REQUEST_SYMBOL( symbol )                                \
        .equ __request_ ## symbol, symbol
#else
#define REQUEST_SYMBOL( symbol )                                \
        __asm__ ( ".equ __request_" #symbol ", " #symbol )
#endif
 
/**
 * Require a symbol
 *
 * @v symbol            Symbol name
 *
 * Require a symbol to be included within the link.  If the symbol
 * cannot be found, the link will fail.
 *
 * To use this macro within a file, you must also specify the file's
 * "requiring symbol" using the REQUIRING_SYMBOL() or
 * PROVIDE_REQUIRING_SYMBOL() macros.
 */
#ifdef ASSEMBLY
#define REQUIRE_SYMBOL( symbol )                                \
        .reloc __requiring_symbol__, RELOC_TYPE_NONE, symbol
#else
#define REQUIRE_SYMBOL( symbol )                                \
        __asm__ ( ".reloc __requiring_symbol__, "               \
                  _S2 ( RELOC_TYPE_NONE ) ", " #symbol )
#endif
 
/**
 * Specify the file's requiring symbol
 *
 * @v symbol            Symbol name
 *
 * REQUIRE_SYMBOL() works by defining a dummy relocation record
 * against a nominated "requiring symbol".  The presence of the
 * nominated requiring symbol will drag in all of the symbols
 * specified using REQUIRE_SYMBOL().
 */
#ifdef ASSEMBLY
#define REQUIRING_SYMBOL( symbol )                              \
        .equ __requiring_symbol__, symbol
#else
#define REQUIRING_SYMBOL( symbol )                              \
        __asm__ ( ".equ __requiring_symbol__, " #symbol )
#endif
 
/**
 * Provide a file's requiring symbol
 *
 * If the file contains no symbols that can be used as the requiring
 * symbol, you can provide a dummy one-byte-long symbol using
 * PROVIDE_REQUIRING_SYMBOL().
 */
#ifdef ASSEMBLY
#define PROVIDE_REQUIRING_SYMBOL()                              \
        .section ".tbl.requiring_symbols", "a", PROGBITS ;      \
        __requiring_symbol__:   .byte 0 ;                       \
        .size __requiring_symbol__, . - __requiring_symbol__ ;  \
        .previous
#else
#define PROVIDE_REQUIRING_SYMBOL()                              \
        __asm__ ( ".section \".tbl.requiring_symbols\", "       \
                  "         \"a\", " PROGBITS "\n"              \
                  "__requiring_symbol__:\t.byte 0\n"            \
                  ".size __requiring_symbol__, "                \
                  "      . - __requiring_symbol__\n"            \
                  ".previous" )
#endif
 
/** @} */
 
/**
 * @defgroup ipxenote Macros to provide ELF notes
 * @{
 */
 
/* Construct an iPXE-specific ELF note */
#define IPXE_NOTE( type )                                       \
        __asm__ ( ".section \".note.ipxe\", \"\", "             \
                  _S2 ( ASM_TCHAR ) "note\n\t"                  \
                  /* Owner name length */                       \
                  ".long 4\n\t"                                 \
                  /* Content length */                          \
                  ".long 0\n\t"                                 \
                  /* Type */                                    \
                  ".long " _S2 ( _C2 ( IPXE_NOTE_, type ) )     \
                  "\n\t"                                        \
                  /* Owner name */                              \
                  ".ascii \"iPXE\"\n\t"                         \
                  ".previous\n\t" )
 
/** Build will use a disk-based console log, if present */
#define IPXE_NOTE_DISKLOG 0x18aed109
 
/** @} */
 
/**
 * @defgroup objmacros Macros to provide or require explicit objects
 * @{
 */
 
#define PREFIX_OBJECT( _prefix ) _C2 ( _prefix, OBJECT )
#define OBJECT_SYMBOL PREFIX_OBJECT ( obj_ )
 
/** Always provide the symbol for the current object (defined by -DOBJECT) */
PROVIDE_SYMBOL ( OBJECT_SYMBOL );
 
/**
 * Request an object
 *
 * @v object            Object name
 *
 * Request an object to be included within the link.  If the object
 * cannot be found, the link will succeed anyway.
 */
#define REQUEST_OBJECT( object ) REQUEST_SYMBOL ( obj_ ## object )
 
/**
 * Require an object
 *
 * @v object            Object name
 *
 * Require an object to be included within the link.  If the object
 * cannot be found, the link will fail.
 *
 * To use this macro within a file, you must also specify the file's
 * "requiring symbol" using the REQUIRING_SYMBOL() or
 * PROVIDE_REQUIRING_SYMBOL() macros.
 */
#define REQUIRE_OBJECT( object ) REQUIRE_SYMBOL ( obj_ ## object )
 
/** @} */
 
/** Select file identifier for errno.h (if used) */
#define ERRFILE PREFIX_OBJECT ( ERRFILE_ )
 
#ifndef ASSEMBLY
 
/** Declare a function as weak (use *before* the definition)
 *
 * Due to a bug in at least GCC 4.4.4 and earlier, weak symbols may be
 * inlined if they have hidden visibility (see above for why hidden
 * visibility is used).  This results in the non-weak symbol never
 * being used, so explicitly mark the function as noinline to prevent
 * inlining.
 */
#define __weak          __attribute__ (( weak, noinline ))
 
#endif
 
/** @defgroup dbg Debugging infrastructure
 * @{
 */
 
/** @def DBG
 *
 * Print a debugging message.
 *
 * The debug level is set at build time by specifying the @c DEBUG=
 * parameter on the @c make command line.  For example, to enable
 * debugging for the PCI bus functions (in pci.c) in a @c .dsk image
 * for the @c rtl8139 card, you could use the command line
 *
 * @code
 *
 *   make bin/rtl8139.dsk DEBUG=pci
 *
 * @endcode
 *
 * This will enable the debugging statements (DBG()) in pci.c.  If
 * debugging is not enabled, DBG() statements will be ignored.
 *
 * You can enable debugging in several objects simultaneously by
 * separating them with commas, as in
 *
 * @code
 *
 *   make bin/rtl8139.dsk DEBUG=pci,buffer,heap
 *
 * @endcode
 *
 * You can increase the debugging level for an object by specifying it
 * with @c :N, where @c N is the level, as in
 *
 * @code
 *
 *   make bin/rtl8139.dsk DEBUG=pci,buffer:2,heap
 *
 * @endcode
 *
 * which would enable debugging for the PCI, buffer-handling and
 * heap-allocation code, with the buffer-handling code at level 2.
 *
 */
 
#ifndef DBGLVL_MAX
#define NDEBUG
#define DBGLVL_MAX 0
#endif
 
#ifndef DBGLVL_DFLT
#define DBGLVL_DFLT DBGLVL_MAX
#endif
 
#ifndef ASSEMBLY
 
/** printf() for debugging */
extern void __attribute__ (( format ( printf, 1, 2 ) ))
dbg_printf ( const char *fmt, ... );
extern void dbg_autocolourise ( unsigned long id );
extern void dbg_decolourise ( void );
extern void dbg_hex_dump_da ( unsigned long dispaddr,
                              const void *data, unsigned long len );
extern void dbg_md5_da ( unsigned long dispaddr,
                         const void *data, unsigned long len );
extern void dbg_pause ( void );
extern void dbg_more ( void );
 
/* Allow for selective disabling of enabled debug levels */
#define __debug_disable( object ) _C2 ( __debug_disable_, object )
char __debug_disable(OBJECT) = ( DBGLVL_MAX & ~DBGLVL_DFLT );
#define DBG_DISABLE_OBJECT( object, level ) do {                \
        extern char __debug_disable(object);                    \
        __debug_disable(object) |= (level);                     \
        } while ( 0 )
#define DBG_ENABLE_OBJECT( object, level ) do {                 \
        extern char __debug_disable(object);                    \
        __debug_disable(object) &= ~(level);                    \
        } while ( 0 )
#if DBGLVL_MAX
#define DBGLVL ( DBGLVL_MAX & ~__debug_disable(OBJECT) )
#define DBG_DISABLE( level ) do {                               \
        __debug_disable(OBJECT) |= ( (level) & DBGLVL_MAX );    \
        } while ( 0 )
#define DBG_ENABLE( level ) do {                                \
        __debug_disable(OBJECT) &= ~( (level) & DBGLVL_MAX );   \
        } while ( 0 )
#else
#define DBGLVL 0
#define DBG_DISABLE( level ) do { } while ( 0 )
#define DBG_ENABLE( level ) do { } while ( 0 )
#endif
 
#define DBGLVL_LOG      1
#define DBG_LOG         ( DBGLVL & DBGLVL_LOG )
#define DBGLVL_EXTRA    2
#define DBG_EXTRA       ( DBGLVL & DBGLVL_EXTRA )
#define DBGLVL_PROFILE  4
#define DBG_PROFILE     ( DBGLVL & DBGLVL_PROFILE )
#define DBGLVL_IO       8
#define DBG_IO          ( DBGLVL & DBGLVL_IO )
 
/**
 * Print debugging message if we are at a certain debug level
 *
 * @v level             Debug level
 * @v ...               printf() argument list
 */
#define DBG_IF( level, ... ) do {                               \
                if ( DBG_ ## level ) {                          \
                        dbg_printf ( __VA_ARGS__ );             \
                }                                               \
        } while ( 0 )
 
/**
 * Print a hex dump if we are at a certain debug level
 *
 * @v level             Debug level
 * @v dispaddr          Display address
 * @v data              Data to print
 * @v len               Length of data
 */
#define DBG_HDA_IF( level, dispaddr, data, len )  do {          \
                if ( DBG_ ## level ) {                          \
                        union {                                 \
                                unsigned long ul;               \
                                typeof ( dispaddr ) raw;        \
                        } da;                                   \
                        da.ul = 0;                              \
                        da.raw = dispaddr;                      \
                        dbg_hex_dump_da ( da.ul, data, len );   \
                }                                               \
        } while ( 0 )
 
/**
 * Print a hex dump if we are at a certain debug level
 *
 * @v level             Debug level
 * @v data              Data to print
 * @v len               Length of data
 */
#define DBG_HD_IF( level, data, len ) do {                      \
                const void *_data = data;                       \
                DBG_HDA_IF ( level, _data, _data, len );        \
        } while ( 0 )
 
/**
 * Print an MD5 checksum if we are at a certain debug level
 *
 * @v level             Debug level
 * @v dispaddr          Display address
 * @v data              Data to print
 * @v len               Length of data
 */
#define DBG_MD5A_IF( level, dispaddr, data, len )  do {         \
                if ( DBG_ ## level ) {                          \
                        union {                                 \
                                unsigned long ul;               \
                                typeof ( dispaddr ) raw;        \
                        } da;                                   \
                        da.ul = 0;                              \
                        da.raw = dispaddr;                      \
                        dbg_md5_da ( da.ul, data, len );        \
                }                                               \
        } while ( 0 )
 
/**
 * Print an MD5 checksum if we are at a certain debug level
 *
 * @v level             Debug level
 * @v data              Data to print
 * @v len               Length of data
 */
#define DBG_MD5_IF( level, data, len ) do {                     \
                const void *_data = data;                       \
                DBG_MD5A_IF ( level, _data, _data, len );       \
        } while ( 0 )
 
/**
 * Prompt for key press if we are at a certain debug level
 *
 * @v level             Debug level
 */
#define DBG_PAUSE_IF( level, ... ) do {                         \
                if ( DBG_ ## level ) {                          \
                        dbg_pause();                            \
                }                                               \
        } while ( 0 )
 
/**
 * Prompt for more output data if we are at a certain debug level
 *
 * @v level             Debug level
 */
#define DBG_MORE_IF( level, ... ) do {                          \
                if ( DBG_ ## level ) {                          \
                        dbg_more();                             \
                }                                               \
        } while ( 0 )
 
/**
 * Select colour for debug messages if we are at a certain debug level
 *
 * @v level             Debug level
 * @v id                Message stream ID
 */
#define DBG_AC_IF( level, id ) do {                             \
                if ( DBG_ ## level ) {                          \
                        union {                                 \
                                unsigned long ul;               \
                                typeof ( id ) raw;              \
                        } dbg_stream;                           \
                        dbg_stream.ul = 0;                      \
                        dbg_stream.raw = id;                    \
                        dbg_autocolourise ( dbg_stream.ul );    \
                }                                               \
        } while ( 0 )
 
/**
 * Revert colour for debug messages if we are at a certain debug level
 *
 * @v level             Debug level
 */
#define DBG_DC_IF( level ) do {                                 \
                if ( DBG_ ## level ) {                          \
                        dbg_decolourise();                      \
                }                                               \
        } while ( 0 )
 
/* Autocolourising versions of the DBGxxx_IF() macros */
 
#define DBGC_IF( level, id, ... ) do {                          \
                DBG_AC_IF ( level, id );                        \
                DBG_IF ( level, __VA_ARGS__ );                  \
                DBG_DC_IF ( level );                            \
        } while ( 0 )
 
#define DBGC_HDA_IF( level, id, ... ) do {                      \
                DBG_AC_IF ( level, id );                        \
                DBG_HDA_IF ( level, __VA_ARGS__ );              \
                DBG_DC_IF ( level );                            \
        } while ( 0 )
 
#define DBGC_HD_IF( level, id, ... ) do {                       \
                DBG_AC_IF ( level, id );                        \
                DBG_HD_IF ( level, __VA_ARGS__ );               \
                DBG_DC_IF ( level );                            \
        } while ( 0 )
 
#define DBGC_MD5A_IF( level, id, ... ) do {                     \
                DBG_AC_IF ( level, id );                        \
                DBG_MD5A_IF ( level, __VA_ARGS__ );             \
                DBG_DC_IF ( level );                            \
        } while ( 0 )
 
#define DBGC_MD5_IF( level, id, ... ) do {                      \
                DBG_AC_IF ( level, id );                        \
                DBG_MD5_IF ( level, __VA_ARGS__ );              \
                DBG_DC_IF ( level );                            \
        } while ( 0 )
 
#define DBGC_PAUSE_IF( level, id ) do {                         \
                DBG_AC_IF ( level, id );                        \
                DBG_PAUSE_IF ( level );                         \
                DBG_DC_IF ( level );                            \
        } while ( 0 )
 
#define DBGC_MORE_IF( level, id ) do {                          \
                DBG_AC_IF ( level, id );                        \
                DBG_MORE_IF ( level );                          \
                DBG_DC_IF ( level );                            \
        } while ( 0 )
 
/* Versions of the DBGxxx_IF() macros that imply DBGxxx_IF( LOG, ... )*/
 
#define DBG( ... )              DBG_IF          ( LOG, ##__VA_ARGS__ )
#define DBG_HDA( ... )          DBG_HDA_IF      ( LOG, ##__VA_ARGS__ )
#define DBG_HD( ... )           DBG_HD_IF       ( LOG, ##__VA_ARGS__ )
#define DBG_MD5A( ... )         DBG_MD5A_IF     ( LOG, ##__VA_ARGS__ )
#define DBG_MD5( ... )          DBG_MD5_IF      ( LOG, ##__VA_ARGS__ )
#define DBG_PAUSE( ... )        DBG_PAUSE_IF    ( LOG, ##__VA_ARGS__ )
#define DBG_MORE( ... )         DBG_MORE_IF     ( LOG, ##__VA_ARGS__ )
#define DBGC( ... )             DBGC_IF         ( LOG, ##__VA_ARGS__ )
#define DBGC_HDA( ... )         DBGC_HDA_IF     ( LOG, ##__VA_ARGS__ )
#define DBGC_HD( ... )          DBGC_HD_IF      ( LOG, ##__VA_ARGS__ )
#define DBGC_MD5A( ... )        DBGC_MD5A_IF    ( LOG, ##__VA_ARGS__ )
#define DBGC_MD5( ... )         DBGC_MD5_IF     ( LOG, ##__VA_ARGS__ )
#define DBGC_PAUSE( ... )       DBGC_PAUSE_IF   ( LOG, ##__VA_ARGS__ )
#define DBGC_MORE( ... )        DBGC_MORE_IF    ( LOG, ##__VA_ARGS__ )
 
/* Versions of the DBGxxx_IF() macros that imply DBGxxx_IF( EXTRA, ... )*/
 
#define DBG2( ... )             DBG_IF          ( EXTRA, ##__VA_ARGS__ )
#define DBG2_HDA( ... )         DBG_HDA_IF      ( EXTRA, ##__VA_ARGS__ )
#define DBG2_HD( ... )          DBG_HD_IF       ( EXTRA, ##__VA_ARGS__ )
#define DBG2_MD5A( ... )        DBG_MD5A_IF     ( EXTRA, ##__VA_ARGS__ )
#define DBG2_MD5( ... )         DBG_MD5_IF      ( EXTRA, ##__VA_ARGS__ )
#define DBG2_PAUSE( ... )       DBG_PAUSE_IF    ( EXTRA, ##__VA_ARGS__ )
#define DBG2_MORE( ... )        DBG_MORE_IF     ( EXTRA, ##__VA_ARGS__ )
#define DBGC2( ... )            DBGC_IF         ( EXTRA, ##__VA_ARGS__ )
#define DBGC2_HDA( ... )        DBGC_HDA_IF     ( EXTRA, ##__VA_ARGS__ )
#define DBGC2_HD( ... )         DBGC_HD_IF      ( EXTRA, ##__VA_ARGS__ )
#define DBGC2_MD5A( ... )       DBGC_MD5A_IF    ( EXTRA, ##__VA_ARGS__ )
#define DBGC2_MD5( ... )        DBGC_MD5_IF     ( EXTRA, ##__VA_ARGS__ )
#define DBGC2_PAUSE( ... )      DBGC_PAUSE_IF   ( EXTRA, ##__VA_ARGS__ )
#define DBGC2_MORE( ... )       DBGC_MORE_IF    ( EXTRA, ##__VA_ARGS__ )
 
/* Versions of the DBGxxx_IF() macros that imply DBGxxx_IF( PROFILE, ... )*/
 
#define DBGP( ... )             DBG_IF          ( PROFILE, ##__VA_ARGS__ )
#define DBGP_HDA( ... )         DBG_HDA_IF      ( PROFILE, ##__VA_ARGS__ )
#define DBGP_HD( ... )          DBG_HD_IF       ( PROFILE, ##__VA_ARGS__ )
#define DBGP_MD5A( ... )        DBG_MD5A_IF     ( PROFILE, ##__VA_ARGS__ )
#define DBGP_MD5( ... )         DBG_MD5_IF      ( PROFILE, ##__VA_ARGS__ )
#define DBGP_PAUSE( ... )       DBG_PAUSE_IF    ( PROFILE, ##__VA_ARGS__ )
#define DBGP_MORE( ... )        DBG_MORE_IF     ( PROFILE, ##__VA_ARGS__ )
#define DBGCP( ... )            DBGC_IF         ( PROFILE, ##__VA_ARGS__ )
#define DBGCP_HDA( ... )        DBGC_HDA_IF     ( PROFILE, ##__VA_ARGS__ )
#define DBGCP_HD( ... )         DBGC_HD_IF      ( PROFILE, ##__VA_ARGS__ )
#define DBGCP_MD5A( ... )       DBGC_MD5A_IF    ( PROFILE, ##__VA_ARGS__ )
#define DBGCP_MD5( ... )        DBGC_MD5_IF     ( PROFILE, ##__VA_ARGS__ )
#define DBGCP_PAUSE( ... )      DBGC_PAUSE_IF   ( PROFILE, ##__VA_ARGS__ )
#define DBGCP_MORE( ... )       DBGC_MORE_IF    ( PROFILE, ##__VA_ARGS__ )
 
/* Versions of the DBGxxx_IF() macros that imply DBGxxx_IF( IO, ... )*/
 
#define DBGIO( ... )            DBG_IF          ( IO, ##__VA_ARGS__ )
#define DBGIO_HDA( ... )        DBG_HDA_IF      ( IO, ##__VA_ARGS__ )
#define DBGIO_HD( ... )         DBG_HD_IF       ( IO, ##__VA_ARGS__ )
#define DBGIO_MD5A( ... )       DBG_MD5A_IF     ( IO, ##__VA_ARGS__ )
#define DBGIO_MD5( ... )        DBG_MD5_IF      ( IO, ##__VA_ARGS__ )
#define DBGIO_PAUSE( ... )      DBG_PAUSE_IF    ( IO, ##__VA_ARGS__ )
#define DBGIO_MORE( ... )       DBG_MORE_IF     ( IO, ##__VA_ARGS__ )
#define DBGCIO( ... )           DBGC_IF         ( IO, ##__VA_ARGS__ )
#define DBGCIO_HDA( ... )       DBGC_HDA_IF     ( IO, ##__VA_ARGS__ )
#define DBGCIO_HD( ... )        DBGC_HD_IF      ( IO, ##__VA_ARGS__ )
#define DBGCIO_MD5A( ... )      DBGC_MD5A_IF    ( IO, ##__VA_ARGS__ )
#define DBGCIO_MD5( ... )       DBGC_MD5_IF     ( IO, ##__VA_ARGS__ )
#define DBGCIO_PAUSE( ... )     DBGC_PAUSE_IF   ( IO, ##__VA_ARGS__ )
#define DBGCIO_MORE( ... )      DBGC_MORE_IF    ( IO, ##__VA_ARGS__ )
 
#endif /* ASSEMBLY */
/** @} */
 
/** @defgroup attrs Miscellaneous attributes
 * @{
 */
#ifndef ASSEMBLY
 
/** Declare a variable or data structure as unused. */
#define __unused __attribute__ (( unused ))
 
/**
 * Declare a function as pure - i.e. without side effects
 */
#define __pure __attribute__ (( pure ))
 
/**
 * Declare a function as const - i.e. it does not access global memory
 * (including dereferencing pointers passed to it) at all.
 * Must also not call any non-const functions.
 */
#define __const __attribute__ (( const ))
 
/**
 * Declare a function's pointer parameters as non-null - i.e. force
 * compiler to check pointers at compile time and enable possible
 * optimizations based on that fact
 */
#define __nonnull __attribute__ (( nonnull ))
 
/**
 * Declare a pointer returned by a function as a unique memory address
 * as returned by malloc-type functions.
 */
#define __malloc __attribute__ (( malloc ))
 
/**
 * Declare a function as used.
 *
 * Necessary only if the function is called only from assembler code.
 */
#define __used __attribute__ (( used ))
 
/** Declare a data structure to be aligned with 16-byte alignment */
#define __aligned __attribute__ (( aligned ( 16 ) ))
 
/** Declare a function to be always inline */
#define __always_inline __attribute__ (( always_inline ))
 
/* Force all inline functions to not be instrumented
 *
 * This is required to cope with what seems to be a long-standing gcc
 * bug, in which -finstrument-functions will cause instances of
 * inlined functions to be reported as further calls to the
 * *containing* function.  This makes instrumentation very difficult
 * to use.
 *
 * Work around this problem by adding the no_instrument_function
 * attribute to all inlined functions.
 */
#define inline inline __attribute__ (( no_instrument_function ))
 
#endif /* ASSEMBLY */
/** @} */
 
/**
 * Optimisation barrier
 */
#ifndef ASSEMBLY
#define barrier() __asm__ __volatile__ ( "" : : : "memory" )
#endif /* ASSEMBLY */
 
/**
 * Array size
 */
#ifndef ASSEMBLY
#define ARRAY_SIZE(array) ( sizeof (array) / sizeof ( (array)[0] ) )
#endif /* ASSEMBLY */
 
/** @defgroup abs Absolute symbols
 * @{
 */
#ifndef ASSEMBLY
 
/** Declare an absolute symbol (e.g. a value defined by a linker script)
 *
 * Use as e.g.:
 *
 *    extern int ABS_SYMBOL ( _my_symbol );
 *
 */
#define ABS_SYMBOL( name ) name[]
 
/** Get value of an absolute symbol for use in a static initializer
 *
 * Use as e.g.:
 *
 *    extern int ABS_SYMBOL ( _my_symbol );
 *    static int my_symbol = ABS_VALUE_INIT ( _my_symbol );
 *
 * Note that the declared type must be at least as large as a pointer
 * type, since the compiler sees the absolute symbol as being an
 * address.
 */
#define ABS_VALUE_INIT( name ) ( ( typeof ( name[0] ) ) name )
 
/** Get value of an absolute symbol
 *
 * In a position-dependent executable, where all addresses are fixed
 * at link time, we can use the standard technique as documented by
 * GNU ld, e.g.:
 *
 *    extern char _my_symbol[];
 *
 *    printf ( "Absolute symbol value is %x\n", ( ( int ) _my_symbol ) );
 *
 * This technique may not work in a position-independent executable.
 * When dynamic relocations are applied, the runtime addresses will no
 * longer be equal to the link-time addresses.  If the code to obtain
 * the address of _my_symbol uses PC-relative addressing, then it
 * will calculate the runtime "address" of the absolute symbol, which
 * will no longer be equal the the link-time "address" (i.e. the
 * correct value) of the absolute symbol.
 *
 * We can work around this by instead declaring a static variable to
 * contain the absolute value, and returning the contents of this
 * static variable:
 *
 *    extern char _my_symbol[];
 *    static void * volatile my_symbol = _my_symbol;
 *
 *    printf ( "Absolute symbol value is %x\n", ( ( int ) my_symbol ) );
 *
 * The value of the static variable cannot possibly use PC-relative
 * addressing (since there is no applicable program counter for
 * non-code), and so will instead be filled in with the correct
 * absolute value at link time.  (No dynamic relocation will be
 * generated that might change its value, since the symbol providing
 * the value is an absolute symbol.)
 *
 * This second technique will work for both position-dependent and
 * position-independent code, but incurs the unnecssary overhead of an
 * additional static variable in position-dependent code.  The
 * ABS_VALUE() macro abstracts away these differences, using the most
 * efficient available technique.  Use as e.g.:
 *
 *    extern int ABS_SYMBOL ( _my_symbol );
 *    #define my_symbol ABS_VALUE ( _my_symbol )
 *
 *    printf ( "Absolute symbol value is %x\n", my_symbol );
 *
 * The ABS_VALUE() macro uses the (otherwise redundant) type declared
 * on the ABS_SYMBOL() array to automatically determine the correct
 * type for the ABS_VALUE() expression.
 *
 * Unlike ABS_VALUE_INIT(), there is no restriction that the type must
 * be at least as large as a pointer type.
 */
#ifndef __pie__
#define ABS_VALUE( name ) ( ( typeof ( name[0] ) ) ( intptr_t ) name )
#else
#define ABS_VALUE( name ) ( {                                           \
        static void * volatile static_ ## name = name;                  \
        ( ( typeof ( name[0] ) ) ( intptr_t ) static_ ## name );        \
        } )
#endif
 
#endif /* ASSEMBLY */
/** @} */
 
/**
 * @defgroup licences Licence declarations
 *
 * For reasons that are partly historical, various different files
 * within the iPXE codebase have differing licences.
 *
 * @{
 */
 
/** Declare a file as being in the public domain
 *
 * This licence declaration is applicable when a file states itself to
 * be in the public domain.
 */
#define FILE_LICENCE_PUBLIC_DOMAIN \
        PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__public_domain__ ) )
 
/** Declare a file as being under version 2 (or later) of the GNU GPL
 *
 * This licence declaration is applicable when a file states itself to
 * be licensed under the GNU GPL; "either version 2 of the License, or
 * (at your option) any later version".
 */
#define FILE_LICENCE_GPL2_OR_LATER \
        PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__gpl2_or_later__ ) )
 
/** Declare a file as being under version 2 of the GNU GPL
 *
 * This licence declaration is applicable when a file states itself to
 * be licensed under version 2 of the GPL, and does not include the
 * "or, at your option, any later version" clause.
 */
#define FILE_LICENCE_GPL2_ONLY \
        PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__gpl2_only__ ) )
 
/** Declare a file as being under any version of the GNU GPL
 *
 * This licence declaration is applicable when a file states itself to
 * be licensed under the GPL, but does not specify a version.
 *
 * According to section 9 of the GPLv2, "If the Program does not
 * specify a version number of this License, you may choose any
 * version ever published by the Free Software Foundation".
 */
#define FILE_LICENCE_GPL_ANY \
        PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__gpl_any__ ) )
 
/** Declare a file as being under the three-clause BSD licence
 *
 * This licence declaration is applicable when a file states itself to
 * be licensed under terms allowing redistribution in source and
 * binary forms (with or without modification) provided that:
 *
 *     redistributions of source code retain the copyright notice,
 *     list of conditions and any attached disclaimers
 *
 *     redistributions in binary form reproduce the copyright notice,
 *     list of conditions and any attached disclaimers in the
 *     documentation and/or other materials provided with the
 *     distribution
 *
 *     the name of the author is not used to endorse or promote
 *     products derived from the software without specific prior
 *     written permission
 *
 * It is not necessary for the file to explicitly state that it is
 * under a "BSD" licence; only that the licensing terms be
 * functionally equivalent to the standard three-clause BSD licence.
 */
#define FILE_LICENCE_BSD3 \
        PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__bsd3__ ) )
 
/** Declare a file as being under the two-clause BSD licence
 *
 * This licence declaration is applicable when a file states itself to
 * be licensed under terms allowing redistribution in source and
 * binary forms (with or without modification) provided that:
 *
 *     redistributions of source code retain the copyright notice,
 *     list of conditions and any attached disclaimers
 *
 *     redistributions in binary form reproduce the copyright notice,
 *     list of conditions and any attached disclaimers in the
 *     documentation and/or other materials provided with the
 *     distribution
 *
 * It is not necessary for the file to explicitly state that it is
 * under a "BSD" licence; only that the licensing terms be
 * functionally equivalent to the standard two-clause BSD licence.
 */
#define FILE_LICENCE_BSD2 \
        PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__bsd2__ ) )
 
/** Declare a file as being under the two-clause BSD plus patent licence
 *
 * This licence declaration is applicable when a file states itself to
 * be licensed under terms allowing redistribution in source and
 * binary forms (with or without modification) provided that:
 *
 *     redistributions of source code retain the copyright notice,
 *     list of conditions and any attached disclaimers
 *
 *     redistributions in binary form reproduce the copyright notice,
 *     list of conditions and any attached disclaimers in the
 *     documentation and/or other materials provided with the
 *     distribution
 *
 * and in addition states that
 *
 *     Subject to the terms and conditions of this license, each
 *     copyright holder and contributor hereby grants to those
 *     receiving rights under this license a perpetual, worldwide,
 *     non-exclusive, no-charge, royalty-free, irrevocable (except for
 *     failure to satisfy the conditions of this license) patent
 *     license to make, have made, use, offer to sell, sell, import,
 *     and otherwise transfer this software, where such license
 *     applies only to those patent claims, already acquired or
 *     hereafter acquired, licensable by such copyright holder or
 *     contributor that are necessarily infringed by:
 *
 *       their Contribution(s) (the licensed copyrights of copyright
 *       holders and non-copyrightable additions of contributors, in
 *       source or binary form) alone; or
 *
 *       combination of their Contribution(s) with the work of
 *       authorship to which such Contribution(s) was added by such
 *       copyright holder or contributor, if, at the time the
 *       Contribution is added, such addition causes such combination
 *       to be necessarily infringed. The patent license shall not
 *       apply to any other combinations which include the
 *       Contribution.
 *
 * It is not necessary for the file to explicitly state that it is
 * under a "BSD" licence; only that the licensing terms be
 * functionally equivalent to the standard two-clause BSD licence with
 * patent grant.
 */
#define FILE_LICENCE_BSD2_PATENT \
        PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__bsd2_patent__ ) )
 
/** Declare a file as being under the one-clause MIT-style licence
 *
 * This licence declaration is applicable when a file states itself to
 * be licensed under terms allowing redistribution for any purpose
 * with or without fee, provided that the copyright notice and
 * permission notice appear in all copies.
 */
#define FILE_LICENCE_MIT \
        PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__mit__ ) )
 
/** Declare a file as being under GPLv2+ or UBDL
 *
 * This licence declaration is applicable when a file states itself to
 * be licensed under the GNU GPL; "either version 2 of the License, or
 * (at your option) any later version" and also states that it may be
 * distributed under the terms of the Unmodified Binary Distribution
 * Licence (as given in the file COPYING.UBDL).
 */
#define FILE_LICENCE_GPL2_OR_LATER_OR_UBDL \
        PROVIDE_SYMBOL ( PREFIX_OBJECT ( __licence__gpl2_or_later_or_ubdl__ ) )
 
/** Declare a particular licence as applying to a file */
#define FILE_LICENCE( _licence ) FILE_LICENCE_ ## _licence
 
/** @} */
 
/* This file itself is under GPLv2+/UBDL */
FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
 
/**
 * @defgroup secboot UEFI Secure Boot restrictions
 *
 * Not all files within the iPXE codebase are allowed to be included
 * in UEFI Secure Boot signed builds.
 *
 * Files that are permitted in a UEFI Secure Boot build are subject to
 * stricter code review requirements.  In particular, contributions
 * from third parties may not be marked as permitted unless they have
 * passed an approved security review.
 *
 * @{
 */
 
/** Declare a file as being permitted in a UEFI Secure Boot build */
#define FILE_SECBOOT_PERMITTED \
        PROVIDE_SYMBOL ( PREFIX_OBJECT ( __secboot__permitted__ ) )
 
/** Declare a file as being forbidden in a UEFI Secure Boot build */
#define FILE_SECBOOT_FORBIDDEN \
        PROVIDE_SYMBOL ( PREFIX_OBJECT ( __secboot__forbidden__ ) )
 
/** Declare a file's UEFI Secure Boot permission status */
#define FILE_SECBOOT( _status ) FILE_SECBOOT_ ## _status
 
/** @} */
 
/* This file itself is permitted in a Secure Boot build */
FILE_SECBOOT ( PERMITTED );
 
#include <bits/compiler.h>
 
#endif /* COMPILER_H */