[ioapi] Formalise the I/O API as used in i386-pcbios
[people/asdlkf/gpxe.git] / src / include / gpxe / api.h
1 #ifndef _GPXE_API_H
2 #define _GPXE_API_H
3
4 /** @file
5  *
6  * gPXE internal APIs
7  *
8  * There are various formally-defined APIs internal to gPXE, with
9  * several differing implementations specific to particular execution
10  * environments (e.g. PC BIOS, EFI, LinuxBIOS).
11  *
12  */
13
14 /** @defgroup Single-implementation APIs
15  *
16  * These are APIs for which only a single implementation may be
17  * compiled in at any given time.
18  *
19  * @{
20  */
21
22 /**
23  * Calculate function implementation name
24  *
25  * @v _prefix           Subsystem prefix
26  * @v _api_func         API function
27  * @ret _subsys_func    Subsystem API function
28  *
29  * The subsystem prefix should be an empty string for the currently
30  * selected subsystem, and should be a subsystem-unique string for all
31  * other subsystems.
32  */
33 #define SINGLE_API_NAME( _prefix, _api_func ) _prefix ## _api_func
34
35 /**
36  * Calculate static inline function name
37  *
38  * @v _prefix           Subsystem prefix
39  * @v _api_func         API function
40  * @ret _subsys_func    Subsystem API function
41  */
42 #define SINGLE_API_INLINE( _prefix, _api_func ) \
43         SINGLE_API_NAME ( _prefix, _api_func )
44
45 /**
46  * Provide an API implementation
47  *
48  * @v _prefix           Subsystem prefix
49  * @v _api_func         API function
50  * @v _func             Implementing function
51  */
52 #define PROVIDE_SINGLE_API( _prefix, _api_func, _func )                       \
53         /* Ensure that _api_func exists */                                    \
54         typeof ( _api_func ) _api_func;                                       \
55         /* Ensure that _func exists */                                        \
56         typeof ( _func ) _func;                                               \
57         /* Ensure that _func is type-compatible with _api_func */             \
58         typeof ( _api_func ) _func;                                           \
59         /* Ensure that _subsys_func is non-static */                          \
60         extern typeof ( _api_func ) SINGLE_API_NAME ( _prefix, _api_func );   \
61         /* Provide symbol alias from _subsys_func to _func */                 \
62         typeof ( _api_func ) SINGLE_API_NAME ( _prefix, _api_func )           \
63                 __attribute__ (( alias ( #_func ) ));
64
65 /**
66  * Provide a static inline API implementation
67  *
68  * @v _prefix           Subsystem prefix
69  * @v _api_func         API function
70  */
71 #define PROVIDE_SINGLE_API_INLINE( _prefix, _api_func )                       \
72         /* Ensure that _api_func exists */                                    \
73         typeof ( _api_func ) _api_func;                                       \
74         /* Ensure that _subsys_func exists and is static */                   \
75         static typeof ( SINGLE_API_INLINE ( _prefix, _api_func ) )            \
76                 SINGLE_API_INLINE ( _prefix, _api_func );                     \
77         /* Ensure that _subsys_func is type-compatible with _api_func */      \
78         typeof ( _api_func ) SINGLE_API_INLINE ( _prefix, _api_func );
79
80 /** @} */
81
82 #endif /* _GPXE_API_H */