[SYCL][DOC] Add documentation for the filter selector #2460
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,85 @@ | ||
| = SYCL Proposals: Filter Selector | ||
| James Brodman <[email protected]> | ||
| 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. | ||
|
|
||
| === 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: | ||
|
There was a problem hiding this comment. Do we define what happens if that syntax is not followed? There was a problem hiding this comment.
Just to expand, syntax being incorrect throws and error, but what about requesting a GPU when there isn't one or requesting gpu:1 when only gpu:0 exists?
Contributor
Author
There was a problem hiding this comment. You should get a runtime error (some sorta device not found one) similar to using gpu_selector when there's no gpu. |
||
|
|
||
| [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". | ||
|
|
||
| .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") | ||
| ---- | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't understand how default_selector fits in here. Should it be filter_selector?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The default selector is used to score devices that match the filter, in case more than one device does.