| 1 |
@ignore |
| 2 |
Copyright (C) 2022-2025 Free Software Foundation, Inc. |
| 3 |
This is part of the GNU D manual. |
| 4 |
For copying conditions, see the file gdc.texi. |
| 5 |
@end ignore |
| 6 |
|
| 7 |
@node D Implementation |
| 8 |
@chapter Language Reference |
| 9 |
@cindex language reference, D language |
| 10 |
|
| 11 |
The implementation of the D programming language used by the GNU D compiler is |
| 12 |
shared with parts of the front-end for the Digital Mars D compiler, hosted at |
| 13 |
@uref{https://github.com/dlang/dmd/}. This common front-end covers lexical |
| 14 |
analysis, parsing, and semantic analysis of the D programming language defined |
| 15 |
in the documents at @uref{https://dlang.org/}. |
| 16 |
|
| 17 |
The implementation details described in this manual are GNU D extensions to the |
| 18 |
D programming language. If you want to write code that checks whether these |
| 19 |
features are available, you can test for the predefined version @code{GNU}, or |
| 20 |
you can check whether a specific feature is compilable using |
| 21 |
@code{__traits(compiles)}. |
| 22 |
|
| 23 |
@smallexample |
| 24 |
version (GNU) |
| 25 |
@{ |
| 26 |
import gcc.builtins; |
| 27 |
return __builtin_atan2(x, y); |
| 28 |
@} |
| 29 |
|
| 30 |
static if (__traits(compiles, @{ asm @{"";@} @})) |
| 31 |
@{ |
| 32 |
asm @{ "magic instruction"; @} |
| 33 |
@} |
| 34 |
@end smallexample |
| 35 |
|
| 36 |
@menu |
| 37 |
* Attributes:: Implementation-defined attributes. |
| 38 |
* Builtin Functions:: GCC built-ins module. |
| 39 |
* ImportC:: Importing C sources into D. |
| 40 |
* Inline Assembly:: Interfacing D with assembler. |
| 41 |
* Intrinsics:: Intrinsic functions supported by GDC. |
| 42 |
* Predefined Pragmas:: Pragmas accepted by GDC. |
| 43 |
* Predefined Versions:: List of versions for conditional compilation. |
| 44 |
* Special Enums:: Intrinsic type interoperability with C and C++. |
| 45 |
* Traits:: Compile-time reflection extensions. |
| 46 |
* Vector Extensions:: Using vector types and supported operations. |
| 47 |
* Vector Intrinsics:: Vector instructions through intrinsics. |
| 48 |
* Missing Features:: Deviations from the D2 specification in GDC. |
| 49 |
@end menu |
| 50 |
|
| 51 |
|
| 52 |
@c -------------------------------------------------------- |
| 53 |
|
| 54 |
@node Attributes |
| 55 |
@section Attributes |
| 56 |
@cindex attributes |
| 57 |
|
| 58 |
User-Defined Attributes (UDA) are compile-time expressions introduced by the |
| 59 |
@code{@@} token that can be attached to a declaration. These attributes can |
| 60 |
then be queried, extracted, and manipulated at compile time. |
| 61 |
|
| 62 |
GNU D provides a number of extra special attributes to control specific |
| 63 |
compiler behavior that may help the compiler optimize or check code more |
| 64 |
carefully for correctness. The attributes are defined in the |
| 65 |
@code{gcc.attributes} module. |
| 66 |
|
| 67 |
There is some overlap between the purposes of attributes and pragmas. It has |
| 68 |
been found more convenient to use @code{@@attribute} to achieve a natural |
| 69 |
attachment of attributes to their corresponding declarations, whereas |
| 70 |
@code{pragma} is of use for compatibility with other compilers or constructs |
| 71 |
that do not naturally form part of the grammar. |
| 72 |
|
| 73 |
@menu |
| 74 |
* Attribute Syntax:: |
| 75 |
* Common Attributes:: |
| 76 |
* Other Attributes:: |
| 77 |
* Target Attributes:: |
| 78 |
@end menu |
| 79 |
|
| 80 |
@c -------------------------------------------------------- |
| 81 |
|
| 82 |
@node Attribute Syntax |
| 83 |
@subsection Attribute Syntax |
| 84 |
|
| 85 |
@code{@@(gcc.attributes.attribute)} is the generic entrypoint for applying GCC |
| 86 |
attributes to a function, variable, or type. There is no type checking done, |
| 87 |
as well as no deprecation path for attributes removed from the compiler. So |
| 88 |
the recommendation is to use any of the other UDAs available as described in |
| 89 |
@ref{Common Attributes} unless it is a target-specific attribute |
| 90 |
(@xref{Target Attributes}). |
| 91 |
|
| 92 |
Function attributes introduced by the @code{@@attribute} UDA are used in the |
| 93 |
declaration of a function, followed by an attribute name string and any |
| 94 |
arguments separated by commas enclosed in parentheses. |
| 95 |
|
| 96 |
@smallexample |
| 97 |
import gcc.attributes; |
| 98 |
@@attribute("regparm", 1) int func(int size); |
| 99 |
@end smallexample |
| 100 |
|
| 101 |
@noindent |
| 102 |
Multiple attributes can be applied to a single declaration either with multiple |
| 103 |
@code{@@attribute} attributes, or passing all attributes as a comma-separated |
| 104 |
list enclosed by parentheses. |
| 105 |
|
| 106 |
@smallexample |
| 107 |
// Both func1 and func2 have the same attributes applied. |
| 108 |
@@attribute("noinline") @@attribute("noclone") void func1(); |
| 109 |
@@(attribute("noinline"), attribute("noclone")) void func2(); |
| 110 |
@end smallexample |
| 111 |
|
| 112 |
@noindent |
| 113 |
There are some problems with the semantics of such attributes in D. For |
| 114 |
example, there are no manglings for attributes, although they may affect code |
| 115 |
generation, so problems may arise when attributed types are used in conjunction |
| 116 |
with templates or overloading. Similarly, @code{typeid} does not distinguish |
| 117 |
between types with different attributes. Support for attributes in D are |
| 118 |
restricted to declarations only. |
| 119 |
|
| 120 |
@c -------------------------------------------------------- |
| 121 |
|
| 122 |
@node Common Attributes |
| 123 |
@subsection Common Attributes |
| 124 |
|
| 125 |
The following attributes are supported on most targets. |
| 126 |
|
| 127 |
@table @code |
| 128 |
|
| 129 |
@cindex @code{alloc_size} function attribute |
| 130 |
@cindex @code{alloc_size} variable attribute |
| 131 |
@item @@(gcc.attributes.alloc_size (@var{sizeArgIdx})) |
| 132 |
@itemx @@(gcc.attributes.alloc_size (@var{sizeArgIdx}, @var{numArgIdx})) |
| 133 |
@itemx @@(gcc.attributes.alloc_size (@var{sizeArgIdx}, @var{numArgIdx}, @var{zeroBasedNumbering})) |
| 134 |
|
| 135 |
The @code{@@alloc_size} attribute may be applied to a function - or a function |
| 136 |
pointer variable - that returns a pointer and takes at least one argument of |
| 137 |
an integer or enumerated type. It indicates that the returned pointer points |
| 138 |
to memory whose size is given by the function argument at @code{sizeArgIdx}, or |
| 139 |
by the product of the arguments at @code{sizeArgIdx} and @code{numArgIdx}. |
| 140 |
Meaningful sizes are positive values less than @code{ptrdiff_t.max}. Unless |
| 141 |
@code{zeroBasedNumbering} is true, argument numbering starts at one for |
| 142 |
ordinary functions, and at two for non-static member functions. |
| 143 |
|
| 144 |
If @code{numArgIdx} is less than @code{0}, it is taken to mean there is no |
| 145 |
argument specifying the element count. |
| 146 |
|
| 147 |
@smallexample |
| 148 |
@@alloc_size(1) void* malloc(size_t); |
| 149 |
@@alloc_size(3,2) void* reallocarray(void *, size_t, size_t); |
| 150 |
@@alloc_size(1,2) void* my_calloc(size_t, size_t, bool); |
| 151 |
void malloc_cb(@@alloc_size(1) void* function(size_t) ptr) @{ @} |
| 152 |
@end smallexample |
| 153 |
|
| 154 |
@cindex @code{always_inline} function attribute |
| 155 |
@item @@(gcc.attributes.always_inline) |
| 156 |
|
| 157 |
The @code{@@always_inline} attribute inlines the function independent of any |
| 158 |
restrictions that otherwise apply to inlining. Failure to inline such a |
| 159 |
function is diagnosed as an error. |
| 160 |
|
| 161 |
@smallexample |
| 162 |
@@always_inline int func(); |
| 163 |
@end smallexample |
| 164 |
|
| 165 |
@cindex @code{cold} function attribute |
| 166 |
@item @@(gcc.attributes.cold) |
| 167 |
|
| 168 |
The @code{@@cold} attribute on functions is used to inform the compiler that the |
| 169 |
function is unlikely to be executed. The function is optimized for size |
| 170 |
rather than speed and on many targets it is placed into a special subsection |
| 171 |
of the text section so all cold functions appear close together, improving |
| 172 |
code locality of non-cold parts of program. The paths leading to calls of |
| 173 |
cold functions within code are considered to be cold too. |
| 174 |
|
| 175 |
@smallexample |
| 176 |
@@cold int func(); |
| 177 |
@end smallexample |
| 178 |
|
| 179 |
@cindex @code{flatten} function attribute |
| 180 |
@item @@(gcc.attributes.flatten) |
| 181 |
|
| 182 |
The @code{@@flatten} attribute is used to inform the compiler that every call |
| 183 |
inside this function should be inlined, if possible. Functions declared with |
| 184 |
attribute @code{@@noinline} and similar are not inlined. |
| 185 |
|
| 186 |
@smallexample |
| 187 |
@@flatten int func(); |
| 188 |
@end smallexample |
| 189 |
|
| 190 |
@cindex @code{no_icf} function attribute |
| 191 |
@item @@(gcc.attributes.no_icf) |
| 192 |
|
| 193 |
The @code{@@no_icf} attribute prevents a function from being merged with |
| 194 |
another semantically equivalent function. |
| 195 |
|
| 196 |
@smallexample |
| 197 |
@@no_icf int func(); |
| 198 |
@end smallexample |
| 199 |
|
| 200 |
@cindex @code{no_sanitize} function attribute |
| 201 |
@item @@(gcc.attributes.no_sanitize ("@var{sanitize_option}")) |
| 202 |
|
| 203 |
The @code{@@no_sanitize} attribute on functions is used to inform the compiler |
| 204 |
that it should not do sanitization of any option mentioned in |
| 205 |
@var{sanitize_option}. A list of values acceptable by the @option{-fsanitize} |
| 206 |
option can be provided. |
| 207 |
|
| 208 |
@smallexample |
| 209 |
@@no_sanitize("alignment", "object-size") void func1() @{ @} |
| 210 |
@@no_sanitize("alignment,object-size") void func2() @{ @} |
| 211 |
@end smallexample |
| 212 |
|
| 213 |
@cindex @code{noclone} function attribute |
| 214 |
@item @@(gcc.attributes.noclone) |
| 215 |
|
| 216 |
The @code{@@noclone} attribute prevents a function from being considered for |
| 217 |
cloning - a mechanism that produces specialized copies of functions and which |
| 218 |
is (currently) performed by interprocedural constant propagation. |
| 219 |
|
| 220 |
@smallexample |
| 221 |
@@noclone int func(); |
| 222 |
@end smallexample |
| 223 |
|
| 224 |
@cindex @code{noinline} function attribute |
| 225 |
@item @@(gcc.attributes.noinline) |
| 226 |
|
| 227 |
The @code{@@noinline} attribute prevents a function from being considered for |
| 228 |
inlining. If the function does not have side effects, there are optimizations |
| 229 |
other than inlining that cause function calls to be optimized away, although |
| 230 |
the function call is live. To keep such calls from being optimized away, put |
| 231 |
@code{asm @{ ""; @}} in the called function, to serve as a special side effect. |
| 232 |
|
| 233 |
@smallexample |
| 234 |
@@noinline int func(); |
| 235 |
@end smallexample |
| 236 |
|
| 237 |
@cindex @code{noipa} function attribute |
| 238 |
@item @@(gcc.attributes.noipa) |
| 239 |
|
| 240 |
The @code{@@noipa} attribute disables interprocedural optimizations between the |
| 241 |
function with this attribute and its callers, as if the body of the function is |
| 242 |
not available when optimizing callers and the callers are unavailable when |
| 243 |
optimizing the body. This attribute implies @code{@@noinline}, |
| 244 |
@code{@@noclone}, and @code{@@no_icf} attributes. However, this attribute is |
| 245 |
not equivalent to a combination of other attributes, because its purpose is to |
| 246 |
suppress existing and future optimizations employing interprocedural analysis, |
| 247 |
including those that do not have an attribute suitable for disabling them |
| 248 |
individually. |
| 249 |
|
| 250 |
This attribute is supported mainly for the purpose of testing the compiler. |
| 251 |
|
| 252 |
@smallexample |
| 253 |
@@noipa int func(); |
| 254 |
@end smallexample |
| 255 |
|
| 256 |
@cindex @code{noplt} function attribute |
| 257 |
@item @@(gcc.attributes.noplt) |
| 258 |
|
| 259 |
The @code{@@noplt} attribute is the counterpart to option @option{-fno-plt}. |
| 260 |
Calls to functions marked with this attribute in position-independent code do |
| 261 |
not use the PLT in position-independent code. |
| 262 |
|
| 263 |
In position-dependant code, a few targets also convert call to functions that |
| 264 |
are marked to not use the PLT to use the GOT instead. |
| 265 |
|
| 266 |
@smallexample |
| 267 |
@@noplt int func(); |
| 268 |
@end smallexample |
| 269 |
|
| 270 |
@cindex @code{optimize} function attribute |
| 271 |
@item @@(gcc.attributes.optimize (@var{arguments})) |
| 272 |
|
| 273 |
The @code{@@optimize} attribute is used to specify that a function is to be |
| 274 |
compiled with different optimization options than specified on the command |
| 275 |
line. Valid @var{arguments} are constant non-negative integers and strings. |
| 276 |
Multiple arguments can be provided, separated by commas to specify multiple |
| 277 |
options. Each numeric argument specifies an optimization level. Each string |
| 278 |
argument that begins with the letter @code{O} refers to an optimization option |
| 279 |
such as @option{-O0} or @option{-Os}. Other options are taken as suffixes to |
| 280 |
the @code{-f} prefix jointly forming the name of an optimization option. |
| 281 |
|
| 282 |
Not every optimization option that starts with the @code{-f} prefix |
| 283 |
specified by the attribute necessarily has an effect on the function. |
| 284 |
The @code{@@optimize} attribute should be used for debugging purposes only. |
| 285 |
It is not suitable in production code. |
| 286 |
|
| 287 |
@smallexample |
| 288 |
@@optimize(2) double fn0(double x); |
| 289 |
@@optimize("2") double fn1(double x); |
| 290 |
@@optimize("s") double fn2(double x); |
| 291 |
@@optimize("Ofast") double fn3(double x); |
| 292 |
@@optimize("-O2") double fn4(double x); |
| 293 |
@@optimize("tree-vectorize") double fn5(double x); |
| 294 |
@@optimize("-ftree-vectorize") double fn6(double x); |
| 295 |
@@optimize("no-finite-math-only", 3) double fn7(double x); |
| 296 |
@end smallexample |
| 297 |
|
| 298 |
@cindex @code{register} variable attribute |
| 299 |
@item @@(gcc.attributes.register ("@var{registerName}")) |
| 300 |
|
| 301 |
The @code{@@register} attribute specifies that a local or @code{__gshared} |
| 302 |
variable is to be given a register storage-class in the C99 sense of the term, |
| 303 |
and will be placed into a register named @var{registerName}. |
| 304 |
|
| 305 |
The variable needs to boiled down to a data type that fits the target register. |
| 306 |
It also cannot have either thread-local or @code{extern} storage. It is an |
| 307 |
error to take the address of a register variable. |
| 308 |
|
| 309 |
@smallexample |
| 310 |
@@register("ebx") __gshared int ebx = void; |
| 311 |
void func() @{ @@register("r10") long r10 = 0x2a; @} |
| 312 |
@end smallexample |
| 313 |
|
| 314 |
@cindex @code{restrict} parameter attribute |
| 315 |
@item @@(gcc.attributes.restrict) |
| 316 |
|
| 317 |
The @code{@@restrict} attribute specifies that a function parameter is to be |
| 318 |
restrict-qualified in the C99 sense of the term. The parameter needs to boil |
| 319 |
down to either a pointer or reference type, such as a D pointer, class |
| 320 |
reference, or a @code{ref} parameter. |
| 321 |
|
| 322 |
@smallexample |
| 323 |
void func(@@restrict ref const float[16] array); |
| 324 |
@end smallexample |
| 325 |
|
| 326 |
@cindex @code{section} function attribute |
| 327 |
@cindex @code{section} variable attribute |
| 328 |
@item @@(gcc.attributes.section ("@var{sectionName}")) |
| 329 |
|
| 330 |
The @code{@@section} attribute specifies that a function or variable lives in a |
| 331 |
particular section. For when you need certain particular functions to appear |
| 332 |
in special sections. |
| 333 |
|
| 334 |
Some file formats do not support arbitrary sections so the section attribute is |
| 335 |
not available on all platforms. If you need to map the entire contents of a |
| 336 |
module to a particular section, consider using the facilities of the linker |
| 337 |
instead. |
| 338 |
|
| 339 |
@smallexample |
| 340 |
@@section("bar") extern void func(); |
| 341 |
@@section("stack") ubyte[10000] stack; |
| 342 |
@end smallexample |
| 343 |
|
| 344 |
@cindex @code{simd} function attribute |
| 345 |
@item @@(gcc.attributes.simd) |
| 346 |
|
| 347 |
The @code{@@simd} attribute enables creation of one or more function versions |
| 348 |
that can process multiple arguments using SIMD instructions from a single |
| 349 |
invocation. Specifying this attribute allows compiler to assume that such |
| 350 |
versions are available at link time (provided in the same or another module). |
| 351 |
Generated versions are target-dependent and described in the corresponding |
| 352 |
Vector ABI document. |
| 353 |
|
| 354 |
@smallexample |
| 355 |
@@simd double sqrt(double x); |
| 356 |
@end smallexample |
| 357 |
|
| 358 |
@cindex @code{simd_clones} function attribute |
| 359 |
@item @@(gcc.attributes.simd_clones ("@var{mask}")) |
| 360 |
|
| 361 |
The @code{@@simd_clones} attribute is the same as @code{@@simd}, but also |
| 362 |
includes a @var{mask} argument. Valid masks values are @code{notinbranch} or |
| 363 |
@code{inbranch}, and instructs the compiler to generate non-masked or masked |
| 364 |
clones correspondingly. |
| 365 |
|
| 366 |
@smallexample |
| 367 |
@@simd_clones("notinbranch") double atan2(double y, double x); |
| 368 |
@end smallexample |
| 369 |
|
| 370 |
@cindex @code{symver} function attribute |
| 371 |
@item @@(gcc.attributes.symver ("@var{arguments}")) |
| 372 |
|
| 373 |
The @code{@@symver} attribute creates a symbol version on ELF targets. |
| 374 |
The syntax of the string parameter is @code{"@var{name}@@@var{nodename}"}. |
| 375 |
The @var{name} part of the parameter is the actual name of the symbol by which |
| 376 |
it will be externally referenced. The @var{nodename} portion should be the |
| 377 |
name of a node specified in the version script supplied to the linker when |
| 378 |
building a shared library. Versioned symbol must be defined and must be |
| 379 |
exported with default visibility. |
| 380 |
|
| 381 |
Finally if the parameter is @code{"@var{name}@@@@@var{nodename}"} then in |
| 382 |
addition to creating a symbol version (as if |
| 383 |
@code{"@var{name}@@@var{nodename}"} was used) the version will be also used to |
| 384 |
resolve @var{name} by the linker. |
| 385 |
|
| 386 |
@smallexample |
| 387 |
@@symver("foo@@VERS_1") int foo_v1(); |
| 388 |
@end smallexample |
| 389 |
|
| 390 |
@cindex @code{target} function attribute |
| 391 |
@item @@(gcc.attributes.target ("@var{options}")) |
| 392 |
|
| 393 |
The @code{@@target} attribute is used to specify that a function is to be |
| 394 |
compiled with different target options than specified on the command line. One |
| 395 |
or more strings can be provided as arguments, separated by commas to specify |
| 396 |
multiple options. Each string consists of one or more comma-separated suffixes |
| 397 |
to the @option{-m} prefix jointly forming the name of a machine-dependent |
| 398 |
option. |
| 399 |
|
| 400 |
The target attribute can be used for instance to have a function compiled with |
| 401 |
a different ISA (instruction set architecture) than the default. |
| 402 |
|
| 403 |
The options supported are specific to each target. |
| 404 |
|
| 405 |
@smallexample |
| 406 |
@@target("arch=core2") void core2_func(); |
| 407 |
@@target("sse3") void sse3_func(); |
| 408 |
@end smallexample |
| 409 |
|
| 410 |
@cindex @code{target_clones} function attribute |
| 411 |
@item @@(gcc.attributes.target_clones ("@var{options}")) |
| 412 |
|
| 413 |
The @code{@@target_clones} attribute is used to specify that a function be |
| 414 |
cloned into multiple versions compiled with different target @var{options} than |
| 415 |
specified on the command line. The supported options and restrictions are the |
| 416 |
same as for @code{@@target} attribute. |
| 417 |
|
| 418 |
It also creates a resolver function that dynamically selects a clone suitable |
| 419 |
for current architecture. The resolver is created only if there is a usage of |
| 420 |
a function with @code{@@target_clones} attribute. |
| 421 |
|
| 422 |
@smallexample |
| 423 |
@@target_clones("sse4.1,avx,default") double func(double x); |
| 424 |
@end smallexample |
| 425 |
|
| 426 |
@cindex @code{used} function attribute |
| 427 |
@cindex @code{used} variable attribute |
| 428 |
@item @@(gcc.attributes.used) |
| 429 |
|
| 430 |
The @code{@@used} attribute, annotated to a function or variable, means that |
| 431 |
code must be emitted for the function even if it appears that the function is |
| 432 |
not referenced. This is useful, for example, when the function is referenced |
| 433 |
only in inline assembly. |
| 434 |
|
| 435 |
@smallexample |
| 436 |
@@used __gshared int var = 0x1000; |
| 437 |
@end smallexample |
| 438 |
|
| 439 |
@cindex @code{visibility} function attribute |
| 440 |
@cindex @code{visibility} variable attribute |
| 441 |
@item @@(gcc.attributes.visibility ("@var{visibilityName}")) |
| 442 |
|
| 443 |
The @code{@@visibility} attribute affects the linkage of the declaration to |
| 444 |
which it is attached. It can be applied to variables, types, and functions. |
| 445 |
|
| 446 |
There are four supported visibility_type values: @code{default}, @code{hidden}, |
| 447 |
@code{protected}, or @code{internal} visibility. |
| 448 |
|
| 449 |
@smallexample |
| 450 |
@@visibility("protected") void func() @{ @} |
| 451 |
@end smallexample |
| 452 |
|
| 453 |
@cindex @code{weak} function attribute |
| 454 |
@cindex @code{weak} variable attribute |
| 455 |
@item @@(gcc.attributes.weak) |
| 456 |
|
| 457 |
The @code{@@weak} attribute causes a declaration of an external symbol to be |
| 458 |
emitted as a weak symbol rather than a global. This is primarily useful in |
| 459 |
defining library functions that can be overridden in user code, though it can |
| 460 |
also be used with non-function declarations. The overriding symbol must have |
| 461 |
the same type as the weak symbol. In addition, if it designates a variable it |
| 462 |
must also have the same size and alignment as the weak symbol. |
| 463 |
|
| 464 |
Weak symbols are supported for ELF targets, and also for a.out targets when |
| 465 |
using the GNU assembler and linker. |
| 466 |
|
| 467 |
@smallexample |
| 468 |
@@weak int func() @{ return 1; @} |
| 469 |
@end smallexample |
| 470 |
|
| 471 |
@end table |
| 472 |
|
| 473 |
@c -------------------------------------------------------- |
| 474 |
|
| 475 |
@node Other Attributes |
| 476 |
@subsection Other Attributes |
| 477 |
|
| 478 |
The following attributes are defined for compatibility with other compilers. |
| 479 |
|
| 480 |
@table @code |
| 481 |
|
| 482 |
@cindex @code{allocSize} function attribute |
| 483 |
@item @@(gcc.attributes.allocSize (@var{sizeArgIdx})) |
| 484 |
@itemx @@(gcc.attributes.allocSize (@var{sizeArgIdx}, @var{numArgIdx})) |
| 485 |
@item @@(gcc.attributes.allocSize (@var{sizeArgIdx})) |
| 486 |
|
| 487 |
These attributes are a synonym for |
| 488 |
@code{@@alloc_size(@var{sizeArgIdx}, @var{numArgIdx}, true)}. |
| 489 |
Unlike @code{@@alloc_size}, it uses 0-based index of the function arguments. |
| 490 |
|
| 491 |
@cindex @code{assumeUsed} function attribute |
| 492 |
@cindex @code{assumeUsed} variable attribute |
| 493 |
@item @@(gcc.attributes.assumeUsed) |
| 494 |
|
| 495 |
This attribute is a synonym for @code{@@used}. |
| 496 |
|
| 497 |
@cindex @code{dynamicCompile} function attribute |
| 498 |
@item @@(gcc.attributes.dynamicCompile) |
| 499 |
@itemx @@(gcc.attributes.dynamicCompileConst) |
| 500 |
@itemx @@(gcc.attributes.dynamicCompileEmit) |
| 501 |
|
| 502 |
These attributes are accepted, but have no effect. |
| 503 |
|
| 504 |
@cindex @code{fastmath} function attribute |
| 505 |
@item @@(gcc.attributes.fastmath) |
| 506 |
|
| 507 |
This attribute is a synonym for @code{@@optimize("Ofast")}. Explicitly sets |
| 508 |
"fast-math" for a function, enabling aggressive math optimizations. |
| 509 |
|
| 510 |
@cindex @code{hidden} function attribute |
| 511 |
@cindex @code{hidden} variable attribute |
| 512 |
@item @@(gcc.attributes.hidden) |
| 513 |
|
| 514 |
This attribute is a synonym for @code{@@visibility("hidden")}. Sets the |
| 515 |
visibility of a function or global variable to "hidden". |
| 516 |
|
| 517 |
@cindex @code{naked} function attribute |
| 518 |
@item @@(gcc.attributes.naked) |
| 519 |
|
| 520 |
This attribute is a synonym for @code{@@attribute("naked")}. Adds GCC's |
| 521 |
"naked" attribute to a function, disabling function prologue / epilogue |
| 522 |
emission. Intended to be used in combination with basic @code{asm} statements. |
| 523 |
While using extended @code{asm} or a mixture of basic @code{asm} and D code may |
| 524 |
appear to work, they cannot be depended upon to work reliably and are not |
| 525 |
supported. |
| 526 |
|
| 527 |
@cindex @code{noSanitize} function attribute |
| 528 |
@item @@(gcc.attributes.noSanitize ("@var{sanitize_option}")) |
| 529 |
|
| 530 |
This attribute is a synonym for @code{@@no_sanitize("sanitize_option")}. |
| 531 |
|
| 532 |
|
| 533 |
@cindex @code{optStrategy} function attribute |
| 534 |
@item @@(gcc.attributes.optStrategy ("@var{strategy}")) |
| 535 |
|
| 536 |
This attribute is a synonym for @code{@@optimize("O0")} and |
| 537 |
@code{@@optimize("Os")}. Sets the optimization strategy for a function. Valid |
| 538 |
strategies are "none", "optsize", "minsize". The strategies are mutually |
| 539 |
exclusive. |
| 540 |
|
| 541 |
@item @@(gcc.attributes.polly) |
| 542 |
|
| 543 |
This attribute is a synonym for |
| 544 |
@code{@@optimize("loop-parallelize-all", "loop-nest-optimize")}. |
| 545 |
Only effective when GDC was built with ISL included. |
| 546 |
|
| 547 |
@end table |
| 548 |
|
| 549 |
@c -------------------------------------------------------- |
| 550 |
|
| 551 |
@node Target Attributes |
| 552 |
@subsection Target-specific Attributes |
| 553 |
|
| 554 |
Many targets have their own target-specific attributes. These are also exposed |
| 555 |
via the @code{gcc.attributes} module with use of the generic |
| 556 |
@code{@@(gcc.attributes.attribute)} UDA function. |
| 557 |
|
| 558 |
@xref{Attribute Syntax}, for details of the exact syntax for using attributes. |
| 559 |
|
| 560 |
See the function and variable attribute documentation in the GCC manual for |
| 561 |
more information about what attributes are available on each target. |
| 562 |
|
| 563 |
Examples of using x86-specific target attributes are shown as follows: |
| 564 |
|
| 565 |
@smallexample |
| 566 |
import gcc.attributes; |
| 567 |
|
| 568 |
@@attribute("cdecl") |
| 569 |
@@attribute("fastcall") |
| 570 |
@@attribute("ms_abi") |
| 571 |
@@attribute("sysv_abi") |
| 572 |
@@attribute("callee_pop_aggregate_return", 1) |
| 573 |
@@attribute("ms_hook_prologue") |
| 574 |
@@attribute("naked") |
| 575 |
@@attribute("regparm", 2) |
| 576 |
@@attribute("sseregparm") |
| 577 |
@@attribute("force_align_arg_pointer") |
| 578 |
@@attribute("stdcall") |
| 579 |
@@attribute("no_caller_saved_registers") |
| 580 |
@@attribute("interrupt") |
| 581 |
@@attribute("indirect_branch", "thunk") |
| 582 |
@@attribute("function_return", "keep")) |
| 583 |
@@attribute("nocf_check") |
| 584 |
@@attribute("cf_check") |
| 585 |
@@attribute("indirect_return") |
| 586 |
@@attribute("fentry_name", "nop") |
| 587 |
@@attribute("fentry_section", "__entry_loc") |
| 588 |
@@attribute("nodirect_extern_access") |
| 589 |
|
| 590 |
@end smallexample |
| 591 |
|
| 592 |
|
| 593 |
@c -------------------------------------------------------- |
| 594 |
|
| 595 |
@node Builtin Functions |
| 596 |
@section Built-in Functions |
| 597 |
@cindex built-in functions |
| 598 |
|
| 599 |
GCC provides a large number of built-in functions that are made available in |
| 600 |
GNU D by importing the @code{gcc.builtins} module. Declarations in this module |
| 601 |
are automatically created by the compiler. All declarations start with |
| 602 |
@code{__builtin_}. Refer to the built-in function documentation in the GCC |
| 603 |
manual for a full list of functions that are available. |
| 604 |
|
| 605 |
@menu |
| 606 |
* Builtin Types:: |
| 607 |
* Query Builtins:: |
| 608 |
* Other Builtins:: |
| 609 |
@end menu |
| 610 |
|
| 611 |
@c -------------------------------------------------------- |
| 612 |
|
| 613 |
@node Builtin Types |
| 614 |
@subsection Built-in Types |
| 615 |
@cindex built-in types |
| 616 |
|
| 617 |
In addition to built-in functions, the following types are defined in the |
| 618 |
@code{gcc.builtins} module. |
| 619 |
|
| 620 |
@table @code |
| 621 |
@item ___builtin_clong |
| 622 |
The D equivalent of the target's C @code{long} type. |
| 623 |
|
| 624 |
@item ___builtin_clonglong |
| 625 |
The D equivalent of the target's C @code{long long} type. |
| 626 |
|
| 627 |
@item ___builtin_culong |
| 628 |
The D equivalent of the target's C @code{unsigned long} type. |
| 629 |
|
| 630 |
@item ___builtin_culonglong |
| 631 |
The D equivalent of the target's C @code{unsigned long long} type. |
| 632 |
|
| 633 |
@item ___builtin_machine_byte |
| 634 |
Signed unit-sized integer type. |
| 635 |
|
| 636 |
@item ___builtin_machine_int |
| 637 |
Signed word-sized integer type. |
| 638 |
|
| 639 |
@item ___builtin_machine_ubyte |
| 640 |
Unsigned unit-sized integer type. |
| 641 |
|
| 642 |
@item ___builtin_machine_uint |
| 643 |
Unsigned word-sized integer type. |
| 644 |
|
| 645 |
@item ___builtin_pointer_int |
| 646 |
Signed pointer-sized integer type. |
| 647 |
|
| 648 |
@item ___builtin_pointer_uint |
| 649 |
Unsigned pointer-sized integer type. |
| 650 |
|
| 651 |
@item ___builtin_unwind_int |
| 652 |
The D equivalent of the target's C @code{_Unwind_Sword} type. |
| 653 |
|
| 654 |
@item ___builtin_unwind_uint |
| 655 |
The D equivalent of the target's C @code{_Unwind_Word} type. |
| 656 |
|
| 657 |
@item ___builtin_va_list |
| 658 |
The target's @code{va_list} type. |
| 659 |
@end table |
| 660 |
|
| 661 |
@c -------------------------------------------------------- |
| 662 |
|
| 663 |
@node Query Builtins |
| 664 |
@subsection Querying Available Built-ins |
| 665 |
@cindex built-in functions |
| 666 |
|
| 667 |
Not all of the functions are supported, and some target-specific functions may |
| 668 |
only be available when compiling for a particular ISA. One way of finding out |
| 669 |
what is exposed by the built-ins module is by generating a D interface file. |
| 670 |
Assuming you have no file @file{builtins.d}, the command |
| 671 |
@smallexample |
| 672 |
echo "module gcc.builtins;" > builtins.d; gdc -H -fsyntax-only builtins.d |
| 673 |
@end smallexample |
| 674 |
@noindent |
| 675 |
will save all built-in declarations to the file @file{builtins.di}. |
| 676 |
|
| 677 |
Another way to determine whether a specific built-in is available is by using |
| 678 |
compile-time reflection. |
| 679 |
@smallexample |
| 680 |
enum X86_HAVE_SSE3 = __traits(compiles, __builtin_ia32_haddps); |
| 681 |
enum X86_HAVE_SSSE3 = __traits(compiles, __builtin_ia32_pmulhrsw128); |
| 682 |
enum X86_HAVE_SSE41 = __traits(compiles, __builtin_ia32_dpps); |
| 683 |
enum X86_HAVE_SSE42 = __traits(compiles, __builtin_ia32_pcmpgtq); |
| 684 |
enum X86_HAVE_AVX = __traits(compiles, __builtin_ia32_vbroadcastf128_pd256); |
| 685 |
enum X86_HAVE_AVX2 = __traits(compiles, __builtin_ia32_gathersiv2df); |
| 686 |
enum X86_HAVE_BMI2 = __traits(compiles, __builtin_ia32_pext_si); |
| 687 |
@end smallexample |
| 688 |
|
| 689 |
@c -------------------------------------------------------- |
| 690 |
|
| 691 |
@node Other Builtins |
| 692 |
@subsection Other Built-in Functions |
| 693 |
@cindex built-in functions |
| 694 |
@opindex fno-builtin |
| 695 |
|
| 696 |
As well as built-ins being available from the @code{gcc.builtins} module, GNU D |
| 697 |
will also recognize when an @code{extern(C)} library function is a GCC |
| 698 |
built-in. Many of these functions are only optimized in certain cases; if they |
| 699 |
are not optimized in a particular case, a call to the library function is |
| 700 |
emitted. This optimization can be disabled with the @option{-fno-builtin} |
| 701 |
option (@pxref{Runtime Options}). |
| 702 |
|
| 703 |
In the @code{core.stdc.complex} module, the functions |
| 704 |
@code{cabs}, @code{cabsf}, @code{cabsl}, @code{cacos}, @code{cacosf}, |
| 705 |
@code{cacosh}, @code{cacoshf}, @code{cacoshl}, @code{cacosl}, @code{carg}, |
| 706 |
@code{cargf}, @code{cargl}, @code{casin}, @code{casinf}, @code{casinh}, |
| 707 |
@code{casinhf}, @code{casinhl}, @code{casinl}, @code{catan}, @code{catanf}, |
| 708 |
@code{catanh}, @code{catanhf}, @code{catanhl}, @code{catanl}, @code{ccos}, |
| 709 |
@code{ccosf}, @code{ccosh}, @code{ccoshf}, @code{ccoshl}, @code{ccosl}, |
| 710 |
@code{cexp}, @code{cexpf}, @code{cexpl}, @code{clog}, @code{clogf}, |
| 711 |
@code{clogl}, @code{conj}, @code{conjf}, @code{conjl}, @code{cpow}, |
| 712 |
@code{cpowf}, @code{cpowl}, @code{cproj}, @code{cprojf}, @code{cprojl}, |
| 713 |
@code{csin}, @code{csinf}, @code{csinh}, @code{csinhf}, @code{csinhl}, |
| 714 |
@code{csinl}, @code{csqrt}, @code{csqrtf}, @code{csqrtl}, @code{ctan}, |
| 715 |
@code{ctanf}, @code{ctanh}, @code{ctanhf}, @code{ctanhl}, @code{ctanl} |
| 716 |
may be handled as built-in functions. All these functions have corresponding |
| 717 |
versions prefixed with @code{__builtin_} in the @code{gcc.builtins} module. |
| 718 |
|
| 719 |
In the @code{core.stdc.ctype} module, the functions |
| 720 |
@code{isalnum}, @code{isalpha}, @code{isblank}, @code{iscntrl}, @code{isdigit}, |
| 721 |
@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, @code{isspace}, |
| 722 |
@code{isupper}, @code{isxdigit}, @code{tolower}, @code{toupper} |
| 723 |
may be handled as built-in functions. All these functions have corresponding |
| 724 |
versions prefixed with @code{__builtin_} in the @code{gcc.builtins} module. |
| 725 |
|
| 726 |
In the @code{core.stdc.fenv} module, the functions |
| 727 |
@code{feclearexcept}, @code{fegetenv}, @code{fegetexceptflag}, |
| 728 |
@code{fegetround}, @code{feholdexcept}, @code{feraiseexcept}, @code{fesetenv}, |
| 729 |
@code{fesetexceptflag}, @code{fesetround}, @code{fetestexcept}, |
| 730 |
@code{feupdateenv} |
| 731 |
may be handled as built-in functions. All these functions have corresponding |
| 732 |
versions prefixed with @code{__builtin_} in the @code{gcc.builtins} module. |
| 733 |
|
| 734 |
In the @code{core.stdc.inttypes} module, the function @code{imaxabs} may be |
| 735 |
handled as a built-in function. All these functions have corresponding |
| 736 |
versions prefixed with @code{__builtin_} in the @code{gcc.builtins} module. |
| 737 |
|
| 738 |
In the @code{core.stdc.math} module, the functions |
| 739 |
@code{acos}, @code{acosf}, @code{acosh}, @code{acoshf}, @code{acoshl}, |
| 740 |
@code{acosl}, @code{asin}, @code{asinf}, @code{asinh}, @code{asinhf}, |
| 741 |
@code{asinhl}, @code{asinl}, @code{atan}, @code{atan2}, @code{atan2f}, |
| 742 |
@code{atan2l}, @code{atanf}, @code{atanh}, @code{atanhf}, @code{atanhl}, |
| 743 |
@code{atanl}, @code{cbrt}, @code{cbrtf}, @code{cbrtl}, @code{ceil}, |
| 744 |
@code{ceilf}, @code{ceill}, @code{copysign}, @code{copysignf}, |
| 745 |
@code{copysignl}, @code{cos}, @code{cosf}, @code{cosh}, @code{coshf}, |
| 746 |
@code{coshl}, @code{cosl}, @code{erf}, @code{erfc}, @code{erfcf}, @code{erfcl}, |
| 747 |
@code{erff}, @code{erfl}, @code{exp}, @code{exp2}, @code{exp2f}, @code{exp2l}, |
| 748 |
@code{expf}, @code{expl}, @code{expm1}, @code{expm1f}, @code{expm1l}, |
| 749 |
@code{fabs}, @code{fabsf}, @code{fabsl}, @code{fdim}, @code{fdimf}, |
| 750 |
@code{fdiml}, @code{floor}, @code{floorf}, @code{floorl}, @code{fma}, |
| 751 |
@code{fmaf}, @code{fmal}, @code{fmax}, @code{fmaxf}, @code{fmaxl}, @code{fmin}, |
| 752 |
@code{fminf}, @code{fminl}, @code{fmod}, @code{fmodf}, @code{fmodl}, |
| 753 |
@code{frexp}, @code{frexpf}, @code{frexpl}, @code{hypot}, @code{hypotf}, |
| 754 |
@code{hypotl}, @code{ilogb}, @code{ilogbf}, @code{ilogbl}, @code{isinf}, |
| 755 |
@code{isnan}, @code{ldexp}, @code{ldexpf}, @code{ldexpl}, @code{lgamma}, |
| 756 |
@code{lgammaf}, @code{lgammal}, @code{llrint}, @code{llrintf}, @code{llrintl}, |
| 757 |
@code{llround}, @code{llroundf}, @code{llroundl}, @code{log}, @code{log10}, |
| 758 |
@code{log10f}, @code{log10l}, @code{log1p}, @code{log1pf}, @code{log1pl}, |
| 759 |
@code{log2}, @code{log2f}, @code{log2l}, @code{logb}, @code{logbf}, |
| 760 |
@code{logbl}, @code{logf}, @code{logl}, @code{lrint}, @code{lrintf}, |
| 761 |
@code{lrintl}, @code{lround}, @code{lroundf}, @code{lroundl}, @code{modf}, |
| 762 |
@code{modff}, @code{modfl}, @code{nan}, @code{nanf}, @code{nanl}, |
| 763 |
@code{nearbyint}, @code{nearbyintf}, @code{nearbyintl}, @code{nextafter}, |
| 764 |
@code{nextafterf}, @code{nextafterl}, @code{nexttoward}, @code{nexttowardf}, |
| 765 |
@code{nexttowardl}, @code{pow}, @code{powf}, @code{powl}, @code{remainder}, |
| 766 |
@code{remainderf}, @code{remainderl}, @code{remquo}, @code{remquof}, |
| 767 |
@code{remquol}, @code{rint}, @code{rintf}, @code{rintl}, @code{round}, |
| 768 |
@code{roundf}, @code{roundl}, @code{scalbln}, @code{scalblnf}, @code{scalblnl}, |
| 769 |
@code{scalbn}, @code{scalbnf}, @code{scalbnl}, @code{signbit}, @code{sin}, |
| 770 |
@code{sinf}, @code{sinh}, @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrt}, |
| 771 |
@code{sqrtf}, @code{sqrtl}, @code{tan}, @code{tanf}, @code{tanh}, @code{tanhf}, |
| 772 |
@code{tanhl}, @code{tanl}, @code{tgamma}, @code{tgammaf}, @code{tgammal}, |
| 773 |
@code{trunc}, @code{truncf}, @code{truncl} |
| 774 |
may be handled as built-in functions. All these functions have corresponding |
| 775 |
versions prefixed with @code{__builtin_} in the @code{gcc.builtins} module. |
| 776 |
|
| 777 |
In the @code{core.stdc.stdio} module, the functions |
| 778 |
@code{fprintf}, @code{fputc}, @code{fputc_unlocked}, @code{fputs}, |
| 779 |
@code{fwrite}, @code{printf}, @code{puts}, @code{snprintf}, @code{sprintf}, |
| 780 |
@code{vfprintf}, @code{vprintf}, @code{vsnprintf}, @code{vsprintf} |
| 781 |
may be handled as built-in functions. All these functions have corresponding |
| 782 |
versions prefixed with @code{__builtin_} in the @code{gcc.builtins} module. |
| 783 |
|
| 784 |
In the @code{core.stdc.stdlib} module, the functions |
| 785 |
@code{abort}, @code{abs}, @code{aligned_alloc}, @code{alloca}, @code{calloc}, |
| 786 |
@code{exit}, @code{_Exit}, @code{free}, @code{labs}, @code{llabs}, |
| 787 |
@code{malloc}, @code{realloc} |
| 788 |
may be handled as built-in functions. All these functions have corresponding |
| 789 |
versions prefixed with @code{__builtin_} in the @code{gcc.builtins} module. |
| 790 |
|
| 791 |
In the @code{core.stdc.string} module, the functions |
| 792 |
@code{memchr}, @code{memcmp}, @code{memcpy}, @code{memmove}, @code{memset}, |
| 793 |
@code{strcat}, @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, |
| 794 |
@code{strdup}, @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, |
| 795 |
@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr} |
| 796 |
may be handled as built-in functions. All these functions have corresponding |
| 797 |
versions prefixed with @code{__builtin_} in the @code{gcc.builtins} module. |
| 798 |
|
| 799 |
In the @code{core.stdc.time} module, the function @code{strftime} may be |
| 800 |
handled as a built-in function. All these functions have corresponding |
| 801 |
versions prefixed with @code{__builtin_} in the @code{gcc.builtins} module. |
| 802 |
|
| 803 |
In the @code{core.stdc.wctype} module, the functions |
| 804 |
@code{iswalnum}, @code{iswalpha}, @code{iswblank}, @code{iswcntrl}, |
| 805 |
@code{iswdigit}, @code{iswgraph}, @code{iswlower}, @code{iswprint}, |
| 806 |
@code{iswpunct}, @code{iswspace}, @code{iswupper}, @code{iswxdigit}, |
| 807 |
@code{towlower}, @code{towupper} |
| 808 |
may be handled as built-in functions. All these functions have corresponding |
| 809 |
versions prefixed with @code{__builtin_} in the @code{gcc.builtins} module. |
| 810 |
|
| 811 |
Within the @code{core.sys} package for POSIX and platform definitions, the |
| 812 |
functions |
| 813 |
@code{putchar_unlocked}, @code{putc_unlocked}, @code{posix_memalign}, |
| 814 |
@code{ffs}, @code{strcasecmp}, @code{strncasecmp}, @code{stpcpy}, |
| 815 |
@code{stpncpy}, @code{strndup}, @code{strnlen}, @code{execl}, @code{execle}, |
| 816 |
@code{execlp}, @code{execv}, @code{execve}, @code{execvp}, @code{_exit}, |
| 817 |
@code{fork} |
| 818 |
may be handled as built-in functions. All these functions have corresponding |
| 819 |
versions prefixed with @code{__builtin_} in the @code{gcc.builtins} module. |
| 820 |
|
| 821 |
|
| 822 |
@c -------------------------------------------------------- |
| 823 |
|
| 824 |
@node ImportC |
| 825 |
@section Importing C Sources into D |
| 826 |
@cindex importC |
| 827 |
|
| 828 |
ImportC is a C preprocessor and parser embedded into the GNU D implementation. |
| 829 |
It enables direct importation of C files, without needing to manually prepare a |
| 830 |
D file corresponding to the declarations in the C file. |
| 831 |
|
| 832 |
ImportC is an implementation of ISO/IEC 9899:2011, which will be referred to as |
| 833 |
C11. Prior versions, such as C99, C89, and K+R C, are not supported. |
| 834 |
|
| 835 |
Assuming you have no file @file{cstdio.c} or @file{main.d}, the commands |
| 836 |
@smallexample |
| 837 |
cat > cstdio.c << @@EOC |
| 838 |
int printf(const char*, ...); |
| 839 |
@@EOC |
| 840 |
cat > main.d << @@EOD |
| 841 |
import cstdio; |
| 842 |
void main() @{ printf("Hello ImportC\n"); @} |
| 843 |
@@EOD |
| 844 |
gdc main.d -o main; ./main |
| 845 |
@end smallexample |
| 846 |
will generate a program which will print @samp{Hello ImportC}. |
| 847 |
|
| 848 |
ImportC does not have a preprocessor. It is designed to compile C files after |
| 849 |
they have been first run through the C preprocessor. If the C file has a |
| 850 |
@samp{.i} extension, the file is presumed to be already preprocessed. |
| 851 |
Preprocessing can be run manually: |
| 852 |
@smallexample |
| 853 |
gcc -E file.c > file.i |
| 854 |
@end smallexample |
| 855 |
|
| 856 |
@noindent |
| 857 |
ImportC collects all the @code{#define} macros from the preprocessor run when |
| 858 |
it is run automatically. The macros that look like manifest constants, such as: |
| 859 |
@smallexample |
| 860 |
#define COLOR 0x123456 |
| 861 |
@end smallexample |
| 862 |
are interpreted as D manifest constant declarations of the form: |
| 863 |
@smallexample |
| 864 |
enum COLOR = 0x123456; |
| 865 |
@end smallexample |
| 866 |
|
| 867 |
@noindent |
| 868 |
The variety of macros that can be interpreted as D declarations may be |
| 869 |
expanded, but will never encompass all the metaprogramming uses of C macros. |
| 870 |
|
| 871 |
GNU D does not directly compile C files into modules that can be linked in with |
| 872 |
D code to form an executable. When given a source file with the suffix |
| 873 |
@samp{.c}, the compiler driver program @command{gdc} instead runs the |
| 874 |
subprogram @command{cc1}. |
| 875 |
|
| 876 |
@smallexample |
| 877 |
gdc file1.d file2.c // d21 file1.d -o file1.s |
| 878 |
// cc1 file2.c -o file2.s |
| 879 |
// as file1.s -o file1.o |
| 880 |
// as file2.s -o file2.o |
| 881 |
// ld file1.o file2.o |
| 882 |
@end smallexample |
| 883 |
|
| 884 |
|
| 885 |
@c -------------------------------------------------------- |
| 886 |
|
| 887 |
@node Inline Assembly |
| 888 |
@section Inline Assembly |
| 889 |
@cindex assembly language in D |
| 890 |
|
| 891 |
The @code{asm} keyword allows you to embed assembler instructions within D |
| 892 |
code. GNU D provides two forms of inline @code{asm} statements. A @dfn{basic |
| 893 |
@code{asm}} statement is one with no operands, while an @dfn{extended |
| 894 |
@code{asm}} statement includes one or more operands. |
| 895 |
|
| 896 |
@example |
| 897 |
asm @var{FunctionAttributes} @{ |
| 898 |
@var{AssemblerInstruction} ; |
| 899 |
@} |
| 900 |
|
| 901 |
asm @var{FunctionAttributes} @{ |
| 902 |
@var{AssemblerTemplate} |
| 903 |
: @var{OutputOperands} |
| 904 |
@r{[} : @var{InputOperands} |
| 905 |
@r{[} : @var{Clobbers} |
| 906 |
@r{[} : @var{GotoLabels} @r{]} @r{]} @r{]} ; |
| 907 |
@} |
| 908 |
@end example |
| 909 |
|
| 910 |
@noindent |
| 911 |
The extended form is preferred for mixing D and assembly language within a |
| 912 |
function, but to include assembly language in a function declared with the |
| 913 |
@code{naked} attribute you must use basic @code{asm}. |
| 914 |
|
| 915 |
@smallexample |
| 916 |
uint incr (uint value) |
| 917 |
@{ |
| 918 |
uint result; |
| 919 |
asm @{ "incl %0" |
| 920 |
: "=a" (result) |
| 921 |
: "a" (value); |
| 922 |
@} |
| 923 |
return result; |
| 924 |
@} |
| 925 |
@end smallexample |
| 926 |
|
| 927 |
@noindent |
| 928 |
Multiple assembler instructions can appear within an @code{asm} block, or the |
| 929 |
instruction template can be a multi-line or concatenated string. In both |
| 930 |
cases, GCC's optimizers won't discard or move any instruction within the |
| 931 |
statement block. |
| 932 |
@smallexample |
| 933 |
bool hasCPUID() |
| 934 |
@{ |
| 935 |
uint flags = void; |
| 936 |
asm nothrow @@nogc @{ |
| 937 |
"pushfl"; |
| 938 |
"pushfl"; |
| 939 |
"xorl %0, (%%esp)" :: "i" (0x00200000); |
| 940 |
"popfl"; |
| 941 |
"pushfl"; |
| 942 |
"popl %0" : "=a" (flags); |
| 943 |
"xorl (%%esp), %0" : "=a" (flags); |
| 944 |
"popfl"; |
| 945 |
@} |
| 946 |
return (flags & 0x0020_0000) != 0; |
| 947 |
@} |
| 948 |
@end smallexample |
| 949 |
|
| 950 |
@noindent |
| 951 |
The instruction templates for both basic and extended @code{asm} can be any |
| 952 |
expression that can be evaluated at compile-time to a string, not just string |
| 953 |
literals. |
| 954 |
|
| 955 |
@smallexample |
| 956 |
uint invert(uint v) |
| 957 |
@{ |
| 958 |
uint result; |
| 959 |
asm @@safe @@nogc nothrow pure @{ |
| 960 |
genAsmInsn(`invert`) |
| 961 |
: [res] `=r` (result) |
| 962 |
: [arg1] `r` (v); |
| 963 |
@} |
| 964 |
return result; |
| 965 |
|
| 966 |
@} |
| 967 |
@end smallexample |
| 968 |
|
| 969 |
@noindent |
| 970 |
The total number of input + output + goto operands is limited to 30. |
| 971 |
|
| 972 |
|
| 973 |
@c -------------------------------------------------------- |
| 974 |
|
| 975 |
@node Intrinsics |
| 976 |
@section Intrinsics |
| 977 |
@cindex intrinsics |
| 978 |
|
| 979 |
The D language specification itself does not define any intrinsics that a |
| 980 |
compatible compiler must implement. Rather, within the D core library there |
| 981 |
are a number of modules that define primitives with generic implementations. |
| 982 |
While the generic versions of these functions are computationally expensive |
| 983 |
relative to the cost of the operation itself, compiler implementations are free |
| 984 |
to recognize them and generate equivalent and faster code. |
| 985 |
|
| 986 |
The following are the kinds of intrinsics recognized by GNU D. |
| 987 |
|
| 988 |
@menu |
| 989 |
* Bit Operation Intrinsics:: |
| 990 |
* Integer Overflow Intrinsics:: |
| 991 |
* Math Intrinsics:: |
| 992 |
* Variadic Intrinsics:: |
| 993 |
* Volatile Intrinsics:: |
| 994 |
* CTFE Intrinsics:: |
| 995 |
@end menu |
| 996 |
|
| 997 |
@c -------------------------------------------------------- |
| 998 |
|
| 999 |
@node Bit Operation Intrinsics |
| 1000 |
@subsection Bit Operation Intrinsics |
| 1001 |
@cindex intrinsics, bitop |
| 1002 |
|
| 1003 |
The following functions are a collection of intrinsics that do bit-level |
| 1004 |
operations, available by importing the @code{core.bitop} module. |
| 1005 |
|
| 1006 |
Although most are named after x86 hardware instructions, it is not guaranteed |
| 1007 |
that they will result in generating equivalent assembly on x86. If the |
| 1008 |
compiler determines there is a better way to get the same result in hardware, |
| 1009 |
then that will be used instead. |
| 1010 |
|
| 1011 |
@deftypefn {Function} {int} core.bitop.bsf (uint @var{v}) |
| 1012 |
@deftypefnx {Function} {int} core.bitop.bsf (ulong @var{v}) |
| 1013 |
|
| 1014 |
Scans the bits in @var{v} starting with bit @code{0}, looking for the first set |
| 1015 |
bit. Returns the bit number of the first bit set. The return value is |
| 1016 |
undefined if @var{v} is zero. |
| 1017 |
|
| 1018 |
This intrinsic is the same as the GCC built-in function @code{__builtin_ctz}. |
| 1019 |
@end deftypefn |
| 1020 |
|
| 1021 |
@deftypefn {Function} {int} core.bitop.bsr (uint @var{v}) |
| 1022 |
@deftypefnx {Function} {int} core.bitop.bsr (ulong @var{v}) |
| 1023 |
|
| 1024 |
Scans the bits in @var{v} from the most significant bit to the least |
| 1025 |
significant bit, looking for the first set bit. Returns the bit number of the |
| 1026 |
first bit set. The return value is undefined if @var{v} is zero. |
| 1027 |
|
| 1028 |
This intrinsic is equivalent to writing the following: |
| 1029 |
@smallexample |
| 1030 |
result = __builtin_clz(v) ^ (v.sizeof * 8 - 1) |
| 1031 |
@end smallexample |
| 1032 |
@end deftypefn |
| 1033 |
|
| 1034 |
@deftypefn {Function} {int} core.bitop.bt (scope const(uint*) @var{p}, uint @var{bitnum}) |
| 1035 |
@deftypefnx {Function} {int} core.bitop.bt (scope const(uint*) @var{p}, uint @var{bitnum}) |
| 1036 |
|
| 1037 |
Tests the bit @var{bitnum} in the input parameter @var{p}. Returns a non-zero |
| 1038 |
value if the bit was set, and a zero if it was clear. |
| 1039 |
|
| 1040 |
This intrinsic is equivalent to writing the following: |
| 1041 |
@smallexample |
| 1042 |
immutable bits_per_unit = (*p).sizeof * 8; |
| 1043 |
immutable bit_mask = size_t(1) << (bitnum % bits_per_unit); |
| 1044 |
|
| 1045 |
result = (p[bitnum / bits_per_unit] & bit_mask) != 0; |
| 1046 |
@end smallexample |
| 1047 |
@end deftypefn |
| 1048 |
|
| 1049 |
@deftypefn {Function} {int} core.bitop.btc (uint* @var{p}, uint @var{bitnum}) |
| 1050 |
@deftypefnx {Function} {int} core.bitop.btc (ulong* @var{p}, ulong @var{bitnum}) |
| 1051 |
|
| 1052 |
Tests and complements the bit @var{bitnum} in the input parameter @var{p}. |
| 1053 |
Returns a non-zero value if the bit was set, and a zero if it was clear. |
| 1054 |
|
| 1055 |
This intrinsic is equivalent to writing the following: |
| 1056 |
@smallexample |
| 1057 |
immutable bits_per_unit = (*p).sizeof * 8; |
| 1058 |
immutable bit_mask = size_t(1) << (bitnum % bits_per_unit); |
| 1059 |
|
| 1060 |
result = (p[bitnum / bits_per_unit] & bit_mask) != 0; |
| 1061 |
|
| 1062 |
p[bitnum / bits_per_unit] ^= bit_mask; |
| 1063 |
@end smallexample |
| 1064 |
@end deftypefn |
| 1065 |
|
| 1066 |
@deftypefn {Function} {int} core.bitop.btr (uint* @var{p}, uint @var{bitnum}) |
| 1067 |
@deftypefnx {Function} {int} core.bitop.btr (ulong* @var{p}, ulong @var{bitnum}) |
| 1068 |
|
| 1069 |
Tests and resets (sets to 0) the bit @var{bitnum} in the input parameter |
| 1070 |
@var{p}. Returns a non-zero value if the bit was set, and a zero if it was |
| 1071 |
clear. |
| 1072 |
|
| 1073 |
This intrinsic is equivalent to writing the following: |
| 1074 |
@smallexample |
| 1075 |
immutable bits_per_unit = (*p).sizeof * 8; |
| 1076 |
immutable bit_mask = size_t(1) << (bitnum % bits_per_unit); |
| 1077 |
|
| 1078 |
result = (p[bitnum / bits_per_unit] & bit_mask) != 0; |
| 1079 |
|
| 1080 |
p[bitnum / bits_per_unit] &= ~bit_mask; |
| 1081 |
@end smallexample |
| 1082 |
@end deftypefn |
| 1083 |
|
| 1084 |
@deftypefn {Function} {int} core.bitop.bts (uint* @var{p}, uint @var{bitnum}) |
| 1085 |
@deftypefnx {Function} {int} core.bitop.bts (ulong* @var{p}, ulong @var{bitnum}) |
| 1086 |
|
| 1087 |
Tests and sets the bit @var{bitnum} in the input parameter @var{p}. Returns a |
| 1088 |
non-zero value if the bit was set, and a zero if it was clear. |
| 1089 |
|
| 1090 |
This intrinsic is equivalent to writing the following: |
| 1091 |
@smallexample |
| 1092 |
immutable bits_per_unit = (*p).sizeof * 8; |
| 1093 |
immutable bit_mask = size_t(1) << (bitnum % bits_per_unit); |
| 1094 |
|
| 1095 |
result = (p[bitnum / bits_per_unit] & bit_mask) != 0; |
| 1096 |
|
| 1097 |
p[bitnum / bits_per_unit] |= bit_mask; |
| 1098 |
@end smallexample |
| 1099 |
@end deftypefn |
| 1100 |
|
| 1101 |
|
| 1102 |
@deftypefn {Function} {ushort} core.bitop.byteswap (ushort @var{x}) |
| 1103 |
@deftypefnx {Function} {uint} core.bitop.bswap (uint @var{x}) |
| 1104 |
@deftypefnx {Function} {ulong} core.bitop.bswap (ulong @var{x}) |
| 1105 |
|
| 1106 |
Swaps the bytes in @var{x} end-to-end; for example, in a 4-byte @code{uint}, |
| 1107 |
byte @code{0} becomes byte @code{3}, byte @code{1} becomes byte @code{2}, etc. |
| 1108 |
|
| 1109 |
This intrinsic is the same as the GCC built-in function @code{__builtin_bswap}. |
| 1110 |
@end deftypefn |
| 1111 |
|
| 1112 |
@deftypefn {Function} {int} core.bitop.popcnt (uint @var{x}) |
| 1113 |
@deftypefnx {Function} {int} core.bitop.popcnt (ulong @var{x}) |
| 1114 |
|
| 1115 |
Calculates the number of set bits in @var{x}. |
| 1116 |
|
| 1117 |
This intrinsic is the same as the GCC built-in function |
| 1118 |
@code{__builtin_popcount}. |
| 1119 |
@end deftypefn |
| 1120 |
|
| 1121 |
@deftypefn {Template} {T} core.bitop.rol (T)(const T @var{value}, const uint @var{count}) |
| 1122 |
@deftypefnx {Template} {T} core.bitop.rol (uint @var{count}, T)(const T @var{value}) |
| 1123 |
|
| 1124 |
Bitwise rotate @var{value} left by @var{count} bit positions. |
| 1125 |
|
| 1126 |
This intrinsic is equivalent to writing the following: |
| 1127 |
@smallexample |
| 1128 |
result = cast(T) ((value << count) | (value >> (T.sizeof * 8 - count))); |
| 1129 |
@end smallexample |
| 1130 |
@end deftypefn |
| 1131 |
|
| 1132 |
@deftypefn {Template} {T} core.bitop.ror (T)(const T @var{value}, const uint @var{count}) |
| 1133 |
@deftypefnx {Template} {T} core.bitop.ror (uint @var{count}, T)(const T @var{value}) |
| 1134 |
|
| 1135 |
Bitwise rotate @var{value} right by @var{count} bit positions. |
| 1136 |
|
| 1137 |
This intrinsic is equivalent to writing the following: |
| 1138 |
@smallexample |
| 1139 |
result = cast(T) ((value >> count) | (value << (T.sizeof * 8 - count))); |
| 1140 |
@end smallexample |
| 1141 |
@end deftypefn |
| 1142 |
|
| 1143 |
@c -------------------------------------------------------- |
| 1144 |
|
| 1145 |
@node Integer Overflow Intrinsics |
| 1146 |
@subsection Integer Overflow Intrinsics |
| 1147 |
@cindex intrinsics, checkedint |
| 1148 |
|
| 1149 |
The following functions are a collection of intrinsics that implement integral |
| 1150 |
arithmetic primitives that check for out-of-range results, available by |
| 1151 |
importing the @code{core.checkedint} module. |
| 1152 |
|
| 1153 |
In all intrinsics, the overflow is sticky, meaning a sequence of operations can |
| 1154 |
be done and overflow need only be checked at the end. |
| 1155 |
|
| 1156 |
@deftypefn {Function} {int} core.checkedint.adds (int @var{x}, int @var{y}, @ |
| 1157 |
ref bool @var{overflow}) |
| 1158 |
@deftypefnx {Function} {long} core.checkedint.adds (long @var{x}, long @var{y}, @ |
| 1159 |
ref bool @var{overflow}) |
| 1160 |
|
| 1161 |
Add two signed integers, checking for overflow. |
| 1162 |
|
| 1163 |
This intrinsic is the same as the GCC built-in function |
| 1164 |
@code{__builtin_sadd_overflow}. |
| 1165 |
@end deftypefn |
| 1166 |
|
| 1167 |
@deftypefn {Function} {int} core.checkedint.addu (int @var{x}, int @var{y}, @ |
| 1168 |
ref bool @var{overflow}) |
| 1169 |
@deftypefnx {Function} {long} core.checkedint.addu (long @var{x}, long @var{y}, @ |
| 1170 |
ref bool @var{overflow}) |
| 1171 |
|
| 1172 |
Add two unsigned integers, checking for overflow. |
| 1173 |
|
| 1174 |
This intrinsic is the same as the GCC built-in function |
| 1175 |
@code{__builtin_uadd_overflow}. |
| 1176 |
@end deftypefn |
| 1177 |
|
| 1178 |
@deftypefn {Function} {int} core.checkedint.muls (int @var{x}, int @var{y}, @ |
| 1179 |
ref bool @var{overflow}) |
| 1180 |
@deftypefnx {Function} {long} core.checkedint.muls (long @var{x}, long @var{y}, @ |
| 1181 |
ref bool @var{overflow}) |
| 1182 |
|
| 1183 |
Multiply two signed integers, checking for overflow. |
| 1184 |
|
| 1185 |
This intrinsic is the same as the GCC built-in function |
| 1186 |
@code{__builtin_smul_overflow}. |
| 1187 |
@end deftypefn |
| 1188 |
|
| 1189 |
@deftypefn {Function} {int} core.checkedint.mulu (int @var{x}, int @var{y}, @ |
| 1190 |
ref bool @var{overflow}) |
| 1191 |
@deftypefnx {Function} {long} core.checkedint.mulu (long @var{x}, long @var{y}, @ |
| 1192 |
ref bool @var{overflow}) |
| 1193 |
|
| 1194 |
Multiply two unsigned integers, checking for overflow. |
| 1195 |
|
| 1196 |
This intrinsic is the same as the GCC built-in function |
| 1197 |
@code{__builtin_umul_overflow}. |
| 1198 |
@end deftypefn |
| 1199 |
|
| 1200 |
@deftypefn {Function} {int} core.checkedint.negs (int @var{x}, @ |
| 1201 |
ref bool @var{overflow}) |
| 1202 |
@deftypefnx {Function} {long} core.checkedint.negs (long @var{x}, @ |
| 1203 |
ref bool @var{overflow}) |
| 1204 |
|
| 1205 |
Negates an integer. |
| 1206 |
|
| 1207 |
This intrinsic is equivalent to writing the following: |
| 1208 |
@smallexample |
| 1209 |
result = __builtin_ssub (0, x, overflow); |
| 1210 |
@end smallexample |
| 1211 |
@end deftypefn |
| 1212 |
|
| 1213 |
@deftypefn {Function} {int} core.checkedint.subs (int @var{x}, int @var{y}, @ |
| 1214 |
ref bool @var{overflow}) |
| 1215 |
@deftypefnx {Function} {long} core.checkedint.subs (long @var{x}, long @var{y}, @ |
| 1216 |
ref bool @var{overflow}) |
| 1217 |
|
| 1218 |
Substract two signed integers, checking for overflow. |
| 1219 |
|
| 1220 |
This intrinsic is the same as the GCC built-in function |
| 1221 |
@code{__builtin_ssub_overflow}. |
| 1222 |
@end deftypefn |
| 1223 |
|
| 1224 |
@deftypefn {Function} {int} core.checkedint.subu (int @var{x}, int @var{y}, @ |
| 1225 |
ref bool @var{overflow}) |
| 1226 |
@deftypefnx {Function} {long} core.checkedint.subu (long @var{x}, long @var{y}, @ |
| 1227 |
ref bool @var{overflow}) |
| 1228 |
|
| 1229 |
Substract two unsigned integers, checking for overflow. |
| 1230 |
|
| 1231 |
This intrinsic is the same as the GCC built-in function |
| 1232 |
@code{__builtin_usub_overflow}. |
| 1233 |
@end deftypefn |
| 1234 |
|
| 1235 |
@c -------------------------------------------------------- |
| 1236 |
|
| 1237 |
@node Math Intrinsics |
| 1238 |
@subsection Math Intrinsics |
| 1239 |
@cindex intrinsics, math |
| 1240 |
|
| 1241 |
The following functions are a collection of mathematical intrinsics, available |
| 1242 |
by importing the @code{core.math} module. |
| 1243 |
|
| 1244 |
@deftypefn {Function} {float} core.math.cos (float x) |
| 1245 |
@deftypefnx {Function} {double} core.math.cos (double x) |
| 1246 |
@deftypefnx {Function} {real} core.math.cos (real x) |
| 1247 |
|
| 1248 |
Returns cosine of @var{x}, where @var{x} is in radians. The return value is |
| 1249 |
undefined if @var{x} is greater than @math{2^{64}}. |
| 1250 |
|
| 1251 |
This intrinsic is the same as the GCC built-in function @code{__builtin_cos}. |
| 1252 |
@end deftypefn |
| 1253 |
|
| 1254 |
@deftypefn {Function} {float} core.math.fabs (float x) |
| 1255 |
@deftypefnx {Function} {double} core.math.fabs (double x) |
| 1256 |
@deftypefnx {Function} {real} core.math.fabs (real x) |
| 1257 |
|
| 1258 |
Compute the absolute value of @var{x}. |
| 1259 |
|
| 1260 |
This intrinsic is the same as the GCC built-in function @code{__builtin_fabs}. |
| 1261 |
@end deftypefn |
| 1262 |
|
| 1263 |
@deftypefn {Function} {float} core.math.ldexp (float n, int exp) |
| 1264 |
@deftypefnx {Function} {double} core.math.ldexp (double n, int exp) |
| 1265 |
@deftypefnx {Function} {real} core.math.ldexp (real n, int exp) |
| 1266 |
|
| 1267 |
Compute @math{n * 2^{exp}}. |
| 1268 |
|
| 1269 |
This intrinsic is the same as the GCC built-in function @code{__builtin_ldexp}. |
| 1270 |
@end deftypefn |
| 1271 |
|
| 1272 |
@deftypefn {Function} {float} core.math.rint (float x) |
| 1273 |
@deftypefnx {Function} {double} core.math.rint (double x) |
| 1274 |
@deftypefnx {Function} {real} core.math.rint (real x) |
| 1275 |
|
| 1276 |
Rounds @var{x} to the nearest integer value, using the current rounding mode. |
| 1277 |
If the return value is not equal to @var{x}, the @code{FE_INEXACT} exception is |
| 1278 |
raised. @code{nearbyint} performs the same operation, but does not set the |
| 1279 |
@code{FE_INEXACT} exception. |
| 1280 |
|
| 1281 |
This intrinsic is the same as the GCC built-in function @code{__builtin_rint}. |
| 1282 |
@end deftypefn |
| 1283 |
|
| 1284 |
@deftypefn {Function} {float} core.math.rndtol (float x) |
| 1285 |
@deftypefnx {Function} {double} core.math.rndtol (double x) |
| 1286 |
@deftypefnx {Function} {real} core.math.rndtol (real x) |
| 1287 |
|
| 1288 |
Returns @var{x} rounded to a long value using the current rounding mode. |
| 1289 |
If the integer value of @var{x} is greater than @code{long.max}, the result |
| 1290 |
is indeterminate. |
| 1291 |
|
| 1292 |
This intrinsic is the same as the GCC built-in function |
| 1293 |
@code{__builtin_llround}. |
| 1294 |
@end deftypefn |
| 1295 |
|
| 1296 |
@deftypefn {Function} {float} core.math.sin (float x) |
| 1297 |
@deftypefnx {Function} {double} core.math.sin (double x) |
| 1298 |
@deftypefnx {Function} {real} core.math.sin (real x) |
| 1299 |
|
| 1300 |
Returns sine of @var{x}, where @var{x} is in radians. The return value is |
| 1301 |
undefined if @var{x} is greater than @math{2^{64}}. |
| 1302 |
|
| 1303 |
This intrinsic is the same as the GCC built-in function @code{__builtin_sin}. |
| 1304 |
@end deftypefn |
| 1305 |
|
| 1306 |
@deftypefn {Function} {float} core.math.sqrt (float x) |
| 1307 |
@deftypefnx {Function} {double} core.math.sqrt (double x) |
| 1308 |
@deftypefnx {Function} {real} core.math.sqrt (real x) |
| 1309 |
|
| 1310 |
Compute the sqrt of @var{x}. |
| 1311 |
|
| 1312 |
This intrinsic is the same as the GCC built-in function @code{__builtin_sqrt}. |
| 1313 |
@end deftypefn |
| 1314 |
|
| 1315 |
@deftypefn {Template} {T} core.math.toPrec (T)(float f) |
| 1316 |
@deftypefnx {Template} {T} core.math.toPrec (T)(double f) |
| 1317 |
@deftypefnx {Template} {T} core.math.toPrec (T)(real f) |
| 1318 |
|
| 1319 |
Round @var{f} to a specific precision. |
| 1320 |
|
| 1321 |
In floating-point operations, D language types specify only a minimum |
| 1322 |
precision, not a maximum. The @code{toPrec} function forces rounding of the |
| 1323 |
argument @var{f} to the precision of the specified floating point type |
| 1324 |
@code{T}. The rounding mode used is inevitably target-dependent, but will be |
| 1325 |
done in a way to maximize accuracy. In most cases, the default is |
| 1326 |
round-to-nearest. |
| 1327 |
@end deftypefn |
| 1328 |
|
| 1329 |
@c -------------------------------------------------------- |
| 1330 |
|
| 1331 |
@node Variadic Intrinsics |
| 1332 |
@subsection Variadic Intrinsics |
| 1333 |
@cindex intrinsics, stdarg |
| 1334 |
|
| 1335 |
The following functions are a collection of variadic intrinsics, available by |
| 1336 |
importing the @code{core.stdc.stdarg} module. |
| 1337 |
|
| 1338 |
@deftypefn {Template} {void} core.stdc.stdarg.va_arg (T)(ref va_list ap, ref T parmn) |
| 1339 |
|
| 1340 |
Retrieve and store in @var{parmn} the next value from the @code{va_list} |
| 1341 |
@var{ap} that is of type @code{T}. |
| 1342 |
|
| 1343 |
This intrinsic is equivalent to writing the following: |
| 1344 |
@smallexample |
| 1345 |
parmn = __builtin_va_arg (ap, T); |
| 1346 |
@end smallexample |
| 1347 |
@end deftypefn |
| 1348 |
|
| 1349 |
@deftypefn {Template} {T} core.stdc.stdarg.va_arg (T)(ref va_list ap) |
| 1350 |
|
| 1351 |
Retrieve and return the next value from the @code{va_list} @var{ap} that is of |
| 1352 |
type @code{T}. |
| 1353 |
|
| 1354 |
This intrinsic is equivalent to writing the following: |
| 1355 |
@smallexample |
| 1356 |
result = __builtin_va_arg (ap, T); |
| 1357 |
@end smallexample |
| 1358 |
@end deftypefn |
| 1359 |
|
| 1360 |
@deftypefn {Function} {void} core.stdc.stdarg.va_copy (out va_list dest, va_list src) |
| 1361 |
|
| 1362 |
Make a copy of @var{src} in its current state and store to @var{dest}. |
| 1363 |
|
| 1364 |
This intrinsic is the same as the GCC built-in function @code{__builtin_va_copy}. |
| 1365 |
@end deftypefn |
| 1366 |
|
| 1367 |
@deftypefn {Function} {void} core.stdc.stdarg.va_end (va_list ap) |
| 1368 |
|
| 1369 |
Destroy @var{ap} so that it is no longer useable. |
| 1370 |
|
| 1371 |
This intrinsic is the same as the GCC built-in function @code{__builtin_va_end}. |
| 1372 |
@end deftypefn |
| 1373 |
|
| 1374 |
@deftypefn {Template} {void} core.stdc.stdarg.va_start (T)(out va_list ap, ref T parmn) |
| 1375 |
|
| 1376 |
Initialize @var{ap} so that it can be used to access the variable arguments |
| 1377 |
that follow the named argument @var{parmn}. |
| 1378 |
|
| 1379 |
This intrinsic is the same as the GCC built-in function @code{__builtin_va_start}. |
| 1380 |
@end deftypefn |
| 1381 |
|
| 1382 |
@c -------------------------------------------------------- |
| 1383 |
|
| 1384 |
@node Volatile Intrinsics |
| 1385 |
@subsection Volatile Intrinsics |
| 1386 |
@cindex intrinsics, volatile |
| 1387 |
|
| 1388 |
The following functions are a collection of intrinsics for volatile operations, |
| 1389 |
available by importing the @code{core.volatile} module. |
| 1390 |
|
| 1391 |
Calls to them are guaranteed to not be removed (as dead assignment elimination |
| 1392 |
or presumed to have no effect) or reordered in the same thread. |
| 1393 |
|
| 1394 |
These reordering guarantees are only made with regards to other operations done |
| 1395 |
through these functions; the compiler is free to reorder regular loads/stores |
| 1396 |
with regards to loads/stores done through these functions. |
| 1397 |
|
| 1398 |
This is useful when dealing with memory-mapped I/O (MMIO) where a store can |
| 1399 |
have an effect other than just writing a value, or where sequential loads with |
| 1400 |
no intervening stores can retrieve different values from the same location due |
| 1401 |
to external stores to the location. |
| 1402 |
|
| 1403 |
These functions will, when possible, do the load/store as a single operation. |
| 1404 |
In general, this is possible when the size of the operation is less than or |
| 1405 |
equal to @code{(void*).sizeof}, although some targets may support larger |
| 1406 |
operations. If the load/store cannot be done as a single operation, multiple |
| 1407 |
smaller operations will be used. |
| 1408 |
|
| 1409 |
These are not to be conflated with atomic operations. They do not guarantee |
| 1410 |
any atomicity. This may be provided by coincidence as a result of the |
| 1411 |
instructions used on the target, but this should not be relied on for portable |
| 1412 |
programs. Further, no memory fences are implied by these functions. They |
| 1413 |
should not be used for communication between threads. They may be used to |
| 1414 |
guarantee a write or read cycle occurs at a specified address. |
| 1415 |
|
| 1416 |
@deftypefn {Function} {ubyte} core.volatile.volatileLoad (ubyte* ptr) |
| 1417 |
@deftypefnx {Function} {ushort} core.volatile.volatileLoad (ushort* ptr) |
| 1418 |
@deftypefnx {Function} {uint} core.volatile.volatileLoad (uint* ptr) |
| 1419 |
@deftypefnx {Function} {ulong} core.volatile.volatileLoad (ulong* ptr) |
| 1420 |
|
| 1421 |
Read value from the memory location indicated by @var{ptr}. |
| 1422 |
@end deftypefn |
| 1423 |
|
| 1424 |
@deftypefn {Function} {ubyte} core.volatile.volatileStore (ubyte* ptr, ubyte value) |
| 1425 |
@deftypefnx {Function} {ushort} core.volatile.volatileStore (ushort* ptr, ushort value) |
| 1426 |
@deftypefnx {Function} {uint} core.volatile.volatileStore (uint* ptr, uint value) |
| 1427 |
@deftypefnx {Function} {ulong} core.volatile.volatileStore (ulong* ptr, ulong value) |
| 1428 |
|
| 1429 |
Write @var{value} to the memory location indicated by @var{ptr}. |
| 1430 |
@end deftypefn |
| 1431 |
|
| 1432 |
@c -------------------------------------------------------- |
| 1433 |
|
| 1434 |
@node CTFE Intrinsics |
| 1435 |
@subsection CTFE Intrinsics |
| 1436 |
@cindex intrinsics, ctfe |
| 1437 |
|
| 1438 |
The following functions are only treated as intrinsics during compile-time |
| 1439 |
function execution (CTFE) phase of compilation to allow more functions to be |
| 1440 |
computable at compile-time, either because their generic implementations are |
| 1441 |
too complex, or do some low-level bit manipulation of floating point types. |
| 1442 |
|
| 1443 |
Calls to these functions that exist after CTFE has finished will get standard |
| 1444 |
code-generation without any special compiler intrinsic suppport. |
| 1445 |
|
| 1446 |
@deftypefn {Function} {float} std.math.exponential.exp (float x) |
| 1447 |
@deftypefnx {Function} {double} std.math.exponential.exp (double x) |
| 1448 |
@deftypefnx {Function} {real} std.math.exponential.exp (real x) |
| 1449 |
|
| 1450 |
Calculates @math{e^x}. |
| 1451 |
|
| 1452 |
This function is evaluated during CTFE as the GCC built-in function |
| 1453 |
@code{__builtin_exp}. |
| 1454 |
@end deftypefn |
| 1455 |
|
| 1456 |
@deftypefn {Function} {float} std.math.exponential.expm1 (float x) |
| 1457 |
@deftypefnx {Function} {double} std.math.exponential.expm1 (double x) |
| 1458 |
@deftypefnx {Function} {real} std.math.exponential.expm1 (real x) |
| 1459 |
|
| 1460 |
Calculates @math{e^x-1.0}. |
| 1461 |
|
| 1462 |
This function is evaluated during CTFE as the GCC built-in function |
| 1463 |
@code{__builtin_expm1}. |
| 1464 |
@end deftypefn |
| 1465 |
|
| 1466 |
@deftypefn {Function} {float} std.math.exponential.exp2 (float x) |
| 1467 |
@deftypefnx {Function} {double} std.math.exponential.exp2 (double x) |
| 1468 |
@deftypefnx {Function} {real} std.math.exponential.exp2 (real x) |
| 1469 |
|
| 1470 |
Calculates @math{2^x}. |
| 1471 |
|
| 1472 |
This function is evaluated during CTFE as the GCC built-in function |
| 1473 |
@code{__builtin_exp2}. |
| 1474 |
@end deftypefn |
| 1475 |
|
| 1476 |
@deftypefn {Function} {float} std.math.exponential.log (float x) |
| 1477 |
@deftypefnx {Function} {double} std.math.exponential.log (double x) |
| 1478 |
@deftypefnx {Function} {real} std.math.exponential.log (real x) |
| 1479 |
|
| 1480 |
Calculate the natural logarithm of @var{x}. |
| 1481 |
|
| 1482 |
This function is evaluated during CTFE as the GCC built-in function |
| 1483 |
@code{__builtin_log}. |
| 1484 |
@end deftypefn |
| 1485 |
|
| 1486 |
@deftypefn {Function} {float} std.math.exponential.log10 (float x) |
| 1487 |
@deftypefnx {Function} {double} std.math.exponential.log10 (double x) |
| 1488 |
@deftypefnx {Function} {real} std.math.exponential.log10 (real x) |
| 1489 |
|
| 1490 |
Calculates the base-10 logarithm of @var{x}. |
| 1491 |
|
| 1492 |
This function is evaluated during CTFE as the GCC built-in function |
| 1493 |
@code{__builtin_log10}. |
| 1494 |
@end deftypefn |
| 1495 |
|
| 1496 |
@deftypefn {Function} {float} std.math.exponential.log2 (float x) |
| 1497 |
@deftypefnx {Function} {double} std.math.exponential.log2 (double x) |
| 1498 |
@deftypefnx {Function} {real} std.math.exponential.log2 (real x) |
| 1499 |
|
| 1500 |
Calculates the base-2 logarithm of @var{x}. |
| 1501 |
|
| 1502 |
This function is evaluated during CTFE as the GCC built-in function |
| 1503 |
@code{__builtin_log2}. |
| 1504 |
@end deftypefn |
| 1505 |
|
| 1506 |
@deftypefn {Template} {Largest!(F, G)} std.math.exponential.pow (F, G) (F x, G y) |
| 1507 |
@deftypefnx {Template} {real} std.math.exponential.pow (I, F)(I x, F y) |
| 1508 |
|
| 1509 |
Calculates @math{x^y}, where @var{y} is a float. |
| 1510 |
|
| 1511 |
This function is evaluated during CTFE as the GCC built-in function |
| 1512 |
@code{__builtin_pow}. |
| 1513 |
@end deftypefn |
| 1514 |
|
| 1515 |
@deftypefn {Template} {F} std.math.exponential.pow (F, G) (F x, G n) |
| 1516 |
|
| 1517 |
Calculates @math{x^n}, where @var{n} is an integer. |
| 1518 |
|
| 1519 |
This function is evaluated during CTFE as the GCC built-in function |
| 1520 |
@code{__builtin_powi}. |
| 1521 |
@end deftypefn |
| 1522 |
|
| 1523 |
@deftypefn {Function} {real} std.math.operations.fma (real x, real y, real z) |
| 1524 |
|
| 1525 |
Returns @code{(x * y) + z}, rounding only once according to the current |
| 1526 |
rounding mode. |
| 1527 |
|
| 1528 |
This function is evaluated during CTFE as the GCC built-in function |
| 1529 |
@code{__builtin_fma}. |
| 1530 |
@end deftypefn |
| 1531 |
|
| 1532 |
@deftypefn {Template} {F} std.math.operations.fmax (F)(const F x, const F y) |
| 1533 |
|
| 1534 |
Returns the larger of @var{x} and @var{y}. |
| 1535 |
|
| 1536 |
This function is evaluated during CTFE as the GCC built-in function |
| 1537 |
@code{__builtin_fmax}. |
| 1538 |
@end deftypefn |
| 1539 |
|
| 1540 |
@deftypefn {Template} {F} std.math.operations.fmin (F)(const F x, const F y) |
| 1541 |
|
| 1542 |
Returns the smaller of @var{x} and @var{y}. |
| 1543 |
|
| 1544 |
This function is evaluated during CTFE as the GCC built-in function |
| 1545 |
@code{__builtin_fmin}. |
| 1546 |
@end deftypefn |
| 1547 |
|
| 1548 |
@deftypefn {Function} {float} std.math.rounding.ceil (float x) |
| 1549 |
@deftypefnx {Function} {double} std.math.rounding.ceil (double x) |
| 1550 |
@deftypefnx {Function} {real} std.math.rounding.ceil (real x) |
| 1551 |
|
| 1552 |
Returns the value of @var{x} rounded upward to the next integer (toward |
| 1553 |
positive infinity). |
| 1554 |
|
| 1555 |
This function is evaluated during CTFE as the GCC built-in function |
| 1556 |
@code{__builtin_ceil}. |
| 1557 |
@end deftypefn |
| 1558 |
|
| 1559 |
@deftypefn {Function} {float} std.math.rounding.floor (float x) |
| 1560 |
@deftypefnx {Function} {double} std.math.rounding.floor (double x) |
| 1561 |
@deftypefnx {Function} {real} std.math.rounding.floor (real x) |
| 1562 |
|
| 1563 |
Returns the value of @var{x} rounded downward to the next integer (toward |
| 1564 |
negative infinity). |
| 1565 |
|
| 1566 |
This function is evaluated during CTFE as the GCC built-in function |
| 1567 |
@code{__builtin_floor}. |
| 1568 |
@end deftypefn |
| 1569 |
|
| 1570 |
@deftypefn {Function} {real} std.math.rounding.round (real x) |
| 1571 |
|
| 1572 |
Return the value of @var{x} rounded to the nearest integer. If the fractional |
| 1573 |
part of @var{x} is exactly 0.5, the return value is rounded away from zero. |
| 1574 |
|
| 1575 |
This function is evaluated during CTFE as the GCC built-in function |
| 1576 |
@code{__builtin_round}. |
| 1577 |
@end deftypefn |
| 1578 |
|
| 1579 |
@deftypefn {Function} {real} std.math.rounding.trunc (real x) |
| 1580 |
|
| 1581 |
Returns the integer portion of @var{x}, dropping the fractional portion. |
| 1582 |
|
| 1583 |
This function is evaluated during CTFE as the GCC built-in function |
| 1584 |
@code{__builtin_trunc}. |
| 1585 |
@end deftypefn |
| 1586 |
|
| 1587 |
@deftypefn {Template} {R} std.math.traits.copysign (R, X)(R to, X from) |
| 1588 |
|
| 1589 |
Returns a value composed of @var{to} with @var{from}'s sign bit. |
| 1590 |
|
| 1591 |
This function is evaluated during CTFE as the GCC built-in function |
| 1592 |
@code{__builtin_copysign}. |
| 1593 |
@end deftypefn |
| 1594 |
|
| 1595 |
@deftypefn {Template} {bool} std.math.traits.isFinite (X)(X x) |
| 1596 |
|
| 1597 |
Returns true if @var{x} is finite. |
| 1598 |
|
| 1599 |
This function is evaluated during CTFE as the GCC built-in function |
| 1600 |
@code{__builtin_isfinite}. |
| 1601 |
@end deftypefn |
| 1602 |
|
| 1603 |
@deftypefn {Template} {bool} std.math.traits.isInfinity (X)(X x) |
| 1604 |
|
| 1605 |
Returns true if @var{x} is infinite. |
| 1606 |
|
| 1607 |
This function is evaluated during CTFE as the GCC built-in function |
| 1608 |
@code{__builtin_isinf}. |
| 1609 |
@end deftypefn |
| 1610 |
|
| 1611 |
@deftypefn {Template} {bool} std.math.traits.isNaN (X)(X x) |
| 1612 |
|
| 1613 |
Returns true if @var{x} is NaN. |
| 1614 |
|
| 1615 |
This function is evaluated during CTFE as the GCC built-in function |
| 1616 |
@code{__builtin_isnan}. |
| 1617 |
@end deftypefn |
| 1618 |
|
| 1619 |
@deftypefn {Function} {float} std.math.trigoometry.tan (float x) |
| 1620 |
@deftypefnx {Function} {double} std.math.trigoometry.tan (double x) |
| 1621 |
@deftypefnx {Function} {real} std.math.trigonometry.tan (real x) |
| 1622 |
|
| 1623 |
Returns tangent of @var{x}, where @var{x} is in radians. |
| 1624 |
|
| 1625 |
This intrinsic is the same as the GCC built-in function @code{__builtin_tan}. |
| 1626 |
@end deftypefn |
| 1627 |
|
| 1628 |
|
| 1629 |
@c -------------------------------------------------------- |
| 1630 |
|
| 1631 |
@node Predefined Pragmas |
| 1632 |
@section Predefined Pragmas |
| 1633 |
@cindex predefined pragmas |
| 1634 |
@cindex @code{pragma} |
| 1635 |
|
| 1636 |
The @code{@w{pragma}} operator is used as a way to pass special information to the |
| 1637 |
implementation and allow the addition of vendor specific extensions. The |
| 1638 |
standard predefined pragmas are documented by the D language specification |
| 1639 |
hosted at @uref{https://dlang.org/spec/pragma.html#predefined-pragmas}. A D |
| 1640 |
compiler must recognize, but is free to ignore any pragma in this list. |
| 1641 |
|
| 1642 |
Where a pragma is ignored, the GNU D compiler will emit a warning when the |
| 1643 |
@option{-Wunknown-pragmas} option is seen on the command-line. |
| 1644 |
|
| 1645 |
@table @code |
| 1646 |
@item pragma(crt_constructor) |
| 1647 |
@code{pragma(crt_constructor)} annotates a function so it is run after the C |
| 1648 |
runtime library is initialized and before the D runtime library is initialized. |
| 1649 |
Functions with this pragma must return @code{void}. |
| 1650 |
@smallexample |
| 1651 |
pragma(crt_constructor) void init() @{ @} |
| 1652 |
@end smallexample |
| 1653 |
|
| 1654 |
@item pragma(crt_destructor) |
| 1655 |
@code{pragma(crt_destructor)} annotates a function so it is run after the D |
| 1656 |
runtime library is terminated and before the C runtime library is terminated. |
| 1657 |
Calling @code{exit} function also causes the annotated functions to run. |
| 1658 |
Functions with this pragma must return @code{void}. |
| 1659 |
@smallexample |
| 1660 |
pragma(crt_destructor) void init() @{ @} |
| 1661 |
@end smallexample |
| 1662 |
|
| 1663 |
@item pragma(inline) |
| 1664 |
@itemx pragma(inline, false) |
| 1665 |
@itemx pragma(inline, true) |
| 1666 |
@code{pragma(inline)} affects whether functions are declared inlined or not. |
| 1667 |
The pragma takes two forms. In the first form, inlining is controlled by the |
| 1668 |
command-line options for inlining. |
| 1669 |
|
| 1670 |
Functions annotated with @code{pragma(inline, false)} are marked uninlinable. |
| 1671 |
Functions annotated with @code{pragma(inline, true)} are always inlined. |
| 1672 |
|
| 1673 |
@item pragma(lib) |
| 1674 |
This pragma is accepted, but has no effect. |
| 1675 |
@smallexample |
| 1676 |
pragma(lib, "advapi32"); |
| 1677 |
@end smallexample |
| 1678 |
|
| 1679 |
@item pragma(linkerDirective) |
| 1680 |
This pragma is accepted, but has no effect. |
| 1681 |
@smallexample |
| 1682 |
pragma(linkerDirective, "/FAILIFMISMATCH:_ITERATOR_DEBUG_LEVEL=2"); |
| 1683 |
@end smallexample |
| 1684 |
|
| 1685 |
@item pragma(mangle) |
| 1686 |
@code{pragma(mangle, "symbol_name")} overrides the default mangling for a |
| 1687 |
function or variable symbol. The symbol name can be any expression that must |
| 1688 |
evaluate at compile time to a string literal. This enables linking to a symbol |
| 1689 |
which is a D keyword, since an identifier cannot be a keyword. |
| 1690 |
|
| 1691 |
Targets are free to apply a prefix to the user label of the symbol name in |
| 1692 |
assembly. For example, on @code{x86_64-apple-darwin}, @samp{symbol_name} would |
| 1693 |
produce @samp{_symbol_name}. If the mangle string begins with @samp{*}, then |
| 1694 |
@code{pragma(mangle)} will output the rest of the string unchanged. |
| 1695 |
|
| 1696 |
@smallexample |
| 1697 |
pragma(mangle, "body") |
| 1698 |
extern(C) void body_func(); |
| 1699 |
|
| 1700 |
pragma(mangle, "function") |
| 1701 |
extern(C++) struct _function @{@} |
| 1702 |
@end smallexample |
| 1703 |
|
| 1704 |
@item pragma(msg) |
| 1705 |
@code{pragma(msg, "message")} causes the compiler to print an informational |
| 1706 |
message with the text @samp{message}. The pragma accepts multiple arguments, |
| 1707 |
each to which is evaluated at compile time and then all are combined into one |
| 1708 |
concatenated message. |
| 1709 |
@smallexample |
| 1710 |
pragma(msg, "compiling...", 6, 1.0); // prints "compiling...61.0" |
| 1711 |
@end smallexample |
| 1712 |
|
| 1713 |
@item pragma(printf) |
| 1714 |
@itemx pragma(scanf) |
| 1715 |
|
| 1716 |
@code{pragma(printf)} and @code{pragma(scanf)} specifies that a function |
| 1717 |
declaration with @code{printf} or @code{scanf} style arguments that should be |
| 1718 |
type-checked against a format string. |
| 1719 |
|
| 1720 |
A printf-like or scanf-like function can either be an @code{extern(C)} or |
| 1721 |
@code{extern(C++)} function with a @var{format} parameter accepting a pointer |
| 1722 |
to a 0-terminated @code{char} string, immediately followed by either a |
| 1723 |
@code{...} variadic argument list or a parameter of type @code{va_list} as the |
| 1724 |
last parameter. |
| 1725 |
|
| 1726 |
@smallexample |
| 1727 |
extern(C): |
| 1728 |
pragma(printf) |
| 1729 |
int printf(scope const char* format, scope const ...); |
| 1730 |
|
| 1731 |
pragma(scanf) |
| 1732 |
int vscanf(scope const char* format, va_list arg); |
| 1733 |
@end smallexample |
| 1734 |
|
| 1735 |
@item pragma(startaddress) |
| 1736 |
This pragma is accepted, but has no effect. |
| 1737 |
@smallexample |
| 1738 |
void foo() @{ @} |
| 1739 |
pragma(startaddress, foo); |
| 1740 |
@end smallexample |
| 1741 |
|
| 1742 |
@end table |
| 1743 |
|
| 1744 |
|
| 1745 |
@c -------------------------------------------------------- |
| 1746 |
|
| 1747 |
@node Predefined Versions |
| 1748 |
@section Predefined Versions |
| 1749 |
@cindex predefined versions |
| 1750 |
@cindex @code{version} |
| 1751 |
|
| 1752 |
Several conditional version identifiers are predefined; you use them without |
| 1753 |
supplying their definitions. They fall into three classes: standard, common, |
| 1754 |
and target-specific. |
| 1755 |
|
| 1756 |
Predefined version identifiers from this list cannot be set from the command |
| 1757 |
line or from version statements. This prevents things like both @code{Windows} |
| 1758 |
and @code{linux} being simultaneously set. |
| 1759 |
|
| 1760 |
@menu |
| 1761 |
* Standard Predefined Versions:: |
| 1762 |
* Common Predefined Versions:: |
| 1763 |
* Target Predefined Versions:: |
| 1764 |
@end menu |
| 1765 |
|
| 1766 |
@c -------------------------------------------------------- |
| 1767 |
|
| 1768 |
@node Standard Predefined Versions |
| 1769 |
@subsection Standard Predefined Versions |
| 1770 |
@cindex standard predefined versions |
| 1771 |
|
| 1772 |
The standard predefined versions are documented by the D language specification |
| 1773 |
hosted at @uref{https://dlang.org/spec/version.html#predefined-versions}. |
| 1774 |
|
| 1775 |
@table @code |
| 1776 |
@item all |
| 1777 |
@itemx none |
| 1778 |
Version @code{none} is never defined; used to just disable a section of code. |
| 1779 |
Version @code{all} is always defined; used as the opposite of @code{none}. |
| 1780 |
|
| 1781 |
@item BigEndian |
| 1782 |
@itemx LittleEndian |
| 1783 |
These versions reflect the byte order of multi-byte data in memory. |
| 1784 |
@code{LittleEndian} is set when the least significant byte is first. |
| 1785 |
@code{BigEndian} is set when the most significant byte is first. |
| 1786 |
|
| 1787 |
@item CRuntime_Bionic |
| 1788 |
@itemx CRuntime_Glibc |
| 1789 |
@itemx CRuntime_Microsoft |
| 1790 |
@itemx CRuntime_Musl |
| 1791 |
@itemx CRuntime_Newlib |
| 1792 |
@itemx CRuntime_UClibc |
| 1793 |
|
| 1794 |
These versions reflect which standard C library is being linked in. |
| 1795 |
@code{CRuntime_Bionic} is set when Bionic is the default C library. |
| 1796 |
@code{CRuntime_Glibc} is set when GLIBC is the default C library. |
| 1797 |
@code{CRuntime_Microsoft} is set when MSVCRT is the default C library. |
| 1798 |
@code{CRuntime_Musl} is set when musl is the default C library. |
| 1799 |
@code{CRuntime_Newlib} is set when Newlib is the default C library. |
| 1800 |
@code{CRuntime_UClibc} is set when uClibc is the default C library. |
| 1801 |
|
| 1802 |
@item CppRuntime_Gcc |
| 1803 |
This version is defined when the standard C++ library being linked in is @file{libstdc++}. |
| 1804 |
|
| 1805 |
@item D_BetterC |
| 1806 |
This version is defined when the standard D libraries are not being implicitly |
| 1807 |
linked in. This also implies that features of the D language that rely on |
| 1808 |
exceptions, module information, or run-time type information are disabled as |
| 1809 |
well. Enabled by @option{-fno-druntime}. |
| 1810 |
|
| 1811 |
@item D_Coverage |
| 1812 |
This version is defined when code coverage analysis instrumentation is being |
| 1813 |
generated. Enabled by @option{-ftest-coverage}. |
| 1814 |
|
| 1815 |
@item D_Ddoc |
| 1816 |
This version is defined when Ddoc documentation is being generated. Enabled by |
| 1817 |
@option{-fdoc}. |
| 1818 |
|
| 1819 |
@item D_Exceptions |
| 1820 |
This version is defined when exception handling is supported. Disabled by |
| 1821 |
@option{-fno-exceptions}. |
| 1822 |
|
| 1823 |
@item D_HardFloat |
| 1824 |
@itemx D_SoftFloat |
| 1825 |
These versions reflect the floating-point ABI in use by the target. |
| 1826 |
@code{D_HardFloat} is set when the target hardware has a floating-point unit. |
| 1827 |
@code{D_SoftFloat} is set when the target hardware does not have a |
| 1828 |
floating-point unit. |
| 1829 |
|
| 1830 |
@item D_Invariants |
| 1831 |
This version is defined when checks are being emitted for class invariants and |
| 1832 |
struct invariants. Enabled by @option{-finvariants}. |
| 1833 |
|
| 1834 |
@item D_LP64 |
| 1835 |
This version is defined when pointers are 64-bits. Not to be confused with |
| 1836 |
with C's @code{__LP64__} model. |
| 1837 |
|
| 1838 |
@item D_ModuleInfo |
| 1839 |
This version is defined when run-time module information (also known as |
| 1840 |
@code{ModuleInfo}) is supported. Disabled by @option{-fno-moduleinfo}. |
| 1841 |
|
| 1842 |
@item D_NoBoundsChecks |
| 1843 |
This version is defined when array bounds checks are disabled. Enabled by |
| 1844 |
@option{-fno-bounds-checks}. |
| 1845 |
|
| 1846 |
@item D_Optimized |
| 1847 |
This version is defined in all optimizing compilations. |
| 1848 |
|
| 1849 |
@item D_PIC |
| 1850 |
This version is defined when position-independent code is being generated. |
| 1851 |
Enabled by @option{-fPIC}. |
| 1852 |
|
| 1853 |
@item D_PIE |
| 1854 |
This version is defined when position-independent code that can be only linked |
| 1855 |
into executables is being generated. Enabled by @option{-fPIE}. |
| 1856 |
|
| 1857 |
@item D_PreConditions |
| 1858 |
This version is defined when checks are being emitted for @code{in} contracts. |
| 1859 |
Disabled by @option{-fno-preconditions}. |
| 1860 |
|
| 1861 |
@item D_PostConditions |
| 1862 |
This version is defined when checks are being emitted for @code{out} contracts. |
| 1863 |
Disabled by @option{-fno-postconditions}. |
| 1864 |
|
| 1865 |
@item D_TypeInfo |
| 1866 |
This version is defined when run-time type information (also known as |
| 1867 |
@code{TypeInfo}) is supported. Disabled by @option{-fno-rtti}. |
| 1868 |
|
| 1869 |
@item D_Version2 |
| 1870 |
This version defined when this is a D version 2 compiler. |
| 1871 |
|
| 1872 |
@item unittest |
| 1873 |
This version is defined when the @code{unittest} code is being compiled in. |
| 1874 |
Enabled by @option{-funittest}. |
| 1875 |
|
| 1876 |
@end table |
| 1877 |
|
| 1878 |
@c -------------------------------------------------------- |
| 1879 |
|
| 1880 |
@node Common Predefined Versions |
| 1881 |
@subsection Common Predefined Versions |
| 1882 |
@cindex common predefined versions |
| 1883 |
|
| 1884 |
The common predefined macros are GNU D extensions. They are available |
| 1885 |
with the same meanings regardless of the machine or operating system on |
| 1886 |
which you are using GNU D. Their names all start with @code{GNU}. |
| 1887 |
|
| 1888 |
@table @code |
| 1889 |
|
| 1890 |
@item GNU |
| 1891 |
This version is defined by the GNU D compiler. If all you need to know is |
| 1892 |
whether or not your D program is being compiled by GDC, or a non-GDC compiler, |
| 1893 |
you can simply test @code{version(GNU)}. |
| 1894 |
|
| 1895 |
@item GNU_CET |
| 1896 |
This version is defined when @option{-fcf-protection} is used. The protection |
| 1897 |
level is also set in @code{__traits(getTargetInfo, "CET")} (@pxref{Traits}). |
| 1898 |
|
| 1899 |
@item GNU_DWARF2_Exceptions |
| 1900 |
@itemx GNU_SEH_Exceptions |
| 1901 |
@itemx GNU_SjLj_Exceptions |
| 1902 |
These versions reflect the mechanism that will be used for exception handling |
| 1903 |
by the target. @code{GNU_DWARF2_Exceptions} is defined when the target uses |
| 1904 |
DWARF 2 exceptions. @code{GNU_SEH_Exceptions} is defined when the target uses |
| 1905 |
SEH exceptions. @code{GNU_SjLj_Exceptions} is defined when the target uses the |
| 1906 |
@code{setjmp}/@code{longjmp}-based exception handling scheme. |
| 1907 |
|
| 1908 |
@item GNU_EMUTLS |
| 1909 |
This version is defined if the target does not support thread-local storage, |
| 1910 |
and an emulation layer is used instead. |
| 1911 |
|
| 1912 |
@item GNU_InlineAsm |
| 1913 |
This version is defined when @code{asm} statements use GNU D style syntax. |
| 1914 |
(@pxref{Inline Assembly}) |
| 1915 |
|
| 1916 |
@item GNU_StackGrowsDown |
| 1917 |
This version is defined if pushing a word onto the stack moves the stack |
| 1918 |
pointer to a smaller address, and is undefined otherwise. |
| 1919 |
|
| 1920 |
@end table |
| 1921 |
|
| 1922 |
@c -------------------------------------------------------- |
| 1923 |
|
| 1924 |
@node Target Predefined Versions |
| 1925 |
@subsection Target-specific Predefined Versions |
| 1926 |
@cindex target-specific predefined versions |
| 1927 |
|
| 1928 |
The D compiler normally predefines several versions that indicate what type of |
| 1929 |
system and machine is in use. They are obviously different on each target |
| 1930 |
supported by GCC. |
| 1931 |
|
| 1932 |
@table @code |
| 1933 |
@item AArch64 |
| 1934 |
Version relating to the AArch64 family of processors. |
| 1935 |
|
| 1936 |
@item Android |
| 1937 |
Version relating to the Android platform. |
| 1938 |
|
| 1939 |
@item ARM |
| 1940 |
@itemx ARM_HardFloat |
| 1941 |
@itemx ARM_SoftFloat |
| 1942 |
@itemx ARM_SoftFP |
| 1943 |
@itemx ARM_Thumb |
| 1944 |
Versions relating to the ARM family of processors. |
| 1945 |
|
| 1946 |
@item Cygwin |
| 1947 |
Version relating to the Cygwin environment. |
| 1948 |
|
| 1949 |
@item darwin |
| 1950 |
Deprecated; use @code{OSX} instead. |
| 1951 |
|
| 1952 |
@item DragonFlyBSD |
| 1953 |
Versions relating to DragonFlyBSD systems. |
| 1954 |
|
| 1955 |
@item FreeBSD |
| 1956 |
@item FreeBSD_9 |
| 1957 |
@item FreeBSD_10 |
| 1958 |
@item FreeBSD_11 |
| 1959 |
@item FreeBSD_... |
| 1960 |
Versions relating to FreeBSD systems. The FreeBSD major version number is |
| 1961 |
inferred from the target triplet. |
| 1962 |
|
| 1963 |
@item HPPA |
| 1964 |
@itemx HPPA64 |
| 1965 |
Versions relating to the HPPA family of processors. |
| 1966 |
|
| 1967 |
@item Hurd |
| 1968 |
Version relating to GNU Hurd systems. |
| 1969 |
|
| 1970 |
@item linux |
| 1971 |
Version relating to Linux systems. |
| 1972 |
|
| 1973 |
@item MinGW |
| 1974 |
Version relating to the MinGW environment. |
| 1975 |
|
| 1976 |
@item MIPS32 |
| 1977 |
@itemx MIPS64 |
| 1978 |
@itemx MIPS_EABI |
| 1979 |
@itemx MIPS_HardFloat |
| 1980 |
@itemx MIPS_N32 |
| 1981 |
@itemx MIPS_N64 |
| 1982 |
@itemx MIPS_O32 |
| 1983 |
@itemx MIPS_O64 |
| 1984 |
@itemx MIPS_SoftFloat |
| 1985 |
Versions relating to the MIPS family of processors. |
| 1986 |
|
| 1987 |
@item NetBSD |
| 1988 |
Version relating to NetBSD systems. |
| 1989 |
|
| 1990 |
@item OpenBSD |
| 1991 |
Version relating to OpenBSD systems. |
| 1992 |
|
| 1993 |
@item OSX |
| 1994 |
Version relating to OSX systems. |
| 1995 |
|
| 1996 |
@item Posix |
| 1997 |
Version relating to POSIX systems (includes Linux, FreeBSD, OSX, Solaris, etc). |
| 1998 |
|
| 1999 |
@item PPC |
| 2000 |
@itemx PPC64 |
| 2001 |
@itemx PPC_HardFloat |
| 2002 |
@itemx PPC_SoftFloat |
| 2003 |
Versions relating to the PowerPC family of processors. |
| 2004 |
|
| 2005 |
@item RISCV32 |
| 2006 |
@itemx RISCV64 |
| 2007 |
Versions relating to the RISC-V family of processors. |
| 2008 |
|
| 2009 |
@item S390 |
| 2010 |
@itemx SystemZ |
| 2011 |
Versions relating to the S/390 and System Z family of processors. |
| 2012 |
|
| 2013 |
@item S390X |
| 2014 |
Deprecated; use @code{SystemZ} instead. |
| 2015 |
|
| 2016 |
@item Solaris |
| 2017 |
Versions relating to Solaris systems. |
| 2018 |
|
| 2019 |
@item SPARC |
| 2020 |
@itemx SPARC64 |
| 2021 |
@itemx SPARC_HardFloat |
| 2022 |
@itemx SPARC_SoftFloat |
| 2023 |
@itemx SPARC_V8Plus |
| 2024 |
Versions relating to the SPARC family of processors. |
| 2025 |
|
| 2026 |
@item Thumb |
| 2027 |
Deprecated; use @code{ARM_Thumb} instead. |
| 2028 |
|
| 2029 |
@item D_X32 |
| 2030 |
@itemx X86 |
| 2031 |
@itemx X86_64 |
| 2032 |
Versions relating to the x86-32 and x86-64 family of processors. |
| 2033 |
|
| 2034 |
@item Windows |
| 2035 |
@itemx Win32 |
| 2036 |
@itemx Win64 |
| 2037 |
Versions relating to Microsoft Windows systems. |
| 2038 |
|
| 2039 |
@end table |
| 2040 |
|
| 2041 |
|
| 2042 |
@c -------------------------------------------------------- |
| 2043 |
|
| 2044 |
@node Special Enums |
| 2045 |
@section Special Enums |
| 2046 |
@cindex special enums |
| 2047 |
|
| 2048 |
Special @code{enum} names are used to represent types that do not have an |
| 2049 |
equivalent basic D type. For example, C++ types used by the C++ name mangler. |
| 2050 |
|
| 2051 |
Special enums are declared opaque, with a base type explicitly set. Unlike |
| 2052 |
regular opaque enums, special enums can be used as any other value type. They |
| 2053 |
have a default @code{.init} value, as well as other enum properties available |
| 2054 |
(@code{.min}, @code{.max}). Special enums can be declared in any module, and |
| 2055 |
will be recognized by the compiler. |
| 2056 |
|
| 2057 |
@smallexample |
| 2058 |
import gcc.builtins; |
| 2059 |
enum __c_long : __builtin_clong; |
| 2060 |
__c_long var = 0x800A; |
| 2061 |
@end smallexample |
| 2062 |
|
| 2063 |
@noindent |
| 2064 |
The following identifiers are recognized by GNU D. |
| 2065 |
|
| 2066 |
@table @code |
| 2067 |
@item __c_complex_double |
| 2068 |
C @code{_Complex double} type. |
| 2069 |
@item __c_complex_float |
| 2070 |
C @code{_Complex float} type. |
| 2071 |
@item __c_complex_real |
| 2072 |
C @code{_Complex long double} type. |
| 2073 |
@item __c_long |
| 2074 |
C++ @code{long} type. |
| 2075 |
@item __c_longlong |
| 2076 |
C++ @code{long long} type. |
| 2077 |
@item __c_long_double |
| 2078 |
C @code{long double} type. |
| 2079 |
@item __c_ulong |
| 2080 |
C++ @code{unsigned long} type. |
| 2081 |
@item __c_ulonglong |
| 2082 |
C++ @code{unsigned long long} type. |
| 2083 |
@item __c_wchar_t |
| 2084 |
C++ @code{wchar_t} type. |
| 2085 |
@end table |
| 2086 |
|
| 2087 |
The @code{core.stdc.config} module declares the following shorthand alias types |
| 2088 |
for convenience: @code{c_complex_double}, @code{c_complex_float}, |
| 2089 |
@code{c_complex_real}, @code{cpp_long}, @code{cpp_longlong}, |
| 2090 |
@code{c_long_double}, @code{cpp_ulong}, @code{cpp_ulonglong}. |
| 2091 |
|
| 2092 |
It may cause undefined behavior at runtime if a special enum is declared with a |
| 2093 |
base type that has a different size to the target C/C++ type it is |
| 2094 |
representing. The GNU D compiler will catch such declarations and emit a |
| 2095 |
warning when the @option{-Wmismatched-special-enum} option is seen on the |
| 2096 |
command-line. |
| 2097 |
|
| 2098 |
@c -------------------------------------------------------- |
| 2099 |
|
| 2100 |
@node Traits |
| 2101 |
@section Traits |
| 2102 |
@cindex traits |
| 2103 |
|
| 2104 |
Traits are extensions to the D programming language to enable programs, at |
| 2105 |
compile time, to get at information internal to the compiler. This is also |
| 2106 |
known as compile time reflection. |
| 2107 |
|
| 2108 |
GNU D implements a @code{__traits(getTargetInfo)} trait that receives a string |
| 2109 |
key as its argument. The result is an expression describing the requested |
| 2110 |
target information. |
| 2111 |
|
| 2112 |
@smallexample |
| 2113 |
version (OSX) |
| 2114 |
@{ |
| 2115 |
static assert(__traits(getTargetInfo, "objectFormat") == "macho"); |
| 2116 |
@} |
| 2117 |
@end smallexample |
| 2118 |
|
| 2119 |
@noindent |
| 2120 |
Keys for the trait are implementation defined, allowing target-specific data |
| 2121 |
for exotic targets. A reliable subset exists which a D compiler must |
| 2122 |
recognize. These are documented by the D language specification hosted at |
| 2123 |
@uref{https://dlang.org/spec/traits.html#getTargetInfo}. |
| 2124 |
|
| 2125 |
The following keys are recognized by GNU D. |
| 2126 |
|
| 2127 |
@table @code |
| 2128 |
@item CET |
| 2129 |
When @option{-fcf-protection} is used, the first bit is set to 1 for the value |
| 2130 |
@code{branch} and the second bit is set to 1 for the value @code{return}. |
| 2131 |
|
| 2132 |
@item cppRuntimeLibrary |
| 2133 |
The C++ runtime library affinity for this toolchain. |
| 2134 |
|
| 2135 |
@item cppStd |
| 2136 |
The version of the C++ standard supported by @code{extern(C++)} code, |
| 2137 |
equivalent to the @code{__cplusplus} macro in a C++ compiler. |
| 2138 |
|
| 2139 |
@item floatAbi |
| 2140 |
Floating point ABI; may be @samp{hard}, @samp{soft}, or @samp{softfp}. |
| 2141 |
|
| 2142 |
@item objectFormat |
| 2143 |
Target object format. |
| 2144 |
|
| 2145 |
@end table |
| 2146 |
|
| 2147 |
|
| 2148 |
@c -------------------------------------------------------- |
| 2149 |
|
| 2150 |
@node Vector Extensions |
| 2151 |
@section Vector Extensions |
| 2152 |
@cindex vector extensions |
| 2153 |
@cindex simd |
| 2154 |
|
| 2155 |
CPUs often support specialized vector types and vector operations (aka media |
| 2156 |
instructions). Vector types are a fixed array of floating or integer types, |
| 2157 |
and vector operations operate simultaneously on them. |
| 2158 |
|
| 2159 |
@smallexample |
| 2160 |
alias int4 = __vector(int[4]); |
| 2161 |
@end smallexample |
| 2162 |
|
| 2163 |
@noindent |
| 2164 |
All the basic integer types can be used as base types, both as signed and as |
| 2165 |
unsigned: @code{byte}, @code{short}, @code{int}, @code{long}. In addition, |
| 2166 |
@code{float} and @code{double} can be used to build floating-point vector |
| 2167 |
types, and @code{void} to build vectors of untyped data. Only sizes that are |
| 2168 |
positive power-of-two multiples of the base type size are currently allowed. |
| 2169 |
|
| 2170 |
@noindent |
| 2171 |
The @code{core.simd} module has the following shorthand aliases for commonly |
| 2172 |
supported vector types: |
| 2173 |
@code{byte8}, @code{byte16}, @code{byte32}, @code{byte64}, |
| 2174 |
@code{double1}, @code{double2}, @code{double4}, @code{double8}, |
| 2175 |
@code{float2}, @code{float4}, @code{float8}, @code{float16}, |
| 2176 |
@code{int2}, @code{int4}, @code{int8}, @code{int16}, |
| 2177 |
@code{long1}, @code{long2}, @code{long4}, @code{long8}, |
| 2178 |
@code{short4}, @code{short8}, @code{short16}, @code{short32}, |
| 2179 |
@code{ubyte8}, @code{ubyte16}, @code{ubyte32}, @code{ubyte64}, |
| 2180 |
@code{uint2}, @code{uint4}, @code{uint8}, @code{uint16}, |
| 2181 |
@code{ulong1}, @code{ulong2}, @code{ulong4}, @code{ulong8}, |
| 2182 |
@code{ushort4}, @code{ushort8}, @code{ushort16}, @code{ushort32}, |
| 2183 |
@code{void8}, @code{void16}, @code{void32}, @code{void64}. |
| 2184 |
All these aliases correspond to @code{__vector(type[N])}. |
| 2185 |
|
| 2186 |
Which vector types are supported depends on the target. Only vector types that |
| 2187 |
are implemented for the current architecture are supported at compile-time. |
| 2188 |
Vector operations that are not supported in hardware cause GNU D to synthesize |
| 2189 |
the instructions using a narrower mode. |
| 2190 |
|
| 2191 |
@smallexample |
| 2192 |
alias v4i = __vector(int[4]); |
| 2193 |
alias v128f = __vector(float[128]); // Error: not supported on this platform |
| 2194 |
|
| 2195 |
int4 a, b, c; |
| 2196 |
|
| 2197 |
c = a * b; // Natively supported on x86 with SSE4 |
| 2198 |
c = a / b; // Always synthesized |
| 2199 |
@end smallexample |
| 2200 |
|
| 2201 |
@noindent |
| 2202 |
Vector types can be used with a subset of normal D operations. Currently, GNU |
| 2203 |
D allows using the following operators on these types: @code{+, -, *, /, |
| 2204 |
unary+, unary-}@. |
| 2205 |
|
| 2206 |
@smallexample |
| 2207 |
alias int4 = __vector(int[4]); |
| 2208 |
|
| 2209 |
int4 a, b, c; |
| 2210 |
|
| 2211 |
c = a + b; |
| 2212 |
@end smallexample |
| 2213 |
|
| 2214 |
@noindent |
| 2215 |
It is also possible to use shifting operators @code{<<}, @code{>>}, the modulus |
| 2216 |
operator @code{%}, logical operations @code{&, |, ^}, and the complement |
| 2217 |
operator @code{unary~} on integer-type vectors. |
| 2218 |
|
| 2219 |
For convenience, it is allowed to use a binary vector operation where one |
| 2220 |
operand is a scalar. In that case the compiler transforms the scalar operand |
| 2221 |
into a vector where each element is the scalar from the operation. The |
| 2222 |
transformation happens only if the scalar could be safely converted to the |
| 2223 |
vector-element type. Consider the following code. |
| 2224 |
|
| 2225 |
@smallexample |
| 2226 |
alias int4 = __vector(int[4]); |
| 2227 |
|
| 2228 |
int4 a, b; |
| 2229 |
long l; |
| 2230 |
|
| 2231 |
a = b + 1; // a = b + [1,1,1,1]; |
| 2232 |
a = 2 * b; // a = [2,2,2,2] * b; |
| 2233 |
|
| 2234 |
a = l + a; // Error, incompatible types. |
| 2235 |
@end smallexample |
| 2236 |
|
| 2237 |
@noindent |
| 2238 |
Vector comparison is supported with standard comparison operators: |
| 2239 |
@code{==, !=, <, <=, >, >=}. Comparison operands can be vector expressions of |
| 2240 |
integer-type or real-type. Comparison between integer-type vectors and |
| 2241 |
real-type vectors are not supported. The result of the comparison is a vector |
| 2242 |
of the same width and number of elements as the comparison operands with a |
| 2243 |
signed integral element type. |
| 2244 |
|
| 2245 |
Vectors are compared element-wise producing 0 when comparison is false |
| 2246 |
and -1 (constant of the appropriate type where all bits are set) |
| 2247 |
otherwise. Consider the following example. |
| 2248 |
|
| 2249 |
@smallexample |
| 2250 |
alias int4 = __vector(int[4]); |
| 2251 |
|
| 2252 |
int4 a = [1,2,3,4]; |
| 2253 |
int4 b = [3,2,1,4]; |
| 2254 |
int4 c; |
| 2255 |
|
| 2256 |
c = a > b; // The result would be [0, 0,-1, 0] |
| 2257 |
c = a == b; // The result would be [0,-1, 0,-1] |
| 2258 |
@end smallexample |
| 2259 |
|
| 2260 |
|
| 2261 |
@c -------------------------------------------------------- |
| 2262 |
|
| 2263 |
@node Vector Intrinsics |
| 2264 |
@section Vector Intrinsics |
| 2265 |
@cindex intrinsics, vector |
| 2266 |
|
| 2267 |
The following functions are a collection of vector operation intrinsics, |
| 2268 |
available by importing the @code{gcc.simd} module. |
| 2269 |
|
| 2270 |
@deftypefn {Template} {void} gcc.simd.prefetch (bool @var{rw}, @ |
| 2271 |
ubyte @var{locality}) @ |
| 2272 |
(const(void)* @var{addr}) |
| 2273 |
|
| 2274 |
Emit the prefetch instruction. The value of @var{addr} is the address of the |
| 2275 |
memory to prefetch. The value of @var{rw} is a compile-time constant one or |
| 2276 |
zero; one means that the prefetch is preparing for a write to the memory |
| 2277 |
address and zero, the default, means that the prefetch is preparing for a read. |
| 2278 |
The value @var{locality} must be a compile-time constant integer between zero |
| 2279 |
and three. |
| 2280 |
|
| 2281 |
This intrinsic is the same as the GCC built-in function |
| 2282 |
@code{__builtin_prefetch}. |
| 2283 |
|
| 2284 |
@smallexample |
| 2285 |
for (i = 0; i < n; i++) |
| 2286 |
@{ |
| 2287 |
import gcc.simd : prefetch; |
| 2288 |
a[i] = a[i] + b[i]; |
| 2289 |
prefetch!(true, 1)(&a[i+j]); |
| 2290 |
prefetch!(false, 1)(&b[i+j]); |
| 2291 |
// @r{@dots{}} |
| 2292 |
@} |
| 2293 |
@end smallexample |
| 2294 |
@end deftypefn |
| 2295 |
|
| 2296 |
@deftypefn {Template} {V} gcc.simd.loadUnaligned (V)(const V* @var{p}) |
| 2297 |
|
| 2298 |
Load unaligned vector from the address @var{p}. |
| 2299 |
|
| 2300 |
@smallexample |
| 2301 |
float4 v; |
| 2302 |
ubyte[16] arr; |
| 2303 |
|
| 2304 |
v = loadUnaligned(cast(float4*)arr.ptr); |
| 2305 |
@end smallexample |
| 2306 |
@end deftypefn |
| 2307 |
|
| 2308 |
@deftypefn {Template} {V} gcc.simd.storeUnaligned (V)(V* @var{p}, V @var{value}) |
| 2309 |
|
| 2310 |
Store vector @var{value} to unaligned address @var{p}. |
| 2311 |
|
| 2312 |
@smallexample |
| 2313 |
float4 v; |
| 2314 |
ubyte[16] arr; |
| 2315 |
|
| 2316 |
storeUnaligned(cast(float4*)arr.ptr, v); |
| 2317 |
@end smallexample |
| 2318 |
@end deftypefn |
| 2319 |
|
| 2320 |
@deftypefn {Template} {V0} gcc.simd.shuffle (V0, V1, M)(V0 @var{op1}, @ |
| 2321 |
V1 @var{op2}, @ |
| 2322 |
M @var{mask}) |
| 2323 |
@deftypefnx {Template} {V} gcc.simd.shuffle (V, M)(V @var{op1}, M @var{mask}) |
| 2324 |
|
| 2325 |
Construct a permutation of elements from one or two vectors, returning a vector |
| 2326 |
of the same type as the input vector(s). The @var{mask} is an integral vector |
| 2327 |
with the same width and element count as the output vector. |
| 2328 |
|
| 2329 |
This intrinsic is the same as the GCC built-in function |
| 2330 |
@code{__builtin_shuffle}. |
| 2331 |
|
| 2332 |
@smallexample |
| 2333 |
int4 a = [1, 2, 3, 4]; |
| 2334 |
int4 b = [5, 6, 7, 8]; |
| 2335 |
int4 mask1 = [0, 1, 1, 3]; |
| 2336 |
int4 mask2 = [0, 4, 2, 5]; |
| 2337 |
int4 res; |
| 2338 |
|
| 2339 |
res = shuffle(a, mask1); // res is [1,2,2,4] |
| 2340 |
res = shuffle(a, b, mask2); // res is [1,5,3,6] |
| 2341 |
@end smallexample |
| 2342 |
@end deftypefn |
| 2343 |
|
| 2344 |
@deftypefn {Template} {V} gcc.simd.shufflevector (V1, V2, M...)(V1 @var{op1}, @ |
| 2345 |
V2 @var{op2}, M @var{mask}) |
| 2346 |
@deftypefnx {Template} {V} gcc.simd.shufflevector (V, @var{mask}...)(V @ |
| 2347 |
@var{op1}, V @var{op2}) |
| 2348 |
|
| 2349 |
Construct a permutation of elements from two vectors, returning a vector with |
| 2350 |
the same element type as the input vector(s), and same length as the |
| 2351 |
@var{mask}. |
| 2352 |
|
| 2353 |
This intrinsic is the same as the GCC built-in function |
| 2354 |
@code{__builtin_shufflevector}. |
| 2355 |
|
| 2356 |
@smallexample |
| 2357 |
int8 a = [1, -2, 3, -4, 5, -6, 7, -8]; |
| 2358 |
int4 b = shufflevector(a, a, 0, 2, 4, 6); // b is [1,3,5,7] |
| 2359 |
int4 c = [-2, -4, -6, -8]; |
| 2360 |
int8 d = shufflevector!(int8, 4, 0, 5, 1, 6, 2, 7, 3)(c, b); // d is a |
| 2361 |
@end smallexample |
| 2362 |
@end deftypefn |
| 2363 |
|
| 2364 |
@deftypefn {Template} {E} gcc.simd.extractelement (V, int idx)(V @var{val}) |
| 2365 |
Extracts a single scalar element from a vector @var{val} at a specified index |
| 2366 |
@var{idx}. |
| 2367 |
|
| 2368 |
@smallexample |
| 2369 |
int4 a = [0, 10, 20, 30]; |
| 2370 |
int k = extractelement!(int4, 2)(a); // a is 20 |
| 2371 |
@end smallexample |
| 2372 |
@end deftypefn |
| 2373 |
|
| 2374 |
@deftypefn {Template} {V} gcc.simd.insertelement (V, int idx)(V val, B @var{e}) |
| 2375 |
Inserts a scalar element @var{e} into a vector @var{val} at a specified index |
| 2376 |
@var{idx}. |
| 2377 |
|
| 2378 |
@smallexample |
| 2379 |
int4 a = [0, 10, 20, 30]; |
| 2380 |
int4 b = insertelement!(int4, 2)(a, 50); // b is [0,10,50,30] |
| 2381 |
@end smallexample |
| 2382 |
@end deftypefn |
| 2383 |
|
| 2384 |
@deftypefn {Template} {V} gcc.simd.convertvector (V, T)(T val) |
| 2385 |
Convert a vector @var{val} from one integral or floating vector type to |
| 2386 |
another. The result is an integral or floating vector that has had every |
| 2387 |
element cast to the element type of the return type. |
| 2388 |
|
| 2389 |
This intrinsic is the same as the GCC built-in function |
| 2390 |
@code{__builtin_convertvector}. |
| 2391 |
|
| 2392 |
@smallexample |
| 2393 |
int4 a = [1, -2, 3, -4]; |
| 2394 |
float4 b = [1.5, -2.5, 3, 7]; |
| 2395 |
float4 c = convertvector!float4(a); // c is [1,-2,3,-4] |
| 2396 |
double4 d = convertvector!double4(a); // d is [1,-2,3,-4] |
| 2397 |
double4 e = convertvector!double4(b); // e is [1.5,-2.5,3,7] |
| 2398 |
int4 f = convertvector!int4(b); // f is [1,-2,3,7] |
| 2399 |
@end smallexample |
| 2400 |
@end deftypefn |
| 2401 |
|
| 2402 |
@deftypefn {Template} {V0} gcc.simd.blendvector (V0, V1, M)(V0 @var{op0}, @ |
| 2403 |
V1 @var{op1}, @ |
| 2404 |
M @var{mask}) |
| 2405 |
|
| 2406 |
Construct a conditional merge of elements from two vectors, returning a vector |
| 2407 |
of the same type as the input vector(s). The @var{mask} is an integral vector |
| 2408 |
with the same width and element count as the output vector. |
| 2409 |
|
| 2410 |
@smallexample |
| 2411 |
int4 a = [1, 2, 3, 4]; |
| 2412 |
int4 b = [3, 2, 1, 4]; |
| 2413 |
auto c = blendvector(a, b, a > b); // c is [3,2,3,4] |
| 2414 |
auto d = blendvector(a, b, a < b); // d is [1,2,1,4] |
| 2415 |
@end smallexample |
| 2416 |
@end deftypefn |
| 2417 |
|
| 2418 |
|
| 2419 |
@c -------------------------------------------------------- |
| 2420 |
|
| 2421 |
@node Missing Features |
| 2422 |
@section Missing Features and Deviations |
| 2423 |
@cindex missing features |
| 2424 |
@cindex D spec deviations |
| 2425 |
|
| 2426 |
Some parts of the D specification are hard or impossible to implement with |
| 2427 |
GCC, they should be listed here. |
| 2428 |
|
| 2429 |
@table @asis |
| 2430 |
@item Bit Operation Intrinsics |
| 2431 |
The Digital Mars D compiler implements the @code{core.bitop} intrinsics |
| 2432 |
@code{inp}, @code{inpw}, @code{inpl}, @code{outp}, @code{outpw}, and |
| 2433 |
@code{outpl}. These are not recognized by GNU D. On most targets, equivalent |
| 2434 |
intrinsics that have the same effect would be @code{core.volatile.loadVolatile} |
| 2435 |
and @code{core.volatile.storeVolatile} respectively |
| 2436 |
(@pxref{Volatile Intrinsics}). |
| 2437 |
|
| 2438 |
On x86 targets, if an @code{in} or @code{out} instruction is specifically |
| 2439 |
required, that can be achieved using assembler statements instead. |
| 2440 |
@smallexample |
| 2441 |
ubyte inp(uint port) |
| 2442 |
@{ |
| 2443 |
ubyte value; |
| 2444 |
asm @{ "inb %w1, %b0" : "=a" (value) : "Nd" (port); @} |
| 2445 |
return value; |
| 2446 |
@} |
| 2447 |
|
| 2448 |
void outp(uint port, ushort value) |
| 2449 |
@{ |
| 2450 |
asm @{ "outb %b0, %w1" : : "a" (value), "Nd" (port); @} |
| 2451 |
@} |
| 2452 |
@end smallexample |
| 2453 |
|
| 2454 |
@item Floating-Point Intermediate Values |
| 2455 |
|
| 2456 |
GNU D uses a software compile-time floating-point type that assists in |
| 2457 |
cross-compilation and support for arbitrary target @code{real} precisions wider |
| 2458 |
than 80 bits. Because of this, the result of floating-point CTFE operations |
| 2459 |
may have different results in GNU D compared with other D compilers that use |
| 2460 |
the host's native floating-point type for storage and CTFE. In particular, GNU |
| 2461 |
D won't overflow or underflow when a target real features a higher precision |
| 2462 |
than the host. Differences also extend to @code{.stringof} representations of |
| 2463 |
intermediate values due to formatting differences with @code{sprintf("%Lg")}. |
| 2464 |
@smallexample |
| 2465 |
version(GNU) |
| 2466 |
assert((25.5).stringof ~ (3.01).stringof == "2.55e+13.01e+0"); |
| 2467 |
else |
| 2468 |
assert((25.5).stringof ~ (3.01).stringof == "25.53.01"); |
| 2469 |
@end smallexample |
| 2470 |
|
| 2471 |
@item Function Calling Conventions |
| 2472 |
GNU D does not implement the @code{extern(D)} calling convention for x86 as |
| 2473 |
described in the D specification hosted at |
| 2474 |
@uref{https://dlang.org/spec/abi.html#function_calling_conventions}. |
| 2475 |
|
| 2476 |
Instead, there is no distinction between @code{extern(C)} and @code{extern(D)} |
| 2477 |
other than name mangling. |
| 2478 |
|
| 2479 |
@item ImportC Limitations |
| 2480 |
GNU D does not run the preprocessor automatically for any ImportC sources. |
| 2481 |
Instead all C files are expected to be manually preprocessed before they are |
| 2482 |
imported into the compilation. |
| 2483 |
|
| 2484 |
@item Inline Assembler |
| 2485 |
GNU D does not implement the D inline assembler for x86 and x86_64 as described |
| 2486 |
in the D specification hosted at @uref{https://dlang.org/spec/iasm.html}. Nor |
| 2487 |
does GNU D predefine the @code{D_InlineAsm_X86} and @code{D_InlineAsm_X86_64} |
| 2488 |
version identifiers to indicate support. |
| 2489 |
|
| 2490 |
The GNU D compiler uses an alternative, GCC-based syntax for inline assembler |
| 2491 |
(@pxref{Inline Assembly}). |
| 2492 |
|
| 2493 |
@item Interfacing to Objective-C |
| 2494 |
GNU D does not support interfacing with Objective-C, nor its protocols, |
| 2495 |
classes, subclasses, instance variables, instance methods and class methods. |
| 2496 |
The @code{extern(Objective-C)} linkage is ignored, as are the @code{@@optional} |
| 2497 |
and @code{@@selector} attributes. The @code{D_ObjectiveC} version identifier |
| 2498 |
is not predefined for compilations. |
| 2499 |
|
| 2500 |
@item Pragma Directives |
| 2501 |
Pragmas that are designed to embed information into object files or otherwise |
| 2502 |
pass options to the linker are not supported by GNU D. These include |
| 2503 |
@code{pragma(lib)}, @code{pragma(linkerDirective)}, and |
| 2504 |
@code{pragma(startaddress)}. |
| 2505 |
|
| 2506 |
@item SIMD Intrinsics |
| 2507 |
The Digital Mars D compiler implements the @code{core.simd} intrinsics |
| 2508 |
@code{__simd}, @code{__simd_ib}, @code{__simd_sto}. These are not recognized |
| 2509 |
by GNU D, nor does GNU D predefine the @code{D_SIMD} version identifier to |
| 2510 |
indicate support. |
| 2511 |
|
| 2512 |
On x86 targets, all intrinsics are available as functions in the |
| 2513 |
@code{gcc.builtins} module, and have predictable equivalents. |
| 2514 |
@smallexample |
| 2515 |
version (DigitalMars) |
| 2516 |
@{ |
| 2517 |
__simd(XMM.PSLLW, op1, op2); |
| 2518 |
__simd_ib(XMM.PSLLW, op1, imm8); |
| 2519 |
@} |
| 2520 |
version (GNU) |
| 2521 |
@{ |
| 2522 |
__builtin_ia32_psllw(op1, op2); |
| 2523 |
__builtin_ia32_psllwi(op1, imm8); |
| 2524 |
@} |
| 2525 |
@end smallexample |
| 2526 |
|
| 2527 |
@item TypeInfo-based va_arg |
| 2528 |
The Digital Mars D compiler implements a version of @code{core.vararg.va_arg} |
| 2529 |
that accepts a run-time @code{TypeInfo} argument for use when the static type |
| 2530 |
is not known. This function is not implemented by GNU D. It is more portable |
| 2531 |
to use variadic template functions instead. |
| 2532 |
|
| 2533 |
@end table |