The OpenCL Specification

1 Last Revision Date: 11/14/12 Page 1 The OpenCL Specification Version: Document Revision: 19 Khronos OpenCL Working Group Editor: Aaftab Munshi Last Revision Date: 11/14/12 Page 2 1. INTRODUCTION .. 12 2. GLOSSARY .. 14 OpenCL Class Diagram .. 20 3. THE OpenCL ARCHITECTURE .. 22 Platform Model .. 22 Platform Mixed Version Support .. 23 Execution Model .. 24 Execution Model: Context and Command Queues .. 26 Execution Model: Categories of Kernels .. 27 Memory Model .. 27 Memory Consistency .. 29 Programming Model .. 29 Data Parallel Programming Model.

2 29 Task Parallel Programming Model .. 30 Synchronization .. 30 Memory Objects .. 31 The OpenCL Framework .. 31 4. THE OpenCL PLATFORM LAYER .. 33 Querying Platform Info .. 33 Querying Devices .. 35 Partitioning a Device .. 50 Contexts .. 55 5. THE OpenCL RUNTIME .. 62 Command Queues .. 62 Buffer Objects .. 67 Creating Buffer Objects .. 67 Reading, Writing and Copying Buffer Objects .. 73 Filling Buffer Objects .. 85 Mapping Buffer Objects .. 87 Image Objects .. 91 Last Revision Date: 11/14/12 Page 3 Creating Image Objects .. 91 Image Format Descriptor .. 93 Image Descriptor.

3 96 Querying List of Supported Image Formats .. 97 Minimum List of Supported Image Formats .. 99 Reading, Writing and Copying Image Objects .. 99 Filling Image Objects .. 106 Copying between Image and Buffer Objects .. 108 Mapping Image Objects .. 113 Image Object Queries .. 116 Querying, Unmapping, Migrating, Retaining and Releasing Memory Objects .. 119 Retaining and Releasing Memory Objects .. 119 Unmapping Mapped Memory Objects .. 121 Accessing mapped regions of a memory object .. 123 Migrating Memory Objects .. 124 Memory Object Queries .. 126 Sampler Objects .. 129 Creating Sampler Objects.

4 129 Sampler Object Queries .. 131 Program Objects .. 133 Creating Program Objects .. 133 Building Program Executables .. 138 Separate Compilation and Linking of Programs .. 140 Compiler Options .. 146 Preprocessor options .. 146 Math Intrinsics Options .. 146 Optimization Options .. 147 Options to Request or Suppress Warnings .. 148 Options Controlling the OpenCL C version .. 148 Options for Querying Kernel Argument Information .. 149 Linker Options .. 149 Library Linking Options .. 149 Program Linking Options .. 150 Unloading the OpenCL Compiler .. 150 Program Object Queries .. 151 Kernel Objects.

5 158 Creating Kernel Objects .. 158 Setting Kernel Arguments .. 161 Kernel Object Queries .. 163 Executing Kernels .. 171 Event Objects .. 179 Markers, Barriers and Waiting for Events .. 188 Out-of-order Execution of Kernels and Memory Object Commands .. 191 Profiling Operations on Memory Objects and Kernels .. 192 Flush and Finish .. 195 Last Revision Date: 11/14/12 Page 4 6. THE OpenCL C PROGRAMMING LANGUAGE .. 197 Supported Data Types .. 197 Built-in Scalar Data Types .. 197 The half data type .. 199 Built-in Vector Data Types .. 200 Other Built-in Data Types .. 201 Reserved Data Types.

6 202 Alignment of Types .. 203 Vector Literals .. 203 Vector Components .. 204 Aliasing Rules .. 208 Keywords .. 208 Conversions and Type Casting .. 209 Implicit Conversions .. 209 Explicit Casts .. 209 Explicit Conversions .. 210 Data Types .. 211 Rounding Modes .. 211 Out-of-Range Behavior and Saturated Conversions .. 212 Explicit Conversion Examples .. 212 Reinterpreting Data As Another Type .. 213 Reinterpreting Types Using Unions .. 213 Reinterpreting Types Using as_type() and as_typen() .. 214 Pointer Casting .. 215 Usual Arithmetic Conversions .. 216 Operators .. 217 Vector Operations.

7 223 Address Space Qualifiers .. 224 __global (or global) .. 225 __local (or local) .. 225 __constant (or constant) .. 226 __private (or private) .. 227 Access Qualifiers .. 228 Function Qualifiers .. 229 __kernel (or kernel) .. 229 Optional Attribute Qualifiers .. 229 Storage-Class Specifiers .. 232 Restrictions .. 233 Preprocessor Directives and Macros .. 236 Attribute Qualifiers .. 238 Specifying Attributes of Types .. 239 Specifying Attributes of Functions .. 241 Specifying Attributes of Variables .. 241 Specifying Attributes of Blocks and Control-Flow-Statements .. 243 Last Revision Date: 11/14/12 Page 5 Extending Attribute Qualifiers.

8 243 Built-in Functions .. 244 Work-Item Functions .. 244 Math Functions .. 246 Floating-point macros and pragmas .. 254 Integer Functions .. 258 Common Functions .. 262 Geometric Functions .. 264 Relational Functions .. 266 Vector Data Load and Store Functions .. 269 Synchronization Functions .. 276 Explicit Memory Fence Functions .. 277 Async Copies from Global to Local Memory, Local to Global Memory, and Prefetch .. 278 Atomic Functions .. 281 Miscellaneous Vector Functions .. 284 printf .. 286 printf output synchronization .. 286 printf format string .. 286 Differences between OpenCL C and C99 printf.

9 292 Image Read and Write Functions .. 294 Samplers .. 294 Built-in Image Read Functions .. 297 Built-in Image Sampler-less Read Functions .. 305 Built-in Image Write Functions .. 311 Built-in Image Query Functions .. 314 Mapping image channels to color values returned by read_image and color values passed to write_image to image channels .. 316 7. OpenCL NUMERICAL COMPLIANCE .. 318 Rounding Modes .. 318 INF, NaN and Denormalized Numbers .. 318 Floating-Point Exceptions .. 319 Relative Error as ULPs .. 319 Edge Case Behavior .. 324 Additional Requirements Beyond C99 TC2 .. 324 Changes to C99 TC2 Behavior.

10 327 Edge Case Behavior in Flush To Zero Mode .. 328 8. IMAGE ADDRESSING AND FILTERING .. 329 Image Coordinates .. 329 Addressing and Filter Modes .. 329 Conversion Rules .. 336 Conversion rules for normalized integer channel data types .. 336 Converting normalized integer channel data types to floating-point values .. 336 Converting floating-point values to normalized integer channel data types .. 337 Last Revision Date: 11/14/12 Page 6 Conversion rules for half precision floating-point channel data type .. 339 Conversion rules for floating-point channel data type .. 339 Conversion rules for signed and unsigned 8-bit, 16-bit and 32-bit integer channel data types.