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