Correct level of indirection used in KernelSetArgPointer calls.

Also attempt to clarify the wording around this a bit.

Addresses #558

Author: aarongreig

include/ur_api.h

@@ -5023,8 +5023,8 @@ urKernelSetArgPointer(
     ur_kernel_handle_t hKernel,                            ///< [in] handle of the kernel object
     uint32_t argIndex,                                     ///< [in] argument index in range [0, num args - 1]
     const ur_kernel_arg_pointer_properties_t *pProperties, ///< [in][optional] pointer to USM pointer properties.
-    const void *pArgValue                                  ///< [in][optional] USM pointer to memory location holding the argument
-                                                           ///< value. If null then argument value is considered null.
+    const void *pArgValue                                  ///< [in][optional] Pointer obtained by USM allocation or virtual memory
+                                                           ///< mapping operation. If null then argument value is considered null.
 );
 
 ///////////////////////////////////////////////////////////////////////////////

scripts/core/kernel.yml

@@ -339,7 +339,7 @@ params:
       desc: "[in][optional] pointer to USM pointer properties."
     - type: "const void*"
       name: pArgValue
-      desc: "[in][optional] USM pointer to memory location holding the argument value. If null then argument value is considered null."
+      desc: "[in][optional] Pointer obtained by USM allocation or virtual memory mapping operation. If null then argument value is considered null."
 returns:
     - $X_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX
     - $X_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_SIZE

source/adapters/null/ur_nullddi.cpp

@@ -2446,8 +2446,8 @@ __urdlllocal ur_result_t UR_APICALL urKernelSetArgPointer(
     const ur_kernel_arg_pointer_properties_t
         *pProperties, ///< [in][optional] pointer to USM pointer properties.
     const void *
-        pArgValue ///< [in][optional] USM pointer to memory location holding the argument
-                  ///< value. If null then argument value is considered null.
+        pArgValue ///< [in][optional] Pointer obtained by USM allocation or virtual memory
+    ///< mapping operation. If null then argument value is considered null.
     ) try {
     ur_result_t result = UR_RESULT_SUCCESS;
 

source/loader/layers/tracing/ur_trcddi.cpp

@@ -3167,8 +3167,8 @@ __urdlllocal ur_result_t UR_APICALL urKernelSetArgPointer(
     const ur_kernel_arg_pointer_properties_t
         *pProperties, ///< [in][optional] pointer to USM pointer properties.
     const void *
-        pArgValue ///< [in][optional] USM pointer to memory location holding the argument
-                  ///< value. If null then argument value is considered null.
+        pArgValue ///< [in][optional] Pointer obtained by USM allocation or virtual memory
+    ///< mapping operation. If null then argument value is considered null.
 ) {
     auto pfnSetArgPointer = context.urDdiTable.Kernel.pfnSetArgPointer;
 

source/loader/layers/validation/ur_valddi.cpp

@@ -3589,8 +3589,8 @@ __urdlllocal ur_result_t UR_APICALL urKernelSetArgPointer(
     const ur_kernel_arg_pointer_properties_t
         *pProperties, ///< [in][optional] pointer to USM pointer properties.
     const void *
-        pArgValue ///< [in][optional] USM pointer to memory location holding the argument
-                  ///< value. If null then argument value is considered null.
+        pArgValue ///< [in][optional] Pointer obtained by USM allocation or virtual memory
+    ///< mapping operation. If null then argument value is considered null.
 ) {
     auto pfnSetArgPointer = context.urDdiTable.Kernel.pfnSetArgPointer;
 

source/loader/ur_ldrddi.cpp

@@ -3230,8 +3230,8 @@ __urdlllocal ur_result_t UR_APICALL urKernelSetArgPointer(
     const ur_kernel_arg_pointer_properties_t
         *pProperties, ///< [in][optional] pointer to USM pointer properties.
     const void *
-        pArgValue ///< [in][optional] USM pointer to memory location holding the argument
-                  ///< value. If null then argument value is considered null.
+        pArgValue ///< [in][optional] Pointer obtained by USM allocation or virtual memory
+    ///< mapping operation. If null then argument value is considered null.
 ) {
     ur_result_t result = UR_RESULT_SUCCESS;
 

source/loader/ur_libapi.cpp

@@ -3863,8 +3863,8 @@ ur_result_t UR_APICALL urKernelSetArgPointer(
     const ur_kernel_arg_pointer_properties_t
         *pProperties, ///< [in][optional] pointer to USM pointer properties.
     const void *
-        pArgValue ///< [in][optional] USM pointer to memory location holding the argument
-                  ///< value. If null then argument value is considered null.
+        pArgValue ///< [in][optional] Pointer obtained by USM allocation or virtual memory
+    ///< mapping operation. If null then argument value is considered null.
     ) try {
     auto pfnSetArgPointer = ur_lib::context->urDdiTable.Kernel.pfnSetArgPointer;
     if (nullptr == pfnSetArgPointer) {

source/ur_api.cpp

@@ -3284,8 +3284,8 @@ ur_result_t UR_APICALL urKernelSetArgPointer(
     const ur_kernel_arg_pointer_properties_t
         *pProperties, ///< [in][optional] pointer to USM pointer properties.
     const void *
-        pArgValue ///< [in][optional] USM pointer to memory location holding the argument
-                  ///< value. If null then argument value is considered null.
+        pArgValue ///< [in][optional] Pointer obtained by USM allocation or virtual memory
+    ///< mapping operation. If null then argument value is considered null.
 ) {
     ur_result_t result = UR_RESULT_SUCCESS;
     return result;

test/conformance/kernel/urKernelSetArgPointer.cpp

@@ -42,7 +42,7 @@ TEST_P(urKernelSetArgPointerTest, SuccessHost) {
                                   &allocation));
     ASSERT_NE(allocation, nullptr);
 
-    ASSERT_SUCCESS(urKernelSetArgPointer(kernel, 0, nullptr, &allocation));
+    ASSERT_SUCCESS(urKernelSetArgPointer(kernel, 0, nullptr, allocation));
     ASSERT_SUCCESS(
         urKernelSetArgValue(kernel, 1, sizeof(data), nullptr, &data));
     Launch1DRange(array_size);
@@ -60,7 +60,7 @@ TEST_P(urKernelSetArgPointerTest, SuccessDevice) {
                                     allocation_size, &allocation));
     ASSERT_NE(allocation, nullptr);
 
-    ASSERT_SUCCESS(urKernelSetArgPointer(kernel, 0, nullptr, &allocation));
+    ASSERT_SUCCESS(urKernelSetArgPointer(kernel, 0, nullptr, allocation));
     ASSERT_SUCCESS(
         urKernelSetArgValue(kernel, 1, sizeof(data), nullptr, &data));
     Launch1DRange(array_size);
@@ -87,7 +87,7 @@ TEST_P(urKernelSetArgPointerTest, SuccessShared) {
                                     allocation_size, &allocation));
     ASSERT_NE(allocation, nullptr);
 
-    ASSERT_SUCCESS(urKernelSetArgPointer(kernel, 0, nullptr, &allocation));
+    ASSERT_SUCCESS(urKernelSetArgPointer(kernel, 0, nullptr, allocation));
     ASSERT_SUCCESS(
         urKernelSetArgValue(kernel, 1, sizeof(data), nullptr, &data));
     Launch1DRange(array_size);
@@ -138,7 +138,7 @@ UUR_INSTANTIATE_KERNEL_TEST_SUITE_P(urKernelSetArgPointerNegativeTest);
 
 TEST_P(urKernelSetArgPointerNegativeTest, InvalidNullHandleKernel) {
     ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_NULL_HANDLE,
-                     urKernelSetArgPointer(nullptr, 0, nullptr, &allocation));
+                     urKernelSetArgPointer(nullptr, 0, nullptr, allocation));
 }
 
 TEST_P(urKernelSetArgPointerNegativeTest, InvalidKernelArgumentIndex) {
@@ -149,5 +149,5 @@ TEST_P(urKernelSetArgPointerNegativeTest, InvalidKernelArgumentIndex) {
 
     ASSERT_EQ_RESULT(UR_RESULT_ERROR_INVALID_KERNEL_ARGUMENT_INDEX,
                      urKernelSetArgPointer(kernel, num_kernel_args + 1, nullptr,
-                                           &allocation));
+                                           allocation));
 }