workbench/libs/codesetslib/include/SDI_lib.h

   1 #ifndef SDI_LIB_H
   2 #define SDI_LIB_H
   3
   4 /* Includeheader
   5
   6         Name:           SDI_lib.h
   7         Versionstring:  $VER: SDI_lib.h 1.9 (15.03.2009)
   8         Author:         Jens Langner
   9         Distribution:   PD
  10         Project page:   http://www.sf.net/projects/sditools/
  11         Description:    defines to hide OS specific library function definitions
  12
  13  1.0   09.05.04 : initial version which allows to hide OS specific shared
  14                   library function definition like it has been introduced with
  15                   the new interface based library system in AmigaOS4.
  16  1.1   13.05.04 : replaced the LIBENTRY() macro with some more sophisticated
  17                   LFUNC_ macros which allow to maintain varargs library functions
  18                   in a much easier manner.
  19  1.2   22.05.04 : removed the anyway not required SAVEDS and ASM statements
  20                   from the LIBFUNC macro for OS4. Also removed the LIBFUNC
  21                   statement in the 68k LIBPROTOVA() macro so that no registers
  22                   can be used in there (which should be the default).
  23  1.3   04.07.04 : added empty LIBFUNC define for MorphOS which was missing.
  24  1.4   05.10.04 : added missing LIBFUNC call to OS3/MOS interface
  25  1.5   19.05.05 : fixed some documentation glitches (Guido Mersmann)
  26  1.6   08.06.05 : swapped LIBFUNC and ret within the prototype, because
  27                   c standard says attributes first and vbcc want them like
  28                   this. (Guido Mersmann)
  29                   changed the documentation to explain that LIBFUNC must be
  30                   set first. (Guido Mersmann)
  31  1.7   11.12.05 : adapted all macros to be somewhat more compatible to also
  32                   OS3 and MorphOS. Now in the real use case (codesets.library)
  33                   it required a fundamental rework of the macros. (Jens Langner)
  34  1.8   28.02.06 : removed "##" in front of the OS3 __VARARGS__ usage as they
  35                   causing errors on GCC >= 3.x.
  36  1.9   15.03.09 : fixed some missing function prototype in LIBPROTOVA()
  37
  38 */
  39
  40 /*
  41 ** This is PD (Public Domain). This means you can do with it whatever you want
  42 ** without any restrictions. I only ask you to tell me improvements, so I may
  43 ** fix the main line of this files as well.
  44 **
  45 ** To keep confusion level low: When changing this file, please note it in
  46 ** above history list and indicate that the change was not made by myself
  47 ** (e.g. add your name or nick name).
  48 **
  49 ** Find the latest version of this file at:
  50 ** http://cvs.sourceforge.net/viewcvs.py/sditools/sditools/headers/
  51 **
  52 ** Jens Langner <Jens.Langner@light-speed.de> and
  53 ** Dirk Stöcker <soft@dstoecker.de>
  54 */
  55
  56 #include "SDI_compiler.h"
  57
  58 /*
  59 ** Library function macros to handle the definition/usage for different
  60 ** Operating System versions.
  61 ** Currently special library function handling for AmigaOS version 4 is
  62 ** supported
  63 **
  64 ** Example:
  65 **
  66 ** Defines a library jump function "TestFunc" with a ULONG return value and
  67 ** which is called by the corresponding library vector of a shared library.
  68 **
  69 ** LIBFUNC ULONG TestFunc(REG(d0, text))
  70 ** {
  71 **   Printf(text);
  72 **   return 0;
  73 ** }
  74 **
  75 ** Please note the use of the LIBFUNC macro which defines this function
  76 ** automatically as a function which is directly called from within a shared
  77 ** library. Since this macro contains compiler attributes it must be
  78 ** called first, even if some compiler allow attributes and result type
  79 ** mixed, other do not and we want to keep the stuff compiler independent.
  80 **
  81 ** If you now require to have some OS/compiler independent prototype
  82 ** definition please use the following statement:
  83 **
  84 ** LIBPROTO(TestFunc, ULONG, REG(d0, text));
  85 **
  86 ** This will ensure that you get a proper prototype for the same function
  87 ** where this macro will automatically take care that a libstub_* stub
  88 ** will also automatically defines as required if you are generating a
  89 ** OS4 shared library which should also be backward compatible to OS3.
  90 **
  91 ** So if you then want to add this function to a library interface please
  92 ** use the LFUNC_* macros to generate your library function vector
  93 ** like this example one:
  94 **
  95 ** #define libvector LFUNC_FAS(SomeFunc)    \
  96 **                   LFUNC_FA_(TestFunc)    \
  97 **                   LFUNC_VA_(VarargsFunc)
  98 **
  99 ** This way you can then easily put the "libvector" define in your real
 100 ** library function vector of your shared library instead of having to
 101 ** specify each function with surrounded "#ifdef" defines. These macros
 102 ** will then also take automatically care that the varargs functions
 103 ** will only be specified on OS versions where these functions are now
 104 ** real functions (like with OS4)
 105 **
 106 ** Such stub functions can then also be easily specified as followed
 107 ** (in analogy to the above example)
 108 **
 109 ** LIBPROTO(TestFunc, ULONG, REG(d0, text))
 110 ** {
 111 **   return TestFunc(text);
 112 ** }
 113 **
 114 ** On AmigaOS4 using this mechanism for the definition of the library functions
 115 ** will automatically ensure that the "struct Interface *self" pointer is included
 116 ** and can be easily referenced as such in the function.
 117 **
 118 ** By using this schema a developer might ensure full source code backward
 119 ** compatibility to AmigaOS3 without having to introduce dozens of #ifdef
 120 ** statements in his code.
 121 */
 122
 123 #ifdef LIBFUNC
 124 #undef LIBFUNC
 125 #endif
 126
 127 #if defined(__amigaos4__)
 128   #define LIBFUNC
 129   #if !defined(__cplusplus) &&                                        \
 130     (__STDC_VERSION__ >= 199901L || __GNUC__ >= 3 ||                  \
 131     (__GNUC__ == 2 && __GNUC_MINOR__ >= 95))
 132     #define LIBPROTO(name, ret, ...)                                  \
 133       LIBFUNC ret name(__VA_ARGS__);                                  \
 134       LIBFUNC ret libstub_##name(struct Interface *self UNUSED,       \
 135       ## __VA_ARGS__)
 136     #define LIBPROTOVA(name, ret, ...)                                \
 137       /*LIBFUNC ret VARARGS68K name(__VA_ARGS__);*/                       \
 138       LIBFUNC ret VARARGS68K                                          \
 139       libstub_##name(struct Interface *self UNUSED, ## __VA_ARGS__)
 140     #define LIBSTUB(name, ret, ...)                                   \
 141       LIBFUNC ret name(__VA_ARGS__);                                  \
 142       LIBFUNC ret libstub_##name(struct Interface *self UNUSED,       \
 143       ## __VA_ARGS__)
 144     #define LIBSTUBVA(name, ret, ...)                                 \
 145       LIBFUNC ret VARARGS68K                                          \
 146       libstub_##name(struct Interface *self UNUSED, ## __VA_ARGS__)
 147   #endif
 148   #define LFUNC_FAS(name) libstub_##name
 149   #define LFUNC_VAS(name) libstub_##name
 150   #define LFUNC_FA_(name) ,libstub_##name
 151   #define LFUNC_VA_(name) ,libstub_##name
 152   #define LFUNC(name)     libstub_##name
 153 #elif defined(__MORPHOS__)
 154   #define LIBFUNC
 155   #if !defined(__cplusplus) &&                                        \
 156     (__STDC_VERSION__ >= 199901L || __GNUC__ >= 3 ||                  \
 157     (__GNUC__ == 2 && __GNUC_MINOR__ >= 95))
 158     #define LIBPROTO(name, ret, ...)                                  \
 159       LIBFUNC ret name(__VA_ARGS__);                                  \
 160       LIBFUNC ret libstub_##name(void)
 161     #define LIBPROTOVA(name, ret, ...)
 162     #define LIBSTUB(name, ret, ...)                                   \
 163       LIBFUNC ret name(__VA_ARGS__);                                  \
 164       LIBFUNC ret libstub_##name(void)
 165     #define LIBSTUBVA(name, ret, ...)                                 \
 166       LIBFUNC UNUSED ret VARARGS68K libstub_##name(void)
 167   #endif
 168   #define LFUNC_FAS(name) libstub_##name
 169   #define LFUNC_VAS(name)
 170   #define LFUNC_FA_(name) ,libstub_##name
 171   #define LFUNC_VA_(name)
 172   #define LFUNC(name)     libstub_##name
 173 #else
 174   #define LIBFUNC SAVEDS ASM
 175   #if !defined(__cplusplus) &&                                        \
 176     (__STDC_VERSION__ >= 199901L || __GNUC__ >= 3 ||                  \
 177     (__GNUC__ == 2 && __GNUC_MINOR__ >= 95))
 178     #define LIBPROTO(name, ret, ...)                                  \
 179       LIBFUNC ret name(__VA_ARGS__)
 180     #define LIBPROTOVA(name, ret, ...)
 181     #define LIBSTUB(name, ret, ...)                                   \
 182       LIBFUNC ret name(__VA_ARGS__);                                  \
 183       LIBFUNC ret libstub_##name(__VA_ARGS__)
 184     #define LIBSTUBVA(name, ret, ...)                                 \
 185       LIBFUNC UNUSED ret STDARGS libstub_##name(__VA_ARGS__)
 186   #endif
 187   #define LFUNC_FAS(name) name
 188   #define LFUNC_VAS(name)
 189   #define LFUNC_FA_(name) ,name
 190   #define LFUNC_VA_(name)
 191   #define LFUNC(name)     name
 192 #endif
 193
 194 #if !defined(LIBPROTO) || !defined(LIBPROTOVA)
 195   #error "OS or compiler is not yet supported by SDI_lib.h"
 196 #endif
 197
 198 #endif /* SDI_LIB_H */