root/trunk/include/iprt/cdefs.h

/** @file
 * IPRT - Common C and C++ definitions.
 */

/*
 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
 *
 * This file is part of VirtualBox Open Source Edition (OSE), as
 * available from http://www.virtualbox.org. This file is free software;
 * you can redistribute it and/or modify it under the terms of the GNU
 * General Public License (GPL) as published by the Free Software
 * Foundation, in version 2 as it comes in the "COPYING" file of the
 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
 *
 * The contents of this file may alternatively be used under the terms
 * of the Common Development and Distribution License Version 1.0
 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
 * VirtualBox OSE distribution, in which case the provisions of the
 * CDDL are applicable instead of those of the GPL.
 *
 * You may elect to license modified versions of this file under the
 * terms and conditions of either the GPL or the CDDL or both.
 *
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 USA or visit http://www.sun.com if you need
 * additional information or have any questions.
 */

#ifndef ___iprt_cdefs_h
#define ___iprt_cdefs_h


/** @defgroup grp_rt_cdefs  IPRT Common Definitions and Macros
 * @{
 */

/*
 * Include sys/cdefs.h if present, if not define the stuff we need.
 */
#ifdef HAVE_SYS_CDEFS_H
# if defined(RT_ARCH_LINUX) && defined(__KERNEL__)
#  error "oops"
# endif
# include <sys/cdefs.h>
#else

 /** @def __BEGIN_DECLS
  * Used to start a block of function declarations which are shared
  * between C and C++ program.
  */

 /** @def __END_DECLS
  * Used to end a block of function declarations which are shared
  * between C and C++ program.
  */

 #if defined(__cplusplus)
 # define __BEGIN_DECLS extern "C" {
 # define __END_DECLS   }
 #else
 # define __BEGIN_DECLS
 # define __END_DECLS
 #endif

#endif


/*
 * Shut up DOXYGEN warnings and guide it properly thru the code.
 */
#ifdef DOXYGEN_RUNNING
#define __AMD64__
#define __X86__
#define RT_ARCH_AMD64
#define RT_ARCH_X86
#define IN_RING0
#define IN_RING3
#define IN_RC
#define IN_RC
#define IN_RT_GC
#define IN_RT_R0
#define IN_RT_R3
#define IN_RT_STATIC
#define RT_STRICT
#define Breakpoint
#define RT_NO_DEPRECATED_MACROS
#endif /* DOXYGEN_RUNNING */

/** @def RT_ARCH_X86
 * Indicates that we're compiling for the X86 architecture.
 */

/** @def RT_ARCH_AMD64
 * Indicates that we're compiling for the AMD64 architecture.
 */
#if !defined(RT_ARCH_X86) && !defined(RT_ARCH_AMD64)
# if defined(__amd64__) || defined(__x86_64__) || defined(_M_X64) || defined(__AMD64__)
#  define RT_ARCH_AMD64
# elif defined(__i386__) || defined(_M_IX86) || defined(__X86__)
#  define RT_ARCH_X86
# else /* PORTME: append test for new archs. */
#  error "Check what predefined stuff your compiler uses to indicate architecture."
# endif
#elif defined(RT_ARCH_X86) && defined(RT_ARCH_AMD64) /* PORTME: append new archs. */
# error "Both RT_ARCH_X86 and RT_ARCH_AMD64 cannot be defined at the same time!"
#endif


/** @def __X86__
 * Indicates that we're compiling for the X86 architecture.
 * @deprecated
 */

/** @def __AMD64__
 * Indicates that we're compiling for the AMD64 architecture.
 * @deprecated
 */
#if !defined(__X86__) && !defined(__AMD64__)
# if defined(RT_ARCH_AMD64)
#  define __AMD64__
# elif defined(RT_ARCH_X86)
#  define __X86__
# else
#  error "Check what predefined stuff your compiler uses to indicate architecture."
# endif
#elif defined(__X86__) && defined(__AMD64__)
# error "Both __X86__ and __AMD64__ cannot be defined at the same time!"
#elif defined(__X86__) && !defined(RT_ARCH_X86)
# error "Both __X86__ without RT_ARCH_X86!"
#elif defined(__AMD64__) && !defined(RT_ARCH_AMD64)
# error "Both __AMD64__ without RT_ARCH_AMD64!"
#endif

/** @def IN_RING0
 * Used to indicate that we're compiling code which is running
 * in Ring-0 Host Context.
 */

/** @def IN_RING3
 * Used to indicate that we're compiling code which is running
 * in Ring-3 Host Context.
 */

/** @def IN_RC
 * Used to indicate that we're compiling code which is running
 * in the Raw-mode Context (implies R0).
 */
#if !defined(IN_RING3) && !defined(IN_RING0) && !defined(IN_RC) && !defined(IN_RC)
# error "You must defined which context the compiled code should run in; IN_RING3, IN_RING0 or IN_RC"
#endif
#if (defined(IN_RING3) && (defined(IN_RING0) || defined(IN_RC)) ) \
 || (defined(IN_RING0) && (defined(IN_RING3) || defined(IN_RC)) ) \
 || (defined(IN_RC)    && (defined(IN_RING3) || defined(IN_RING0)) )
# error "Only one of the IN_RING3, IN_RING0, IN_RC defines should be defined."
#endif


/** @def ARCH_BITS
 * Defines the bit count of the current context.
 */
#if !defined(ARCH_BITS) || defined(DOXYGEN_RUNNING)
# if defined(RT_ARCH_AMD64)
#  define ARCH_BITS 64
# else
#  define ARCH_BITS 32
# endif
#endif

/** @def HC_ARCH_BITS
 * Defines the host architecture bit count.
 */
#if !defined(HC_ARCH_BITS) || defined(DOXYGEN_RUNNING)
# ifndef IN_RC
#  define HC_ARCH_BITS ARCH_BITS
# else
#  define HC_ARCH_BITS 32
# endif
#endif

/** @def GC_ARCH_BITS
 * Defines the guest architecture bit count.
 */
#if !defined(GC_ARCH_BITS) && !defined(DOXYGEN_RUNNING)
# ifdef VBOX_WITH_64_BITS_GUESTS
#  define GC_ARCH_BITS  64
# else
#  define GC_ARCH_BITS  32
# endif
#endif

/** @def R3_ARCH_BITS
 * Defines the host ring-3 architecture bit count.
 */
#if !defined(R3_ARCH_BITS) || defined(DOXYGEN_RUNNING)
# ifdef IN_RING3
#  define R3_ARCH_BITS ARCH_BITS
# else
#  define R3_ARCH_BITS HC_ARCH_BITS
# endif
#endif

/** @def R0_ARCH_BITS
 * Defines the host ring-0 architecture bit count.
 */
#if !defined(R0_ARCH_BITS) || defined(DOXYGEN_RUNNING)
# ifdef IN_RING0
#  define R0_ARCH_BITS ARCH_BITS
# else
#  define R0_ARCH_BITS HC_ARCH_BITS
# endif
#endif

/** @def GC_ARCH_BITS
 * Defines the guest architecture bit count.
 */
#if !defined(GC_ARCH_BITS) || defined(DOXYGEN_RUNNING)
# ifdef IN_RC
#  define GC_ARCH_BITS ARCH_BITS
# else
#  define GC_ARCH_BITS 32
# endif
#endif


/** @def CTXTYPE
 * Declare a type differently in GC, R3 and R0.
 *
 * @param   GCType  The GC type.
 * @param   R3Type  The R3 type.
 * @param   R0Type  The R0 type.
 * @remark  For pointers used only in one context use RCPTRTYPE(), R3R0PTRTYPE(), R3PTRTYPE() or R0PTRTYPE().
 */
#ifdef IN_RC
# define CTXTYPE(GCType, R3Type, R0Type)  GCType
#elif defined(IN_RING3)
# define CTXTYPE(GCType, R3Type, R0Type)  R3Type
#else
# define CTXTYPE(GCType, R3Type, R0Type)  R0Type
#endif

/** @def RCPTRTYPE
 * Declare a pointer which is used in the raw mode context but appears in structure(s) used by
 * both HC and RC. The main purpose is to make sure structures have the same
 * size when built for different architectures.
 *
 * @param   RCType  The RC type.
 */
#define RCPTRTYPE(RCType)       CTXTYPE(RCType, RTRCPTR, RTRCPTR)

/** @def R3R0PTRTYPE
 * Declare a pointer which is used in HC, is explicitely valid in ring 3 and 0,
 * but appears in structure(s) used by both HC and GC. The main purpose is to
 * make sure structures have the same size when built for different architectures.
 *
 * @param   R3R0Type  The R3R0 type.
 * @remarks This used to be called HCPTRTYPE.
 */
#define R3R0PTRTYPE(R3R0Type)   CTXTYPE(RTHCPTR, R3R0Type, R3R0Type)

/** @def R3PTRTYPE
 * Declare a pointer which is used in R3 but appears in structure(s) used by
 * both HC and GC. The main purpose is to make sure structures have the same
 * size when built for different architectures.
 *
 * @param   R3Type  The R3 type.
 */
#define R3PTRTYPE(R3Type)       CTXTYPE(RTHCUINTPTR, R3Type, RTHCUINTPTR)

/** @def R0PTRTYPE
 * Declare a pointer which is used in R0 but appears in structure(s) used by
 * both HC and GC. The main purpose is to make sure structures have the same
 * size when built for different architectures.
 *
 * @param   R0Type  The R0 type.
 */
#define R0PTRTYPE(R0Type)       CTXTYPE(RTHCUINTPTR, RTHCUINTPTR, R0Type)

/** @def CTXSUFF
 * Adds the suffix of the current context to the passed in
 * identifier name. The suffix is HC or GC.
 *
 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
 * @param   var     Identifier name.
 * @deprecated Use CTX_SUFF. Do NOT use this for new code.
 */
/** @def OTHERCTXSUFF
 * Adds the suffix of the other context to the passed in
 * identifier name. The suffix is HC or GC.
 *
 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
 * @param   var     Identifier name.
 * @deprecated Use CTX_SUFF. Do NOT use this for new code.
 */
#ifdef IN_RC
# define CTXSUFF(var)       var##GC
# define OTHERCTXSUFF(var)  var##HC
#else
# define CTXSUFF(var)       var##HC
# define OTHERCTXSUFF(var)  var##GC
#endif

/** @def CTXALLSUFF
 * Adds the suffix of the current context to the passed in
 * identifier name. The suffix is R3, R0 or GC.
 *
 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
 * @param   var     Identifier name.
 * @deprecated Use CTX_SUFF. Do NOT use this for new code.
 */
#ifdef IN_RC
# define CTXALLSUFF(var)    var##GC
#elif defined(IN_RING0)
# define CTXALLSUFF(var)    var##R0
#else
# define CTXALLSUFF(var)    var##R3
#endif

/** @def CTX_SUFF
 * Adds the suffix of the current context to the passed in
 * identifier name. The suffix is R3, R0 or RC.
 *
 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
 * @param   var     Identifier name.
 *
 * @remark  This will replace CTXALLSUFF and CTXSUFF before long.
 */
#ifdef IN_RC
# define CTX_SUFF(var)      var##RC
#elif defined(IN_RING0)
# define CTX_SUFF(var)      var##R0
#else
# define CTX_SUFF(var)      var##R3
#endif

/** @def CTX_SUFF_Z
 * Adds the suffix of the current context to the passed in
 * identifier name, combining RC and R0 into RZ.
 * The suffix thus is R3 or RZ.
 *
 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
 * @param   var     Identifier name.
 *
 * @remark  This will replace CTXALLSUFF and CTXSUFF before long.
 */
#ifdef IN_RING3
# define CTX_SUFF_Z(var)    var##R3
#else
# define CTX_SUFF_Z(var)    var##RZ
#endif


/** @def CTXMID
 * Adds the current context as a middle name of an identifier name
 * The middle name is HC or GC.
 *
 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
 * @param   first   First name.
 * @param   last    Surname.
 */
/** @def OTHERCTXMID
 * Adds the other context as a middle name of an identifier name
 * The middle name is HC or GC.
 *
 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
 * @param   first   First name.
 * @param   last    Surname.
 * @deprecated use CTX_MID or CTX_MID_Z
 */
#ifdef IN_RC
# define CTXMID(first, last)        first##GC##last
# define OTHERCTXMID(first, last)   first##HC##last
#else
# define CTXMID(first, last)        first##HC##last
# define OTHERCTXMID(first, last)   first##GC##last
#endif

/** @def CTXALLMID
 * Adds the current context as a middle name of an identifier name.
 * The middle name is R3, R0 or GC.
 *
 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
 * @param   first   First name.
 * @param   last    Surname.
 * @deprecated use CTX_MID or CTX_MID_Z
 */
#ifdef IN_RC
# define CTXALLMID(first, last)     first##GC##last
#elif defined(IN_RING0)
# define CTXALLMID(first, last)     first##R0##last
#else
# define CTXALLMID(first, last)     first##R3##last
#endif

/** @def CTX_MID
 * Adds the current context as a middle name of an identifier name.
 * The middle name is R3, R0 or RC.
 *
 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
 * @param   first   First name.
 * @param   last    Surname.
 */
#ifdef IN_RC
# define CTX_MID(first, last)       first##RC##last
#elif defined(IN_RING0)
# define CTX_MID(first, last)       first##R0##last
#else
# define CTX_MID(first, last)       first##R3##last
#endif

/** @def CTX_MID_Z
 * Adds the current context as a middle name of an identifier name, combining RC
 * and R0 into RZ.
 * The middle name thus is either R3 or RZ.
 *
 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
 * @param   first   First name.
 * @param   last    Surname.
 */
#ifdef IN_RING3
# define CTX_MID_Z(first, last)     first##R3##last
#else
# define CTX_MID_Z(first, last)     first##RZ##last
#endif


/** @def R3STRING
 * A macro which in GC and R0 will return a dummy string while in R3 it will return
 * the parameter.
 *
 * This is typically used to wrap description strings in structures shared
 * between R3, R0 and/or GC. The intention is to avoid the \#ifdef IN_RING3 mess.
 *
 * @param   pR3String   The R3 string. Only referenced in R3.
 * @see R0STRING and GCSTRING
 */
#ifdef IN_RING3
# define R3STRING(pR3String)    (pR3String)
#else
# define R3STRING(pR3String)    ("<R3_STRING>")
#endif

/** @def R0STRING
 * A macro which in GC and R3 will return a dummy string while in R0 it will return
 * the parameter.
 *
 * This is typically used to wrap description strings in structures shared
 * between R3, R0 and/or GC. The intention is to avoid the \#ifdef IN_RING0 mess.
 *
 * @param   pR0String   The R0 string. Only referenced in R0.
 * @see R3STRING and GCSTRING
 */
#ifdef IN_RING0
# define R0STRING(pR0String)    (pR0String)
#else
# define R0STRING(pR0String)    ("<R0_STRING>")
#endif

/** @def RCSTRING
 * A macro which in R3 and R0 will return a dummy string while in RC it will return
 * the parameter.
 *
 * This is typically used to wrap description strings in structures shared
 * between R3, R0 and/or RC. The intention is to avoid the \#ifdef IN_RC mess.
 *
 * @param   pR0String   The RC string. Only referenced in RC.
 * @see R3STRING, R0STRING
 */
#ifdef IN_RC
# define RCSTRING(pRCString)    (pRCString)
#else
# define RCSTRING(pRCString)    ("<RC_STRING>")
#endif


/** @def RTCALL
 * The standard calling convention for the Runtime interfaces.
 */
#ifdef _MSC_VER
# define RTCALL     __cdecl
#elif defined(__GNUC__) && defined(IN_RING0) && !(defined(RT_OS_OS2) || defined(RT_ARCH_AMD64)) /* the latter is kernel/gcc */
# define RTCALL     __attribute__((cdecl,regparm(0)))
#else
# define RTCALL
#endif

/** @def RT_NO_THROW
 * How to express that a function doesn't throw C++ exceptions
 * and the compiler can thus save itself the bother of trying
 * to catch any of them. Put this between the closing parenthesis
 * and the semicolon in function prototypes (and implementation if C++).
 */
#if defined(__cplusplus) \
 && (   (defined(_MSC_VER) && defined(_CPPUNWIND)) \
     || (defined(__GNUC__) && defined(__EXCEPTIONS)))
# define RT_NO_THROW    throw()
#else
# define RT_NO_THROW
#endif

/** @def DECLEXPORT
 * How to declare an exported function.
 * @param   type    The return type of the function declaration.
 */
#if defined(_MSC_VER) || defined(RT_OS_OS2)
# define DECLEXPORT(type)       __declspec(dllexport) type
#elif defined(RT_USE_VISIBILITY_DEFAULT)
# define DECLEXPORT(type)      __attribute__((visibility("default"))) type
#else
# define DECLEXPORT(type)      type
#endif

/** @def DECLIMPORT
 * How to declare an imported function.
 * @param   type    The return type of the function declaration.
 */
#if defined(_MSC_VER) || (defined(RT_OS_OS2) && !defined(__IBMC__) && !defined(__IBMCPP__))
# define DECLIMPORT(type)       __declspec(dllimport) type
#else
# define DECLIMPORT(type)       type
#endif

/** @def DECLHIDDEN
 * How to declare a non-exported function or variable.
 * @param   type    The return type of the function or the data type of the variable.
 */
#if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS) || !defined(RT_USE_VISIBILITY_HIDDEN)
# define DECLHIDDEN(type)       type
#else
# define DECLHIDDEN(type)       __attribute__((visibility("hidden"))) type
#endif

/** @def DECLASM
 * How to declare an internal assembly function.
 * @param   type    The return type of the function declaration.
 */
#ifdef __cplusplus
# ifdef _MSC_VER
#  define DECLASM(type)          extern "C" type __cdecl
# else
#  define DECLASM(type)          extern "C" type
# endif
#else
# ifdef _MSC_VER
#  define DECLASM(type)          type __cdecl
# else
#  define DECLASM(type)          type
# endif
#endif

/** @def DECLASMTYPE
 * How to declare an internal assembly function type.
 * @param   type    The return type of the function.
 */
#ifdef _MSC_VER
# define DECLASMTYPE(type)      type __cdecl
#else
# define DECLASMTYPE(type)      type
#endif

/** @def DECLNORETURN
 * How to declare a function which does not return.
 * @note: This macro can be combined with other macros, for example
 * @code
 *   EMR3DECL(DECLNORETURN(void)) foo(void);
 * @endcode
 */
#ifdef _MSC_VER
# define DECLNORETURN(type)     __declspec(noreturn) type
#elif defined(__GNUC__)
# define DECLNORETURN(type)     __attribute__((noreturn)) type
#else
# define DECLNORETURN(type)     type
#endif

/** @def DECLCALLBACK
 * How to declare an call back function type.
 * @param   type    The return type of the function declaration.
 */
#define DECLCALLBACK(type)      type RTCALL

/** @def DECLCALLBACKPTR
 * How to declare an call back function pointer.
 * @param   type    The return type of the function declaration.
 * @param   name    The name of the variable member.
 */
#define DECLCALLBACKPTR(type, name)  type (RTCALL * name)

/** @def DECLCALLBACKMEMBER
 * How to declare an call back function pointer member.
 * @param   type    The return type of the function declaration.
 * @param   name    The name of the struct/union/class member.
 */
#define DECLCALLBACKMEMBER(type, name)  type (RTCALL * name)

/** @def DECLR3CALLBACKMEMBER
 * How to declare an call back function pointer member - R3 Ptr.
 * @param   type    The return type of the function declaration.
 * @param   name    The name of the struct/union/class member.
 * @param   args    The argument list enclosed in parentheses.
 */
#ifdef IN_RING3
# define DECLR3CALLBACKMEMBER(type, name, args)  type (RTCALL * name) args
#else
# define DECLR3CALLBACKMEMBER(type, name, args)  RTR3PTR name
#endif

/** @def DECLRCCALLBACKMEMBER
 * How to declare an call back function pointer member - RC Ptr.
 * @param   type    The return type of the function declaration.
 * @param   name    The name of the struct/union/class member.
 * @param   args    The argument list enclosed in parentheses.
 */
#ifdef IN_RC
# define DECLRCCALLBACKMEMBER(type, name, args)  type (RTCALL * name) args
#else
# define DECLRCCALLBACKMEMBER(type, name, args)  RTRCPTR name
#endif

/** @def DECLR0CALLBACKMEMBER
 * How to declare an call back function pointer member - R0 Ptr.
 * @param   type    The return type of the function declaration.
 * @param   name    The name of the struct/union/class member.
 * @param   args    The argument list enclosed in parentheses.
 */
#ifdef IN_RING0
# define DECLR0CALLBACKMEMBER(type, name, args)  type (RTCALL * name) args
#else
# define DECLR0CALLBACKMEMBER(type, name, args)  RTR0PTR name
#endif

/** @def DECLINLINE
 * How to declare a function as inline.
 * @param   type    The return type of the function declaration.
 * @remarks Don't use this macro on C++ methods.
 */
#ifdef __GNUC__
# define DECLINLINE(type) static __inline__ type
#elif defined(__cplusplus)
# define DECLINLINE(type) inline type
#elif defined(_MSC_VER)
# define DECLINLINE(type) _inline type
#elif defined(__IBMC__)
# define DECLINLINE(type) _Inline type
#else
# define DECLINLINE(type) inline type
#endif


/** @def IN_RT_STATIC
 * Used to inidicate whether we're linking against a static IPRT
 * or not. The IPRT symbols will be declared as hidden (if
 * supported). Note that this define has no effect without setting
 * IN_RT_R0, IN_RT_R3 or IN_RT_GC indicators are set first.
 */

/** @def IN_RT_R0
 * Used to indicate whether we're inside the same link module as
 * the HC Ring-0 Runtime Library.
 */
/** @def RTR0DECL(type)
 * Runtime Library HC Ring-0 export or import declaration.
 * @param   type    The return type of the function declaration.
 */
#ifdef IN_RT_R0
# ifdef IN_RT_STATIC
#  define RTR0DECL(type)    DECLHIDDEN(type) RTCALL
# else
#  define RTR0DECL(type)    DECLEXPORT(type) RTCALL
# endif
#else
# define RTR0DECL(type)     DECLIMPORT(type) RTCALL
#endif

/** @def IN_RT_R3
 * Used to indicate whether we're inside the same link module as
 * the HC Ring-3 Runtime Library.
 */
/** @def RTR3DECL(type)
 * Runtime Library HC Ring-3 export or import declaration.
 * @param   type    The return type of the function declaration.
 */
#ifdef IN_RT_R3
# ifdef IN_RT_STATIC
#  define RTR3DECL(type)    DECLHIDDEN(type) RTCALL
# else
#  define RTR3DECL(type)    DECLEXPORT(type) RTCALL
# endif
#else
# define RTR3DECL(type)     DECLIMPORT(type) RTCALL
#endif

/** @def IN_RT_GC
 * Used to indicate whether we're inside the same link module as
 * the GC Runtime Library.
 */
/** @def RTGCDECL(type)
 * Runtime Library HC Ring-3 export or import declaration.
 * @param   type    The return type of the function declaration.
 */
#ifdef IN_RT_GC
# ifdef IN_RT_STATIC
#  define RTGCDECL(type)    DECLHIDDEN(type) RTCALL
# else
#  define RTGCDECL(type)    DECLEXPORT(type) RTCALL
# endif
#else
# define RTGCDECL(type)     DECLIMPORT(type) RTCALL
#endif

/** @def RTDECL(type)
 * Runtime Library export or import declaration.
 * Functions declared using this macro exists in all contexts.
 * @param   type    The return type of the function declaration.
 */
#if defined(IN_RT_R3) || defined(IN_RT_GC) || defined(IN_RT_R0)
# ifdef IN_RT_STATIC
#  define RTDECL(type)      DECLHIDDEN(type) RTCALL
# else
#  define RTDECL(type)      DECLEXPORT(type) RTCALL
# endif
#else
# define RTDECL(type)       DECLIMPORT(type) RTCALL
#endif

/** @def RTDATADECL(type)
 * Runtime Library export or import declaration.
 * Data declared using this macro exists in all contexts.
 * @param   type    The return type of the function declaration.
 */
#if defined(IN_RT_R3) || defined(IN_RT_GC) || defined(IN_RT_R0)
# ifdef IN_RT_STATIC
#  define RTDATADECL(type)  DECLHIDDEN(type)
# else
#  define RTDATADECL(type)  DECLEXPORT(type)
# endif
#else
# define RTDATADECL(type)   DECLIMPORT(type)
#endif


/** @def RT_NOCRT
 * Symbol name wrapper for the No-CRT bits.
 *
 * In order to coexist in the same process as other CRTs, we need to
 * decorate the symbols such that they don't conflict the ones in the
 * other CRTs. The result of such conflicts / duplicate symbols can
 * confuse the dynamic loader on unix like systems.
 *
 * Define RT_WITHOUT_NOCRT_WRAPPERS to drop the wrapping.
 * Define RT_WITHOUT_NOCRT_WRAPPER_ALIASES to drop the aliases to the
 * wrapped names.
 */
/** @def RT_NOCRT_STR
 * Same as RT_NOCRT only it'll return a double quoted string of the result.
 */
#ifndef RT_WITHOUT_NOCRT_WRAPPERS
# define RT_NOCRT(name) nocrt_ ## name
# define RT_NOCRT_STR(name) "nocrt_" # name
#else
# define RT_NOCRT(name) name
# define RT_NOCRT_STR(name) #name
#endif



/** @def RT_LIKELY
 * Give the compiler a hint that an expression is very likely to hold true.
 *
 * Some compilers support explicit branch prediction so that the CPU backend
 * can hint the processor and also so that code blocks can be reordered such
 * that the predicted path sees a more linear flow, thus improving cache
 * behaviour, etc.
 *
 * IPRT provides the macros RT_LIKELY() and RT_UNLIKELY() as a way to utilize
 * this compiler feature when present.
 *
 * A few notes about the usage:
 *
 *      - Generally, use RT_UNLIKELY() with error condition checks (unless you
 *        have some _strong_ reason to do otherwise, in which case document it),
 *        and/or RT_LIKELY() with success condition checks, assuming you want
 *        to optimize for the success path.
 *
 *      - Other than that, if you don't know the likelihood of a test succeeding
 *        from empirical or other 'hard' evidence, don't make predictions unless
 *        you happen to be a Dirk Gently.
 *
 *      - These macros are meant to be used in places that get executed a lot. It
 *        is wasteful to make predictions in code that is executed seldomly (e.g.
 *        at subsystem initialization time) as the basic block reording that this
 *        affecs can often generate larger code.
 *
 *      - Note that RT_SUCCESS() and RT_FAILURE() already makes use of RT_LIKELY()
 *        and RT_UNLIKELY(). Should you wish for prediction free status checks,
 *        use the RT_SUCCESS_NP() and RT_FAILURE_NP() macros instead.
 *
 *
 * @returns the boolean result of the expression.
 * @param   expr        The expression that's very likely to be true.
 * @see RT_UNLIKELY
 */
/** @def RT_UNLIKELY
 * Give the compiler a hint that an expression is highly unlikely hold true.
 *
 * See the usage instructions give in the RT_LIKELY() docs.
 *
 * @returns the boolean result of the expression.
 * @param   expr        The expression that's very unlikely to be true.
 * @see RT_LIKELY
 */
#if defined(__GNUC__)
# if __GNUC__ >= 3
#  define RT_LIKELY(expr)       __builtin_expect(!!(expr), 1)
#  define RT_UNLIKELY(expr)     __builtin_expect(!!(expr), 0)
# else
#  define RT_LIKELY(expr)       (expr)
#  define RT_UNLIKELY(expr)     (expr)
# endif
#else
# define RT_LIKELY(expr)        (expr)
# define RT_UNLIKELY(expr)      (expr)
#endif


/** @def RT_BIT
 * Make a bitmask for one integer sized bit.
 * @param   bit     Bit number.
 */
#define RT_BIT(bit)                     (1U << (bit))

/** @def RT_BIT_32
 * Make a 32-bit bitmask for one bit.
 * @param   bit     Bit number.
 */
#define RT_BIT_32(bit)                  (UINT32_C(1) << (bit))

/** @def RT_BIT_64
 * Make a 64-bit bitmask for one bit.
 * @param   bit     Bit number.