1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Random123-1.09: Preprocessor symbols for porting Random123 to different platforms.</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body onload='searchBox.OnSelectItem(0);'>
<div class="tabs"><ul class="tablist"><li style="padding-left: 1.5em; font-weight: bold">Random123-1.09 Documentation</li></ul></div>
<!-- Generated by Doxygen 1.7.1 -->
<script type="text/javascript"><!--
var searchBox = new SearchBox("searchBox", "search",false,'Search');
--></script>
<div class="navigation" id="top">
<div class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li id="searchli">
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<h1>Preprocessor symbols for porting Random123 to different platforms. </h1> </div>
</div>
<div class="contents">
<p>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>).</p>
<p><a class="el" href="compilerfeatures_8h.html">Random123/features/compilerfeatures.h</a> 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.</p>
<p>Most of the symbols are boolean valued. In general, they will <b>always</b> be defined with value either 1 or 0, so do <b>NOT</b> use #ifdef. Use #if R123_USE_SOMETHING instead.</p>
<p>Library users can override any value by defining the pp-symbol with a compiler option, e.g.,</p>
<p>cc -DR123_USE_MULHILO64_C99</p>
<p>will use a strictly c99 version of the full-width 64x64->128-bit multiplication function, even if it would be disabled by default.</p>
<p>All boolean-valued pre-processor symbols in <a class="el" href="compilerfeatures_8h.html">Random123/features/compilerfeatures.h</a> start with the prefix R123_USE_ </p>
<div class="fragment"><pre class="fragment">
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
</pre></div><p> Most have obvious meanings. Some non-obvious ones:</p>
<p>AES_NI and AES_OPENSSL are not mutually exclusive. You can have one, both or neither.</p>
<p>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.</p>
<p>If the XXXINTRIN_H macros are true, then one should </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <xxxintrin.h></span>
</pre></div><p> to gain accesss to compiler intrinsics.</p>
<p>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.</p>
<p>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.</p>
<p>There are a number of invariants that are always true. Application code may choose to rely on these:</p>
<ul>
<li>
ASM_GNU and ASM_MASM are mutually exclusive </li>
<li>
The "higher" SSE values imply the lower ones. </li>
</ul>
<p>There are also non-boolean valued symbols:</p>
<ul>
<li>
<p class="startli">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: <a href="http://gcc.gnu.org/onlinedocs/gcc/Inline.html">http://gcc.gnu.org/onlinedocs/gcc/Inline.html</a> <a href="http://www.greenend.org.uk/rjk/2003/03/inline.html">http://www.greenend.org.uk/rjk/2003/03/inline.html</a></p>
<p class="endli"></p>
</li>
<li>
<p class="startli">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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">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).</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">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.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">R123_ULONG_LONG - which expands to a declaration of the longest available unsigned integer.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli">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.</p>
<p class="endli"></p>
</li>
<li>
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. </li>
</ul>
</div>
<!--- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Friends</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark"> </span>Defines</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<hr class="footer"/><address class="footer"><small>Generated on Mon Mar 7 2016 18:34:00 for Random123-1.09 by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.1 </small></address>
</body>
</html>
|
