- Random123-1.09 Documentation

# Preprocessor symbols for porting Random123 to different platforms.

The Random123 library is portable across C, C++, CUDA, OpenCL environments, and multiple operating systems (Linux, Windows 7, Mac OS X, FreeBSD, Solaris). This level of portability requires the abstraction of some features and idioms that are either not standardized (e.g., asm statments), or for which different vendors have their own standards (e.g., SSE intrinsics) or for which vendors simply refuse to conform to well-established standards (e.g., <inttypes.h>).

Random123/features/compilerfeatures.h conditionally includes a compiler-or-OS-specific Random123/featires/XXXfeatures.h file which defines appropriate values for the preprocessor symbols which can be used with a specific compiler or OS. Those symbols will then be used by other header files and source files in the Random123 library (and may be used by applications) to control what actually gets presented to the compiler.

Most of the symbols are boolean valued. In general, they will always be defined with value either 1 or 0, so do NOT use #ifdef. Use #if R123_USE_SOMETHING instead.

Library users can override any value by defining the pp-symbol with a compiler option, e.g.,

cc -DR123_USE_MULHILO64_C99

will use a strictly c99 version of the full-width 64x64->128-bit multiplication function, even if it would be disabled by default.

All boolean-valued pre-processor symbols in Random123/features/compilerfeatures.h start with the prefix R123_USE_

             AES_NI
             AES_OPENSSL
             SSE4_2
             SSE4_1
             SSE

             STD_RANDOM

             GNU_UINT128
             ASM_GNU
             ASM_MSASM

             CPUID_MSVC

             CXX11_RANDOM
             CXX11_TYPE_TRAITS
             CXX11_STATIC_ASSERT
             CXX11_CONSTEXPR
             CXX11_UNRESTRICTED_UNIONS
             CXX11_EXPLICIT_CONVERSIONS
             CXX11_LONG_LONG
             CXX11

             X86INTRIN_H
             IA32INTRIN_H
             XMMINTRIN_H
             EMMINTRIN_H
             SMMINTRIN_H
             WMMINTRIN_H
             INTRIN_H

             MULHILO32_ASM
             MULHILO64_ASM
             MULHILO64_MSVC_INTRIN
             MULHILO64_CUDA_INTRIN
             MULHILO64_OPENCL_INTRIN
             MULHILO64_C99

             U01_DOUBLE

Most have obvious meanings. Some non-obvious ones:

AES_NI and AES_OPENSSL are not mutually exclusive. You can have one, both or neither.

GNU_UINT128 says that it's safe to use __uint128_t, but it does not require its use. In particular, it should be used in mulhilo<uint64_t> only if MULHILO64_ASM is unset.

If the XXXINTRIN_H macros are true, then one should

    #include <xxxintrin.h>

to gain accesss to compiler intrinsics.

The CXX11_SOME_FEATURE macros allow the code to use specific features of the C++11 language and library. The catchall In the absence of a specific CXX11_SOME_FEATURE, the feature is controlled by the catch-all R123_USE_CXX11 macro.

U01_DOUBLE defaults on, and can be turned off (set to 0) if one does not want the utility functions that convert to double (i.e. u01_*_53()), e.g. on OpenCL without the cl_khr_fp64 extension.

There are a number of invariants that are always true. Application code may choose to rely on these:

- ASM_GNU and ASM_MASM are mutually exclusive
- The "higher" SSE values imply the lower ones.

There are also non-boolean valued symbols:

- R123_STATIC_INLINE - According to both C99 and GNU99, the 'static inline' declaration allows the compiler to not emit code if the function is not used. Note that the semantics of 'inline', 'static' and 'extern' in gcc have changed over time and are subject to modification by command line options, e.g., -std=gnu89, -fgnu-inline. Nevertheless, it appears that the meaning of 'static inline' has not changed over time and (with a little luck) the use of 'static inline' here will be portable between versions of gcc and to other C99 compilers. See: http://gcc.gnu.org/onlinedocs/gcc/Inline.html http://www.greenend.org.uk/rjk/2003/03/inline.html

- R123_FORCE_INLINE(decl) - which expands to 'decl', adorned with the compiler-specific embellishments to strongly encourage that the declared function be inlined. If there is no such compiler-specific magic, it should expand to decl, unadorned.

- R123_CUDA_DEVICE - which expands to __device__ (or something else with sufficiently similar semantics) when CUDA is in use, and expands to nothing in other cases.

- R123_ASSERT(x) - which expands to assert(x), or maybe to nothing at all if we're in an environment so feature-poor that you can't even call assert (I'm looking at you, CUDA and OpenCL), or even include assert.h safely (OpenCL).

- R123_STATIC_ASSERT(expr,msg) - which expands to static_assert(expr,msg), or to an expression that will raise a compile-time exception if expr is not true.

- R123_ULONG_LONG - which expands to a declaration of the longest available unsigned integer.

- R123_64BIT(x) - expands to something equivalent to UINT64_C(x) from <stdint.h>, even in environments where <stdint.h> is not available, e.g., MSVC and OpenCL.

- R123_BUILTIN_EXPECT(expr,likely_value) - expands to something with the semantics of gcc's __builtin_expect(expr,likely_value). If the environment has nothing like __builtin_expect, it should expand to just expr.

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines