libgomp.info revision 1.15
1 This is libgomp.info, produced by makeinfo version 6.5 from 2 libgomp.texi. 3 4 Copyright (C) 2006-2022 Free Software Foundation, Inc. 5 6 Permission is granted to copy, distribute and/or modify this document 7 under the terms of the GNU Free Documentation License, Version 1.3 or 8 any later version published by the Free Software Foundation; with the 9 Invariant Sections being "Funding Free Software", the Front-Cover texts 10 being (a) (see below), and with the Back-Cover Texts being (b) (see 11 below). A copy of the license is included in the section entitled "GNU 12 Free Documentation License". 13 14 (a) The FSF's Front-Cover Text is: 15 16 A GNU Manual 17 18 (b) The FSF's Back-Cover Text is: 19 20 You have freedom to copy and modify this GNU Manual, like GNU 21 software. Copies published by the Free Software Foundation raise funds 22 for GNU development. 23 INFO-DIR-SECTION GNU Libraries 24 START-INFO-DIR-ENTRY 25 * libgomp: (libgomp). GNU Offloading and Multi Processing Runtime Library. 26 END-INFO-DIR-ENTRY 27 28 This manual documents libgomp, the GNU Offloading and Multi 29 Processing Runtime library. This is the GNU implementation of the 30 OpenMP and OpenACC APIs for parallel and accelerator programming in 31 C/C++ and Fortran. 32 33 Published by the Free Software Foundation 51 Franklin Street, Fifth 34 Floor Boston, MA 02110-1301 USA 35 36 Copyright (C) 2006-2022 Free Software Foundation, Inc. 37 38 Permission is granted to copy, distribute and/or modify this document 39 under the terms of the GNU Free Documentation License, Version 1.3 or 40 any later version published by the Free Software Foundation; with the 41 Invariant Sections being "Funding Free Software", the Front-Cover texts 42 being (a) (see below), and with the Back-Cover Texts being (b) (see 43 below). A copy of the license is included in the section entitled "GNU 44 Free Documentation License". 45 46 (a) The FSF's Front-Cover Text is: 47 48 A GNU Manual 49 50 (b) The FSF's Back-Cover Text is: 51 52 You have freedom to copy and modify this GNU Manual, like GNU 53 software. Copies published by the Free Software Foundation raise funds 54 for GNU development. 55 56 57 File: libgomp.info, Node: Top, Next: Enabling OpenMP 58 59 Introduction 60 ************ 61 62 This manual documents the usage of libgomp, the GNU Offloading and Multi 63 Processing Runtime Library. This includes the GNU implementation of the 64 OpenMP (https://www.openmp.org) Application Programming Interface (API) 65 for multi-platform shared-memory parallel programming in C/C++ and 66 Fortran, and the GNU implementation of the OpenACC 67 (https://www.openacc.org) Application Programming Interface (API) for 68 offloading of code to accelerator devices in C/C++ and Fortran. 69 70 Originally, libgomp implemented the GNU OpenMP Runtime Library. 71 Based on this, support for OpenACC and offloading (both OpenACC and 72 OpenMP 4's target construct) has been added later on, and the library's 73 name changed to GNU Offloading and Multi Processing Runtime Library. 74 75 * Menu: 76 77 * Enabling OpenMP:: How to enable OpenMP for your applications. 78 * OpenMP Implementation Status:: List of implemented features by OpenMP version 79 * OpenMP Runtime Library Routines: Runtime Library Routines. 80 The OpenMP runtime application programming 81 interface. 82 * OpenMP Environment Variables: Environment Variables. 83 Influencing OpenMP runtime behavior with 84 environment variables. 85 * Enabling OpenACC:: How to enable OpenACC for your 86 applications. 87 * OpenACC Runtime Library Routines:: The OpenACC runtime application 88 programming interface. 89 * OpenACC Environment Variables:: Influencing OpenACC runtime behavior with 90 environment variables. 91 * CUDA Streams Usage:: Notes on the implementation of 92 asynchronous operations. 93 * OpenACC Library Interoperability:: OpenACC library interoperability with the 94 NVIDIA CUBLAS library. 95 * OpenACC Profiling Interface:: 96 * The libgomp ABI:: Notes on the external ABI presented by libgomp. 97 * Reporting Bugs:: How to report bugs in the GNU Offloading and 98 Multi Processing Runtime Library. 99 * Copying:: GNU general public license says 100 how you can copy and share libgomp. 101 * GNU Free Documentation License:: 102 How you can copy and share this manual. 103 * Funding:: How to help assure continued work for free 104 software. 105 * Library Index:: Index of this documentation. 106 107 108 File: libgomp.info, Node: Enabling OpenMP, Next: OpenMP Implementation Status, Up: Top 109 110 1 Enabling OpenMP 111 ***************** 112 113 To activate the OpenMP extensions for C/C++ and Fortran, the 114 compile-time flag '-fopenmp' must be specified. This enables the OpenMP 115 directive '#pragma omp' in C/C++ and '!$omp' directives in free form, 116 'c$omp', '*$omp' and '!$omp' directives in fixed form, '!$' conditional 117 compilation sentinels in free form and 'c$', '*$' and '!$' sentinels in 118 fixed form, for Fortran. The flag also arranges for automatic linking 119 of the OpenMP runtime library (*note Runtime Library Routines::). 120 121 A complete description of all OpenMP directives may be found in the 122 OpenMP Application Program Interface (https://www.openmp.org) manuals. 123 See also *note OpenMP Implementation Status::. 124 125 126 File: libgomp.info, Node: OpenMP Implementation Status, Next: Runtime Library Routines, Prev: Enabling OpenMP, Up: Top 127 128 2 OpenMP Implementation Status 129 ****************************** 130 131 * Menu: 132 133 * OpenMP 4.5:: Feature completion status to 4.5 specification 134 * OpenMP 5.0:: Feature completion status to 5.0 specification 135 * OpenMP 5.1:: Feature completion status to 5.1 specification 136 137 The '_OPENMP' preprocessor macro and Fortran's 'openmp_version' 138 parameter, provided by 'omp_lib.h' and the 'omp_lib' module, have the 139 value '201511' (i.e. OpenMP 4.5). 140 141 142 File: libgomp.info, Node: OpenMP 4.5, Next: OpenMP 5.0, Up: OpenMP Implementation Status 143 144 2.1 OpenMP 4.5 145 ============== 146 147 The OpenMP 4.5 specification is fully supported. 148 149 150 File: libgomp.info, Node: OpenMP 5.0, Next: OpenMP 5.1, Prev: OpenMP 4.5, Up: OpenMP Implementation Status 151 152 2.2 OpenMP 5.0 153 ============== 154 155 New features listed in Appendix B of the OpenMP specification 156 ------------------------------------------------------------- 157 158 Description Status Comments 159 ----------------------------------------------------------------------- 160 Array shaping N 161 Array sections with non-unit strides in C N 162 and C++ 163 Iterators Y 164 'metadirective' directive N 165 'declare variant' directive P simd traits not 166 handled 167 correctly 168 _target-offload-var_ ICV and Y 169 'OMP_TARGET_OFFLOAD' env variable 170 Nested-parallel changes to Y 171 _max-active-levels-var_ ICV 172 'requires' directive P Only fulfillable 173 requirement are 174 'atomic_default_mem_order' 175 and 176 'dynamic_allocators' 177 'teams' construct outside an enclosing Y 178 target region 179 Non-rectangular loop nests P Only C/C++ 180 '!=' as relational-op in canonical loop Y 181 form for C/C++ 182 'nonmonotonic' as default loop schedule Y 183 modifier for worksharing-loop constructs 184 Collapse of associated loops that are N 185 imperfectly nested loops 186 Clauses 'if', 'nontemporal' and Y 187 'order(concurrent)' in 'simd' construct 188 'atomic' constructs in 'simd' Y 189 'loop' construct Y 190 'order(concurrent)' clause Y 191 'scan' directive and 'in_scan' modifier Y 192 for the 'reduction' clause 193 'in_reduction' clause on 'task' Y 194 constructs 195 'in_reduction' clause on 'target' P 'nowait' only 196 constructs stub 197 'task_reduction' clause with 'taskgroup' Y 198 'task' modifier to 'reduction' clause Y 199 'affinity' clause to 'task' construct Y Stub only 200 'detach' clause to 'task' construct Y 201 'omp_fulfill_event' runtime routine Y 202 'reduction' and 'in_reduction' clauses on Y 203 'taskloop' and 'taskloop simd' constructs 204 'taskloop' construct cancelable by Y 205 'cancel' construct 206 'mutexinoutset' _dependence-type_ for Y 207 'depend' clause 208 Predefined memory spaces, memory Y Some are only 209 allocators, allocator traits stubs 210 Memory management routines Y 211 'allocate' directive N 212 'allocate' clause P initial support 213 'use_device_addr' clause on 'target data' Y 214 'ancestor' modifier on 'device' clause P Reverse offload 215 unsupported 216 Implicit declare target directive Y 217 Discontiguous array section with 'target N 218 update' construct 219 C/C++'s lvalue expressions in 'to', N 220 'from' and 'map' clauses 221 C/C++'s lvalue expressions in 'depend' Y 222 clauses 223 Nested 'declare target' directive Y 224 Combined 'master' constructs Y 225 'depend' clause on 'taskwait' Y 226 Weak memory ordering clauses on 'atomic' Y 227 and 'flush' construct 228 'hint' clause on the 'atomic' construct Y Stub only 229 'depobj' construct and depend objects Y 230 Lock hints were renamed to Y 231 synchronization hints 232 'conditional' modifier to 'lastprivate' Y 233 clause 234 Map-order clarifications P 235 'close' _map-type-modifier_ Y 236 Mapping C/C++ pointer variables and to P 237 assign the address of device memory 238 mapped by an array section 239 Mapping of Fortran pointer and P Mapping of vars 240 allocatable variables, including pointer with allocatable 241 and allocatable components of variables components 242 unsupported 243 'defaultmap' extensions Y 244 'declare mapper' directive N 245 'omp_get_supported_active_levels' routine Y 246 Runtime routines and environment Y 247 variables to display runtime thread 248 affinity information 249 'omp_pause_resource' and Y 250 'omp_pause_resource_all' runtime routines 251 'omp_get_device_num' runtime routine Y 252 OMPT interface N 253 OMPD interface N 254 255 Other new OpenMP 5.0 features 256 ----------------------------- 257 258 Description Status Comments 259 ----------------------------------------------------------------------- 260 Supporting C++'s range-based for loop Y 261 262 263 File: libgomp.info, Node: OpenMP 5.1, Prev: OpenMP 5.0, Up: OpenMP Implementation Status 264 265 2.3 OpenMP 5.1 266 ============== 267 268 New features listed in Appendix B of the OpenMP specification 269 ------------------------------------------------------------- 270 271 Description Status Comments 272 ----------------------------------------------------------------------- 273 OpenMP directive as C++ attribute Y 274 specifiers 275 'omp_all_memory' reserved locator N 276 _target_device trait_ in OpenMP Context N 277 'target_device' selector set in context N 278 selectors 279 C/C++'s 'declare variant' directive: N 280 elision support of preprocessed code 281 'declare variant': new clauses N 282 'adjust_args' and 'append_args' 283 'dispatch' construct N 284 device-specific ICV settings the N 285 environment variables 286 assume directive N 287 'nothing' directive Y 288 'error' directive Y 289 'masked' construct Y 290 'scope' directive Y 291 Loop transformation constructs N 292 'strict' modifier in the 'grainsize' and Y 293 'num_tasks' clauses of the taskloop 294 construct 295 'align' clause/modifier in 'allocate' P C/C++ on clause 296 directive/clause and 'allocator' only 297 directive 298 'thread_limit' clause to 'target' Y 299 construct 300 'has_device_addr' clause to 'target' Y 301 construct 302 iterators in 'target update' motion N 303 clauses and 'map' clauses 304 indirect calls to the device version of a N 305 procedure or function in 'target' regions 306 'interop' directive N 307 'omp_interop_t' object support in runtime N 308 routines 309 'nowait' clause in 'taskwait' directive N 310 Extensions to the 'atomic' directive Y 311 'seq_cst' clause on a 'flush' construct Y 312 'inoutset' argument to the 'depend' N 313 clause 314 'private' and 'firstprivate' argument to Y 315 'default' clause in C and C++ 316 'present' argument to 'defaultmap' clause N 317 'omp_set_num_teams', Y 318 'omp_set_teams_thread_limit', 319 'omp_get_max_teams', 320 'omp_get_teams_thread_limit' runtime 321 routines 322 'omp_target_is_accessible' runtime N 323 routine 324 'omp_target_memcpy_async' and N 325 'omp_target_memcpy_rect_async' runtime 326 routines 327 'omp_get_mapped_ptr' runtime routine N 328 'omp_calloc', 'omp_realloc', Y 329 'omp_aligned_alloc' and 330 'omp_aligned_calloc' runtime routines 331 'omp_alloctrait_key_t' enum: Y 332 'omp_atv_serialized' added, 333 'omp_atv_default' changed 334 'omp_display_env' runtime routine Y 335 'ompt_scope_endpoint_t' enum: N 336 'ompt_scope_beginend' 337 'ompt_sync_region_t' enum additions N 338 'ompt_state_t' enum: N 339 'ompt_state_wait_barrier_implementation' 340 and 'ompt_state_wait_barrier_teams' 341 'ompt_callback_target_data_op_emi_t', N 342 'ompt_callback_target_emi_t', 343 'ompt_callback_target_map_emi_t' and 344 'ompt_callback_target_submit_emi_t' 345 'ompt_callback_error_t' type N 346 'OMP_PLACES' syntax extensions Y 347 'OMP_NUM_TEAMS' and Y 348 'OMP_TEAMS_THREAD_LIMIT' environment 349 variables 350 351 Other new OpenMP 5.1 features 352 ----------------------------- 353 354 Description Status Comments 355 ----------------------------------------------------------------------- 356 Support of strictly structured blocks in Y 357 Fortran 358 Support of structured block sequences in Y 359 C/C++ 360 'unconstrained' and 'reproducible' Y 361 modifiers on 'order' clause 362 363 364 File: libgomp.info, Node: Runtime Library Routines, Next: Environment Variables, Prev: OpenMP Implementation Status, Up: Top 365 366 3 OpenMP Runtime Library Routines 367 ********************************* 368 369 The runtime routines described here are defined by Section 3 of the 370 OpenMP specification in version 4.5. The routines are structured in 371 following three parts: 372 373 * Menu: 374 375 Control threads, processors and the parallel environment. They have C 376 linkage, and do not throw exceptions. 377 378 * omp_get_active_level:: Number of active parallel regions 379 * omp_get_ancestor_thread_num:: Ancestor thread ID 380 * omp_get_cancellation:: Whether cancellation support is enabled 381 * omp_get_default_device:: Get the default device for target regions 382 * omp_get_device_num:: Get device that current thread is running on 383 * omp_get_dynamic:: Dynamic teams setting 384 * omp_get_initial_device:: Device number of host device 385 * omp_get_level:: Number of parallel regions 386 * omp_get_max_active_levels:: Current maximum number of active regions 387 * omp_get_max_task_priority:: Maximum task priority value that can be set 388 * omp_get_max_teams:: Maximum number of teams for teams region 389 * omp_get_max_threads:: Maximum number of threads of parallel region 390 * omp_get_nested:: Nested parallel regions 391 * omp_get_num_devices:: Number of target devices 392 * omp_get_num_procs:: Number of processors online 393 * omp_get_num_teams:: Number of teams 394 * omp_get_num_threads:: Size of the active team 395 * omp_get_proc_bind:: Whether threads may be moved between CPUs 396 * omp_get_schedule:: Obtain the runtime scheduling method 397 * omp_get_supported_active_levels:: Maximum number of active regions supported 398 * omp_get_team_num:: Get team number 399 * omp_get_team_size:: Number of threads in a team 400 * omp_get_teams_thread_limit:: Maximum number of threads imposed by teams 401 * omp_get_thread_limit:: Maximum number of threads 402 * omp_get_thread_num:: Current thread ID 403 * omp_in_parallel:: Whether a parallel region is active 404 * omp_in_final:: Whether in final or included task region 405 * omp_is_initial_device:: Whether executing on the host device 406 * omp_set_default_device:: Set the default device for target regions 407 * omp_set_dynamic:: Enable/disable dynamic teams 408 * omp_set_max_active_levels:: Limits the number of active parallel regions 409 * omp_set_nested:: Enable/disable nested parallel regions 410 * omp_set_num_teams:: Set upper teams limit for teams region 411 * omp_set_num_threads:: Set upper team size limit 412 * omp_set_schedule:: Set the runtime scheduling method 413 * omp_set_teams_thread_limit:: Set upper thread limit for teams construct 414 415 Initialize, set, test, unset and destroy simple and nested locks. 416 417 * omp_init_lock:: Initialize simple lock 418 * omp_set_lock:: Wait for and set simple lock 419 * omp_test_lock:: Test and set simple lock if available 420 * omp_unset_lock:: Unset simple lock 421 * omp_destroy_lock:: Destroy simple lock 422 * omp_init_nest_lock:: Initialize nested lock 423 * omp_set_nest_lock:: Wait for and set simple lock 424 * omp_test_nest_lock:: Test and set nested lock if available 425 * omp_unset_nest_lock:: Unset nested lock 426 * omp_destroy_nest_lock:: Destroy nested lock 427 428 Portable, thread-based, wall clock timer. 429 430 * omp_get_wtick:: Get timer precision. 431 * omp_get_wtime:: Elapsed wall clock time. 432 433 Support for event objects. 434 435 * omp_fulfill_event:: Fulfill and destroy an OpenMP event. 436 437 438 File: libgomp.info, Node: omp_get_active_level, Next: omp_get_ancestor_thread_num, Up: Runtime Library Routines 439 440 3.1 'omp_get_active_level' - Number of parallel regions 441 ======================================================= 442 443 _Description_: 444 This function returns the nesting level for the active parallel 445 blocks, which enclose the calling call. 446 447 _C/C++_ 448 _Prototype_: 'int omp_get_active_level(void);' 449 450 _Fortran_: 451 _Interface_: 'integer function omp_get_active_level()' 452 453 _See also_: 454 *note omp_get_level::, *note omp_get_max_active_levels::, *note 455 omp_set_max_active_levels:: 456 457 _Reference_: 458 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.20. 459 460 461 File: libgomp.info, Node: omp_get_ancestor_thread_num, Next: omp_get_cancellation, Prev: omp_get_active_level, Up: Runtime Library Routines 462 463 3.2 'omp_get_ancestor_thread_num' - Ancestor thread ID 464 ====================================================== 465 466 _Description_: 467 This function returns the thread identification number for the 468 given nesting level of the current thread. For values of LEVEL 469 outside zero to 'omp_get_level' -1 is returned; if LEVEL is 470 'omp_get_level' the result is identical to 'omp_get_thread_num'. 471 472 _C/C++_ 473 _Prototype_: 'int omp_get_ancestor_thread_num(int level);' 474 475 _Fortran_: 476 _Interface_: 'integer function omp_get_ancestor_thread_num(level)' 477 'integer level' 478 479 _See also_: 480 *note omp_get_level::, *note omp_get_thread_num::, *note 481 omp_get_team_size:: 482 483 _Reference_: 484 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.18. 485 486 487 File: libgomp.info, Node: omp_get_cancellation, Next: omp_get_default_device, Prev: omp_get_ancestor_thread_num, Up: Runtime Library Routines 488 489 3.3 'omp_get_cancellation' - Whether cancellation support is enabled 490 ==================================================================== 491 492 _Description_: 493 This function returns 'true' if cancellation is activated, 'false' 494 otherwise. Here, 'true' and 'false' represent their 495 language-specific counterparts. Unless 'OMP_CANCELLATION' is set 496 true, cancellations are deactivated. 497 498 _C/C++_: 499 _Prototype_: 'int omp_get_cancellation(void);' 500 501 _Fortran_: 502 _Interface_: 'logical function omp_get_cancellation()' 503 504 _See also_: 505 *note OMP_CANCELLATION:: 506 507 _Reference_: 508 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.9. 509 510 511 File: libgomp.info, Node: omp_get_default_device, Next: omp_get_device_num, Prev: omp_get_cancellation, Up: Runtime Library Routines 512 513 3.4 'omp_get_default_device' - Get the default device for target regions 514 ======================================================================== 515 516 _Description_: 517 Get the default device for target regions without device clause. 518 519 _C/C++_: 520 _Prototype_: 'int omp_get_default_device(void);' 521 522 _Fortran_: 523 _Interface_: 'integer function omp_get_default_device()' 524 525 _See also_: 526 *note OMP_DEFAULT_DEVICE::, *note omp_set_default_device:: 527 528 _Reference_: 529 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.30. 530 531 532 File: libgomp.info, Node: omp_get_device_num, Next: omp_get_dynamic, Prev: omp_get_default_device, Up: Runtime Library Routines 533 534 3.5 'omp_get_device_num' - Return device number of current device 535 ================================================================= 536 537 _Description_: 538 This function returns a device number that represents the device 539 that the current thread is executing on. For OpenMP 5.0, this must 540 be equal to the value returned by the 'omp_get_initial_device' 541 function when called from the host. 542 543 _C/C++_ 544 _Prototype_: 'int omp_get_device_num(void);' 545 546 _Fortran_: 547 _Interface_: 'integer function omp_get_device_num()' 548 549 _See also_: 550 *note omp_get_initial_device:: 551 552 _Reference_: 553 OpenMP specification v5.0 (https://www.openmp.org), Section 3.2.37. 554 555 556 File: libgomp.info, Node: omp_get_dynamic, Next: omp_get_initial_device, Prev: omp_get_device_num, Up: Runtime Library Routines 557 558 3.6 'omp_get_dynamic' - Dynamic teams setting 559 ============================================= 560 561 _Description_: 562 This function returns 'true' if enabled, 'false' otherwise. Here, 563 'true' and 'false' represent their language-specific counterparts. 564 565 The dynamic team setting may be initialized at startup by the 566 'OMP_DYNAMIC' environment variable or at runtime using 567 'omp_set_dynamic'. If undefined, dynamic adjustment is disabled by 568 default. 569 570 _C/C++_: 571 _Prototype_: 'int omp_get_dynamic(void);' 572 573 _Fortran_: 574 _Interface_: 'logical function omp_get_dynamic()' 575 576 _See also_: 577 *note omp_set_dynamic::, *note OMP_DYNAMIC:: 578 579 _Reference_: 580 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.8. 581 582 583 File: libgomp.info, Node: omp_get_initial_device, Next: omp_get_level, Prev: omp_get_dynamic, Up: Runtime Library Routines 584 585 3.7 'omp_get_initial_device' - Return device number of initial device 586 ===================================================================== 587 588 _Description_: 589 This function returns a device number that represents the host 590 device. For OpenMP 5.1, this must be equal to the value returned 591 by the 'omp_get_num_devices' function. 592 593 _C/C++_ 594 _Prototype_: 'int omp_get_initial_device(void);' 595 596 _Fortran_: 597 _Interface_: 'integer function omp_get_initial_device()' 598 599 _See also_: 600 *note omp_get_num_devices:: 601 602 _Reference_: 603 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.35. 604 605 606 File: libgomp.info, Node: omp_get_level, Next: omp_get_max_active_levels, Prev: omp_get_initial_device, Up: Runtime Library Routines 607 608 3.8 'omp_get_level' - Obtain the current nesting level 609 ====================================================== 610 611 _Description_: 612 This function returns the nesting level for the parallel blocks, 613 which enclose the calling call. 614 615 _C/C++_ 616 _Prototype_: 'int omp_get_level(void);' 617 618 _Fortran_: 619 _Interface_: 'integer function omp_level()' 620 621 _See also_: 622 *note omp_get_active_level:: 623 624 _Reference_: 625 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.17. 626 627 628 File: libgomp.info, Node: omp_get_max_active_levels, Next: omp_get_max_task_priority, Prev: omp_get_level, Up: Runtime Library Routines 629 630 3.9 'omp_get_max_active_levels' - Current maximum number of active regions 631 ========================================================================== 632 633 _Description_: 634 This function obtains the maximum allowed number of nested, active 635 parallel regions. 636 637 _C/C++_ 638 _Prototype_: 'int omp_get_max_active_levels(void);' 639 640 _Fortran_: 641 _Interface_: 'integer function omp_get_max_active_levels()' 642 643 _See also_: 644 *note omp_set_max_active_levels::, *note omp_get_active_level:: 645 646 _Reference_: 647 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.16. 648 649 650 File: libgomp.info, Node: omp_get_max_task_priority, Next: omp_get_max_teams, Prev: omp_get_max_active_levels, Up: Runtime Library Routines 651 652 3.10 'omp_get_max_task_priority' - Maximum priority value 653 ========================================================= 654 655 that can be set for tasks. 656 _Description_: 657 This function obtains the maximum allowed priority number for 658 tasks. 659 660 _C/C++_ 661 _Prototype_: 'int omp_get_max_task_priority(void);' 662 663 _Fortran_: 664 _Interface_: 'integer function omp_get_max_task_priority()' 665 666 _Reference_: 667 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.29. 668 669 670 File: libgomp.info, Node: omp_get_max_teams, Next: omp_get_max_threads, Prev: omp_get_max_task_priority, Up: Runtime Library Routines 671 672 3.11 'omp_get_max_teams' - Maximum number of teams of teams region 673 ================================================================== 674 675 _Description_: 676 Return the maximum number of teams used for the teams region that 677 does not use the clause 'num_teams'. 678 679 _C/C++_: 680 _Prototype_: 'int omp_get_max_teams(void);' 681 682 _Fortran_: 683 _Interface_: 'integer function omp_get_max_teams()' 684 685 _See also_: 686 *note omp_set_num_teams::, *note omp_get_num_teams:: 687 688 _Reference_: 689 OpenMP specification v5.1 (https://www.openmp.org), Section 3.4.4. 690 691 692 File: libgomp.info, Node: omp_get_max_threads, Next: omp_get_nested, Prev: omp_get_max_teams, Up: Runtime Library Routines 693 694 3.12 'omp_get_max_threads' - Maximum number of threads of parallel region 695 ========================================================================= 696 697 _Description_: 698 Return the maximum number of threads used for the current parallel 699 region that does not use the clause 'num_threads'. 700 701 _C/C++_: 702 _Prototype_: 'int omp_get_max_threads(void);' 703 704 _Fortran_: 705 _Interface_: 'integer function omp_get_max_threads()' 706 707 _See also_: 708 *note omp_set_num_threads::, *note omp_set_dynamic::, *note 709 omp_get_thread_limit:: 710 711 _Reference_: 712 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.3. 713 714 715 File: libgomp.info, Node: omp_get_nested, Next: omp_get_num_devices, Prev: omp_get_max_threads, Up: Runtime Library Routines 716 717 3.13 'omp_get_nested' - Nested parallel regions 718 =============================================== 719 720 _Description_: 721 This function returns 'true' if nested parallel regions are 722 enabled, 'false' otherwise. Here, 'true' and 'false' represent 723 their language-specific counterparts. 724 725 The state of nested parallel regions at startup depends on several 726 environment variables. If 'OMP_MAX_ACTIVE_LEVELS' is defined and 727 is set to greater than one, then nested parallel regions will be 728 enabled. If not defined, then the value of the 'OMP_NESTED' 729 environment variable will be followed if defined. If neither are 730 defined, then if either 'OMP_NUM_THREADS' or 'OMP_PROC_BIND' are 731 defined with a list of more than one value, then nested parallel 732 regions are enabled. If none of these are defined, then nested 733 parallel regions are disabled by default. 734 735 Nested parallel regions can be enabled or disabled at runtime using 736 'omp_set_nested', or by setting the maximum number of nested 737 regions with 'omp_set_max_active_levels' to one to disable, or 738 above one to enable. 739 740 _C/C++_: 741 _Prototype_: 'int omp_get_nested(void);' 742 743 _Fortran_: 744 _Interface_: 'logical function omp_get_nested()' 745 746 _See also_: 747 *note omp_set_max_active_levels::, *note omp_set_nested::, *note 748 OMP_MAX_ACTIVE_LEVELS::, *note OMP_NESTED:: 749 750 _Reference_: 751 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.11. 752 753 754 File: libgomp.info, Node: omp_get_num_devices, Next: omp_get_num_procs, Prev: omp_get_nested, Up: Runtime Library Routines 755 756 3.14 'omp_get_num_devices' - Number of target devices 757 ===================================================== 758 759 _Description_: 760 Returns the number of target devices. 761 762 _C/C++_: 763 _Prototype_: 'int omp_get_num_devices(void);' 764 765 _Fortran_: 766 _Interface_: 'integer function omp_get_num_devices()' 767 768 _Reference_: 769 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.31. 770 771 772 File: libgomp.info, Node: omp_get_num_procs, Next: omp_get_num_teams, Prev: omp_get_num_devices, Up: Runtime Library Routines 773 774 3.15 'omp_get_num_procs' - Number of processors online 775 ====================================================== 776 777 _Description_: 778 Returns the number of processors online on that device. 779 780 _C/C++_: 781 _Prototype_: 'int omp_get_num_procs(void);' 782 783 _Fortran_: 784 _Interface_: 'integer function omp_get_num_procs()' 785 786 _Reference_: 787 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.5. 788 789 790 File: libgomp.info, Node: omp_get_num_teams, Next: omp_get_num_threads, Prev: omp_get_num_procs, Up: Runtime Library Routines 791 792 3.16 'omp_get_num_teams' - Number of teams 793 ========================================== 794 795 _Description_: 796 Returns the number of teams in the current team region. 797 798 _C/C++_: 799 _Prototype_: 'int omp_get_num_teams(void);' 800 801 _Fortran_: 802 _Interface_: 'integer function omp_get_num_teams()' 803 804 _Reference_: 805 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.32. 806 807 808 File: libgomp.info, Node: omp_get_num_threads, Next: omp_get_proc_bind, Prev: omp_get_num_teams, Up: Runtime Library Routines 809 810 3.17 'omp_get_num_threads' - Size of the active team 811 ==================================================== 812 813 _Description_: 814 Returns the number of threads in the current team. In a sequential 815 section of the program 'omp_get_num_threads' returns 1. 816 817 The default team size may be initialized at startup by the 818 'OMP_NUM_THREADS' environment variable. At runtime, the size of 819 the current team may be set either by the 'NUM_THREADS' clause or 820 by 'omp_set_num_threads'. If none of the above were used to define 821 a specific value and 'OMP_DYNAMIC' is disabled, one thread per CPU 822 online is used. 823 824 _C/C++_: 825 _Prototype_: 'int omp_get_num_threads(void);' 826 827 _Fortran_: 828 _Interface_: 'integer function omp_get_num_threads()' 829 830 _See also_: 831 *note omp_get_max_threads::, *note omp_set_num_threads::, *note 832 OMP_NUM_THREADS:: 833 834 _Reference_: 835 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.2. 836 837 838 File: libgomp.info, Node: omp_get_proc_bind, Next: omp_get_schedule, Prev: omp_get_num_threads, Up: Runtime Library Routines 839 840 3.18 'omp_get_proc_bind' - Whether threads may be moved between CPUs 841 ==================================================================== 842 843 _Description_: 844 This functions returns the currently active thread affinity policy, 845 which is set via 'OMP_PROC_BIND'. Possible values are 846 'omp_proc_bind_false', 'omp_proc_bind_true', 847 'omp_proc_bind_primary', 'omp_proc_bind_master', 848 'omp_proc_bind_close' and 'omp_proc_bind_spread', where 849 'omp_proc_bind_master' is an alias for 'omp_proc_bind_primary'. 850 851 _C/C++_: 852 _Prototype_: 'omp_proc_bind_t omp_get_proc_bind(void);' 853 854 _Fortran_: 855 _Interface_: 'integer(kind=omp_proc_bind_kind) function 856 omp_get_proc_bind()' 857 858 _See also_: 859 *note OMP_PROC_BIND::, *note OMP_PLACES::, *note 860 GOMP_CPU_AFFINITY::, 861 862 _Reference_: 863 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.22. 864 865 866 File: libgomp.info, Node: omp_get_schedule, Next: omp_get_supported_active_levels, Prev: omp_get_proc_bind, Up: Runtime Library Routines 867 868 3.19 'omp_get_schedule' - Obtain the runtime scheduling method 869 ============================================================== 870 871 _Description_: 872 Obtain the runtime scheduling method. The KIND argument will be 873 set to the value 'omp_sched_static', 'omp_sched_dynamic', 874 'omp_sched_guided' or 'omp_sched_auto'. The second argument, 875 CHUNK_SIZE, is set to the chunk size. 876 877 _C/C++_ 878 _Prototype_: 'void omp_get_schedule(omp_sched_t *kind, int 879 *chunk_size);' 880 881 _Fortran_: 882 _Interface_: 'subroutine omp_get_schedule(kind, chunk_size)' 883 'integer(kind=omp_sched_kind) kind' 884 'integer chunk_size' 885 886 _See also_: 887 *note omp_set_schedule::, *note OMP_SCHEDULE:: 888 889 _Reference_: 890 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.13. 891 892 893 File: libgomp.info, Node: omp_get_supported_active_levels, Next: omp_get_team_num, Prev: omp_get_schedule, Up: Runtime Library Routines 894 895 3.20 'omp_get_supported_active_levels' - Maximum number of active regions supported 896 =================================================================================== 897 898 _Description_: 899 This function returns the maximum number of nested, active parallel 900 regions supported by this implementation. 901 902 _C/C++_ 903 _Prototype_: 'int omp_get_supported_active_levels(void);' 904 905 _Fortran_: 906 _Interface_: 'integer function omp_get_supported_active_levels()' 907 908 _See also_: 909 *note omp_get_max_active_levels::, *note 910 omp_set_max_active_levels:: 911 912 _Reference_: 913 OpenMP specification v5.0 (https://www.openmp.org), Section 3.2.15. 914 915 916 File: libgomp.info, Node: omp_get_team_num, Next: omp_get_team_size, Prev: omp_get_supported_active_levels, Up: Runtime Library Routines 917 918 3.21 'omp_get_team_num' - Get team number 919 ========================================= 920 921 _Description_: 922 Returns the team number of the calling thread. 923 924 _C/C++_: 925 _Prototype_: 'int omp_get_team_num(void);' 926 927 _Fortran_: 928 _Interface_: 'integer function omp_get_team_num()' 929 930 _Reference_: 931 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.33. 932 933 934 File: libgomp.info, Node: omp_get_team_size, Next: omp_get_teams_thread_limit, Prev: omp_get_team_num, Up: Runtime Library Routines 935 936 3.22 'omp_get_team_size' - Number of threads in a team 937 ====================================================== 938 939 _Description_: 940 This function returns the number of threads in a thread team to 941 which either the current thread or its ancestor belongs. For 942 values of LEVEL outside zero to 'omp_get_level', -1 is returned; if 943 LEVEL is zero, 1 is returned, and for 'omp_get_level', the result 944 is identical to 'omp_get_num_threads'. 945 946 _C/C++_: 947 _Prototype_: 'int omp_get_team_size(int level);' 948 949 _Fortran_: 950 _Interface_: 'integer function omp_get_team_size(level)' 951 'integer level' 952 953 _See also_: 954 *note omp_get_num_threads::, *note omp_get_level::, *note 955 omp_get_ancestor_thread_num:: 956 957 _Reference_: 958 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.19. 959 960 961 File: libgomp.info, Node: omp_get_teams_thread_limit, Next: omp_get_thread_limit, Prev: omp_get_team_size, Up: Runtime Library Routines 962 963 3.23 'omp_get_teams_thread_limit' - Maximum number of threads imposed by teams 964 ============================================================================== 965 966 _Description_: 967 Return the maximum number of threads that will be able to 968 participate in each team created by a teams construct. 969 970 _C/C++_: 971 _Prototype_: 'int omp_get_teams_thread_limit(void);' 972 973 _Fortran_: 974 _Interface_: 'integer function omp_get_teams_thread_limit()' 975 976 _See also_: 977 *note omp_set_teams_thread_limit::, *note OMP_TEAMS_THREAD_LIMIT:: 978 979 _Reference_: 980 OpenMP specification v5.1 (https://www.openmp.org), Section 3.4.6. 981 982 983 File: libgomp.info, Node: omp_get_thread_limit, Next: omp_get_thread_num, Prev: omp_get_teams_thread_limit, Up: Runtime Library Routines 984 985 3.24 'omp_get_thread_limit' - Maximum number of threads 986 ======================================================= 987 988 _Description_: 989 Return the maximum number of threads of the program. 990 991 _C/C++_: 992 _Prototype_: 'int omp_get_thread_limit(void);' 993 994 _Fortran_: 995 _Interface_: 'integer function omp_get_thread_limit()' 996 997 _See also_: 998 *note omp_get_max_threads::, *note OMP_THREAD_LIMIT:: 999 1000 _Reference_: 1001 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.14. 1002 1003 1004 File: libgomp.info, Node: omp_get_thread_num, Next: omp_in_parallel, Prev: omp_get_thread_limit, Up: Runtime Library Routines 1005 1006 3.25 'omp_get_thread_num' - Current thread ID 1007 ============================================= 1008 1009 _Description_: 1010 Returns a unique thread identification number within the current 1011 team. In a sequential parts of the program, 'omp_get_thread_num' 1012 always returns 0. In parallel regions the return value varies from 1013 0 to 'omp_get_num_threads'-1 inclusive. The return value of the 1014 primary thread of a team is always 0. 1015 1016 _C/C++_: 1017 _Prototype_: 'int omp_get_thread_num(void);' 1018 1019 _Fortran_: 1020 _Interface_: 'integer function omp_get_thread_num()' 1021 1022 _See also_: 1023 *note omp_get_num_threads::, *note omp_get_ancestor_thread_num:: 1024 1025 _Reference_: 1026 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.4. 1027 1028 1029 File: libgomp.info, Node: omp_in_parallel, Next: omp_in_final, Prev: omp_get_thread_num, Up: Runtime Library Routines 1030 1031 3.26 'omp_in_parallel' - Whether a parallel region is active 1032 ============================================================ 1033 1034 _Description_: 1035 This function returns 'true' if currently running in parallel, 1036 'false' otherwise. Here, 'true' and 'false' represent their 1037 language-specific counterparts. 1038 1039 _C/C++_: 1040 _Prototype_: 'int omp_in_parallel(void);' 1041 1042 _Fortran_: 1043 _Interface_: 'logical function omp_in_parallel()' 1044 1045 _Reference_: 1046 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.6. 1047 1048 1049 File: libgomp.info, Node: omp_in_final, Next: omp_is_initial_device, Prev: omp_in_parallel, Up: Runtime Library Routines 1050 1051 3.27 'omp_in_final' - Whether in final or included task region 1052 ============================================================== 1053 1054 _Description_: 1055 This function returns 'true' if currently running in a final or 1056 included task region, 'false' otherwise. Here, 'true' and 'false' 1057 represent their language-specific counterparts. 1058 1059 _C/C++_: 1060 _Prototype_: 'int omp_in_final(void);' 1061 1062 _Fortran_: 1063 _Interface_: 'logical function omp_in_final()' 1064 1065 _Reference_: 1066 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.21. 1067 1068 1069 File: libgomp.info, Node: omp_is_initial_device, Next: omp_set_default_device, Prev: omp_in_final, Up: Runtime Library Routines 1070 1071 3.28 'omp_is_initial_device' - Whether executing on the host device 1072 =================================================================== 1073 1074 _Description_: 1075 This function returns 'true' if currently running on the host 1076 device, 'false' otherwise. Here, 'true' and 'false' represent 1077 their language-specific counterparts. 1078 1079 _C/C++_: 1080 _Prototype_: 'int omp_is_initial_device(void);' 1081 1082 _Fortran_: 1083 _Interface_: 'logical function omp_is_initial_device()' 1084 1085 _Reference_: 1086 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.34. 1087 1088 1089 File: libgomp.info, Node: omp_set_default_device, Next: omp_set_dynamic, Prev: omp_is_initial_device, Up: Runtime Library Routines 1090 1091 3.29 'omp_set_default_device' - Set the default device for target regions 1092 ========================================================================= 1093 1094 _Description_: 1095 Set the default device for target regions without device clause. 1096 The argument shall be a nonnegative device number. 1097 1098 _C/C++_: 1099 _Prototype_: 'void omp_set_default_device(int device_num);' 1100 1101 _Fortran_: 1102 _Interface_: 'subroutine omp_set_default_device(device_num)' 1103 'integer device_num' 1104 1105 _See also_: 1106 *note OMP_DEFAULT_DEVICE::, *note omp_get_default_device:: 1107 1108 _Reference_: 1109 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.29. 1110 1111 1112 File: libgomp.info, Node: omp_set_dynamic, Next: omp_set_max_active_levels, Prev: omp_set_default_device, Up: Runtime Library Routines 1113 1114 3.30 'omp_set_dynamic' - Enable/disable dynamic teams 1115 ===================================================== 1116 1117 _Description_: 1118 Enable or disable the dynamic adjustment of the number of threads 1119 within a team. The function takes the language-specific equivalent 1120 of 'true' and 'false', where 'true' enables dynamic adjustment of 1121 team sizes and 'false' disables it. 1122 1123 _C/C++_: 1124 _Prototype_: 'void omp_set_dynamic(int dynamic_threads);' 1125 1126 _Fortran_: 1127 _Interface_: 'subroutine omp_set_dynamic(dynamic_threads)' 1128 'logical, intent(in) :: dynamic_threads' 1129 1130 _See also_: 1131 *note OMP_DYNAMIC::, *note omp_get_dynamic:: 1132 1133 _Reference_: 1134 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.7. 1135 1136 1137 File: libgomp.info, Node: omp_set_max_active_levels, Next: omp_set_nested, Prev: omp_set_dynamic, Up: Runtime Library Routines 1138 1139 3.31 'omp_set_max_active_levels' - Limits the number of active parallel regions 1140 =============================================================================== 1141 1142 _Description_: 1143 This function limits the maximum allowed number of nested, active 1144 parallel regions. MAX_LEVELS must be less or equal to the value 1145 returned by 'omp_get_supported_active_levels'. 1146 1147 _C/C++_ 1148 _Prototype_: 'void omp_set_max_active_levels(int max_levels);' 1149 1150 _Fortran_: 1151 _Interface_: 'subroutine omp_set_max_active_levels(max_levels)' 1152 'integer max_levels' 1153 1154 _See also_: 1155 *note omp_get_max_active_levels::, *note omp_get_active_level::, 1156 *note omp_get_supported_active_levels:: 1157 1158 _Reference_: 1159 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.15. 1160 1161 1162 File: libgomp.info, Node: omp_set_nested, Next: omp_set_num_teams, Prev: omp_set_max_active_levels, Up: Runtime Library Routines 1163 1164 3.32 'omp_set_nested' - Enable/disable nested parallel regions 1165 ============================================================== 1166 1167 _Description_: 1168 Enable or disable nested parallel regions, i.e., whether team 1169 members are allowed to create new teams. The function takes the 1170 language-specific equivalent of 'true' and 'false', where 'true' 1171 enables dynamic adjustment of team sizes and 'false' disables it. 1172 1173 Enabling nested parallel regions will also set the maximum number 1174 of active nested regions to the maximum supported. Disabling 1175 nested parallel regions will set the maximum number of active 1176 nested regions to one. 1177 1178 _C/C++_: 1179 _Prototype_: 'void omp_set_nested(int nested);' 1180 1181 _Fortran_: 1182 _Interface_: 'subroutine omp_set_nested(nested)' 1183 'logical, intent(in) :: nested' 1184 1185 _See also_: 1186 *note omp_get_nested::, *note omp_set_max_active_levels::, *note 1187 OMP_MAX_ACTIVE_LEVELS::, *note OMP_NESTED:: 1188 1189 _Reference_: 1190 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.10. 1191 1192 1193 File: libgomp.info, Node: omp_set_num_teams, Next: omp_set_num_threads, Prev: omp_set_nested, Up: Runtime Library Routines 1194 1195 3.33 'omp_set_num_teams' - Set upper teams limit for teams construct 1196 ==================================================================== 1197 1198 _Description_: 1199 Specifies the upper bound for number of teams created by the teams 1200 construct which does not specify a 'num_teams' clause. The 1201 argument of 'omp_set_num_teams' shall be a positive integer. 1202 1203 _C/C++_: 1204 _Prototype_: 'void omp_set_num_teams(int num_teams);' 1205 1206 _Fortran_: 1207 _Interface_: 'subroutine omp_set_num_teams(num_teams)' 1208 'integer, intent(in) :: num_teams' 1209 1210 _See also_: 1211 *note OMP_NUM_TEAMS::, *note omp_get_num_teams::, *note 1212 omp_get_max_teams:: 1213 1214 _Reference_: 1215 OpenMP specification v5.1 (https://www.openmp.org), Section 3.4.3. 1216 1217 1218 File: libgomp.info, Node: omp_set_num_threads, Next: omp_set_schedule, Prev: omp_set_num_teams, Up: Runtime Library Routines 1219 1220 3.34 'omp_set_num_threads' - Set upper team size limit 1221 ====================================================== 1222 1223 _Description_: 1224 Specifies the number of threads used by default in subsequent 1225 parallel sections, if those do not specify a 'num_threads' clause. 1226 The argument of 'omp_set_num_threads' shall be a positive integer. 1227 1228 _C/C++_: 1229 _Prototype_: 'void omp_set_num_threads(int num_threads);' 1230 1231 _Fortran_: 1232 _Interface_: 'subroutine omp_set_num_threads(num_threads)' 1233 'integer, intent(in) :: num_threads' 1234 1235 _See also_: 1236 *note OMP_NUM_THREADS::, *note omp_get_num_threads::, *note 1237 omp_get_max_threads:: 1238 1239 _Reference_: 1240 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.1. 1241 1242 1243 File: libgomp.info, Node: omp_set_schedule, Next: omp_set_teams_thread_limit, Prev: omp_set_num_threads, Up: Runtime Library Routines 1244 1245 3.35 'omp_set_schedule' - Set the runtime scheduling method 1246 =========================================================== 1247 1248 _Description_: 1249 Sets the runtime scheduling method. The KIND argument can have the 1250 value 'omp_sched_static', 'omp_sched_dynamic', 'omp_sched_guided' 1251 or 'omp_sched_auto'. Except for 'omp_sched_auto', the chunk size 1252 is set to the value of CHUNK_SIZE if positive, or to the default 1253 value if zero or negative. For 'omp_sched_auto' the CHUNK_SIZE 1254 argument is ignored. 1255 1256 _C/C++_ 1257 _Prototype_: 'void omp_set_schedule(omp_sched_t kind, int 1258 chunk_size);' 1259 1260 _Fortran_: 1261 _Interface_: 'subroutine omp_set_schedule(kind, chunk_size)' 1262 'integer(kind=omp_sched_kind) kind' 1263 'integer chunk_size' 1264 1265 _See also_: 1266 *note omp_get_schedule:: *note OMP_SCHEDULE:: 1267 1268 _Reference_: 1269 OpenMP specification v4.5 (https://www.openmp.org), Section 3.2.12. 1270 1271 1272 File: libgomp.info, Node: omp_set_teams_thread_limit, Next: omp_init_lock, Prev: omp_set_schedule, Up: Runtime Library Routines 1273 1274 3.36 'omp_set_teams_thread_limit' - Set upper thread limit for teams construct 1275 ============================================================================== 1276 1277 _Description_: 1278 Specifies the upper bound for number of threads that will be 1279 available for each team created by the teams construct which does 1280 not specify a 'thread_limit' clause. The argument of 1281 'omp_set_teams_thread_limit' shall be a positive integer. 1282 1283 _C/C++_: 1284 _Prototype_: 'void omp_set_teams_thread_limit(int thread_limit);' 1285 1286 _Fortran_: 1287 _Interface_: 'subroutine omp_set_teams_thread_limit(thread_limit)' 1288 'integer, intent(in) :: thread_limit' 1289 1290 _See also_: 1291 *note OMP_TEAMS_THREAD_LIMIT::, *note omp_get_teams_thread_limit::, 1292 *note omp_get_thread_limit:: 1293 1294 _Reference_: 1295 OpenMP specification v5.1 (https://www.openmp.org), Section 3.4.5. 1296 1297 1298 File: libgomp.info, Node: omp_init_lock, Next: omp_set_lock, Prev: omp_set_teams_thread_limit, Up: Runtime Library Routines 1299 1300 3.37 'omp_init_lock' - Initialize simple lock 1301 ============================================= 1302 1303 _Description_: 1304 Initialize a simple lock. After initialization, the lock is in an 1305 unlocked state. 1306 1307 _C/C++_: 1308 _Prototype_: 'void omp_init_lock(omp_lock_t *lock);' 1309 1310 _Fortran_: 1311 _Interface_: 'subroutine omp_init_lock(svar)' 1312 'integer(omp_lock_kind), intent(out) :: svar' 1313 1314 _See also_: 1315 *note omp_destroy_lock:: 1316 1317 _Reference_: 1318 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.1. 1319 1320 1321 File: libgomp.info, Node: omp_set_lock, Next: omp_test_lock, Prev: omp_init_lock, Up: Runtime Library Routines 1322 1323 3.38 'omp_set_lock' - Wait for and set simple lock 1324 ================================================== 1325 1326 _Description_: 1327 Before setting a simple lock, the lock variable must be initialized 1328 by 'omp_init_lock'. The calling thread is blocked until the lock 1329 is available. If the lock is already held by the current thread, a 1330 deadlock occurs. 1331 1332 _C/C++_: 1333 _Prototype_: 'void omp_set_lock(omp_lock_t *lock);' 1334 1335 _Fortran_: 1336 _Interface_: 'subroutine omp_set_lock(svar)' 1337 'integer(omp_lock_kind), intent(inout) :: svar' 1338 1339 _See also_: 1340 *note omp_init_lock::, *note omp_test_lock::, *note 1341 omp_unset_lock:: 1342 1343 _Reference_: 1344 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.4. 1345 1346 1347 File: libgomp.info, Node: omp_test_lock, Next: omp_unset_lock, Prev: omp_set_lock, Up: Runtime Library Routines 1348 1349 3.39 'omp_test_lock' - Test and set simple lock if available 1350 ============================================================ 1351 1352 _Description_: 1353 Before setting a simple lock, the lock variable must be initialized 1354 by 'omp_init_lock'. Contrary to 'omp_set_lock', 'omp_test_lock' 1355 does not block if the lock is not available. This function returns 1356 'true' upon success, 'false' otherwise. Here, 'true' and 'false' 1357 represent their language-specific counterparts. 1358 1359 _C/C++_: 1360 _Prototype_: 'int omp_test_lock(omp_lock_t *lock);' 1361 1362 _Fortran_: 1363 _Interface_: 'logical function omp_test_lock(svar)' 1364 'integer(omp_lock_kind), intent(inout) :: svar' 1365 1366 _See also_: 1367 *note omp_init_lock::, *note omp_set_lock::, *note omp_set_lock:: 1368 1369 _Reference_: 1370 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.6. 1371 1372 1373 File: libgomp.info, Node: omp_unset_lock, Next: omp_destroy_lock, Prev: omp_test_lock, Up: Runtime Library Routines 1374 1375 3.40 'omp_unset_lock' - Unset simple lock 1376 ========================================= 1377 1378 _Description_: 1379 A simple lock about to be unset must have been locked by 1380 'omp_set_lock' or 'omp_test_lock' before. In addition, the lock 1381 must be held by the thread calling 'omp_unset_lock'. Then, the 1382 lock becomes unlocked. If one or more threads attempted to set the 1383 lock before, one of them is chosen to, again, set the lock to 1384 itself. 1385 1386 _C/C++_: 1387 _Prototype_: 'void omp_unset_lock(omp_lock_t *lock);' 1388 1389 _Fortran_: 1390 _Interface_: 'subroutine omp_unset_lock(svar)' 1391 'integer(omp_lock_kind), intent(inout) :: svar' 1392 1393 _See also_: 1394 *note omp_set_lock::, *note omp_test_lock:: 1395 1396 _Reference_: 1397 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.5. 1398 1399 1400 File: libgomp.info, Node: omp_destroy_lock, Next: omp_init_nest_lock, Prev: omp_unset_lock, Up: Runtime Library Routines 1401 1402 3.41 'omp_destroy_lock' - Destroy simple lock 1403 ============================================= 1404 1405 _Description_: 1406 Destroy a simple lock. In order to be destroyed, a simple lock 1407 must be in the unlocked state. 1408 1409 _C/C++_: 1410 _Prototype_: 'void omp_destroy_lock(omp_lock_t *lock);' 1411 1412 _Fortran_: 1413 _Interface_: 'subroutine omp_destroy_lock(svar)' 1414 'integer(omp_lock_kind), intent(inout) :: svar' 1415 1416 _See also_: 1417 *note omp_init_lock:: 1418 1419 _Reference_: 1420 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.3. 1421 1422 1423 File: libgomp.info, Node: omp_init_nest_lock, Next: omp_set_nest_lock, Prev: omp_destroy_lock, Up: Runtime Library Routines 1424 1425 3.42 'omp_init_nest_lock' - Initialize nested lock 1426 ================================================== 1427 1428 _Description_: 1429 Initialize a nested lock. After initialization, the lock is in an 1430 unlocked state and the nesting count is set to zero. 1431 1432 _C/C++_: 1433 _Prototype_: 'void omp_init_nest_lock(omp_nest_lock_t *lock);' 1434 1435 _Fortran_: 1436 _Interface_: 'subroutine omp_init_nest_lock(nvar)' 1437 'integer(omp_nest_lock_kind), intent(out) :: nvar' 1438 1439 _See also_: 1440 *note omp_destroy_nest_lock:: 1441 1442 _Reference_: 1443 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.1. 1444 1445 1446 File: libgomp.info, Node: omp_set_nest_lock, Next: omp_test_nest_lock, Prev: omp_init_nest_lock, Up: Runtime Library Routines 1447 1448 3.43 'omp_set_nest_lock' - Wait for and set nested lock 1449 ======================================================= 1450 1451 _Description_: 1452 Before setting a nested lock, the lock variable must be initialized 1453 by 'omp_init_nest_lock'. The calling thread is blocked until the 1454 lock is available. If the lock is already held by the current 1455 thread, the nesting count for the lock is incremented. 1456 1457 _C/C++_: 1458 _Prototype_: 'void omp_set_nest_lock(omp_nest_lock_t *lock);' 1459 1460 _Fortran_: 1461 _Interface_: 'subroutine omp_set_nest_lock(nvar)' 1462 'integer(omp_nest_lock_kind), intent(inout) :: nvar' 1463 1464 _See also_: 1465 *note omp_init_nest_lock::, *note omp_unset_nest_lock:: 1466 1467 _Reference_: 1468 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.4. 1469 1470 1471 File: libgomp.info, Node: omp_test_nest_lock, Next: omp_unset_nest_lock, Prev: omp_set_nest_lock, Up: Runtime Library Routines 1472 1473 3.44 'omp_test_nest_lock' - Test and set nested lock if available 1474 ================================================================= 1475 1476 _Description_: 1477 Before setting a nested lock, the lock variable must be initialized 1478 by 'omp_init_nest_lock'. Contrary to 'omp_set_nest_lock', 1479 'omp_test_nest_lock' does not block if the lock is not available. 1480 If the lock is already held by the current thread, the new nesting 1481 count is returned. Otherwise, the return value equals zero. 1482 1483 _C/C++_: 1484 _Prototype_: 'int omp_test_nest_lock(omp_nest_lock_t *lock);' 1485 1486 _Fortran_: 1487 _Interface_: 'logical function omp_test_nest_lock(nvar)' 1488 'integer(omp_nest_lock_kind), intent(inout) :: nvar' 1489 1490 _See also_: 1491 *note omp_init_lock::, *note omp_set_lock::, *note omp_set_lock:: 1492 1493 _Reference_: 1494 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.6. 1495 1496 1497 File: libgomp.info, Node: omp_unset_nest_lock, Next: omp_destroy_nest_lock, Prev: omp_test_nest_lock, Up: Runtime Library Routines 1498 1499 3.45 'omp_unset_nest_lock' - Unset nested lock 1500 ============================================== 1501 1502 _Description_: 1503 A nested lock about to be unset must have been locked by 1504 'omp_set_nested_lock' or 'omp_test_nested_lock' before. In 1505 addition, the lock must be held by the thread calling 1506 'omp_unset_nested_lock'. If the nesting count drops to zero, the 1507 lock becomes unlocked. If one ore more threads attempted to set 1508 the lock before, one of them is chosen to, again, set the lock to 1509 itself. 1510 1511 _C/C++_: 1512 _Prototype_: 'void omp_unset_nest_lock(omp_nest_lock_t *lock);' 1513 1514 _Fortran_: 1515 _Interface_: 'subroutine omp_unset_nest_lock(nvar)' 1516 'integer(omp_nest_lock_kind), intent(inout) :: nvar' 1517 1518 _See also_: 1519 *note omp_set_nest_lock:: 1520 1521 _Reference_: 1522 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.5. 1523 1524 1525 File: libgomp.info, Node: omp_destroy_nest_lock, Next: omp_get_wtick, Prev: omp_unset_nest_lock, Up: Runtime Library Routines 1526 1527 3.46 'omp_destroy_nest_lock' - Destroy nested lock 1528 ================================================== 1529 1530 _Description_: 1531 Destroy a nested lock. In order to be destroyed, a nested lock 1532 must be in the unlocked state and its nesting count must equal 1533 zero. 1534 1535 _C/C++_: 1536 _Prototype_: 'void omp_destroy_nest_lock(omp_nest_lock_t *);' 1537 1538 _Fortran_: 1539 _Interface_: 'subroutine omp_destroy_nest_lock(nvar)' 1540 'integer(omp_nest_lock_kind), intent(inout) :: nvar' 1541 1542 _See also_: 1543 *note omp_init_lock:: 1544 1545 _Reference_: 1546 OpenMP specification v4.5 (https://www.openmp.org), Section 3.3.3. 1547 1548 1549 File: libgomp.info, Node: omp_get_wtick, Next: omp_get_wtime, Prev: omp_destroy_nest_lock, Up: Runtime Library Routines 1550 1551 3.47 'omp_get_wtick' - Get timer precision 1552 ========================================== 1553 1554 _Description_: 1555 Gets the timer precision, i.e., the number of seconds between two 1556 successive clock ticks. 1557 1558 _C/C++_: 1559 _Prototype_: 'double omp_get_wtick(void);' 1560 1561 _Fortran_: 1562 _Interface_: 'double precision function omp_get_wtick()' 1563 1564 _See also_: 1565 *note omp_get_wtime:: 1566 1567 _Reference_: 1568 OpenMP specification v4.5 (https://www.openmp.org), Section 3.4.2. 1569 1570 1571 File: libgomp.info, Node: omp_get_wtime, Next: omp_fulfill_event, Prev: omp_get_wtick, Up: Runtime Library Routines 1572 1573 3.48 'omp_get_wtime' - Elapsed wall clock time 1574 ============================================== 1575 1576 _Description_: 1577 Elapsed wall clock time in seconds. The time is measured per 1578 thread, no guarantee can be made that two distinct threads measure 1579 the same time. Time is measured from some "time in the past", 1580 which is an arbitrary time guaranteed not to change during the 1581 execution of the program. 1582 1583 _C/C++_: 1584 _Prototype_: 'double omp_get_wtime(void);' 1585 1586 _Fortran_: 1587 _Interface_: 'double precision function omp_get_wtime()' 1588 1589 _See also_: 1590 *note omp_get_wtick:: 1591 1592 _Reference_: 1593 OpenMP specification v4.5 (https://www.openmp.org), Section 3.4.1. 1594 1595 1596 File: libgomp.info, Node: omp_fulfill_event, Prev: omp_get_wtime, Up: Runtime Library Routines 1597 1598 3.49 'omp_fulfill_event' - Fulfill and destroy an OpenMP event 1599 ============================================================== 1600 1601 _Description_: 1602 Fulfill the event associated with the event handle argument. 1603 Currently, it is only used to fulfill events generated by detach 1604 clauses on task constructs - the effect of fulfilling the event is 1605 to allow the task to complete. 1606 1607 The result of calling 'omp_fulfill_event' with an event handle 1608 other than that generated by a detach clause is undefined. Calling 1609 it with an event handle that has already been fulfilled is also 1610 undefined. 1611 1612 _C/C++_: 1613 _Prototype_: 'void omp_fulfill_event(omp_event_handle_t event);' 1614 1615 _Fortran_: 1616 _Interface_: 'subroutine omp_fulfill_event(event)' 1617 'integer (kind=omp_event_handle_kind) :: event' 1618 1619 _Reference_: 1620 OpenMP specification v5.0 (https://www.openmp.org), Section 3.5.1. 1621 1622 1623 File: libgomp.info, Node: Environment Variables, Next: Enabling OpenACC, Prev: Runtime Library Routines, Up: Top 1624 1625 4 OpenMP Environment Variables 1626 ****************************** 1627 1628 The environment variables which beginning with 'OMP_' are defined by 1629 section 4 of the OpenMP specification in version 4.5, while those 1630 beginning with 'GOMP_' are GNU extensions. 1631 1632 * Menu: 1633 1634 * OMP_CANCELLATION:: Set whether cancellation is activated 1635 * OMP_DISPLAY_ENV:: Show OpenMP version and environment variables 1636 * OMP_DEFAULT_DEVICE:: Set the device used in target regions 1637 * OMP_DYNAMIC:: Dynamic adjustment of threads 1638 * OMP_MAX_ACTIVE_LEVELS:: Set the maximum number of nested parallel regions 1639 * OMP_MAX_TASK_PRIORITY:: Set the maximum task priority value 1640 * OMP_NESTED:: Nested parallel regions 1641 * OMP_NUM_TEAMS:: Specifies the number of teams to use by teams region 1642 * OMP_NUM_THREADS:: Specifies the number of threads to use 1643 * OMP_PROC_BIND:: Whether threads may be moved between CPUs 1644 * OMP_PLACES:: Specifies on which CPUs the threads should be placed 1645 * OMP_STACKSIZE:: Set default thread stack size 1646 * OMP_SCHEDULE:: How threads are scheduled 1647 * OMP_TARGET_OFFLOAD:: Controls offloading behaviour 1648 * OMP_TEAMS_THREAD_LIMIT:: Set the maximum number of threads imposed by teams 1649 * OMP_THREAD_LIMIT:: Set the maximum number of threads 1650 * OMP_WAIT_POLICY:: How waiting threads are handled 1651 * GOMP_CPU_AFFINITY:: Bind threads to specific CPUs 1652 * GOMP_DEBUG:: Enable debugging output 1653 * GOMP_STACKSIZE:: Set default thread stack size 1654 * GOMP_SPINCOUNT:: Set the busy-wait spin count 1655 * GOMP_RTEMS_THREAD_POOLS:: Set the RTEMS specific thread pools 1656 1657 1658 File: libgomp.info, Node: OMP_CANCELLATION, Next: OMP_DISPLAY_ENV, Up: Environment Variables 1659 1660 4.1 'OMP_CANCELLATION' - Set whether cancellation is activated 1661 ============================================================== 1662 1663 _Description_: 1664 If set to 'TRUE', the cancellation is activated. If set to 'FALSE' 1665 or if unset, cancellation is disabled and the 'cancel' construct is 1666 ignored. 1667 1668 _See also_: 1669 *note omp_get_cancellation:: 1670 1671 _Reference_: 1672 OpenMP specification v4.5 (https://www.openmp.org), Section 4.11 1673 1674 1675 File: libgomp.info, Node: OMP_DISPLAY_ENV, Next: OMP_DEFAULT_DEVICE, Prev: OMP_CANCELLATION, Up: Environment Variables 1676 1677 4.2 'OMP_DISPLAY_ENV' - Show OpenMP version and environment variables 1678 ===================================================================== 1679 1680 _Description_: 1681 If set to 'TRUE', the OpenMP version number and the values 1682 associated with the OpenMP environment variables are printed to 1683 'stderr'. If set to 'VERBOSE', it additionally shows the value of 1684 the environment variables which are GNU extensions. If undefined 1685 or set to 'FALSE', this information will not be shown. 1686 1687 _Reference_: 1688 OpenMP specification v4.5 (https://www.openmp.org), Section 4.12 1689 1690 1691 File: libgomp.info, Node: OMP_DEFAULT_DEVICE, Next: OMP_DYNAMIC, Prev: OMP_DISPLAY_ENV, Up: Environment Variables 1692 1693 4.3 'OMP_DEFAULT_DEVICE' - Set the device used in target regions 1694 ================================================================ 1695 1696 _Description_: 1697 Set to choose the device which is used in a 'target' region, unless 1698 the value is overridden by 'omp_set_default_device' or by a 1699 'device' clause. The value shall be the nonnegative device number. 1700 If no device with the given device number exists, the code is 1701 executed on the host. If unset, device number 0 will be used. 1702 1703 _See also_: 1704 *note omp_get_default_device::, *note omp_set_default_device::, 1705 1706 _Reference_: 1707 OpenMP specification v4.5 (https://www.openmp.org), Section 4.13 1708 1709 1710 File: libgomp.info, Node: OMP_DYNAMIC, Next: OMP_MAX_ACTIVE_LEVELS, Prev: OMP_DEFAULT_DEVICE, Up: Environment Variables 1711 1712 4.4 'OMP_DYNAMIC' - Dynamic adjustment of threads 1713 ================================================= 1714 1715 _Description_: 1716 Enable or disable the dynamic adjustment of the number of threads 1717 within a team. The value of this environment variable shall be 1718 'TRUE' or 'FALSE'. If undefined, dynamic adjustment is disabled by 1719 default. 1720 1721 _See also_: 1722 *note omp_set_dynamic:: 1723 1724 _Reference_: 1725 OpenMP specification v4.5 (https://www.openmp.org), Section 4.3 1726 1727 1728 File: libgomp.info, Node: OMP_MAX_ACTIVE_LEVELS, Next: OMP_MAX_TASK_PRIORITY, Prev: OMP_DYNAMIC, Up: Environment Variables 1729 1730 4.5 'OMP_MAX_ACTIVE_LEVELS' - Set the maximum number of nested parallel regions 1731 =============================================================================== 1732 1733 _Description_: 1734 Specifies the initial value for the maximum number of nested 1735 parallel regions. The value of this variable shall be a positive 1736 integer. If undefined, then if 'OMP_NESTED' is defined and set to 1737 true, or if 'OMP_NUM_THREADS' or 'OMP_PROC_BIND' are defined and 1738 set to a list with more than one item, the maximum number of nested 1739 parallel regions will be initialized to the largest number 1740 supported, otherwise it will be set to one. 1741 1742 _See also_: 1743 *note omp_set_max_active_levels::, *note OMP_NESTED:: 1744 1745 _Reference_: 1746 OpenMP specification v4.5 (https://www.openmp.org), Section 4.9 1747 1748 1749 File: libgomp.info, Node: OMP_MAX_TASK_PRIORITY, Next: OMP_NESTED, Prev: OMP_MAX_ACTIVE_LEVELS, Up: Environment Variables 1750 1751 4.6 'OMP_MAX_TASK_PRIORITY' - Set the maximum priority 1752 ====================================================== 1753 1754 number that can be set for a task. 1755 _Description_: 1756 Specifies the initial value for the maximum priority value that can 1757 be set for a task. The value of this variable shall be a 1758 non-negative integer, and zero is allowed. If undefined, the 1759 default priority is 0. 1760 1761 _See also_: 1762 *note omp_get_max_task_priority:: 1763 1764 _Reference_: 1765 OpenMP specification v4.5 (https://www.openmp.org), Section 4.14 1766 1767 1768 File: libgomp.info, Node: OMP_NESTED, Next: OMP_NUM_TEAMS, Prev: OMP_MAX_TASK_PRIORITY, Up: Environment Variables 1769 1770 4.7 'OMP_NESTED' - Nested parallel regions 1771 ========================================== 1772 1773 _Description_: 1774 Enable or disable nested parallel regions, i.e., whether team 1775 members are allowed to create new teams. The value of this 1776 environment variable shall be 'TRUE' or 'FALSE'. If set to 'TRUE', 1777 the number of maximum active nested regions supported will by 1778 default be set to the maximum supported, otherwise it will be set 1779 to one. If 'OMP_MAX_ACTIVE_LEVELS' is defined, its setting will 1780 override this setting. If both are undefined, nested parallel 1781 regions are enabled if 'OMP_NUM_THREADS' or 'OMP_PROC_BINDS' are 1782 defined to a list with more than one item, otherwise they are 1783 disabled by default. 1784 1785 _See also_: 1786 *note omp_set_max_active_levels::, *note omp_set_nested:: 1787 1788 _Reference_: 1789 OpenMP specification v4.5 (https://www.openmp.org), Section 4.6 1790 1791 1792 File: libgomp.info, Node: OMP_NUM_TEAMS, Next: OMP_NUM_THREADS, Prev: OMP_NESTED, Up: Environment Variables 1793 1794 4.8 'OMP_NUM_TEAMS' - Specifies the number of teams to use by teams region 1795 ========================================================================== 1796 1797 _Description_: 1798 Specifies the upper bound for number of teams to use in teams 1799 regions without explicit 'num_teams' clause. The value of this 1800 variable shall be a positive integer. If undefined it defaults to 1801 0 which means implementation defined upper bound. 1802 1803 _See also_: 1804 *note omp_set_num_teams:: 1805 1806 _Reference_: 1807 OpenMP specification v5.1 (https://www.openmp.org), Section 6.23 1808 1809 1810 File: libgomp.info, Node: OMP_NUM_THREADS, Next: OMP_PROC_BIND, Prev: OMP_NUM_TEAMS, Up: Environment Variables 1811 1812 4.9 'OMP_NUM_THREADS' - Specifies the number of threads to use 1813 ============================================================== 1814 1815 _Description_: 1816 Specifies the default number of threads to use in parallel regions. 1817 The value of this variable shall be a comma-separated list of 1818 positive integers; the value specifies the number of threads to use 1819 for the corresponding nested level. Specifying more than one item 1820 in the list will automatically enable nesting by default. If 1821 undefined one thread per CPU is used. 1822 1823 _See also_: 1824 *note omp_set_num_threads::, *note OMP_NESTED:: 1825 1826 _Reference_: 1827 OpenMP specification v4.5 (https://www.openmp.org), Section 4.2 1828 1829 1830 File: libgomp.info, Node: OMP_PROC_BIND, Next: OMP_PLACES, Prev: OMP_NUM_THREADS, Up: Environment Variables 1831 1832 4.10 'OMP_PROC_BIND' - Whether threads may be moved between CPUs 1833 ================================================================ 1834 1835 _Description_: 1836 Specifies whether threads may be moved between processors. If set 1837 to 'TRUE', OpenMP threads should not be moved; if set to 'FALSE' 1838 they may be moved. Alternatively, a comma separated list with the 1839 values 'PRIMARY', 'MASTER', 'CLOSE' and 'SPREAD' can be used to 1840 specify the thread affinity policy for the corresponding nesting 1841 level. With 'PRIMARY' and 'MASTER' the worker threads are in the 1842 same place partition as the primary thread. With 'CLOSE' those are 1843 kept close to the primary thread in contiguous place partitions. 1844 And with 'SPREAD' a sparse distribution across the place partitions 1845 is used. Specifying more than one item in the list will 1846 automatically enable nesting by default. 1847 1848 When undefined, 'OMP_PROC_BIND' defaults to 'TRUE' when 1849 'OMP_PLACES' or 'GOMP_CPU_AFFINITY' is set and 'FALSE' otherwise. 1850 1851 _See also_: 1852 *note omp_get_proc_bind::, *note GOMP_CPU_AFFINITY::, *note 1853 OMP_NESTED::, *note OMP_PLACES:: 1854 1855 _Reference_: 1856 OpenMP specification v4.5 (https://www.openmp.org), Section 4.4 1857 1858 1859 File: libgomp.info, Node: OMP_PLACES, Next: OMP_STACKSIZE, Prev: OMP_PROC_BIND, Up: Environment Variables 1860 1861 4.11 'OMP_PLACES' - Specifies on which CPUs the threads should be placed 1862 ======================================================================== 1863 1864 _Description_: 1865 The thread placement can be either specified using an abstract name 1866 or by an explicit list of the places. The abstract names 1867 'threads', 'cores', 'sockets', 'll_caches' and 'numa_domains' can 1868 be optionally followed by a positive number in parentheses, which 1869 denotes the how many places shall be created. With 'threads' each 1870 place corresponds to a single hardware thread; 'cores' to a single 1871 core with the corresponding number of hardware threads; with 1872 'sockets' the place corresponds to a single socket; with 1873 'll_caches' to a set of cores that shares the last level cache on 1874 the device; and 'numa_domains' to a set of cores for which their 1875 closest memory on the device is the same memory and at a similar 1876 distance from the cores. The resulting placement can be shown by 1877 setting the 'OMP_DISPLAY_ENV' environment variable. 1878 1879 Alternatively, the placement can be specified explicitly as 1880 comma-separated list of places. A place is specified by set of 1881 nonnegative numbers in curly braces, denoting the hardware threads. 1882 The curly braces can be omitted when only a single number has been 1883 specified. The hardware threads belonging to a place can either be 1884 specified as comma-separated list of nonnegative thread numbers or 1885 using an interval. Multiple places can also be either specified by 1886 a comma-separated list of places or by an interval. To specify an 1887 interval, a colon followed by the count is placed after the 1888 hardware thread number or the place. Optionally, the length can be 1889 followed by a colon and the stride number - otherwise a unit stride 1890 is assumed. Placing an exclamation mark ('!') directly before a 1891 curly brace or numbers inside the curly braces (excluding 1892 intervals) will exclude those hardware threads. 1893 1894 For instance, the following specifies the same places list: 1895 '"{0,1,2}, {3,4,6}, {7,8,9}, {10,11,12}"'; '"{0:3}, {3:3}, {7:3}, 1896 {10:3}"'; and '"{0:2}:4:3"'. 1897 1898 If 'OMP_PLACES' and 'GOMP_CPU_AFFINITY' are unset and 1899 'OMP_PROC_BIND' is either unset or 'false', threads may be moved 1900 between CPUs following no placement policy. 1901 1902 _See also_: 1903 *note OMP_PROC_BIND::, *note GOMP_CPU_AFFINITY::, *note 1904 omp_get_proc_bind::, *note OMP_DISPLAY_ENV:: 1905 1906 _Reference_: 1907 OpenMP specification v4.5 (https://www.openmp.org), Section 4.5 1908 1909 1910 File: libgomp.info, Node: OMP_STACKSIZE, Next: OMP_SCHEDULE, Prev: OMP_PLACES, Up: Environment Variables 1911 1912 4.12 'OMP_STACKSIZE' - Set default thread stack size 1913 ==================================================== 1914 1915 _Description_: 1916 Set the default thread stack size in kilobytes, unless the number 1917 is suffixed by 'B', 'K', 'M' or 'G', in which case the size is, 1918 respectively, in bytes, kilobytes, megabytes or gigabytes. This is 1919 different from 'pthread_attr_setstacksize' which gets the number of 1920 bytes as an argument. If the stack size cannot be set due to 1921 system constraints, an error is reported and the initial stack size 1922 is left unchanged. If undefined, the stack size is system 1923 dependent. 1924 1925 _Reference_: 1926 OpenMP specification v4.5 (https://www.openmp.org), Section 4.7 1927 1928 1929 File: libgomp.info, Node: OMP_SCHEDULE, Next: OMP_TARGET_OFFLOAD, Prev: OMP_STACKSIZE, Up: Environment Variables 1930 1931 4.13 'OMP_SCHEDULE' - How threads are scheduled 1932 =============================================== 1933 1934 _Description_: 1935 Allows to specify 'schedule type' and 'chunk size'. The value of 1936 the variable shall have the form: 'type[,chunk]' where 'type' is 1937 one of 'static', 'dynamic', 'guided' or 'auto' The optional 'chunk' 1938 size shall be a positive integer. If undefined, dynamic scheduling 1939 and a chunk size of 1 is used. 1940 1941 _See also_: 1942 *note omp_set_schedule:: 1943 1944 _Reference_: 1945 OpenMP specification v4.5 (https://www.openmp.org), Sections 1946 2.7.1.1 and 4.1 1947 1948 1949 File: libgomp.info, Node: OMP_TARGET_OFFLOAD, Next: OMP_TEAMS_THREAD_LIMIT, Prev: OMP_SCHEDULE, Up: Environment Variables 1950 1951 4.14 'OMP_TARGET_OFFLOAD' - Controls offloading behaviour 1952 ========================================================= 1953 1954 _Description_: 1955 Specifies the behaviour with regard to offloading code to a device. 1956 This variable can be set to one of three values - 'MANDATORY', 1957 'DISABLED' or 'DEFAULT'. 1958 1959 If set to 'MANDATORY', the program will terminate with an error if 1960 the offload device is not present or is not supported. If set to 1961 'DISABLED', then offloading is disabled and all code will run on 1962 the host. If set to 'DEFAULT', the program will try offloading to 1963 the device first, then fall back to running code on the host if it 1964 cannot. 1965 1966 If undefined, then the program will behave as if 'DEFAULT' was set. 1967 1968 _Reference_: 1969 OpenMP specification v5.0 (https://www.openmp.org), Section 6.17 1970 1971 1972 File: libgomp.info, Node: OMP_TEAMS_THREAD_LIMIT, Next: OMP_THREAD_LIMIT, Prev: OMP_TARGET_OFFLOAD, Up: Environment Variables 1973 1974 4.15 'OMP_TEAMS_THREAD_LIMIT' - Set the maximum number of threads imposed by teams 1975 ================================================================================== 1976 1977 _Description_: 1978 Specifies an upper bound for the number of threads to use by each 1979 contention group created by a teams construct without explicit 1980 'thread_limit' clause. The value of this variable shall be a 1981 positive integer. If undefined, the value of 0 is used which 1982 stands for an implementation defined upper limit. 1983 1984 _See also_: 1985 *note OMP_THREAD_LIMIT::, *note omp_set_teams_thread_limit:: 1986 1987 _Reference_: 1988 OpenMP specification v5.1 (https://www.openmp.org), Section 6.24 1989 1990 1991 File: libgomp.info, Node: OMP_THREAD_LIMIT, Next: OMP_WAIT_POLICY, Prev: OMP_TEAMS_THREAD_LIMIT, Up: Environment Variables 1992 1993 4.16 'OMP_THREAD_LIMIT' - Set the maximum number of threads 1994 =========================================================== 1995 1996 _Description_: 1997 Specifies the number of threads to use for the whole program. The 1998 value of this variable shall be a positive integer. If undefined, 1999 the number of threads is not limited. 2000 2001 _See also_: 2002 *note OMP_NUM_THREADS::, *note omp_get_thread_limit:: 2003 2004 _Reference_: 2005 OpenMP specification v4.5 (https://www.openmp.org), Section 4.10 2006 2007 2008 File: libgomp.info, Node: OMP_WAIT_POLICY, Next: GOMP_CPU_AFFINITY, Prev: OMP_THREAD_LIMIT, Up: Environment Variables 2009 2010 4.17 'OMP_WAIT_POLICY' - How waiting threads are handled 2011 ======================================================== 2012 2013 _Description_: 2014 Specifies whether waiting threads should be active or passive. If 2015 the value is 'PASSIVE', waiting threads should not consume CPU 2016 power while waiting; while the value is 'ACTIVE' specifies that 2017 they should. If undefined, threads wait actively for a short time 2018 before waiting passively. 2019 2020 _See also_: 2021 *note GOMP_SPINCOUNT:: 2022 2023 _Reference_: 2024 OpenMP specification v4.5 (https://www.openmp.org), Section 4.8 2025 2026 2027 File: libgomp.info, Node: GOMP_CPU_AFFINITY, Next: GOMP_DEBUG, Prev: OMP_WAIT_POLICY, Up: Environment Variables 2028 2029 4.18 'GOMP_CPU_AFFINITY' - Bind threads to specific CPUs 2030 ======================================================== 2031 2032 _Description_: 2033 Binds threads to specific CPUs. The variable should contain a 2034 space-separated or comma-separated list of CPUs. This list may 2035 contain different kinds of entries: either single CPU numbers in 2036 any order, a range of CPUs (M-N) or a range with some stride 2037 (M-N:S). CPU numbers are zero based. For example, 2038 'GOMP_CPU_AFFINITY="0 3 1-2 4-15:2"' will bind the initial thread 2039 to CPU 0, the second to CPU 3, the third to CPU 1, the fourth to 2040 CPU 2, the fifth to CPU 4, the sixth through tenth to CPUs 6, 8, 2041 10, 12, and 14 respectively and then start assigning back from the 2042 beginning of the list. 'GOMP_CPU_AFFINITY=0' binds all threads to 2043 CPU 0. 2044 2045 There is no libgomp library routine to determine whether a CPU 2046 affinity specification is in effect. As a workaround, 2047 language-specific library functions, e.g., 'getenv' in C or 2048 'GET_ENVIRONMENT_VARIABLE' in Fortran, may be used to query the 2049 setting of the 'GOMP_CPU_AFFINITY' environment variable. A defined 2050 CPU affinity on startup cannot be changed or disabled during the 2051 runtime of the application. 2052 2053 If both 'GOMP_CPU_AFFINITY' and 'OMP_PROC_BIND' are set, 2054 'OMP_PROC_BIND' has a higher precedence. If neither has been set 2055 and 'OMP_PROC_BIND' is unset, or when 'OMP_PROC_BIND' is set to 2056 'FALSE', the host system will handle the assignment of threads to 2057 CPUs. 2058 2059 _See also_: 2060 *note OMP_PLACES::, *note OMP_PROC_BIND:: 2061 2062 2063 File: libgomp.info, Node: GOMP_DEBUG, Next: GOMP_STACKSIZE, Prev: GOMP_CPU_AFFINITY, Up: Environment Variables 2064 2065 4.19 'GOMP_DEBUG' - Enable debugging output 2066 =========================================== 2067 2068 _Description_: 2069 Enable debugging output. The variable should be set to '0' 2070 (disabled, also the default if not set), or '1' (enabled). 2071 2072 If enabled, some debugging output will be printed during execution. 2073 This is currently not specified in more detail, and subject to 2074 change. 2075 2076 2077 File: libgomp.info, Node: GOMP_STACKSIZE, Next: GOMP_SPINCOUNT, Prev: GOMP_DEBUG, Up: Environment Variables 2078 2079 4.20 'GOMP_STACKSIZE' - Set default thread stack size 2080 ===================================================== 2081 2082 _Description_: 2083 Set the default thread stack size in kilobytes. This is different 2084 from 'pthread_attr_setstacksize' which gets the number of bytes as 2085 an argument. If the stack size cannot be set due to system 2086 constraints, an error is reported and the initial stack size is 2087 left unchanged. If undefined, the stack size is system dependent. 2088 2089 _See also_: 2090 *note OMP_STACKSIZE:: 2091 2092 _Reference_: 2093 GCC Patches Mailinglist 2094 (https://gcc.gnu.org/ml/gcc-patches/2006-06/msg00493.html), GCC 2095 Patches Mailinglist 2096 (https://gcc.gnu.org/ml/gcc-patches/2006-06/msg00496.html) 2097 2098 2099 File: libgomp.info, Node: GOMP_SPINCOUNT, Next: GOMP_RTEMS_THREAD_POOLS, Prev: GOMP_STACKSIZE, Up: Environment Variables 2100 2101 4.21 'GOMP_SPINCOUNT' - Set the busy-wait spin count 2102 ==================================================== 2103 2104 _Description_: 2105 Determines how long a threads waits actively with consuming CPU 2106 power before waiting passively without consuming CPU power. The 2107 value may be either 'INFINITE', 'INFINITY' to always wait actively 2108 or an integer which gives the number of spins of the busy-wait 2109 loop. The integer may optionally be followed by the following 2110 suffixes acting as multiplication factors: 'k' (kilo, thousand), 2111 'M' (mega, million), 'G' (giga, billion), or 'T' (tera, trillion). 2112 If undefined, 0 is used when 'OMP_WAIT_POLICY' is 'PASSIVE', 2113 300,000 is used when 'OMP_WAIT_POLICY' is undefined and 30 billion 2114 is used when 'OMP_WAIT_POLICY' is 'ACTIVE'. If there are more 2115 OpenMP threads than available CPUs, 1000 and 100 spins are used for 2116 'OMP_WAIT_POLICY' being 'ACTIVE' or undefined, respectively; unless 2117 the 'GOMP_SPINCOUNT' is lower or 'OMP_WAIT_POLICY' is 'PASSIVE'. 2118 2119 _See also_: 2120 *note OMP_WAIT_POLICY:: 2121 2122 2123 File: libgomp.info, Node: GOMP_RTEMS_THREAD_POOLS, Prev: GOMP_SPINCOUNT, Up: Environment Variables 2124 2125 4.22 'GOMP_RTEMS_THREAD_POOLS' - Set the RTEMS specific thread pools 2126 ==================================================================== 2127 2128 _Description_: 2129 This environment variable is only used on the RTEMS real-time 2130 operating system. It determines the scheduler instance specific 2131 thread pools. The format for 'GOMP_RTEMS_THREAD_POOLS' is a list 2132 of optional '<thread-pool-count>[$<priority>]@<scheduler-name>' 2133 configurations separated by ':' where: 2134 * '<thread-pool-count>' is the thread pool count for this 2135 scheduler instance. 2136 * '$<priority>' is an optional priority for the worker threads 2137 of a thread pool according to 'pthread_setschedparam'. In 2138 case a priority value is omitted, then a worker thread will 2139 inherit the priority of the OpenMP primary thread that created 2140 it. The priority of the worker thread is not changed after 2141 creation, even if a new OpenMP primary thread using the worker 2142 has a different priority. 2143 * '@<scheduler-name>' is the scheduler instance name according 2144 to the RTEMS application configuration. 2145 In case no thread pool configuration is specified for a scheduler 2146 instance, then each OpenMP primary thread of this scheduler 2147 instance will use its own dynamically allocated thread pool. To 2148 limit the worker thread count of the thread pools, each OpenMP 2149 primary thread must call 'omp_set_num_threads'. 2150 _Example_: 2151 Lets suppose we have three scheduler instances 'IO', 'WRK0', and 2152 'WRK1' with 'GOMP_RTEMS_THREAD_POOLS' set to '"1@WRK0:3$4@WRK1"'. 2153 Then there are no thread pool restrictions for scheduler instance 2154 'IO'. In the scheduler instance 'WRK0' there is one thread pool 2155 available. Since no priority is specified for this scheduler 2156 instance, the worker thread inherits the priority of the OpenMP 2157 primary thread that created it. In the scheduler instance 'WRK1' 2158 there are three thread pools available and their worker threads run 2159 at priority four. 2160 2161 2162 File: libgomp.info, Node: Enabling OpenACC, Next: OpenACC Runtime Library Routines, Prev: Environment Variables, Up: Top 2163 2164 5 Enabling OpenACC 2165 ****************** 2166 2167 To activate the OpenACC extensions for C/C++ and Fortran, the 2168 compile-time flag '-fopenacc' must be specified. This enables the 2169 OpenACC directive '#pragma acc' in C/C++ and '!$acc' directives in free 2170 form, 'c$acc', '*$acc' and '!$acc' directives in fixed form, '!$' 2171 conditional compilation sentinels in free form and 'c$', '*$' and '!$' 2172 sentinels in fixed form, for Fortran. The flag also arranges for 2173 automatic linking of the OpenACC runtime library (*note OpenACC Runtime 2174 Library Routines::). 2175 2176 See <https://gcc.gnu.org/wiki/OpenACC> for more information. 2177 2178 A complete description of all OpenACC directives accepted may be 2179 found in the OpenACC (https://www.openacc.org) Application Programming 2180 Interface manual, version 2.6. 2181 2182 2183 File: libgomp.info, Node: OpenACC Runtime Library Routines, Next: OpenACC Environment Variables, Prev: Enabling OpenACC, Up: Top 2184 2185 6 OpenACC Runtime Library Routines 2186 ********************************** 2187 2188 The runtime routines described here are defined by section 3 of the 2189 OpenACC specifications in version 2.6. They have C linkage, and do not 2190 throw exceptions. Generally, they are available only for the host, with 2191 the exception of 'acc_on_device', which is available for both the host 2192 and the acceleration device. 2193 2194 * Menu: 2195 2196 * acc_get_num_devices:: Get number of devices for the given device 2197 type. 2198 * acc_set_device_type:: Set type of device accelerator to use. 2199 * acc_get_device_type:: Get type of device accelerator to be used. 2200 * acc_set_device_num:: Set device number to use. 2201 * acc_get_device_num:: Get device number to be used. 2202 * acc_get_property:: Get device property. 2203 * acc_async_test:: Tests for completion of a specific asynchronous 2204 operation. 2205 * acc_async_test_all:: Tests for completion of all asynchronous 2206 operations. 2207 * acc_wait:: Wait for completion of a specific asynchronous 2208 operation. 2209 * acc_wait_all:: Waits for completion of all asynchronous 2210 operations. 2211 * acc_wait_all_async:: Wait for completion of all asynchronous 2212 operations. 2213 * acc_wait_async:: Wait for completion of asynchronous operations. 2214 * acc_init:: Initialize runtime for a specific device type. 2215 * acc_shutdown:: Shuts down the runtime for a specific device 2216 type. 2217 * acc_on_device:: Whether executing on a particular device 2218 * acc_malloc:: Allocate device memory. 2219 * acc_free:: Free device memory. 2220 * acc_copyin:: Allocate device memory and copy host memory to 2221 it. 2222 * acc_present_or_copyin:: If the data is not present on the device, 2223 allocate device memory and copy from host 2224 memory. 2225 * acc_create:: Allocate device memory and map it to host 2226 memory. 2227 * acc_present_or_create:: If the data is not present on the device, 2228 allocate device memory and map it to host 2229 memory. 2230 * acc_copyout:: Copy device memory to host memory. 2231 * acc_delete:: Free device memory. 2232 * acc_update_device:: Update device memory from mapped host memory. 2233 * acc_update_self:: Update host memory from mapped device memory. 2234 * acc_map_data:: Map previously allocated device memory to host 2235 memory. 2236 * acc_unmap_data:: Unmap device memory from host memory. 2237 * acc_deviceptr:: Get device pointer associated with specific 2238 host address. 2239 * acc_hostptr:: Get host pointer associated with specific 2240 device address. 2241 * acc_is_present:: Indicate whether host variable / array is 2242 present on device. 2243 * acc_memcpy_to_device:: Copy host memory to device memory. 2244 * acc_memcpy_from_device:: Copy device memory to host memory. 2245 * acc_attach:: Let device pointer point to device-pointer target. 2246 * acc_detach:: Let device pointer point to host-pointer target. 2247 2248 API routines for target platforms. 2249 2250 * acc_get_current_cuda_device:: Get CUDA device handle. 2251 * acc_get_current_cuda_context::Get CUDA context handle. 2252 * acc_get_cuda_stream:: Get CUDA stream handle. 2253 * acc_set_cuda_stream:: Set CUDA stream handle. 2254 2255 API routines for the OpenACC Profiling Interface. 2256 2257 * acc_prof_register:: Register callbacks. 2258 * acc_prof_unregister:: Unregister callbacks. 2259 * acc_prof_lookup:: Obtain inquiry functions. 2260 * acc_register_library:: Library registration. 2261 2262 2263 File: libgomp.info, Node: acc_get_num_devices, Next: acc_set_device_type, Up: OpenACC Runtime Library Routines 2264 2265 6.1 'acc_get_num_devices' - Get number of devices for given device type 2266 ======================================================================= 2267 2268 _Description_ 2269 This function returns a value indicating the number of devices 2270 available for the device type specified in DEVICETYPE. 2271 2272 _C/C++_: 2273 _Prototype_: 'int acc_get_num_devices(acc_device_t devicetype);' 2274 2275 _Fortran_: 2276 _Interface_: 'integer function acc_get_num_devices(devicetype)' 2277 'integer(kind=acc_device_kind) devicetype' 2278 2279 _Reference_: 2280 OpenACC specification v2.6 (https://www.openacc.org), section 2281 3.2.1. 2282 2283 2284 File: libgomp.info, Node: acc_set_device_type, Next: acc_get_device_type, Prev: acc_get_num_devices, Up: OpenACC Runtime Library Routines 2285 2286 6.2 'acc_set_device_type' - Set type of device accelerator to use. 2287 ================================================================== 2288 2289 _Description_ 2290 This function indicates to the runtime library which device type, 2291 specified in DEVICETYPE, to use when executing a parallel or 2292 kernels region. 2293 2294 _C/C++_: 2295 _Prototype_: 'acc_set_device_type(acc_device_t devicetype);' 2296 2297 _Fortran_: 2298 _Interface_: 'subroutine acc_set_device_type(devicetype)' 2299 'integer(kind=acc_device_kind) devicetype' 2300 2301 _Reference_: 2302 OpenACC specification v2.6 (https://www.openacc.org), section 2303 3.2.2. 2304 2305 2306 File: libgomp.info, Node: acc_get_device_type, Next: acc_set_device_num, Prev: acc_set_device_type, Up: OpenACC Runtime Library Routines 2307 2308 6.3 'acc_get_device_type' - Get type of device accelerator to be used. 2309 ====================================================================== 2310 2311 _Description_ 2312 This function returns what device type will be used when executing 2313 a parallel or kernels region. 2314 2315 This function returns 'acc_device_none' if 'acc_get_device_type' is 2316 called from 'acc_ev_device_init_start', 'acc_ev_device_init_end' 2317 callbacks of the OpenACC Profiling Interface (*note OpenACC 2318 Profiling Interface::), that is, if the device is currently being 2319 initialized. 2320 2321 _C/C++_: 2322 _Prototype_: 'acc_device_t acc_get_device_type(void);' 2323 2324 _Fortran_: 2325 _Interface_: 'function acc_get_device_type(void)' 2326 'integer(kind=acc_device_kind) acc_get_device_type' 2327 2328 _Reference_: 2329 OpenACC specification v2.6 (https://www.openacc.org), section 2330 3.2.3. 2331 2332 2333 File: libgomp.info, Node: acc_set_device_num, Next: acc_get_device_num, Prev: acc_get_device_type, Up: OpenACC Runtime Library Routines 2334 2335 6.4 'acc_set_device_num' - Set device number to use. 2336 ==================================================== 2337 2338 _Description_ 2339 This function will indicate to the runtime which device number, 2340 specified by DEVICENUM, associated with the specified device type 2341 DEVICETYPE. 2342 2343 _C/C++_: 2344 _Prototype_: 'acc_set_device_num(int devicenum, acc_device_t 2345 devicetype);' 2346 2347 _Fortran_: 2348 _Interface_: 'subroutine acc_set_device_num(devicenum, devicetype)' 2349 'integer devicenum' 2350 'integer(kind=acc_device_kind) devicetype' 2351 2352 _Reference_: 2353 OpenACC specification v2.6 (https://www.openacc.org), section 2354 3.2.4. 2355 2356 2357 File: libgomp.info, Node: acc_get_device_num, Next: acc_get_property, Prev: acc_set_device_num, Up: OpenACC Runtime Library Routines 2358 2359 6.5 'acc_get_device_num' - Get device number to be used. 2360 ======================================================== 2361 2362 _Description_ 2363 This function returns which device number associated with the 2364 specified device type DEVICETYPE, will be used when executing a 2365 parallel or kernels region. 2366 2367 _C/C++_: 2368 _Prototype_: 'int acc_get_device_num(acc_device_t devicetype);' 2369 2370 _Fortran_: 2371 _Interface_: 'function acc_get_device_num(devicetype)' 2372 'integer(kind=acc_device_kind) devicetype' 2373 'integer acc_get_device_num' 2374 2375 _Reference_: 2376 OpenACC specification v2.6 (https://www.openacc.org), section 2377 3.2.5. 2378 2379 2380 File: libgomp.info, Node: acc_get_property, Next: acc_async_test, Prev: acc_get_device_num, Up: OpenACC Runtime Library Routines 2381 2382 6.6 'acc_get_property' - Get device property. 2383 ============================================= 2384 2385 _Description_ 2386 These routines return the value of the specified PROPERTY for the 2387 device being queried according to DEVICENUM and DEVICETYPE. 2388 Integer-valued and string-valued properties are returned by 2389 'acc_get_property' and 'acc_get_property_string' respectively. The 2390 Fortran 'acc_get_property_string' subroutine returns the string 2391 retrieved in its fourth argument while the remaining entry points 2392 are functions, which pass the return value as their result. 2393 2394 Note for Fortran, only: the OpenACC technical committee corrected 2395 and, hence, modified the interface introduced in OpenACC 2.6. The 2396 kind-value parameter 'acc_device_property' has been renamed to 2397 'acc_device_property_kind' for consistency and the return type of 2398 the 'acc_get_property' function is now a 'c_size_t' integer instead 2399 of a 'acc_device_property' integer. The parameter 2400 'acc_device_property' will continue to be provided, but might be 2401 removed in a future version of GCC. 2402 2403 _C/C++_: 2404 _Prototype_: 'size_t acc_get_property(int devicenum, acc_device_t 2405 devicetype, acc_device_property_t property);' 2406 _Prototype_: 'const char *acc_get_property_string(int devicenum, 2407 acc_device_t devicetype, acc_device_property_t 2408 property);' 2409 2410 _Fortran_: 2411 _Interface_: 'function acc_get_property(devicenum, devicetype, 2412 property)' 2413 _Interface_: 'subroutine acc_get_property_string(devicenum, 2414 devicetype, property, string)' 2415 'use ISO_C_Binding, only: c_size_t' 2416 'integer devicenum' 2417 'integer(kind=acc_device_kind) devicetype' 2418 'integer(kind=acc_device_property_kind) property' 2419 'integer(kind=c_size_t) acc_get_property' 2420 'character(*) string' 2421 2422 _Reference_: 2423 OpenACC specification v2.6 (https://www.openacc.org), section 2424 3.2.6. 2425 2426 2427 File: libgomp.info, Node: acc_async_test, Next: acc_async_test_all, Prev: acc_get_property, Up: OpenACC Runtime Library Routines 2428 2429 6.7 'acc_async_test' - Test for completion of a specific asynchronous operation. 2430 ================================================================================ 2431 2432 _Description_ 2433 This function tests for completion of the asynchronous operation 2434 specified in ARG. In C/C++, a non-zero value will be returned to 2435 indicate the specified asynchronous operation has completed. While 2436 Fortran will return a 'true'. If the asynchronous operation has 2437 not completed, C/C++ returns a zero and Fortran returns a 'false'. 2438 2439 _C/C++_: 2440 _Prototype_: 'int acc_async_test(int arg);' 2441 2442 _Fortran_: 2443 _Interface_: 'function acc_async_test(arg)' 2444 'integer(kind=acc_handle_kind) arg' 2445 'logical acc_async_test' 2446 2447 _Reference_: 2448 OpenACC specification v2.6 (https://www.openacc.org), section 2449 3.2.9. 2450 2451 2452 File: libgomp.info, Node: acc_async_test_all, Next: acc_wait, Prev: acc_async_test, Up: OpenACC Runtime Library Routines 2453 2454 6.8 'acc_async_test_all' - Tests for completion of all asynchronous operations. 2455 =============================================================================== 2456 2457 _Description_ 2458 This function tests for completion of all asynchronous operations. 2459 In C/C++, a non-zero value will be returned to indicate all 2460 asynchronous operations have completed. While Fortran will return 2461 a 'true'. If any asynchronous operation has not completed, C/C++ 2462 returns a zero and Fortran returns a 'false'. 2463 2464 _C/C++_: 2465 _Prototype_: 'int acc_async_test_all(void);' 2466 2467 _Fortran_: 2468 _Interface_: 'function acc_async_test()' 2469 'logical acc_get_device_num' 2470 2471 _Reference_: 2472 OpenACC specification v2.6 (https://www.openacc.org), section 2473 3.2.10. 2474 2475 2476 File: libgomp.info, Node: acc_wait, Next: acc_wait_all, Prev: acc_async_test_all, Up: OpenACC Runtime Library Routines 2477 2478 6.9 'acc_wait' - Wait for completion of a specific asynchronous operation. 2479 ========================================================================== 2480 2481 _Description_ 2482 This function waits for completion of the asynchronous operation 2483 specified in ARG. 2484 2485 _C/C++_: 2486 _Prototype_: 'acc_wait(arg);' 2487 _Prototype 'acc_async_wait(arg);' 2488 (OpenACC 1.0 2489 compatibility)_: 2490 2491 _Fortran_: 2492 _Interface_: 'subroutine acc_wait(arg)' 2493 'integer(acc_handle_kind) arg' 2494 _Interface 'subroutine acc_async_wait(arg)' 2495 (OpenACC 1.0 2496 compatibility)_: 2497 'integer(acc_handle_kind) arg' 2498 2499 _Reference_: 2500 OpenACC specification v2.6 (https://www.openacc.org), section 2501 3.2.11. 2502 2503 2504 File: libgomp.info, Node: acc_wait_all, Next: acc_wait_all_async, Prev: acc_wait, Up: OpenACC Runtime Library Routines 2505 2506 6.10 'acc_wait_all' - Waits for completion of all asynchronous operations. 2507 ========================================================================== 2508 2509 _Description_ 2510 This function waits for the completion of all asynchronous 2511 operations. 2512 2513 _C/C++_: 2514 _Prototype_: 'acc_wait_all(void);' 2515 _Prototype 'acc_async_wait_all(void);' 2516 (OpenACC 1.0 2517 compatibility)_: 2518 2519 _Fortran_: 2520 _Interface_: 'subroutine acc_wait_all()' 2521 _Interface 'subroutine acc_async_wait_all()' 2522 (OpenACC 1.0 2523 compatibility)_: 2524 2525 _Reference_: 2526 OpenACC specification v2.6 (https://www.openacc.org), section 2527 3.2.13. 2528 2529 2530 File: libgomp.info, Node: acc_wait_all_async, Next: acc_wait_async, Prev: acc_wait_all, Up: OpenACC Runtime Library Routines 2531 2532 6.11 'acc_wait_all_async' - Wait for completion of all asynchronous operations. 2533 =============================================================================== 2534 2535 _Description_ 2536 This function enqueues a wait operation on the queue ASYNC for any 2537 and all asynchronous operations that have been previously enqueued 2538 on any queue. 2539 2540 _C/C++_: 2541 _Prototype_: 'acc_wait_all_async(int async);' 2542 2543 _Fortran_: 2544 _Interface_: 'subroutine acc_wait_all_async(async)' 2545 'integer(acc_handle_kind) async' 2546 2547 _Reference_: 2548 OpenACC specification v2.6 (https://www.openacc.org), section 2549 3.2.14. 2550 2551 2552 File: libgomp.info, Node: acc_wait_async, Next: acc_init, Prev: acc_wait_all_async, Up: OpenACC Runtime Library Routines 2553 2554 6.12 'acc_wait_async' - Wait for completion of asynchronous operations. 2555 ======================================================================= 2556 2557 _Description_ 2558 This function enqueues a wait operation on queue ASYNC for any and 2559 all asynchronous operations enqueued on queue ARG. 2560 2561 _C/C++_: 2562 _Prototype_: 'acc_wait_async(int arg, int async);' 2563 2564 _Fortran_: 2565 _Interface_: 'subroutine acc_wait_async(arg, async)' 2566 'integer(acc_handle_kind) arg, async' 2567 2568 _Reference_: 2569 OpenACC specification v2.6 (https://www.openacc.org), section 2570 3.2.12. 2571 2572 2573 File: libgomp.info, Node: acc_init, Next: acc_shutdown, Prev: acc_wait_async, Up: OpenACC Runtime Library Routines 2574 2575 6.13 'acc_init' - Initialize runtime for a specific device type. 2576 ================================================================ 2577 2578 _Description_ 2579 This function initializes the runtime for the device type specified 2580 in DEVICETYPE. 2581 2582 _C/C++_: 2583 _Prototype_: 'acc_init(acc_device_t devicetype);' 2584 2585 _Fortran_: 2586 _Interface_: 'subroutine acc_init(devicetype)' 2587 'integer(acc_device_kind) devicetype' 2588 2589 _Reference_: 2590 OpenACC specification v2.6 (https://www.openacc.org), section 2591 3.2.7. 2592 2593 2594 File: libgomp.info, Node: acc_shutdown, Next: acc_on_device, Prev: acc_init, Up: OpenACC Runtime Library Routines 2595 2596 6.14 'acc_shutdown' - Shuts down the runtime for a specific device type. 2597 ======================================================================== 2598 2599 _Description_ 2600 This function shuts down the runtime for the device type specified 2601 in DEVICETYPE. 2602 2603 _C/C++_: 2604 _Prototype_: 'acc_shutdown(acc_device_t devicetype);' 2605 2606 _Fortran_: 2607 _Interface_: 'subroutine acc_shutdown(devicetype)' 2608 'integer(acc_device_kind) devicetype' 2609 2610 _Reference_: 2611 OpenACC specification v2.6 (https://www.openacc.org), section 2612 3.2.8. 2613 2614 2615 File: libgomp.info, Node: acc_on_device, Next: acc_malloc, Prev: acc_shutdown, Up: OpenACC Runtime Library Routines 2616 2617 6.15 'acc_on_device' - Whether executing on a particular device 2618 =============================================================== 2619 2620 _Description_: 2621 This function returns whether the program is executing on a 2622 particular device specified in DEVICETYPE. In C/C++ a non-zero 2623 value is returned to indicate the device is executing on the 2624 specified device type. In Fortran, 'true' will be returned. If 2625 the program is not executing on the specified device type C/C++ 2626 will return a zero, while Fortran will return 'false'. 2627 2628 _C/C++_: 2629 _Prototype_: 'acc_on_device(acc_device_t devicetype);' 2630 2631 _Fortran_: 2632 _Interface_: 'function acc_on_device(devicetype)' 2633 'integer(acc_device_kind) devicetype' 2634 'logical acc_on_device' 2635 2636 _Reference_: 2637 OpenACC specification v2.6 (https://www.openacc.org), section 2638 3.2.17. 2639 2640 2641 File: libgomp.info, Node: acc_malloc, Next: acc_free, Prev: acc_on_device, Up: OpenACC Runtime Library Routines 2642 2643 6.16 'acc_malloc' - Allocate device memory. 2644 =========================================== 2645 2646 _Description_ 2647 This function allocates LEN bytes of device memory. It returns the 2648 device address of the allocated memory. 2649 2650 _C/C++_: 2651 _Prototype_: 'd_void* acc_malloc(size_t len);' 2652 2653 _Reference_: 2654 OpenACC specification v2.6 (https://www.openacc.org), section 2655 3.2.18. 2656 2657 2658 File: libgomp.info, Node: acc_free, Next: acc_copyin, Prev: acc_malloc, Up: OpenACC Runtime Library Routines 2659 2660 6.17 'acc_free' - Free device memory. 2661 ===================================== 2662 2663 _Description_ 2664 Free previously allocated device memory at the device address 'a'. 2665 2666 _C/C++_: 2667 _Prototype_: 'acc_free(d_void *a);' 2668 2669 _Reference_: 2670 OpenACC specification v2.6 (https://www.openacc.org), section 2671 3.2.19. 2672 2673 2674 File: libgomp.info, Node: acc_copyin, Next: acc_present_or_copyin, Prev: acc_free, Up: OpenACC Runtime Library Routines 2675 2676 6.18 'acc_copyin' - Allocate device memory and copy host memory to it. 2677 ====================================================================== 2678 2679 _Description_ 2680 In C/C++, this function allocates LEN bytes of device memory and 2681 maps it to the specified host address in A. The device address of 2682 the newly allocated device memory is returned. 2683 2684 In Fortran, two (2) forms are supported. In the first form, A 2685 specifies a contiguous array section. The second form A specifies 2686 a variable or array element and LEN specifies the length in bytes. 2687 2688 _C/C++_: 2689 _Prototype_: 'void *acc_copyin(h_void *a, size_t len);' 2690 _Prototype_: 'void *acc_copyin_async(h_void *a, size_t len, int 2691 async);' 2692 2693 _Fortran_: 2694 _Interface_: 'subroutine acc_copyin(a)' 2695 'type, dimension(:[,:]...) :: a' 2696 _Interface_: 'subroutine acc_copyin(a, len)' 2697 'type, dimension(:[,:]...) :: a' 2698 'integer len' 2699 _Interface_: 'subroutine acc_copyin_async(a, async)' 2700 'type, dimension(:[,:]...) :: a' 2701 'integer(acc_handle_kind) :: async' 2702 _Interface_: 'subroutine acc_copyin_async(a, len, async)' 2703 'type, dimension(:[,:]...) :: a' 2704 'integer len' 2705 'integer(acc_handle_kind) :: async' 2706 2707 _Reference_: 2708 OpenACC specification v2.6 (https://www.openacc.org), section 2709 3.2.20. 2710 2711 2712 File: libgomp.info, Node: acc_present_or_copyin, Next: acc_create, Prev: acc_copyin, Up: OpenACC Runtime Library Routines 2713 2714 6.19 'acc_present_or_copyin' - If the data is not present on the device, allocate device memory and copy from host memory. 2715 ========================================================================================================================== 2716 2717 _Description_ 2718 This function tests if the host data specified by A and of length 2719 LEN is present or not. If it is not present, then device memory 2720 will be allocated and the host memory copied. The device address 2721 of the newly allocated device memory is returned. 2722 2723 In Fortran, two (2) forms are supported. In the first form, A 2724 specifies a contiguous array section. The second form A specifies 2725 a variable or array element and LEN specifies the length in bytes. 2726 2727 Note that 'acc_present_or_copyin' and 'acc_pcopyin' exist for 2728 backward compatibility with OpenACC 2.0; use *note acc_copyin:: 2729 instead. 2730 2731 _C/C++_: 2732 _Prototype_: 'void *acc_present_or_copyin(h_void *a, size_t len);' 2733 _Prototype_: 'void *acc_pcopyin(h_void *a, size_t len);' 2734 2735 _Fortran_: 2736 _Interface_: 'subroutine acc_present_or_copyin(a)' 2737 'type, dimension(:[,:]...) :: a' 2738 _Interface_: 'subroutine acc_present_or_copyin(a, len)' 2739 'type, dimension(:[,:]...) :: a' 2740 'integer len' 2741 _Interface_: 'subroutine acc_pcopyin(a)' 2742 'type, dimension(:[,:]...) :: a' 2743 _Interface_: 'subroutine acc_pcopyin(a, len)' 2744 'type, dimension(:[,:]...) :: a' 2745 'integer len' 2746 2747 _Reference_: 2748 OpenACC specification v2.6 (https://www.openacc.org), section 2749 3.2.20. 2750 2751 2752 File: libgomp.info, Node: acc_create, Next: acc_present_or_create, Prev: acc_present_or_copyin, Up: OpenACC Runtime Library Routines 2753 2754 6.20 'acc_create' - Allocate device memory and map it to host memory. 2755 ===================================================================== 2756 2757 _Description_ 2758 This function allocates device memory and maps it to host memory 2759 specified by the host address A with a length of LEN bytes. In 2760 C/C++, the function returns the device address of the allocated 2761 device memory. 2762 2763 In Fortran, two (2) forms are supported. In the first form, A 2764 specifies a contiguous array section. The second form A specifies 2765 a variable or array element and LEN specifies the length in bytes. 2766 2767 _C/C++_: 2768 _Prototype_: 'void *acc_create(h_void *a, size_t len);' 2769 _Prototype_: 'void *acc_create_async(h_void *a, size_t len, int 2770 async);' 2771 2772 _Fortran_: 2773 _Interface_: 'subroutine acc_create(a)' 2774 'type, dimension(:[,:]...) :: a' 2775 _Interface_: 'subroutine acc_create(a, len)' 2776 'type, dimension(:[,:]...) :: a' 2777 'integer len' 2778 _Interface_: 'subroutine acc_create_async(a, async)' 2779 'type, dimension(:[,:]...) :: a' 2780 'integer(acc_handle_kind) :: async' 2781 _Interface_: 'subroutine acc_create_async(a, len, async)' 2782 'type, dimension(:[,:]...) :: a' 2783 'integer len' 2784 'integer(acc_handle_kind) :: async' 2785 2786 _Reference_: 2787 OpenACC specification v2.6 (https://www.openacc.org), section 2788 3.2.21. 2789 2790 2791 File: libgomp.info, Node: acc_present_or_create, Next: acc_copyout, Prev: acc_create, Up: OpenACC Runtime Library Routines 2792 2793 6.21 'acc_present_or_create' - If the data is not present on the device, allocate device memory and map it to host memory. 2794 ========================================================================================================================== 2795 2796 _Description_ 2797 This function tests if the host data specified by A and of length 2798 LEN is present or not. If it is not present, then device memory 2799 will be allocated and mapped to host memory. In C/C++, the device 2800 address of the newly allocated device memory is returned. 2801 2802 In Fortran, two (2) forms are supported. In the first form, A 2803 specifies a contiguous array section. The second form A specifies 2804 a variable or array element and LEN specifies the length in bytes. 2805 2806 Note that 'acc_present_or_create' and 'acc_pcreate' exist for 2807 backward compatibility with OpenACC 2.0; use *note acc_create:: 2808 instead. 2809 2810 _C/C++_: 2811 _Prototype_: 'void *acc_present_or_create(h_void *a, size_t len)' 2812 _Prototype_: 'void *acc_pcreate(h_void *a, size_t len)' 2813 2814 _Fortran_: 2815 _Interface_: 'subroutine acc_present_or_create(a)' 2816 'type, dimension(:[,:]...) :: a' 2817 _Interface_: 'subroutine acc_present_or_create(a, len)' 2818 'type, dimension(:[,:]...) :: a' 2819 'integer len' 2820 _Interface_: 'subroutine acc_pcreate(a)' 2821 'type, dimension(:[,:]...) :: a' 2822 _Interface_: 'subroutine acc_pcreate(a, len)' 2823 'type, dimension(:[,:]...) :: a' 2824 'integer len' 2825 2826 _Reference_: 2827 OpenACC specification v2.6 (https://www.openacc.org), section 2828 3.2.21. 2829 2830 2831 File: libgomp.info, Node: acc_copyout, Next: acc_delete, Prev: acc_present_or_create, Up: OpenACC Runtime Library Routines 2832 2833 6.22 'acc_copyout' - Copy device memory to host memory. 2834 ======================================================= 2835 2836 _Description_ 2837 This function copies mapped device memory to host memory which is 2838 specified by host address A for a length LEN bytes in C/C++. 2839 2840 In Fortran, two (2) forms are supported. In the first form, A 2841 specifies a contiguous array section. The second form A specifies 2842 a variable or array element and LEN specifies the length in bytes. 2843 2844 _C/C++_: 2845 _Prototype_: 'acc_copyout(h_void *a, size_t len);' 2846 _Prototype_: 'acc_copyout_async(h_void *a, size_t len, int async);' 2847 _Prototype_: 'acc_copyout_finalize(h_void *a, size_t len);' 2848 _Prototype_: 'acc_copyout_finalize_async(h_void *a, size_t len, int 2849 async);' 2850 2851 _Fortran_: 2852 _Interface_: 'subroutine acc_copyout(a)' 2853 'type, dimension(:[,:]...) :: a' 2854 _Interface_: 'subroutine acc_copyout(a, len)' 2855 'type, dimension(:[,:]...) :: a' 2856 'integer len' 2857 _Interface_: 'subroutine acc_copyout_async(a, async)' 2858 'type, dimension(:[,:]...) :: a' 2859 'integer(acc_handle_kind) :: async' 2860 _Interface_: 'subroutine acc_copyout_async(a, len, async)' 2861 'type, dimension(:[,:]...) :: a' 2862 'integer len' 2863 'integer(acc_handle_kind) :: async' 2864 _Interface_: 'subroutine acc_copyout_finalize(a)' 2865 'type, dimension(:[,:]...) :: a' 2866 _Interface_: 'subroutine acc_copyout_finalize(a, len)' 2867 'type, dimension(:[,:]...) :: a' 2868 'integer len' 2869 _Interface_: 'subroutine acc_copyout_finalize_async(a, async)' 2870 'type, dimension(:[,:]...) :: a' 2871 'integer(acc_handle_kind) :: async' 2872 _Interface_: 'subroutine acc_copyout_finalize_async(a, len, async)' 2873 'type, dimension(:[,:]...) :: a' 2874 'integer len' 2875 'integer(acc_handle_kind) :: async' 2876 2877 _Reference_: 2878 OpenACC specification v2.6 (https://www.openacc.org), section 2879 3.2.22. 2880 2881 2882 File: libgomp.info, Node: acc_delete, Next: acc_update_device, Prev: acc_copyout, Up: OpenACC Runtime Library Routines 2883 2884 6.23 'acc_delete' - Free device memory. 2885 ======================================= 2886 2887 _Description_ 2888 This function frees previously allocated device memory specified by 2889 the device address A and the length of LEN bytes. 2890 2891 In Fortran, two (2) forms are supported. In the first form, A 2892 specifies a contiguous array section. The second form A specifies 2893 a variable or array element and LEN specifies the length in bytes. 2894 2895 _C/C++_: 2896 _Prototype_: 'acc_delete(h_void *a, size_t len);' 2897 _Prototype_: 'acc_delete_async(h_void *a, size_t len, int async);' 2898 _Prototype_: 'acc_delete_finalize(h_void *a, size_t len);' 2899 _Prototype_: 'acc_delete_finalize_async(h_void *a, size_t len, int 2900 async);' 2901 2902 _Fortran_: 2903 _Interface_: 'subroutine acc_delete(a)' 2904 'type, dimension(:[,:]...) :: a' 2905 _Interface_: 'subroutine acc_delete(a, len)' 2906 'type, dimension(:[,:]...) :: a' 2907 'integer len' 2908 _Interface_: 'subroutine acc_delete_async(a, async)' 2909 'type, dimension(:[,:]...) :: a' 2910 'integer(acc_handle_kind) :: async' 2911 _Interface_: 'subroutine acc_delete_async(a, len, async)' 2912 'type, dimension(:[,:]...) :: a' 2913 'integer len' 2914 'integer(acc_handle_kind) :: async' 2915 _Interface_: 'subroutine acc_delete_finalize(a)' 2916 'type, dimension(:[,:]...) :: a' 2917 _Interface_: 'subroutine acc_delete_finalize(a, len)' 2918 'type, dimension(:[,:]...) :: a' 2919 'integer len' 2920 _Interface_: 'subroutine acc_delete_async_finalize(a, async)' 2921 'type, dimension(:[,:]...) :: a' 2922 'integer(acc_handle_kind) :: async' 2923 _Interface_: 'subroutine acc_delete_async_finalize(a, len, async)' 2924 'type, dimension(:[,:]...) :: a' 2925 'integer len' 2926 'integer(acc_handle_kind) :: async' 2927 2928 _Reference_: 2929 OpenACC specification v2.6 (https://www.openacc.org), section 2930 3.2.23. 2931 2932 2933 File: libgomp.info, Node: acc_update_device, Next: acc_update_self, Prev: acc_delete, Up: OpenACC Runtime Library Routines 2934 2935 6.24 'acc_update_device' - Update device memory from mapped host memory. 2936 ======================================================================== 2937 2938 _Description_ 2939 This function updates the device copy from the previously mapped 2940 host memory. The host memory is specified with the host address A 2941 and a length of LEN bytes. 2942 2943 In Fortran, two (2) forms are supported. In the first form, A 2944 specifies a contiguous array section. The second form A specifies 2945 a variable or array element and LEN specifies the length in bytes. 2946 2947 _C/C++_: 2948 _Prototype_: 'acc_update_device(h_void *a, size_t len);' 2949 _Prototype_: 'acc_update_device(h_void *a, size_t len, async);' 2950 2951 _Fortran_: 2952 _Interface_: 'subroutine acc_update_device(a)' 2953 'type, dimension(:[,:]...) :: a' 2954 _Interface_: 'subroutine acc_update_device(a, len)' 2955 'type, dimension(:[,:]...) :: a' 2956 'integer len' 2957 _Interface_: 'subroutine acc_update_device_async(a, async)' 2958 'type, dimension(:[,:]...) :: a' 2959 'integer(acc_handle_kind) :: async' 2960 _Interface_: 'subroutine acc_update_device_async(a, len, async)' 2961 'type, dimension(:[,:]...) :: a' 2962 'integer len' 2963 'integer(acc_handle_kind) :: async' 2964 2965 _Reference_: 2966 OpenACC specification v2.6 (https://www.openacc.org), section 2967 3.2.24. 2968 2969 2970 File: libgomp.info, Node: acc_update_self, Next: acc_map_data, Prev: acc_update_device, Up: OpenACC Runtime Library Routines 2971 2972 6.25 'acc_update_self' - Update host memory from mapped device memory. 2973 ====================================================================== 2974 2975 _Description_ 2976 This function updates the host copy from the previously mapped 2977 device memory. The host memory is specified with the host address 2978 A and a length of LEN bytes. 2979 2980 In Fortran, two (2) forms are supported. In the first form, A 2981 specifies a contiguous array section. The second form A specifies 2982 a variable or array element and LEN specifies the length in bytes. 2983 2984 _C/C++_: 2985 _Prototype_: 'acc_update_self(h_void *a, size_t len);' 2986 _Prototype_: 'acc_update_self_async(h_void *a, size_t len, int 2987 async);' 2988 2989 _Fortran_: 2990 _Interface_: 'subroutine acc_update_self(a)' 2991 'type, dimension(:[,:]...) :: a' 2992 _Interface_: 'subroutine acc_update_self(a, len)' 2993 'type, dimension(:[,:]...) :: a' 2994 'integer len' 2995 _Interface_: 'subroutine acc_update_self_async(a, async)' 2996 'type, dimension(:[,:]...) :: a' 2997 'integer(acc_handle_kind) :: async' 2998 _Interface_: 'subroutine acc_update_self_async(a, len, async)' 2999 'type, dimension(:[,:]...) :: a' 3000 'integer len' 3001 'integer(acc_handle_kind) :: async' 3002 3003 _Reference_: 3004 OpenACC specification v2.6 (https://www.openacc.org), section 3005 3.2.25. 3006 3007 3008 File: libgomp.info, Node: acc_map_data, Next: acc_unmap_data, Prev: acc_update_self, Up: OpenACC Runtime Library Routines 3009 3010 6.26 'acc_map_data' - Map previously allocated device memory to host memory. 3011 ============================================================================ 3012 3013 _Description_ 3014 This function maps previously allocated device and host memory. 3015 The device memory is specified with the device address D. The host 3016 memory is specified with the host address H and a length of LEN. 3017 3018 _C/C++_: 3019 _Prototype_: 'acc_map_data(h_void *h, d_void *d, size_t len);' 3020 3021 _Reference_: 3022 OpenACC specification v2.6 (https://www.openacc.org), section 3023 3.2.26. 3024 3025 3026 File: libgomp.info, Node: acc_unmap_data, Next: acc_deviceptr, Prev: acc_map_data, Up: OpenACC Runtime Library Routines 3027 3028 6.27 'acc_unmap_data' - Unmap device memory from host memory. 3029 ============================================================= 3030 3031 _Description_ 3032 This function unmaps previously mapped device and host memory. The 3033 latter specified by H. 3034 3035 _C/C++_: 3036 _Prototype_: 'acc_unmap_data(h_void *h);' 3037 3038 _Reference_: 3039 OpenACC specification v2.6 (https://www.openacc.org), section 3040 3.2.27. 3041 3042 3043 File: libgomp.info, Node: acc_deviceptr, Next: acc_hostptr, Prev: acc_unmap_data, Up: OpenACC Runtime Library Routines 3044 3045 6.28 'acc_deviceptr' - Get device pointer associated with specific host address. 3046 ================================================================================ 3047 3048 _Description_ 3049 This function returns the device address that has been mapped to 3050 the host address specified by H. 3051 3052 _C/C++_: 3053 _Prototype_: 'void *acc_deviceptr(h_void *h);' 3054 3055 _Reference_: 3056 OpenACC specification v2.6 (https://www.openacc.org), section 3057 3.2.28. 3058 3059 3060 File: libgomp.info, Node: acc_hostptr, Next: acc_is_present, Prev: acc_deviceptr, Up: OpenACC Runtime Library Routines 3061 3062 6.29 'acc_hostptr' - Get host pointer associated with specific device address. 3063 ============================================================================== 3064 3065 _Description_ 3066 This function returns the host address that has been mapped to the 3067 device address specified by D. 3068 3069 _C/C++_: 3070 _Prototype_: 'void *acc_hostptr(d_void *d);' 3071 3072 _Reference_: 3073 OpenACC specification v2.6 (https://www.openacc.org), section 3074 3.2.29. 3075 3076 3077 File: libgomp.info, Node: acc_is_present, Next: acc_memcpy_to_device, Prev: acc_hostptr, Up: OpenACC Runtime Library Routines 3078 3079 6.30 'acc_is_present' - Indicate whether host variable / array is present on device. 3080 ==================================================================================== 3081 3082 _Description_ 3083 This function indicates whether the specified host address in A and 3084 a length of LEN bytes is present on the device. In C/C++, a 3085 non-zero value is returned to indicate the presence of the mapped 3086 memory on the device. A zero is returned to indicate the memory is 3087 not mapped on the device. 3088 3089 In Fortran, two (2) forms are supported. In the first form, A 3090 specifies a contiguous array section. The second form A specifies 3091 a variable or array element and LEN specifies the length in bytes. 3092 If the host memory is mapped to device memory, then a 'true' is 3093 returned. Otherwise, a 'false' is return to indicate the mapped 3094 memory is not present. 3095 3096 _C/C++_: 3097 _Prototype_: 'int acc_is_present(h_void *a, size_t len);' 3098 3099 _Fortran_: 3100 _Interface_: 'function acc_is_present(a)' 3101 'type, dimension(:[,:]...) :: a' 3102 'logical acc_is_present' 3103 _Interface_: 'function acc_is_present(a, len)' 3104 'type, dimension(:[,:]...) :: a' 3105 'integer len' 3106 'logical acc_is_present' 3107 3108 _Reference_: 3109 OpenACC specification v2.6 (https://www.openacc.org), section 3110 3.2.30. 3111 3112 3113 File: libgomp.info, Node: acc_memcpy_to_device, Next: acc_memcpy_from_device, Prev: acc_is_present, Up: OpenACC Runtime Library Routines 3114 3115 6.31 'acc_memcpy_to_device' - Copy host memory to device memory. 3116 ================================================================ 3117 3118 _Description_ 3119 This function copies host memory specified by host address of SRC 3120 to device memory specified by the device address DEST for a length 3121 of BYTES bytes. 3122 3123 _C/C++_: 3124 _Prototype_: 'acc_memcpy_to_device(d_void *dest, h_void *src, size_t 3125 bytes);' 3126 3127 _Reference_: 3128 OpenACC specification v2.6 (https://www.openacc.org), section 3129 3.2.31. 3130 3131 3132 File: libgomp.info, Node: acc_memcpy_from_device, Next: acc_attach, Prev: acc_memcpy_to_device, Up: OpenACC Runtime Library Routines 3133 3134 6.32 'acc_memcpy_from_device' - Copy device memory to host memory. 3135 ================================================================== 3136 3137 _Description_ 3138 This function copies host memory specified by host address of SRC 3139 from device memory specified by the device address DEST for a 3140 length of BYTES bytes. 3141 3142 _C/C++_: 3143 _Prototype_: 'acc_memcpy_from_device(d_void *dest, h_void *src, 3144 size_t bytes);' 3145 3146 _Reference_: 3147 OpenACC specification v2.6 (https://www.openacc.org), section 3148 3.2.32. 3149 3150 3151 File: libgomp.info, Node: acc_attach, Next: acc_detach, Prev: acc_memcpy_from_device, Up: OpenACC Runtime Library Routines 3152 3153 6.33 'acc_attach' - Let device pointer point to device-pointer target. 3154 ====================================================================== 3155 3156 _Description_ 3157 This function updates a pointer on the device from pointing to a 3158 host-pointer address to pointing to the corresponding device data. 3159 3160 _C/C++_: 3161 _Prototype_: 'acc_attach(h_void **ptr);' 3162 _Prototype_: 'acc_attach_async(h_void **ptr, int async);' 3163 3164 _Reference_: 3165 OpenACC specification v2.6 (https://www.openacc.org), section 3166 3.2.34. 3167 3168 3169 File: libgomp.info, Node: acc_detach, Next: acc_get_current_cuda_device, Prev: acc_attach, Up: OpenACC Runtime Library Routines 3170 3171 6.34 'acc_detach' - Let device pointer point to host-pointer target. 3172 ==================================================================== 3173 3174 _Description_ 3175 This function updates a pointer on the device from pointing to a 3176 device-pointer address to pointing to the corresponding host data. 3177 3178 _C/C++_: 3179 _Prototype_: 'acc_detach(h_void **ptr);' 3180 _Prototype_: 'acc_detach_async(h_void **ptr, int async);' 3181 _Prototype_: 'acc_detach_finalize(h_void **ptr);' 3182 _Prototype_: 'acc_detach_finalize_async(h_void **ptr, int async);' 3183 3184 _Reference_: 3185 OpenACC specification v2.6 (https://www.openacc.org), section 3186 3.2.35. 3187 3188 3189 File: libgomp.info, Node: acc_get_current_cuda_device, Next: acc_get_current_cuda_context, Prev: acc_detach, Up: OpenACC Runtime Library Routines 3190 3191 6.35 'acc_get_current_cuda_device' - Get CUDA device handle. 3192 ============================================================ 3193 3194 _Description_ 3195 This function returns the CUDA device handle. This handle is the 3196 same as used by the CUDA Runtime or Driver API's. 3197 3198 _C/C++_: 3199 _Prototype_: 'void *acc_get_current_cuda_device(void);' 3200 3201 _Reference_: 3202 OpenACC specification v2.6 (https://www.openacc.org), section 3203 A.2.1.1. 3204 3205 3206 File: libgomp.info, Node: acc_get_current_cuda_context, Next: acc_get_cuda_stream, Prev: acc_get_current_cuda_device, Up: OpenACC Runtime Library Routines 3207 3208 6.36 'acc_get_current_cuda_context' - Get CUDA context handle. 3209 ============================================================== 3210 3211 _Description_ 3212 This function returns the CUDA context handle. This handle is the 3213 same as used by the CUDA Runtime or Driver API's. 3214 3215 _C/C++_: 3216 _Prototype_: 'void *acc_get_current_cuda_context(void);' 3217 3218 _Reference_: 3219 OpenACC specification v2.6 (https://www.openacc.org), section 3220 A.2.1.2. 3221 3222 3223 File: libgomp.info, Node: acc_get_cuda_stream, Next: acc_set_cuda_stream, Prev: acc_get_current_cuda_context, Up: OpenACC Runtime Library Routines 3224 3225 6.37 'acc_get_cuda_stream' - Get CUDA stream handle. 3226 ==================================================== 3227 3228 _Description_ 3229 This function returns the CUDA stream handle for the queue ASYNC. 3230 This handle is the same as used by the CUDA Runtime or Driver 3231 API's. 3232 3233 _C/C++_: 3234 _Prototype_: 'void *acc_get_cuda_stream(int async);' 3235 3236 _Reference_: 3237 OpenACC specification v2.6 (https://www.openacc.org), section 3238 A.2.1.3. 3239 3240 3241 File: libgomp.info, Node: acc_set_cuda_stream, Next: acc_prof_register, Prev: acc_get_cuda_stream, Up: OpenACC Runtime Library Routines 3242 3243 6.38 'acc_set_cuda_stream' - Set CUDA stream handle. 3244 ==================================================== 3245 3246 _Description_ 3247 This function associates the stream handle specified by STREAM with 3248 the queue ASYNC. 3249 3250 This cannot be used to change the stream handle associated with 3251 'acc_async_sync'. 3252 3253 The return value is not specified. 3254 3255 _C/C++_: 3256 _Prototype_: 'int acc_set_cuda_stream(int async, void *stream);' 3257 3258 _Reference_: 3259 OpenACC specification v2.6 (https://www.openacc.org), section 3260 A.2.1.4. 3261 3262 3263 File: libgomp.info, Node: acc_prof_register, Next: acc_prof_unregister, Prev: acc_set_cuda_stream, Up: OpenACC Runtime Library Routines 3264 3265 6.39 'acc_prof_register' - Register callbacks. 3266 ============================================== 3267 3268 _Description_: 3269 This function registers callbacks. 3270 3271 _C/C++_: 3272 _Prototype_: 'void acc_prof_register (acc_event_t, acc_prof_callback, 3273 acc_register_t);' 3274 3275 _See also_: 3276 *note OpenACC Profiling Interface:: 3277 3278 _Reference_: 3279 OpenACC specification v2.6 (https://www.openacc.org), section 5.3. 3280 3281 3282 File: libgomp.info, Node: acc_prof_unregister, Next: acc_prof_lookup, Prev: acc_prof_register, Up: OpenACC Runtime Library Routines 3283 3284 6.40 'acc_prof_unregister' - Unregister callbacks. 3285 ================================================== 3286 3287 _Description_: 3288 This function unregisters callbacks. 3289 3290 _C/C++_: 3291 _Prototype_: 'void acc_prof_unregister (acc_event_t, 3292 acc_prof_callback, acc_register_t);' 3293 3294 _See also_: 3295 *note OpenACC Profiling Interface:: 3296 3297 _Reference_: 3298 OpenACC specification v2.6 (https://www.openacc.org), section 5.3. 3299 3300 3301 File: libgomp.info, Node: acc_prof_lookup, Next: acc_register_library, Prev: acc_prof_unregister, Up: OpenACC Runtime Library Routines 3302 3303 6.41 'acc_prof_lookup' - Obtain inquiry functions. 3304 ================================================== 3305 3306 _Description_: 3307 Function to obtain inquiry functions. 3308 3309 _C/C++_: 3310 _Prototype_: 'acc_query_fn acc_prof_lookup (const char *);' 3311 3312 _See also_: 3313 *note OpenACC Profiling Interface:: 3314 3315 _Reference_: 3316 OpenACC specification v2.6 (https://www.openacc.org), section 5.3. 3317 3318 3319 File: libgomp.info, Node: acc_register_library, Prev: acc_prof_lookup, Up: OpenACC Runtime Library Routines 3320 3321 6.42 'acc_register_library' - Library registration. 3322 =================================================== 3323 3324 _Description_: 3325 Function for library registration. 3326 3327 _C/C++_: 3328 _Prototype_: 'void acc_register_library (acc_prof_reg, acc_prof_reg, 3329 acc_prof_lookup_func);' 3330 3331 _See also_: 3332 *note OpenACC Profiling Interface::, *note ACC_PROFLIB:: 3333 3334 _Reference_: 3335 OpenACC specification v2.6 (https://www.openacc.org), section 5.3. 3336 3337 3338 File: libgomp.info, Node: OpenACC Environment Variables, Next: CUDA Streams Usage, Prev: OpenACC Runtime Library Routines, Up: Top 3339 3340 7 OpenACC Environment Variables 3341 ******************************* 3342 3343 The variables 'ACC_DEVICE_TYPE' and 'ACC_DEVICE_NUM' are defined by 3344 section 4 of the OpenACC specification in version 2.0. The variable 3345 'ACC_PROFLIB' is defined by section 4 of the OpenACC specification in 3346 version 2.6. The variable 'GCC_ACC_NOTIFY' is used for diagnostic 3347 purposes. 3348 3349 * Menu: 3350 3351 * ACC_DEVICE_TYPE:: 3352 * ACC_DEVICE_NUM:: 3353 * ACC_PROFLIB:: 3354 * GCC_ACC_NOTIFY:: 3355 3356 3357 File: libgomp.info, Node: ACC_DEVICE_TYPE, Next: ACC_DEVICE_NUM, Up: OpenACC Environment Variables 3358 3359 7.1 'ACC_DEVICE_TYPE' 3360 ===================== 3361 3362 _Reference_: 3363 OpenACC specification v2.6 (https://www.openacc.org), section 4.1. 3364 3365 3366 File: libgomp.info, Node: ACC_DEVICE_NUM, Next: ACC_PROFLIB, Prev: ACC_DEVICE_TYPE, Up: OpenACC Environment Variables 3367 3368 7.2 'ACC_DEVICE_NUM' 3369 ==================== 3370 3371 _Reference_: 3372 OpenACC specification v2.6 (https://www.openacc.org), section 4.2. 3373 3374 3375 File: libgomp.info, Node: ACC_PROFLIB, Next: GCC_ACC_NOTIFY, Prev: ACC_DEVICE_NUM, Up: OpenACC Environment Variables 3376 3377 7.3 'ACC_PROFLIB' 3378 ================= 3379 3380 _See also_: 3381 *note acc_register_library::, *note OpenACC Profiling Interface:: 3382 3383 _Reference_: 3384 OpenACC specification v2.6 (https://www.openacc.org), section 4.3. 3385 3386 3387 File: libgomp.info, Node: GCC_ACC_NOTIFY, Prev: ACC_PROFLIB, Up: OpenACC Environment Variables 3388 3389 7.4 'GCC_ACC_NOTIFY' 3390 ==================== 3391 3392 _Description_: 3393 Print debug information pertaining to the accelerator. 3394 3395 3396 File: libgomp.info, Node: CUDA Streams Usage, Next: OpenACC Library Interoperability, Prev: OpenACC Environment Variables, Up: Top 3397 3398 8 CUDA Streams Usage 3399 ******************** 3400 3401 This applies to the 'nvptx' plugin only. 3402 3403 The library provides elements that perform asynchronous movement of 3404 data and asynchronous operation of computing constructs. This 3405 asynchronous functionality is implemented by making use of CUDA 3406 streams(1). 3407 3408 The primary means by that the asynchronous functionality is accessed 3409 is through the use of those OpenACC directives which make use of the 3410 'async' and 'wait' clauses. When the 'async' clause is first used with 3411 a directive, it creates a CUDA stream. If an 'async-argument' is used 3412 with the 'async' clause, then the stream is associated with the 3413 specified 'async-argument'. 3414 3415 Following the creation of an association between a CUDA stream and 3416 the 'async-argument' of an 'async' clause, both the 'wait' clause and 3417 the 'wait' directive can be used. When either the clause or directive 3418 is used after stream creation, it creates a rendezvous point whereby 3419 execution waits until all operations associated with the 3420 'async-argument', that is, stream, have completed. 3421 3422 Normally, the management of the streams that are created as a result 3423 of using the 'async' clause, is done without any intervention by the 3424 caller. This implies the association between the 'async-argument' and 3425 the CUDA stream will be maintained for the lifetime of the program. 3426 However, this association can be changed through the use of the library 3427 function 'acc_set_cuda_stream'. When the function 'acc_set_cuda_stream' 3428 is called, the CUDA stream that was originally associated with the 3429 'async' clause will be destroyed. Caution should be taken when changing 3430 the association as subsequent references to the 'async-argument' refer 3431 to a different CUDA stream. 3432 3433 ---------- Footnotes ---------- 3434 3435 (1) See "Stream Management" in "CUDA Driver API", TRM-06703-001, 3436 Version 5.5, for additional information 3437 3438 3439 File: libgomp.info, Node: OpenACC Library Interoperability, Next: OpenACC Profiling Interface, Prev: CUDA Streams Usage, Up: Top 3440 3441 9 OpenACC Library Interoperability 3442 ********************************** 3443 3444 9.1 Introduction 3445 ================ 3446 3447 The OpenACC library uses the CUDA Driver API, and may interact with 3448 programs that use the Runtime library directly, or another library based 3449 on the Runtime library, e.g., CUBLAS(1). This chapter describes the use 3450 cases and what changes are required in order to use both the OpenACC 3451 library and the CUBLAS and Runtime libraries within a program. 3452 3453 9.2 First invocation: NVIDIA CUBLAS library API 3454 =============================================== 3455 3456 In this first use case (see below), a function in the CUBLAS library is 3457 called prior to any of the functions in the OpenACC library. More 3458 specifically, the function 'cublasCreate()'. 3459 3460 When invoked, the function initializes the library and allocates the 3461 hardware resources on the host and the device on behalf of the caller. 3462 Once the initialization and allocation has completed, a handle is 3463 returned to the caller. The OpenACC library also requires 3464 initialization and allocation of hardware resources. Since the CUBLAS 3465 library has already allocated the hardware resources for the device, all 3466 that is left to do is to initialize the OpenACC library and acquire the 3467 hardware resources on the host. 3468 3469 Prior to calling the OpenACC function that initializes the library 3470 and allocate the host hardware resources, you need to acquire the device 3471 number that was allocated during the call to 'cublasCreate()'. The 3472 invoking of the runtime library function 'cudaGetDevice()' accomplishes 3473 this. Once acquired, the device number is passed along with the device 3474 type as parameters to the OpenACC library function 3475 'acc_set_device_num()'. 3476 3477 Once the call to 'acc_set_device_num()' has completed, the OpenACC 3478 library uses the context that was created during the call to 3479 'cublasCreate()'. In other words, both libraries will be sharing the 3480 same context. 3481 3482 /* Create the handle */ 3483 s = cublasCreate(&h); 3484 if (s != CUBLAS_STATUS_SUCCESS) 3485 { 3486 fprintf(stderr, "cublasCreate failed %d\n", s); 3487 exit(EXIT_FAILURE); 3488 } 3489 3490 /* Get the device number */ 3491 e = cudaGetDevice(&dev); 3492 if (e != cudaSuccess) 3493 { 3494 fprintf(stderr, "cudaGetDevice failed %d\n", e); 3495 exit(EXIT_FAILURE); 3496 } 3497 3498 /* Initialize OpenACC library and use device 'dev' */ 3499 acc_set_device_num(dev, acc_device_nvidia); 3500 3501 Use Case 1 3502 3503 9.3 First invocation: OpenACC library API 3504 ========================================= 3505 3506 In this second use case (see below), a function in the OpenACC library 3507 is called prior to any of the functions in the CUBLAS library. More 3508 specificially, the function 'acc_set_device_num()'. 3509 3510 In the use case presented here, the function 'acc_set_device_num()' 3511 is used to both initialize the OpenACC library and allocate the hardware 3512 resources on the host and the device. In the call to the function, the 3513 call parameters specify which device to use and what device type to use, 3514 i.e., 'acc_device_nvidia'. It should be noted that this is but one 3515 method to initialize the OpenACC library and allocate the appropriate 3516 hardware resources. Other methods are available through the use of 3517 environment variables and these will be discussed in the next section. 3518 3519 Once the call to 'acc_set_device_num()' has completed, other OpenACC 3520 functions can be called as seen with multiple calls being made to 3521 'acc_copyin()'. In addition, calls can be made to functions in the 3522 CUBLAS library. In the use case a call to 'cublasCreate()' is made 3523 subsequent to the calls to 'acc_copyin()'. As seen in the previous use 3524 case, a call to 'cublasCreate()' initializes the CUBLAS library and 3525 allocates the hardware resources on the host and the device. However, 3526 since the device has already been allocated, 'cublasCreate()' will only 3527 initialize the CUBLAS library and allocate the appropriate hardware 3528 resources on the host. The context that was created as part of the 3529 OpenACC initialization is shared with the CUBLAS library, similarly to 3530 the first use case. 3531 3532 dev = 0; 3533 3534 acc_set_device_num(dev, acc_device_nvidia); 3535 3536 /* Copy the first set to the device */ 3537 d_X = acc_copyin(&h_X[0], N * sizeof (float)); 3538 if (d_X == NULL) 3539 { 3540 fprintf(stderr, "copyin error h_X\n"); 3541 exit(EXIT_FAILURE); 3542 } 3543 3544 /* Copy the second set to the device */ 3545 d_Y = acc_copyin(&h_Y1[0], N * sizeof (float)); 3546 if (d_Y == NULL) 3547 { 3548 fprintf(stderr, "copyin error h_Y1\n"); 3549 exit(EXIT_FAILURE); 3550 } 3551 3552 /* Create the handle */ 3553 s = cublasCreate(&h); 3554 if (s != CUBLAS_STATUS_SUCCESS) 3555 { 3556 fprintf(stderr, "cublasCreate failed %d\n", s); 3557 exit(EXIT_FAILURE); 3558 } 3559 3560 /* Perform saxpy using CUBLAS library function */ 3561 s = cublasSaxpy(h, N, &alpha, d_X, 1, d_Y, 1); 3562 if (s != CUBLAS_STATUS_SUCCESS) 3563 { 3564 fprintf(stderr, "cublasSaxpy failed %d\n", s); 3565 exit(EXIT_FAILURE); 3566 } 3567 3568 /* Copy the results from the device */ 3569 acc_memcpy_from_device(&h_Y1[0], d_Y, N * sizeof (float)); 3570 3571 Use Case 2 3572 3573 9.4 OpenACC library and environment variables 3574 ============================================= 3575 3576 There are two environment variables associated with the OpenACC library 3577 that may be used to control the device type and device number: 3578 'ACC_DEVICE_TYPE' and 'ACC_DEVICE_NUM', respectively. These two 3579 environment variables can be used as an alternative to calling 3580 'acc_set_device_num()'. As seen in the second use case, the device type 3581 and device number were specified using 'acc_set_device_num()'. If 3582 however, the aforementioned environment variables were set, then the 3583 call to 'acc_set_device_num()' would not be required. 3584 3585 The use of the environment variables is only relevant when an OpenACC 3586 function is called prior to a call to 'cudaCreate()'. If 'cudaCreate()' 3587 is called prior to a call to an OpenACC function, then you must call 3588 'acc_set_device_num()'(2) 3589 3590 ---------- Footnotes ---------- 3591 3592 (1) See section 2.26, "Interactions with the CUDA Driver API" in 3593 "CUDA Runtime API", Version 5.5, and section 2.27, "VDPAU 3594 Interoperability", in "CUDA Driver API", TRM-06703-001, Version 5.5, for 3595 additional information on library interoperability. 3596 3597 (2) More complete information about 'ACC_DEVICE_TYPE' and 3598 'ACC_DEVICE_NUM' can be found in sections 4.1 and 4.2 of the OpenACC 3599 (https://www.openacc.org) Application Programming Interface, Version 3600 2.6. 3601 3602 3603 File: libgomp.info, Node: OpenACC Profiling Interface, Next: The libgomp ABI, Prev: OpenACC Library Interoperability, Up: Top 3604 3605 10 OpenACC Profiling Interface 3606 ****************************** 3607 3608 10.1 Implementation Status and Implementation-Defined Behavior 3609 ============================================================== 3610 3611 We're implementing the OpenACC Profiling Interface as defined by the 3612 OpenACC 2.6 specification. We're clarifying some aspects here as 3613 _implementation-defined behavior_, while they're still under discussion 3614 within the OpenACC Technical Committee. 3615 3616 This implementation is tuned to keep the performance impact as low as 3617 possible for the (very common) case that the Profiling Interface is not 3618 enabled. This is relevant, as the Profiling Interface affects all the 3619 _hot_ code paths (in the target code, not in the offloaded code). Users 3620 of the OpenACC Profiling Interface can be expected to understand that 3621 performance will be impacted to some degree once the Profiling Interface 3622 has gotten enabled: for example, because of the _runtime_ (libgomp) 3623 calling into a third-party _library_ for every event that has been 3624 registered. 3625 3626 We're not yet accounting for the fact that 'OpenACC events may occur 3627 during event processing'. We just handle one case specially, as 3628 required by CUDA 9.0 'nvprof', that 'acc_get_device_type' (*note 3629 acc_get_device_type::)) may be called from 'acc_ev_device_init_start', 3630 'acc_ev_device_init_end' callbacks. 3631 3632 We're not yet implementing initialization via a 3633 'acc_register_library' function that is either statically linked in, or 3634 dynamically via 'LD_PRELOAD'. Initialization via 'acc_register_library' 3635 functions dynamically loaded via the 'ACC_PROFLIB' environment variable 3636 does work, as does directly calling 'acc_prof_register', 3637 'acc_prof_unregister', 'acc_prof_lookup'. 3638 3639 As currently there are no inquiry functions defined, calls to 3640 'acc_prof_lookup' will always return 'NULL'. 3641 3642 There aren't separate _start_, _stop_ events defined for the event 3643 types 'acc_ev_create', 'acc_ev_delete', 'acc_ev_alloc', 'acc_ev_free'. 3644 It's not clear if these should be triggered before or after the actual 3645 device-specific call is made. We trigger them after. 3646 3647 Remarks about data provided to callbacks: 3648 3649 'acc_prof_info.event_type' 3650 It's not clear if for _nested_ event callbacks (for example, 3651 'acc_ev_enqueue_launch_start' as part of a parent compute 3652 construct), this should be set for the nested event 3653 ('acc_ev_enqueue_launch_start'), or if the value of the parent 3654 construct should remain ('acc_ev_compute_construct_start'). In 3655 this implementation, the value will generally correspond to the 3656 innermost nested event type. 3657 3658 'acc_prof_info.device_type' 3659 3660 * For 'acc_ev_compute_construct_start', and in presence of an 3661 'if' clause with _false_ argument, this will still refer to 3662 the offloading device type. It's not clear if that's the 3663 expected behavior. 3664 3665 * Complementary to the item before, for 3666 'acc_ev_compute_construct_end', this is set to 3667 'acc_device_host' in presence of an 'if' clause with _false_ 3668 argument. It's not clear if that's the expected behavior. 3669 3670 'acc_prof_info.thread_id' 3671 Always '-1'; not yet implemented. 3672 3673 'acc_prof_info.async' 3674 3675 * Not yet implemented correctly for 3676 'acc_ev_compute_construct_start'. 3677 3678 * In a compute construct, for host-fallback 3679 execution/'acc_device_host' it will always be 3680 'acc_async_sync'. It's not clear if that's the expected 3681 behavior. 3682 3683 * For 'acc_ev_device_init_start' and 'acc_ev_device_init_end', 3684 it will always be 'acc_async_sync'. It's not clear if that's 3685 the expected behavior. 3686 3687 'acc_prof_info.async_queue' 3688 There is no 'limited number of asynchronous queues' in libgomp. 3689 This will always have the same value as 'acc_prof_info.async'. 3690 3691 'acc_prof_info.src_file' 3692 Always 'NULL'; not yet implemented. 3693 3694 'acc_prof_info.func_name' 3695 Always 'NULL'; not yet implemented. 3696 3697 'acc_prof_info.line_no' 3698 Always '-1'; not yet implemented. 3699 3700 'acc_prof_info.end_line_no' 3701 Always '-1'; not yet implemented. 3702 3703 'acc_prof_info.func_line_no' 3704 Always '-1'; not yet implemented. 3705 3706 'acc_prof_info.func_end_line_no' 3707 Always '-1'; not yet implemented. 3708 3709 'acc_event_info.event_type', 'acc_event_info.*.event_type' 3710 Relating to 'acc_prof_info.event_type' discussed above, in this 3711 implementation, this will always be the same value as 3712 'acc_prof_info.event_type'. 3713 3714 'acc_event_info.*.parent_construct' 3715 3716 * Will be 'acc_construct_parallel' for all OpenACC compute 3717 constructs as well as many OpenACC Runtime API calls; should 3718 be the one matching the actual construct, or 3719 'acc_construct_runtime_api', respectively. 3720 3721 * Will be 'acc_construct_enter_data' or 3722 'acc_construct_exit_data' when processing variable mappings 3723 specified in OpenACC _declare_ directives; should be 3724 'acc_construct_declare'. 3725 3726 * For implicit 'acc_ev_device_init_start', 3727 'acc_ev_device_init_end', and explicit as well as implicit 3728 'acc_ev_alloc', 'acc_ev_free', 'acc_ev_enqueue_upload_start', 3729 'acc_ev_enqueue_upload_end', 'acc_ev_enqueue_download_start', 3730 and 'acc_ev_enqueue_download_end', will be 3731 'acc_construct_parallel'; should reflect the real parent 3732 construct. 3733 3734 'acc_event_info.*.implicit' 3735 For 'acc_ev_alloc', 'acc_ev_free', 'acc_ev_enqueue_upload_start', 3736 'acc_ev_enqueue_upload_end', 'acc_ev_enqueue_download_start', and 3737 'acc_ev_enqueue_download_end', this currently will be '1' also for 3738 explicit usage. 3739 3740 'acc_event_info.data_event.var_name' 3741 Always 'NULL'; not yet implemented. 3742 3743 'acc_event_info.data_event.host_ptr' 3744 For 'acc_ev_alloc', and 'acc_ev_free', this is always 'NULL'. 3745 3746 'typedef union acc_api_info' 3747 ... as printed in '5.2.3. Third Argument: API-Specific 3748 Information'. This should obviously be 'typedef _struct_ 3749 acc_api_info'. 3750 3751 'acc_api_info.device_api' 3752 Possibly not yet implemented correctly for 3753 'acc_ev_compute_construct_start', 'acc_ev_device_init_start', 3754 'acc_ev_device_init_end': will always be 'acc_device_api_none' for 3755 these event types. For 'acc_ev_enter_data_start', it will be 3756 'acc_device_api_none' in some cases. 3757 3758 'acc_api_info.device_type' 3759 Always the same as 'acc_prof_info.device_type'. 3760 3761 'acc_api_info.vendor' 3762 Always '-1'; not yet implemented. 3763 3764 'acc_api_info.device_handle' 3765 Always 'NULL'; not yet implemented. 3766 3767 'acc_api_info.context_handle' 3768 Always 'NULL'; not yet implemented. 3769 3770 'acc_api_info.async_handle' 3771 Always 'NULL'; not yet implemented. 3772 3773 Remarks about certain event types: 3774 3775 'acc_ev_device_init_start', 'acc_ev_device_init_end' 3776 3777 * When a compute construct triggers implicit 3778 'acc_ev_device_init_start' and 'acc_ev_device_init_end' 3779 events, they currently aren't _nested within_ the 3780 corresponding 'acc_ev_compute_construct_start' and 3781 'acc_ev_compute_construct_end', but they're currently observed 3782 _before_ 'acc_ev_compute_construct_start'. It's not clear 3783 what to do: the standard asks us provide a lot of details to 3784 the 'acc_ev_compute_construct_start' callback, without 3785 (implicitly) initializing a device before? 3786 3787 * Callbacks for these event types will not be invoked for calls 3788 to the 'acc_set_device_type' and 'acc_set_device_num' 3789 functions. It's not clear if they should be. 3790 3791 'acc_ev_enter_data_start', 'acc_ev_enter_data_end', 'acc_ev_exit_data_start', 'acc_ev_exit_data_end' 3792 3793 * Callbacks for these event types will also be invoked for 3794 OpenACC _host_data_ constructs. It's not clear if they should 3795 be. 3796 3797 * Callbacks for these event types will also be invoked when 3798 processing variable mappings specified in OpenACC _declare_ 3799 directives. It's not clear if they should be. 3800 3801 Callbacks for the following event types will be invoked, but dispatch 3802 and information provided therein has not yet been thoroughly reviewed: 3803 3804 * 'acc_ev_alloc' 3805 * 'acc_ev_free' 3806 * 'acc_ev_update_start', 'acc_ev_update_end' 3807 * 'acc_ev_enqueue_upload_start', 'acc_ev_enqueue_upload_end' 3808 * 'acc_ev_enqueue_download_start', 'acc_ev_enqueue_download_end' 3809 3810 During device initialization, and finalization, respectively, 3811 callbacks for the following event types will not yet be invoked: 3812 3813 * 'acc_ev_alloc' 3814 * 'acc_ev_free' 3815 3816 Callbacks for the following event types have not yet been 3817 implemented, so currently won't be invoked: 3818 3819 * 'acc_ev_device_shutdown_start', 'acc_ev_device_shutdown_end' 3820 * 'acc_ev_runtime_shutdown' 3821 * 'acc_ev_create', 'acc_ev_delete' 3822 * 'acc_ev_wait_start', 'acc_ev_wait_end' 3823 3824 For the following runtime library functions, not all expected 3825 callbacks will be invoked (mostly concerning implicit device 3826 initialization): 3827 3828 * 'acc_get_num_devices' 3829 * 'acc_set_device_type' 3830 * 'acc_get_device_type' 3831 * 'acc_set_device_num' 3832 * 'acc_get_device_num' 3833 * 'acc_init' 3834 * 'acc_shutdown' 3835 3836 Aside from implicit device initialization, for the following runtime 3837 library functions, no callbacks will be invoked for shared-memory 3838 offloading devices (it's not clear if they should be): 3839 3840 * 'acc_malloc' 3841 * 'acc_free' 3842 * 'acc_copyin', 'acc_present_or_copyin', 'acc_copyin_async' 3843 * 'acc_create', 'acc_present_or_create', 'acc_create_async' 3844 * 'acc_copyout', 'acc_copyout_async', 'acc_copyout_finalize', 3845 'acc_copyout_finalize_async' 3846 * 'acc_delete', 'acc_delete_async', 'acc_delete_finalize', 3847 'acc_delete_finalize_async' 3848 * 'acc_update_device', 'acc_update_device_async' 3849 * 'acc_update_self', 'acc_update_self_async' 3850 * 'acc_map_data', 'acc_unmap_data' 3851 * 'acc_memcpy_to_device', 'acc_memcpy_to_device_async' 3852 * 'acc_memcpy_from_device', 'acc_memcpy_from_device_async' 3853 3854 3855 File: libgomp.info, Node: The libgomp ABI, Next: Reporting Bugs, Prev: OpenACC Profiling Interface, Up: Top 3856 3857 11 The libgomp ABI 3858 ****************** 3859 3860 The following sections present notes on the external ABI as presented by 3861 libgomp. Only maintainers should need them. 3862 3863 * Menu: 3864 3865 * Implementing MASTER construct:: 3866 * Implementing CRITICAL construct:: 3867 * Implementing ATOMIC construct:: 3868 * Implementing FLUSH construct:: 3869 * Implementing BARRIER construct:: 3870 * Implementing THREADPRIVATE construct:: 3871 * Implementing PRIVATE clause:: 3872 * Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses:: 3873 * Implementing REDUCTION clause:: 3874 * Implementing PARALLEL construct:: 3875 * Implementing FOR construct:: 3876 * Implementing ORDERED construct:: 3877 * Implementing SECTIONS construct:: 3878 * Implementing SINGLE construct:: 3879 * Implementing OpenACC's PARALLEL construct:: 3880 3881 3882 File: libgomp.info, Node: Implementing MASTER construct, Next: Implementing CRITICAL construct, Up: The libgomp ABI 3883 3884 11.1 Implementing MASTER construct 3885 ================================== 3886 3887 if (omp_get_thread_num () == 0) 3888 block 3889 3890 Alternately, we generate two copies of the parallel subfunction and 3891 only include this in the version run by the primary thread. Surely this 3892 is not worthwhile though... 3893 3894 3895 File: libgomp.info, Node: Implementing CRITICAL construct, Next: Implementing ATOMIC construct, Prev: Implementing MASTER construct, Up: The libgomp ABI 3896 3897 11.2 Implementing CRITICAL construct 3898 ==================================== 3899 3900 Without a specified name, 3901 3902 void GOMP_critical_start (void); 3903 void GOMP_critical_end (void); 3904 3905 so that we don't get COPY relocations from libgomp to the main 3906 application. 3907 3908 With a specified name, use omp_set_lock and omp_unset_lock with name 3909 being transformed into a variable declared like 3910 3911 omp_lock_t gomp_critical_user_<name> __attribute__((common)) 3912 3913 Ideally the ABI would specify that all zero is a valid unlocked 3914 state, and so we wouldn't need to initialize this at startup. 3915 3916 3917 File: libgomp.info, Node: Implementing ATOMIC construct, Next: Implementing FLUSH construct, Prev: Implementing CRITICAL construct, Up: The libgomp ABI 3918 3919 11.3 Implementing ATOMIC construct 3920 ================================== 3921 3922 The target should implement the '__sync' builtins. 3923 3924 Failing that we could add 3925 3926 void GOMP_atomic_enter (void) 3927 void GOMP_atomic_exit (void) 3928 3929 which reuses the regular lock code, but with yet another lock object 3930 private to the library. 3931 3932 3933 File: libgomp.info, Node: Implementing FLUSH construct, Next: Implementing BARRIER construct, Prev: Implementing ATOMIC construct, Up: The libgomp ABI 3934 3935 11.4 Implementing FLUSH construct 3936 ================================= 3937 3938 Expands to the '__sync_synchronize' builtin. 3939 3940 3941 File: libgomp.info, Node: Implementing BARRIER construct, Next: Implementing THREADPRIVATE construct, Prev: Implementing FLUSH construct, Up: The libgomp ABI 3942 3943 11.5 Implementing BARRIER construct 3944 =================================== 3945 3946 void GOMP_barrier (void) 3947 3948 3949 File: libgomp.info, Node: Implementing THREADPRIVATE construct, Next: Implementing PRIVATE clause, Prev: Implementing BARRIER construct, Up: The libgomp ABI 3950 3951 11.6 Implementing THREADPRIVATE construct 3952 ========================================= 3953 3954 In _most_ cases we can map this directly to '__thread'. Except that OMP 3955 allows constructors for C++ objects. We can either refuse to support 3956 this (how often is it used?) or we can implement something akin to 3957 .ctors. 3958 3959 Even more ideally, this ctor feature is handled by extensions to the 3960 main pthreads library. Failing that, we can have a set of entry points 3961 to register ctor functions to be called. 3962 3963 3964 File: libgomp.info, Node: Implementing PRIVATE clause, Next: Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses, Prev: Implementing THREADPRIVATE construct, Up: The libgomp ABI 3965 3966 11.7 Implementing PRIVATE clause 3967 ================================ 3968 3969 In association with a PARALLEL, or within the lexical extent of a 3970 PARALLEL block, the variable becomes a local variable in the parallel 3971 subfunction. 3972 3973 In association with FOR or SECTIONS blocks, create a new automatic 3974 variable within the current function. This preserves the semantic of 3975 new variable creation. 3976 3977 3978 File: libgomp.info, Node: Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses, Next: Implementing REDUCTION clause, Prev: Implementing PRIVATE clause, Up: The libgomp ABI 3979 3980 11.8 Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses 3981 ========================================================================= 3982 3983 This seems simple enough for PARALLEL blocks. Create a private struct 3984 for communicating between the parent and subfunction. In the parent, 3985 copy in values for scalar and "small" structs; copy in addresses for 3986 others TREE_ADDRESSABLE types. In the subfunction, copy the value into 3987 the local variable. 3988 3989 It is not clear what to do with bare FOR or SECTION blocks. The only 3990 thing I can figure is that we do something like: 3991 3992 #pragma omp for firstprivate(x) lastprivate(y) 3993 for (int i = 0; i < n; ++i) 3994 body; 3995 3996 which becomes 3997 3998 { 3999 int x = x, y; 4000 4001 // for stuff 4002 4003 if (i == n) 4004 y = y; 4005 } 4006 4007 where the "x=x" and "y=y" assignments actually have different uids 4008 for the two variables, i.e. not something you could write directly in 4009 C. Presumably this only makes sense if the "outer" x and y are global 4010 variables. 4011 4012 COPYPRIVATE would work the same way, except the structure broadcast 4013 would have to happen via SINGLE machinery instead. 4014 4015 4016 File: libgomp.info, Node: Implementing REDUCTION clause, Next: Implementing PARALLEL construct, Prev: Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses, Up: The libgomp ABI 4017 4018 11.9 Implementing REDUCTION clause 4019 ================================== 4020 4021 The private struct mentioned in the previous section should have a 4022 pointer to an array of the type of the variable, indexed by the thread's 4023 TEAM_ID. The thread stores its final value into the array, and after 4024 the barrier, the primary thread iterates over the array to collect the 4025 values. 4026 4027 4028 File: libgomp.info, Node: Implementing PARALLEL construct, Next: Implementing FOR construct, Prev: Implementing REDUCTION clause, Up: The libgomp ABI 4029 4030 11.10 Implementing PARALLEL construct 4031 ===================================== 4032 4033 #pragma omp parallel 4034 { 4035 body; 4036 } 4037 4038 becomes 4039 4040 void subfunction (void *data) 4041 { 4042 use data; 4043 body; 4044 } 4045 4046 setup data; 4047 GOMP_parallel_start (subfunction, &data, num_threads); 4048 subfunction (&data); 4049 GOMP_parallel_end (); 4050 4051 void GOMP_parallel_start (void (*fn)(void *), void *data, unsigned num_threads) 4052 4053 The FN argument is the subfunction to be run in parallel. 4054 4055 The DATA argument is a pointer to a structure used to communicate 4056 data in and out of the subfunction, as discussed above with respect to 4057 FIRSTPRIVATE et al. 4058 4059 The NUM_THREADS argument is 1 if an IF clause is present and false, 4060 or the value of the NUM_THREADS clause, if present, or 0. 4061 4062 The function needs to create the appropriate number of threads and/or 4063 launch them from the dock. It needs to create the team structure and 4064 assign team ids. 4065 4066 void GOMP_parallel_end (void) 4067 4068 Tears down the team and returns us to the previous 4069 'omp_in_parallel()' state. 4070 4071 4072 File: libgomp.info, Node: Implementing FOR construct, Next: Implementing ORDERED construct, Prev: Implementing PARALLEL construct, Up: The libgomp ABI 4073 4074 11.11 Implementing FOR construct 4075 ================================ 4076 4077 #pragma omp parallel for 4078 for (i = lb; i <= ub; i++) 4079 body; 4080 4081 becomes 4082 4083 void subfunction (void *data) 4084 { 4085 long _s0, _e0; 4086 while (GOMP_loop_static_next (&_s0, &_e0)) 4087 { 4088 long _e1 = _e0, i; 4089 for (i = _s0; i < _e1; i++) 4090 body; 4091 } 4092 GOMP_loop_end_nowait (); 4093 } 4094 4095 GOMP_parallel_loop_static (subfunction, NULL, 0, lb, ub+1, 1, 0); 4096 subfunction (NULL); 4097 GOMP_parallel_end (); 4098 4099 #pragma omp for schedule(runtime) 4100 for (i = 0; i < n; i++) 4101 body; 4102 4103 becomes 4104 4105 { 4106 long i, _s0, _e0; 4107 if (GOMP_loop_runtime_start (0, n, 1, &_s0, &_e0)) 4108 do { 4109 long _e1 = _e0; 4110 for (i = _s0, i < _e0; i++) 4111 body; 4112 } while (GOMP_loop_runtime_next (&_s0, _&e0)); 4113 GOMP_loop_end (); 4114 } 4115 4116 Note that while it looks like there is trickiness to propagating a 4117 non-constant STEP, there isn't really. We're explicitly allowed to 4118 evaluate it as many times as we want, and any variables involved should 4119 automatically be handled as PRIVATE or SHARED like any other variables. 4120 So the expression should remain evaluable in the subfunction. We can 4121 also pull it into a local variable if we like, but since its supposed to 4122 remain unchanged, we can also not if we like. 4123 4124 If we have SCHEDULE(STATIC), and no ORDERED, then we ought to be able 4125 to get away with no work-sharing context at all, since we can simply 4126 perform the arithmetic directly in each thread to divide up the 4127 iterations. Which would mean that we wouldn't need to call any of these 4128 routines. 4129 4130 There are separate routines for handling loops with an ORDERED 4131 clause. Bookkeeping for that is non-trivial... 4132 4133 4134 File: libgomp.info, Node: Implementing ORDERED construct, Next: Implementing SECTIONS construct, Prev: Implementing FOR construct, Up: The libgomp ABI 4135 4136 11.12 Implementing ORDERED construct 4137 ==================================== 4138 4139 void GOMP_ordered_start (void) 4140 void GOMP_ordered_end (void) 4141 4142 4143 File: libgomp.info, Node: Implementing SECTIONS construct, Next: Implementing SINGLE construct, Prev: Implementing ORDERED construct, Up: The libgomp ABI 4144 4145 11.13 Implementing SECTIONS construct 4146 ===================================== 4147 4148 A block as 4149 4150 #pragma omp sections 4151 { 4152 #pragma omp section 4153 stmt1; 4154 #pragma omp section 4155 stmt2; 4156 #pragma omp section 4157 stmt3; 4158 } 4159 4160 becomes 4161 4162 for (i = GOMP_sections_start (3); i != 0; i = GOMP_sections_next ()) 4163 switch (i) 4164 { 4165 case 1: 4166 stmt1; 4167 break; 4168 case 2: 4169 stmt2; 4170 break; 4171 case 3: 4172 stmt3; 4173 break; 4174 } 4175 GOMP_barrier (); 4176 4177 4178 File: libgomp.info, Node: Implementing SINGLE construct, Next: Implementing OpenACC's PARALLEL construct, Prev: Implementing SECTIONS construct, Up: The libgomp ABI 4179 4180 11.14 Implementing SINGLE construct 4181 =================================== 4182 4183 A block like 4184 4185 #pragma omp single 4186 { 4187 body; 4188 } 4189 4190 becomes 4191 4192 if (GOMP_single_start ()) 4193 body; 4194 GOMP_barrier (); 4195 4196 while 4197 4198 #pragma omp single copyprivate(x) 4199 body; 4200 4201 becomes 4202 4203 datap = GOMP_single_copy_start (); 4204 if (datap == NULL) 4205 { 4206 body; 4207 data.x = x; 4208 GOMP_single_copy_end (&data); 4209 } 4210 else 4211 x = datap->x; 4212 GOMP_barrier (); 4213 4214 4215 File: libgomp.info, Node: Implementing OpenACC's PARALLEL construct, Prev: Implementing SINGLE construct, Up: The libgomp ABI 4216 4217 11.15 Implementing OpenACC's PARALLEL construct 4218 =============================================== 4219 4220 void GOACC_parallel () 4221 4222 4223 File: libgomp.info, Node: Reporting Bugs, Next: Copying, Prev: The libgomp ABI, Up: Top 4224 4225 12 Reporting Bugs 4226 ***************** 4227 4228 Bugs in the GNU Offloading and Multi Processing Runtime Library should 4229 be reported via Bugzilla (https://gcc.gnu.org/bugzilla/). Please add 4230 "openacc", or "openmp", or both to the keywords field in the bug report, 4231 as appropriate. 4232 4233 4234 File: libgomp.info, Node: Copying, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top 4235 4236 GNU General Public License 4237 ************************** 4238 4239 Version 3, 29 June 2007 4240 4241 Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/> 4242 4243 Everyone is permitted to copy and distribute verbatim copies of this 4244 license document, but changing it is not allowed. 4245 4246 Preamble 4247 ======== 4248 4249 The GNU General Public License is a free, copyleft license for software 4250 and other kinds of works. 4251 4252 The licenses for most software and other practical works are designed 4253 to take away your freedom to share and change the works. By contrast, 4254 the GNU General Public License is intended to guarantee your freedom to 4255 share and change all versions of a program-to make sure it remains free 4256 software for all its users. We, the Free Software Foundation, use the 4257 GNU General Public License for most of our software; it applies also to 4258 any other work released this way by its authors. You can apply it to 4259 your programs, too. 4260 4261 When we speak of free software, we are referring to freedom, not 4262 price. Our General Public Licenses are designed to make sure that you 4263 have the freedom to distribute copies of free software (and charge for 4264 them if you wish), that you receive source code or can get it if you 4265 want it, that you can change the software or use pieces of it in new 4266 free programs, and that you know you can do these things. 4267 4268 To protect your rights, we need to prevent others from denying you 4269 these rights or asking you to surrender the rights. Therefore, you have 4270 certain responsibilities if you distribute copies of the software, or if 4271 you modify it: responsibilities to respect the freedom of others. 4272 4273 For example, if you distribute copies of such a program, whether 4274 gratis or for a fee, you must pass on to the recipients the same 4275 freedoms that you received. You must make sure that they, too, receive 4276 or can get the source code. And you must show them these terms so they 4277 know their rights. 4278 4279 Developers that use the GNU GPL protect your rights with two steps: 4280 (1) assert copyright on the software, and (2) offer you this License 4281 giving you legal permission to copy, distribute and/or modify it. 4282 4283 For the developers' and authors' protection, the GPL clearly explains 4284 that there is no warranty for this free software. For both users' and 4285 authors' sake, the GPL requires that modified versions be marked as 4286 changed, so that their problems will not be attributed erroneously to 4287 authors of previous versions. 4288 4289 Some devices are designed to deny users access to install or run 4290 modified versions of the software inside them, although the manufacturer 4291 can do so. This is fundamentally incompatible with the aim of 4292 protecting users' freedom to change the software. The systematic 4293 pattern of such abuse occurs in the area of products for individuals to 4294 use, which is precisely where it is most unacceptable. Therefore, we 4295 have designed this version of the GPL to prohibit the practice for those 4296 products. If such problems arise substantially in other domains, we 4297 stand ready to extend this provision to those domains in future versions 4298 of the GPL, as needed to protect the freedom of users. 4299 4300 Finally, every program is threatened constantly by software patents. 4301 States should not allow patents to restrict development and use of 4302 software on general-purpose computers, but in those that do, we wish to 4303 avoid the special danger that patents applied to a free program could 4304 make it effectively proprietary. To prevent this, the GPL assures that 4305 patents cannot be used to render the program non-free. 4306 4307 The precise terms and conditions for copying, distribution and 4308 modification follow. 4309 4310 TERMS AND CONDITIONS 4311 ==================== 4312 4313 0. Definitions. 4314 4315 "This License" refers to version 3 of the GNU General Public 4316 License. 4317 4318 "Copyright" also means copyright-like laws that apply to other 4319 kinds of works, such as semiconductor masks. 4320 4321 "The Program" refers to any copyrightable work licensed under this 4322 License. Each licensee is addressed as "you". "Licensees" and 4323 "recipients" may be individuals or organizations. 4324 4325 To "modify" a work means to copy from or adapt all or part of the 4326 work in a fashion requiring copyright permission, other than the 4327 making of an exact copy. The resulting work is called a "modified 4328 version" of the earlier work or a work "based on" the earlier work. 4329 4330 A "covered work" means either the unmodified Program or a work 4331 based on the Program. 4332 4333 To "propagate" a work means to do anything with it that, without 4334 permission, would make you directly or secondarily liable for 4335 infringement under applicable copyright law, except executing it on 4336 a computer or modifying a private copy. Propagation includes 4337 copying, distribution (with or without modification), making 4338 available to the public, and in some countries other activities as 4339 well. 4340 4341 To "convey" a work means any kind of propagation that enables other 4342 parties to make or receive copies. Mere interaction with a user 4343 through a computer network, with no transfer of a copy, is not 4344 conveying. 4345 4346 An interactive user interface displays "Appropriate Legal Notices" 4347 to the extent that it includes a convenient and prominently visible 4348 feature that (1) displays an appropriate copyright notice, and (2) 4349 tells the user that there is no warranty for the work (except to 4350 the extent that warranties are provided), that licensees may convey 4351 the work under this License, and how to view a copy of this 4352 License. If the interface presents a list of user commands or 4353 options, such as a menu, a prominent item in the list meets this 4354 criterion. 4355 4356 1. Source Code. 4357 4358 The "source code" for a work means the preferred form of the work 4359 for making modifications to it. "Object code" means any non-source 4360 form of a work. 4361 4362 A "Standard Interface" means an interface that either is an 4363 official standard defined by a recognized standards body, or, in 4364 the case of interfaces specified for a particular programming 4365 language, one that is widely used among developers working in that 4366 language. 4367 4368 The "System Libraries" of an executable work include anything, 4369 other than the work as a whole, that (a) is included in the normal 4370 form of packaging a Major Component, but which is not part of that 4371 Major Component, and (b) serves only to enable use of the work with 4372 that Major Component, or to implement a Standard Interface for 4373 which an implementation is available to the public in source code 4374 form. A "Major Component", in this context, means a major 4375 essential component (kernel, window system, and so on) of the 4376 specific operating system (if any) on which the executable work 4377 runs, or a compiler used to produce the work, or an object code 4378 interpreter used to run it. 4379 4380 The "Corresponding Source" for a work in object code form means all 4381 the source code needed to generate, install, and (for an executable 4382 work) run the object code and to modify the work, including scripts 4383 to control those activities. However, it does not include the 4384 work's System Libraries, or general-purpose tools or generally 4385 available free programs which are used unmodified in performing 4386 those activities but which are not part of the work. For example, 4387 Corresponding Source includes interface definition files associated 4388 with source files for the work, and the source code for shared 4389 libraries and dynamically linked subprograms that the work is 4390 specifically designed to require, such as by intimate data 4391 communication or control flow between those subprograms and other 4392 parts of the work. 4393 4394 The Corresponding Source need not include anything that users can 4395 regenerate automatically from other parts of the Corresponding 4396 Source. 4397 4398 The Corresponding Source for a work in source code form is that 4399 same work. 4400 4401 2. Basic Permissions. 4402 4403 All rights granted under this License are granted for the term of 4404 copyright on the Program, and are irrevocable provided the stated 4405 conditions are met. This License explicitly affirms your unlimited 4406 permission to run the unmodified Program. The output from running 4407 a covered work is covered by this License only if the output, given 4408 its content, constitutes a covered work. This License acknowledges 4409 your rights of fair use or other equivalent, as provided by 4410 copyright law. 4411 4412 You may make, run and propagate covered works that you do not 4413 convey, without conditions so long as your license otherwise 4414 remains in force. You may convey covered works to others for the 4415 sole purpose of having them make modifications exclusively for you, 4416 or provide you with facilities for running those works, provided 4417 that you comply with the terms of this License in conveying all 4418 material for which you do not control copyright. Those thus making 4419 or running the covered works for you must do so exclusively on your 4420 behalf, under your direction and control, on terms that prohibit 4421 them from making any copies of your copyrighted material outside 4422 their relationship with you. 4423 4424 Conveying under any other circumstances is permitted solely under 4425 the conditions stated below. Sublicensing is not allowed; section 4426 10 makes it unnecessary. 4427 4428 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 4429 4430 No covered work shall be deemed part of an effective technological 4431 measure under any applicable law fulfilling obligations under 4432 article 11 of the WIPO copyright treaty adopted on 20 December 4433 1996, or similar laws prohibiting or restricting circumvention of 4434 such measures. 4435 4436 When you convey a covered work, you waive any legal power to forbid 4437 circumvention of technological measures to the extent such 4438 circumvention is effected by exercising rights under this License 4439 with respect to the covered work, and you disclaim any intention to 4440 limit operation or modification of the work as a means of 4441 enforcing, against the work's users, your or third parties' legal 4442 rights to forbid circumvention of technological measures. 4443 4444 4. Conveying Verbatim Copies. 4445 4446 You may convey verbatim copies of the Program's source code as you 4447 receive it, in any medium, provided that you conspicuously and 4448 appropriately publish on each copy an appropriate copyright notice; 4449 keep intact all notices stating that this License and any 4450 non-permissive terms added in accord with section 7 apply to the 4451 code; keep intact all notices of the absence of any warranty; and 4452 give all recipients a copy of this License along with the Program. 4453 4454 You may charge any price or no price for each copy that you convey, 4455 and you may offer support or warranty protection for a fee. 4456 4457 5. Conveying Modified Source Versions. 4458 4459 You may convey a work based on the Program, or the modifications to 4460 produce it from the Program, in the form of source code under the 4461 terms of section 4, provided that you also meet all of these 4462 conditions: 4463 4464 a. The work must carry prominent notices stating that you 4465 modified it, and giving a relevant date. 4466 4467 b. The work must carry prominent notices stating that it is 4468 released under this License and any conditions added under 4469 section 7. This requirement modifies the requirement in 4470 section 4 to "keep intact all notices". 4471 4472 c. You must license the entire work, as a whole, under this 4473 License to anyone who comes into possession of a copy. This 4474 License will therefore apply, along with any applicable 4475 section 7 additional terms, to the whole of the work, and all 4476 its parts, regardless of how they are packaged. This License 4477 gives no permission to license the work in any other way, but 4478 it does not invalidate such permission if you have separately 4479 received it. 4480 4481 d. If the work has interactive user interfaces, each must display 4482 Appropriate Legal Notices; however, if the Program has 4483 interactive interfaces that do not display Appropriate Legal 4484 Notices, your work need not make them do so. 4485 4486 A compilation of a covered work with other separate and independent 4487 works, which are not by their nature extensions of the covered 4488 work, and which are not combined with it such as to form a larger 4489 program, in or on a volume of a storage or distribution medium, is 4490 called an "aggregate" if the compilation and its resulting 4491 copyright are not used to limit the access or legal rights of the 4492 compilation's users beyond what the individual works permit. 4493 Inclusion of a covered work in an aggregate does not cause this 4494 License to apply to the other parts of the aggregate. 4495 4496 6. Conveying Non-Source Forms. 4497 4498 You may convey a covered work in object code form under the terms 4499 of sections 4 and 5, provided that you also convey the 4500 machine-readable Corresponding Source under the terms of this 4501 License, in one of these ways: 4502 4503 a. Convey the object code in, or embodied in, a physical product 4504 (including a physical distribution medium), accompanied by the 4505 Corresponding Source fixed on a durable physical medium 4506 customarily used for software interchange. 4507 4508 b. Convey the object code in, or embodied in, a physical product 4509 (including a physical distribution medium), accompanied by a 4510 written offer, valid for at least three years and valid for as 4511 long as you offer spare parts or customer support for that 4512 product model, to give anyone who possesses the object code 4513 either (1) a copy of the Corresponding Source for all the 4514 software in the product that is covered by this License, on a 4515 durable physical medium customarily used for software 4516 interchange, for a price no more than your reasonable cost of 4517 physically performing this conveying of source, or (2) access 4518 to copy the Corresponding Source from a network server at no 4519 charge. 4520 4521 c. Convey individual copies of the object code with a copy of the 4522 written offer to provide the Corresponding Source. This 4523 alternative is allowed only occasionally and noncommercially, 4524 and only if you received the object code with such an offer, 4525 in accord with subsection 6b. 4526 4527 d. Convey the object code by offering access from a designated 4528 place (gratis or for a charge), and offer equivalent access to 4529 the Corresponding Source in the same way through the same 4530 place at no further charge. You need not require recipients 4531 to copy the Corresponding Source along with the object code. 4532 If the place to copy the object code is a network server, the 4533 Corresponding Source may be on a different server (operated by 4534 you or a third party) that supports equivalent copying 4535 facilities, provided you maintain clear directions next to the 4536 object code saying where to find the Corresponding Source. 4537 Regardless of what server hosts the Corresponding Source, you 4538 remain obligated to ensure that it is available for as long as 4539 needed to satisfy these requirements. 4540 4541 e. Convey the object code using peer-to-peer transmission, 4542 provided you inform other peers where the object code and 4543 Corresponding Source of the work are being offered to the 4544 general public at no charge under subsection 6d. 4545 4546 A separable portion of the object code, whose source code is 4547 excluded from the Corresponding Source as a System Library, need 4548 not be included in conveying the object code work. 4549 4550 A "User Product" is either (1) a "consumer product", which means 4551 any tangible personal property which is normally used for personal, 4552 family, or household purposes, or (2) anything designed or sold for 4553 incorporation into a dwelling. In determining whether a product is 4554 a consumer product, doubtful cases shall be resolved in favor of 4555 coverage. For a particular product received by a particular user, 4556 "normally used" refers to a typical or common use of that class of 4557 product, regardless of the status of the particular user or of the 4558 way in which the particular user actually uses, or expects or is 4559 expected to use, the product. A product is a consumer product 4560 regardless of whether the product has substantial commercial, 4561 industrial or non-consumer uses, unless such uses represent the 4562 only significant mode of use of the product. 4563 4564 "Installation Information" for a User Product means any methods, 4565 procedures, authorization keys, or other information required to 4566 install and execute modified versions of a covered work in that 4567 User Product from a modified version of its Corresponding Source. 4568 The information must suffice to ensure that the continued 4569 functioning of the modified object code is in no case prevented or 4570 interfered with solely because modification has been made. 4571 4572 If you convey an object code work under this section in, or with, 4573 or specifically for use in, a User Product, and the conveying 4574 occurs as part of a transaction in which the right of possession 4575 and use of the User Product is transferred to the recipient in 4576 perpetuity or for a fixed term (regardless of how the transaction 4577 is characterized), the Corresponding Source conveyed under this 4578 section must be accompanied by the Installation Information. But 4579 this requirement does not apply if neither you nor any third party 4580 retains the ability to install modified object code on the User 4581 Product (for example, the work has been installed in ROM). 4582 4583 The requirement to provide Installation Information does not 4584 include a requirement to continue to provide support service, 4585 warranty, or updates for a work that has been modified or installed 4586 by the recipient, or for the User Product in which it has been 4587 modified or installed. Access to a network may be denied when the 4588 modification itself materially and adversely affects the operation 4589 of the network or violates the rules and protocols for 4590 communication across the network. 4591 4592 Corresponding Source conveyed, and Installation Information 4593 provided, in accord with this section must be in a format that is 4594 publicly documented (and with an implementation available to the 4595 public in source code form), and must require no special password 4596 or key for unpacking, reading or copying. 4597 4598 7. Additional Terms. 4599 4600 "Additional permissions" are terms that supplement the terms of 4601 this License by making exceptions from one or more of its 4602 conditions. Additional permissions that are applicable to the 4603 entire Program shall be treated as though they were included in 4604 this License, to the extent that they are valid under applicable 4605 law. If additional permissions apply only to part of the Program, 4606 that part may be used separately under those permissions, but the 4607 entire Program remains governed by this License without regard to 4608 the additional permissions. 4609 4610 When you convey a copy of a covered work, you may at your option 4611 remove any additional permissions from that copy, or from any part 4612 of it. (Additional permissions may be written to require their own 4613 removal in certain cases when you modify the work.) You may place 4614 additional permissions on material, added by you to a covered work, 4615 for which you have or can give appropriate copyright permission. 4616 4617 Notwithstanding any other provision of this License, for material 4618 you add to a covered work, you may (if authorized by the copyright 4619 holders of that material) supplement the terms of this License with 4620 terms: 4621 4622 a. Disclaiming warranty or limiting liability differently from 4623 the terms of sections 15 and 16 of this License; or 4624 4625 b. Requiring preservation of specified reasonable legal notices 4626 or author attributions in that material or in the Appropriate 4627 Legal Notices displayed by works containing it; or 4628 4629 c. Prohibiting misrepresentation of the origin of that material, 4630 or requiring that modified versions of such material be marked 4631 in reasonable ways as different from the original version; or 4632 4633 d. Limiting the use for publicity purposes of names of licensors 4634 or authors of the material; or 4635 4636 e. Declining to grant rights under trademark law for use of some 4637 trade names, trademarks, or service marks; or 4638 4639 f. Requiring indemnification of licensors and authors of that 4640 material by anyone who conveys the material (or modified 4641 versions of it) with contractual assumptions of liability to 4642 the recipient, for any liability that these contractual 4643 assumptions directly impose on those licensors and authors. 4644 4645 All other non-permissive additional terms are considered "further 4646 restrictions" within the meaning of section 10. If the Program as 4647 you received it, or any part of it, contains a notice stating that 4648 it is governed by this License along with a term that is a further 4649 restriction, you may remove that term. If a license document 4650 contains a further restriction but permits relicensing or conveying 4651 under this License, you may add to a covered work material governed 4652 by the terms of that license document, provided that the further 4653 restriction does not survive such relicensing or conveying. 4654 4655 If you add terms to a covered work in accord with this section, you 4656 must place, in the relevant source files, a statement of the 4657 additional terms that apply to those files, or a notice indicating 4658 where to find the applicable terms. 4659 4660 Additional terms, permissive or non-permissive, may be stated in 4661 the form of a separately written license, or stated as exceptions; 4662 the above requirements apply either way. 4663 4664 8. Termination. 4665 4666 You may not propagate or modify a covered work except as expressly 4667 provided under this License. Any attempt otherwise to propagate or 4668 modify it is void, and will automatically terminate your rights 4669 under this License (including any patent licenses granted under the 4670 third paragraph of section 11). 4671 4672 However, if you cease all violation of this License, then your 4673 license from a particular copyright holder is reinstated (a) 4674 provisionally, unless and until the copyright holder explicitly and 4675 finally terminates your license, and (b) permanently, if the 4676 copyright holder fails to notify you of the violation by some 4677 reasonable means prior to 60 days after the cessation. 4678 4679 Moreover, your license from a particular copyright holder is 4680 reinstated permanently if the copyright holder notifies you of the 4681 violation by some reasonable means, this is the first time you have 4682 received notice of violation of this License (for any work) from 4683 that copyright holder, and you cure the violation prior to 30 days 4684 after your receipt of the notice. 4685 4686 Termination of your rights under this section does not terminate 4687 the licenses of parties who have received copies or rights from you 4688 under this License. If your rights have been terminated and not 4689 permanently reinstated, you do not qualify to receive new licenses 4690 for the same material under section 10. 4691 4692 9. Acceptance Not Required for Having Copies. 4693 4694 You are not required to accept this License in order to receive or 4695 run a copy of the Program. Ancillary propagation of a covered work 4696 occurring solely as a consequence of using peer-to-peer 4697 transmission to receive a copy likewise does not require 4698 acceptance. However, nothing other than this License grants you 4699 permission to propagate or modify any covered work. These actions 4700 infringe copyright if you do not accept this License. Therefore, 4701 by modifying or propagating a covered work, you indicate your 4702 acceptance of this License to do so. 4703 4704 10. Automatic Licensing of Downstream Recipients. 4705 4706 Each time you convey a covered work, the recipient automatically 4707 receives a license from the original licensors, to run, modify and 4708 propagate that work, subject to this License. You are not 4709 responsible for enforcing compliance by third parties with this 4710 License. 4711 4712 An "entity transaction" is a transaction transferring control of an 4713 organization, or substantially all assets of one, or subdividing an 4714 organization, or merging organizations. If propagation of a 4715 covered work results from an entity transaction, each party to that 4716 transaction who receives a copy of the work also receives whatever 4717 licenses to the work the party's predecessor in interest had or 4718 could give under the previous paragraph, plus a right to possession 4719 of the Corresponding Source of the work from the predecessor in 4720 interest, if the predecessor has it or can get it with reasonable 4721 efforts. 4722 4723 You may not impose any further restrictions on the exercise of the 4724 rights granted or affirmed under this License. For example, you 4725 may not impose a license fee, royalty, or other charge for exercise 4726 of rights granted under this License, and you may not initiate 4727 litigation (including a cross-claim or counterclaim in a lawsuit) 4728 alleging that any patent claim is infringed by making, using, 4729 selling, offering for sale, or importing the Program or any portion 4730 of it. 4731 4732 11. Patents. 4733 4734 A "contributor" is a copyright holder who authorizes use under this 4735 License of the Program or a work on which the Program is based. 4736 The work thus licensed is called the contributor's "contributor 4737 version". 4738 4739 A contributor's "essential patent claims" are all patent claims 4740 owned or controlled by the contributor, whether already acquired or 4741 hereafter acquired, that would be infringed by some manner, 4742 permitted by this License, of making, using, or selling its 4743 contributor version, but do not include claims that would be 4744 infringed only as a consequence of further modification of the 4745 contributor version. For purposes of this definition, "control" 4746 includes the right to grant patent sublicenses in a manner 4747 consistent with the requirements of this License. 4748 4749 Each contributor grants you a non-exclusive, worldwide, 4750 royalty-free patent license under the contributor's essential 4751 patent claims, to make, use, sell, offer for sale, import and 4752 otherwise run, modify and propagate the contents of its contributor 4753 version. 4754 4755 In the following three paragraphs, a "patent license" is any 4756 express agreement or commitment, however denominated, not to 4757 enforce a patent (such as an express permission to practice a 4758 patent or covenant not to sue for patent infringement). To "grant" 4759 such a patent license to a party means to make such an agreement or 4760 commitment not to enforce a patent against the party. 4761 4762 If you convey a covered work, knowingly relying on a patent 4763 license, and the Corresponding Source of the work is not available 4764 for anyone to copy, free of charge and under the terms of this 4765 License, through a publicly available network server or other 4766 readily accessible means, then you must either (1) cause the 4767 Corresponding Source to be so available, or (2) arrange to deprive 4768 yourself of the benefit of the patent license for this particular 4769 work, or (3) arrange, in a manner consistent with the requirements 4770 of this License, to extend the patent license to downstream 4771 recipients. "Knowingly relying" means you have actual knowledge 4772 that, but for the patent license, your conveying the covered work 4773 in a country, or your recipient's use of the covered work in a 4774 country, would infringe one or more identifiable patents in that 4775 country that you have reason to believe are valid. 4776 4777 If, pursuant to or in connection with a single transaction or 4778 arrangement, you convey, or propagate by procuring conveyance of, a 4779 covered work, and grant a patent license to some of the parties 4780 receiving the covered work authorizing them to use, propagate, 4781 modify or convey a specific copy of the covered work, then the 4782 patent license you grant is automatically extended to all 4783 recipients of the covered work and works based on it. 4784 4785 A patent license is "discriminatory" if it does not include within 4786 the scope of its coverage, prohibits the exercise of, or is 4787 conditioned on the non-exercise of one or more of the rights that 4788 are specifically granted under this License. You may not convey a 4789 covered work if you are a party to an arrangement with a third 4790 party that is in the business of distributing software, under which 4791 you make payment to the third party based on the extent of your 4792 activity of conveying the work, and under which the third party 4793 grants, to any of the parties who would receive the covered work 4794 from you, a discriminatory patent license (a) in connection with 4795 copies of the covered work conveyed by you (or copies made from 4796 those copies), or (b) primarily for and in connection with specific 4797 products or compilations that contain the covered work, unless you 4798 entered into that arrangement, or that patent license was granted, 4799 prior to 28 March 2007. 4800 4801 Nothing in this License shall be construed as excluding or limiting 4802 any implied license or other defenses to infringement that may 4803 otherwise be available to you under applicable patent law. 4804 4805 12. No Surrender of Others' Freedom. 4806 4807 If conditions are imposed on you (whether by court order, agreement 4808 or otherwise) that contradict the conditions of this License, they 4809 do not excuse you from the conditions of this License. If you 4810 cannot convey a covered work so as to satisfy simultaneously your 4811 obligations under this License and any other pertinent obligations, 4812 then as a consequence you may not convey it at all. For example, 4813 if you agree to terms that obligate you to collect a royalty for 4814 further conveying from those to whom you convey the Program, the 4815 only way you could satisfy both those terms and this License would 4816 be to refrain entirely from conveying the Program. 4817 4818 13. Use with the GNU Affero General Public License. 4819 4820 Notwithstanding any other provision of this License, you have 4821 permission to link or combine any covered work with a work licensed 4822 under version 3 of the GNU Affero General Public License into a 4823 single combined work, and to convey the resulting work. The terms 4824 of this License will continue to apply to the part which is the 4825 covered work, but the special requirements of the GNU Affero 4826 General Public License, section 13, concerning interaction through 4827 a network will apply to the combination as such. 4828 4829 14. Revised Versions of this License. 4830 4831 The Free Software Foundation may publish revised and/or new 4832 versions of the GNU General Public License from time to time. Such 4833 new versions will be similar in spirit to the present version, but 4834 may differ in detail to address new problems or concerns. 4835 4836 Each version is given a distinguishing version number. If the 4837 Program specifies that a certain numbered version of the GNU 4838 General Public License "or any later version" applies to it, you 4839 have the option of following the terms and conditions either of 4840 that numbered version or of any later version published by the Free 4841 Software Foundation. If the Program does not specify a version 4842 number of the GNU General Public License, you may choose any 4843 version ever published by the Free Software Foundation. 4844 4845 If the Program specifies that a proxy can decide which future 4846 versions of the GNU General Public License can be used, that 4847 proxy's public statement of acceptance of a version permanently 4848 authorizes you to choose that version for the Program. 4849 4850 Later license versions may give you additional or different 4851 permissions. However, no additional obligations are imposed on any 4852 author or copyright holder as a result of your choosing to follow a 4853 later version. 4854 4855 15. Disclaimer of Warranty. 4856 4857 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 4858 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE 4859 COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" 4860 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, 4861 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 4862 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE 4863 RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. 4864 SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL 4865 NECESSARY SERVICING, REPAIR OR CORRECTION. 4866 4867 16. Limitation of Liability. 4868 4869 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 4870 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES 4871 AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR 4872 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR 4873 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE 4874 THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA 4875 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 4876 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER 4877 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF 4878 THE POSSIBILITY OF SUCH DAMAGES. 4879 4880 17. Interpretation of Sections 15 and 16. 4881 4882 If the disclaimer of warranty and limitation of liability provided 4883 above cannot be given local legal effect according to their terms, 4884 reviewing courts shall apply local law that most closely 4885 approximates an absolute waiver of all civil liability in 4886 connection with the Program, unless a warranty or assumption of 4887 liability accompanies a copy of the Program in return for a fee. 4888 4889 END OF TERMS AND CONDITIONS 4890 =========================== 4891 4892 How to Apply These Terms to Your New Programs 4893 ============================================= 4894 4895 If you develop a new program, and you want it to be of the greatest 4896 possible use to the public, the best way to achieve this is to make it 4897 free software which everyone can redistribute and change under these 4898 terms. 4899 4900 To do so, attach the following notices to the program. It is safest 4901 to attach them to the start of each source file to most effectively 4902 state the exclusion of warranty; and each file should have at least the 4903 "copyright" line and a pointer to where the full notice is found. 4904 4905 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. 4906 Copyright (C) YEAR NAME OF AUTHOR 4907 4908 This program is free software: you can redistribute it and/or modify 4909 it under the terms of the GNU General Public License as published by 4910 the Free Software Foundation, either version 3 of the License, or (at 4911 your option) any later version. 4912 4913 This program is distributed in the hope that it will be useful, but 4914 WITHOUT ANY WARRANTY; without even the implied warranty of 4915 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 4916 General Public License for more details. 4917 4918 You should have received a copy of the GNU General Public License 4919 along with this program. If not, see <https://www.gnu.org/licenses/>. 4920 4921 Also add information on how to contact you by electronic and paper 4922 mail. 4923 4924 If the program does terminal interaction, make it output a short 4925 notice like this when it starts in an interactive mode: 4926 4927 PROGRAM Copyright (C) YEAR NAME OF AUTHOR 4928 This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. 4929 This is free software, and you are welcome to redistribute it 4930 under certain conditions; type 'show c' for details. 4931 4932 The hypothetical commands 'show w' and 'show c' should show the 4933 appropriate parts of the General Public License. Of course, your 4934 program's commands might be different; for a GUI interface, you would 4935 use an "about box". 4936 4937 You should also get your employer (if you work as a programmer) or 4938 school, if any, to sign a "copyright disclaimer" for the program, if 4939 necessary. For more information on this, and how to apply and follow 4940 the GNU GPL, see <https://www.gnu.org/licenses/>. 4941 4942 The GNU General Public License does not permit incorporating your 4943 program into proprietary programs. If your program is a subroutine 4944 library, you may consider it more useful to permit linking proprietary 4945 applications with the library. If this is what you want to do, use the 4946 GNU Lesser General Public License instead of this License. But first, 4947 please read <https://www.gnu.org/licenses/why-not-lgpl.html>. 4948 4949 4950 File: libgomp.info, Node: GNU Free Documentation License, Next: Funding, Prev: Copying, Up: Top 4951 4952 GNU Free Documentation License 4953 ****************************** 4954 4955 Version 1.3, 3 November 2008 4956 4957 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 4958 <https://fsf.org/> 4959 4960 Everyone is permitted to copy and distribute verbatim copies 4961 of this license document, but changing it is not allowed. 4962 4963 0. PREAMBLE 4964 4965 The purpose of this License is to make a manual, textbook, or other 4966 functional and useful document "free" in the sense of freedom: to 4967 assure everyone the effective freedom to copy and redistribute it, 4968 with or without modifying it, either commercially or 4969 noncommercially. Secondarily, this License preserves for the 4970 author and publisher a way to get credit for their work, while not 4971 being considered responsible for modifications made by others. 4972 4973 This License is a kind of "copyleft", which means that derivative 4974 works of the document must themselves be free in the same sense. 4975 It complements the GNU General Public License, which is a copyleft 4976 license designed for free software. 4977 4978 We have designed this License in order to use it for manuals for 4979 free software, because free software needs free documentation: a 4980 free program should come with manuals providing the same freedoms 4981 that the software does. But this License is not limited to 4982 software manuals; it can be used for any textual work, regardless 4983 of subject matter or whether it is published as a printed book. We 4984 recommend this License principally for works whose purpose is 4985 instruction or reference. 4986 4987 1. APPLICABILITY AND DEFINITIONS 4988 4989 This License applies to any manual or other work, in any medium, 4990 that contains a notice placed by the copyright holder saying it can 4991 be distributed under the terms of this License. Such a notice 4992 grants a world-wide, royalty-free license, unlimited in duration, 4993 to use that work under the conditions stated herein. The 4994 "Document", below, refers to any such manual or work. Any member 4995 of the public is a licensee, and is addressed as "you". You accept 4996 the license if you copy, modify or distribute the work in a way 4997 requiring permission under copyright law. 4998 4999 A "Modified Version" of the Document means any work containing the 5000 Document or a portion of it, either copied verbatim, or with 5001 modifications and/or translated into another language. 5002 5003 A "Secondary Section" is a named appendix or a front-matter section 5004 of the Document that deals exclusively with the relationship of the 5005 publishers or authors of the Document to the Document's overall 5006 subject (or to related matters) and contains nothing that could 5007 fall directly within that overall subject. (Thus, if the Document 5008 is in part a textbook of mathematics, a Secondary Section may not 5009 explain any mathematics.) The relationship could be a matter of 5010 historical connection with the subject or with related matters, or 5011 of legal, commercial, philosophical, ethical or political position 5012 regarding them. 5013 5014 The "Invariant Sections" are certain Secondary Sections whose 5015 titles are designated, as being those of Invariant Sections, in the 5016 notice that says that the Document is released under this License. 5017 If a section does not fit the above definition of Secondary then it 5018 is not allowed to be designated as Invariant. The Document may 5019 contain zero Invariant Sections. If the Document does not identify 5020 any Invariant Sections then there are none. 5021 5022 The "Cover Texts" are certain short passages of text that are 5023 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 5024 that says that the Document is released under this License. A 5025 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 5026 be at most 25 words. 5027 5028 A "Transparent" copy of the Document means a machine-readable copy, 5029 represented in a format whose specification is available to the 5030 general public, that is suitable for revising the document 5031 straightforwardly with generic text editors or (for images composed 5032 of pixels) generic paint programs or (for drawings) some widely 5033 available drawing editor, and that is suitable for input to text 5034 formatters or for automatic translation to a variety of formats 5035 suitable for input to text formatters. A copy made in an otherwise 5036 Transparent file format whose markup, or absence of markup, has 5037 been arranged to thwart or discourage subsequent modification by 5038 readers is not Transparent. An image format is not Transparent if 5039 used for any substantial amount of text. A copy that is not 5040 "Transparent" is called "Opaque". 5041 5042 Examples of suitable formats for Transparent copies include plain 5043 ASCII without markup, Texinfo input format, LaTeX input format, 5044 SGML or XML using a publicly available DTD, and standard-conforming 5045 simple HTML, PostScript or PDF designed for human modification. 5046 Examples of transparent image formats include PNG, XCF and JPG. 5047 Opaque formats include proprietary formats that can be read and 5048 edited only by proprietary word processors, SGML or XML for which 5049 the DTD and/or processing tools are not generally available, and 5050 the machine-generated HTML, PostScript or PDF produced by some word 5051 processors for output purposes only. 5052 5053 The "Title Page" means, for a printed book, the title page itself, 5054 plus such following pages as are needed to hold, legibly, the 5055 material this License requires to appear in the title page. For 5056 works in formats which do not have any title page as such, "Title 5057 Page" means the text near the most prominent appearance of the 5058 work's title, preceding the beginning of the body of the text. 5059 5060 The "publisher" means any person or entity that distributes copies 5061 of the Document to the public. 5062 5063 A section "Entitled XYZ" means a named subunit of the Document 5064 whose title either is precisely XYZ or contains XYZ in parentheses 5065 following text that translates XYZ in another language. (Here XYZ 5066 stands for a specific section name mentioned below, such as 5067 "Acknowledgements", "Dedications", "Endorsements", or "History".) 5068 To "Preserve the Title" of such a section when you modify the 5069 Document means that it remains a section "Entitled XYZ" according 5070 to this definition. 5071 5072 The Document may include Warranty Disclaimers next to the notice 5073 which states that this License applies to the Document. These 5074 Warranty Disclaimers are considered to be included by reference in 5075 this License, but only as regards disclaiming warranties: any other 5076 implication that these Warranty Disclaimers may have is void and 5077 has no effect on the meaning of this License. 5078 5079 2. VERBATIM COPYING 5080 5081 You may copy and distribute the Document in any medium, either 5082 commercially or noncommercially, provided that this License, the 5083 copyright notices, and the license notice saying this License 5084 applies to the Document are reproduced in all copies, and that you 5085 add no other conditions whatsoever to those of this License. You 5086 may not use technical measures to obstruct or control the reading 5087 or further copying of the copies you make or distribute. However, 5088 you may accept compensation in exchange for copies. If you 5089 distribute a large enough number of copies you must also follow the 5090 conditions in section 3. 5091 5092 You may also lend copies, under the same conditions stated above, 5093 and you may publicly display copies. 5094 5095 3. COPYING IN QUANTITY 5096 5097 If you publish printed copies (or copies in media that commonly 5098 have printed covers) of the Document, numbering more than 100, and 5099 the Document's license notice requires Cover Texts, you must 5100 enclose the copies in covers that carry, clearly and legibly, all 5101 these Cover Texts: Front-Cover Texts on the front cover, and 5102 Back-Cover Texts on the back cover. Both covers must also clearly 5103 and legibly identify you as the publisher of these copies. The 5104 front cover must present the full title with all words of the title 5105 equally prominent and visible. You may add other material on the 5106 covers in addition. Copying with changes limited to the covers, as 5107 long as they preserve the title of the Document and satisfy these 5108 conditions, can be treated as verbatim copying in other respects. 5109 5110 If the required texts for either cover are too voluminous to fit 5111 legibly, you should put the first ones listed (as many as fit 5112 reasonably) on the actual cover, and continue the rest onto 5113 adjacent pages. 5114 5115 If you publish or distribute Opaque copies of the Document 5116 numbering more than 100, you must either include a machine-readable 5117 Transparent copy along with each Opaque copy, or state in or with 5118 each Opaque copy a computer-network location from which the general 5119 network-using public has access to download using public-standard 5120 network protocols a complete Transparent copy of the Document, free 5121 of added material. If you use the latter option, you must take 5122 reasonably prudent steps, when you begin distribution of Opaque 5123 copies in quantity, to ensure that this Transparent copy will 5124 remain thus accessible at the stated location until at least one 5125 year after the last time you distribute an Opaque copy (directly or 5126 through your agents or retailers) of that edition to the public. 5127 5128 It is requested, but not required, that you contact the authors of 5129 the Document well before redistributing any large number of copies, 5130 to give them a chance to provide you with an updated version of the 5131 Document. 5132 5133 4. MODIFICATIONS 5134 5135 You may copy and distribute a Modified Version of the Document 5136 under the conditions of sections 2 and 3 above, provided that you 5137 release the Modified Version under precisely this License, with the 5138 Modified Version filling the role of the Document, thus licensing 5139 distribution and modification of the Modified Version to whoever 5140 possesses a copy of it. In addition, you must do these things in 5141 the Modified Version: 5142 5143 A. Use in the Title Page (and on the covers, if any) a title 5144 distinct from that of the Document, and from those of previous 5145 versions (which should, if there were any, be listed in the 5146 History section of the Document). You may use the same title 5147 as a previous version if the original publisher of that 5148 version gives permission. 5149 5150 B. List on the Title Page, as authors, one or more persons or 5151 entities responsible for authorship of the modifications in 5152 the Modified Version, together with at least five of the 5153 principal authors of the Document (all of its principal 5154 authors, if it has fewer than five), unless they release you 5155 from this requirement. 5156 5157 C. State on the Title page the name of the publisher of the 5158 Modified Version, as the publisher. 5159 5160 D. Preserve all the copyright notices of the Document. 5161 5162 E. Add an appropriate copyright notice for your modifications 5163 adjacent to the other copyright notices. 5164 5165 F. Include, immediately after the copyright notices, a license 5166 notice giving the public permission to use the Modified 5167 Version under the terms of this License, in the form shown in 5168 the Addendum below. 5169 5170 G. Preserve in that license notice the full lists of Invariant 5171 Sections and required Cover Texts given in the Document's 5172 license notice. 5173 5174 H. Include an unaltered copy of this License. 5175 5176 I. Preserve the section Entitled "History", Preserve its Title, 5177 and add to it an item stating at least the title, year, new 5178 authors, and publisher of the Modified Version as given on the 5179 Title Page. If there is no section Entitled "History" in the 5180 Document, create one stating the title, year, authors, and 5181 publisher of the Document as given on its Title Page, then add 5182 an item describing the Modified Version as stated in the 5183 previous sentence. 5184 5185 J. Preserve the network location, if any, given in the Document 5186 for public access to a Transparent copy of the Document, and 5187 likewise the network locations given in the Document for 5188 previous versions it was based on. These may be placed in the 5189 "History" section. You may omit a network location for a work 5190 that was published at least four years before the Document 5191 itself, or if the original publisher of the version it refers 5192 to gives permission. 5193 5194 K. For any section Entitled "Acknowledgements" or "Dedications", 5195 Preserve the Title of the section, and preserve in the section 5196 all the substance and tone of each of the contributor 5197 acknowledgements and/or dedications given therein. 5198 5199 L. Preserve all the Invariant Sections of the Document, unaltered 5200 in their text and in their titles. Section numbers or the 5201 equivalent are not considered part of the section titles. 5202 5203 M. Delete any section Entitled "Endorsements". Such a section 5204 may not be included in the Modified Version. 5205 5206 N. Do not retitle any existing section to be Entitled 5207 "Endorsements" or to conflict in title with any Invariant 5208 Section. 5209 5210 O. Preserve any Warranty Disclaimers. 5211 5212 If the Modified Version includes new front-matter sections or 5213 appendices that qualify as Secondary Sections and contain no 5214 material copied from the Document, you may at your option designate 5215 some or all of these sections as invariant. To do this, add their 5216 titles to the list of Invariant Sections in the Modified Version's 5217 license notice. These titles must be distinct from any other 5218 section titles. 5219 5220 You may add a section Entitled "Endorsements", provided it contains 5221 nothing but endorsements of your Modified Version by various 5222 parties--for example, statements of peer review or that the text 5223 has been approved by an organization as the authoritative 5224 definition of a standard. 5225 5226 You may add a passage of up to five words as a Front-Cover Text, 5227 and a passage of up to 25 words as a Back-Cover Text, to the end of 5228 the list of Cover Texts in the Modified Version. Only one passage 5229 of Front-Cover Text and one of Back-Cover Text may be added by (or 5230 through arrangements made by) any one entity. If the Document 5231 already includes a cover text for the same cover, previously added 5232 by you or by arrangement made by the same entity you are acting on 5233 behalf of, you may not add another; but you may replace the old 5234 one, on explicit permission from the previous publisher that added 5235 the old one. 5236 5237 The author(s) and publisher(s) of the Document do not by this 5238 License give permission to use their names for publicity for or to 5239 assert or imply endorsement of any Modified Version. 5240 5241 5. COMBINING DOCUMENTS 5242 5243 You may combine the Document with other documents released under 5244 this License, under the terms defined in section 4 above for 5245 modified versions, provided that you include in the combination all 5246 of the Invariant Sections of all of the original documents, 5247 unmodified, and list them all as Invariant Sections of your 5248 combined work in its license notice, and that you preserve all 5249 their Warranty Disclaimers. 5250 5251 The combined work need only contain one copy of this License, and 5252 multiple identical Invariant Sections may be replaced with a single 5253 copy. If there are multiple Invariant Sections with the same name 5254 but different contents, make the title of each such section unique 5255 by adding at the end of it, in parentheses, the name of the 5256 original author or publisher of that section if known, or else a 5257 unique number. Make the same adjustment to the section titles in 5258 the list of Invariant Sections in the license notice of the 5259 combined work. 5260 5261 In the combination, you must combine any sections Entitled 5262 "History" in the various original documents, forming one section 5263 Entitled "History"; likewise combine any sections Entitled 5264 "Acknowledgements", and any sections Entitled "Dedications". You 5265 must delete all sections Entitled "Endorsements." 5266 5267 6. COLLECTIONS OF DOCUMENTS 5268 5269 You may make a collection consisting of the Document and other 5270 documents released under this License, and replace the individual 5271 copies of this License in the various documents with a single copy 5272 that is included in the collection, provided that you follow the 5273 rules of this License for verbatim copying of each of the documents 5274 in all other respects. 5275 5276 You may extract a single document from such a collection, and 5277 distribute it individually under this License, provided you insert 5278 a copy of this License into the extracted document, and follow this 5279 License in all other respects regarding verbatim copying of that 5280 document. 5281 5282 7. AGGREGATION WITH INDEPENDENT WORKS 5283 5284 A compilation of the Document or its derivatives with other 5285 separate and independent documents or works, in or on a volume of a 5286 storage or distribution medium, is called an "aggregate" if the 5287 copyright resulting from the compilation is not used to limit the 5288 legal rights of the compilation's users beyond what the individual 5289 works permit. When the Document is included in an aggregate, this 5290 License does not apply to the other works in the aggregate which 5291 are not themselves derivative works of the Document. 5292 5293 If the Cover Text requirement of section 3 is applicable to these 5294 copies of the Document, then if the Document is less than one half 5295 of the entire aggregate, the Document's Cover Texts may be placed 5296 on covers that bracket the Document within the aggregate, or the 5297 electronic equivalent of covers if the Document is in electronic 5298 form. Otherwise they must appear on printed covers that bracket 5299 the whole aggregate. 5300 5301 8. TRANSLATION 5302 5303 Translation is considered a kind of modification, so you may 5304 distribute translations of the Document under the terms of section 5305 4. Replacing Invariant Sections with translations requires special 5306 permission from their copyright holders, but you may include 5307 translations of some or all Invariant Sections in addition to the 5308 original versions of these Invariant Sections. You may include a 5309 translation of this License, and all the license notices in the 5310 Document, and any Warranty Disclaimers, provided that you also 5311 include the original English version of this License and the 5312 original versions of those notices and disclaimers. In case of a 5313 disagreement between the translation and the original version of 5314 this License or a notice or disclaimer, the original version will 5315 prevail. 5316 5317 If a section in the Document is Entitled "Acknowledgements", 5318 "Dedications", or "History", the requirement (section 4) to 5319 Preserve its Title (section 1) will typically require changing the 5320 actual title. 5321 5322 9. TERMINATION 5323 5324 You may not copy, modify, sublicense, or distribute the Document 5325 except as expressly provided under this License. Any attempt 5326 otherwise to copy, modify, sublicense, or distribute it is void, 5327 and will automatically terminate your rights under this License. 5328 5329 However, if you cease all violation of this License, then your 5330 license from a particular copyright holder is reinstated (a) 5331 provisionally, unless and until the copyright holder explicitly and 5332 finally terminates your license, and (b) permanently, if the 5333 copyright holder fails to notify you of the violation by some 5334 reasonable means prior to 60 days after the cessation. 5335 5336 Moreover, your license from a particular copyright holder is 5337 reinstated permanently if the copyright holder notifies you of the 5338 violation by some reasonable means, this is the first time you have 5339 received notice of violation of this License (for any work) from 5340 that copyright holder, and you cure the violation prior to 30 days 5341 after your receipt of the notice. 5342 5343 Termination of your rights under this section does not terminate 5344 the licenses of parties who have received copies or rights from you 5345 under this License. If your rights have been terminated and not 5346 permanently reinstated, receipt of a copy of some or all of the 5347 same material does not give you any rights to use it. 5348 5349 10. FUTURE REVISIONS OF THIS LICENSE 5350 5351 The Free Software Foundation may publish new, revised versions of 5352 the GNU Free Documentation License from time to time. Such new 5353 versions will be similar in spirit to the present version, but may 5354 differ in detail to address new problems or concerns. See 5355 <https://www.gnu.org/copyleft/>. 5356 5357 Each version of the License is given a distinguishing version 5358 number. If the Document specifies that a particular numbered 5359 version of this License "or any later version" applies to it, you 5360 have the option of following the terms and conditions either of 5361 that specified version or of any later version that has been 5362 published (not as a draft) by the Free Software Foundation. If the 5363 Document does not specify a version number of this License, you may 5364 choose any version ever published (not as a draft) by the Free 5365 Software Foundation. If the Document specifies that a proxy can 5366 decide which future versions of this License can be used, that 5367 proxy's public statement of acceptance of a version permanently 5368 authorizes you to choose that version for the Document. 5369 5370 11. RELICENSING 5371 5372 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 5373 World Wide Web server that publishes copyrightable works and also 5374 provides prominent facilities for anybody to edit those works. A 5375 public wiki that anybody can edit is an example of such a server. 5376 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 5377 site means any set of copyrightable works thus published on the MMC 5378 site. 5379 5380 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 5381 license published by Creative Commons Corporation, a not-for-profit 5382 corporation with a principal place of business in San Francisco, 5383 California, as well as future copyleft versions of that license 5384 published by that same organization. 5385 5386 "Incorporate" means to publish or republish a Document, in whole or 5387 in part, as part of another Document. 5388 5389 An MMC is "eligible for relicensing" if it is licensed under this 5390 License, and if all works that were first published under this 5391 License somewhere other than this MMC, and subsequently 5392 incorporated in whole or in part into the MMC, (1) had no cover 5393 texts or invariant sections, and (2) were thus incorporated prior 5394 to November 1, 2008. 5395 5396 The operator of an MMC Site may republish an MMC contained in the 5397 site under CC-BY-SA on the same site at any time before August 1, 5398 2009, provided the MMC is eligible for relicensing. 5399 5400 ADDENDUM: How to use this License for your documents 5401 ==================================================== 5402 5403 To use this License in a document you have written, include a copy of 5404 the License in the document and put the following copyright and license 5405 notices just after the title page: 5406 5407 Copyright (C) YEAR YOUR NAME. 5408 Permission is granted to copy, distribute and/or modify this document 5409 under the terms of the GNU Free Documentation License, Version 1.3 5410 or any later version published by the Free Software Foundation; 5411 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 5412 Texts. A copy of the license is included in the section entitled ``GNU 5413 Free Documentation License''. 5414 5415 If you have Invariant Sections, Front-Cover Texts and Back-Cover 5416 Texts, replace the "with...Texts." line with this: 5417 5418 with the Invariant Sections being LIST THEIR TITLES, with 5419 the Front-Cover Texts being LIST, and with the Back-Cover Texts 5420 being LIST. 5421 5422 If you have Invariant Sections without Cover Texts, or some other 5423 combination of the three, merge those two alternatives to suit the 5424 situation. 5425 5426 If your document contains nontrivial examples of program code, we 5427 recommend releasing these examples in parallel under your choice of free 5428 software license, such as the GNU General Public License, to permit 5429 their use in free software. 5430 5431 5432 File: libgomp.info, Node: Funding, Next: Library Index, Prev: GNU Free Documentation License, Up: Top 5433 5434 Funding Free Software 5435 ********************* 5436 5437 If you want to have more free software a few years from now, it makes 5438 sense for you to help encourage people to contribute funds for its 5439 development. The most effective approach known is to encourage 5440 commercial redistributors to donate. 5441 5442 Users of free software systems can boost the pace of development by 5443 encouraging for-a-fee distributors to donate part of their selling price 5444 to free software developers--the Free Software Foundation, and others. 5445 5446 The way to convince distributors to do this is to demand it and 5447 expect it from them. So when you compare distributors, judge them 5448 partly by how much they give to free software development. Show 5449 distributors they must compete to be the one who gives the most. 5450 5451 To make this approach work, you must insist on numbers that you can 5452 compare, such as, "We will donate ten dollars to the Frobnitz project 5453 for each disk sold." Don't be satisfied with a vague promise, such as 5454 "A portion of the profits are donated," since it doesn't give a basis 5455 for comparison. 5456 5457 Even a precise fraction "of the profits from this disk" is not very 5458 meaningful, since creative accounting and unrelated business decisions 5459 can greatly alter what fraction of the sales price counts as profit. If 5460 the price you pay is $50, ten percent of the profit is probably less 5461 than a dollar; it might be a few cents, or nothing at all. 5462 5463 Some redistributors do development work themselves. This is useful 5464 too; but to keep everyone honest, you need to inquire how much they do, 5465 and what kind. Some kinds of development make much more long-term 5466 difference than others. For example, maintaining a separate version of 5467 a program contributes very little; maintaining the standard version of a 5468 program for the whole community contributes much. Easy new ports 5469 contribute little, since someone else would surely do them; difficult 5470 ports such as adding a new CPU to the GNU Compiler Collection contribute 5471 more; major new features or packages contribute the most. 5472 5473 By establishing the idea that supporting further development is "the 5474 proper thing to do" when distributing free software for a fee, we can 5475 assure a steady flow of resources into making more free software. 5476 5477 Copyright (C) 1994 Free Software Foundation, Inc. 5478 Verbatim copying and redistribution of this section is permitted 5479 without royalty; alteration is not permitted. 5480 5481 5482 File: libgomp.info, Node: Library Index, Prev: Funding, Up: Top 5483 5484 Library Index 5485 ************* 5486 5487 [index] 5488 * Menu: 5489 5490 * acc_get_property: acc_get_property. (line 6) 5491 * acc_get_property_string: acc_get_property. (line 6) 5492 * Environment Variable: OMP_CANCELLATION. (line 6) 5493 * Environment Variable <1>: OMP_DISPLAY_ENV. (line 6) 5494 * Environment Variable <2>: OMP_DEFAULT_DEVICE. (line 6) 5495 * Environment Variable <3>: OMP_DYNAMIC. (line 6) 5496 * Environment Variable <4>: OMP_MAX_ACTIVE_LEVELS. (line 6) 5497 * Environment Variable <5>: OMP_MAX_TASK_PRIORITY. (line 6) 5498 * Environment Variable <6>: OMP_NESTED. (line 6) 5499 * Environment Variable <7>: OMP_NUM_TEAMS. (line 6) 5500 * Environment Variable <8>: OMP_NUM_THREADS. (line 6) 5501 * Environment Variable <9>: OMP_PROC_BIND. (line 6) 5502 * Environment Variable <10>: OMP_PLACES. (line 6) 5503 * Environment Variable <11>: OMP_STACKSIZE. (line 6) 5504 * Environment Variable <12>: OMP_SCHEDULE. (line 6) 5505 * Environment Variable <13>: OMP_TARGET_OFFLOAD. (line 6) 5506 * Environment Variable <14>: OMP_TEAMS_THREAD_LIMIT. 5507 (line 6) 5508 * Environment Variable <15>: OMP_THREAD_LIMIT. (line 6) 5509 * Environment Variable <16>: OMP_WAIT_POLICY. (line 6) 5510 * Environment Variable <17>: GOMP_CPU_AFFINITY. (line 6) 5511 * Environment Variable <18>: GOMP_DEBUG. (line 6) 5512 * Environment Variable <19>: GOMP_STACKSIZE. (line 6) 5513 * Environment Variable <20>: GOMP_SPINCOUNT. (line 6) 5514 * Environment Variable <21>: GOMP_RTEMS_THREAD_POOLS. 5515 (line 6) 5516 * FDL, GNU Free Documentation License: GNU Free Documentation License. 5517 (line 6) 5518 * Implementation specific setting: OMP_NESTED. (line 6) 5519 * Implementation specific setting <1>: OMP_NUM_THREADS. (line 6) 5520 * Implementation specific setting <2>: OMP_SCHEDULE. (line 6) 5521 * Implementation specific setting <3>: OMP_TARGET_OFFLOAD. (line 6) 5522 * Implementation specific setting <4>: GOMP_STACKSIZE. (line 6) 5523 * Implementation specific setting <5>: GOMP_SPINCOUNT. (line 6) 5524 * Implementation specific setting <6>: GOMP_RTEMS_THREAD_POOLS. 5525 (line 6) 5526 * Introduction: Top. (line 6) 5527 5528 5529 5530 Tag Table: 5531 Node: Top2083 5532 Node: Enabling OpenMP4713 5533 Node: OpenMP Implementation Status5519 5534 Node: OpenMP 4.56074 5535 Node: OpenMP 5.06250 5536 Node: OpenMP 5.111120 5537 Node: Runtime Library Routines14711 5538 Node: omp_get_active_level18416 5539 Node: omp_get_ancestor_thread_num19116 5540 Node: omp_get_cancellation20046 5541 Node: omp_get_default_device20860 5542 Node: omp_get_device_num21539 5543 Node: omp_get_dynamic22344 5544 Node: omp_get_initial_device23224 5545 Node: omp_get_level23968 5546 Node: omp_get_max_active_levels24595 5547 Node: omp_get_max_task_priority25316 5548 Node: omp_get_max_teams25936 5549 Node: omp_get_max_threads26630 5550 Node: omp_get_nested27381 5551 Node: omp_get_num_devices28989 5552 Node: omp_get_num_procs29510 5553 Node: omp_get_num_teams30049 5554 Node: omp_get_num_threads30565 5555 Node: omp_get_proc_bind31654 5556 Node: omp_get_schedule32677 5557 Node: omp_get_supported_active_levels33646 5558 Node: omp_get_team_num34432 5559 Node: omp_get_team_size34946 5560 Node: omp_get_teams_thread_limit35912 5561 Node: omp_get_thread_limit36674 5562 Node: omp_get_thread_num37302 5563 Node: omp_in_parallel38174 5564 Node: omp_in_final38823 5565 Node: omp_is_initial_device39497 5566 Node: omp_set_default_device40190 5567 Node: omp_set_dynamic40981 5568 Node: omp_set_max_active_levels41867 5569 Node: omp_set_nested42789 5570 Node: omp_set_num_teams43984 5571 Node: omp_set_num_threads44857 5572 Node: omp_set_schedule45728 5573 Node: omp_set_teams_thread_limit46822 5574 Node: omp_init_lock47824 5575 Node: omp_set_lock48487 5576 Node: omp_test_lock49342 5577 Node: omp_unset_lock50318 5578 Node: omp_destroy_lock51249 5579 Node: omp_init_nest_lock51926 5580 Node: omp_set_nest_lock52661 5581 Node: omp_test_nest_lock53576 5582 Node: omp_unset_nest_lock54603 5583 Node: omp_destroy_nest_lock55618 5584 Node: omp_get_wtick56369 5585 Node: omp_get_wtime56961 5586 Node: omp_fulfill_event57763 5587 Node: Environment Variables58784 5588 Node: OMP_CANCELLATION60573 5589 Node: OMP_DISPLAY_ENV61106 5590 Node: OMP_DEFAULT_DEVICE61809 5591 Node: OMP_DYNAMIC62589 5592 Node: OMP_MAX_ACTIVE_LEVELS63185 5593 Node: OMP_MAX_TASK_PRIORITY64112 5594 Node: OMP_NESTED64770 5595 Node: OMP_NUM_TEAMS65797 5596 Node: OMP_NUM_THREADS66470 5597 Node: OMP_PROC_BIND67275 5598 Node: OMP_PLACES68617 5599 Node: OMP_STACKSIZE71306 5600 Node: OMP_SCHEDULE72130 5601 Node: OMP_TARGET_OFFLOAD72830 5602 Node: OMP_TEAMS_THREAD_LIMIT73792 5603 Node: OMP_THREAD_LIMIT74599 5604 Node: OMP_WAIT_POLICY75209 5605 Node: GOMP_CPU_AFFINITY75901 5606 Node: GOMP_DEBUG77631 5607 Node: GOMP_STACKSIZE78138 5608 Node: GOMP_SPINCOUNT78969 5609 Node: GOMP_RTEMS_THREAD_POOLS80173 5610 Node: Enabling OpenACC82356 5611 Node: OpenACC Runtime Library Routines83257 5612 Node: acc_get_num_devices87538 5613 Node: acc_set_device_type88264 5614 Node: acc_get_device_type89028 5615 Node: acc_set_device_num90041 5616 Node: acc_get_device_num90858 5617 Node: acc_get_property91657 5618 Node: acc_async_test93880 5619 Node: acc_async_test_all94868 5620 Node: acc_wait95768 5621 Node: acc_wait_all96631 5622 Node: acc_wait_all_async97392 5623 Node: acc_wait_async98144 5624 Node: acc_init98852 5625 Node: acc_shutdown99497 5626 Node: acc_on_device100164 5627 Node: acc_malloc101168 5628 Node: acc_free101667 5629 Node: acc_copyin102094 5630 Node: acc_present_or_copyin103681 5631 Node: acc_create105459 5632 Node: acc_present_or_create107091 5633 Node: acc_copyout108877 5634 Node: acc_delete111181 5635 Node: acc_update_device113428 5636 Node: acc_update_self115002 5637 Node: acc_map_data116592 5638 Node: acc_unmap_data117277 5639 Node: acc_deviceptr117798 5640 Node: acc_hostptr118368 5641 Node: acc_is_present118932 5642 Node: acc_memcpy_to_device120459 5643 Node: acc_memcpy_from_device121122 5644 Node: acc_attach121789 5645 Node: acc_detach122436 5646 Node: acc_get_current_cuda_device123215 5647 Node: acc_get_current_cuda_context123800 5648 Node: acc_get_cuda_stream124400 5649 Node: acc_set_cuda_stream124991 5650 Node: acc_prof_register125662 5651 Node: acc_prof_unregister126221 5652 Node: acc_prof_lookup126788 5653 Node: acc_register_library127309 5654 Node: OpenACC Environment Variables127875 5655 Node: ACC_DEVICE_TYPE128447 5656 Node: ACC_DEVICE_NUM128683 5657 Node: ACC_PROFLIB128937 5658 Node: GCC_ACC_NOTIFY129268 5659 Node: CUDA Streams Usage129488 5660 Ref: CUDA Streams Usage-Footnote-1131389 5661 Node: OpenACC Library Interoperability131498 5662 Ref: OpenACC Library Interoperability-Footnote-1137866 5663 Ref: OpenACC Library Interoperability-Footnote-2138118 5664 Node: OpenACC Profiling Interface138326 5665 Node: The libgomp ABI148354 5666 Node: Implementing MASTER construct149207 5667 Node: Implementing CRITICAL construct149624 5668 Node: Implementing ATOMIC construct150365 5669 Node: Implementing FLUSH construct150848 5670 Node: Implementing BARRIER construct151121 5671 Node: Implementing THREADPRIVATE construct151392 5672 Node: Implementing PRIVATE clause152047 5673 Node: Implementing FIRSTPRIVATE LASTPRIVATE COPYIN and COPYPRIVATE clauses152630 5674 Node: Implementing REDUCTION clause153956 5675 Node: Implementing PARALLEL construct154516 5676 Node: Implementing FOR construct155775 5677 Node: Implementing ORDERED construct157775 5678 Node: Implementing SECTIONS construct158083 5679 Node: Implementing SINGLE construct158851 5680 Node: Implementing OpenACC's PARALLEL construct159565 5681 Node: Reporting Bugs159825 5682 Node: Copying160188 5683 Node: GNU Free Documentation License197737 5684 Node: Funding222862 5685 Node: Library Index225388 5686 5687 End Tag Table 5688
Indexes created Tue Mar 24 00:24:13 UTC 2026