General Macros

_ASSERTE

Defined in clr/src/inc/debugmacros.h, this is used to verify that an invariant holds true at runtime in debug-enabled builds.

C_ASSERT

CPP_ASSERT

These macros are used for language-specific compile-time assertions.

DEFINE_LOG_FACILITY

Defined in clr/src/inc/loglf.h to produce the list found in clr/src/inc/loglf.h, this is used to define facilities called out for individual configurability when tracing.

GET_UNALIGNED_16

GET_UNALIGNED_32

GET_UNALIGNED_64

Defined in clr/src/inc/palclr.h, these macros dereference a pointer and fetch a value, even if the pointer is not a naturally-aligned pointer. Natural alignment is defined as ((UINT_PTR)p & (sizeof(p)-1)) == 0.

For platforms that automatically handle misaligned memory references, these macros expand to a simple dereference. See also SET_UNALIGNED.

IfFailGoto

IfFailGo

IfFailRet

Also defined in clr/src/inc/debugmacros.h, these are used to branch conditionally on HRESULT values.

LOG

Defined in clr/src/inc/log.h, this is used in debug-enabled builds to issue a logging message. See also DEFINE_LOG_FACILITY.

MAKEDLLNAME_A

MAKEDLLNAME_W

These macros are used to convert a platform-independent basename into a platform-specific loadable library name. They append the operating system-specific prefix and suffix to the generic name. For example, MAKEDLLNAME_A("foo") will create libfoo.dylib on Mac OS X, libfoo.so on FreeBSD, and foo.dll on Windows. These macros are defined in clr/src/inc/palclr.h.

OPDEF

Use this macro, found in clr/src/inc/openum.h, to define CLI opcodes. The file clr/src/inc/opcode.def contains all opcode definitions for Rotor, and is shared by the C# compiler, the assembler and disassembler, and the execution engine.

PORTABILITY_ASSERT

PORTABILITY_WARNING

These are used within regions of code that differ from platform to platform. They are no-ops while working on a port, and once you've finished porting a platform-specific region, its WARNING should be changed to a matching ASSERT. To find regions of code that are platform-specific, use your favorite search or indexing utility to find these macros .

SET_UNALIGNED_16

SET_UNALIGNED_32

SET_UNALIGNED_64

Defined in clr/src/inc/palclr.h, these store a value into a pointer, even if the pointer is not naturally aligned. For platforms that automatically handle mis-aligned memory references, these macros expand to a simple dereferenced assignment. See also GET_UNALIGNED.

SwapString

SwapStringLength

SwapGuid

Defined in clr/src/inc/palclr.h, these perform an in-place byte swap of a string, counted string, or GUID structure.

VAL16

VAL32

VAL64

Defined in clr/src/inc/palclr.h, these are used to simplify writing code to run on both big-endian and little-endian processors. They are no-ops on little-endian platforms, but byte-swapped on big-endian platforms. Given a value composed of 16, 32, or 64 bits in little-endian format, they return the value in the native format.

 

Execution Engine Macros

BEGIN_FORBID

ENDFORBID

Defined in clr/src/vm/threads.h, these macros bracket code in which garbage collection is forbidden. They are activated in debug-enabled builds only.

COMPlusThrow

This macro, defined in clr/src/vm/exceptmacros.h, is used to throw exceptions from within execution engine code.

COMPLUS_TRY

COMPLUS_CATCH

COMPLUS_END_CATCH

COMPLUS_FINALLY

COMPLUS_END_FINALLY

These macros wrap the PAL_TRY family of macros with additional code that maintains internal execution engine data structures. In particular, these protect the integrity of the frame chain. They are defined in clr/src/vm/exceptmacros.h.

EE_TRY_FOR_FINALLY

EE_ FINALLY

EE_END_FINALLY

This is a simplified version of the COMPLUS_TRY macro that supports only finally clauses. (COMPLUS_TRY supports both catch and finally clauses.) It is defined in clr/src/vm/exceptmacros.h.

FCDECL*

FCIMPL*

The macros from this large series, defined and documented in clr/src/vm/fcall.h, are used to declare and implement FCalls. Platform-to-platform differences in FCall calling conventions are encapsulated inside these macros.

FCThrow

This macro is used to throw exceptions from within FCall implementations when a helper frame is not erected for the FCall. (COMPlusThrow would be used to throw exceptions if a helper frame were erected.) It is defined in clr/src/vm/frames.h.

GCPROTECT_BEGIN

GCPROTECT_ARRAY_BEGIN

GCPROTECT_BEGININTERIOR

GCPROTECT_END

This series of macros is used to mark memory locations (usually local variables) that contain object references. Locations that are protected using GC_PROTECT are visible to the garbage collector, and the objects that they reference can be promoted safely. These macros are defined in clr/src/vm/frames.h.

GETTHROWABLE

SETTHROWABLE

Defined in clr/src/vm/exceptmacros.h, these macros are used to get or set the thrown exception. GETTHROWABLE is usually used inside a COMPLUS_CATCH clause.

HELPER_METHOD_FRAME_*

Defined in clr/src/vm/fcall.h, these macros are used to erect a helper frame within an FCall implementation. These helper frames must exist when an FCall wishes to call other parts of the execution engine that might trigger garbage collection or cause nonlocal changes. Simple FCalls do not need helper frames. Some flavors of HELPER_METHOD_FRAME expose a simplified version of GC_PROTECT, to reduce the number of frames pushed in the FCall.

THROWSCOMPLUSEXCEPTION

This macro, defined in clr/src/vm/exceptmacros.h, is used to mark code blocks that can throw exceptions. This is used only in debug-enabled builds.

TRIGGERSGC

This macro is used in debug-enabled builds to mark code blocks that can trigger garbage collection. It is defined in clr/src/vm/threads.h.

 

JIT Compiler Macros

CHECK_STACK

CHECK_STACK_SIZE

When verification is turned on, these macros will verify that the evaluation stack is deep enough to be valid or that it matches an exact depth.

FJIT_FAIL

This macro will cause the current JIT compilation to fail and return an error code.

VALIDITY_CHECK

If verification is turned on, this macro will conditionally terminate a JIT compilation and return an error code that indicates that invalid code was provided.

VERIFICATION_CHECK

If verification is turned on, this macro will conditionally emit code to throw a verification exception. It is used within the JIT compiler.

There is a large series of macros used to emit code, which is contained in clr/src/fjit/fjitdef.h and is augmented by platform-specific redefinition files that can be found in subdirectories named after their processor targets:

 

x86_*

These are low-level, x86-specific macros used by fjitdef.h.

ppc_*

These are low-level, PowerPC-specific macros used by fjitdef.h.

emit_*

These are high-level, macros defined in fjitdef.h that can be redefined by platform-specific low-level macros.

emit_<IL OPCODE NAME>_*

These are portable macros that implement opcodes, and are frequently separated by the size of the stack and frame registers.

ARG_*

These definitions represent argument registers.

RETURN_*

These definitions represent return value registers.

The file clr/src/fjit/fjitdef.h also contains macros used to emit code for manipulating the stack and calling helper functions:

deregisterTOS

enregisterTOS

These macros are used by the JIT compiler to manage the top of the stack.

emit_arg

emit_reg_arg

emit_tos_arg

emit_tos_fixedsize_arg

emit_tos_indirect_to_arg

emit_reg_to_arg

These simple portable calling convention macros are used by the JIT compiler to set up arguments being passed on the stack.

emit_callhelper_*

These macros represent a portable way to make a call to a helper function.

emit_loadresult_*

emit_pushresult_*

These macros manage return value placement. (The mechanism used to return values is platform-specific.)

Finally, there are a few JIT macros that affect the runtime execution of code:

LABELSTACK

This macro, defined in clr/src/fjit/fjit.cpp, saves the a map of the evaluation stack and associates it with the current IL offset so that the garbage collector will be able to find roots on the stack. This macro is used before calls to JIT helper functions that may trigger garbage collection.

THROW_FROM_HELPER

THROW_FROM_HELPER_RET

These macros define a mechanism by which JIT helper functions can construct an exception context as though the exception occurred within the code of the JIT-compiled function that called them rather than in their own code. They are defined in clr/src/fjit/fjit.h.

 

PAL & Platform Macros

_PPC_

This is defined when compiling for Motorola PowerPC.

_X86_

This is defined when compiling for Intel x86.

BIGENDIAN

This is defined on big-endian platforms, and undefined on little-endian platforms.

HAVE_CASE_SENSITIVE_FILESYSTEM

This macro is defined to differentiate filesystems that are case-sensitive, such as FreeBSD, from filesystems that are case-insensitive, such as Windows or HFS+, the default and most frequently used Mac OS X filesystem.

HAVE_CFSTRING

This is defined if Mac OS X CoreFoundation CFString is present.

HAVE_COMPATIBLE_ASIN

HAVE_COMPATIBLE_ACOS

HAVE_COMPATIBLE_*

This is defined when C runtime math functions produce Windows-compatible results for edge-case values.

HAVE_POLL

This is defined if the poll( ) system call is implemented.

HAVE_STRTOK_R

This is defined if the strok_r( ) API is implemented.

MMAP_IGNORES_HINT

This is set when the mmap( ) system call ignores its hint argument.

PAL_TRY

PAL_EXCEPT

PAL_EXCEPT_EX

PAL_EXCEPT_FILTER

PAL_EXCEPT_FILTER_EX

PAL_FINALLY

PAL_FINALLY_EX

PAL_ENDTRY

The file pal/rotor_pal.h contains the API definitions for the PAL, as well as these macros, which result in calls against the PAL's exception-handling mechanism.

PLATFORM_UNIX

This is defined when building for Unix systems, and is used to control the formatting of things dictated by convention, such as line breaks, path and environment separator characters, and the like.

There are a number of macros used within the Unix PAL implementation:

ASSERT

This macro is different from the Win32 PAL and execution engine ASSERT macros in that it doesn't take an expression as an argument. It is a printf-style logger plus an optional debug breakpoint. This is a no-op in the "free" build.

LOGAPI

This is a printf-style logging call for the PAL. It is a no-ops in the "free" build.

PALASSERT

This macro asserts if its argument is false and is a no-op in the "free" build.

TRACE

WARN

ERROR

These printf-style logging calls are defined in pal/unix/include/dbgmsg.h and are no-ops in the "free" build.