add a specification change log (#718)

* added change log for v3.0.6

* added change log for v3.0.7

* added change log for other OpenCL versions

* move build option change to the API spec

OpenCL_C.txt

@@ -12968,6 +12968,10 @@ one of the integers 0, 1, ... h~t~ - 1.
     References are to sections of this specific version, referred to as the
     "`Embedded C Specification`", although other versions exist.
 
+:numbered!:
+
+include::c/appendix_a.asciidoc[]
+
 // This is generatig asciidoctor errors:
 //  OpenCL_C.txt: Failed to load AsciiDoc document - undefined method `+' for nil:NilClass
 // Disabling acknowledgements for now.  We have them in the API spec already.

OpenCL_Env.txt

@@ -43,3 +43,8 @@ include::env/numerical_compliance.asciidoc[]
 include::env/image_addressing_and_filtering.asciidoc[]
 
 include::env/references.asciidoc[]
+
+:numbered!:
+:leveloffset: 1
+
+include::env/appendix_a.asciidoc[]

api/appendix_e.asciidoc

@@ -6,8 +6,8 @@
 [[changes_to_opencl]]
 = Changes to OpenCL
 
-Changes to the OpenCL API and OpenCL C between successive versions are
-summarized below.
+Changes to the OpenCL API and OpenCL C specifications between successive
+versions are summarized below.
 
 // (Jon) Are these section and table numbers for the current spec, in which
 // case they should turn into asciidoctor xrefs, or to older specs?
@@ -457,3 +457,72 @@ test suite that the device has fully passed in accordance with the official
 conformance process:
 
   * {CL_DEVICE_LATEST_CONFORMANCE_VERSION_PASSED}
+
+== Summary of changes from OpenCL 3.0
+
+The first non-provisional version of the OpenCL 3.0 specifications was *v3.0.5*.
+
+Changes from *v3.0.5*:
+
+  * Fixed the calculation in "mapping work-items onto an NDRange".
+  * Added new extensions:
+      ** `cl_khr_extended_versioning`
+      ** `cl_khr_subgroup_extended_types`
+      ** `cl_khr_subgroup_non_uniform_vote`
+      ** `cl_khr_subgroup_ballot`
+      ** `cl_khr_subgroup_non_uniform_arithmetic`
+      ** `cl_khr_subgroup_shuffle`
+      ** `cl_khr_subgroup_shuffle_relative`
+      ** `cl_khr_subgroup_clustered_reduce`
+
+Changes from *v3.0.6*:
+
+  * Removed erroneous condition for {CL_INVALID_KERNEL_ARGS}.
+  * Fixed the spelling of `-cl-no-signed-zeros`.
+  * Clarified the table structure in the backwards compatibility appendix.
+  * Clarified that `-cl-unsafe-math-optimizations` also implies `-cl-denorms-are-zero`.
+  * Added new extensions:
+      ** `cl_khr_extended_bit_ops`
+      ** `cl_khr_pci_bus_info`
+      ** `cl_khr_spirv_extended_debug_info`
+      ** `cl_khr_spirv_linkonce_odr`
+      ** `cl_khr_suggested_local_work_size`
+
+Changes from *v3.0.7*:
+
+  * Clarified optionality support for double-precision literals.
+  * Removed unnecessary phrase from subgroup mask function descriptions.
+  * Added _input_slice_pitch_ error condition for read and write image APIs.
+  * Added new extension:
+      ** `cl_khr_integer_dot_product`
+
+Changes from *v3.0.8*:
+
+  * Added a missing error condition for {clGetKernelSuggestedLocalWorkSizeKHR}.
+  * Clarified requirements for {CL_DEVICE_DOUBLE_FP_CONFIG} prior to OpenCL 2.0.
+  * Clarified the behavior of ballot operations for remainder subgroups.
+  * Added new extensions:
+      ** `cl_khr_integer_dot_product` (version 2)
+      ** `cl_khr_semaphore` (provisional)
+      ** `cl_khr_external_semaphore` (provisional)
+      ** `cl_khr_external_semaphore_dx_fence` (provisional)
+      ** `cl_khr_external_semaphore_opaque_fd` (provisional)
+      ** `cl_khr_external_semaphore_sync_fd` (provisional)
+      ** `cl_khr_external_semaphore_win32` (provisional)
+      ** `cl_khr_external_memory` (provisional)
+      ** `cl_khr_external_memory_dma_buf` (provisional)
+      ** `cl_khr_external_memory_dx` (provisional)
+      ** `cl_khr_external_memory_opaque_fd` (provisional)
+      ** `cl_khr_external_memory_win32` (provisional)
+
+Changes from *v3.0.9*:
+
+  * Relaxed memory object acquire error checking requirements for OpenGL, EGL, and DirectX interop extensions.
+  * Added a missing error condition for {clGetSemaphoreHandleForTypeKHR}.
+  * Clarified that {clCompileProgram} is valid for programs created from SPIR.
+  * Documented the possible state of a kernel object after a failed call to {clSetKernelArg}.
+  * Added new extensions:
+      ** `cl_khr_async_copy_fence` (final)
+      ** `cl_khr_extended_async_copies` (final)
+      ** `cl_khr_expect_assume`
+      ** `cl_khr_command_buffer` (provisional)

c/appendix_a.asciidoc

@@ -0,0 +1,38 @@
+// Copyright 2017-2021 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_to_opencl]]
+= Changes to OpenCL
+
+Changes to the OpenCL C specifications between successive versions are
+summarized below.
+
+== Summary of changes from OpenCL 3.0
+
+The first non-provisional version of the OpenCL 3.0 specifications was *v3.0.5*.
+
+Changes from *v3.0.5*:
+
+  * Clarified that `memory_scope_all_devices` is supported only for OpenCL C 3.0 or newer.
+  * Defined ULP overflow leniency.
+  * Removed a confusing phrase about kernel argument pointer types.
+  * Clarified usage of feature test macros pre-OpenCL C 3.0.
+  * Clarified relationship between optional core features and extensions.
+  * Deprecated the `+__OPENCL_C_VERSION__+` predefined macro and clarified possible values of the macro for different versions of OpenCL.
+
+Changes from *v3.0.6*:
+
+  * Clarified the argument to *vec_step* is not evaluated.
+  * Improved description for pipe specifier.
+  * Fixed parameter name in *work_group_broadcast* description.
+  * Clarified that the size of a pipe is implementation-defined.
+  * Moved descriptions of the identify value for exclusive scans.
+  * Fixed several bugs and formatting in the fast math ULP tables.
+  * Clarified the behavior of *work_group_broadcast*.
+  * Clarified the minimum OpenCL C version for the `opencl_unroll_hint` attribute.
+
+Changes from *v3.0.7*:
+
+  * Clarified optionality support for double-precision literals.

env/appendix_a.asciidoc

@@ -0,0 +1,41 @@
+// Copyright 2017-2021 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_to_opencl]]
+= Changes to OpenCL
+
+Changes to the OpenCL SPIR-V Environment specifications between successive
+versions are summarized below.
+
+== Summary of changes from OpenCL 3.0
+
+The first non-provisional version of the OpenCL 3.0 specifications was *v3.0.5*.
+
+Changes from *v3.0.5*:
+
+  * Clarified subgroup barrier behavior in non-uniform control flow.
+  * Added required alignment of types.
+  * Added new extensions:
+      ** `cl_khr_subgroup_extended_types`
+      ** `cl_khr_subgroup_non_uniform_vote`
+      ** `cl_khr_subgroup_ballot`
+      ** `cl_khr_subgroup_non_uniform_arithmetic`
+      ** `cl_khr_subgroup_shuffle`
+      ** `cl_khr_subgroup_shuffle_relative`
+      ** `cl_khr_subgroup_clustered_reduce`
+
+Changes from *v3.0.6*:
+
+  * Explicitly say that *OpTypeSampledImage* may be used in an OpenCL environment.
+  * Added the required type for SPIR-V built-in variables.
+  * Fixed several bugs and formatting in the fast math ULP tables.
+  * Added new extensions:
+      ** `cl_khr_extended_bit_ops`
+      ** `cl_khr_spirv_extended_debug_info`
+      ** `cl_khr_spirv_linkonce_odr`
+
+Changes from *v3.0.8*:
+
+  * Clarified that some OpenCL `khr` extensions also require SPIR-V extensions.