api/e_appendix.txt

// Copyright 2017-2019 The Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[appendix]
= Changes

// (Jon) Are these section and table numbers for the current spec, in which
// case they should turn into asciidoctor xrefs, or to older specs?

== Summary of changes from OpenCL 1.0

The following features are added to the OpenCL 1.1 platform layer and
runtime (_sections 4 and 5_):

  * Following queries to _table 4.3_
  ** CL_DEVICE_NATIVE_VECTOR_WIDTH_{CHAR | SHORT | INT | LONG | FLOAT |
     DOUBLE | HALF}
  ** CL_DEVICE_HOST_UNIFIED_MEMORY
  ** CL_DEVICE_OPENCL_C_VERSION
  * CL_CONTEXT_NUM_DEVICES to the list of queries specified to
    *clGetContextInfo*.
  * Optional image formats: CL_Rx, CL_RGx and CL_RGBx.
  * Support for sub-buffer objects ability to create a buffer object that
    refers to a specific region in another buffer object using
    *clCreateSubBuffer*.
  * *clEnqueueReadBufferRect*, *clEnqueueWriteBufferRect* and
    *clEnqueueCopyBufferRect* APIs to read from, write to and copy a
    rectangular region of a buffer object respectively.
  * *clSetMemObjectDestructorCallback* API to allow a user to register a
    callback function that will be called when the memory object is deleted
    and its resources freed.
  * Options that <<opencl-c-version, control the OpenCL C version>> used
    when building a program executable.
  * CL_KERNEL_PREFERRED_WORK_GROUP_SIZE_MULTIPLE to the list of queries
    specified to *clGetKernelWorkGroupInfo*.
  * Support for user events.
    User events allow applications to enqueue commands that wait on a user
    event to finish before the command is executed by the device.
    Following new APIs are added - *clCreateUserEvent* and
    *clSetUserEventStatus*.
  * *clSetEventCallback* API to register a callback function for a specific
    command execution status.

The following modifications are made to the OpenCL 1.1 platform layer and
runtime (_sections 4 and 5_):

  * Following queries in _table 4.3_
  ** CL_DEVICE_MAX_PARAMETER_SIZE from 256 to 1024 bytes
  ** CL_DEVICE_LOCAL_MEM_SIZE from 16 KB to 32 KB.
  * The _global_work_offset_ argument in *clEnqueueNDRangeKernel* can be a
    non-`NULL` value.
  * All API calls except *clSetKernelArg* are thread-safe.

The following features are added to the OpenCL C programming language
(_section 6_) in OpenCL 1.1:

  * 3-component vector data types.
  * New built-in functions
  ** *get_global_offset* work-item function defined in section _6.12.1_.
  ** *minmag*, *maxmag* math functions defined in section _6.12.2_.
  ** *clamp* integer function defined in _section 6.12.3_.
  ** (vector, scalar) variant of integer functions *min* and *max* in
     _section 6.12.3_.
  ** *async_work_group_strided_copy* defined in section _6.12.10_.
  ** *vec_step*, *shuffle* and *shuffle2* defined in section _6.12.12_.
  * *cl_khr_byte_addressable_store* extension is a core feature.
  * *cl_khr_global_int32_base_atomics*,
    *cl_khr_global_int32_extended_atomics*,
    *cl_khr_local_int32_base_atomics* and
    *cl_khr_local_int32_extended_atomics* extensions are core features.
    The built-in atomic function names are changed to use the *atomic_*
    prefix instead of *atom_*.
  * Macros CL_VERSION_1_0 and CL_VERSION_1_1.

The following features in OpenCL 1.0 are deprecated (see glossary) in OpenCL
1.1:

  * The *clSetCommandQueueProperty* API is no longer supported in OpenCL
    1.1.
  * The `+__ROUNDING_MODE__+` macro is no longer supported in OpenCL C 1.1.
  * The cl-strict-aliasing option that can be specified in _options_
    argument to *clBuildProgram* is no longer supported in OpenCL 1.1.

The following new extensions are added to _section 9_ in OpenCL 1.1:

  * *cl_khr_gl_event* for creating a CL event object from a GL sync object.
  * *cl_khr_d3d10_sharing* for sharing memory objects with Direct3D 10.

The following modifications are made to the OpenCL ES Profile described in
_section 10_ in OpenCL 1.1:

  * 64-bit integer support is optional.


== Summary of changes from OpenCL 1.1

The following features are added to the OpenCL 1.2 platform layer and
runtime (_sections 4 and 5_):

  * Custom devices and built-in kernels are supported.
  * Device partitioning that allows a device to be partitioned based on a
    number of partitioning schemes supported by the device.
  * Extend _cl_mem_flags_ to describe how the host accesses the data in a
    cl_mem object.
  * *clEnqueueFillBuffer* and *clEnqueueFillImage* to support filling a
    buffer with a pattern or an image with a color.
  * Add CL_MAP_WRITE_INVALIDATE_REGION to _cl_map_flags_.
    Appropriate clarification to the behavior of CL_MAP_WRITE has been added
    to the spec.
  * New image types: 1D image, 1D image from a buffer object, 1D image array
    and 2D image arrays.
  * *clCreateImage* to create an image object.
  * *clEnqueueMigrateMemObjects* API that allows a developer to have
    explicit control over the location of memory objects or to migrate a
    memory object from one device to another.
  * Support separate compilation and linking of programs.
  * Additional queries to get the number of kernels and kernel names in a
    program have been added to *clGetProgramInfo*.
  * Additional queries to get the compile and link status and options have
    been added to *clGetProgramBuildInfo*.
  * *clGetKernelArgInfo* API that returns information about the arguments of
    a kernel.
  * *clEnqueueMarkerWithWaitList* and *clEnqueueBarrierWithWaitList* APIs.

The following features are added to the OpenCL C programming language
(_section 6_) in OpenCL 1.2:

  * Double-precision is now an optional core feature instead of an
    extension.
  * New built in image types: *image1d_t*, *image1d_array_t* and
    *image2d_array_t* .
  * New built-in functions
  ** Functions to read from and write to a 1D image, 1D and 2D image arrays
     described in _sections 6.12.14.2_, _6.12.14.3_ and _6.12.14.4_.
  ** Sampler-less image read functions described in _section 6.12.14.3_.
  ** *popcount* integer function described in _section 6.12.3_.
  ** *printf* function described in _section 6.12.13_.
  * Storage class specifiers extern and static as described in _section
    6.8_.
  * Macros `CL_VERSION_1_2` and `+__OPENCL_C_VERSION__+`.

The following APIs in OpenCL 1.1 are deprecated (see glossary) in OpenCL
1.2:

  * *clEnqueueMarker*, *clEnqueueBarrier* and *clEnqueueWaitForEvents*
  * *clCreateImage2D* and *clCreateImage3D*
  * *clUnloadCompiler* and *clGetExtensionFunctionAddress*
  * *clCreateFromGLTexture2D* and *clCreateFromGLTexture3D*

The following queries are deprecated (see glossary) in OpenCL 1.2:

  * *CL_DEVICE_MIN_DATA_TYPE_ALIGN_SIZE* in _table 4.3_ queried using
    *clGetDeviceInfo*.


== Summary of changes from OpenCL 1.2

The following features are added to the OpenCL 2.0 platform layer and
runtime (_sections 4 and 5_):

  * Shared virtual memory.
  * Device queues used to enqueue kernels on the device.
  * Pipes.
  * Images support for 2D image from buffer, depth images and sRGB images.

The following modifications are made to the OpenCL 2.0 platform layer and
runtime (sections 4 and 5):

  * All API calls except *clSetKernelArg*, *clSetKernelArgSVMPointer* and
    *clSetKernelExecInfo* are thread-safe.

The following features are added to the OpenCL C programming language
(_section 6_) in OpenCL 2.0:

  * Clang Blocks.
  * Kernels enqueing kernels to a device queue.
  * Program scope variables in global address space.
  * Generic address space.
  * C1x atomics.
  * New built-in functions (sections 6.13.9, 6.13.11, 6.13.15 and 6.14).
  * Support images with the read_write qualifier.
  * 3D image writes are a core feature.
  * The CL_VERSION_2_0 macro.

The following APIs are deprecated (see glossary) in OpenCL 2.0:

  * *clCreateCommandQueue*, *clCreateSampler* and *clEnqueueTask*

The following queries are deprecated (see glossary) in OpenCL 2.0:

  * *CL_DEVICE_HOST_UNIFIED_MEMORY* in _table 4.3_ queried using
    *clGetDeviceInfo*.
  * *CL_IMAGE_BUFFER* in _table 5.10_ is deprecated.
  * *CL_DEVICE_QUEUE_PROPERTIES* is replaced by
    *CL_DEVICE_QUEUE_ON_HOST_PROPERTIES*.
  * The explicit memory fence functions defined in section 6.12.9 of the
    OpenCL 1.2 specification.
  * The OpenCL 1.2 atomic built-in functions for 32-bit integer and
    floating-point data types defined in section 6.12.11 of the OpenCL 1.2
    specification.


== Summary of changes from OpenCL 2.0

The following features are added to the OpenCL 2.1 platform layer and
runtime (_sections 4 and 5_):

  * *clGetKernelSubGroupInfo* API call.
  * *CL_KERNEL_MAX_NUM_SUB_GROUPS*, *CL_KERNEL_COMPILE_NUM_SUB_GROUPS*
    additions to table 5.21 of the API specification.
  * *clCreateProgramWithIL* API call.
  * *clGetHostTimer* and *clGetDeviceAndHostTimer* API calls.
  * *clEnqueueSVMMigrateMem* API call.
  * *clCloneKernel* API call.
  * *clSetDefaultDeviceCommandQueue* API call.
  * *CL_PLATFORM_HOST_TIMER_RESOLUTION* added to table 4.1 of the API
    specification.
  * *CL_DEVICE_IL_VERSION*, *CL_DEVICE_MAX_NUM_SUB_GROUPS*,
    *CL_DEVICE_SUB_GROUP_INDEPENDENT_FORWARD_PROGRESS* added to table 4.3 of
    the API specification.
  * *CL_PROGRAM_IL* to table 5.17 of the API specification.
  * *CL_QUEUE_DEVICE_DEFAULT* added to table 5.2 of the API specification.
  * Added table 5.22 to the API specification with the enums:
    *CL_KERNEL_MAX_SUB_GROUP_SIZE_FOR_NDRANGE*,
    *CL_KERNEL_SUB_GROUP_COUNT_FOR_NDRANGE* and
    *CL_KERNEL_LOCAL_SIZE_FOR_SUB_GROUP_COUNT*

The following modifications are made to the OpenCL 2.1 platform layer and
runtime (sections 4 and 5):

  * All API calls except *clSetKernelArg*, *clSetKernelArgSVMPointer*,
    *clSetKernelExecInfo* and *clCloneKernel* are thread-safe.

The OpenCL C kernel language is no longer chapter 6.
The OpenCL C kernel language is not updated for OpenCL 2.1.
The OpenCL 2.0 kernel language will still be consumed by OpenCL 2.1
runtimes.

The SPIR-V IL specification has been added.


== Summary of changes from OpenCL 2.1

The following changes have been made to the OpenCL 2.2 execution model
(section 3)

  * Added the third prerequisite (executing non-trivial constructors for
    program scope global variables).

The following features are added to the OpenCL 2.2 platform layer and
runtime (_sections 4 and 5_):

  * *clSetProgramSpecializationConstant* API call
  * *clSetProgramReleaseCallback* API call
  * Queries for CL_PROGRAM_SCOPE_GLOBAL_CTORS_PRESENT,
    CL_PROGRAM_SCOPE_GLOBAL_DTORS_PRESENT

The following modifications are made to the OpenCL 2.2 platform layer and
runtime (section 4 and 5):

  * Modified description of CL_DEVICE_MAX_CLOCK_FREQUENCY query.
  * Added a new error code CL_MAX_SIZE_RESTRICTION_EXCEEDED to
    *clSetKernelArg* API call

Added definition of Deprecation and Specialization constants to the
glossary.