[SYCL][DOC] Add documentation for the filter selector

sycl/doc/extensions/FilterSelector/FilterSelector.adoc

@@ -0,0 +1,85 @@
+= SYCL Proposals: Filter Selector
+James Brodman <james.brodman@intel.com>
+v0.1
+:source-highlighter: pygments
+:icons: font
+== Introduction
+This document presents an extension on top of the SYCL specification.  The goal of this extension is to provide a new device selector class that allows expressing common but non-trivial requirements for device selection in a simple manner.
+
+== Filter Selector
+
+The filter selector is a new device selector class that accepts a string of one or more filters that refine the set of devices that may be returned when the selector's `select_device` method is invoked.  Devices that match the specified filter(s) are ranked by the `default_selector` to determine which device is ultimately selected.  The `default_selector` is used to prefer an implementation's preferences for one device over another when multiple devices satisfy the provided filters.
+
+=== DSL for Specifying Filters
+
+A string passed to the selector defines one or more filters.  Filters have a certain syntax that must be followed.  A filter is specified as a triple of the form:
+
+[source]
+--
+Backend:DeviceType:RelativeDeviceNumber
+--
+
+Every element of the triple is optional, but a filter must contain at least one component. 
+
+`Backend` specifies the desired backend for the wanted devices. `DeviceType` specifies the type of the desired device.  `RelativeDeviceNumber` refers to the number of device that matches any other requirements, starting from `0`, which means "the first device that matches the requirements".  Incorrect input will result in an a `runtime_error` being thrown.
+
+.Supported Backends
+[width=25%]
+|====
+| Backend
+
+|`cuda`
+|`host`
+| `opencl`
+|`level_zero`
+|====
+
+.Supported Device Types
+[width=25%]
+|====
+| Device Type
+
+| `accelerator`
+| `cpu`
+| `gpu`
+| `host`
+|====
+
+=== Specifying Multiple Filters
+
+Multiple filters may be specified in the string passed to the selector by using `,` to separate additional filters.
+
+[source]
+--
+Backend0:DeviceType0:RelativeDeviceNumber0,Backend1:DeviceType1:RelativeDeviceNumber1,...
+--
+
+== Examples
+
+[source,c++]
+----
+
+// Return a device that uses the opencl backend
+filter_selector("opencl")
+
+// Return a cpu device that uses the opencl backend
+filter_selector("opencl:cpu")
+
+// Return a gpu device
+filter_selector("gpu")
+
+// Return the first device found
+filter_selector("0")
+
+// Return the second opencl gpu found
+filter_selector("opencl:gpu:1")
+
+// Return either a gpu or cpu
+filter_selector("gpu,cpu")
+
+// Return either a cuda gpu or an opencl cpu
+filter_selector("cuda:gpu,opencl:cpu")
+
+// Return either the second level_zero gpu or the host device
+filter_selector("level_zero:gpu:1,host")
+----