VirtualBox

source: vbox/trunk/include/iprt/cdefs.h@ 14949

Last change on this file since 14949 was 14013, checked in by vboxsync, 15 years ago

RT_LODWORD/RT_HIDWORD must cast the result to uint32_t.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 53.5 KB
Line 
1/** @file
2 * IPRT - Common C and C++ definitions.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 *
25 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___iprt_cdefs_h
31#define ___iprt_cdefs_h
32
33
34/** @defgroup grp_rt_cdefs IPRT Common Definitions and Macros
35 * @{
36 */
37
38/*
39 * Include sys/cdefs.h if present, if not define the stuff we need.
40 */
41#ifdef HAVE_SYS_CDEFS_H
42# if defined(RT_ARCH_LINUX) && defined(__KERNEL__)
43# error "oops"
44# endif
45# include <sys/cdefs.h>
46#else
47
48 /** @def __BEGIN_DECLS
49 * Used to start a block of function declarations which are shared
50 * between C and C++ program.
51 */
52
53 /** @def __END_DECLS
54 * Used to end a block of function declarations which are shared
55 * between C and C++ program.
56 */
57
58 #if defined(__cplusplus)
59 # define __BEGIN_DECLS extern "C" {
60 # define __END_DECLS }
61 #else
62 # define __BEGIN_DECLS
63 # define __END_DECLS
64 #endif
65
66#endif
67
68
69/*
70 * Shut up DOXYGEN warnings and guide it properly thru the code.
71 */
72#ifdef DOXYGEN_RUNNING
73#define __AMD64__
74#define __X86__
75#define RT_ARCH_AMD64
76#define RT_ARCH_X86
77#define IN_RING0
78#define IN_RING3
79#define IN_RC
80#define IN_RC
81#define IN_RT_GC
82#define IN_RT_R0
83#define IN_RT_R3
84#define IN_RT_STATIC
85#define RT_STRICT
86#define Breakpoint
87#define RT_NO_DEPRECATED_MACROS
88#endif /* DOXYGEN_RUNNING */
89
90/** @def RT_ARCH_X86
91 * Indicates that we're compiling for the X86 architecture.
92 */
93
94/** @def RT_ARCH_AMD64
95 * Indicates that we're compiling for the AMD64 architecture.
96 */
97#if !defined(RT_ARCH_X86) && !defined(RT_ARCH_AMD64)
98# if defined(__amd64__) || defined(__x86_64__) || defined(_M_X64) || defined(__AMD64__)
99# define RT_ARCH_AMD64
100# elif defined(__i386__) || defined(_M_IX86) || defined(__X86__)
101# define RT_ARCH_X86
102# else /* PORTME: append test for new archs. */
103# error "Check what predefined stuff your compiler uses to indicate architecture."
104# endif
105#elif defined(RT_ARCH_X86) && defined(RT_ARCH_AMD64) /* PORTME: append new archs. */
106# error "Both RT_ARCH_X86 and RT_ARCH_AMD64 cannot be defined at the same time!"
107#endif
108
109
110/** @def __X86__
111 * Indicates that we're compiling for the X86 architecture.
112 * @deprecated
113 */
114
115/** @def __AMD64__
116 * Indicates that we're compiling for the AMD64 architecture.
117 * @deprecated
118 */
119#if !defined(__X86__) && !defined(__AMD64__)
120# if defined(RT_ARCH_AMD64)
121# define __AMD64__
122# elif defined(RT_ARCH_X86)
123# define __X86__
124# else
125# error "Check what predefined stuff your compiler uses to indicate architecture."
126# endif
127#elif defined(__X86__) && defined(__AMD64__)
128# error "Both __X86__ and __AMD64__ cannot be defined at the same time!"
129#elif defined(__X86__) && !defined(RT_ARCH_X86)
130# error "Both __X86__ without RT_ARCH_X86!"
131#elif defined(__AMD64__) && !defined(RT_ARCH_AMD64)
132# error "Both __AMD64__ without RT_ARCH_AMD64!"
133#endif
134
135/** @def IN_RING0
136 * Used to indicate that we're compiling code which is running
137 * in Ring-0 Host Context.
138 */
139
140/** @def IN_RING3
141 * Used to indicate that we're compiling code which is running
142 * in Ring-3 Host Context.
143 */
144
145/** @def IN_RC
146 * Used to indicate that we're compiling code which is running
147 * in the Raw-mode Context (implies R0).
148 */
149#if !defined(IN_RING3) && !defined(IN_RING0) && !defined(IN_RC) && !defined(IN_RC)
150# error "You must defined which context the compiled code should run in; IN_RING3, IN_RING0 or IN_RC"
151#endif
152#if (defined(IN_RING3) && (defined(IN_RING0) || defined(IN_RC)) ) \
153 || (defined(IN_RING0) && (defined(IN_RING3) || defined(IN_RC)) ) \
154 || (defined(IN_RC) && (defined(IN_RING3) || defined(IN_RING0)) )
155# error "Only one of the IN_RING3, IN_RING0, IN_RC defines should be defined."
156#endif
157
158
159/** @def ARCH_BITS
160 * Defines the bit count of the current context.
161 */
162#if !defined(ARCH_BITS) || defined(DOXYGEN_RUNNING)
163# if defined(RT_ARCH_AMD64)
164# define ARCH_BITS 64
165# else
166# define ARCH_BITS 32
167# endif
168#endif
169
170/** @def HC_ARCH_BITS
171 * Defines the host architecture bit count.
172 */
173#if !defined(HC_ARCH_BITS) || defined(DOXYGEN_RUNNING)
174# ifndef IN_RC
175# define HC_ARCH_BITS ARCH_BITS
176# else
177# define HC_ARCH_BITS 32
178# endif
179#endif
180
181/** @def GC_ARCH_BITS
182 * Defines the guest architecture bit count.
183 */
184#if !defined(GC_ARCH_BITS) && !defined(DOXYGEN_RUNNING)
185# ifdef VBOX_WITH_64_BITS_GUESTS
186# define GC_ARCH_BITS 64
187# else
188# define GC_ARCH_BITS 32
189# endif
190#endif
191
192/** @def R3_ARCH_BITS
193 * Defines the host ring-3 architecture bit count.
194 */
195#if !defined(R3_ARCH_BITS) || defined(DOXYGEN_RUNNING)
196# ifdef IN_RING3
197# define R3_ARCH_BITS ARCH_BITS
198# else
199# define R3_ARCH_BITS HC_ARCH_BITS
200# endif
201#endif
202
203/** @def R0_ARCH_BITS
204 * Defines the host ring-0 architecture bit count.
205 */
206#if !defined(R0_ARCH_BITS) || defined(DOXYGEN_RUNNING)
207# ifdef IN_RING0
208# define R0_ARCH_BITS ARCH_BITS
209# else
210# define R0_ARCH_BITS HC_ARCH_BITS
211# endif
212#endif
213
214/** @def GC_ARCH_BITS
215 * Defines the guest architecture bit count.
216 */
217#if !defined(GC_ARCH_BITS) || defined(DOXYGEN_RUNNING)
218# ifdef IN_RC
219# define GC_ARCH_BITS ARCH_BITS
220# else
221# define GC_ARCH_BITS 32
222# endif
223#endif
224
225
226/** @def CTXTYPE
227 * Declare a type differently in GC, R3 and R0.
228 *
229 * @param GCType The GC type.
230 * @param R3Type The R3 type.
231 * @param R0Type The R0 type.
232 * @remark For pointers used only in one context use RCPTRTYPE(), R3R0PTRTYPE(), R3PTRTYPE() or R0PTRTYPE().
233 */
234#ifdef IN_RC
235# define CTXTYPE(GCType, R3Type, R0Type) GCType
236#elif defined(IN_RING3)
237# define CTXTYPE(GCType, R3Type, R0Type) R3Type
238#else
239# define CTXTYPE(GCType, R3Type, R0Type) R0Type
240#endif
241
242/** @def RCPTRTYPE
243 * Declare a pointer which is used in the raw mode context but appears in structure(s) used by
244 * both HC and RC. The main purpose is to make sure structures have the same
245 * size when built for different architectures.
246 *
247 * @param RCType The RC type.
248 */
249#define RCPTRTYPE(RCType) CTXTYPE(RCType, RTRCPTR, RTRCPTR)
250
251/** @def R3R0PTRTYPE
252 * Declare a pointer which is used in HC, is explicitely valid in ring 3 and 0,
253 * but appears in structure(s) used by both HC and GC. The main purpose is to
254 * make sure structures have the same size when built for different architectures.
255 *
256 * @param R3R0Type The R3R0 type.
257 * @remarks This used to be called HCPTRTYPE.
258 */
259#define R3R0PTRTYPE(R3R0Type) CTXTYPE(RTHCPTR, R3R0Type, R3R0Type)
260
261/** @def R3PTRTYPE
262 * Declare a pointer which is used in R3 but appears in structure(s) used by
263 * both HC and GC. The main purpose is to make sure structures have the same
264 * size when built for different architectures.
265 *
266 * @param R3Type The R3 type.
267 */
268#define R3PTRTYPE(R3Type) CTXTYPE(RTHCUINTPTR, R3Type, RTHCUINTPTR)
269
270/** @def R0PTRTYPE
271 * Declare a pointer which is used in R0 but appears in structure(s) used by
272 * both HC and GC. The main purpose is to make sure structures have the same
273 * size when built for different architectures.
274 *
275 * @param R0Type The R0 type.
276 */
277#define R0PTRTYPE(R0Type) CTXTYPE(RTHCUINTPTR, RTHCUINTPTR, R0Type)
278
279/** @def CTXSUFF
280 * Adds the suffix of the current context to the passed in
281 * identifier name. The suffix is HC or GC.
282 *
283 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
284 * @param var Identifier name.
285 * @deprecated Use CTX_SUFF. Do NOT use this for new code.
286 */
287/** @def OTHERCTXSUFF
288 * Adds the suffix of the other context to the passed in
289 * identifier name. The suffix is HC or GC.
290 *
291 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
292 * @param var Identifier name.
293 * @deprecated Use CTX_SUFF. Do NOT use this for new code.
294 */
295#ifdef IN_RC
296# define CTXSUFF(var) var##GC
297# define OTHERCTXSUFF(var) var##HC
298#else
299# define CTXSUFF(var) var##HC
300# define OTHERCTXSUFF(var) var##GC
301#endif
302
303/** @def CTXALLSUFF
304 * Adds the suffix of the current context to the passed in
305 * identifier name. The suffix is R3, R0 or GC.
306 *
307 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
308 * @param var Identifier name.
309 * @deprecated Use CTX_SUFF. Do NOT use this for new code.
310 */
311#ifdef IN_RC
312# define CTXALLSUFF(var) var##GC
313#elif defined(IN_RING0)
314# define CTXALLSUFF(var) var##R0
315#else
316# define CTXALLSUFF(var) var##R3
317#endif
318
319/** @def CTX_SUFF
320 * Adds the suffix of the current context to the passed in
321 * identifier name. The suffix is R3, R0 or RC.
322 *
323 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
324 * @param var Identifier name.
325 *
326 * @remark This will replace CTXALLSUFF and CTXSUFF before long.
327 */
328#ifdef IN_RC
329# define CTX_SUFF(var) var##RC
330#elif defined(IN_RING0)
331# define CTX_SUFF(var) var##R0
332#else
333# define CTX_SUFF(var) var##R3
334#endif
335
336/** @def CTX_SUFF_Z
337 * Adds the suffix of the current context to the passed in
338 * identifier name, combining RC and R0 into RZ.
339 * The suffix thus is R3 or RZ.
340 *
341 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
342 * @param var Identifier name.
343 *
344 * @remark This will replace CTXALLSUFF and CTXSUFF before long.
345 */
346#ifdef IN_RING3
347# define CTX_SUFF_Z(var) var##R3
348#else
349# define CTX_SUFF_Z(var) var##RZ
350#endif
351
352
353/** @def CTXMID
354 * Adds the current context as a middle name of an identifier name
355 * The middle name is HC or GC.
356 *
357 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
358 * @param first First name.
359 * @param last Surname.
360 */
361/** @def OTHERCTXMID
362 * Adds the other context as a middle name of an identifier name
363 * The middle name is HC or GC.
364 *
365 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
366 * @param first First name.
367 * @param last Surname.
368 * @deprecated use CTX_MID or CTX_MID_Z
369 */
370#ifdef IN_RC
371# define CTXMID(first, last) first##GC##last
372# define OTHERCTXMID(first, last) first##HC##last
373#else
374# define CTXMID(first, last) first##HC##last
375# define OTHERCTXMID(first, last) first##GC##last
376#endif
377
378/** @def CTXALLMID
379 * Adds the current context as a middle name of an identifier name.
380 * The middle name is R3, R0 or GC.
381 *
382 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
383 * @param first First name.
384 * @param last Surname.
385 * @deprecated use CTX_MID or CTX_MID_Z
386 */
387#ifdef IN_RC
388# define CTXALLMID(first, last) first##GC##last
389#elif defined(IN_RING0)
390# define CTXALLMID(first, last) first##R0##last
391#else
392# define CTXALLMID(first, last) first##R3##last
393#endif
394
395/** @def CTX_MID
396 * Adds the current context as a middle name of an identifier name.
397 * The middle name is R3, R0 or RC.
398 *
399 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
400 * @param first First name.
401 * @param last Surname.
402 */
403#ifdef IN_RC
404# define CTX_MID(first, last) first##RC##last
405#elif defined(IN_RING0)
406# define CTX_MID(first, last) first##R0##last
407#else
408# define CTX_MID(first, last) first##R3##last
409#endif
410
411/** @def CTX_MID_Z
412 * Adds the current context as a middle name of an identifier name, combining RC
413 * and R0 into RZ.
414 * The middle name thus is either R3 or RZ.
415 *
416 * This is macro should only be used in shared code to avoid a forrest of ifdefs.
417 * @param first First name.
418 * @param last Surname.
419 */
420#ifdef IN_RING3
421# define CTX_MID_Z(first, last) first##R3##last
422#else
423# define CTX_MID_Z(first, last) first##RZ##last
424#endif
425
426
427/** @def R3STRING
428 * A macro which in GC and R0 will return a dummy string while in R3 it will return
429 * the parameter.
430 *
431 * This is typically used to wrap description strings in structures shared
432 * between R3, R0 and/or GC. The intention is to avoid the \#ifdef IN_RING3 mess.
433 *
434 * @param pR3String The R3 string. Only referenced in R3.
435 * @see R0STRING and GCSTRING
436 */
437#ifdef IN_RING3
438# define R3STRING(pR3String) (pR3String)
439#else
440# define R3STRING(pR3String) ("<R3_STRING>")
441#endif
442
443/** @def R0STRING
444 * A macro which in GC and R3 will return a dummy string while in R0 it will return
445 * the parameter.
446 *
447 * This is typically used to wrap description strings in structures shared
448 * between R3, R0 and/or GC. The intention is to avoid the \#ifdef IN_RING0 mess.
449 *
450 * @param pR0String The R0 string. Only referenced in R0.
451 * @see R3STRING and GCSTRING
452 */
453#ifdef IN_RING0
454# define R0STRING(pR0String) (pR0String)
455#else
456# define R0STRING(pR0String) ("<R0_STRING>")
457#endif
458
459/** @def RCSTRING
460 * A macro which in R3 and R0 will return a dummy string while in RC it will return
461 * the parameter.
462 *
463 * This is typically used to wrap description strings in structures shared
464 * between R3, R0 and/or RC. The intention is to avoid the \#ifdef IN_RC mess.
465 *
466 * @param pR0String The RC string. Only referenced in RC.
467 * @see R3STRING, R0STRING
468 */
469#ifdef IN_RC
470# define RCSTRING(pRCString) (pRCString)
471#else
472# define RCSTRING(pRCString) ("<RC_STRING>")
473#endif
474
475
476/** @def RTCALL
477 * The standard calling convention for the Runtime interfaces.
478 */
479#ifdef _MSC_VER
480# define RTCALL __cdecl
481#elif defined(__GNUC__) && defined(IN_RING0) && !(defined(RT_OS_OS2) || defined(RT_ARCH_AMD64)) /* the latter is kernel/gcc */
482# define RTCALL __attribute__((cdecl,regparm(0)))
483#else
484# define RTCALL
485#endif
486
487/** @def RT_NO_THROW
488 * How to express that a function doesn't throw C++ exceptions
489 * and the compiler can thus save itself the bother of trying
490 * to catch any of them. Put this between the closing parenthesis
491 * and the semicolon in function prototypes (and implementation if C++).
492 */
493#if defined(__cplusplus) \
494 && ( (defined(_MSC_VER) && defined(_CPPUNWIND)) \
495 || (defined(__GNUC__) && defined(__EXCEPTIONS)))
496# define RT_NO_THROW throw()
497#else
498# define RT_NO_THROW
499#endif
500
501/** @def DECLEXPORT
502 * How to declare an exported function.
503 * @param type The return type of the function declaration.
504 */
505#if defined(_MSC_VER) || defined(RT_OS_OS2)
506# define DECLEXPORT(type) __declspec(dllexport) type
507#elif defined(RT_USE_VISIBILITY_DEFAULT)
508# define DECLEXPORT(type) __attribute__((visibility("default"))) type
509#else
510# define DECLEXPORT(type) type
511#endif
512
513/** @def DECLIMPORT
514 * How to declare an imported function.
515 * @param type The return type of the function declaration.
516 */
517#if defined(_MSC_VER) || (defined(RT_OS_OS2) && !defined(__IBMC__) && !defined(__IBMCPP__))
518# define DECLIMPORT(type) __declspec(dllimport) type
519#else
520# define DECLIMPORT(type) type
521#endif
522
523/** @def DECLHIDDEN
524 * How to declare a non-exported function or variable.
525 * @param type The return type of the function or the data type of the variable.
526 */
527#if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS) || !defined(RT_USE_VISIBILITY_HIDDEN)
528# define DECLHIDDEN(type) type
529#else
530# define DECLHIDDEN(type) __attribute__((visibility("hidden"))) type
531#endif
532
533/** @def DECLASM
534 * How to declare an internal assembly function.
535 * @param type The return type of the function declaration.
536 */
537#ifdef __cplusplus
538# ifdef _MSC_VER
539# define DECLASM(type) extern "C" type __cdecl
540# else
541# define DECLASM(type) extern "C" type
542# endif
543#else
544# ifdef _MSC_VER
545# define DECLASM(type) type __cdecl
546# else
547# define DECLASM(type) type
548# endif
549#endif
550
551/** @def DECLASMTYPE
552 * How to declare an internal assembly function type.
553 * @param type The return type of the function.
554 */
555#ifdef _MSC_VER
556# define DECLASMTYPE(type) type __cdecl
557#else
558# define DECLASMTYPE(type) type
559#endif
560
561/** @def DECLNORETURN
562 * How to declare a function which does not return.
563 * @note: This macro can be combined with other macros, for example
564 * @code
565 * EMR3DECL(DECLNORETURN(void)) foo(void);
566 * @endcode
567 */
568#ifdef _MSC_VER
569# define DECLNORETURN(type) __declspec(noreturn) type
570#elif defined(__GNUC__)
571# define DECLNORETURN(type) __attribute__((noreturn)) type
572#else
573# define DECLNORETURN(type) type
574#endif
575
576/** @def DECLCALLBACK
577 * How to declare an call back function type.
578 * @param type The return type of the function declaration.
579 */
580#define DECLCALLBACK(type) type RTCALL
581
582/** @def DECLCALLBACKPTR
583 * How to declare an call back function pointer.
584 * @param type The return type of the function declaration.
585 * @param name The name of the variable member.
586 */
587#define DECLCALLBACKPTR(type, name) type (RTCALL * name)
588
589/** @def DECLCALLBACKMEMBER
590 * How to declare an call back function pointer member.
591 * @param type The return type of the function declaration.
592 * @param name The name of the struct/union/class member.
593 */
594#define DECLCALLBACKMEMBER(type, name) type (RTCALL * name)
595
596/** @def DECLR3CALLBACKMEMBER
597 * How to declare an call back function pointer member - R3 Ptr.
598 * @param type The return type of the function declaration.
599 * @param name The name of the struct/union/class member.
600 * @param args The argument list enclosed in parentheses.
601 */
602#ifdef IN_RING3
603# define DECLR3CALLBACKMEMBER(type, name, args) type (RTCALL * name) args
604#else
605# define DECLR3CALLBACKMEMBER(type, name, args) RTR3PTR name
606#endif
607
608/** @def DECLRCCALLBACKMEMBER
609 * How to declare an call back function pointer member - RC Ptr.
610 * @param type The return type of the function declaration.
611 * @param name The name of the struct/union/class member.
612 * @param args The argument list enclosed in parentheses.
613 */
614#ifdef IN_RC
615# define DECLRCCALLBACKMEMBER(type, name, args) type (RTCALL * name) args
616#else
617# define DECLRCCALLBACKMEMBER(type, name, args) RTRCPTR name
618#endif
619
620/** @def DECLR0CALLBACKMEMBER
621 * How to declare an call back function pointer member - R0 Ptr.
622 * @param type The return type of the function declaration.
623 * @param name The name of the struct/union/class member.
624 * @param args The argument list enclosed in parentheses.
625 */
626#ifdef IN_RING0
627# define DECLR0CALLBACKMEMBER(type, name, args) type (RTCALL * name) args
628#else
629# define DECLR0CALLBACKMEMBER(type, name, args) RTR0PTR name
630#endif
631
632/** @def DECLINLINE
633 * How to declare a function as inline.
634 * @param type The return type of the function declaration.
635 * @remarks Don't use this macro on C++ methods.
636 */
637#ifdef __GNUC__
638# define DECLINLINE(type) static __inline__ type
639#elif defined(__cplusplus)
640# define DECLINLINE(type) inline type
641#elif defined(_MSC_VER)
642# define DECLINLINE(type) _inline type
643#elif defined(__IBMC__)
644# define DECLINLINE(type) _Inline type
645#else
646# define DECLINLINE(type) inline type
647#endif
648
649
650/** @def IN_RT_STATIC
651 * Used to inidicate whether we're linking against a static IPRT
652 * or not. The IPRT symbols will be declared as hidden (if
653 * supported). Note that this define has no effect without setting
654 * IN_RT_R0, IN_RT_R3 or IN_RT_GC indicators are set first.
655 */
656
657/** @def IN_RT_R0
658 * Used to indicate whether we're inside the same link module as
659 * the HC Ring-0 Runtime Library.
660 */
661/** @def RTR0DECL(type)
662 * Runtime Library HC Ring-0 export or import declaration.
663 * @param type The return type of the function declaration.
664 */
665#ifdef IN_RT_R0
666# ifdef IN_RT_STATIC
667# define RTR0DECL(type) DECLHIDDEN(type) RTCALL
668# else
669# define RTR0DECL(type) DECLEXPORT(type) RTCALL
670# endif
671#else
672# define RTR0DECL(type) DECLIMPORT(type) RTCALL
673#endif
674
675/** @def IN_RT_R3
676 * Used to indicate whether we're inside the same link module as
677 * the HC Ring-3 Runtime Library.
678 */
679/** @def RTR3DECL(type)
680 * Runtime Library HC Ring-3 export or import declaration.
681 * @param type The return type of the function declaration.
682 */
683#ifdef IN_RT_R3
684# ifdef IN_RT_STATIC
685# define RTR3DECL(type) DECLHIDDEN(type) RTCALL
686# else
687# define RTR3DECL(type) DECLEXPORT(type) RTCALL
688# endif
689#else
690# define RTR3DECL(type) DECLIMPORT(type) RTCALL
691#endif
692
693/** @def IN_RT_GC
694 * Used to indicate whether we're inside the same link module as
695 * the GC Runtime Library.
696 */
697/** @def RTGCDECL(type)
698 * Runtime Library HC Ring-3 export or import declaration.
699 * @param type The return type of the function declaration.
700 */
701#ifdef IN_RT_GC
702# ifdef IN_RT_STATIC
703# define RTGCDECL(type) DECLHIDDEN(type) RTCALL
704# else
705# define RTGCDECL(type) DECLEXPORT(type) RTCALL
706# endif
707#else
708# define RTGCDECL(type) DECLIMPORT(type) RTCALL
709#endif
710
711/** @def RTDECL(type)
712 * Runtime Library export or import declaration.
713 * Functions declared using this macro exists in all contexts.
714 * @param type The return type of the function declaration.
715 */
716#if defined(IN_RT_R3) || defined(IN_RT_GC) || defined(IN_RT_R0)
717# ifdef IN_RT_STATIC
718# define RTDECL(type) DECLHIDDEN(type) RTCALL
719# else
720# define RTDECL(type) DECLEXPORT(type) RTCALL
721# endif
722#else
723# define RTDECL(type) DECLIMPORT(type) RTCALL
724#endif
725
726/** @def RTDATADECL(type)
727 * Runtime Library export or import declaration.
728 * Data declared using this macro exists in all contexts.
729 * @param type The return type of the function declaration.
730 */
731#if defined(IN_RT_R3) || defined(IN_RT_GC) || defined(IN_RT_R0)
732# ifdef IN_RT_STATIC
733# define RTDATADECL(type) DECLHIDDEN(type)
734# else
735# define RTDATADECL(type) DECLEXPORT(type)
736# endif
737#else
738# define RTDATADECL(type) DECLIMPORT(type)
739#endif
740
741
742/** @def RT_NOCRT
743 * Symbol name wrapper for the No-CRT bits.
744 *
745 * In order to coexist in the same process as other CRTs, we need to
746 * decorate the symbols such that they don't conflict the ones in the
747 * other CRTs. The result of such conflicts / duplicate symbols can
748 * confuse the dynamic loader on unix like systems.
749 *
750 * Define RT_WITHOUT_NOCRT_WRAPPERS to drop the wrapping.
751 * Define RT_WITHOUT_NOCRT_WRAPPER_ALIASES to drop the aliases to the
752 * wrapped names.
753 */
754/** @def RT_NOCRT_STR
755 * Same as RT_NOCRT only it'll return a double quoted string of the result.
756 */
757#ifndef RT_WITHOUT_NOCRT_WRAPPERS
758# define RT_NOCRT(name) nocrt_ ## name
759# define RT_NOCRT_STR(name) "nocrt_" # name
760#else
761# define RT_NOCRT(name) name
762# define RT_NOCRT_STR(name) #name
763#endif
764
765
766
767/** @def RT_LIKELY
768 * Give the compiler a hint that an expression is very likely to hold true.
769 *
770 * Some compilers support explicit branch prediction so that the CPU backend
771 * can hint the processor and also so that code blocks can be reordered such
772 * that the predicted path sees a more linear flow, thus improving cache
773 * behaviour, etc.
774 *
775 * IPRT provides the macros RT_LIKELY() and RT_UNLIKELY() as a way to utilize
776 * this compiler feature when present.
777 *
778 * A few notes about the usage:
779 *
780 * - Generally, use RT_UNLIKELY() with error condition checks (unless you
781 * have some _strong_ reason to do otherwise, in which case document it),
782 * and/or RT_LIKELY() with success condition checks, assuming you want
783 * to optimize for the success path.
784 *
785 * - Other than that, if you don't know the likelihood of a test succeeding
786 * from empirical or other 'hard' evidence, don't make predictions unless
787 * you happen to be a Dirk Gently.
788 *
789 * - These macros are meant to be used in places that get executed a lot. It
790 * is wasteful to make predictions in code that is executed seldomly (e.g.
791 * at subsystem initialization time) as the basic block reording that this
792 * affecs can often generate larger code.
793 *
794 * - Note that RT_SUCCESS() and RT_FAILURE() already makes use of RT_LIKELY()
795 * and RT_UNLIKELY(). Should you wish for prediction free status checks,
796 * use the RT_SUCCESS_NP() and RT_FAILURE_NP() macros instead.
797 *
798 *
799 * @returns the boolean result of the expression.
800 * @param expr The expression that's very likely to be true.
801 * @see RT_UNLIKELY
802 */
803/** @def RT_UNLIKELY
804 * Give the compiler a hint that an expression is highly unlikely hold true.
805 *
806 * See the usage instructions give in the RT_LIKELY() docs.
807 *
808 * @returns the boolean result of the expression.
809 * @param expr The expression that's very unlikely to be true.
810 * @see RT_LIKELY
811 */
812#if defined(__GNUC__)
813# if __GNUC__ >= 3
814# define RT_LIKELY(expr) __builtin_expect(!!(expr), 1)
815# define RT_UNLIKELY(expr) __builtin_expect(!!(expr), 0)
816# else
817# define RT_LIKELY(expr) (expr)
818# define RT_UNLIKELY(expr) (expr)
819# endif
820#else
821# define RT_LIKELY(expr) (expr)
822# define RT_UNLIKELY(expr) (expr)
823#endif
824
825
826/** @def RT_BIT
827 * Make a bitmask for one integer sized bit.
828 * @param bit Bit number.
829 */
830#define RT_BIT(bit) (1U << (bit))
831
832/** @def RT_BIT_32
833 * Make a 32-bit bitmask for one bit.
834 * @param bit Bit number.
835 */
836#define RT_BIT_32(bit) (UINT32_C(1) << (bit))
837
838/** @def RT_BIT_64
839 * Make a 64-bit bitmask for one bit.
840 * @param bit Bit number.
841 */
842#define RT_BIT_64(bit) (UINT64_C(1) << (bit))
843
844/** @def RT_ALIGN
845 * Align macro.
846 * @param u Value to align.
847 * @param uAlignment The alignment. Power of two!
848 *
849 * @remark Be extremely careful when using this macro with type which sizeof != sizeof int.
850 * When possible use any of the other RT_ALIGN_* macros. And when that's not
851 * possible, make 101% sure that uAlignment is specified with a right sized type.
852 *
853 * Specifying an unsigned 32-bit alignment constant with a 64-bit value will give
854 * you a 32-bit return value!
855 *
856 * In short: Don't use this macro. Use RT_ALIGN_T() instead.
857 */
858#define RT_ALIGN(u, uAlignment) ( ((u) + ((uAlignment) - 1)) & ~((uAlignment) - 1) )
859
860/** @def RT_ALIGN_T
861 * Align macro.
862 * @param u Value to align.
863 * @param uAlignment The alignment. Power of two!
864 * @param type Integer type to use while aligning.
865 * @remark This macro is the prefered alignment macro, it doesn't have any of the pitfalls RT_ALIGN has.
866 */
867#define RT_ALIGN_T(u, uAlignment, type) ( ((type)(u) + ((uAlignment) - 1)) & ~(type)((uAlignment) - 1) )
868
869/** @def RT_ALIGN_32
870 * Align macro for a 32-bit value.
871 * @param u32 Value to align.
872 * @param uAlignment The alignment. Power of two!
873 */
874#define RT_ALIGN_32(u32, uAlignment) RT_ALIGN_T(u32, uAlignment, uint32_t)
875
876/** @def RT_ALIGN_64
877 * Align macro for a 64-bit value.
878 * @param u64 Value to align.
879 * @param uAlignment The alignment. Power of two!
880 */
881#define RT_ALIGN_64(u64, uAlignment) RT_ALIGN_T(u64, uAlignment, uint64_t)
882
883/** @def RT_ALIGN_Z
884 * Align macro for size_t.
885 * @param cb Value to align.
886 * @param uAlignment The alignment. Power of two!
887 */
888#define RT_ALIGN_Z(cb, uAlignment) RT_ALIGN_T(cb, uAlignment, size_t)
889
890/** @def RT_ALIGN_P
891 * Align macro for pointers.
892 * @param pv Value to align.
893 * @param uAlignment The alignment. Power of two!
894 */
895#define RT_ALIGN_P(pv, uAlignment) RT_ALIGN_PT(pv, uAlignment, void *)
896
897/** @def RT_ALIGN_PT
898 * Align macro for pointers with type cast.
899 * @param u Value to align.
900 * @param uAlignment The alignment. Power of two!
901 * @param CastType The type to cast the result to.
902 */
903#define RT_ALIGN_PT(u, uAlignment, CastType) ((CastType)RT_ALIGN_T(u, uAlignment, uintptr_t))
904
905/** @def RT_ALIGN_R3PT
906 * Align macro for ring-3 pointers with type cast.
907 * @param u Value to align.
908 * @param uAlignment The alignment. Power of two!
909 * @param CastType The type to cast the result to.
910 */
911#define RT_ALIGN_R3PT(u, uAlignment, CastType) ((CastType)RT_ALIGN_T(u, uAlignment, RTR3UINTPTR))
912
913/** @def RT_ALIGN_R0PT
914 * Align macro for ring-0 pointers with type cast.
915 * @param u Value to align.
916 * @param uAlignment The alignment. Power of two!
917 * @param CastType The type to cast the result to.
918 */
919#define RT_ALIGN_R0PT(u, uAlignment, CastType) ((CastType)RT_ALIGN_T(u, uAlignment, RTR0UINTPTR))
920
921/** @def RT_ALIGN_GCPT
922 * Align macro for GC pointers with type cast.
923 * @param u Value to align.
924 * @param uAlignment The alignment. Power of two!
925 * @param CastType The type to cast the result to.
926 */
927#define RT_ALIGN_GCPT(u, uAlignment, CastType) ((CastType)RT_ALIGN_T(u, uAlignment, RTGCUINTPTR))
928
929
930/** @def RT_OFFSETOF
931 * Our own special offsetof() variant, returns a signed result.
932 *
933 * This differs from the usual offsetof() in that it's not relying on builtin
934 * compiler stuff and thus can use variables in arrays the structure may
935 * contain. If in this usful to determin the sizes of structures ending
936 * with a variable length field.
937 *
938 * @returns offset into the structure of the specified member. signed.
939 * @param type Structure type.
940 * @param member Member.
941 */
942#define RT_OFFSETOF(type, member) ( (int)(uintptr_t)&( ((type *)(void *)0)->member) )
943
944/** @def RT_UOFFSETOF
945 * Our own special offsetof() variant, returns an unsigned result.
946 *
947 * This differs from the usual offsetof() in that it's not relying on builtin
948 * compiler stuff and thus can use variables in arrays the structure may
949 * contain. If in this usful to determin the sizes of structures ending
950 * with a variable length field.
951 *
952 * @returns offset into the structure of the specified member. unsigned.
953 * @param type Structure type.
954 * @param member Member.
955 */
956#define RT_UOFFSETOF(type, member) ( (uintptr_t)&( ((type *)(void *)0)->member) )
957
958/** @def RT_SIZEOFMEMB
959 * Get the size of a structure member.
960 *
961 * @returns size of the structure member.
962 * @param type Structure type.
963 * @param member Member.
964 */
965#define RT_SIZEOFMEMB(type, member) ( sizeof(((type *)(void *)0)->member) )
966
967/** @def RT_ELEMENTS
968 * Calcs the number of elements in an array.
969 * @returns Element count.
970 * @param aArray Array in question.
971 */
972#define RT_ELEMENTS(aArray) ( sizeof(aArray) / sizeof((aArray)[0]) )
973
974#ifdef RT_OS_OS2
975/* Undefine RT_MAX since there is an unfortunate clash with the max
976 resource type define in os2.h. */
977# undef RT_MAX
978#endif
979
980/** @def RT_MAX
981 * Finds the maximum value.
982 * @returns The higher of the two.
983 * @param Value1 Value 1
984 * @param Value2 Value 2
985 */
986#define RT_MAX(Value1, Value2) ((Value1) >= (Value2) ? (Value1) : (Value2))
987
988/** @def RT_MIN
989 * Finds the minimum value.
990 * @returns The lower of the two.
991 * @param Value1 Value 1
992 * @param Value2 Value 2
993 */
994#define RT_MIN(Value1, Value2) ((Value1) <= (Value2) ? (Value1) : (Value2))
995
996/** @def RT_ABS
997 * Get the absolute (non-negative) value.
998 * @returns The absolute value of Value.
999 * @param Value The value.
1000 */
1001#define RT_ABS(Value) ((Value) >= 0 ? (Value) : -(Value))
1002
1003/** @def RT_LODWORD
1004 * Gets the low dword (=uint32_t) of something. */
1005#define RT_LODWORD(a) ( (uint32_t)(a) )
1006
1007/** @def RT_HIDWORD
1008 * Gets the high dword (=uint32_t) of a 64-bit of something. */
1009#define RT_HIDWORD(a) ( (uint32_t)((a) >> 32) )
1010
1011/** @def RT_LOWORD
1012 * Gets the low word (=uint16_t) of something. */
1013#define RT_LOWORD(a) ((a) & 0xffff)
1014
1015/** @def RT_HIWORD
1016 * Gets the high word (=uint16_t) of a 32-bit something. */
1017#define RT_HIWORD(a) ((a) >> 16)
1018
1019/** @def RT_LOBYTE
1020 * Gets the low byte of something. */
1021#define RT_LOBYTE(a) ((a) & 0xff)
1022
1023/** @def RT_HIBYTE
1024 * Gets the low byte of a 16-bit something. */
1025#define RT_HIBYTE(a) ((a) >> 8)
1026
1027/** @def RT_BYTE1
1028 * Gets first byte of something. */
1029#define RT_BYTE1(a) ((a) & 0xff)
1030
1031/** @def RT_BYTE2
1032 * Gets second byte of something. */
1033#define RT_BYTE2(a) (((a) >> 8) & 0xff)
1034
1035/** @def RT_BYTE3
1036 * Gets second byte of something. */
1037#define RT_BYTE3(a) (((a) >> 16) & 0xff)
1038
1039/** @def RT_BYTE4
1040 * Gets fourth byte of something. */
1041#define RT_BYTE4(a) (((a) >> 24) & 0xff)
1042
1043
1044/** @def RT_MAKE_U64
1045 * Constructs a uint64_t value from two uint32_t values.
1046 */
1047#define RT_MAKE_U64(Lo, Hi) ( (uint64_t)((uint32_t)(Hi)) << 32 | (uint32_t)(Lo) )
1048
1049/** @def RT_MAKE_U64_FROM_U16
1050 * Constructs a uint64_t value from four uint16_t values.
1051 */
1052#define RT_MAKE_U64_FROM_U16(w0, w1, w2, w3) \
1053 ( (uint64_t)((uint16_t)(w3)) << 48 \
1054 | (uint64_t)((uint16_t)(w2)) << 32 \
1055 | (uint32_t)((uint16_t)(w1)) << 16 \
1056 | (uint16_t)(w0) )
1057
1058/** @def RT_MAKE_U64_FROM_U8
1059 * Constructs a uint64_t value from eight uint8_t values.
1060 */
1061#define RT_MAKE_U64_FROM_U8(b0, b1, b2, b3, b4, b5, b6, b7) \
1062 ( (uint64_t)((uint8_t)(b7)) << 56 \
1063 | (uint64_t)((uint8_t)(b6)) << 48 \
1064 | (uint64_t)((uint8_t)(b5)) << 40 \
1065 | (uint64_t)((uint8_t)(b4)) << 32 \
1066 | (uint32_t)((uint8_t)(b3)) << 24 \
1067 | (uint32_t)((uint8_t)(b2)) << 16 \
1068 | (uint16_t)((uint8_t)(b1)) << 8 \
1069 | (uint8_t)(b0) )
1070
1071/** @def RT_MAKE_U32
1072 * Constructs a uint32_t value from two uint16_t values.
1073 */
1074#define RT_MAKE_U32(Lo, Hi) ( (uint32_t)((uint16_t)(Hi)) << 16 | (uint16_t)(Lo) )
1075
1076/** @def RT_MAKE_U32_FROM_U8
1077 * Constructs a uint32_t value from four uint8_t values.
1078 */
1079#define RT_MAKE_U32_FROM_U8(b0, b1, b2, b3) \
1080 ( (uint32_t)((uint8_t)(b3)) << 24 \
1081 | (uint32_t)((uint8_t)(b2)) << 16 \
1082 | (uint16_t)((uint8_t)(b1)) << 8 \
1083 | (uint8_t)(b0) )
1084
1085/** @def RT_MAKE_U16
1086 * Constructs a uint32_t value from two uint16_t values.
1087 */
1088#define RT_MAKE_U16(Lo, Hi) ( (uint16_t)((uint8_t)(Hi)) << 8 | (uint8_t)(Lo) )
1089
1090
1091/** @def RT_BSWAP_U64
1092 * Reverses the byte order of an uint64_t value. */
1093#if 0
1094# define RT_BSWAP_U64(u64) RT_BSWAP_U64_C(u64)
1095#elif defined(__GNUC__)
1096/** @todo use __builtin_constant_p? */
1097# define RT_BSWAP_U64(u64) ASMByteSwapU64(u64)
1098#else
1099# define RT_BSWAP_U64(u64) ASMByteSwapU64(u64)
1100#endif
1101
1102/** @def RT_BSWAP_U32
1103 * Reverses the byte order of an uint32_t value. */
1104#if 0
1105# define RT_BSWAP_U32(u32) RT_BSWAP_U32_C(u32)
1106#elif defined(__GNUC__)
1107/** @todo use __builtin_constant_p? */
1108# define RT_BSWAP_U32(u32) ASMByteSwapU32(u32)
1109#else
1110# define RT_BSWAP_U32(u32) ASMByteSwapU32(u32)
1111#endif
1112
1113/** @def RT_BSWAP_U16
1114 * Reverses the byte order of an uint16_t value. */
1115#if 0
1116# define RT_BSWAP_U16(u16) RT_BSWAP_U16_C(u16)
1117#elif defined(__GNUC__)
1118/** @todo use __builtin_constant_p? */
1119# define RT_BSWAP_U16(u16) ASMByteSwapU16(u16)
1120#else
1121# define RT_BSWAP_U16(u16) ASMByteSwapU16(u16)
1122#endif
1123
1124
1125/** @def RT_BSWAP_U64_C
1126 * Reverses the byte order of an uint64_t constant. */
1127#define RT_BSWAP_U64_C(u64) RT_MAKE_U64(RT_BSWAP_U32_C((u64) >> 32), RT_BSWAP_U32_C((u64) & 0xffffffff))
1128
1129/** @def RT_BSWAP_U32_C
1130 * Reverses the byte order of an uint32_t constant. */
1131#define RT_BSWAP_U32_C(u32) (RT_BYTE4(u32) | (RT_BYTE3(u32) << 8) | (RT_BYTE2(u32) << 16) | (RT_BYTE1(u32) << 24))
1132
1133/** @def RT_BSWAP_U16_C
1134 * Reverses the byte order of an uint16_t constant. */
1135#define RT_BSWAP_U16_C(u16) (RT_HIBYTE(u16) | (RT_LOBYTE(u16) << 8))
1136
1137
1138/** @def RT_H2LE_U64
1139 * Converts an uint64_t value from host to little endian byte order. */
1140#ifdef RT_BIG_ENDIAN
1141# define RT_H2LE_U64(u64) RT_BSWAP_U64(u64)
1142#else
1143# define RT_H2LE_U64(u64) (u64)
1144#endif
1145
1146/** @def RT_H2LE_U64_C
1147 * Converts an uint64_t constant from host to little endian byte order. */
1148#ifdef RT_BIG_ENDIAN
1149# define RT_H2LE_U64_C(u64) RT_BSWAP_U64_C(u64)
1150#else
1151# define RT_H2LE_U64_C(u64) (u64)
1152#endif
1153
1154/** @def RT_H2LE_U32
1155 * Converts an uint32_t value from host to little endian byte order. */
1156#ifdef RT_BIG_ENDIAN
1157# define RT_H2LE_U32(u32) RT_BSWAP_U32(u32)
1158#else
1159# define RT_H2LE_U32(u32) (u32)
1160#endif
1161
1162/** @def RT_H2LE_U32_C
1163 * Converts an uint32_t constant from host to little endian byte order. */
1164#ifdef RT_BIG_ENDIAN
1165# define RT_H2LE_U32_C(u32) RT_BSWAP_U32_C(u32)
1166#else
1167# define RT_H2LE_U32_C(u32) (u32)
1168#endif
1169
1170/** @def RT_H2LE_U16
1171 * Converts an uint16_t value from host to little endian byte order. */
1172#ifdef RT_BIG_ENDIAN
1173# define RT_H2LE_U16(u16) RT_BSWAP_U16(u16)
1174#else
1175# define RT_H2LE_U16(u16) (u16)
1176#endif
1177
1178/** @def RT_H2LE_U16_C
1179 * Converts an uint16_t constant from host to little endian byte order. */
1180#ifdef RT_BIG_ENDIAN
1181# define RT_H2LE_U16_C(u16) RT_BSWAP_U16_C(u16)
1182#else
1183# define RT_H2LE_U16_C(u16) (u16)
1184#endif
1185
1186
1187/** @def RT_LE2H_U64
1188 * Converts an uint64_t value from little endian to host byte order. */
1189#ifdef RT_BIG_ENDIAN
1190# define RT_LE2H_U64(u64) RT_BSWAP_U64(u64)
1191#else
1192# define RT_LE2H_U64(u64) (u64)
1193#endif
1194
1195/** @def RT_LE2H_U64_C
1196 * Converts an uint64_t constant from little endian to host byte order. */
1197#ifdef RT_BIG_ENDIAN
1198# define RT_LE2H_U64_C(u64) RT_BSWAP_U64_C(u64)
1199#else
1200# define RT_LE2H_U64_C(u64) (u64)
1201#endif
1202
1203/** @def RT_LE2H_U32
1204 * Converts an uint32_t value from little endian to host byte order. */
1205#ifdef RT_BIG_ENDIAN
1206# define RT_LE2H_U32(u32) RT_BSWAP_U32(u32)
1207#else
1208# define RT_LE2H_U32(u32) (u32)
1209#endif
1210
1211/** @def RT_LE2H_U32_C
1212 * Converts an uint32_t constant from little endian to host byte order. */
1213#ifdef RT_BIG_ENDIAN
1214# define RT_LE2H_U32_C(u32) RT_BSWAP_U32_C(u32)
1215#else
1216# define RT_LE2H_U32_C(u32) (u32)
1217#endif
1218
1219/** @def RT_LE2H_U16
1220 * Converts an uint16_t value from little endian to host byte order. */
1221#ifdef RT_BIG_ENDIAN
1222# define RT_LE2H_U16(u16) RT_BSWAP_U16(u16)
1223#else
1224# define RT_LE2H_U16(u16) (u16)
1225#endif
1226
1227/** @def RT_LE2H_U16_C
1228 * Converts an uint16_t constant from little endian to host byte order. */
1229#ifdef RT_BIG_ENDIAN
1230# define RT_LE2H_U16_C(u16) RT_BSWAP_U16_C(u16)
1231#else
1232# define RT_LE2H_U16_C(u16) (u16)
1233#endif
1234
1235
1236/** @def RT_H2BE_U64
1237 * Converts an uint64_t value from host to big endian byte order. */
1238#ifdef RT_BIG_ENDIAN
1239# define RT_H2BE_U64(u64) (u64)
1240#else
1241# define RT_H2BE_U64(u64) RT_BSWAP_U64(u64)
1242#endif
1243
1244/** @def RT_H2BE_U64_C
1245 * Converts an uint64_t constant from host to big endian byte order. */
1246#ifdef RT_BIG_ENDIAN
1247# define RT_H2BE_U64_C(u64) (u64)
1248#else
1249# define RT_H2BE_U64_C(u64) RT_BSWAP_U64_C(u64)
1250#endif
1251
1252/** @def RT_H2BE_U32
1253 * Converts an uint32_t value from host to big endian byte order. */
1254#ifdef RT_BIG_ENDIAN
1255# define RT_H2BE_U32(u32) (u32)
1256#else
1257# define RT_H2BE_U32(u32) RT_BSWAP_U32(u32)
1258#endif
1259
1260/** @def RT_H2BE_U32_C
1261 * Converts an uint32_t constant from host to big endian byte order. */
1262#ifdef RT_BIG_ENDIAN
1263# define RT_H2BE_U32_C(u32) (u32)
1264#else
1265# define RT_H2BE_U32_C(u32) RT_BSWAP_U32_C(u32)
1266#endif
1267
1268/** @def RT_H2BE_U16
1269 * Converts an uint16_t value from host to big endian byte order. */
1270#ifdef RT_BIG_ENDIAN
1271# define RT_H2BE_U16(u16) (u16)
1272#else
1273# define RT_H2BE_U16(u16) RT_BSWAP_U16(u16)
1274#endif
1275
1276/** @def RT_H2BE_U16_C
1277 * Converts an uint16_t constant from host to big endian byte order. */
1278#ifdef RT_BIG_ENDIAN
1279# define RT_H2BE_U16_C(u16) (u16)
1280#else
1281# define RT_H2BE_U16_C(u16) RT_BSWAP_U16_C(u16)
1282#endif
1283
1284/** @def RT_BE2H_U64
1285 * Converts an uint64_t value from big endian to host byte order. */
1286#ifdef RT_BIG_ENDIAN
1287# define RT_BE2H_U64(u64) (u64)
1288#else
1289# define RT_BE2H_U64(u64) RT_BSWAP_U64(u64)
1290#endif
1291
1292/** @def RT_BE2H_U64
1293 * Converts an uint64_t constant from big endian to host byte order. */
1294#ifdef RT_BIG_ENDIAN
1295# define RT_BE2H_U64_C(u64) (u64)
1296#else
1297# define RT_BE2H_U64_C(u64) RT_BSWAP_U64_C(u64)
1298#endif
1299
1300/** @def RT_BE2H_U32
1301 * Converts an uint32_t value from big endian to host byte order. */
1302#ifdef RT_BIG_ENDIAN
1303# define RT_BE2H_U32(u32) (u32)
1304#else
1305# define RT_BE2H_U32(u32) RT_BSWAP_U32(u32)
1306#endif
1307
1308/** @def RT_BE2H_U32_C
1309 * Converts an uint32_t value from big endian to host byte order. */
1310#ifdef RT_BIG_ENDIAN
1311# define RT_BE2H_U32_C(u32) (u32)
1312#else
1313# define RT_BE2H_U32_C(u32) RT_BSWAP_U32_C(u32)
1314#endif
1315
1316/** @def RT_BE2H_U16
1317 * Converts an uint16_t value from big endian to host byte order. */
1318#ifdef RT_BIG_ENDIAN
1319# define RT_BE2H_U16(u16) (u16)
1320#else
1321# define RT_BE2H_U16(u16) RT_BSWAP_U16(u16)
1322#endif
1323
1324/** @def RT_BE2H_U16_C
1325 * Converts an uint16_t constant from big endian to host byte order. */
1326#ifdef RT_BIG_ENDIAN
1327# define RT_BE2H_U16_C(u16) (u16)
1328#else
1329# define RT_BE2H_U16_C(u16) RT_BSWAP_U16_C(u16)
1330#endif
1331
1332
1333/** @def RT_H2N_U64
1334 * Converts an uint64_t value from host to network byte order. */
1335#define RT_H2N_U64(u64) RT_H2BE_U64(u64)
1336
1337/** @def RT_H2N_U64_C
1338 * Converts an uint64_t constant from host to network byte order. */
1339#define RT_H2N_U64_C(u64) RT_H2BE_U64_C(u64)
1340
1341/** @def RT_H2N_U32
1342 * Converts an uint32_t value from host to network byte order. */
1343#define RT_H2N_U32(u32) RT_H2BE_U32(u32)
1344
1345/** @def RT_H2N_U32_C
1346 * Converts an uint32_t constant from host to network byte order. */
1347#define RT_H2N_U32_C(u32) RT_H2BE_U32_C(u32)
1348
1349/** @def RT_H2N_U16
1350 * Converts an uint16_t value from host to network byte order. */
1351#define RT_H2N_U16(u16) RT_H2BE_U16(u16)
1352
1353/** @def RT_H2N_U16_C
1354 * Converts an uint16_t constant from host to network byte order. */
1355#define RT_H2N_U16_C(u16) RT_H2BE_U16_C(u16)
1356
1357/** @def RT_N2H_U64
1358 * Converts an uint64_t value from network to host byte order. */
1359#define RT_N2H_U64(u64) RT_BE2H_U64(u64)
1360
1361/** @def RT_N2H_U64_C
1362 * Converts an uint64_t constant from network to host byte order. */
1363#define RT_N2H_U64_C(u64) RT_BE2H_U64_C(u64)
1364
1365/** @def RT_N2H_U32
1366 * Converts an uint32_t value from network to host byte order. */
1367#define RT_N2H_U32(u32) RT_BE2H_U32(u32)
1368
1369/** @def RT_N2H_U32_C
1370 * Converts an uint32_t constant from network to host byte order. */
1371#define RT_N2H_U32_C(u32) RT_BE2H_U32_C(u32)
1372
1373/** @def RT_N2H_U16
1374 * Converts an uint16_t value from network to host byte order. */
1375#define RT_N2H_U16(u16) RT_BE2H_U16(u16)
1376
1377/** @def RT_N2H_U16_C
1378 * Converts an uint16_t value from network to host byte order. */
1379#define RT_N2H_U16_C(u16) RT_BE2H_U16_C(u16)
1380
1381
1382/*
1383 * The BSD sys/param.h + machine/param.h file is a major source of
1384 * namespace pollution. Kill off some of the worse ones unless we're
1385 * compiling kernel code.
1386 */
1387#if defined(RT_OS_DARWIN) \
1388 && !defined(KERNEL) \
1389 && !defined(RT_NO_BSD_PARAM_H_UNDEFING) \
1390 && ( defined(_SYS_PARAM_H_) || defined(_I386_PARAM_H_) )
1391/* sys/param.h: */
1392# undef PSWP
1393# undef PVM
1394# undef PINOD
1395# undef PRIBO
1396# undef PVFS
1397# undef PZERO
1398# undef PSOCK
1399# undef PWAIT
1400# undef PLOCK
1401# undef PPAUSE
1402# undef PUSER
1403# undef PRIMASK
1404# undef MINBUCKET
1405# undef MAXALLOCSAVE
1406# undef FSHIFT
1407# undef FSCALE
1408
1409/* i386/machine.h: */
1410# undef ALIGN
1411# undef ALIGNBYTES
1412# undef DELAY
1413# undef STATUS_WORD
1414# undef USERMODE
1415# undef BASEPRI
1416# undef MSIZE
1417# undef CLSIZE
1418# undef CLSIZELOG2
1419#endif
1420
1421
1422/** @def NULL
1423 * NULL pointer.
1424 */
1425#ifndef NULL
1426# ifdef __cplusplus
1427# define NULL 0
1428# else
1429# define NULL ((void*)0)
1430# endif
1431#endif
1432
1433/** @def NIL_OFFSET
1434 * NIL offset.
1435 * Whenever we use offsets instead of pointers to save space and relocation effort
1436 * NIL_OFFSET shall be used as the equivalent to NULL.
1437 */
1438#define NIL_OFFSET (~0U)
1439
1440/** @def NOREF
1441 * Keeps the compiler from bitching about an unused parameters.
1442 */
1443#define NOREF(var) (void)(var)
1444
1445/** @def Breakpoint
1446 * Emit a debug breakpoint instruction.
1447 *
1448 * Use this for instrumenting a debugging session only!
1449 * No comitted code shall use Breakpoint().
1450 */
1451#ifdef __GNUC__
1452# define Breakpoint() __asm__ __volatile__("int $3\n\t")
1453#endif
1454#ifdef _MSC_VER
1455# define Breakpoint() __asm int 3
1456#endif
1457#if defined(__IBMC__) || defined(__IBMCPP__)
1458# define Breakpoint() __interrupt(3)
1459#endif
1460#ifndef Breakpoint
1461# error "This compiler is not supported!"
1462#endif
1463
1464
1465/** Size Constants
1466 * (Of course, these are binary computer terms, not SI.)
1467 * @{
1468 */
1469/** 1 K (Kilo) (1 024). */
1470#define _1K 0x00000400
1471/** 4 K (Kilo) (4 096). */
1472#define _4K 0x00001000
1473/** 32 K (Kilo) (32 678). */
1474#define _32K 0x00008000
1475/** 64 K (Kilo) (65 536). */
1476#define _64K 0x00010000
1477/** 128 K (Kilo) (131 072). */
1478#define _128K 0x00020000
1479/** 256 K (Kilo) (262 144). */
1480#define _256K 0x00040000
1481/** 512 K (Kilo) (524 288). */
1482#define _512K 0x00080000
1483/** 1 M (Mega) (1 048 576). */
1484#define _1M 0x00100000
1485/** 2 M (Mega) (2 097 152). */
1486#define _2M 0x00200000
1487/** 4 M (Mega) (4 194 304). */
1488#define _4M 0x00400000
1489/** 1 G (Giga) (1 073 741 824). */
1490#define _1G 0x40000000
1491/** 2 G (Giga) (2 147 483 648). (32-bit) */
1492#define _2G32 0x80000000U
1493/** 2 G (Giga) (2 147 483 648). (64-bit) */
1494#define _2G 0x0000000080000000LL
1495/** 4 G (Giga) (4 294 967 296). */
1496#define _4G 0x0000000100000000LL
1497/** 1 T (Tera) (1 099 511 627 776). */
1498#define _1T 0x0000010000000000LL
1499/** 1 P (Peta) (1 125 899 906 842 624). */
1500#define _1P 0x0004000000000000LL
1501/** 1 E (Exa) (1 152 921 504 606 846 976). */
1502#define _1E 0x1000000000000000LL
1503/** 2 E (Exa) (2 305 843 009 213 693 952). */
1504#define _2E 0x2000000000000000ULL
1505/** @} */
1506
1507/** @def VALID_PTR
1508 * Pointer validation macro.
1509 * @param ptr
1510 */
1511#if defined(RT_ARCH_AMD64)
1512# ifdef IN_RING3
1513# if defined(RT_OS_DARWIN) /* first 4GB is reserved for legacy kernel. */
1514# define VALID_PTR(ptr) ( (uintptr_t)(ptr) >= _4G \
1515 && !((uintptr_t)(ptr) & 0xffff800000000000ULL) )
1516# elif defined(RT_OS_SOLARIS) /* The kernel only used the top 2TB, but keep it simple. */
1517# define VALID_PTR(ptr) ( (uintptr_t)(ptr) + 0x1000U >= 0x2000U \
1518 && ( ((uintptr_t)(ptr) & 0xffff800000000000ULL) == 0xffff800000000000ULL \
1519 || ((uintptr_t)(ptr) & 0xffff800000000000ULL) == 0) )
1520# else
1521# define VALID_PTR(ptr) ( (uintptr_t)(ptr) + 0x1000U >= 0x2000U \
1522 && !((uintptr_t)(ptr) & 0xffff800000000000ULL) )
1523# endif
1524# else /* !IN_RING3 */
1525# define VALID_PTR(ptr) ( (uintptr_t)(ptr) + 0x1000U >= 0x2000U \
1526 && ( ((uintptr_t)(ptr) & 0xffff800000000000ULL) == 0xffff800000000000ULL \
1527 || ((uintptr_t)(ptr) & 0xffff800000000000ULL) == 0) )
1528# endif /* !IN_RING3 */
1529#elif defined(RT_ARCH_X86)
1530# define VALID_PTR(ptr) ( (uintptr_t)(ptr) + 0x1000U >= 0x2000U )
1531#else
1532# error "Architecture identifier missing / not implemented."
1533#endif
1534
1535
1536/** @def VALID_PHYS32
1537 * 32 bits physical address validation macro.
1538 * @param Phys The RTGCPHYS address.
1539 */
1540#define VALID_PHYS32(Phys) ( (uint64_t)(Phys) < (uint64_t)_4G )
1541
1542/** @def N_
1543 * The \#define N_ is used mark a string for translation. This is usable in
1544 * any part of the code, as it is only used by the tools that create message
1545 * catalogs. This macro is a no-op as far as the compiler and code generation
1546 * is concerned.
1547 *
1548 * If you want to both mark a string for translation and translate it, use _.
1549 */
1550#define N_(s) (s)
1551
1552/** @def _
1553 * The \#define _ is used mark a string for translation and to translate it in
1554 * one step.
1555 *
1556 * If you want to only mark a string for translation, use N_.
1557 */
1558#define _(s) gettext(s)
1559
1560
1561/** @def __PRETTY_FUNCTION__
1562 * With GNU C we'd like to use the builtin __PRETTY_FUNCTION__, so define that for the other compilers.
1563 */
1564#if !defined(__GNUC__) && !defined(__PRETTY_FUNCTION__)
1565# define __PRETTY_FUNCTION__ __FUNCTION__
1566#endif
1567
1568
1569/** @def RT_STRICT
1570 * The \#define RT_STRICT controls whether or not assertions and other runtime checks
1571 * should be compiled in or not.
1572 *
1573 * If you want assertions which are not a subject to compile time options use
1574 * the AssertRelease*() flavors.
1575 */
1576#if !defined(RT_STRICT) && defined(DEBUG)
1577# define RT_STRICT
1578#endif
1579
1580/** Source position. */
1581#define RT_SRC_POS __FILE__, __LINE__, __PRETTY_FUNCTION__
1582
1583/** Source position declaration. */
1584#define RT_SRC_POS_DECL const char *pszFile, unsigned iLine, const char *pszFunction
1585
1586/** Source position arguments. */
1587#define RT_SRC_POS_ARGS pszFile, iLine, pszFunction
1588
1589/** @} */
1590
1591
1592/** @defgroup grp_rt_cdefs_cpp Special Macros for C++
1593 * @ingroup grp_rt_cdefs
1594 * @{
1595 */
1596
1597#ifdef __cplusplus
1598
1599/** @def DECLEXPORT_CLASS
1600 * How to declare an exported class. Place this macro after the 'class'
1601 * keyword in the declaration of every class you want to export.
1602 *
1603 * @note It is necessary to use this macro even for inner classes declared
1604 * inside the already exported classes. This is a GCC specific requirement,
1605 * but it seems not to harm other compilers.
1606 */
1607#if defined(_MSC_VER) || defined(RT_OS_OS2)
1608# define DECLEXPORT_CLASS __declspec(dllexport)
1609#elif defined(RT_USE_VISIBILITY_DEFAULT)
1610# define DECLEXPORT_CLASS __attribute__((visibility("default")))
1611#else
1612# define DECLEXPORT_CLASS
1613#endif
1614
1615/** @def DECLIMPORT_CLASS
1616 * How to declare an imported class Place this macro after the 'class'
1617 * keyword in the declaration of every class you want to export.
1618 *
1619 * @note It is necessary to use this macro even for inner classes declared
1620 * inside the already exported classes. This is a GCC specific requirement,
1621 * but it seems not to harm other compilers.
1622 */
1623#if defined(_MSC_VER) || (defined(RT_OS_OS2) && !defined(__IBMC__) && !defined(__IBMCPP__))
1624# define DECLIMPORT_CLASS __declspec(dllimport)
1625#elif defined(RT_USE_VISIBILITY_DEFAULT)
1626# define DECLIMPORT_CLASS __attribute__((visibility("default")))
1627#else
1628# define DECLIMPORT_CLASS
1629#endif
1630
1631/** @def WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP
1632 * Macro to work around error C2593 of the not-so-smart MSVC 7.x ambiguity
1633 * resolver. The following snippet clearly demonstrates the code causing this
1634 * error:
1635 * @code
1636 * class A
1637 * {
1638 * public:
1639 * operator bool() const { return false; }
1640 * operator int*() const { return NULL; }
1641 * };
1642 * int main()
1643 * {
1644 * A a;
1645 * if (!a);
1646 * if (a && 0);
1647 * return 0;
1648 * }
1649 * @endcode
1650 * The code itself seems pretty valid to me and GCC thinks the same.
1651 *
1652 * This macro fixes the compiler error by explicitly overloading implicit
1653 * global operators !, && and || that take the given class instance as one of
1654 * their arguments.
1655 *
1656 * The best is to use this macro right after the class declaration.
1657 *
1658 * @note The macro expands to nothing for compilers other than MSVC.
1659 *
1660 * @param Cls Class to apply the workaround to
1661 */
1662#if defined(_MSC_VER)
1663# define WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP(Cls) \
1664 inline bool operator! (const Cls &that) { return !bool (that); } \
1665 inline bool operator&& (const Cls &that, bool b) { return bool (that) && b; } \
1666 inline bool operator|| (const Cls &that, bool b) { return bool (that) || b; } \
1667 inline bool operator&& (bool b, const Cls &that) { return b && bool (that); } \
1668 inline bool operator|| (bool b, const Cls &that) { return b || bool (that); }
1669#else
1670# define WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP(Cls)
1671#endif
1672
1673/** @def WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP_TPL
1674 * Version of WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP for template classes.
1675 *
1676 * @param Tpl Name of the template class to apply the workaround to
1677 * @param ArgsDecl arguments of the template, as declared in |<>| after the
1678 * |template| keyword, including |<>|
1679 * @param Args arguments of the template, as specified in |<>| after the
1680 * template class name when using the, including |<>|
1681 *
1682 * Example:
1683 * @code
1684 * // template class declaration
1685 * template <class C>
1686 * class Foo { ... };
1687 * // applied workaround
1688 * WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP_TPL (Foo, <class C>, <C>)
1689 * @endcode
1690 */
1691#if defined(_MSC_VER)
1692# define WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP_TPL(Tpl, ArgsDecl, Args) \
1693 template ArgsDecl \
1694 inline bool operator! (const Tpl Args &that) { return !bool (that); } \
1695 template ArgsDecl \
1696 inline bool operator&& (const Tpl Args &that, bool b) { return bool (that) && b; } \
1697 template ArgsDecl \
1698 inline bool operator|| (const Tpl Args &that, bool b) { return bool (that) || b; } \
1699 template ArgsDecl \
1700 inline bool operator&& (bool b, const Tpl Args &that) { return b && bool (that); } \
1701 template ArgsDecl \
1702 inline bool operator|| (bool b, const Tpl Args &that) { return b || bool (that); }
1703#else
1704# define WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP_TPL(Tpl, ArgsDecl, Args)
1705#endif
1706
1707
1708/** @def DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP
1709 * Declares the copy constructor and the assignment operation as inlined no-ops
1710 * (non-existent functions) for the given class. Use this macro inside the
1711 * private section if you want to effectively disable these operations for your
1712 * class.
1713 *
1714 * @param Cls class name to declare for
1715 */
1716
1717#define DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(Cls) \
1718 inline Cls (const Cls &); \
1719 inline Cls &operator= (const Cls &);
1720
1721
1722/** @def DECLARE_CLS_NEW_DELETE_NOOP
1723 * Declares the new and delete operations as no-ops (non-existent functions)
1724 * for the given class. Use this macro inside the private section if you want
1725 * to effectively limit creating class instances on the stack only.
1726 *
1727 * @note The destructor of the given class must not be virtual, otherwise a
1728 * compile time error will occur. Note that this is not a drawback: having
1729 * the virtual destructor for a stack-based class is absolutely useless
1730 * (the real class of the stack-based instance is always known to the compiler
1731 * at compile time, so it will always call the correct destructor).
1732 *
1733 * @param Cls class name to declare for
1734 */
1735#define DECLARE_CLS_NEW_DELETE_NOOP(Cls) \
1736 inline static void *operator new (size_t); \
1737 inline static void operator delete (void *);
1738
1739#endif /* defined(__cplusplus) */
1740
1741/** @} */
1742
1743#endif
1744
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use