Merge pull request #625 from gmlueck/gmlueck/execution-capabilities

Clarify and deprecate "execution_capabilities"

adoc/chapters/programming_interface.adoc

@@ -2799,12 +2799,19 @@ struct execution_capabilities {
 } // namespace sycl::info::device
 ----
 
+Deprecated by SYCL 2020.
+
 _Remarks:_ Template parameter to [api]#device::get_info#.
 
-_Returns:_ A [code]#std::vector# of the [api]#info::execution_capability# values
+_Returns:_ Only supported when the backend of this device is OpenCL (see
+<<chapter:opencl-backend>>).
+Returns a [code]#std::vector# of the [api]#info::execution_capability# values
 describing the supported execution capabilities.
-Note that this information is intended for OpenCL interoperability only as SYCL
-only supports [api]#info::execution_capability::exec_kernel#.
+Unless the device type is [api]#info::device_type::custom#, the returned vector
+will always include [api]#info::execution_capability::exec_kernel#.
+
+_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code if the
+backend of this device is not OpenCL.
 
 '''
 
@@ -3709,6 +3716,11 @@ enum class global_mem_cache_type : /* unspecified */ {
 [[sec:device-enum-execution-capability]]
 ===== Execution capability
 
+Deprecated by SYCL 2020.
+
+The [code]#info::execution_capability# enumeration tells the type of kernels
+that can be submitted to a device from the OpenCL backend.
+
 [source,role=synopsis]
 ----
 namespace sycl::info {
@@ -3719,6 +3731,24 @@ enum class execution_capability : /* unspecified */ {
 } // namespace sycl::info
 ----
 
+'''
+
+.[apidef]#info::execution_capability::exec_kernel#
+[role=synopsis,id=api:info-execution-capability-exec-kernel]
+--
+Device can execute SYCL kernels.
+--
+
+'''
+
+.[apidef]#info::execution_capability::exec_native_kernel#
+[role=synopsis,id=api:info-execution-capability-exec-native-kernel]
+--
+Device can execute native OpenCL kernels.
+--
+
+'''
+
 
 [[sec:queue-class]]
 === Queue class

adoc/config/api_xrefs.adoc

@@ -15,7 +15,6 @@
   info::device_type::custom=sec:device-enum-device-type \
   info::device_type::all=sec:device-enum-device-type \
   info::execution_capability=sec:device-enum-execution-capability \
-  info::execution_capability::exec_kernel=sec:device-enum-execution-capability \
   info::fp_config=sec:device-enum-fp-config \
   info::global_mem_cache_type=sec:device-enum-global-mem-cache-type \
   info::local_mem_type=sec:device-enum-local-mem-type \