diff --git a/adoc/chapters/information_descriptors.adoc b/adoc/chapters/information_descriptors.adoc
index 46d16e7f..32e281e9 100644
--- a/adoc/chapters/information_descriptors.adoc
+++ b/adoc/chapters/information_descriptors.adoc
@@ -33,7 +33,7 @@ include::{header_dir}/contextInfo.h[lines=4..-1]
== Device information descriptors
The following interface includes all the information descriptors for the
-[code]#device# class as described in <
>.
+[code]#device# class.
[source,,linenums]
----
include::{header_dir}/deviceInfo.h[lines=4..-1]
diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc
index 4fbbc12c..327b56e5 100644
--- a/adoc/chapters/programming_interface.adoc
+++ b/adoc/chapters/programming_interface.adoc
@@ -1454,14 +1454,12 @@ info::context::atomic_fence_scope_capabilities
The [code]#property_list# constructor parameters are present for extensibility.
-// \input{device_class}
-// %%%%%%%%%%%%%%%%%%%%%%%%%%%% begin device_class %%%%%%%%%%%%%%%%%%%%%%%%%%%%
[[sec:device-class]]
=== Device class
-The SYCL [code]#device# class encapsulates a single SYCL device on which
-<> can be executed.
+The [code]#device# class represents a single SYCL device on which <> can be executed.
All member functions of the [code]#device# class are synchronous and errors are
handled by throwing synchronous SYCL exceptions.
@@ -1469,1375 +1467,1956 @@ handled by throwing synchronous SYCL exceptions.
The execution environment for a SYCL application has a fixed number of
<> which does not vary as the application executes.
The application can get a list of all these devices via
-[code]#device::get_devices()#, and the order of the device objects is the same
-each time the application calls that function (assuming the parameter to that
+[api]#device::get_devices#, and the order of the device objects is the same each
+time the application calls that function (assuming the parameter to that
function is the same for each call).
The [code]#device# class also provides constructors, but constructing a new
[code]#device# instance merely creates a new object that is a copy of one of the
-objects returned by [code]#device::get_devices()#.
+objects returned by [api]#device::get_devices#.
-A SYCL [code]#device# can be partitioned into multiple SYCL devices, by calling
-the [code]#create_sub_devices()# member function template.
-The resulting SYCL [code]#devices# are considered sub devices, and it is valid
+A device can be partitioned into multiple devices, by calling the
+[code]#device::create_sub_devices# member function template.
+The resulting [code]#device# objects are considered sub devices, and it is valid
to partition these sub devices further.
The range of support for this feature is <> and device specific and can
-be queried for through [code]#get_info()#.
+be queried for through [api]#device::get_info#.
-The SYCL [code]#device# class provides the common reference semantics (see
-<>).
-
-==== Device interface
-
-A synopsis of the SYCL [code]#device# class is provided below.
-The constructors, member functions and static member functions of the SYCL
-[code]#device# class are listed in <>,
-<> and <> respectively.
-The additional common special member functions and common member functions are
-listed in <> in
-<> and
-<>, respectively.
+The [code]#device# class provides the common reference semantics as defined in
+<>.
-// Interface of the device class
-[source,,linenums]
+[source,role=synopsis]
----
include::{header_dir}/device.h[lines=4..-1]
----
+[[sec:device-ctors]]
+==== Constructors
-[[table.constructors.device]]
-.Constructors of the SYCL [code]#device# class
-[width="100%",options="header",separator="@",cols="65%,35%"]
-|====
-@ Constructor @ Description
-a@
-[source]
+.[apititle]#Default constructor#
+[source,role=synopsis,id=api:device-ctor]
----
device()
----
- a@ Constructs a SYCL [code]#device# instance that is a copy of the device
- returned by [code]#default_selector_v#.
-a@
-[source]
+_Effects:_ Constructs a [code]#device# object that is a copy of the device
+returned by [code]#default_selector_v#.
+
+'''
+
+.[apititle]#Selector constructor#
+[source,role=synopsis,id=api:device-ctor-selector]
----
-template explicit device(const DeviceSelector&)
+template
+explicit device(const DeviceSelector& selector)
----
- a@ Constructs a SYCL [code]#device# instance that is a copy of the device
- returned by the <> parameter.
-|====
+_Constraints:_ Available only when the [code]#DeviceSelector# is a type that
+satisfies the requirements of a <> as defined in
+<>.
+_Effects:_ The [code]#selector# is called for every <> as described
+in <>.
+Constructs a [code]#device# object that is a copy of the device selected by
+[code]#selector#.
+'''
-[[table.members.device]]
-.Member functions of the SYCL [code]#device# class
-[width="100%",options="header",separator="@",cols="58%,42%"]
-|====
-@ Member function @ Description
-a@
-[source]
+[[sec:device-member-funcs]]
+==== Member functions
+
+.[apidef]#device::get_backend#
+[source,role=synopsis,id=api:device-get-backend]
----
backend get_backend() const noexcept
----
- a@ Returns a [code]#backend# identifying the <> associated
- with this [code]#device#.
-a@
-[source]
+_Returns:_ The <> that is associated with this device.
+
+'''
+
+.[apidef]#device::get_platform#
+[source,role=synopsis,id=api:device-get-platform]
----
platform get_platform() const
----
- a@ Returns the associated SYCL [code]#platform#.
- The value returned must be equal to that returned by [code]#get_info()#.
-a@
-[source]
+_Returns:_ The <> that is associated with this device.
+
+'''
+
+.[apidef]#device::is_cpu#
+[source,role=synopsis,id=api:device-is-cpu]
----
bool is_cpu() const
----
- a@ Returns the same value as [code]#has(aspect::cpu)#. See <>.
-a@
-[source]
+_Returns:_ The same value as [code]#has(aspect::cpu)#.
+See <>.
+
+'''
+
+.[apidef]#device::is_gpu#
+[source,role=synopsis,id=api:device-is-gpu]
----
bool is_gpu() const
----
- a@ Returns the same value as [code]#has(aspect::gpu)#. See <>.
-a@
-[source]
+_Returns:_ The same value as [code]#has(aspect::gpu)#.
+See <>.
+
+'''
+
+.[apidef]#device::is_accelerator#
+[source,role=synopsis,id=api:device-is-accelerator]
----
bool is_accelerator() const
----
- a@ Returns the same value as [code]#has(aspect::accelerator)#. See <>.
-a@
-[source]
+_Returns:_ The same value as [code]#has(aspect::accelerator)#.
+See <>.
+
+'''
+
+.[apidef]#device::get_info#
+[source,role=synopsis,id=api:device-get-info]
----
-template typename Param::return_type get_info() const
+template
+typename Param::return_type get_info() const
----
- a@ Queries this SYCL [code]#device# for information requested by the
- template parameter [code]#Param#.
- The type alias [code]#Param::return_type# must be defined in
- accordance with the info parameters in <> to
- facilitate returning the type associated with the [code]#Param#
- parameter.
-a@
-[source]
+_Constraints:_ Available only when [code]#Param# is an information descriptor
+for the device class.
+
+Each information descriptor specifies the return value and may also specify
+preconditions, exceptions that are thrown, etc.
+See <> for the device information descriptors that
+are defined by the <>.
+
+'''
+
+.[apidef]#device::get_backend_info#
+[source,role=synopsis,id=api:device-get-backend-info]
----
-template typename Param::return_type get_backend_info() const
+template
+typename Param::return_type get_backend_info() const
----
- a@ Queries this SYCL [code]#device# for <>-specific information
- requested by the template parameter [code]#Param#.
- The type alias [code]#Param::return_type# must be defined in
- accordance with the <> specification.
- Must throw an [code]#exception# with the [code]#errc::backend_mismatch#
- error code if the <> that corresponds with [code]#Param# is different
- from the <> that is associated with this [code]#device#.
-a@
-[source]
+_Constraints:_ Available only when [code]#Param# is a backend information
+descriptor for the device class.
+
+_Throws:_ An [code]#exception# with the [code]#errc::backend_mismatch# error
+code if the backend that corresponds with [code]#Param# is different from the
+backend that is associated with this device.
+
+Each information descriptor specifies the return value and may also specify
+preconditions, additional exceptions that are thrown, etc.
+
+'''
+
+.[apidef]#device::has#
+[source,role=synopsis,id=api:device-has]
----
bool has(aspect asp) const
----
- a@ Returns true if this SYCL [code]#device# has the given <>.
- SYCL applications can use this member function to determine which
- optional features this device supports (if any).
-a@
-[source]
+_Returns:_ The value [code]#true# if this device has the given <>.
+Applications can use this member function to determine which optional features
+this device supports (if any).
+
+'''
+
+.[apidef]#device::has_extension#
+[source,role=synopsis,id=api:device-has-extension]
----
bool has_extension(const std::string& extension) const
----
- a@ Deprecated, use [code]#has()# instead.
-Returns true if this SYCL [code]#device# supports the extension queried by the [code]#extension# parameter.
+Deprecated by SYCL 2020.
-a@
-[source]
+{note}Use [api]#device::has# instead.
+{endnote}
+
+_Returns:_ The value [code]#true# if this device supports the extension queried
+by the [code]#extension# parameter.
+
+'''
+
+.[apititle]#device::create_sub_devices (partition equally)#
+[source,role=synopsis,id=api:device-create-sub-devices-partition-equally]
----
template
std::vector create_sub_devices(size_t count) const
----
- a@ Available only when [code]#Prop# is
- [code]#info::partition_property::partition_equally#. Returns a
- [code]#std::vector# of sub devices partitioned from this SYCL
- [code]#device# based on the [code]#count# parameter. 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#, then the remaining compute units are
- not included in any of the sub devices.
-If this SYCL [code]#device# does not support
-[code]#info::partition_property::partition_equally# an [code]#exception# with
-the [code]#errc::feature_not_supported# error code must be thrown. If
-[code]#count# exceeds the total number of compute units in the device, an
-[code]#exception# with the [code]#errc::invalid# error code must be thrown.
+_Constraints:_ Available only when [code]#Prop# is
+[api]#info::partition_property::partition_equally#.
-a@
-[source]
+_Returns:_ A [code]#std::vector# of sub devices partitioned from this
+[code]#device# object based on the [code]#count# parameter.
+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
+[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:_
+
+* An [code]#exception# with the [code]#errc::feature_not_supported# error code
+ if this device does not support
+ [api]#info::partition_property::partition_equally#.
+
+* An [code]#exception# with the [code]#errc::invalid# error code if
+ [code]#count# exceeds the total number of compute units in the device.
+
+'''
+
+.[apititle]#device::create_sub_devices (partition by counts)#
+[source,role=synopsis,id=api:device-create-sub-devices-partition-by-counts]
----
template
std::vector create_sub_devices(const std::vector& counts) const
----
- a@ Available only when [code]#Prop# is
- [code]#info::partition_property::partition_by_counts#. Returns a
- [code]#std::vector# of sub devices partitioned from this SYCL
- [code]#device# based on the [code]#counts# parameter. For each non-zero
- value _M_ in the [code]#counts# vector, a sub device with _M_ compute
- units is created.
-If the SYCL [code]#device# does not support
-[code]#info::partition_property::partition_by_counts# an [code]#exception# with
-the [code]#errc::feature_not_supported# error code must be thrown. 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#), an
-[code]#exception# with the [code]#errc::invalid# error code must be thrown.
+_Constraints:_ Available only when [code]#Prop# is
+[api]#info::partition_property::partition_by_counts#.
-a@
-[source]
+_Returns:_ A [code]#std::vector# of sub devices partitioned from this
+[code]#device# object based on the [code]#counts# parameter.
+For each non-zero value _M_ in the [code]#counts# vector, a sub device with _M_
+compute units is created.
+
+_Throws:_
+
+* An [code]#exception# with the [code]#errc::feature_not_supported# error code
+ if this device does not support
+ [api]#info::partition_property::partition_by_counts#.
+
+* 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 [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#).
+
+'''
+
+.[apititle]#device::create_sub_devices (partition by affinity domain)#
+[source,role=synopsis,id=api:device-create-sub-devices-partition-by-affinity-domain]
----
template
std::vector
create_sub_devices(info::partition_affinity_domain domain) const
----
-// WARNING: The Asciidoctor PDF renderer seems to be unable to generate a table
-// where any single row is taller than a page. This row is already close to
-// the page limit. If you add any more text in this cell, check the PDF render
-// to see if any of the text is cut off at the bottom of the page. If so, try
-// making this column wider so that this row still fits on a page.
- a@ Available only when [code]#Prop# is
- [code]#info::partition_property::partition_by_affinity_domain#. Returns
- a [code]#std::vector# of sub devices partitioned from this SYCL
- [code]#device# by affinity domain based on the [code]#domain# parameter,
- which must be one of the following values:
+_Constraints:_ Available only when [code]#Prop# is
+[api]#info::partition_property::partition_by_affinity_domain#.
-* [code]#info::partition_affinity_domain::numa#: Split the device into
- sub devices comprised of compute units that share a NUMA node.
+_Returns:_ A [code]#std::vector# of sub devices partitioned from this
+[code]#device# object based on the [code]#domain# parameter, which must be one
+of the following values:
-* [code]#info::partition_affinity_domain::L4_cache#: Split the device into
- sub devices comprised of compute units that share a level 4 data cache.
+* [api]#info::partition_affinity_domain::numa#: Split the device into sub
+ devices comprised of compute units that share a NUMA node.
-* [code]#info::partition_affinity_domain::L3_cache#: Split the device into
- sub devices comprised of compute units that share a level 3 data cache.
+* [api]#info::partition_affinity_domain::L4_cache#: Split the device into sub
+ devices comprised of compute units that share a level 4 data cache.
-* [code]#info::partition_affinity_domain::L2_cache#: Split the device into
- sub devices comprised of compute units that share a level 2 data cache.
+* [api]#info::partition_affinity_domain::L3_cache#: Split the device into sub
+ devices comprised of compute units that share a level 3 data cache.
-* [code]#info::partition_affinity_domain::L1_cache#: Split the device into
- sub devices comprised of compute units that share a level 1 data cache.
+* [api]#info::partition_affinity_domain::L2_cache#: Split the device into sub
+ devices comprised of compute units that share a level 2 data cache.
-* [code]#info::partition_affinity_domain::next_partitionable#: Split the device
- along the next partitionable affinity domain. The implementation shall find
- the first level along which the device or sub device may be further
- subdivided in the order [code]#numa#, [code]#L4_cache#, [code]#L3_cache#,
- [code]#L2_cache#, [code]#L1_cache#, and partition the device 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::partition_affinity_domain::L1_cache#: Split the device into sub
+ devices comprised of compute units that share a level 1 data cache.
-If the SYCL [code]#device# does not support
-[code]#info::partition_property::partition_by_affinity_domain# or the
-SYCL [code]#device# does not support the
-[code]#info::partition_affinity_domain# provided, an [code]#exception#
-with the [code]#errc::feature_not_supported# error code must be thrown.
+* [api]#info::partition_affinity_domain::next_partitionable#: Split the device
+ along the next partitionable affinity domain.
+ The implementation shall find the first level along which the device or sub
+ device may be further subdivided in the order [code]#numa#, [code]#L4_cache#,
+ [code]#L3_cache#, [code]#L2_cache#, [code]#L1_cache#, and partition the device
+ into sub devices comprised of compute units that share memory subsystems at
+ this level.
+ The user may determine what happened via
+ [api]#info::device::partition_type_affinity_domain#.
-|====
+_Throws:_
+* An [code]#exception# with the [code]#errc::feature_not_supported# error code
+ if this device does not support
+ [api]#info::partition_property::partition_by_affinity_domain# or if this
+ device does not support the [api]#info::partition_affinity_domain# provided.
+'''
-[[table.staticmembers.device]]
-.Static member functions of the SYCL [code]#device# class
-[width="100%",options="header",separator="@",cols="65%,35%"]
-|====
-@ Static member function @ Description
-a@
-[source]
+[[sec:device-static-member-funcs]]
+==== Static member functions
+
+.[apidef]#device::get_devices#
+[source,role=synopsis,id=api:device-get-devices]
----
static std::vector
get_devices(info::device_type type = info::device_type::all)
----
- a@ Returns a [code]#std::vector# containing all the
- <> from all <>
- available in the system which have the device type encapsulated by
- [code]#type#.
-
-|====
+_Returns:_ A [code]#std::vector# containing all the <> from all <> available in the system which have
+the device type [code]#type#.
+'''
-==== Device information descriptors
+[[sec:device-info-descriptors]]
+==== Information descriptors
-A <> can be queried for information using the [code]#get_info# member
-function of the [code]#device# class, specifying one of the info parameters in
-[code]#info::device#.
-The possible values for each info parameter and any restriction are defined in
-the specification of the <> associated with the <>.
-All info parameters in [code]#info::device# are specified in
-<> and the synopsis for [code]#info::device# is described in
-<>.
+This section describes the information descriptors that can be used as the
+[code]#Param# template parameter to [api]#device::get_info#.
+When the description has a _Returns_, _Throws_, etc. paragraph, this indicates
+the value returned by or the exceptions thrown by the [api]#device::get_info#
+function.
+'''
-[[table.device.info]]
-.Device information descriptors
-// Jon: Dims{5cm}{2.5cm}{6.5cm}
-[width="100%",options="header",separator="@",cols="37%,19%,44%"]
-|====
-@ Device descriptors @ Return type @ Description
-a@
-[source]
+.[apidef]#info::device::device_type#
+[source,role=synopsis,id=api:info-device-device-type]
----
-info::device::device_type
+namespace sycl::info::device {
+struct device_type {
+ using return_type = info::device_type;
+};
+} // namespace sycl::info::device
----
- @ [.code]#info::device_type#
- a@ Returns the device type associated with the <>. May not return
- [code]#info::device_type::all#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::vendor_id
-----
+_Returns:_ The device type associated with the device.
+May not return [api]#info::device_type::all#.
- @ [.code]#uint32_t#
- a@ Returns a unique vendor device identifier.
+'''
-a@
-[source]
+.[apidef]#info::device::vendor_id#
+[source,role=synopsis,id=api:info-device-vendor-id]
----
-info::device::max_compute_units
+namespace sycl::info::device {
+struct vendor_id {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#uint32_t#
- a@ Returns the number of parallel compute units available to the
- <>. The minimum value is 1.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::max_work_item_dimensions
-----
+_Returns:_ A unique vendor device identifier.
- @ [.code]#uint32_t#
- a@ Returns the maximum dimensions that specify the global and local work-item IDs used by the data parallel execution model.
- The minimum value is 3 if this SYCL [code]#device# is not of device type [code]#info::device_type::custom#.
+'''
-a@
-[source]
+.[apidef]#info::device::max_compute_units#
+[source,role=synopsis,id=api:info-device-max-compute-units]
----
-info::device::max_work_item_sizes\<1>
+namespace sycl::info::device {
+struct max_compute_units {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#range<1>#
- a@ Returns the maximum number of work-items that are permitted in a
- work-group for a kernel running in a one-dimensional index space. The
- minimum value is latexmath:[(1)] for [code]#devices# that are not of
- device type [code]#info::device_type::custom#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::max_work_item_sizes\<2>
-----
+_Returns:_ The number of parallel compute units available to the device.
+The minimum value is 1.
- @ [.code]#range<2>#
- a@ Returns the maximum number of work-items that are permitted in each
- dimension of a work-group for a kernel running in a two-dimensional index
- space. The minimum value is latexmath:[(1,1)] for [code]#devices# that
- are not of device type [code]#info::device_type::custom#.
+'''
-a@
-[source]
+.[apidef]#info::device::max_work_item_dimensions#
+[source,role=synopsis,id=api:info-device-max-work-item-dimensions]
----
-info::device::max_work_item_sizes\<3>
+namespace sycl::info::device {
+struct max_work_item_dimensions {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#range<3>#
- a@ Returns the maximum number of work-items that are permitted in each
- dimension of a work-group for a kernel running in a three-dimensional
- index space. The minimum value is latexmath:[(1,1,1)] for [code]#devices#
- that are not of device type [code]#info::device_type::custom#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::max_work_group_size
-----
+_Returns:_ The maximum dimensions that specify the global and local work-item
+IDs used by the data parallel execution model.
+The minimum value is 3 if this device is not of device type
+[api]#info::device_type::custom#.
- @ [.code]#size_t#
- a@ Returns the maximum number of work-items that this device is capable of
- executing in a work-group.
- The minimum value is 1.
- This value is an upper limit and will not necessarily maximize
- performance.
- The maximum number of work-items in a work-group depends on the kernel and
- the implementation.
- Use [code]#info::kernel_device_specific::work_group_size# to query this
- limit.
+'''
-a@
-[source]
+.[apidef]#info::device::max_work_item_sizes#
+[source,role=synopsis,id=api:info-device-max-work-item-sizes]
----
-info::device::max_num_sub_groups
+namespace sycl::info::device {
+template
+struct max_work_item_sizes {
+ using return_type = range;
+};
+} // namespace sycl::info::device
----
- @ [.code]#uint32_t#
- a@ Returns the maximum number of sub-groups in a work-group for any kernel executed on the device. The minimum value is 1.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::sub_group_sizes
-----
+_Constraints_: Available only when [code]#Dimensions# is 1, 2, or 3.
- @ [.code]#std::vector#
- a@ Returns a [code]#std::vector# of [code]#size_t# containing the set of sub-group sizes supported by the device.
+_Returns:_ The maximum number of work-items that are permitted in a work-group
+for a kernel running in an index space of [code]#Dimensions# dimensions.
+When the device type is not [api]#info::device_type::custom#, the minimum value
+returned from this query is: (1) when [code]#Dimensions# is 1, (1, 1) when
+[code]#Dimensions# is 2, and (1, 1, 1) when [code]#Dimensions# is 3.
-a@
-[source]
+'''
+
+.[apidef]#info::device::max_work_group_size#
+[source,role=synopsis,id=api:info-device-max-work-group-size]
----
-info::device::preferred_vector_width_char
-info::device::preferred_vector_width_short
-info::device::preferred_vector_width_int
-info::device::preferred_vector_width_long
-info::device::preferred_vector_width_float
-info::device::preferred_vector_width_double
-info::device::preferred_vector_width_half
+namespace sycl::info::device {
+struct max_work_group_size {
+ using return_type = size_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#uint32_t#
- a@ Returns the preferred native vector width size for built-in scalar types that 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 [code]#device# does not have [code]#aspect::fp64# and must return 0 for [code]#info::device::preferred_vector_width_half# if the [code]#device# does not have [code]#aspect::fp16#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::native_vector_width_char
-info::device::native_vector_width_short
-info::device::native_vector_width_int
-info::device::native_vector_width_long
-info::device::native_vector_width_float
-info::device::native_vector_width_double
-info::device::native_vector_width_half
-----
+_Returns:_ The maximum number of work-items that this device is capable of
+executing in a work-group.
+The minimum value is 1.
+This value is an upper limit and will not necessarily maximize performance.
+The maximum number of work-items in a work-group depends on the kernel and the
+implementation.
+Use [code]#info::kernel_device_specific::work_group_size# to query this limit.
- @ [.code]#uint32_t#
- a@ 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 [code]#device# does not have [code]#aspect::fp64# and must return 0 for [code]#info::device::native_vector_width_half# if the [code]#device# does not have [code]#aspect::fp16#.
+'''
-a@
-[source]
+.[apidef]#info::device::max_num_sub_groups#
+[source,role=synopsis,id=api:info-device-max-num-sub-groups]
----
-info::device::max_clock_frequency
+namespace sycl::info::device {
+struct max_num_sub_groups {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#uint32_t#
- a@ Returns the maximum configured clock frequency of this SYCL [code]#device# in MHz.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::address_bits
-----
+_Returns:_ The maximum number of sub-groups in a work-group for any kernel
+executed on the device.
+The minimum value is 1.
- @ [.code]#uint32_t#
- a@ Returns the default compute device address space size specified as an unsigned integer value in bits. Must return either 32 or 64.
+'''
-a@
-[source]
+.[apidef]#info::device::sub_group_sizes#
+[source,role=synopsis,id=api:info-device-sub-group-sizes]
----
-info::device::max_mem_alloc_size
+namespace sycl::info::device {
+struct sub_group_sizes {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
----
- @ [.code]#uint64_t#
- a@ Returns the maximum size of memory object allocation in bytes. The minimum value is max (1/4th of [code]#info::device::global_mem_size#,128*1024*1024) if this SYCL [code]#device# is not of device type [code]#info::device_type::custom#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
+_Returns:_ A [code]#std::vector# of [code]#size_t# containing the set of
+sub-group sizes supported by the device.
+
+'''
+
+.[apititle]#info::device::preferred_vector_width#
+[source,role=synopsis,id=api:info-device-preferred-vector-width]
----
-info::device::image_support
+namespace sycl::info::device {
+struct preferred_vector_width_char {
+ using return_type = uint32_t;
+};
+struct preferred_vector_width_short {
+ using return_type = uint32_t;
+};
+struct preferred_vector_width_int {
+ using return_type = uint32_t;
+};
+struct preferred_vector_width_long {
+ using return_type = uint32_t;
+};
+struct preferred_vector_width_float {
+ using return_type = uint32_t;
+};
+struct preferred_vector_width_double {
+ using return_type = uint32_t;
+};
+struct preferred_vector_width_half {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#bool#
- a@ Deprecated.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-Returns the same value as [code]#device::has(aspect::image)#.
+_Returns:_ The preferred native vector width size for built-in scalar types that
+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 [api]#aspect::fp64# and must return 0 for
+[code]#info::device::preferred_vector_width_half# if the device does not have
+[api]#aspect::fp16#.
-a@
-[source]
+'''
+
+.[apititle]#info::device::native_vector_width#
+[source,role=synopsis,id=api:info-device-native-vector-width]
----
-info::device::max_read_image_args
+namespace sycl::info::device {
+struct native_vector_width_char {
+ using return_type = uint32_t;
+};
+struct native_vector_width_short {
+ using return_type = uint32_t;
+};
+struct native_vector_width_int {
+ using return_type = uint32_t;
+};
+struct native_vector_width_long {
+ using return_type = uint32_t;
+};
+struct native_vector_width_float {
+ using return_type = uint32_t;
+};
+struct native_vector_width_double {
+ using return_type = uint32_t;
+};
+struct native_vector_width_half {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#uint32_t#
- a@ Returns the maximum number of simultaneous image objects that can be read from by a kernel. The minimum value is 128 if the SYCL [code]#device# has [code]#aspect::image#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::max_write_image_args
-----
+_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 [api]#aspect::fp64# and must return 0 for
+[code]#info::device::native_vector_width_half# if the device does not have
+[api]#aspect::fp16#.
- @ [.code]#uint32_t#
- a@ Returns the maximum number of simultaneous image objects that can be written to by a kernel. The minimum value is 8 if the SYCL [code]#device# has [code]#aspect::image#.
+'''
-a@
-[source]
+.[apidef]#info::device::max_clock_frequency#
+[source,role=synopsis,id=api:info-device-max-clock-frequency]
----
-info::device::image2d_max_width
+namespace sycl::info::device {
+struct max_clock_frequency {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#size_t#
- a@ Returns the maximum width of a 2D image or 1D image in pixels. The minimum value is 8192 if the SYCL [code]#device# has [code]#aspect::image#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::image2d_max_height
-----
+_Returns:_ The maximum configured clock frequency of this device in MHz.
- @ [.code]#size_t#
- a@ Returns the maximum height of a 2D image in pixels. The minimum value is 8192 if the SYCL [code]#device# has [code]#aspect::image#.
+'''
-a@
-[source]
+.[apidef]#info::device::address_bits#
+[source,role=synopsis,id=api:info-device-address-bits]
----
-info::device::image3d_max_width
+namespace sycl::info::device {
+struct address_bits {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#size_t#
- a@ Returns the maximum width of a 3D image in pixels. The minimum value is 2048 if the SYCL [code]#device# has [code]#aspect::image#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::image3d_max_height
-----
+_Returns:_ The default compute device address space size in bits.
+Must return either 32 or 64.
- @ [.code]#size_t#
- a@ Returns the maximum height of a 3D image in pixels. The minimum value is 2048 if the SYCL [code]#device# has [code]#aspect::image#.
+'''
-a@
-[source]
+.[apidef]#info::device::max_mem_alloc_size#
+[source,role=synopsis,id=api:info-device-max-mem-alloc-size]
----
-info::device::image3d_max_depth
+namespace sycl::info::device {
+struct max_mem_alloc_size {
+ using return_type = uint64_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#size_t#
- a@ Returns the maximum depth of a 3D image in pixels. The minimum value is 2048 if the SYCL [code]#device# has [code]#aspect::image#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::image_max_buffer_size
-----
+_Returns:_ The maximum size of memory object allocation in bytes.
+The minimum value is max (1/4th of
+[code]#info::device::global_mem_size#,128*1024*1024) if this device is not of
+device type [api]#info::device_type::custom#.
- @ [.code]#size_t#
- a@ Returns the number of pixels for a 1D image created from a buffer object. The minimum value is 65536 if the SYCL [code]#device# has [code]#aspect::image#. Note that this information is intended for OpenCL interoperability only as this feature is not supported in SYCL.
+'''
-a@
-[source]
+.[apidef]#info::device::image_support#
+[source,role=synopsis,id=api:info-device-image-support]
----
-info::device::max_samplers
+namespace sycl::info::device {
+struct image_support {
+ using return_type = bool;
+};
+} // namespace sycl::info::device
----
- @ [.code]#uint32_t#
- a@ Returns the maximum number of samplers that can be used in a kernel. The minimum value is 16 if the SYCL [code]#device# has [code]#aspect::image#.
+Deprecated by SYCL 2020.
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::max_parameter_size
-----
+_Returns:_ The same value as [code]#device::has(aspect::image)#.
- @ [.code]#size_t#
- a@ Returns the maximum size in bytes of the arguments that can be passed to a kernel. The minimum value is 1024 if this SYCL [code]#device# is not of device type [code]#info::device_type::custom#. For this minimum value, only a maximum of 128 arguments can be passed to a kernel.
+'''
-a@
-[source]
+.[apidef]#info::device::max_read_image_args#
+[source,role=synopsis,id=api:info-device-max-read-image-args]
----
-info::device::mem_base_addr_align
+namespace sycl::info::device {
+struct max_read_image_args {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#uint32_t#
- a@ Returns the minimum value in bits of the largest supported SYCL built-in
- data type if this SYCL [code]#device# is not of device type [code]#info::device_type::custom#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::half_fp_config
-----
+_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 [api]#aspect::image#.
- @ [.code]#std::vector#
- a@ Returns a [code]#std::vector# of [code]#info::fp_config#
- describing the half precision floating-point capability of this SYCL
- [code]#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.
-
-If half precision is supported by this SYCL [code]#device# (i.e. the
-[code]#device# has [code]#aspect::fp16#) there is no minimum floating-point
-capability.
-If half support is not supported the returned [code]#std::vector# must be empty.
---
+'''
-a@
-[source]
+.[apidef]#info::device::max_write_image_args#
+[source,role=synopsis,id=api:info-device-max-write-image-args]
----
-info::device::single_fp_config
+namespace sycl::info::device {
+struct max_write_image_args {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#std::vector#
- a@ Returns a [code]#std::vector# of [code]#info::fp_config#
- describing the single precision floating-point capability of this
- SYCL [code]#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.
-
-If this SYCL [code]#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#.
---
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::double_fp_config
-----
+_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 [api]#aspect::image#.
- @ [.code]#std::vector#
- a@ Returns a [code]#std::vector# of [code]#info::fp_config#
- describing the double precision floating-point capability of this
- SYCL [code]#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.
-
-If double precision is supported by this SYCL [code]#device# (i.e. the
-[code]#device# has [code]#aspect::fp64# and this SYCL [code]#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#.
-If double support is not supported the returned [code]#std::vector# must be
-empty.
---
+'''
-a@
-[source]
+.[apidef]#info::device::image2d_max_width#
+[source,role=synopsis,id=api:info-device-image2d-max-width]
----
-info::device::global_mem_cache_type
+namespace sycl::info::device {
+struct image2d_max_width {
+ using return_type = size_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#info::global_mem_cache_type#
- a@ Returns the type of global memory cache supported.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::global_mem_cache_line_size
-----
+_Returns:_ The maximum width of a 2D image or 1D image in pixels.
+The minimum value is 8192 if the device has [api]#aspect::image#.
- @ [.code]#uint32_t#
- a@ Returns the size of global memory cache line in bytes.
+'''
-a@
-[source]
+.[apidef]#info::device::image2d_max_height#
+[source,role=synopsis,id=api:info-device-image2d-max-height]
----
-info::device::global_mem_cache_size
+namespace sycl::info::device {
+struct image2d_max_height {
+ using return_type = size_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#uint64_t#
- a@ Returns the size of global memory cache in bytes.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::global_mem_size
-----
+_Returns:_ The maximum height of a 2D image in pixels.
+The minimum value is 8192 if the device has [api]#aspect::image#.
- @ [.code]#uint64_t#
- a@ Returns the size of global device memory in bytes.
+'''
-a@
-[source]
+.[apidef]#info::device::image3d_max_width#
+[source,role=synopsis,id=api:info-device-image3d-max-width]
----
-info::device::max_constant_buffer_size
+namespace sycl::info::device {
+struct image3d_max_width {
+ using return_type = size_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#uint64_t#
- a@ Deprecated in SYCL 2020. Returns the maximum size in bytes of a constant buffer allocation. The minimum value is 64 KB if this SYCL [code]#device# is not of type [code]#info::device_type::custom#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::max_constant_args
-----
+_Returns:_ The maximum width of a 3D image in pixels.
+The minimum value is 2048 if the device has [api]#aspect::image#.
- @ [.code]#uint32_t#
- a@ Deprecated in SYCL 2020. Returns the maximum number of constant arguments that can be declared in a kernel. The minimum value is 8 if this SYCL [code]#device# is not of type [code]#info::device_type::custom#.
+'''
-a@
-[source]
+.[apidef]#info::device::image3d_max_height#
+[source,role=synopsis,id=api:info-device-image3d-max-height]
----
-info::device::local_mem_type
+namespace sycl::info::device {
+struct image3d_max_height {
+ using return_type = size_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#info::local_mem_type#
- a@ Returns the type of local memory supported. This can
- be [code]#info::local_mem_type::local# implying dedicated
- local memory storage such as SRAM, or [code]#info::local_mem_type::global#.
- If this SYCL [code]#device# is of type [code]#info::device_type::custom# this can also be [code]#info::local_mem_type::none#, indicating local memory is not supported.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::local_mem_size
-----
+_Returns:_ The maximum height of a 3D image in pixels.
+The minimum value is 2048 if the device has [api]#aspect::image#.
- @ [.code]#uint64_t#
- a@ Returns the size of local memory arena in bytes. The minimum value is 32 KB if this SYCL [code]#device# is not of type [code]#info::device_type::custom#.
+'''
-a@
-[source]
+.[apidef]#info::device::image3d_max_depth#
+[source,role=synopsis,id=api:info-device-image3d-max-depth]
----
-info::device::error_correction_support
+namespace sycl::info::device {
+struct image3d_max_depth {
+ using return_type = size_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#bool#
- a@ Returns true if the device implements error correction for all accesses to
- compute device memory (global and constant). Returns false if the device does
- not implement such error correction.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
+_Returns:_ The maximum depth of a 3D image in pixels.
+The minimum value is 2048 if the device has [api]#aspect::image#.
+
+'''
+
+.[apidef]#info::device::image_max_buffer_size#
+[source,role=synopsis,id=api:info-device-image-max-buffer-size]
----
-info::device::host_unified_memory
+namespace sycl::info::device {
+struct image_max_buffer_size {
+ using return_type = size_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#bool#
- a@ Deprecated, use [code]#device::has()# with one of the [code]#aspect::usm_*# aspects instead.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-Returns true if the device and the host have a unified memory subsystem and
-returns false otherwise.
+_Returns:_ The number of pixels for a 1D image created from a buffer object.
+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.
-a@
-[source]
+'''
+
+.[apidef]#info::device::max_samplers#
+[source,role=synopsis,id=api:info-device-max-samplers]
----
-info::device::atomic_memory_order_capabilities
+namespace sycl::info::device {
+struct max_samplers {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#std::vector#
- a@ Returns the set of memory orders supported by atomic operations on the
- device. When a device returns a "stronger" memory order in this set, it
- must also return all "weaker" memory orders. (See
- <> for a definition of "stronger" and "weaker"
- memory orders.) The memory orders [code]#memory_order::acquire#,
- [code]#memory_order::release#, and [code]#memory_order::acq_rel# are all
- the same strength. If a device returns one of these, it must return them
- all.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-At a minimum, each device must support [code]#memory_order::relaxed#.
+_Returns:_ The maximum number of samplers that can be used in a kernel.
+The minimum value is 16 if the device has [api]#aspect::image#.
-a@
-[source]
+'''
+
+.[apidef]#info::device::max_parameter_size#
+[source,role=synopsis,id=api:info-device-max-parameter-size]
----
-info::device::atomic_fence_order_capabilities
+namespace sycl::info::device {
+struct max_parameter_size {
+ using return_type = size_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#std::vector#
- a@ Returns the set of memory orders supported by [code]#atomic_fence# on
- the device. When a device returns a "stronger" memory order in this set,
- it must also return all "weaker" memory orders. (See
- <> for a definition of "stronger" and "weaker"
- memory orders.) At a minimum, each device must support
- [code]#memory_order::relaxed#, [code]#memory_order::acquire#,
- [code]#memory_order::release#, and [code]#memory_order::acq_rel#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::atomic_memory_scope_capabilities
-----
+_Returns:_ The maximum size in bytes of the arguments that can be passed to a
+kernel.
+The minimum value is 1024 if this device is not of device type
+[api]#info::device_type::custom#.
+For this minimum value, only a maximum of 128 arguments can be passed to a
+kernel.
- @ [.code]#std::vector#
- a@ Returns the set of memory scopes supported by atomic operations on the
- device. When a device returns a "wider" memory scope in this set, it
- must also return all "narrower" memory scopes. (See <>
- for a definition of "wider" and "narrower" scopes.) At a minimum, each
- device must support [code]#memory_scope::work_item#,
- [code]#memory_scope::sub_group#, and [code]#memory_scope::work_group#.
+'''
-a@
-[source]
+.[apidef]#info::device::mem_base_addr_align#
+[source,role=synopsis,id=api:info-device-mem-base-addr-align]
----
-info::device::atomic_fence_scope_capabilities
+namespace sycl::info::device {
+struct mem_base_addr_align {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#std::vector#
- a@ Returns the set of memory scopes supported by [code]#atomic_fence# on the
- device. When a device returns a "wider" memory scope in this set, it
- must also return all "narrower" memory scopes. (See <>
- for a definition of "wider" and "narrower" scopes.) At a minimum, each
- device must support [code]#memory_scope::work_item#,
- [code]#memory_scope::sub_group#, and [code]#memory_scope::work_group#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::profiling_timer_resolution
-----
+_Returns:_ The minimum value in bits of the largest supported SYCL built-in data
+type if this device is not of device type [api]#info::device_type::custom#.
- @ [.code]#size_t#
- a@ Returns the resolution of device timer in nanoseconds.
+'''
-a@
-[source]
+.[apidef]#info::device::half_fp_config#
+[source,role=synopsis,id=api:info-device-half-fp-config]
----
-info::device::is_endian_little
+namespace sycl::info::device {
+struct half_fp_config {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
----
- @ [.code]#bool#
- a@ Deprecated. Check the byte order of the host system instead. The host
- and device are required to have the same byte order.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-Returns true if this SYCL [code]#device# is a little endian device and returns
-false otherwise.
+_Returns:_ A [code]#std::vector# of [api]#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:
-a@
-[source]
-----
-info::device::is_available
-----
+* [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#
- @ [.code]#bool#
- a@ Returns true if the SYCL [code]#device# is available and returns false if the device is not
- available.
+If half precision is supported by this device (i.e. the device has
+[api]#aspect::fp16#) there is no minimum floating-point capability.
+If half support is not supported the returned [code]#std::vector# must be empty.
-a@
-[source]
+'''
+
+.[apidef]#info::device::single_fp_config#
+[source,role=synopsis,id=api:info-device-single-fp-config]
----
-info::device::is_compiler_available
+namespace sycl::info::device {
+struct single_fp_config {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
----
- @ [.code]#bool#
- a@ Deprecated.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-Returns the same value as [code]#device::has(aspect::online_compiler)#.
+_Returns:_ A [code]#std::vector# of [api]#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:
-a@
-[source]
-----
-info::device::is_linker_available
-----
+* [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#
- @ [.code]#bool#
- a@ Deprecated.
+If this device is not of type [api]#info::device_type::custom# then the minimum
+floating-point capability must be: [api]#info::fp_config::round_to_nearest# and
+[api]#info::fp_config::inf_nan#.
-Returns the same value as [code]#device::has(aspect::online_linker)#.
+'''
-a@
-[source]
+.[apidef]#info::device::double_fp_config#
+[source,role=synopsis,id=api:info-device-double-fp-config]
----
-info::device::execution_capabilities
+namespace sycl::info::device {
+struct double_fp_config {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
----
- @ [.code]#std::vector#
- a@ Returns a [code]#std::vector# of the [code]#info::execution_capability# describing the supported execution capabilities.
- Note that this information is intended for OpenCL interoperability only as SYCL only supports [code]#info::execution_capability::exec_kernel#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::queue_profiling
-----
+_Returns:_ A [code]#std::vector# of [api]#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]#bool#
- a@ Deprecated.
+* [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
+[api]#aspect::fp64#) and this device is not of type
+[api]#info::device_type::custom# then the minimum floating-point capability 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.
-Returns the same value as [code]#device::has(aspect::queue_profiling)#.
+'''
-a@
-[source]
+.[apidef]#info::device::global_mem_cache_type#
+[source,role=synopsis,id=api:info-device-global-mem-cache-type]
----
-info::device::built_in_kernel_ids
+namespace sycl::info::device {
+struct global_mem_cache_type {
+ using return_type = info::global_mem_cache_type;
+};
+} // namespace sycl::info::device
----
- @ [.code]#std::vector#
- a@ Returns a [code]#std::vector# of identifiers for the built-in kernels
- supported by this SYCL [code]#device#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
+_Returns:_ The type of global memory cache supported.
+
+'''
+
+.[apidef]#info::device::global_mem_cache_line_size#
+[source,role=synopsis,id=api:info-device-global-mem-cache-line-size]
----
-info::device::built_in_kernels
+namespace sycl::info::device {
+struct global_mem_cache_line_size {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#std::vector#
- a@ Deprecated. Use [code]#info::device::built_in_kernel_ids# instead.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-Returns a [code]#std::vector# of built-in OpenCL kernels supported by this SYCL
-[code]#device#.
+_Returns:_ The size of global memory cache line in bytes.
-a@
-[source]
+'''
+
+.[apidef]#info::device::global_mem_cache_size#
+[source,role=synopsis,id=api:info-device-global-mem-cache-size]
----
-info::device::platform
+namespace sycl::info::device {
+struct global_mem_cache_size {
+ using return_type = uint64_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#platform#
- a@ Returns the SYCL [code]#platform# associated with this SYCL [code]#device#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::name
-----
+_Returns:_ The size of global memory cache in bytes.
- @ [.code]#std::string#
- a@ Returns the device name of this SYCL [code]#device#.
+'''
-a@
-[source]
+.[apidef]#info::device::global_mem_size#
+[source,role=synopsis,id=api:info-device-global-mem-size]
----
-info::device::vendor
+namespace sycl::info::device {
+struct global_mem_size {
+ using return_type = uint64_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#std::string#
- a@ Returns the vendor of this SYCL [code]#device#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::driver_version
-----
+_Returns:_ The size of global device memory in bytes.
- @ [.code]#std::string#
- a@ Returns a vendor-defined string describing the version of the underlying
- backend software driver.
+'''
-a@
-[source]
+.[apidef]#info::device::max_constant_buffer_size#
+[source,role=synopsis,id=api:info-device-max-constant-buffer-size]
----
-info::device::profile
+namespace sycl::info::device {
+struct max_constant_buffer_size {
+ using return_type = uint64_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#std::string#
- a@ Deprecated in SYCL 2020. Only supported when using the OpenCL backend
- (see <>). Throws an [code]#exception# with the
- [code]#errc::invalid# error code if used with a device whose backend is
- not OpenCL.
+Deprecated by SYCL 2020.
-The value returned can be one of the following strings:
---
- * FULL_PROFILE - if the device supports the OpenCL specification
- (functionality defined as part of the core specification and does not
- require any extensions to be supported).
- * EMBEDDED_PROFILE - if the device supports the OpenCL embedded profile.
---
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::version
-----
+_Returns:_ The maximum size in bytes of a constant buffer allocation.
+The minimum value is 64 KB if this device is not of type
+[api]#info::device_type::custom#.
- @ [.code]#std::string#
- a@ Returns a backend-defined <> version.
+'''
-a@
-[source]
+.[apidef]#info::device::max_constant_args#
+[source,role=synopsis,id=api:info-device-max-constant-args]
----
-info::device::backend_version
+namespace sycl::info::device {
+struct max_constant_args {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#std::string#
- a@ Returns a string describing the version of the <> associated with
- the <>. The possible values are specified in the <>
- specification of the <> associated with the <>.
+Deprecated by SYCL 2020.
-a@
-[source]
-----
-info::device::aspects
-----
+_Remarks:_ Template parameter to [api]#device::get_info#.
- @ [.code]#std::vector#
- a@ Returns a [code]#std::vector# of <> values supported by this
- SYCL [code]#device#.
+_Returns:_ The maximum number of constant arguments that can be declared in a
+kernel.
+The minimum value is 8 if this device is not of type
+[api]#info::device_type::custom#.
-a@
-[source]
+'''
+
+.[apidef]#info::device::local_mem_type#
+[source,role=synopsis,id=api:info-device-local-mem-type]
----
-info::device::extensions
+namespace sycl::info::device {
+struct local_mem_type {
+ using return_type = info::local_mem_type;
+};
+} // namespace sycl::info::device
----
- @ [.code]#std::vector#
- a@ Deprecated, use [code]#info::device::aspects# instead.
---
-Returns a [code]#std::vector# of extension names (the extension names do not
-contain any spaces) supported by this SYCL [code]#device#.
-The extension names returned can be vendor supported extension names and one or
-more of the following Khronos approved extension names:
+_Remarks:_ Template parameter to [api]#device::get_info#.
- * [code]#cl_khr_int64_base_atomics#
- * [code]#cl_khr_int64_extended_atomics#
- * [code]#cl_khr_3d_image_writes#
- * [code]#cl_khr_fp16#
- * [code]#cl_khr_gl_sharing#
- * [code]#cl_khr_gl_event#
- * [code]#cl_khr_d3d10_sharing#
- * [code]#cl_khr_dx9_media_sharing#
- * [code]#cl_khr_d3d11_sharing#
- * [code]#cl_khr_depth_images#
- * [code]#cl_khr_gl_depth_images#
- * [code]#cl_khr_gl_msaa_sharing#
- * [code]#cl_khr_image2d_from_buffer#
- * [code]#cl_khr_initialize_memory#
- * [code]#cl_khr_context_abort#
- * [code]#cl_khr_spir#
-
-If this SYCL [code]#device# is an OpenCL device then following approved Khronos
-extension names must be returned by all device that support OpenCL C 1.2:
-
- * [code]#cl_khr_global_int32_base_atomics#
- * [code]#cl_khr_global_int32_extended_atomics#
- * [code]#cl_khr_local_int32_base_atomics#
- * [code]#cl_khr_local_int32_extended_atomics#
- * [code]#cl_khr_byte_addressable_store#
- * [code]#cl_khr_fp64# (for backward compatibility if double precision is
- supported)
+_Returns:_ The type of local memory supported.
+This can be [api]#info::local_mem_type::local# implying dedicated local memory
+storage such as SRAM, or [api]#info::local_mem_type::global#.
+If this device is of type [api]#info::device_type::custom# this can also be
+[api]#info::local_mem_type::none#, indicating local memory is not supported.
-Please refer to the OpenCL 1.2 Extension Specification for a detailed
-description of these extensions.
---
+'''
-a@
-[source]
+.[apidef]#info::device::local_mem_size#
+[source,role=synopsis,id=api:info-device-local-mem-size]
----
-info::device::printf_buffer_size
+namespace sycl::info::device {
+struct local_mem_size {
+ using return_type = uint64_t;
+};
+} // namespace sycl::info::device
----
- @ [.code]#size_t#
- a@ Deprecated in SYCL 2020.
+_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 SYCL [code]#device#.
+_Returns:_ The size of local memory arena in bytes.
+The minimum value is 32 KB if this device is not of type
+[api]#info::device_type::custom#.
-a@
-[source]
+'''
+
+.[apidef]#info::device::error_correction_support#
+[source,role=synopsis,id=api:info-device-error-correction-support]
----
-info::device::preferred_interop_user_sync
+namespace sycl::info::device {
+struct error_correction_support {
+ using return_type = bool;
+};
+} // namespace sycl::info::device
----
- @ [.code]#bool#
- a@ Deprecated in SYCL 2020. Only supported when using the OpenCL backend
- (see <>). Throws an [code]#exception# with the
- [code]#errc::invalid# error code if used with a device whose backend is
- not OpenCL.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-Returns true if the preference for this SYCL [code]#device# is for the user to
-be responsible for synchronization, when sharing memory objects between OpenCL
-and other APIs such as DirectX, false if the device/implementation has a
-performant path for performing synchronization of memory object shared between
-OpenCL and other APIs such as DirectX.
+_Returns:_ The value [code]#true# if the device implements error correction for
+all accesses to compute device memory (global and constant).
+Returns [coee]#false# if the device does not implement such error correction.
-a@
-[source]
+'''
+
+.[apidef]#info::device::host_unified_memory#
+[source,role=synopsis,id=api:info-device-host-unified-memory]
----
-info::device::parent_device
+namespace sycl::info::device {
+struct host_unified_memory {
+ using return_type = bool;
+};
+} // namespace sycl::info::device
----
- @ [.code]#device#
- a@ Returns the parent SYCL [code]#device# to which this sub-device is a child if this is a sub-device.
- Must throw an [code]#exception# with the [code]#errc::invalid# error code if this SYCL [code]#device# is not a sub device.
+Deprecated by SYCL 2020.
-a@
-[source]
-----
-info::device::partition_max_sub_devices
-----
+{note}Use [api]#device::has# with one of the [code]#aspect::usm_*# aspects
+instead.
+{endnote}
- @ [.code]#uint32_t#
- a@ Returns the maximum number of sub-devices that can be created when this SYCL [code]#device# is partitioned. The value returned cannot exceed the value returned by [code]#info::device::max_compute_units#.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::partition_properties
-----
+_Returns:_ The value [coee]#true# if the device and the host have a unified
+memory subsystem and returns [code]#false# otherwise.
- @ [.code]#std::vector#
- a@ Returns the partition properties supported by this SYCL [code]#device;# a
- vector of [code]#info::partition_property#. An element is returned in
- this vector only if the device can be partitioned into at least two sub
- devices along that partition property.
+'''
-a@
-[source]
+.[apidef]#info::device::atomic_memory_order_capabilities#
+[source,role=synopsis,id=api:info-device-atomic-memory-order-capabilities]
----
-info::device::partition_affinity_domains
+namespace sycl::info::device {
+struct atomic_memory_order_capabilities {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
----
- @ [.code]#std::vector#
- a@ Returns a [code]#std::vector# of the partition affinity domains
- supported by this SYCL [code]#device# when partitioning with
- [code]#info::partition_property::partition_by_affinity_domain#.
- An element is returned in this vector only if the device can be
- partitioned into at least two sub devices along that affinity domain.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
-----
-info::device::partition_type_property
-----
+_Returns:_ The set of memory orders supported by atomic operations on this
+device.
+When a device returns a "stronger" memory order in this set, it must also return
+all "weaker" memory orders.
+(See <> for a definition of "stronger" and "weaker" memory
+orders.)
+The memory orders [code]#memory_order::acquire#, [code]#memory_order::release#,
+and [code]#memory_order::acq_rel# are all the same strength.
+If a device returns one of these, it must return them all.
- @ [.code]#info::partition_property#
- a@ Returns the partition property of this SYCL [code]#device#. If this SYCL [code]#device# is not a sub device then the return value must be [code]#info::partition_property::no_partition#, otherwise it must be one of the following values:
---
- * [code]#info::partition_property::partition_equally#
- * [code]#info::partition_property::partition_by_counts#
- * [code]#info::partition_property::partition_by_affinity_domain#
---
+At a minimum, each device must support [code]#memory_order::relaxed#.
-a@
-[source]
+'''
+
+.[apidef]#info::device::atomic_fence_order_capabilities#
+[source,role=synopsis,id=api:info-device-atomic-fence-order-capabilities]
----
-info::device::partition_type_affinity_domain
+namespace sycl::info::device {
+struct atomic_fence_order_capabilities {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
----
- @ [.code]#info::partition_affinity_domain#
- a@ Returns the partition affinity domain of this SYCL [code]#device#. If this SYCL [code]#device# is not a sub device or the sub device was not partitioned with [code]#info::partition_type::partition_by_affinity_domain# then the return value must be [code]#info::partition_affinity_domain::not_applicable#, otherwise it must be one of the following values:
---
- * [code]#info::partition_affinity_domain::numa#
- * [code]#info::partition_affinity_domain::L4_cache#
- * [code]#info::partition_affinity_domain::L3_cache#
- * [code]#info::partition_affinity_domain::L2_cache#
- * [code]#info::partition_affinity_domain::L1_cache#
---
+_Remarks:_ Template parameter to [api]#device::get_info#.
-|====
+_Returns:_ The set of memory orders supported by [code]#atomic_fence# on this
+device.
+When a device returns a "stronger" memory order in this set, it must also return
+all "weaker" memory orders.
+(See <> for a definition of "stronger" and "weaker" memory
+orders.)
+At a minimum, each device must support [code]#memory_order::relaxed#,
+[code]#memory_order::acquire#, [code]#memory_order::release#, and
+[code]#memory_order::acq_rel#.
+'''
+.[apidef]#info::device::atomic_memory_scope_capabilities#
+[source,role=synopsis,id=api:info-device-atomic-memory-scope-capabilities]
+----
+namespace sycl::info::device {
+struct atomic_memory_scope_capabilities {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
+----
-[[sec:device-aspects]]
-==== Device aspects
+_Remarks:_ Template parameter to [api]#device::get_info#.
-Every SYCL <> has an associated set of <> which identify
-characteristics of the [code]#device#.
-Aspects are defined via the [code]#enum class aspect# enumeration:
+_Returns:_ The set of memory scopes supported by atomic operations on this
+device.
+When a device returns a "wider" memory scope in this set, it must also return
+all "narrower" memory scopes.
+(See <> for a definition of "wider" and "narrower" scopes.)
+At a minimum, each device must support [code]#memory_scope::work_item#,
+[code]#memory_scope::sub_group#, and [code]#memory_scope::work_group#.
-[source,,linenums]
+'''
+
+.[apidef]#info::device::atomic_fence_scope_capabilities#
+[source,role=synopsis,id=api:info-device-atomic-fence-scope-capabilities]
----
-include::{header_dir}/deviceEnumClassAspect.h[lines=4..-1]
+namespace sycl::info::device {
+struct atomic_fence_scope_capabilities {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
----
-SYCL applications can query the aspects for a [code]#device# via
-[code]#device::has()# in order to determine whether the [code]#device# supports
-any optional features.
-<> lists the aspects that are defined in the <>
-and tells which optional features correspond to each.
-Backends and extensions may provide additional aspects and additional optional
-device features.
-If so, the <> specification document or the extension document
-describes them.
+_Remarks:_ Template parameter to [api]#device::get_info#.
-[[table.device.aspect]]
-.Device aspects defined by the <>
-[width="100%",options="header",separator="@",cols="50%,50%"]
-|====
-@ Aspect @ Description
-a@
-[source]
+_Returns:_ The set of memory scopes supported by [code]#atomic_fence# on this
+device.
+When a device returns a "wider" memory scope in this set, it must also return
+all "narrower" memory scopes.
+(See <> for a definition of "wider" and "narrower" scopes.)
+At a minimum, each device must support [code]#memory_scope::work_item#,
+[code]#memory_scope::sub_group#, and [code]#memory_scope::work_group#.
+
+'''
+
+.[apidef]#info::device::profiling_timer_resolution#
+[source,role=synopsis,id=api:info-device-profiling-timer-resolution]
----
-aspect::cpu
+namespace sycl::info::device {
+struct profiling_timer_resolution {
+ using return_type = size_t;
+};
+} // namespace sycl::info::device
----
- a@ A device that runs on a CPU. Devices with this [code]#aspect# have
- device type [code]#info::device_type::cpu#.
-a@
-[source]
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ The resolution of device timer in nanoseconds.
+
+'''
+
+.[apidef]#info::device::is_endian_little#
+[source,role=synopsis,id=api:info-device-is-endian-little]
----
-aspect::gpu
+namespace sycl::info::device {
+struct is_endian_little {
+ using return_type = bool;
+};
+} // namespace sycl::info::device
----
- a@ A device that can also be used to accelerate a 3D graphics API. Devices
- with this [code]#aspect# have device type
- [code]#info::device_type::gpu#.
-a@
-[source]
+Deprecated by SYCL 2020.
+
+{note}Check the byte order of the host system instead.
+The host and device are required to have the same byte order.
+{endnote}
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ The value [code]#true# if this device is a little endian device and
+returns [code]#false# otherwise.
+
+'''
+
+.[apidef]#info::device::is_available#
+[source,role=synopsis,id=api:info-device-is-available]
----
-aspect::accelerator
+namespace sycl::info::device {
+struct is_available {
+ using return_type = bool;
+};
+} // namespace sycl::info::device
----
- a@ A dedicated accelerator device, usually using a peripheral interconnect for
- communication. Devices with this [code]#aspect# have device type
- [code]#info::device_type::accelerator#.
-a@
-[source]
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ The value [code]#true# if the device is available and [code]#false#
+if the device is not available.
+
+'''
+
+.[apidef]#info::device::is_compiler_available#
+[source,role=synopsis,id=api:info-device-is-compiler-available]
----
-aspect::custom
+namespace sycl::info::device {
+struct is_compiler_available {
+ using return_type = bool;
+};
+} // namespace sycl::info::device
----
- a@ A dedicated accelerator that can use the SYCL API, but programmable kernels
- cannot be dispatched to the device, only fixed functionality is available.
- See <>. Devices with this
- [code]#aspect# have device type [code]#info::device_type::custom#.
-a@
-[source]
+Deprecated by SYCL 2020.
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ The same value as [code]#device::has(aspect::online_compiler)#.
+
+'''
+
+.[apidef]#info::device::is_linker_available#
+[source,role=synopsis,id=api:info-device-is-linker-available]
----
-aspect::emulated
+namespace sycl::info::device {
+struct is_linker_available {
+ using return_type = bool;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that the device is somehow emulated. A device with this aspect
- is not intended for performance, and instead will generally have another
- purpose such as emulation or profiling. The precise definition of this
- aspect is left open to the SYCL implementation.
-[NOTE]
-====
-As an example, a vendor might support both a hardware FPGA device and a 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.
-====
+Deprecated by SYCL 2020.
-a@
-[source]
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ The same value as [code]#device::has(aspect::online_linker)#.
+
+'''
+
+.[apidef]#info::device::execution_capabilities#
+[source,role=synopsis,id=api:info-device-execution-capabilities]
----
-aspect::host_debuggable
+namespace sycl::info::device {
+struct execution_capabilities {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that <> running on this device can be debugged
- using standard debuggers that are normally available on the host system
- where the SYCL implementation resides. The precise definition of this
- aspect is left open to the SYCL implementation.
-a@
-[source]
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_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#.
+
+'''
+
+.[apidef]#info::device::queue_profiling#
+[source,role=synopsis,id=api:info-device-queue-profiling]
----
-aspect::fp16
+namespace sycl::info::device {
+struct queue_profiling {
+ using return_type =
+};
+} // namespace sycl::info::device
----
- a@ Indicates that kernels submitted to the device may use the
- [code]#sycl::half# data type.
-a@
-[source]
+Deprecated by SYCL 2020.
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ The same value as [code]#device::has(aspect::queue_profiling)#.
+
+'''
+
+.[apidef]#info::device::built_in_kernel_ids#
+[source,role=synopsis,id=api:info-device-built-in-kernel-ids]
----
-aspect::fp64
+namespace sycl::info::device {
+struct built_in_kernel_ids {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that kernels submitted to the device may use the [code]#double#
- data type.
-a@
-[source]
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ A [code]#std::vector# of identifiers for the built-in kernels
+supported by this device.
+
+'''
+
+.[apidef]#info::device::built_in_kernels#
+[source,role=synopsis,id=api:info-device-built-in-kernels]
----
-aspect::atomic64
+namespace sycl::info::device {
+struct built_in_kernels {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that kernels submitted to the device may perform 64-bit atomic
- operations.
-a@
-[source]
+Deprecated by SYCL 2020.
+
+{note}Use [api]#info::device::built_in_kernel_ids# instead.
+{endnote}
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ A [code]#std::vector# of built-in OpenCL kernels supported by this
+device.
+
+'''
+
+.[apidef]#info::device::platform#
+[source,role=synopsis,id=api:info-device-platform]
----
-aspect::image
+namespace sycl::info::device {
+struct platform {
+ using return_type = platform;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that the device supports <>.
-a@
-[source]
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ The <> that is associated with this device.
+
+'''
+
+.[apidef]#info::device::name#
+[source,role=synopsis,id=api:info-device-name]
----
-aspect::online_compiler
+namespace sycl::info::device {
+struct name {
+ using return_type = std::string;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that the device supports online compilation of device code.
- <> that have this aspect support the [code]#build()#
- and [code]#compile()# functions defined in <>.
-a@
-[source]
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ An implementation-defined name for this device.
+
+'''
+
+.[apidef]#info::device::vendor#
+[source,role=synopsis,id=api:info-device-vendor]
----
-aspect::online_linker
+namespace sycl::info::device {
+struct vendor {
+ using return_type = std::string;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that the device supports online linking of device code.
- <> that have this aspect support the [code]#link()#
- functions defined in <>. All
- <> that have this aspect also have
- [code]#aspect::online_compiler#.
-a@
-[source]
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ An implementation-defined name for the vendor providing this device.
+
+'''
+
+.[apidef]#info::device::driver_version#
+[source,role=synopsis,id=api:info-device-driver-version]
----
-aspect::queue_profiling
+namespace sycl::info::device {
+struct driver_version {
+ using return_type = std::string;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that the device supports queue profiling via [code]#property::queue::enable_profiling#.
-a@
-[source]
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ An implementation-defined name describing the version of the
+underlying software driver for this device.
+
+'''
+
+.[apidef]#info::device::profile#
+[source,role=synopsis,id=api:info-device-profile]
----
-aspect::usm_device_allocations
+namespace sycl::info::device {
+struct profile {
+ using return_type = std::string;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that the device supports explicit USM allocations as described
- in <>.
-a@
-[source]
+Deprecated by SYCL 2020.
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ Only supported when the backend of this device is OpenCL (see
+<>).
+The value returned can be one of the following strings:
+
+* FULL_PROFILE - if the device supports the OpenCL specification (functionality
+ defined as part of the core specification and does not require any extensions
+ to be supported).
+* EMBEDDED_PROFILE - if the device supports the OpenCL embedded profile.
+
+_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code if the
+backend of this device is not OpenCL.
+
+'''
+
+.[apidef]#info::device::version#
+[source,role=synopsis,id=api:info-device-version]
----
-aspect::usm_host_allocations
+namespace sycl::info::device {
+struct version {
+ using return_type = std::string;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that the device can access USM memory allocated via
- [code]#usm::alloc::host#. The device only
- supports atomic modification of a host allocation if
- [code]#aspect::usm_atomic_host_allocations# is also supported.
- (See <>.)
-a@
-[source]
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ A backend-defined device version.
+
+'''
+
+.[apidef]#info::device::backend_version#
+[source,role=synopsis,id=api:info-device-backend-version]
----
-aspect::usm_atomic_host_allocations
+namespace sycl::info::device {
+struct backend_version {
+ using return_type = std::string;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that the device supports USM memory allocated
- via [code]#usm::alloc::host#. The host and this device may
- concurrently access and atomically modify host allocations. (See <>.)
+_Remarks:_ Template parameter to [api]#device::get_info#.
-a@
-[source]
+_Returns:_ A string describing the version of the <> associated with
+this device.
+The value returned from this query is defined by the backend interoperation
+specification that corresponds to this device's backend.
+
+'''
+
+.[apidef]#info::device::aspects#
+[source,role=synopsis,id=api:info-device-aspects]
----
-aspect::usm_shared_allocations
+namespace sycl::info::device {
+struct aspects {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that the device supports USM memory allocated via
- [code]#usm::alloc::shared# on the same device. Concurrent access
- and atomic modification of a shared allocation is only supported
- if [code]#aspect::usm_atomic_shared_allocations# is also supported.
- (See <>.)
-a@
-[source]
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ A [code]#std::vector# of <> values supported by this device.
+
+'''
+
+.[apidef]#info::device::extensions#
+[source,role=synopsis,id=api:info-device-extensions]
----
-aspect::usm_atomic_shared_allocations
+namespace sycl::info::device {
+struct extensions {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that the device supports USM memory allocated via
- [code]#usm::alloc::shared#. The host and other devices in the same
- context that also support this capability may concurrently access
- and atomically modify shared allocations. The allocation is free
- to migrate between the host and the appropriate devices. (See <>.)
-a@
-[source]
+Deprecated by SYCL 2020.
+
+{note}Use [api]#info::device::aspects# instead.
+{endnote}
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ A [code]#std::vector# of extension names (the extension names do not
+contain any spaces) supported by this device.
+The extension names returned can be vendor supported extension names and one or
+more of the following Khronos approved extension names:
+
+* [code]#cl_khr_int64_base_atomics#
+* [code]#cl_khr_int64_extended_atomics#
+* [code]#cl_khr_3d_image_writes#
+* [code]#cl_khr_fp16#
+* [code]#cl_khr_gl_sharing#
+* [code]#cl_khr_gl_event#
+* [code]#cl_khr_d3d10_sharing#
+* [code]#cl_khr_dx9_media_sharing#
+* [code]#cl_khr_d3d11_sharing#
+* [code]#cl_khr_depth_images#
+* [code]#cl_khr_gl_depth_images#
+* [code]#cl_khr_gl_msaa_sharing#
+* [code]#cl_khr_image2d_from_buffer#
+* [code]#cl_khr_initialize_memory#
+* [code]#cl_khr_context_abort#
+* [code]#cl_khr_spir#
+
+If the backend associated with this device is OpenCL, then following approved
+Khronos extension names must be returned by all device that support OpenCL C
+1.2:
+
+* [code]#cl_khr_global_int32_base_atomics#
+* [code]#cl_khr_global_int32_extended_atomics#
+* [code]#cl_khr_local_int32_base_atomics#
+* [code]#cl_khr_local_int32_extended_atomics#
+* [code]#cl_khr_byte_addressable_store#
+* [code]#cl_khr_fp64# (for backward compatibility if double precision is
+ supported)
+
+Please refer to the OpenCL 1.2 Extension Specification for a detailed
+description of these extensions.
+
+'''
+
+.[apidef]#info::device::printf_buffer_size#
+[source,role=synopsis,id=api:info-device-printf-buffer-size]
----
-aspect::usm_system_allocations
+namespace sycl::info::device {
+struct printf_buffer_size {
+ using return_type = size_t;
+};
+} // namespace sycl::info::device
----
- a@ Indicates that the system allocator may be used instead of SYCL USM
- allocation mechanisms for [code]#usm::alloc::shared# allocations on
- this device. (See <>.)
-|====
+Deprecated by SYCL 2020.
+
+_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 [api]#info::device::profile# returns true for this
+device.
+
+'''
+
+.[apidef]#info::device::preferred_interop_user_sync#
+[source,role=synopsis,id=api:info-device-preferred-interop-user-sync]
+----
+namespace sycl::info::device {
+struct preferred_interop_user_sync {
+ using return_type = bool;
+};
+} // namespace sycl::info::device
+----
+
+Deprecated by SYCL 2020.
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ Only supported when the backend of this device is OpenCL (see
+<>).
+Returns [code]#true# if the preference for this device is for the user to be
+responsible for synchronization, when sharing memory objects between OpenCL and
+other APIs such as DirectX, [code]#false# if the device/implementation has a
+performant path for performing synchronization of memory object shared between
+OpenCL and other APIs such as DirectX.
+
+_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code if the
+backend of this device is not OpenCL.
+
+'''
+
+.[apidef]#info::device::parent_device#
+[source,role=synopsis,id=api:info-device-parent-device]
+----
+namespace sycl::info::device {
+info::device::parent_device
+struct parent_device {
+ using return_type = device;
+};
+} // namespace sycl::info::device
+----
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ The parent device to which this sub device is a child if this is a
+sub device.
+
+_Throws:_ An [code]#exception# with the [code]#errc::invalid# error code if this
+device is not a sub device.
+
+'''
+
+.[apidef]#info::device::partition_max_sub_devices#
+[source,role=synopsis,id=api:info-device-partition-max-sub-devices]
+----
+namespace sycl::info::device {
+struct partition_max_sub_devices {
+ using return_type = uint32_t;
+};
+} // namespace sycl::info::device
+----
+
+_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
+[api]#info::device::max_compute_units#.
+
+'''
+
+.[apidef]#info::device::partition_properties#
+[source,role=synopsis,id=api:info-device-partition-properties]
+----
+namespace sycl::info::device {
+struct partition_properties {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
+----
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ A [code]#std::vector# of the partition properties supported by this
+device.
+An element is returned in this vector only if the device can be partitioned into
+at least two sub devices along that partition property.
+
+'''
+
+.[apidef]#info::device::partition_affinity_domains#
+[source,role=synopsis,id=api:info-device-partition-affinity-domains]
+----
+namespace sycl::info::device {
+struct partition_affinity_domains {
+ using return_type = std::vector;
+};
+} // namespace sycl::info::device
+----
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ A [code]#std::vector# of the partition affinity domains supported by
+this device when partitioning with
+[api]#info::partition_property::partition_by_affinity_domain#.
+An element is returned in this vector only if the device can be partitioned into
+at least two sub devices along that affinity domain.
+
+'''
+
+.[apidef]#info::device::partition_type_property#
+[source,role=synopsis,id=api:info-device-partition-type-property]
+----
+namespace sycl::info::device {
+struct partition_type_property {
+ using return_type = info::partition_property;
+};
+} // namespace sycl::info::device
+----
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ The partition property of this device.
+If this device is not a sub device then the return value is
+[api]#info::partition_property::no_partition#, otherwise it is one of the
+following values:
+
+* [api]#info::partition_property::partition_equally#
+* [api]#info::partition_property::partition_by_counts#
+* [api]#info::partition_property::partition_by_affinity_domain#
+
+'''
+
+.[apidef]#info::device::partition_type_affinity_domain#
+[source,role=synopsis,id=api:info-device-partition-type-affinity-domain]
+----
+namespace sycl::info::device {
+struct partition_type_affinity_domain {
+ using return_type = info::partition_affinity_domain;
+};
+} // namespace sycl::info::device
+----
+
+_Remarks:_ Template parameter to [api]#device::get_info#.
+
+_Returns:_ The partition affinity domain of this device.
+If this device is not a sub device or the sub device was not partitioned with
+[api]#info::partition_property::partition_by_affinity_domain# then the return
+value is [api]#info::partition_affinity_domain::not_applicable#, otherwise it is
+one of the following values:
+
+* [api]#info::partition_affinity_domain::numa#
+* [api]#info::partition_affinity_domain::L4_cache#
+* [api]#info::partition_affinity_domain::L3_cache#
+* [api]#info::partition_affinity_domain::L2_cache#
+* [api]#info::partition_affinity_domain::L1_cache#
+
+'''
+
+[[sec:device-aspects]]
+==== Aspects
+
+Every device has an associated set of aspects which identify characteristics of
+the device.
+Aspects are defined via the [code]#aspect# enumeration:
+
+[source,role=synopsis]
+----
+include::{header_dir}/deviceEnumClassAspect.h[lines=4..-1]
+----
+
+Applications can query the aspects of a device via [api]#device::has# in order
+to determine whether the device supports any optional features.
+The following list describes the aspects that are defined in the <>
+and tells which optional features correspond to each.
+Backends and extensions may provide additional aspects and additional optional
+device features.
+If so, the <> specification document or the extension document
+describes them.
+
+'''
+
+.[apidef]#aspect::cpu#
+[role=synopsis,id=api:aspect-cpu]
+--
+A device that runs on a CPU.
+Devices with this aspect have device type [api]#info::device_type::cpu#.
+--
+
+'''
+
+.[apidef]#aspect::gpu#
+[role=synopsis,id=api:aspect-gpu]
+--
+A device that can also be used to accelerate a 3D graphics API.
+Devices with this aspect have device type [api]#info::device_type::gpu#.
+--
+
+'''
+
+.[apidef]#aspect::accelerator#
+[role=synopsis,id=api:aspect-accelerator]
+--
+A dedicated accelerator device, usually using a peripheral interconnect for
+communication.
+Devices with this aspect have device type [api]#info::device_type::accelerator#.
+--
+
+'''
+
+.[apidef]#aspect::custom#
+[role=synopsis,id=api:aspect-custom]
+--
+A dedicated accelerator that can use the SYCL API, but programmable kernels
+cannot be dispatched to the device, only fixed functionality is available.
+See <>.
+Devices with this aspect have device type [api]#info::device_type::custom#.
+--
+
+'''
+
+.[apidef]#aspect::emulated#
+[role=synopsis,id=api:aspect-emulated]
+--
+Indicates that the device is somehow emulated.
+A device with this aspect is not intended for performance, and instead will
+generally have another purpose such as emulation or profiling.
+The precise definition of this aspect is left open to the SYCL implementation.
+
+{note}As an example, a vendor might support both a hardware FPGA device and a
+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
+[api]#aspect::emulated# to distinguish the two.
+{endnote}
+--
+
+'''
+
+.[apidef]#aspect::host_debuggable#
+[role=synopsis,id=api:aspect-host-debuggable]
+--
+Indicates that <> running on this device can be debugged using
+standard debuggers that are normally available on the host system where the SYCL
+implementation resides.
+The precise definition of this aspect is left open to the SYCL implementation.
+--
+
+'''
+
+.[apidef]#aspect::fp16#
+[role=synopsis,id=api:aspect-fp16]
+--
+Indicates that kernels submitted to the device may use the [code]#sycl::half#
+data type.
+--
+
+'''
+
+.[apidef]#aspect::fp64#
+[role=synopsis,id=api:aspect-fp64]
+--
+Indicates that kernels submitted to the device may use the [code]#double# data
+type.
+--
+
+'''
+
+.[apidef]#aspect::atomic64#
+[role=synopsis,id=api:aspect-atomic64]
+--
+Indicates that kernels submitted to the device may perform 64-bit atomic
+operations.
+--
+
+'''
+
+.[apidef]#aspect::image#
+[role=synopsis,id=api:aspect-image]
+--
+Indicates that the device supports <>.
+--
+
+'''
+
+.[apidef]#aspect::online_compiler#
+[role=synopsis,id=api:aspect-online-compiler]
+--
+Indicates that the device supports online compilation of device code.
+Devices that have this aspect support the [code]#build# and [code]#compile#
+functions defined in <>.
+--
+
+'''
+
+.[apidef]#aspect::online_linker#
+[role=synopsis,id=api:aspect-online-linker]
+--
+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 [api]#aspect::online_compiler#.
+--
+
+'''
+
+.[apidef]#aspect::queue_profiling#
+[role=synopsis,id=api:aspect-queue-profiling]
+--
+Indicates that the device supports queue profiling via
+[code]#property::queue::enable_profiling#.
+--
+
+'''
+
+.[apidef]#aspect::usm_device_allocations#
+[role=synopsis,id=api:aspect-usm-device-allocations]
+--
+Indicates that the device supports explicit USM allocations as described in
+<>.
+--
+
+'''
+
+.[apidef]#aspect::usm_host_allocations#
+[role=synopsis,id=api:aspect-usm-host-allocations]
+--
+Indicates that the device can access USM memory allocated via
+[code]#usm::alloc::host#.
+The device only supports atomic modification of a host allocation if
+[api]#aspect::usm_atomic_host_allocations# is also supported.
+(See <>.)
+--
+
+'''
+
+.[apidef]#aspect::usm_atomic_host_allocations#
+[role=synopsis,id=api:aspect-usm-atomic-host-allocations]
+--
+Indicates that the device supports USM memory allocated via
+[code]#usm::alloc::host#.
+The host and this device may concurrently access and atomically modify host
+allocations.
+(See <>.)
+--
+
+'''
+
+.[apidef]#aspect::usm_shared_allocations#
+[role=synopsis,id=api:aspect-usm-shared-allocations]
+--
+Indicates that the device supports USM memory allocated via
+[code]#usm::alloc::shared# on the same device.
+Concurrent access and atomic modification of a shared allocation is only
+supported if [api]#aspect::usm_atomic_shared_allocations# is also supported.
+(See <>.)
+--
+
+'''
+
+.[apidef]#aspect::usm_atomic_shared_allocations#
+[role=synopsis,id=api:aspect-usm-atomic-shared-allocations]
+--
+Indicates that the device supports USM memory allocated via
+[code]#usm::alloc::shared#.
+The host and other devices in the same context that also support this capability
+may concurrently access and atomically modify shared allocations.
+The allocation is free to migrate between the host and the appropriate devices.
+(See <>.)
+--
+
+'''
+
+.[apidef]#aspect::usm_system_allocations#
+[role=synopsis,id=api:aspect-usm-system-allocations]
+--
+Indicates that the system allocator may be used instead of SYCL USM allocation
+mechanisms for [code]#usm::alloc::shared# allocations on this device.
+(See <>.)
+--
+
+'''
+
+[[sec:device-aspect-traits]]
+==== Aspect traits
The implementation also provides two traits that the application can use to
query aspects at compilation time.
@@ -2849,7 +3428,7 @@ only if at least one device in _D_ has the specified aspect.
The trait [code]#all_devices_have# inherits from [code]#std::true_type#
only if all devices in _D_ have the specified aspect.
-[source,,linenums]
+[source,role=synopsis]
----
include::{header_dir}/aspectTraits.h[lines=4..-1]
----
@@ -2865,51 +3444,229 @@ include::{code_dir}/aspectTraitExample.cpp[lines=4..-1]
----
The kernel function [code]#MyKernel# is templated to use a different algorithm
-depending on whether the device has the aspect [code]#aspect::fp16#, and the
-call to [code]#dev.has()# chooses the kernel function instantiation that matches
-the device's capabilities.
+depending on whether the device has the aspect [api]#aspect::fp16#, and the call
+to [code]#dev.has()# chooses the kernel function instantiation that matches the
+device's capabilities.
However, the use of [code]#any_device_has_v# and [code]#all_devices_have_v#
entirely avoid useless instantiations of the kernel function.
For example, when the compilation environment does not support any devices with
-[code]#aspect::fp16#, [code]#any_device_has_v# is [code]#false#,
+[api]#aspect::fp16#, [code]#any_device_has_v# is [code]#false#,
and the kernel function is never instantiated with support for the
[code]#sycl::half# type.
-[NOTE]
-====
-Like any trait, the definitions of [code]#any_device_has# and
+{note}Like any trait, the definitions of [code]#any_device_has# and
[code]#all_devices_have# are uniform across all parts of a SYCL application.
If an implementation uses <>, all compiler passes define a particular
aspect's specialization of the traits the same way, regardless of whether that
compiler pass' device supports the aspect.
Thus, [code]#any_device_has# and [code]#all_devices_have# cannot be used to
determine whether any particular device supports an aspect.
-Instead, applications must use [code]#device::has()# or [code]#platform::has()#
-for this.
-====
+Instead, applications must use [api]#device::has# or [code]#platform::has# for
+this.
+{endnote}
-[NOTE]
-====
-An implementation could choose to provide command line options which affect the
-set of devices that it supports.
+{note}An implementation could choose to provide command line options which
+affect the set of devices that it supports.
If so, those command line options would also affect these traits.
For example, if an implementation provides a command line option that disables
-[code]#aspect::accelerator# devices, the trait
+[api]#aspect::accelerator# devices, the trait
[code]#any_device_has# would inherit from
[code]#std::false_type# when that command line option was specified.
-====
+{endnote}
-[NOTE]
-====
-These traits only reflect the supported devices at the time the SYCL application
-is compiled.
+{note}These traits only reflect the supported devices at the time the SYCL
+application is compiled.
It's possible that unsupported devices are still visible to the application when
it runs.
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
+----
-// %%%%%%%%%%%%%%%%%%%%%%%%%%%% end device_class %%%%%%%%%%%%%%%%%%%%%%%%%%%%
+'''
+
+.[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]]
@@ -10089,7 +10846,7 @@ USM is an optional feature which may not be supported by all devices, and
devices that support USM may not support all types of USM allocation.
A SYCL application can use the [code]#device::has()# function to determine the
level of USM support for a device.
-See <> in <> for more details.
+See <> for more details.
The characteristics of USM allocations are summarized in
<>.
@@ -10204,7 +10961,7 @@ set of shared allocations larger than device memory.
Users may query whether a device supports concurrent access with atomic
modification of shared allocations through the aspect
[code]#aspect::usm_atomic_shared_allocations#.
-See <> in <> for more details.
+See <> for more details.
Performance hints for shared allocations may be specified by the user by
enqueuing [code]#prefetch# operations on a device.
diff --git a/adoc/config/api_xrefs.adoc b/adoc/config/api_xrefs.adoc
new file mode 100644
index 00000000..5555cc46
--- /dev/null
+++ b/adoc/config/api_xrefs.adoc
@@ -0,0 +1,37 @@
+// Copyright (c) 2011-2024 The Khronos Group, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Define an association between API names and IDs to use for automatic cross
+// references. See the "api-xref" extension.
+//
+:api-xrefs: device=sec:device-class \
+ all_devices_have=sec:device-aspect-traits \
+ any_device_has=sec:device-aspect-traits \
+ aspect=sec:device-aspects \
+ info::device_type=sec:device-enum-device-type \
+ info::device_type::cpu=sec:device-enum-device-type \
+ info::device_type::gpu=sec:device-enum-device-type \
+ info::device_type::accelerator=sec:device-enum-device-type \
+ 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 \
+ info::local_mem_type::none=sec:device-enum-local-mem-type \
+ info::local_mem_type::local=sec:device-enum-local-mem-type \
+ info::local_mem_type::global=sec:device-enum-local-mem-type \
+ info::partition_affinity_domain=sec:device-enum-partition-affinity-domain \
+ info::partition_affinity_domain::not_applicable=sec:device-enum-partition-affinity-domain \
+ info::partition_affinity_domain::numa=sec:device-enum-partition-affinity-domain \
+ info::partition_affinity_domain::L4_cache=sec:device-enum-partition-affinity-domain \
+ info::partition_affinity_domain::L3_cache=sec:device-enum-partition-affinity-domain \
+ info::partition_affinity_domain::L2_cache=sec:device-enum-partition-affinity-domain \
+ info::partition_affinity_domain::L1_cache=sec:device-enum-partition-affinity-domain \
+ info::partition_affinity_domain::next_partitionable=sec:device-enum-partition-affinity-domain \
+ info::partition_property=sec:device-enum-partition-property \
+ info::partition_property::no_partition=sec:device-enum-partition-property \
+ info::partition_property::partition_equally=sec:device-enum-partition-property \
+ info::partition_property::partition_by_counts=sec:device-enum-partition-property \
+ info::partition_property::partition_by_affinity_domain=sec:device-enum-partition-property
diff --git a/adoc/syclbase.adoc b/adoc/syclbase.adoc
index 1439f542..e2533049 100644
--- a/adoc/syclbase.adoc
+++ b/adoc/syclbase.adoc
@@ -65,6 +65,7 @@ The Khronos{regtitle} {SYCL_NAME}{tmtitle} Working Group
:title-logo-image: image:logos/SYCL_RGB_June16-inkscape-1500.png[Logo,pdfwidth=4in,align=right]
// Various special / math symbols. This is easier to edit with than Unicode.
include::config/attribs.adoc[]
+include::config/api_xrefs.adoc[]
// Default TikZ conversion to SVG, not PDF (default), per email from Pepijn
// Van Eeckhoudt