cdefs.h revision a71cd86f26a15f4b62925c2f67a342f758ac730e
* Copyright (C) 2006 InnoTek Systemberatung GmbH * This file is part of VirtualBox Open Source Edition (OSE), as * you can redistribute it and/or modify it under the terms of the GNU * General Public License 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. * If you received this file as part of a commercial VirtualBox * distribution, then only the terms of your commercial VirtualBox * license agreement apply instead of the previous paragraph. /** @defgroup grp_rt_cdefs InnoTek Portable Runtime Common Definitions and Macros * Include sys/cdefs.h if present, if not define the stuff we need. * Used to start a block of function declarations which are shared * between C and C++ program. * Used to end a block of function declarations which are shared * between C and C++ program. * Shut up DOXYGEN warnings and guide it properly thru the code. * Indicates that we're compiling for the X86 architecture. * Indicates that we're compiling for the AMD64 architecture. #
error "Check what predefined stuff your compiler uses to indicate architecture."#
error "Both __X86__ and __AMD64__ cannot be defined at the same time!" * Used to indicate that we're compiling code which is running * in Ring-0 Host Context. * Used to indicate that we're compiling code which is running * in Ring-3 Host Context. * Used to indicate that we're compiling code which is running * in Guest Context (implies R0). #
error "You must defined which context the compiled code should run in; IN_RING3, IN_RING0 or IN_GC"#
error "Only one of the IN_RING3, IN_RING0, IN_GC defines should be defined." * Defines the bit count of the current context. * Defines the host architechture bit count. * Defines the host ring-3 architechture bit count. * Defines the host ring-0 architechture bit count. * Defines the guest architechture bit count. * 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 GCPTRTYPE(), HCPTRTYPE(), R3PTRTYPE() or R0PTRTYPE(). * Declare a type differently in GC and HC. * @param GCType The GC type. * @param HCType The HC type. * @remark For pointers used only in one context use GCPTRTYPE(), HCPTRTYPE(), R3PTRTYPE() or R0PTRTYPE(). * Declare a pointer which is used in GC 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 GCType The GC type. * Declare a pointer which is used in HC 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 HCType The HC type. * 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. * 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. * 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. * 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. * 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. * 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. * 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. * 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. * A macro which in GC and R0 will return a dummy string while in R3 it will return * 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 * A macro which in GC and R3 will return a dummy string while in R0 it will return * 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 * A macro which in R3 and R0 will return a dummy string while in GC it will return * 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_GC mess. * @param pR0String The GC string. Only referenced in GC. * @see R3STRING, R0STRING * Macro which in GC will return a dummy string while in HC will return * This is typically used to wrap description strings in structures shared * between HC and GC. The intention is to avoid the \#ifdef IN_GC kludge. * @param pHCString The HC string. Only referenced in HC. * @deprecated Use R3STRING or R0STRING instead. * The standard calling convention for the Runtime interfaces. * How to declare an exported function. * @param type The return type of the function declaration. * How to declare an imported function. * @param type The return type of the function declaration. * How to declare an internal assembly function. * @param type The return type of the function declaration. * How to declare an internal assembly function type. * @param type The return type of the function. * How to declare an call back function type. * @param type The return type of the function declaration. * 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. /** @def DECLCALLBACKMEMBER * How to declare an call back function pointer member. * @param type The return type of the function declaration. /** @def DECLR3CALLBACKMEMBER * How to declare an call back function pointer member - R3 Ptr. * @param type The return type of the function declaration. * @param args The argument list enclosed in parentheses. /** @def DECLGCCALLBACKMEMBER * How to declare an call back function pointer member - GC Ptr. * @param type The return type of the function declaration. * @param args The argument list enclosed in parentheses. /** @def DECLR0CALLBACKMEMBER * How to declare an call back function pointer member - R0 Ptr. * @param type The return type of the function declaration. * @param args The argument list enclosed in parentheses. * How to declare a function as inline. * @param type The return type of the function declaration. * Used to indicate whether we're inside the same link module as * the HC Ring-0 Runtime Library. * Runtime Library HC Ring-0 export or import declaration. * @param type The return type of the function declaration. * Used to indicate whether we're inside the same link module as * the HC Ring-3 Runtime Library. * Runtime Library HC Ring-3 export or import declaration. * @param type The return type of the function declaration. * Used to indicate whether we're inside the same link module as * the GC Runtime Library. * Runtime Library HC Ring-3 export or import declaration. * @param type The return type of the function declaration. * Runtime Library export or import declaration. * Functions declared using this macro exists in all contexts. * @param type The return type of the function declaration. /** @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. * 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. * Same as RT_NOCRT only it'll return a double quoted string of the result. * 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 * 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. * 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. * Make a bitmask for one integer sized bit. * Make a 32-bit bitmask for one bit. * Make a 64-bit bitmask for one bit. * @param u Value to align. * @param uAlignment The alignment. Power of two! * @remark Be extremely careful when using this macro with type which sizeof != sizeof int. * When possible use any of the other RT_ALIGN_* macros. And when that's not * possible, make 101% sure that uAlignment is specified with a right sized type. * Specifying an unsigned 32-bit alignment constant with a 64-bit value will give * you a 32-bit return value! * In short: Don't use this macro. Use RT_ALIGN_T() instead. * @param u Value to align. * @param uAlignment The alignment. Power of two! * @param type Integer type to use while aligning. * @remark This macro is the prefered alignment macro, it doesn't have any of the pitfalls RT_ALIGN has. * Align macro for a 32-bit value. * @param u32 Value to align. * @param uAlignment The alignment. Power of two! * Align macro for a 64-bit value. * @param u64 Value to align. * @param uAlignment The alignment. Power of two! * Align macro for size_t. * @param cb Value to align. * @param uAlignment The alignment. Power of two! * Align macro for pointers. * @param pv Value to align. * @param uAlignment The alignment. Power of two! * Align macro for pointers with type cast. * @param u Value to align. * @param uAlignment The alignment. Power of two! * @param CastType The type to cast the result to. * Align macro for ring-3 pointers with type cast. * @param u Value to align. * @param uAlignment The alignment. Power of two! * @param CastType The type to cast the result to. * Align macro for ring-0 pointers with type cast. * @param u Value to align. * @param uAlignment The alignment. Power of two! * @param CastType The type to cast the result to. * Align macro for GC pointers with type cast. * @param u Value to align. * @param uAlignment The alignment. Power of two! * @param CastType The type to cast the result to. * Our own special offsetof() variant. * This differs from the usual offsetof() in that it's not relying on builtin * compiler stuff and thus can use variables in arrays the structure may * contain. If in this usful to determin the sizes of structures ending * with a variable length field. * @returns offset into the structure of the specified member. * @param type Structure type. * Get the size of a structure member. * @returns size of the structure member. * @param type Structure type. * Calcs the number of elements in an array. * @returns Element count. * @param aArray Array in question. * Finds the maximum value. * @returns The higher of the two. * Finds the minimum value. * @returns The lower of the two. * Get the absolute (non-negative) value. * @returns The absolute value of Value. * @param Value The value. * Gets the low word (=uint16_t) of something. */ * Gets the high word (=uint16_t) of a 32 bit something. */ * Gets the low byte of something. */ * Gets the low byte of a 16 bit something. */ * Gets first byte of something. */ * Gets second byte of something. */ * Gets second byte of something. */ #
define RT_BYTE3(a) (((a) >>
16) &
0xff)
* Gets fourth byte of something. */ #
define RT_BYTE4(a) (((a) >>
24) &
0xff)
* Constructs a uint64_t value from two uint32_t values. /** @def RT_MAKE_U64_FROM_U16 * Constructs a uint64_t value from four uint16_t values. /** @def RT_MAKE_U64_FROM_U8 * Constructs a uint64_t value from eight uint8_t values. * Constructs a uint32_t value from two uint16_t values. /** @def RT_MAKE_U32_FROM_U8 * Constructs a uint32_t value from four uint8_t values. /** @todo remove this after uses in VUSBUrb.cpp has been corrected. */ * Constructs a uint32_t value from two uint16_t values. * Converts uint64_t value from host to little endian byte order. */ * Converts uint32_t value from host to little endian byte order. */ * Converts uint16_t value from host to little endian byte order. */ * Converts uint64_t value from little endian to host byte order. */ * Converts uint32_t value from little endian to host byte order. */ * Converts uint16_t value from little endian to host byte order. */ * Converts uint64_t value from host to big endian byte order. */ * Converts uint32_t value from host to big endian byte order. */ * Converts uint16_t value from host to big endian byte order. */ * Converts uint64_t value from big endian to host byte order. */ * Converts uint32_t value from big endian to host byte order. */ * Converts uint16_t value from big endian to host byte order. */ * Converts uint32_t value from host to network byte order. */ * Converts uint16_t value from host to network byte order. */ * Converts uint32_t value from network to host byte order. */ * Converts uint16_t value from network to host byte order. */ /** @def RT_NO_DEPRECATED_MACROS * Define RT_NO_DEPRECATED_MACROS to not define deprecated macros. * @deprecated Use RT_BIT. /** @deprecated Use RT_BIT64. */ * @deprecated use RT_ALIGN_P. */ /** @copydoc RT_SIZEOFMEMB * @deprecated Use RT_SIZEOFMEMB. */ * @deprecated use RT_ELEMENTS. */ * namespace pollution. Kill off some of the worse ones unless we're * Whenever we use offsets instead of pointers to save space and relocation effort * NIL_OFFSET shall be used as the equivalent to NULL. * Keeps the compiler from bitching about an unused parameters. * Emit a debug breakpoint instruction. * Use this for instrumenting a debugging session only! * No comitted code shall use Breakpoint(). #
error "This compiler is not supported!" * (Of course, these are binary computer terms, not SI.) /** 1 K (Kilo) (1 024). */ /** 4 K (Kilo) (4 096). */ /** 32 K (Kilo) (32 678). */ /** 64 K (Kilo) (65 536). */ /** 128 K (Kilo) (131 072). */ /** 256 K (Kilo) (262 144). */ /** 512 K (Kilo) (524 288). */ /** 1 M (Mega) (1 048 576). */ /** 2 M (Mega) (2 097 152). */ /** 4 M (Mega) (4 194 304). */ /** 1 G (Giga) (1 073 741 824). */ /** 2 G (Giga) (2 147 483 648). (32-bit) */ #
define _2G32 0x80000000U/** 2 G (Giga) (2 147 483 648). (64-bit) */ #
define _2G 0x0000000080000000LL/** 4 G (Giga) (4 294 967 296). */ #
define _4G 0x0000000100000000LL/** 1 T (Tera) (1 099 511 627 776). */ #
define _1T 0x0000010000000000LL/** 1 P (Peta) (1 125 899 906 842 624). */ #
define _1P 0x0004000000000000LL/** 1 E (Exa) (1 152 921 504 606 846 976). */ #
define _1E 0x1000000000000000LL/** 2 E (Exa) (2 305 843 009 213 693 952). */ #
define _2E 0x2000000000000000ULL * Pointer validation macro. #
if defined(
__DARWIN__)
/* first 4GB is reserved for legacy kernel. */ && ( ((
uintptr_t)(
ptr) &
0xffff800000000000ULL) ==
0xffff800000000000ULL \
#
error "Architecture identifier missing / not implemented." * The \#define N_ is used mark a string for translation. This is usable in * any part of the code, as it is only used by the tools that create message * catalogs. This macro is a no-op as far as the compiler and code generation * If you want to both mark a string for translation and translate it, use _. * The \#define _ is used mark a string for translation and to translate it in * If you want to only mark a string for translation, use N_. /** @def __PRETTY_FUNCTION__ * With GNU C we'd like to use the builtin __PRETTY_FUNCTION__, so define that for the other compilers. * The \#define RT_STRICT controls whether or not assertions and other runtime checks * should be compiled in or not. * If you want assertions which are not a subject to compile time options use * the AssertRelease*() flavors. /** Source position declaration. */ /** Source position arguments. */ /** @defgroup grp_rt_cdefs_cpp Special Macros for C++ /** @def WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP * Macro to work around error C2593 of the not-so-smart MSVC 7.x ambiguity * resolver. The following snippet clearly demonstrates the code causing this * operator bool() const { return false; } * operator int*() const { return NULL; } * The code itself seems pretty valid to me and GCC thinks the same. * This macro fixes the compiler error by explicitly overloading implicit * global operators !, && and || that take the given class instance as one of * The best is to use this macro right after the class declaration. * @note The macro expands to nothing for compilers other than MSVC. * @param Cls Class to apply the workaround to /** @def WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP_TPL * Version of WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP for template classes. * @param Tpl Name of the template class to apply the workaround to * @param ArgsDecl arguments of the template, as declared in |<>| after the * |template| keyword, including |<>| * @param Args arguments of the template, as specified in |<>| after the * template class name when using the, including |<>| * // template class declaration * WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP_TPL (Foo, <class C>, <C>) /** @def DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP * Declares the copy constructor and the assignment operation as inlined no-ops * (non-existent functions) for the given class. Use this macro inside the * private section if you want to effectively disable these operations for your * @param Cls class name to declare for /** @def DECLARE_CLS_NEW_DELETE_NOOP * Declares the new and delete operations as no-ops (non-existent functions) * for the given class. Use this macro inside the private section if you want * to effectively limit creating class instances on the stack only. * @note The destructor of the given class must not be virtual, otherwise a * compile time error will occur. Note that this is not a drawback: having * the virtual destructor for a stack-based class is absolutely useless * (the real class of the stack-based instance is always known to the compiler * at compile time, so it will always call the correct destructor). * @param Cls class name to declare for * Shortcut to |const_cast<C &>()| that automatically derives the correct * type (class) for the const_cast template's argument from its own argument. * Can be used to temporarily cancel the |const| modifier on the left-hand side * of assignment expressions, like this: * unconst (that) = some_value; * Shortcut to |const_cast<C *>()| that automatically derives the correct * type (class) for the const_cast template's argument from its own argument. * Can be used to temporarily cancel the |const| modifier on the left-hand side * of assignment expressions, like this: * unconst (that) = some_value; #
endif /* defined(__cplusplus) */