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
This also comes with a new accompanying helper header which allows tests
to override entry points and create their own reference counted dummy
handles.
Copy file name to clipboardExpand all lines: scripts/YaML.md
+2-1Lines changed: 2 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -620,11 +620,12 @@ class ur_name_t(Structure):
620
620
-`out` is used for params that are write-only; if the param is a pointer, then the memory being pointed to is also write-only
621
621
-`in,out` is used for params that are both read and write; typically this is used for pointers to other data structures that contain both read and write params
622
622
-`nocheck` is used to specify that no additional validation checks will be generated.
623
-
+`desc` may include one the following annotations: {`"[optional]"`, `"[range(start,end)]"`, `"[release]"`, `"[typename(typeVarName)]"`, `"[bounds(offset,size)]"`}
623
+
+`desc` may include one the following annotations: {`"[optional]"`, `"[range(start,end)]"`, `"[retain]"`, `"[release]"`, `"[typename(typeVarName)]"`, `"[bounds(offset,size)]"`}
624
624
-`optional` is used for params that are handles or pointers where it is legal for the value to be `nullptr`
625
625
-`range` is used for params that are array pointers to specify the valid range that the is valid to read
626
626
+`start` and `end` must be an ISO-C standard identifier or literal
627
627
+`start` is inclusive and `end` is exclusive
628
+
-`retain` is used for params that are handles or pointers to handles where the function will increment the reference counter associated with the handle(s).
628
629
-`release` is used for params that are handles or pointers to handles where the function will decrement the handle's reference count, potentially leaving it in an invalid state if the reference count reaches zero.
629
630
-`typename` is used to denote the type enum for params that are opaque pointers to values of tagged data types.
630
631
-`bounds` is used for params that are memory objects or USM allocations. It specifies the range within the memory allocation represented by the param that will be accessed by the operation.
Copy file name to clipboardExpand all lines: scripts/core/INTRO.rst
+33Lines changed: 33 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -256,6 +256,37 @@ Currently, UR looks for these adapter libraries:
256
256
257
257
For more information about the usage of mentioned environment variables see `Environment Variables`_ section.
258
258
259
+
Mocking
260
+
---------------------
261
+
A mock UR adapter can be accessed for test purposes by enabling the ``MOCK``
262
+
layer as described below. When the mock layer is enabled, calls to the API will
263
+
still be intercepted by other layers (e.g. validation, tracing), but they will
264
+
stop short of the loader - the call chain will end in either a generic fallback
265
+
behavior defined by the mock layer itself, or a user defined replacement
266
+
callback.
267
+
268
+
The default fallback behavior for entry points in the mock layer is to simply
269
+
return ``UR_RESULT_SUCCESS``. For entry points concerning handles, i.e. those
270
+
that create a new handle or modify the reference count of an existing one, a
271
+
dummy handle mechanism is used. This means the layer will return generic
272
+
handles that track a reference count, and ``Retain``/``Release`` entry points will
273
+
function as expected when used with these handles.
274
+
275
+
During global setup the behavior of the mock layer can be customized by setting
276
+
chain of structs, with each registering a callback with a given entry point in
277
+
the API. Callbacks can be registered to be called ``BEFORE`` or ``AFTER`` the
278
+
generic implementation, or they can be registered to entirely ``REPLACE`` it. A
279
+
given entry point can only have one of each kind of callback associated with
280
+
it, multiple structs with the same function/mode combination will override
281
+
eachother.
282
+
283
+
The callback signature defined by ``${x}_mock_callback_t`` takes a single
284
+
``void *`` parameter. When calling a user callback the layer will pack the
285
+
entry point's parameters into the appropriate ``_params_t`` struct (e.g.
286
+
``ur_adapter_get_params_t``) and pass a pointer to that struct into the
287
+
callback. This allows parameters to be accessed and modified. The definitions
288
+
for these parameter structs can be found in the main API header.
289
+
259
290
Layers
260
291
---------------------
261
292
UR comes with a mechanism that allows various API intercept layers to be enabled, either through the API or with an environment variable (see `Environment Variables`_).
@@ -278,6 +309,8 @@ Layers currently included with the runtime are as follows:
278
309
- Enables the XPTI tracing layer, see Tracing_ for more detail.
- Enables the device-side sanitizer layer, see Sanitizers_ for more detail.
312
+
* - UR_LAYER_MOCK
313
+
- Enables adapter mocking for test purposes. Similar behavior to the null adapter except entry points can be overridden or instrumented with callbacks. See Mocking_ for more detail.
0 commit comments