diff --git a/sycl/doc/extensions/FilterSelector/FilterSelector.adoc b/sycl/doc/extensions/FilterSelector/FilterSelector.adoc new file mode 100644 index 0000000000000..c576581c087a8 --- /dev/null +++ b/sycl/doc/extensions/FilterSelector/FilterSelector.adoc @@ -0,0 +1,85 @@ += SYCL Proposals: Filter Selector +James Brodman +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") +---- \ No newline at end of file