Merge pull request #468 from illuhad/patch-1

Allow platforms to be empty

(cherry picked from commit 35c52d6)

adoc/chapters/architecture.adoc

@@ -174,9 +174,9 @@ text within the specification, the normative text must be taken to be correct.
 [[sec:platformmodel]]
 == The SYCL platform model
 
-The SYCL platform model is based on the OpenCL platform model.
-The model consists of a host connected to one or more heterogeneous devices,
-called <<device,devices>>.
+The SYCL platform model consists of a host connected to one or more heterogeneous devices,
+called <<device,devices>>. <<device,Devices>> are grouped together into one or multiple <<platform, platforms>>.
+An implementation may also expose empty <<platform, platforms>> that do not contain any <<device,devices>>.
 
 A SYCL <<context>> is constructed, either directly by the user or implicitly
 when creating a <<queue>>, to hold all the runtime information required by
@@ -295,7 +295,7 @@ implementation that supports the required features for the application.
 === Platform mixed version support
 
 The SYCL generic programming model exposes a number of <<platform,platforms>>, each of
-them exposing a number of <<device,devices>>. Each <<platform>> is bound
+them either empty or exposing a number of <<device,devices>>. Each <<platform>> is bound
 to a certain <<backend>>. SYCL <<device,devices>> associated with said <<platform>>
 are associated with that <<backend>>.
 
@@ -371,9 +371,12 @@ The resources managed by SYCL are:
   . <<platform,Platforms>>: all features of <<backend-api>>s are implemented by
     platforms. A platform can be viewed as a given vendor's runtime and the
     devices accessible through it. Some devices will only be accessible to
-    one vendor's runtime and hence multiple platforms may be present. SYCL
-    manages the different platforms for the user which are accessible through a
-    [code]#sycl::platform# object.
+    one vendor's runtime and hence multiple platforms may be present. SYCL manages
+    the different platforms for the user which are accessible through a
+    [code]#sycl::platform# object. In some cases, an implementation might also
+    choose to expose empty [code]#sycl::platform# objects, for example if 
+    a vendor's runtime is available, but no devices supported by that runtime are
+    available in the system.
   . <<context,Contexts>>: any <<backend>> resource that is acquired by the user is
     attached to a context. A context contains a collection of devices that
     the host can use and manages memory objects that can be shared between
@@ -382,7 +385,7 @@ The resources managed by SYCL are:
     mechanism. A given context can only wrap devices owned by a single
     platform. A context is exposed to the user with a
     [code]#sycl::context# object.
-  . <<device,Devices>>: platforms provide one or more devices for executing SYCL
+  . <<device,Devices>>: platforms may provide devices for executing SYCL
     kernels. In SYCL, a device is accessible through a
     [code]#sycl::device# object.
   . <<kernel,Kernels>>: the SYCL functions that run on SYCL devices are defined

adoc/chapters/programming_interface.adoc

@@ -1030,8 +1030,9 @@ 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 <<backend>>.
 
-A SYCL [code]#platform# is also associated with one or more SYCL
-[code]#devices# associated with the same <<backend>>.
+A SYCL [code]#platform# is also associated with any number of SYCL
+[code]#devices# associated with the same <<backend>>. A platform may
+contain no devices.
 
 All member functions of the [code]#platform# class are synchronous and
 errors are handled by throwing synchronous SYCL exceptions.
@@ -1139,7 +1140,8 @@ a@
 bool has(aspect asp) const
 ----
    a@ Returns true if all of the SYCL [code]#devices# associated with this
-      SYCL [code]#platform# have the given <<aspect>>.
+      SYCL [code]#platform# have the given <<aspect>>. Returns [code]#false# if this SYCL [code]#platform# does not
+      contain any devices.
 
 a@
 [source]
@@ -1148,7 +1150,7 @@ bool has_extension(const std::string& extension) const
 ----
    a@ Deprecated, use [code]#has()# instead.
 
-Returns 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]#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.
 
 a@
 [source]
@@ -1236,7 +1238,7 @@ info::platform::extensions
    a@ Deprecated, use [code]#device::get_info()# with
       [code]#info::device::aspects# instead.
 
-Returns the extensions supported by the <<platform>>.
+Returns the extensions supported by this [code]#platform#. Returns an empty list if this [code]#platform# does not contain any devices.
 
 |====