R 1 The OpenACC 2 Application Programming Interface 3 Version 2.7 4 OpenACC-Standard.org 5 November, 2018 The OpenACC R API 6 Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, 7 no part of this document may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form 8 or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express 9 written permission of the authors. 10 c 2011-2018 OpenACC-Standard.org. All rights reserved. 2 The OpenACC R API 11 Contents 12 1. Introduction 7 13 1.1. Scope ......................................... 7 14 1.2. ExecutionModel ................................... 7 15 1.3. MemoryModel .................................... 9 16 1.4. Conventions used in this document . 11 17 1.5. Organization of this document . 11 18 1.6. References...................................... 12 19 1.7. Changes from Version 1.0 to 2.0 . 12 20 1.8. Corrections in the August 2013 document . 13 21 1.9. Changes from Version 2.0 to 2.5 . 14 22 1.10. Changes from Version 2.5 to 2.6 . 15 23 1.11. Changes from Version 2.6 to 2.7 . 16 24 1.12. Topics Deferred For a Future Revision . ..... 16 25 2. Directives 19 26 2.1. DirectiveFormat ................................... 19 27 2.2. Conditional Compilation . 20 28 2.3. Internal Control Variables . 20 29 2.3.1. Modifying and Retrieving ICV Values . 20 30 2.4. Device-SpecificClauses .............................. 21 31 2.5. Compute Constructs . 22 32 2.5.1. Parallel Construct . 22 33 2.5.2. KernelsConstruct............................... 23 34 2.5.3. SerialConstruct................................ 25 35 2.5.4. ifclause.................................... 27 36 2.5.5. selfclause................................... 27 37 2.5.6. asyncclause ................................. 27 38 2.5.7. waitclause .................................. 27 39 2.5.8. num gangsclause............................... 27 40 2.5.9. num workersclause ............................. 27 41 2.5.10. vector lengthclause ............................. 28 42 2.5.11.privateclause................................. 28 43 2.5.12. firstprivate clause . 28 44 2.5.13.reductionclause ............................... 28 45 2.5.14.defaultclause................................. 29 46 2.6. DataEnvironment................................... 30 47 2.6.1. Variables with Predetermined Data Attributes . 30 48 2.6.2. Data Regions and Data Lifetimes . 31 49 2.6.3. Data Structures with Pointers . 31 50 2.6.4. DataConstruct ................................ 32 3 The OpenACC R API 51 2.6.5. Enter Data and Exit Data Directives . 33 52 2.6.6. ReferenceCounters.............................. 35 53 2.6.7. Attachment Counter . 35 54 2.7. DataClauses ..................................... 36 55 2.7.1. Data Specification in Data Clauses . 36 56 2.7.2. Data Clause Actions . 38 57 2.7.3. deviceptrclause................................ 41 58 2.7.4. presentclause................................. 41 59 2.7.5. copyclause.................................. 42 60 2.7.6. copyinclause................................. 42 61 2.7.7. copyoutclause ................................ 43 62 2.7.8. createclause ................................. 43 63 2.7.9. no createclause................................ 44 64 2.7.10.deleteclause ................................. 44 65 2.7.11.attachclause ................................. 45 66 2.7.12.detachclause ................................. 45 67 2.8. Host DataConstruct ................................. 45 68 2.8.1. use deviceclause............................... 46 69 2.8.2. ifclause.................................... 46 70 2.8.3. if presentclause ............................... 47 71 2.9. LoopConstruct .................................... 47 72 2.9.1. collapseclause ................................ 48 73 2.9.2. gangclause.................................. 48 74 2.9.3. workerclause................................. 49 75 2.9.4. vectorclause ................................. 49 76 2.9.5. seqclause................................... 50 77 2.9.6. autoclause .................................. 50 78 2.9.7. tile clause . 50 79 2.9.8. device typeclause .............................. 50 80 2.9.9. independentclause .............................. 51 81 2.9.10.privateclause................................. 51 82 2.9.11.reductionclause ............................... 51 83 2.10.CacheDirective................................... 52 84 2.11. Combined Constructs . 53 85 2.12. Atomic Construct . 54 86 2.13.DeclareDirective .................................. 59 87 2.13.1. device residentclause ............................ 60 88 2.13.2.createclause ................................. 61 89 2.13.3.linkclause .................................. 61 90 2.14. Executable Directives . 62 91 2.14.1.InitDirective ................................. 62 92 2.14.2. Shutdown Directive . 63 93 2.14.3.SetDirective ................................. 64 94 2.14.4.UpdateDirective ............................... 65 95 2.14.5.WaitDirective ................................ 67 96 2.14.6. Enter Data Directive . 67 97 2.14.7. Exit Data Directive . 67 4 The OpenACC R API 98 2.15. Procedure Calls in Compute Regions . 67 99 2.15.1. Routine Directive . 68 100 2.15.2.GlobalDataAccess.............................. 70 101 2.16. Asynchronous Behavior . 71 102 2.16.1.asyncclause ................................. 71 103 2.16.2.waitclause .................................. 72 104 2.16.3.WaitDirective ................................ 72 105 2.17. Fortran Optional Arguments . 73 106 3. Runtime Library 75 107 3.1. Runtime Library Definitions . 75 108 3.2. Runtime Library Routines . 76 109 3.2.1. acc get num devices............................. 76 110 3.2.2. acc set device type.............................. 77 111 3.2.3. acc get device type.............................. 77 112 3.2.4. acc set device num.............................. 78 113 3.2.5. acc get device num.............................. 78 114 3.2.6. acc get property ............................... 79 115 3.2.7. acc init .................................... 80 116 3.2.8. acc shutdown................................. 81 117 3.2.9. acc async test................................. 81 118 3.2.10. acc async test all............................... 82 119 3.2.11. acc wait.................................... 82 120 3.2.12. acc wait async ................................ 83 121 3.2.13. acc wait all.................................. 83 122 3.2.14. acc wait all async .............................. 84 123 3.2.15. acc get default async............................. 84 124 3.2.16. acc set default async............................. 85 125 3.2.17. acc on device................................. 85 126 3.2.18. acc malloc .................................. 86 127 3.2.19. acc free.................................... 86 128 3.2.20. acc copyin .................................. 86 129 3.2.21. acc create................................... 88 130 3.2.22. acc copyout.................................. 89 131 3.2.23. acc delete................................... 90 132 3.2.24. acc update device .............................. 91 133 3.2.25. acc update self................................ 91 134 3.2.26. acc map data................................. 92 135 3.2.27. acc unmap data................................ 93 136 3.2.28. acc deviceptr................................. 93 137 3.2.29. acc hostptr .................................. 93 138 3.2.30. acc is present................................. 94 139 3.2.31. acc memcpy to device............................ 94 140 3.2.32. acc memcpy from device .......................... 95 141 3.2.33. acc memcpy device ............................. 95 142 3.2.34. acc attach................................... 96 143 3.2.35. acc detach .................................. 96 5 The OpenACC R API 144 4. Environment Variables 99 145 4.1. ACC DEVICE TYPE................................. 99 146 4.2. ACC DEVICE NUM................................. 99 147 4.3. ACC PROFLIB.................................... 99 148 5. Profiling Interface 101 149 5.1. Events......................................... 101 150 5.1.1. Runtime Initialization and Shutdown . 102 151 5.1.2. Device Initialization and Shutdown . 102 152 5.1.3. Enter Data and Exit Data . 103 153 5.1.4. Data Allocation . 103 154 5.1.5. DataConstruct ................................ 104 155 5.1.6. UpdateDirective ............................... 104 156 5.1.7. ComputeConstruct.............................. 104 157 5.1.8. EnqueueKernelLaunch . 105 158 5.1.9. Enqueue Data Update (Upload and Download) . 105 159 5.1.10.Wait...................................... 106 160 5.2. Callbacks Signature . 106 161 5.2.1. First Argument: General Information . 107 162 5.2.2. Second Argument: Event-Specific Information . 108 163 5.2.3. Third Argument: API-Specific Information . 111 164 5.3. LoadingtheLibrary.................................. 112 165 5.3.1. Library Registration . 113 166 5.3.2. Statically-Linked Library Initialization . 114 167 5.3.3. Runtime Dynamic Library Loading . 114 168 5.3.4. Preloading with LD PRELOAD ....................... 115 169 5.3.5. Application-Controlled Initialization . 116 170 5.4. Registering Event Callbacks . 116 171 5.4.1. Event Registration and Unregistration . 117 172 5.4.2. Disabling and Enabling Callbacks . 118 173 5.5. AdvancedTopics ................................... 119 174 5.5.1. DynamicBehavior .............................