diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index a0747ca5..0bd0c64b 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -1624,7 +1624,7 @@ _Returns:_ A [code]#std::vector# of sub devices partitioned from this The returned vector contains as many sub devices as can be created such that each sub device contains [code]#count# compute units. If the device's total number of compute units (as returned by -[code]#info::device::max_compute_units#) is not evenly divided by [code]#count#, +[api]#info::device::max_compute_units#) is not evenly divided by [code]#count#, then the remaining compute units are not included in any of the sub devices. _Throws:_ @@ -1661,10 +1661,10 @@ _Throws:_ * An [code]#exception# with the [code]#errc::invalid# error code if the number of non-zero values in [code]#counts# exceeds the device's maximum number of - sub devices (as returned by [code]#info::device::partition_max_sub_devices#) - or if the total of all the values in the [code]#counts# vector exceeds the - total number of compute units in the device (as returned by - [code]#info::device::max_compute_units#). + sub devices (as returned by [api]#info::device::partition_max_sub_devices#) or + if the total of all the values in the [code]#counts# vector exceeds the total + number of compute units in the device (as returned by + [api]#info::device::max_compute_units#). ''' @@ -1706,7 +1706,7 @@ of the following values: into sub devices comprised of compute units that share memory subsystems at this level. The user may determine what happened via - [code]#info::device::partition_type_affinity_domain#. + [api]#info::device::partition_type_affinity_domain#. _Throws:_ @@ -1928,9 +1928,9 @@ can be put into vectors. The vector width is defined as the number of scalar elements that can be stored in the vector. Must return 0 for [code]#info::device::preferred_vector_width_double# if the -device does not have [code]#aspect::fp64# and must return 0 for +device does not have [api]#aspect::fp64# and must return 0 for [code]#info::device::preferred_vector_width_half# if the device does not have -[code]#aspect::fp16#. +[api]#aspect::fp16#. ''' @@ -1968,9 +1968,9 @@ _Returns:_ The native ISA vector width. The vector width is defined as the number of scalar elements that can be stored in the vector. Must return 0 for [code]#info::device::native_vector_width_double# if the device -does not have [code]#aspect::fp64# and must return 0 for +does not have [api]#aspect::fp64# and must return 0 for [code]#info::device::native_vector_width_half# if the device does not have -[code]#aspect::fp16#. +[api]#aspect::fp16#. ''' @@ -2058,7 +2058,7 @@ _Remarks:_ Template parameter to [api]#device::get_info#. _Returns:_ The maximum number of simultaneous image objects that can be read from by a kernel. -The minimum value is 128 if the device has [code]#aspect::image#. +The minimum value is 128 if the device has [api]#aspect::image#. ''' @@ -2076,7 +2076,7 @@ _Remarks:_ Template parameter to [api]#device::get_info#. _Returns:_ The maximum number of simultaneous image objects that can be written to by a kernel. -The minimum value is 8 if the device has [code]#aspect::image#. +The minimum value is 8 if the device has [api]#aspect::image#. ''' @@ -2093,7 +2093,7 @@ struct image2d_max_width { _Remarks:_ Template parameter to [api]#device::get_info#. _Returns:_ The maximum width of a 2D image or 1D image in pixels. -The minimum value is 8192 if the device has [code]#aspect::image#. +The minimum value is 8192 if the device has [api]#aspect::image#. ''' @@ -2110,7 +2110,7 @@ struct image2d_max_height { _Remarks:_ Template parameter to [api]#device::get_info#. _Returns:_ The maximum height of a 2D image in pixels. -The minimum value is 8192 if the device has [code]#aspect::image#. +The minimum value is 8192 if the device has [api]#aspect::image#. ''' @@ -2127,7 +2127,7 @@ struct image3d_max_width { _Remarks:_ Template parameter to [api]#device::get_info#. _Returns:_ The maximum width of a 3D image in pixels. -The minimum value is 2048 if the device has [code]#aspect::image#. +The minimum value is 2048 if the device has [api]#aspect::image#. ''' @@ -2144,7 +2144,7 @@ struct image3d_max_height { _Remarks:_ Template parameter to [api]#device::get_info#. _Returns:_ The maximum height of a 3D image in pixels. -The minimum value is 2048 if the device has [code]#aspect::image#. +The minimum value is 2048 if the device has [api]#aspect::image#. ''' @@ -2161,7 +2161,7 @@ struct image3d_max_depth { _Remarks:_ Template parameter to [api]#device::get_info#. _Returns:_ The maximum depth of a 3D image in pixels. -The minimum value is 2048 if the device has [code]#aspect::image#. +The minimum value is 2048 if the device has [api]#aspect::image#. ''' @@ -2178,7 +2178,7 @@ struct image_max_buffer_size { _Remarks:_ Template parameter to [api]#device::get_info#. _Returns:_ The number of pixels for a 1D image created from a buffer object. -The minimum value is 65536 if the device has [code]#aspect::image#. +The minimum value is 65536 if the device has [api]#aspect::image#. Note that this information is intended for OpenCL interoperability only as this feature is not supported in SYCL. @@ -2197,7 +2197,7 @@ struct max_samplers { _Remarks:_ Template parameter to [api]#device::get_info#. _Returns:_ The maximum number of samplers that can be used in a kernel. -The minimum value is 16 if the device has [code]#aspect::image#. +The minimum value is 16 if the device has [api]#aspect::image#. ''' @@ -2255,23 +2255,17 @@ _Returns:_ A [code]#std::vector# of [code]#info::fp_config# values describing the half precision floating-point capability of this device. The [code]#std::vector# may contain zero or more of the following values: -* [code]#info::fp_config::denorm#: denorms are supported. -* [code]#info::fp_config::inf_nan#: INF and quiet NaNs are supported. -* [code]#info::fp_config::round_to_nearest#: round to nearest even rounding mode - is supported. -* [code]#info::fp_config::round_to_zero#: round to zero rounding mode is - supported. -* [code]#info::fp_config::round_to_inf#: round to positive and negative infinity - rounding modes are supported. -* [code]#info::fp_config::fma#: IEEE754-2008 fused multiply add is supported. -* [code]#info::fp_config::correctly_rounded_divide_sqrt#: divide and sqrt are - correctly rounded as defined by the IEEE754 specification. - This property is deprecated. -* [code]#info::fp_config::soft_float#: basic floating-point operations (such as - addition, subtraction, multiplication) are implemented in software. +* [api]#info::fp_config::denorm# +* [api]#info::fp_config::inf_nan# +* [api]#info::fp_config::round_to_nearest# +* [api]#info::fp_config::round_to_zero# +* [api]#info::fp_config::round_to_inf# +* [api]#info::fp_config::fma# +* [api]#info::fp_config::correctly_rounded_divide_sqrt# +* [api]#info::fp_config::soft_float# If half precision is supported by this device (i.e. the device has -[code]#aspect::fp16#) there is no minimum floating-point capability. +[api]#aspect::fp16#) there is no minimum floating-point capability. If half support is not supported the returned [code]#std::vector# must be empty. ''' @@ -2292,24 +2286,18 @@ _Returns:_ A [code]#std::vector# of [code]#info::fp_config# values describing the single precision floating-point capability of this device. The [code]#std::vector# must contain one or more of the following values: -* [code]#info::fp_config::denorm#: denorms are supported. -* [code]#info::fp_config::inf_nan#: INF and quiet NaNs are supported. -* [code]#info::fp_config::round_to_nearest#: round to nearest even rounding mode - is supported. -* [code]#info::fp_config::round_to_zero#: round to zero rounding mode is - supported. -* [code]#info::fp_config::round_to_inf#: round to positive and negative infinity - rounding modes are supported. -* [code]#info::fp_config::fma#: IEEE754-2008 fused multiply add is supported. -* [code]#info::fp_config::correctly_rounded_divide_sqrt#: divide and sqrt are - correctly rounded as defined by the IEEE754 specification. - This property is deprecated. -* [code]#info::fp_config::soft_float#: basic floating-point operations (such as - addition, subtraction, multiplication) are implemented in software. +* [api]#info::fp_config::denorm# +* [api]#info::fp_config::inf_nan# +* [api]#info::fp_config::round_to_nearest# +* [api]#info::fp_config::round_to_zero# +* [api]#info::fp_config::round_to_inf# +* [api]#info::fp_config::fma# +* [api]#info::fp_config::correctly_rounded_divide_sqrt# +* [api]#info::fp_config::soft_float# If this device is not of type [code]#info::device_type::custom# then the minimum -floating-point capability must be: [code]#info::fp_config::round_to_nearest# and -[code]#info::fp_config::inf_nan#. +floating-point capability must be: [api]#info::fp_config::round_to_nearest# and +[api]#info::fp_config::inf_nan#. ''' @@ -2329,25 +2317,20 @@ _Returns:_ A [code]#std::vector# of [code]#info::fp_config# values describing the double precision floating-point capability of this device. The [code]#std::vector# may contain zero or more of the following values: -* [code]#info::fp_config::denorm#: denorms are supported. -* [code]#info::fp_config::inf_nan#: INF and NaNs are supported. -* [code]#info::fp_config::round_to_nearest#: round to nearest even rounding mode - is supported. -* [code]#info::fp_config::round_to_zero#: round to zero rounding mode is - supported. -* [code]#info::fp_config::round_to_inf#: round to positive and negative infinity - rounding modes are supported. -* [code]#info::fp_config::fma#: IEEE754-2008 fused multiply-add is supported. -* [code]#info::fp_config::soft_float#: basic floating-point operations (such as - addition, subtraction, multiplication) are implemented in software. +* [api]#info::fp_config::denorm# +* [api]#info::fp_config::inf_nan# +* [api]#info::fp_config::round_to_nearest# +* [api]#info::fp_config::round_to_zero# +* [api]#info::fp_config::round_to_inf# +* [api]#info::fp_config::fma# +* [api]#info::fp_config::soft_float# If double precision is supported by this device (i.e. the device has -[code]#aspect::fp64#) and this device is not of type +[api]#aspect::fp64#) and this device is not of type [code]#info::device_type::custom# then the minimum floating-point capability -must be: [code]#info::fp_config::fma#, -[code]#info::fp_config::round_to_nearest#, -[code]#info::fp_config::round_to_zero#, [code]#info::fp_config::round_to_inf#, -[code]#info::fp_config::inf_nan# and [code]#info::fp_config::denorm#. +must be: [api]#info::fp_config::fma#, [api]#info::fp_config::round_to_nearest#, +[api]#info::fp_config::round_to_zero#, [api]#info::fp_config::round_to_inf#, +[api]#info::fp_config::inf_nan# and [api]#info::fp_config::denorm#. If double support is not supported the returned [code]#std::vector# must be empty. @@ -3015,7 +2998,7 @@ _Remarks:_ Template parameter to [api]#device::get_info#. _Returns:_ The maximum size of the internal buffer that holds the output of [code]#printf# calls from a kernel. -The minimum value is 1 MB if [code]#info::device::profile# returns true for this +The minimum value is 1 MB if [api]#info::device::profile# returns true for this device. ''' @@ -3083,7 +3066,7 @@ _Remarks:_ Template parameter to [api]#device::get_info#. _Returns:_ The maximum number of sub devices that can be created when this device is partitioned. The value returned cannot exceed the value returned by -[code]#info::device::max_compute_units#. +[api]#info::device::max_compute_units#. ''' @@ -3251,7 +3234,7 @@ software emulated FPGA, where the emulated FPGA has all the same features as the hardware one but runs more slowly and can provide additional profiling or diagnostic information. In such a case, an application's <> can use -[code]#aspect::emulated# to distinguish the two. +[api]#aspect::emulated# to distinguish the two. {endnote} -- @@ -3319,7 +3302,7 @@ functions defined in <>. Indicates that the device supports online linking of device code. Devices that have this aspect support the [code]#link# functions defined in <>. -All devices that have this aspect also have [code]#aspect::online_compiler#. +All devices that have this aspect also have [api]#aspect::online_compiler#. -- ''' @@ -3468,6 +3451,192 @@ However, if a device _D_ is not supported when the application is compiled, the application will not be able to submit kernels to that device _D_. {endnote} +[[sec:device-other-enumerations]] +==== Other enumerations + +[[sec:device-enum-device-type]] +===== Device type + +[source,role=synopsis] +---- +namespace sycl::info { +enum class device_type : /* unspecified */ { + cpu, // Maps to OpenCL CL_DEVICE_TYPE_CPU + gpu, // Maps to OpenCL CL_DEVICE_TYPE_GPU + accelerator, // Maps to OpenCL CL_DEVICE_TYPE_ACCELERATOR + custom, // Maps to OpenCL CL_DEVICE_TYPE_CUSTOM + automatic, // Maps to OpenCL CL_DEVICE_TYPE_DEFAULT + host, + all // Maps to OpenCL CL_DEVICE_TYPE_ALL +}; +} // namespace sycl::info +---- + +[[sec:device-enum-partition-property]] +===== Partition property + +[source,role=synopsis] +---- +namespace sycl::info { +enum class partition_property : /* unspecified */ { + no_partition, + partition_equally, + partition_by_counts, + partition_by_affinity_domain +}; +} // namespace sycl::info +---- + +[[sec:device-enum-partition-affinity-domain]] +===== Partition affinity domain + +[source,role=synopsis] +---- +namespace sycl::info { +enum class partition_affinity_domain : /* unspecified */ { + not_applicable, + numa, + L4_cache, + L3_cache, + L2_cache, + L1_cache, + next_partitionable +}; +} // namespace sycl::info +---- + +[[sec:device-enum-fp-config]] +===== Floating point configuration + +The [code]#info::fp_config# enumeration tells the behavior of floating point +operations on a device. + +[source,role=synopsis] +---- +namespace sycl::info { +enum class fp_config : /* unspecified */ { + denorm, + inf_nan, + round_to_nearest, + round_to_zero, + round_to_inf, + fma, + correctly_rounded_divide_sqrt, + soft_float +}; +} // namespace sycl::info +---- + +''' + +.[apidef]#info::fp_config::denorm# +[role=synopsis,id=api:info-fp-config-denorm] +-- +Denormalized numbers are supported. +-- + +''' + +.[apidef]#info::fp_config::inf_nan# +[role=synopsis,id=api:info-fp-config-inf-nan] +-- +INF and NaNs are supported. +-- + +''' + +.[apidef]#info::fp_config::round_to_nearest# +[role=synopsis,id=api:info-fp-config-round-to-nearest] +-- +Round to nearest even rounding mode is supported. +-- + +''' + +.[apidef]#info::fp_config::round_to_zero# +[role=synopsis,id=api:info-fp-config-round-to-zero] +-- +Round to zero rounding mode is supported. +-- + +''' + +.[apidef]#info::fp_config::round_to_inf# +[role=synopsis,id=api:info-fp-config-round-to-inf] +-- +Round to positive and negative infinity rounding modes are supported. +-- + +''' + +.[apidef]#info::fp_config::fma# +[role=synopsis,id=api:info-fp-config-fma] +-- +IEEE754-2008 fused multiply-add is supported. +-- + +''' + +.[apidef]#info::fp_config::correctly_rounded_divide_sqrt# +[role=synopsis,id=api:info-fp-config-correctly-rounded-divide-sqrt] +-- +Deprecated by SYCL 2020. + +Divide and sqrt are correctly rounded as defined by the IEEE754 specification. +-- + +''' + +.[apidef]#info::fp_config::soft_float# +[role=synopsis,id=api:info-fp-config-soft-float] +-- +Basic floating-point operations (such as addition, subtraction, multiplication) +are implemented in software. +-- + +''' + +[[sec:device-enum-local-mem-type]] +===== Local memory type + +[source,role=synopsis] +---- +namespace sycl::info { +enum class local_mem_type : /* unspecified */ { + none, + local, + global +}; +} // namespace sycl::info +---- + +[[sec:device-enum-global-mem-cache-type]] +===== Global memory cache type + +[source,role=synopsis] +---- +namespace sycl::info { +enum class global_mem_cache_type : /* unspecified */ { + none, + read_only, + read_write +}; +} // namespace sycl::info +---- + +[[sec:device-enum-execution-capability]] +===== Execution capability + +[source,role=synopsis] +---- +namespace sycl::info { +enum class execution_capability : /* unspecified */ { + exec_kernel, + exec_native_kernel +}; +} // namespace sycl::info +---- + [[sec:interface.queue.class]] === Queue class