You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[SYCL] Add Level-Zero interop with specification of ownership (#3231)
The Level-Zero backend specified assuming ownership of the native
handles used in the interoperability. There was however request made
that this is not sufficient in all cases, e.g. when some memory was created
outside SYCL RT in some Level-Zero Context, then working with that
memory should always be within the same context. Thus if anyone wanted
to "return" something back from SYCL, then the context should still exist
and be the same.
This patch only does for context, but probably we'd need to deal with other
objects too at some point.
Signed-off-by: Sergey V Maslov [email protected]
Copy file name to clipboardExpand all lines: sycl/doc/extensions/LevelZeroBackend/LevelZeroBackend.md
+33-12Lines changed: 33 additions & 12 deletions
Original file line number
Diff line number
Diff line change
@@ -87,7 +87,7 @@ a SYCL object that encapsulates a corresponding Level-Zero object:
87
87
|-------------|:------------|
88
88
|``` make<platform>(ze_driver_handle_t);```|Constructs a SYCL platform instance from a Level-Zero ```ze_driver_handle_t```.|
89
89
|``` make<device>(const platform &, ze_device_handle_t);```|Constructs a SYCL device instance from a Level-Zero ```ze_device_handle_t```. The platform argument gives a SYCL platform, encapsulating a Level-Zero driver supporting the passed Level-Zero device.|
90
-
|``` make<context>(const vector_class<device> &, ze_context_handle_t);```| Constructs a SYCL context instance from a Level-Zero ```ze_context_handle_t```. The context is created against the devices passed in. There must be at least one device given and all the devices must be from the same SYCL platform and thus from the same Level-Zero driver.|
90
+
|``` make<context>(const vector_class<device> &, ze_context_handle_t, ownership = transfer);```| Constructs a SYCL context instance from a Level-Zero ```ze_context_handle_t```. The context is created against the devices passed in. There must be at least one device given and all the devices must be from the same SYCL platform and thus from the same Level-Zero driver. The ```ownership``` argument specifies if the SYCL runtime should take ownership of the passed native handle. The default behavior is to transfer the ownership to the SYCL runtime. See section 4.4 for details.|
91
91
|``` make<queue>(const context &, ze_command_queue_handle_t);```| Constructs a SYCL queue instance from a Level-Zero ```ze_command_queue_handle_t```. The context argument must be a valid SYCL context encapsulating a Level-Zero context. The queue is attached to the first device in the passed SYCL context.|
92
92
|``` make<program>(const context &, ze_module_handle_t);```| Constructs a SYCL program instance from a Level-Zero ```ze_module_handle_t```. The context argument must be a valid SYCL context encapsulating a Level-Zero context. The Level-Zero module must be fully linked (i.e. not require further linking through [```zeModuleDynamicLink```](https://spec.oneapi.com/level-zero/latest/core/api.html?highlight=zemoduledynamiclink#_CPPv419zeModuleDynamicLink8uint32_tP18ze_module_handle_tP28ze_module_build_log_handle_t)), and thus the SYCL program is created in the "linked" state.|
93
93
@@ -96,23 +96,43 @@ NOTE: We shall consider adding other interoperability as needed, if possible.
96
96
### 4.4 Level-Zero handles' ownership and thread-safety
97
97
98
98
The Level-Zero runtime doesn't do reference-counting of its objects, so it is crucial to adhere to these
99
-
practices of how Level-Zero handles are manged.
99
+
practices of how Level-Zero handles are managed. By default, the ownership is transferred to the SYCL runtime, but
100
+
some interoparability API supports overriding this behavior and keep the ownership in the application.
101
+
Use this enumeration for explicit specification of the ownership:
102
+
``` C++
103
+
namespace sycl {
104
+
namespace level_zero {
105
+
106
+
enum class ownership { transfer, keep };
107
+
108
+
} // namesace level_zero
109
+
} // namespace sycl
110
+
```
100
111
101
-
#### 4.4.1 SYCL runtime takes ownership
112
+
#### 4.4.1 SYCL runtime takes ownership (default)
102
113
103
114
Whenever the application creates a SYCL object from the corresponding Level-Zero handle via one of the ```make<T>()``` functions,
104
-
the SYCL runtime takes ownership of the Level-Zero handle. The application must not use the Level-Zero handle after
105
-
the last host copy of the SYCL object is destroyed (as described in the core SYCL specification under
106
-
"Common reference semantics"), and the application must not destroy the Level-Zero handle itself.
115
+
the SYCL runtime takes ownership of the Level-Zero handle, if no explicit ```ownership::keep``` was specified.
116
+
The application must not use the Level-Zero handle after the last host copy of the SYCL object is destroyed (
117
+
as described in the core SYCL specification under "Common reference semantics"), and the application must not
118
+
destroy the Level-Zero handle itself.
119
+
120
+
#### 4.4.2 Application keeps ownership (explicit)
121
+
122
+
If SYCL object is created with an interoperability API explicitly asking to keep the native handle ownership in the application with
123
+
```ownership::keep``` then the SYCL runtime does not take the ownership and will not destroy the Level-Zero handle at the destruction of the SYCL object.
124
+
The application is responsible for destroying the native handle when it no longer needs it, but it must not destroy the
125
+
handle before the last host copy of the SYCL object is destroyed (as described in the core SYCL specification under
126
+
"Common reference semantics").
107
127
108
-
#### 4.4.2 SYCL runtime assumes ownership
128
+
#### 4.4.3 Obtaining native handle does not change ownership
109
129
110
-
The application may call the ```get_native<T>()``` member function of a SYCL object to retrieve the underlying Level-Zero handle,
111
-
however, the SYCL runtime continues to retain ownership of this handle. The application must not use this handle after
112
-
the last host copy of the SYCL object is destroyed (as described in the core SYCL specification under
113
-
"Common reference semantics"), and the application must not destroy the Level-Zero handle.
130
+
The application may call the ```get_native<T>()``` member function of a SYCL object to retrieve the underlying Level-Zero handle.
131
+
Doing so does not change the ownership of the the Level-Zero handle. Therefore, the application may not use this
132
+
handle after the last host copy of the SYCL object is destroyed (as described in the core SYCL specification under
133
+
"Common reference semantics") unless the SYCL object was created by the application with ```ownership::keep```.
114
134
115
-
#### 4.4.3 Considerations for multi-threaded environment
135
+
#### 4.4.4 Considerations for multi-threaded environment
116
136
117
137
The Level-Zero API is not thread-safe, refer to <https://spec.oneapi.com/level-zero/latest/core/INTRO.html#multithreading-and-concurrency>.
118
138
Applications must make sure that the Level-Zero handles themselves aren't used simultaneously from different threads.
@@ -123,4 +143,5 @@ the application should not attempt further direct use of those handles.
0 commit comments