From ef5ebff7185892c074f40e3fe401fedca142c141 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 3 Oct 2024 14:19:57 -0400 Subject: [PATCH] Update device description to new format Cherry pick #601 from main (cherry picked from commit a9e6c924c28ee7f1e420ca5084df933476ed4db6) --- adoc/chapters/information_descriptors.adoc | 2 +- adoc/chapters/programming_interface.adoc | 2757 +++++++++++++------- adoc/config/api_xrefs.adoc | 37 + adoc/syclbase.adoc | 1 + 4 files changed, 1796 insertions(+), 1001 deletions(-) create mode 100644 adoc/config/api_xrefs.adoc 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