diff options
author | Michael Brown | 2005-05-19 21:00:21 +0200 |
---|---|---|
committer | Michael Brown | 2005-05-19 21:00:21 +0200 |
commit | a9fabe75464e6ae31563f9a73cdbb9f5b2058219 (patch) | |
tree | f942e6a8d8a9e953abf31847c4bb834599adcf35 /src/include/compiler.h | |
parent | API docs to .h (diff) | |
download | ipxe-a9fabe75464e6ae31563f9a73cdbb9f5b2058219.tar.gz ipxe-a9fabe75464e6ae31563f9a73cdbb9f5b2058219.tar.xz ipxe-a9fabe75464e6ae31563f9a73cdbb9f5b2058219.zip |
Doxygenation
Diffstat (limited to 'src/include/compiler.h')
-rw-r--r-- | src/include/compiler.h | 119 |
1 files changed, 101 insertions, 18 deletions
diff --git a/src/include/compiler.h b/src/include/compiler.h index d02078b0..c7708949 100644 --- a/src/include/compiler.h +++ b/src/include/compiler.h @@ -10,12 +10,21 @@ #define __attribute__(x) #endif -/* - * We export the symbol obj_OBJECT (OBJECT is defined on command-line) - * as a global symbol, so that the linker can drag in selected object - * files from the library using -u obj_OBJECT. +/** @file + * + * Global compiler definitions. + * + * This file is implicitly included by every @c .c file in Etherboot. + * It defines global macros such as DBG() and ASSERT(). * - * Not quite sure why cpp requires two levels of macro call in order + * 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>. + * + */ + +/* Not quite sure why cpp requires two levels of macro call in order * to actually expand OBJECT... */ #undef _H1 @@ -40,7 +49,9 @@ __asm__ ( ".globl\t" OBJECT_SYMBOL_STR ); __asm__ ( ".equ\t" OBJECT_SYMBOL_STR ", 0" ); -/* +/** + * Drag in an object by object name. + * * Macro to allow objects to explicitly drag in other objects by * object name. Used by config.c. * @@ -48,6 +59,56 @@ __asm__ ( ".equ\t" OBJECT_SYMBOL_STR ", 0" ); #define REQUIRE_OBJECT(object) \ __asm__ ( ".equ\tneed_" #object ", obj_" #object ); +/** @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. + * + */ + +/** @def DBG2 + * + * Print a level 2 debugging message. + * + * As for DBG(). DBG2() takes effect only when the debugging level is + * 2 or greater. + * + */ + /* * If debug_OBJECT is set to a true value, the macro DBG(...) will * expand to printf(...) when compiling OBJECT, and the symbol @@ -77,8 +138,12 @@ __asm__ ( ".equ\tDEBUG_LEVEL, " DEBUG_SYMBOL_STR ); #define DBG2 DBG_PRINT #endif -/* - * ASSERT() macros +/** + * Assert a condition. + * + * If the condition is not true, a debug message will be printed. + * Assertions only take effect if the debug level is non-zero (see + * DBG()). * */ #define ASSERT(x) @@ -94,20 +159,35 @@ __asm__ ( ".equ\tDEBUG_LEVEL, " DEBUG_SYMBOL_STR ); } while (0) #endif -/* - * Commonly-used attributes. +/** Declare a data structure as packed. */ +#define PACKED __attribute__ (( packed )) + +/** + * Declare a variable or data structure as unused. * - * Note that __used can be used only for functions. If you have a - * static variable declaration that you want to force to be included, - * use __unused. + * Note that using @c __unused on a static global variable (such as a + * table structure as mentioned in tables.h) is necessary in order to + * inhibit compiler warnings. * */ -#define PACKED __attribute__ (( packed )) #define __unused __attribute__ (( unused )) + +/** + * Declare a function as used. + * + * Necessary only if the function is called only from assembler code. + * You cannot use this attribute for static global variables; use @c + * __unused instead. + * + */ #define __used __attribute__ (( used )) + +/** Declare a data structure to be aligned with 16-byte alignment */ #define __aligned __attribute__ (( aligned ( 16 ) )) -/* +/** + * Shared data. + * * To save space in the binary when multiple-driver images are * compiled, uninitialised data areas can be shared between drivers. * This will typically be used to share statically-allocated receive @@ -115,13 +195,16 @@ __asm__ ( ".equ\tDEBUG_LEVEL, " DEBUG_SYMBOL_STR ); * * Use as e.g. * - * struct { + * @code + * + * struct { * char rx_buf[NUM_RX_BUF][RX_BUF_SIZE]; * char tx_buf[TX_BUF_SIZE]; - * } my_static_data __shared; + * } my_static_data __shared; + * + * @endcode * */ - #define __shared __asm__ ( "_shared_bss" ) #endif /* ASSEMBLY */ |