From 97b30c46dad96d127fb6e014d1d197ef559114fc Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 23 May 2024 18:22:43 -0400 Subject: [PATCH 1/6] Add "etc." to reflow exclusion list --- adoc/scripts/reflow.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/scripts/reflow.py b/adoc/scripts/reflow.py index 5f3407e0..748c4862 100755 --- a/adoc/scripts/reflow.py +++ b/adoc/scripts/reflow.py @@ -53,7 +53,7 @@ # A single letter followed by a period, typically a middle initial. endInitial = re.compile(r'^[A-Z]\.$') # An abbreviation, which does not (usually) end a line. -endAbbrev = re.compile(r'(e\.g|i\.e|c\.f|\bvs\b|\bco\b|\bltd\b|\bch\b)\.$', re.IGNORECASE) +endAbbrev = re.compile(r'(e\.g|i\.e|c\.f|\bvs\b|\bco\b|\bltd\b|\bch\b|\betc)\.$', re.IGNORECASE) # Explicit Valid Usage list item with one or more leading asterisks # The re.DOTALL is needed to prevent vuPat.search() from stripping From 89cd50c5c65606a9f5a933a7ec192e59ab56f7fc Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 23 May 2024 18:20:55 -0400 Subject: [PATCH 2/6] 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 | 296 ++++++++++++--------- 2 files changed, 164 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..cdc35548 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,237 @@ 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]] From 576f2741a0568b45b0543d24125e99e7dd1ec8a0 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Tue, 25 Jun 2024 17:44:19 -0400 Subject: [PATCH 3/6] Consistent parameter name for device type Use the same formal parameter name `type` for all the `get_devices` member functions. --- adoc/chapters/programming_interface.adoc | 4 ++-- adoc/headers/device.h | 2 +- adoc/headers/platform.h | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index cdc35548..a7075ece 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -1719,12 +1719,12 @@ a@ [source] ---- static std::vector -get_devices(info::device_type deviceType = info::device_type::all) +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]#deviceType#. + [code]#type#. |==== diff --git a/adoc/headers/device.h b/adoc/headers/device.h index 7d23ffd2..bfc66ce9 100644 --- a/adoc/headers/device.h +++ b/adoc/headers/device.h @@ -47,6 +47,6 @@ class device { create_sub_devices(info::partition_affinity_domain affinityDomain) const; static std::vector - get_devices(info::device_type deviceType = info::device_type::all); + get_devices(info::device_type type = info::device_type::all); }; } // namespace sycl diff --git a/adoc/headers/platform.h b/adoc/headers/platform.h index f28f1445..64609d35 100644 --- a/adoc/headers/platform.h +++ b/adoc/headers/platform.h @@ -14,7 +14,7 @@ class platform { backend get_backend() const noexcept; std::vector - get_devices(info::device_type = info::device_type::all) const; + get_devices(info::device_type type = info::device_type::all) const; template typename Param::return_type get_info() const; From 1b1bde486d535fe9d211b1c82d05ec6e4b5fe80a Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Tue, 25 Jun 2024 17:59:24 -0400 Subject: [PATCH 4/6] Device selector might be called more than once The description of device selectors in the "Device selection" section does not say that a selector is called exactly once for each root device. Change the wording of the `platform` selector constructor to be consistent with this wording, leaving the number of times it is called ambiguous. We might want to reconsider this, though. Why wouldn't we want to require the selector to be called exactly once? --- adoc/chapters/programming_interface.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index a7075ece..2bdae493 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -1001,8 +1001,8 @@ explicit platform(const DeviceSelector& selector) _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 <>. +_Effects:_ The [code]#selector# is called 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#. From c1780c506780b44f6b85cf3a83d2b589ef2a603d Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 25 Jul 2024 10:38:46 -0400 Subject: [PATCH 5/6] "get_platforms" returns available platforms Restore the wording that `get_platforms` returns "available" platforms. --- adoc/chapters/programming_interface.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index 4c1a88a7..d1a101a0 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -1109,7 +1109,7 @@ static std::vector get_platforms() ---- _Returns:_ A [code]#std::vector# containing all of the platforms from all -<> that are known to the SYCL implementation. +<> that are available in the system. ''' From 6915b81636ef42e0333f24aff19c08dfd62e136e Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Thu, 25 Jul 2024 16:05:17 -0400 Subject: [PATCH 6/6] Add reference to platform info descriptors Add a link from `platform::get_info` to the section defining the platform information descriptors. --- adoc/chapters/programming_interface.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/adoc/chapters/programming_interface.adoc b/adoc/chapters/programming_interface.adoc index d1a101a0..01c2f369 100644 --- a/adoc/chapters/programming_interface.adoc +++ b/adoc/chapters/programming_interface.adoc @@ -1033,6 +1033,8 @@ platform class. Each information descriptor specifies the return value and may also specify preconditions, exceptions that are thrown, etc. +See <> for the platform information descriptors +that are defined by the <>. '''