api.h

Go to the documentation of this file.
00001 #ifndef _GPXE_API_H
00002 #define _GPXE_API_H
00003 
00004 /** @file
00005  *
00006  * gPXE internal APIs
00007  *
00008  * There are various formally-defined APIs internal to gPXE, with
00009  * several differing implementations specific to particular execution
00010  * environments (e.g. PC BIOS, EFI, LinuxBIOS).
00011  *
00012  */
00013 
00014 FILE_LICENCE ( GPL2_OR_LATER );
00015 
00016 /** @defgroup Single-implementation APIs
00017  *
00018  * These are APIs for which only a single implementation may be
00019  * compiled in at any given time.
00020  *
00021  * @{
00022  */
00023 
00024 /**
00025  * Calculate function implementation name
00026  *
00027  * @v _prefix           Subsystem prefix
00028  * @v _api_func         API function
00029  * @ret _subsys_func    Subsystem API function
00030  *
00031  * The subsystem prefix should be an empty string for the currently
00032  * selected subsystem, and should be a subsystem-unique string for all
00033  * other subsystems.
00034  */
00035 #define SINGLE_API_NAME( _prefix, _api_func ) _prefix ## _api_func
00036 
00037 /**
00038  * Calculate static inline function name
00039  *
00040  * @v _prefix           Subsystem prefix
00041  * @v _api_func         API function
00042  * @ret _subsys_func    Subsystem API function
00043  */
00044 #define SINGLE_API_INLINE( _prefix, _api_func ) \
00045         SINGLE_API_NAME ( _prefix, _api_func )
00046 
00047 /**
00048  * Provide an API implementation
00049  *
00050  * @v _prefix           Subsystem prefix
00051  * @v _api_func         API function
00052  * @v _func             Implementing function
00053  */
00054 #define PROVIDE_SINGLE_API( _prefix, _api_func, _func )                       \
00055         /* Ensure that _api_func exists */                                    \
00056         typeof ( _api_func ) _api_func;                                       \
00057         /* Ensure that _func exists */                                        \
00058         typeof ( _func ) _func;                                               \
00059         /* Ensure that _func is type-compatible with _api_func */             \
00060         typeof ( _api_func ) _func;                                           \
00061         /* Ensure that _subsys_func is non-static */                          \
00062         extern typeof ( _api_func ) SINGLE_API_NAME ( _prefix, _api_func );   \
00063         /* Provide symbol alias from _subsys_func to _func */                 \
00064         typeof ( _api_func ) SINGLE_API_NAME ( _prefix, _api_func )           \
00065                 __attribute__ (( alias ( #_func ) ));
00066 
00067 /**
00068  * Provide a static inline API implementation
00069  *
00070  * @v _prefix           Subsystem prefix
00071  * @v _api_func         API function
00072  */
00073 #define PROVIDE_SINGLE_API_INLINE( _prefix, _api_func )                       \
00074         /* Ensure that _api_func exists */                                    \
00075         typeof ( _api_func ) _api_func;                                       \
00076         /* Ensure that _subsys_func exists and is static */                   \
00077         static typeof ( SINGLE_API_INLINE ( _prefix, _api_func ) )            \
00078                 SINGLE_API_INLINE ( _prefix, _api_func );                     \
00079         /* Ensure that _subsys_func is type-compatible with _api_func */      \
00080         typeof ( _api_func ) SINGLE_API_INLINE ( _prefix, _api_func );
00081 
00082 /** @} */
00083 
00084 #endif /* _GPXE_API_H */