Correct level of indirection used in KernelSetArgPointer calls.

Also attempt to clarify the wording around this a bit.

Addresses #558

include/ur_api.h

@@ -4759,8 +4759,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

@@ -340,7 +340,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

@@ -2278,8 +2278,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

@@ -2588,8 +2588,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

@@ -3142,8 +3142,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

@@ -2953,8 +2953,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

@@ -3688,8 +3688,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

@@ -3114,8 +3114,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);
@@ -129,16 +129,16 @@ struct urKernelSetArgPointerNegativeTest : urKernelSetArgPointerTest {
  }
 
  void SetUp() {
+ UUR_RETURN_ON_FATAL_FAILURE(urKernelSetArgPointerTest::SetUp());
  SetUpAllocation();
  ASSERT_NE(allocation, nullptr);
- UUR_RETURN_ON_FATAL_FAILURE(urKernelSetArgPointerTest::SetUp());
  }
 };
 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));
 }