Skip to content

Commit 74cceed

Browse files
aarongreigaarongreig
committed
Rework null adapter into mock adapter
This also comes with a new accompanying helper header which allows tests to override entry points and create their own reference counted dummy handles.
1 parent 33eb5ea commit 74cceed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+6860
-1897
lines changed

‎include/ur_api.h

+67-28
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,7 @@ typedef enum ur_function_t {
225225
UR_FUNCTION_ENQUEUE_TIMESTAMP_RECORDING_EXP = 223, ///< Enumerator for ::urEnqueueTimestampRecordingExp
226226
UR_FUNCTION_ENQUEUE_KERNEL_LAUNCH_CUSTOM_EXP = 224, ///< Enumerator for ::urEnqueueKernelLaunchCustomExp
227227
UR_FUNCTION_KERNEL_GET_SUGGESTED_LOCAL_WORK_SIZE = 225, ///< Enumerator for ::urKernelGetSuggestedLocalWorkSize
228+
UR_FUNCTION_LOADER_CONFIG_SET_MOCKING_ENABLED = 231, ///< Enumerator for ::urLoaderConfigSetMockingEnabled
228229
/// @cond
229230
UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
230231
/// @endcond
@@ -598,7 +599,7 @@ urLoaderConfigCreate(
598599
/// + `NULL == hLoaderConfig`
599600
UR_APIEXPORT ur_result_t UR_APICALL
600601
urLoaderConfigRetain(
601-
ur_loader_config_handle_t hLoaderConfig ///< [in] loader config handle to retain
602+
ur_loader_config_handle_t hLoaderConfig ///< [in][retain] loader config handle to retain
602603
);
603604

604605
///////////////////////////////////////////////////////////////////////////////
@@ -619,7 +620,7 @@ urLoaderConfigRetain(
619620
/// + `NULL == hLoaderConfig`
620621
UR_APIEXPORT ur_result_t UR_APICALL
621622
urLoaderConfigRelease(
622-
ur_loader_config_handle_t hLoaderConfig ///< [in] config handle to release
623+
ur_loader_config_handle_t hLoaderConfig ///< [in][release] config handle to release
623624
);
624625

625626
///////////////////////////////////////////////////////////////////////////////
@@ -739,6 +740,35 @@ urLoaderConfigSetCodeLocationCallback(
739740
void *pUserData ///< [in][out][optional] pointer to data to be passed to callback.
740741
);
741742

743+
///////////////////////////////////////////////////////////////////////////////
744+
/// @brief Callback to replace or instrument generic mock functionality in the
745+
/// mock adapter.
746+
typedef ur_result_t (*ur_mock_callback_t)(
747+
void *pParams ///< [in][out] Pointer to the appropriate param struct for the function
748+
);
749+
750+
///////////////////////////////////////////////////////////////////////////////
751+
/// @brief The only adapter reported with mock enabled will be the mock adapter.
752+
///
753+
/// @details
754+
/// - The mock adapter will default to returning ::UR_RESULT_SUCCESS for all
755+
/// entry points. It will also create and correctly reference count dummy
756+
/// handles where appropriate. Its behaviour can be modified by linking
757+
/// the ::ur_mock_headers library and using the callbacks object.
758+
///
759+
/// @returns
760+
/// - ::UR_RESULT_SUCCESS
761+
/// - ::UR_RESULT_ERROR_UNINITIALIZED
762+
/// - ::UR_RESULT_ERROR_DEVICE_LOST
763+
/// - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
764+
/// - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
765+
/// + `NULL == hLoaderConfig`
766+
UR_APIEXPORT ur_result_t UR_APICALL
767+
urLoaderConfigSetMockingEnabled(
768+
ur_loader_config_handle_t hLoaderConfig, ///< [in] Handle to config object mocking will be enabled for.
769+
ur_bool_t enable ///< [in] Handle to config object the layer will be enabled for.
770+
);
771+
742772
///////////////////////////////////////////////////////////////////////////////
743773
/// @brief Initialize the 'oneAPI' loader
744774
///
@@ -842,7 +872,7 @@ urAdapterGet(
842872
/// + `NULL == hAdapter`
843873
UR_APIEXPORT ur_result_t UR_APICALL
844874
urAdapterRelease(
845-
ur_adapter_handle_t hAdapter ///< [in] Adapter handle to release
875+
ur_adapter_handle_t hAdapter ///< [in][release] Adapter handle to release
846876
);
847877

848878
///////////////////////////////////////////////////////////////////////////////
@@ -860,7 +890,7 @@ urAdapterRelease(
860890
/// + `NULL == hAdapter`
861891
UR_APIEXPORT ur_result_t UR_APICALL
862892
urAdapterRetain(
863-
ur_adapter_handle_t hAdapter ///< [in] Adapter handle to retain
893+
ur_adapter_handle_t hAdapter ///< [in][retain] Adapter handle to retain
864894
);
865895

866896
///////////////////////////////////////////////////////////////////////////////
@@ -1727,7 +1757,7 @@ urDeviceGetInfo(
17271757
/// + `NULL == hDevice`
17281758
UR_APIEXPORT ur_result_t UR_APICALL
17291759
urDeviceRetain(
1730-
ur_device_handle_t hDevice ///< [in] handle of the device to get a reference of.
1760+
ur_device_handle_t hDevice ///< [in][retain] handle of the device to get a reference of.
17311761
);
17321762

17331763
///////////////////////////////////////////////////////////////////////////////
@@ -1755,7 +1785,7 @@ urDeviceRetain(
17551785
/// + `NULL == hDevice`
17561786
UR_APIEXPORT ur_result_t UR_APICALL
17571787
urDeviceRelease(
1758-
ur_device_handle_t hDevice ///< [in] handle of the device to release.
1788+
ur_device_handle_t hDevice ///< [in][release] handle of the device to release.
17591789
);
17601790

17611791
///////////////////////////////////////////////////////////////////////////////
@@ -2208,7 +2238,7 @@ urContextCreate(
22082238
/// + `NULL == hContext`
22092239
UR_APIEXPORT ur_result_t UR_APICALL
22102240
urContextRetain(
2211-
ur_context_handle_t hContext ///< [in] handle of the context to get a reference of.
2241+
ur_context_handle_t hContext ///< [in][retain] handle of the context to get a reference of.
22122242
);
22132243

22142244
///////////////////////////////////////////////////////////////////////////////
@@ -2262,7 +2292,7 @@ typedef enum ur_context_info_t {
22622292
/// + `NULL == hContext`
22632293
UR_APIEXPORT ur_result_t UR_APICALL
22642294
urContextRelease(
2265-
ur_context_handle_t hContext ///< [in] handle of the context to release.
2295+
ur_context_handle_t hContext ///< [in][release] handle of the context to release.
22662296
);
22672297

22682298
///////////////////////////////////////////////////////////////////////////////
@@ -2726,7 +2756,7 @@ urMemBufferCreate(
27262756
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
27272757
UR_APIEXPORT ur_result_t UR_APICALL
27282758
urMemRetain(
2729-
ur_mem_handle_t hMem ///< [in] handle of the memory object to get access
2759+
ur_mem_handle_t hMem ///< [in][retain] handle of the memory object to get access
27302760
);
27312761

27322762
///////////////////////////////////////////////////////////////////////////////
@@ -2748,7 +2778,7 @@ urMemRetain(
27482778
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
27492779
UR_APIEXPORT ur_result_t UR_APICALL
27502780
urMemRelease(
2751-
ur_mem_handle_t hMem ///< [in] handle of the memory object to release
2781+
ur_mem_handle_t hMem ///< [in][release] handle of the memory object to release
27522782
);
27532783

27542784
///////////////////////////////////////////////////////////////////////////////
@@ -3114,7 +3144,7 @@ urSamplerCreate(
31143144
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
31153145
UR_APIEXPORT ur_result_t UR_APICALL
31163146
urSamplerRetain(
3117-
ur_sampler_handle_t hSampler ///< [in] handle of the sampler object to get access
3147+
ur_sampler_handle_t hSampler ///< [in][retain] handle of the sampler object to get access
31183148
);
31193149

31203150
///////////////////////////////////////////////////////////////////////////////
@@ -3137,7 +3167,7 @@ urSamplerRetain(
31373167
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
31383168
UR_APIEXPORT ur_result_t UR_APICALL
31393169
urSamplerRelease(
3140-
ur_sampler_handle_t hSampler ///< [in] handle of the sampler object to release
3170+
ur_sampler_handle_t hSampler ///< [in][release] handle of the sampler object to release
31413171
);
31423172

31433173
///////////////////////////////////////////////////////////////////////////////
@@ -3674,7 +3704,7 @@ urUSMPoolCreate(
36743704
/// + `NULL == pPool`
36753705
UR_APIEXPORT ur_result_t UR_APICALL
36763706
urUSMPoolRetain(
3677-
ur_usm_pool_handle_t pPool ///< [in] pointer to USM memory pool
3707+
ur_usm_pool_handle_t pPool ///< [in][retain] pointer to USM memory pool
36783708
);
36793709

36803710
///////////////////////////////////////////////////////////////////////////////
@@ -3696,7 +3726,7 @@ urUSMPoolRetain(
36963726
/// + `NULL == pPool`
36973727
UR_APIEXPORT ur_result_t UR_APICALL
36983728
urUSMPoolRelease(
3699-
ur_usm_pool_handle_t pPool ///< [in] pointer to USM memory pool
3729+
ur_usm_pool_handle_t pPool ///< [in][release] pointer to USM memory pool
37003730
);
37013731

37023732
///////////////////////////////////////////////////////////////////////////////
@@ -4030,7 +4060,7 @@ urPhysicalMemCreate(
40304060
/// + `NULL == hPhysicalMem`
40314061
UR_APIEXPORT ur_result_t UR_APICALL
40324062
urPhysicalMemRetain(
4033-
ur_physical_mem_handle_t hPhysicalMem ///< [in] handle of the physical memory object to retain.
4063+
ur_physical_mem_handle_t hPhysicalMem ///< [in][retain] handle of the physical memory object to retain.
40344064
);
40354065

40364066
///////////////////////////////////////////////////////////////////////////////
@@ -4045,7 +4075,7 @@ urPhysicalMemRetain(
40454075
/// + `NULL == hPhysicalMem`
40464076
UR_APIEXPORT ur_result_t UR_APICALL
40474077
urPhysicalMemRelease(
4048-
ur_physical_mem_handle_t hPhysicalMem ///< [in] handle of the physical memory object to release.
4078+
ur_physical_mem_handle_t hPhysicalMem ///< [in][release] handle of the physical memory object to release.
40494079
);
40504080

40514081
#if !defined(__GNUC__)
@@ -4313,7 +4343,7 @@ urProgramLink(
43134343
/// + `NULL == hProgram`
43144344
UR_APIEXPORT ur_result_t UR_APICALL
43154345
urProgramRetain(
4316-
ur_program_handle_t hProgram ///< [in] handle for the Program to retain
4346+
ur_program_handle_t hProgram ///< [in][retain] handle for the Program to retain
43174347
);
43184348

43194349
///////////////////////////////////////////////////////////////////////////////
@@ -4338,7 +4368,7 @@ urProgramRetain(
43384368
/// + `NULL == hProgram`
43394369
UR_APIEXPORT ur_result_t UR_APICALL
43404370
urProgramRelease(
4341-
ur_program_handle_t hProgram ///< [in] handle for the Program to release
4371+
ur_program_handle_t hProgram ///< [in][release] handle for the Program to release
43424372
);
43434373

43444374
///////////////////////////////////////////////////////////////////////////////
@@ -4960,7 +4990,7 @@ urKernelGetSubGroupInfo(
49604990
/// + `NULL == hKernel`
49614991
UR_APIEXPORT ur_result_t UR_APICALL
49624992
urKernelRetain(
4963-
ur_kernel_handle_t hKernel ///< [in] handle for the Kernel to retain
4993+
ur_kernel_handle_t hKernel ///< [in][retain] handle for the Kernel to retain
49644994
);
49654995

49664996
///////////////////////////////////////////////////////////////////////////////
@@ -4985,7 +5015,7 @@ urKernelRetain(
49855015
/// + `NULL == hKernel`
49865016
UR_APIEXPORT ur_result_t UR_APICALL
49875017
urKernelRelease(
4988-
ur_kernel_handle_t hKernel ///< [in] handle for the Kernel to release
5018+
ur_kernel_handle_t hKernel ///< [in][release] handle for the Kernel to release
49895019
);
49905020

49915021
///////////////////////////////////////////////////////////////////////////////
@@ -5467,7 +5497,7 @@ urQueueCreate(
54675497
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
54685498
UR_APIEXPORT ur_result_t UR_APICALL
54695499
urQueueRetain(
5470-
ur_queue_handle_t hQueue ///< [in] handle of the queue object to get access
5500+
ur_queue_handle_t hQueue ///< [in][retain] handle of the queue object to get access
54715501
);
54725502

54735503
///////////////////////////////////////////////////////////////////////////////
@@ -5496,7 +5526,7 @@ urQueueRetain(
54965526
/// - ::UR_RESULT_ERROR_OUT_OF_RESOURCES
54975527
UR_APIEXPORT ur_result_t UR_APICALL
54985528
urQueueRelease(
5499-
ur_queue_handle_t hQueue ///< [in] handle of the queue object to release
5529+
ur_queue_handle_t hQueue ///< [in][release] handle of the queue object to release
55005530
);
55015531

55025532
///////////////////////////////////////////////////////////////////////////////
@@ -5861,7 +5891,7 @@ urEventWait(
58615891
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
58625892
UR_APIEXPORT ur_result_t UR_APICALL
58635893
urEventRetain(
5864-
ur_event_handle_t hEvent ///< [in] handle of the event object
5894+
ur_event_handle_t hEvent ///< [in][retain] handle of the event object
58655895
);
58665896

58675897
///////////////////////////////////////////////////////////////////////////////
@@ -5884,7 +5914,7 @@ urEventRetain(
58845914
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
58855915
UR_APIEXPORT ur_result_t UR_APICALL
58865916
urEventRelease(
5887-
ur_event_handle_t hEvent ///< [in] handle of the event object
5917+
ur_event_handle_t hEvent ///< [in][release] handle of the event object
58885918
);
58895919

58905920
///////////////////////////////////////////////////////////////////////////////
@@ -7893,7 +7923,7 @@ UR_APIEXPORT ur_result_t UR_APICALL
78937923
urBindlessImagesReleaseInteropExp(
78947924
ur_context_handle_t hContext, ///< [in] handle of the context object
78957925
ur_device_handle_t hDevice, ///< [in] handle of the device object
7896-
ur_exp_interop_mem_handle_t hInteropMem ///< [in] handle of interop memory to be freed
7926+
ur_exp_interop_mem_handle_t hInteropMem ///< [in][release] handle of interop memory to be freed
78977927
);
78987928

78997929
///////////////////////////////////////////////////////////////////////////////
@@ -8191,7 +8221,7 @@ urCommandBufferCreateExp(
81918221
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
81928222
UR_APIEXPORT ur_result_t UR_APICALL
81938223
urCommandBufferRetainExp(
8194-
ur_exp_command_buffer_handle_t hCommandBuffer ///< [in] Handle of the command-buffer object.
8224+
ur_exp_command_buffer_handle_t hCommandBuffer ///< [in][retain] Handle of the command-buffer object.
81958225
);
81968226

81978227
///////////////////////////////////////////////////////////////////////////////
@@ -8210,7 +8240,7 @@ urCommandBufferRetainExp(
82108240
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
82118241
UR_APIEXPORT ur_result_t UR_APICALL
82128242
urCommandBufferReleaseExp(
8213-
ur_exp_command_buffer_handle_t hCommandBuffer ///< [in] Handle of the command-buffer object.
8243+
ur_exp_command_buffer_handle_t hCommandBuffer ///< [in][release] Handle of the command-buffer object.
82148244
);
82158245

82168246
///////////////////////////////////////////////////////////////////////////////
@@ -8758,7 +8788,7 @@ urCommandBufferRetainCommandExp(
87588788
/// - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
87598789
UR_APIEXPORT ur_result_t UR_APICALL
87608790
urCommandBufferReleaseCommandExp(
8761-
ur_exp_command_buffer_command_handle_t hCommand ///< [in] Handle of the command-buffer command.
8791+
ur_exp_command_buffer_command_handle_t hCommand ///< [in][release] Handle of the command-buffer command.
87628792
);
87638793

87648794
///////////////////////////////////////////////////////////////////////////////
@@ -9519,6 +9549,15 @@ typedef struct ur_loader_config_set_code_location_callback_params_t {
95199549
void **ppUserData;
95209550
} ur_loader_config_set_code_location_callback_params_t;
95219551

9552+
///////////////////////////////////////////////////////////////////////////////
9553+
/// @brief Function parameters for urLoaderConfigSetMockingEnabled
9554+
/// @details Each entry is a pointer to the parameter passed to the function;
9555+
/// allowing the callback the ability to modify the parameter's value
9556+
typedef struct ur_loader_config_set_mocking_enabled_params_t {
9557+
ur_loader_config_handle_t *phLoaderConfig;
9558+
ur_bool_t *penable;
9559+
} ur_loader_config_set_mocking_enabled_params_t;
9560+
95229561
///////////////////////////////////////////////////////////////////////////////
95239562
/// @brief Function parameters for urPlatformGet
95249563
/// @details Each entry is a pointer to the parameter passed to the function;

‎include/ur_print.h

+8
Original file line numberDiff line numberDiff line change
@@ -1074,6 +1074,14 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintLoaderConfigEnableLayerParams(const s
10741074
/// - `buff_size < out_size`
10751075
UR_APIEXPORT ur_result_t UR_APICALL urPrintLoaderConfigSetCodeLocationCallbackParams(const struct ur_loader_config_set_code_location_callback_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
10761076

1077+
///////////////////////////////////////////////////////////////////////////////
1078+
/// @brief Print ur_loader_config_set_mocking_enabled_params_t struct
1079+
/// @returns
1080+
/// - ::UR_RESULT_SUCCESS
1081+
/// - ::UR_RESULT_ERROR_INVALID_SIZE
1082+
/// - `buff_size < out_size`
1083+
UR_APIEXPORT ur_result_t UR_APICALL urPrintLoaderConfigSetMockingEnabledParams(const struct ur_loader_config_set_mocking_enabled_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
1084+
10771085
///////////////////////////////////////////////////////////////////////////////
10781086
/// @brief Print ur_platform_get_params_t struct
10791087
/// @returns

‎include/ur_print.hpp

+25
Original file line numberDiff line numberDiff line change
@@ -932,6 +932,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
932932
case UR_FUNCTION_KERNEL_GET_SUGGESTED_LOCAL_WORK_SIZE:
933933
os << "UR_FUNCTION_KERNEL_GET_SUGGESTED_LOCAL_WORK_SIZE";
934934
break;
935+
case UR_FUNCTION_LOADER_CONFIG_SET_MOCKING_ENABLED:
936+
os << "UR_FUNCTION_LOADER_CONFIG_SET_MOCKING_ENABLED";
937+
break;
935938
default:
936939
os << "unknown enumerator";
937940
break;
@@ -10101,6 +10104,25 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
1010110104
return os;
1010210105
}
1010310106

10107+
///////////////////////////////////////////////////////////////////////////////
10108+
/// @brief Print operator for the ur_loader_config_set_mocking_enabled_params_t type
10109+
/// @returns
10110+
/// std::ostream &
10111+
inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_loader_config_set_mocking_enabled_params_t *params) {
10112+
10113+
os << ".hLoaderConfig = ";
10114+
10115+
ur::details::printPtr(os,
10116+
*(params->phLoaderConfig));
10117+
10118+
os << ", ";
10119+
os << ".enable = ";
10120+
10121+
os << *(params->penable);
10122+
10123+
return os;
10124+
}
10125+
1010410126
///////////////////////////////////////////////////////////////////////////////
1010510127
/// @brief Print operator for the ur_platform_get_params_t type
1010610128
/// @returns
@@ -17048,6 +17070,9 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os, ur_function_
1704817070
case UR_FUNCTION_LOADER_CONFIG_SET_CODE_LOCATION_CALLBACK: {
1704917071
os << (const struct ur_loader_config_set_code_location_callback_params_t *)params;
1705017072
} break;
17073+
case UR_FUNCTION_LOADER_CONFIG_SET_MOCKING_ENABLED: {
17074+
os << (const struct ur_loader_config_set_mocking_enabled_params_t *)params;
17075+
} break;
1705117076
case UR_FUNCTION_PLATFORM_GET: {
1705217077
os << (const struct ur_platform_get_params_t *)params;
1705317078
} break;

‎scripts/YaML.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -620,11 +620,12 @@ class ur_name_t(Structure):
620620
- `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
621621
- `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
622622
- `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)]"`}
624624
- `optional` is used for params that are handles or pointers where it is legal for the value to be `nullptr`
625625
- `range` is used for params that are array pointers to specify the valid range that the is valid to read
626626
+ `start` and `end` must be an ISO-C standard identifier or literal
627627
+ `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)
628629
- `release` is used for params that are handles or pointers to handles where the function will destroy any backing memory associated with the handle(s)
629630
- `typename` is used to denote the type enum for params that are opaque pointers to values of tagged data types.
630631
- `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.

0 commit comments

Comments
 (0)