From caf7d9cbd6d980162acc5557a45cbf5ebe82978e Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 23 May 2024 18:20:55 -0400 Subject: [PATCH] Update platform description to new format Update the section describing the `platform` class to the new format. --- adoc/chapters/information_descriptors.adoc | 2 +- adoc/chapters/programming_interface.adoc | 297 ++++++++++++--------- 2 files changed, 165 insertions(+), 134 deletions(-) diff --git a/adoc/chapters/information_descriptors.adoc b/adoc/chapters/information_descriptors.adoc index 2cfc189a..46d16e7f 100644 --- a/adoc/chapters/information_descriptors.adoc +++ b/adoc/chapters/information_descriptors.adoc @@ -11,7 +11,7 @@ introduced in <>. == Platform information descriptors The following interface includes all the information descriptors for the -[code]#platform# class as described in <>. +[code]#platform# class. [source,,linenums] ---- include::{header_dir}/platformInfo.h[lines=4..-1] diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 0730736d..d041271f 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -949,12 +949,12 @@ to resolve some ambiguity in constructors with default parameters. [[sec:platform-class]] === Platform class -The SYCL [code]#platform# class encapsulates a single SYCL platform on which -SYCL kernel functions may be executed. -A SYCL platform must be associated with a single <>. +The [code]#platform# class encapsulates a single SYCL platform on which kernel +functions may be executed. +A platform must be associated with a single <>. -A SYCL [code]#platform# is also associated with any number of SYCL -[code]#devices# associated with the same <>. +A [code]#platform# also contains a set of devices that are associated with the +same <>. A platform may contain no devices. All member functions of the [code]#platform# class are synchronous and errors @@ -963,207 +963,238 @@ are handled by throwing synchronous SYCL exceptions. The execution environment for a SYCL application has a fixed number of platforms which does not vary as the application executes. The application can get a list of all these platforms via -[code]#platform::get_platforms()#, and the order of the platform objects is the +[api]#platform::get_platforms#, and the order of the platform objects is the same each time the application calls that function. The [code]#platform# class also provides constructors, but constructing a new [code]#platform# instance merely creates a new object that is a copy of one of -the objects returned by [code]#platform::get_platforms()#. +the objects returned by [api]#platform::get_platforms#. -The SYCL [code]#platform# class provides the common reference semantics (see -<>). - -==== Platform interface - -A synopsis of the SYCL [code]#platform# class is provided below. -The constructors, member functions and static member functions of the SYCL -[code]#platform# class are listed in <>, -<> and <> respectively. -The additional common special member functions and common member functions are -listed in <> in -<> and -<> respectively. +The [code]#platform# class provides the common reference semantics as defined in +<>. -// Interface of platform class -[source,,linenums] +[source,role=synopsis] ---- include::{header_dir}/platform.h[lines=4..-1] ---- +[[sec:platform-ctors]] +==== Constructors -[[table.constructors.platform]] -.Constructors of the SYCL [code]#platform# class -// Jon: Dims{6.7cm}{8.3cm} -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Constructor @ Description -a@ -[source] +.[apititle]#Default constructor# +[source,role=synopsis,id=api:platform-ctor] ---- platform() ---- - a@ Constructs a SYCL [code]#platform# instance that is a copy of the - [code]#platform# which contains the device returned by - [code]#default_selector_v#. -a@ -[source] +_Effects:_ Constructs a [code]#platform# object that is a copy of the platform +which contains the device returned by [code]#default_selector_v#. + +''' + +.[apititle]#Selector constructor# +[source,role=synopsis,id=api:platform-ctor-selector] ---- -template explicit platform(const DeviceSelector&) +template +explicit platform(const DeviceSelector& selector) ---- - a@ Constructs a SYCL [code]#platform# instance that is a copy of the - [code]#platform# which contains the device returned by the - <> parameter. -|==== +_Constraints:_ The [code]#DeviceSelector# must be a type that satisfies the +requirements of a <> as defined in <>. +_Effects:_ The [code]#selector# is called once for every <> as +described in <>. +Constructs a [code]#platform# object that is a copy of the platform which +contains the device that is selected by [code]#selector#. +''' -[[table.members.platform]] -.Member functions of the SYCL [code]#platform# class -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Member function @ Description -a@ -[source] +[[sec:platform-member-funcs]] +==== Member functions + +.[apidef]#platform::get_backend# +[source,role=synopsis,id=api:platform-get-backend] ---- backend get_backend() const noexcept ---- - a@ Returns a [code]#backend# identifying the <> associated - with this [code]#platform#. -a@ -[source] +_Returns:_ The <> that is associated with this platform. + +''' + +.[apidef]#platform::get_info# +[source,role=synopsis,id=api:platform-get-info] ---- -template typename Param::return_type get_info() const +template +typename Param::return_type get_info() const ---- - a@ Queries this SYCL [code]#platform# 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:_ The [code]#Param# must be an information descriptor for the +platform class. + +Each information descriptor specifies the return value and may also specify +preconditions, exceptions that are thrown, etc. + +''' + +.[apidef]#platform::get_backend_info# +[source,role=synopsis,id=api:platform-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]#platform# 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]#platform#. -a@ -[source] +_Constraints:_ The [code]#Param# must be a backend information descriptor for +the platform 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 platform. + +Each information descriptor specifies the return value and may also specify +preconditions, additional exceptions that are thrown, etc. + +''' + +.[apidef]#platform::has# +[source,role=synopsis,id=api:platform-has] ---- bool has(aspect asp) const ---- - a@ Returns true if all of the SYCL [code]#devices# associated with this - SYCL [code]#platform# have the given <>. Returns [code]#false# if this SYCL [code]#platform# does not - contain any devices. -a@ -[source] +_Returns:_ The value [code]#true# if all of the devices associated with this +platform have the given <>. +Returns the value [code]#false# if this platform does not contain any devices. + +''' + +.[apidef]#platform::has_extension# +[source,role=synopsis,id=api:platform-has-extension] ---- bool has_extension(const std::string& extension) const ---- - a@ Deprecated, use [code]#has()# instead. -Returns [code]#true# if this SYCL [code]#platform# supports the extension queried by the [code]#extension# parameter. A SYCL [code]#platform# can only support an extension if all associated SYCL [code]#devices# support that extension. Returns [code]#false# if this SYCL [code]#platform# does not contain any devices. +Deprecated by SYCL 2020. -a@ -[source] +{note} Use [api]#platform::has# instead. +{endnote} + +_Returns:_ The value [code]#true# if this platform supports the extension +queried by the [code]#extension# parameter. +A platform only supports an extension if all associated devices support that +extension. +Returns [code]#false# if this platform does not contain any devices. + +''' + +.[apidef]#platform::get_devices# +[source,role=synopsis,id=api:platform-get-devices] ---- std::vector -get_devices(info::device_type deviceType = info::device_type::all) const +get_devices(info::device_type type = info::device_type::all) const ---- - a@ Returns a [code]#std::vector# containing all the - <> associated with this SYCL [code]#platform# - which have the device type encapsulated by [code]#deviceType#. -|==== +_Returns:_ A [code]#std::vector# containing all of the <> associated with this platform which have the device type specified by +[code]#type#. +''' +[[sec:platform-static-member-funcs]] +==== Static member functions -[[table.staticmembers.platform]] -.Static member functions of the SYCL [code]#platform# class -[width="100%",options="header",separator="@",cols="65%,35%"] -|==== -@ Static member function @ Description -a@ -[source] +.[apidef]#platform::get_platforms# +[source,role=synopsis,id=api:platform-get-platforms] ---- static std::vector get_platforms() ---- - a@ Returns a [code]#std::vector# containing all SYCL - [code]#platforms# from all <> available in the system. - -|==== +_Returns:_ A [code]#std::vector# containing all of the platforms from all +<> that are known to the SYCL implementation. +''' -==== Platform information descriptors +[[sec:platform-info-descriptors]] +==== Information descriptors -A <> can be queried for information using the [code]#get_info# member -function of the [code]#platform# class, specifying one of the info parameters in -[code]#info::platform#. -The possible values for each info parameter and any restrictions are defined in -the specification of the <> associated with the <>. -All info parameters in [code]#info::platform# are specified in -<> and the synopsis for [code]#info::platform# is described -in <>. +This section describes the information descriptors that can be used as the +[code]#Param# template parameter to [api]#platform::get_info#. +When the description has a _Returns_, _Throws_, etc. paragraph, this indicates +the value returned by or the exceptions thrown by the [api]#platform::get_info# +function. +''' -[[table.platform.info]] -.Platform information descriptors -// Jon: Dims{5cm}{2cm}{7cm} -[width="100%",options="header",separator="@",cols="37%,19%,44%"] -|==== -@ Platform descriptors @ Return type @ Description -a@ -[source] +.[apidef]#info::platform::version# +[source,role=synopsis,id=api:info-platform-version] ---- -info::platform::version +namespace sycl::info::platform { +struct version { + using return_type = std::string; +}; +} // namespace sycl::info::platform ---- - @ [.code]#std::string# - a@ Returns a backend-defined <> version. +_Remarks:_ Template parameter to [api]#platform::get_info#. -a@ -[source] +_Returns:_ An implementation-defined platform version string. + +''' + +.[apidef]#info::platform::name# +[source,role=synopsis,id=api:info-platform-name] ---- -info::platform::name +namespace sycl::info::platform { +struct name { + using return_type = std::string; +}; +} // namespace sycl::info::platform ---- - @ [.code]#std::string# - a@ Returns the name of the <>. +_Remarks:_ Template parameter to [api]#platform::get_info#. -a@ -[source] +_Returns:_ An implementation-defined name for this platform. + +''' + +.[apidef]#info::platform::vendor# +[source,role=synopsis,id=api:info-platform-vendor] ---- -info::platform::vendor +namespace sycl::info::platform { +struct vendor { + using return_type = std::string; +}; +} // namespace sycl::info::platform ---- - @ [.code]#std::string# - a@ Returns the name of the vendor providing the <>. +_Remarks:_ Template parameter to [api]#platform::get_info#. -a@ -[source] +_Returns:_ An implementation-defined name for the vendor providing this +platform. + +''' + +.[apidef]#info::platform::extensions# +[source,role=synopsis,id=api:info-platform-extensions] ---- -info::platform::extensions +namespace sycl::info::platform { +struct extensions { + using return_type = std::vector; +}; +} // namespace sycl::info::platform ---- - @ [.code]#std::vector# - a@ Deprecated, use [code]#device::get_info()# with - [code]#info::device::aspects# instead. +Deprecated by SYCL 2020. -Returns the extensions supported by this [code]#platform#. Returns an empty list if this [code]#platform# does not contain any devices. +{note} Use [code]#device::get_info()# with [code]#info::device::aspects# +instead. +{endnote} -|==== +_Remarks:_ Template parameter to [api]#platform::get_info#. + +_Returns:_ The extensions supported by this platform. +Returns an empty list if this platform does not contain any devices. +''' [[sec:interface.context.class]]