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
Copy file name to clipboardExpand all lines: scripts/YaML.md
+2-1
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
+27
Original file line number
Diff line number
Diff line change
@@ -256,6 +256,33 @@ 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 it via
262
+
${x}LoaderConfigSetMockingEnabled.
263
+
264
+
The default fallback behavior for entry points in the mock adapter is to simply
265
+
return ``UR_RESULT_SUCCESS``. For entry points concerning handles, i.e. those
266
+
that create a new handle or modify the reference count of an existing one, a
267
+
dummy handle mechanism is used. This means the adapter will return generic
268
+
handles that track a reference count, and ``Retain``/``Release`` entry points will
269
+
function as expected when used with these handles.
270
+
271
+
The behavior of the mock adapter can be customized by linking the
272
+
``unified-runtime::mock`` library and making use of the object accessed via the
273
+
``mock::getCallbacks()`` helper. Callbacks can be passed into this object to
274
+
run either before or after a given entry point, or they can be set to entirely
275
+
replace the default behavior. Only one callback of each type (before, replace,
276
+
after) can be set per entry point, with subsequent callbacks set in the same
277
+
"slot" overwriting any set previously.
278
+
279
+
The callback signature defined by ``ur_mock_callback_t`` takes a single
280
+
``void *`` parameter. When calling a user callback the adapter will pack the
281
+
entry point's parameters into the appropriate ``_params_t`` struct (e.g.
282
+
``ur_adapter_get_params_t``) and pass a pointer to that struct into the
283
+
callback. This allows parameters to be accessed and modified. The definitions
284
+
for these parameter structs can be found in the main API header.
285
+
259
286
Layers
260
287
---------------------
261
288
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`_).
desc: "The only adapter reported with mock enabled will be the mock adapter."
192
+
details:
193
+
- "The mock adapter will default to returning $X_RESULT_SUCCESS for all entry points. It will also create and correctly reference count dummy handles where appropriate. Its behaviour can be modified by linking the mock library and using the object accessed via mock::getCallbacks()."
194
+
class: $xLoaderConfig
195
+
loader_only: True
196
+
name: "SetMockingEnabled"
197
+
decl: static
198
+
params:
199
+
- type: $x_loader_config_handle_t
200
+
name: hLoaderConfig
201
+
desc: "[in] Handle to config object mocking will be enabled for."
202
+
- type: $x_bool_t
203
+
name: enable
204
+
desc: "[in] Handle to config object the layer will be enabled for."
0 commit comments