Merge pull request #1212 from aarongreig/aaron/specMotivatedRefactors

Batch adapter changes: spec motivated refactors

Author: kbenzie

include/ur_api.h

@@ -481,7 +481,8 @@ typedef enum ur_result_t {
     UR_RESULT_ERROR_UNSUPPORTED_IMAGE_FORMAT = 55,                            ///< [Validation] image format is not supported by the device
     UR_RESULT_ERROR_INVALID_NATIVE_BINARY = 56,                               ///< [Validation] native binary is not supported by the device
     UR_RESULT_ERROR_INVALID_GLOBAL_NAME = 57,                                 ///< [Validation] global variable is not found in the program
-    UR_RESULT_ERROR_INVALID_FUNCTION_NAME = 58,                               ///< [Validation] function name is not found in the program
+    UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE = 58,                      ///< [Validation] function name is in the program but its address could not
+                                                                              ///< be determined
     UR_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION = 59,                        ///< [Validation] group size dimension is not valid for the kernel or
                                                                               ///< device
     UR_RESULT_ERROR_INVALID_GLOBAL_WIDTH_DIMENSION = 60,                      ///< [Validation] global width dimension is not valid for the kernel or
@@ -1597,6 +1598,9 @@ typedef enum ur_device_info_t {
                                                                      ///< this composite device.
     UR_DEVICE_INFO_COMPOSITE_DEVICE = 117,                           ///< [::ur_device_handle_t] The composite device containing this component
                                                                      ///< device.
+    UR_DEVICE_INFO_GLOBAL_VARIABLE_SUPPORT = 118,                    ///< [::ur_bool_t] return true if the device supports the
+                                                                     ///< `EnqueueDeviceGlobalVariableWrite` and
+                                                                     ///< `EnqueueDeviceGlobalVariableRead` entry points.
     UR_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP = 0x1000,              ///< [::ur_bool_t] Returns true if the device supports the use of
                                                                      ///< command-buffers.
     UR_DEVICE_INFO_COMMAND_BUFFER_UPDATE_SUPPORT_EXP = 0x1001,       ///< [::ur_bool_t] Returns true if the device supports updating the kernel
@@ -2556,8 +2560,8 @@ typedef struct ur_image_desc_t {
     size_t arraySize;          ///< [in] image array size
     size_t rowPitch;           ///< [in] image row pitch
     size_t slicePitch;         ///< [in] image slice pitch
-    uint32_t numMipLevel;      ///< [in] number of MIP levels
-    uint32_t numSamples;       ///< [in] number of samples
+    uint32_t numMipLevel;      ///< [in] number of MIP levels, must be `0`
+    uint32_t numSamples;       ///< [in] number of samples, must be `0`
 
 } ur_image_desc_t;
 
@@ -2601,6 +2605,10 @@ typedef struct ur_image_desc_t {
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
 ///     - ::UR_RESULT_ERROR_INVALID_IMAGE_FORMAT_DESCRIPTOR
 ///         + `pImageDesc && UR_MEM_TYPE_IMAGE1D_ARRAY < pImageDesc->type`
+///         + `pImageDesc && pImageDesc->numMipLevel != 0`
+///         + `pImageDesc && pImageDesc->numSamples != 0`
+///         + `pImageDesc && pImageDesc->rowPitch != 0 && pHost == nullptr`
+///         + `pImageDesc && pImageDesc->slicePitch != 0 && pHost == nullptr`
 ///     - ::UR_RESULT_ERROR_INVALID_IMAGE_SIZE
 ///     - ::UR_RESULT_ERROR_INVALID_OPERATION
 ///     - ::UR_RESULT_ERROR_INVALID_HOST_PTR
@@ -4355,8 +4363,8 @@ urProgramRelease(
 /// @details
 ///     - Retrieves a pointer to the functions with the given name and defined
 ///       in the given program.
-///     - ::UR_RESULT_ERROR_INVALID_FUNCTION_NAME is returned if the function
-///       can not be obtained.
+///     - ::UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE is returned if the
+///       function can not be obtained.
 ///     - The application may call this function from simultaneous threads for
 ///       the same device.
 ///     - The implementation of this function should be thread-safe.
@@ -4376,6 +4384,10 @@ urProgramRelease(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pFunctionName`
 ///         + `NULL == ppFunctionPointer`
+///     - ::UR_RESULT_ERROR_INVALID_KERNEL_NAME
+///         + If `pFunctionName` couldn't be found in `hProgram`.
+///     - ::UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE
+///         + If `pFunctionName` could be located, but its address couldn't be retrieved.
 UR_APIEXPORT ur_result_t UR_APICALL
 urProgramGetFunctionPointer(
     ur_device_handle_t hDevice,   ///< [in] handle of the device to retrieve pointer for.
@@ -4777,7 +4789,7 @@ urKernelSetArgLocal(
 /// @brief Get Kernel object information
 typedef enum ur_kernel_info_t {
     UR_KERNEL_INFO_FUNCTION_NAME = 0,   ///< [char[]] Return null-terminated kernel function name.
-    UR_KERNEL_INFO_NUM_ARGS = 1,        ///< [size_t] Return Kernel number of arguments.
+    UR_KERNEL_INFO_NUM_ARGS = 1,        ///< [uint32_t] Return Kernel number of arguments.
     UR_KERNEL_INFO_REFERENCE_COUNT = 2, ///< [uint32_t] Reference count of the kernel object.
                                         ///< The reference count returned should be considered immediately stale.
                                         ///< It is unsuitable for general use in applications. This feature is

include/ur_print.hpp

@@ -1541,8 +1541,8 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_result_t value) {
     case UR_RESULT_ERROR_INVALID_GLOBAL_NAME:
         os << "UR_RESULT_ERROR_INVALID_GLOBAL_NAME";
         break;
-    case UR_RESULT_ERROR_INVALID_FUNCTION_NAME:
-        os << "UR_RESULT_ERROR_INVALID_FUNCTION_NAME";
+    case UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE:
+        os << "UR_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE";
         break;
     case UR_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION:
         os << "UR_RESULT_ERROR_INVALID_GROUP_SIZE_DIMENSION";
@@ -2524,6 +2524,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_device_info_t value) {
     case UR_DEVICE_INFO_COMPOSITE_DEVICE:
         os << "UR_DEVICE_INFO_COMPOSITE_DEVICE";
         break;
+    case UR_DEVICE_INFO_GLOBAL_VARIABLE_SUPPORT:
+        os << "UR_DEVICE_INFO_GLOBAL_VARIABLE_SUPPORT";
+        break;
     case UR_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP:
         os << "UR_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP";
         break;
@@ -4008,6 +4011,18 @@ inline ur_result_t printTagged(std::ostream &os, const void *ptr, ur_device_info
 
         os << ")";
     } break;
+    case UR_DEVICE_INFO_GLOBAL_VARIABLE_SUPPORT: {
+        const ur_bool_t *tptr = (const ur_bool_t *)ptr;
+        if (sizeof(ur_bool_t) > size) {
+            os << "invalid size (is: " << size << ", expected: >=" << sizeof(ur_bool_t) << ")";
+            return UR_RESULT_ERROR_INVALID_SIZE;
+        }
+        os << (const void *)(tptr) << " (";
+
+        os << *tptr;
+
+        os << ")";
+    } break;
     case UR_DEVICE_INFO_COMMAND_BUFFER_SUPPORT_EXP: {
         const ur_bool_t *tptr = (const ur_bool_t *)ptr;
         if (sizeof(ur_bool_t) > size) {
@@ -7855,9 +7870,9 @@ inline ur_result_t printTagged(std::ostream &os, const void *ptr, ur_kernel_info
         printPtr(os, tptr);
     } break;
     case UR_KERNEL_INFO_NUM_ARGS: {
-        const size_t *tptr = (const size_t *)ptr;
-        if (sizeof(size_t) > size) {
-            os << "invalid size (is: " << size << ", expected: >=" << sizeof(size_t) << ")";
+        const uint32_t *tptr = (const uint32_t *)ptr;
+        if (sizeof(uint32_t) > size) {
+            os << "invalid size (is: " << size << ", expected: >=" << sizeof(uint32_t) << ")";
             return UR_RESULT_ERROR_INVALID_SIZE;
         }
         os << (const void *)(tptr) << " (";

scripts/core/common.yml

@@ -251,8 +251,8 @@ etors:
       desc: "[Validation] native binary is not supported by the device"
     - name: ERROR_INVALID_GLOBAL_NAME
       desc: "[Validation] global variable is not found in the program"
-    - name: ERROR_INVALID_FUNCTION_NAME
-      desc: "[Validation] function name is not found in the program"
+    - name: ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE
+      desc: "[Validation] function name is in the program but its address could not be determined"
     - name: ERROR_INVALID_GROUP_SIZE_DIMENSION
       desc: "[Validation] group size dimension is not valid for the kernel or device"
     - name: ERROR_INVALID_GLOBAL_WIDTH_DIMENSION

scripts/core/device.yml

@@ -439,6 +439,8 @@ etors:
       desc: "[$x_device_handle_t[]] The set of component devices contained by this composite device."
     - name: COMPOSITE_DEVICE
       desc: "[$x_device_handle_t] The composite device containing this component device."
+    - name: GLOBAL_VARIABLE_SUPPORT
+      desc: "[$x_bool_t] return true if the device supports the `EnqueueDeviceGlobalVariableWrite` and `EnqueueDeviceGlobalVariableRead` entry points."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Retrieves various information about device"

scripts/core/kernel.yml

@@ -109,7 +109,7 @@ etors:
     - name: FUNCTION_NAME
       desc: "[char[]] Return null-terminated kernel function name."
     - name: NUM_ARGS
-      desc: "[size_t] Return Kernel number of arguments."
+      desc: "[uint32_t] Return Kernel number of arguments."
     - name: REFERENCE_COUNT
       desc: |
             [uint32_t] Reference count of the kernel object.

scripts/core/memory.yml

@@ -197,10 +197,10 @@ members:
       desc: "[in] image slice pitch"
     - type: uint32_t
       name: numMipLevel
-      desc: "[in] number of MIP levels"
+      desc: "[in] number of MIP levels, must be `0`"
     - type: uint32_t
       name: numSamples
-      desc: "[in] number of samples"
+      desc: "[in] number of samples, must be `0`"
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create an image object"
@@ -242,6 +242,10 @@ returns:
     - $X_RESULT_ERROR_INVALID_VALUE
     - $X_RESULT_ERROR_INVALID_IMAGE_FORMAT_DESCRIPTOR:
       - "`pImageDesc && UR_MEM_TYPE_IMAGE1D_ARRAY < pImageDesc->type`"
+      - "`pImageDesc && pImageDesc->numMipLevel != 0`"
+      - "`pImageDesc && pImageDesc->numSamples != 0`"
+      - "`pImageDesc && pImageDesc->rowPitch != 0 && pHost == nullptr`"
+      - "`pImageDesc && pImageDesc->slicePitch != 0 && pHost == nullptr`"
     - $X_RESULT_ERROR_INVALID_IMAGE_SIZE
     - $X_RESULT_ERROR_INVALID_OPERATION
     - $X_RESULT_ERROR_INVALID_HOST_PTR:

scripts/core/program.yml

@@ -291,7 +291,7 @@ analogue:
     - "**clGetDeviceFunctionPointerINTEL**"
 details:
     - "Retrieves a pointer to the functions with the given name and defined in the given program."
-    - "$X_RESULT_ERROR_INVALID_FUNCTION_NAME is returned if the function can not be obtained."
+    - "$X_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE is returned if the function can not be obtained."
     - "The application may call this function from simultaneous threads for the same device."
     - "The implementation of this function should be thread-safe."
 params:
@@ -313,6 +313,11 @@ params:
       name: ppFunctionPointer
       desc: |
             [out] Returns the pointer to the function if it is found in the program.
+returns:
+    - $X_RESULT_ERROR_INVALID_KERNEL_NAME:
+        - "If `pFunctionName` couldn't be found in `hProgram`."
+    - $X_RESULT_ERROR_FUNCTION_ADDRESS_NOT_AVAILABLE:
+        - "If `pFunctionName` could be located, but its address couldn't be retrieved."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Retrieves a pointer to a device global variable."

source/adapters/cuda/device.cpp

@@ -1075,6 +1075,8 @@ UR_APIEXPORT ur_result_t UR_APICALL urDeviceGetInfo(ur_device_handle_t hDevice,
     return ReturnValue(true);
   case UR_DEVICE_INFO_ESIMD_SUPPORT:
     return ReturnValue(false);
+  case UR_DEVICE_INFO_GLOBAL_VARIABLE_SUPPORT:
+    return ReturnValue(true);
   case UR_DEVICE_INFO_COMPONENT_DEVICES:
   case UR_DEVICE_INFO_COMPOSITE_DEVICE:
   case UR_DEVICE_INFO_MAX_READ_WRITE_IMAGE_ARGS:

source/adapters/cuda/kernel.hpp

@@ -204,7 +204,9 @@ struct ur_kernel_handle_t_ {
   /// Note this only returns the current known number of arguments, not the
   /// real one required by the kernel, since this cannot be queried from
   /// the CUDA Driver API
-  size_t getNumArgs() const noexcept { return Args.Indices.size() - 1; }
+  uint32_t getNumArgs() const noexcept {
+    return static_cast<uint32_t>(Args.Indices.size() - 1);
+  }
 
   void setKernelArg(int Index, size_t Size, const void *Arg) {
     Args.addArg(Index, Size, Arg);

source/adapters/cuda/memory.cpp

@@ -208,16 +208,6 @@ UR_APIEXPORT ur_result_t UR_APICALL urMemImageCreate(
             UR_RESULT_ERROR_INVALID_IMAGE_FORMAT_DESCRIPTOR);
   UR_ASSERT(pImageDesc->type <= UR_MEM_TYPE_IMAGE1D_ARRAY,
             UR_RESULT_ERROR_INVALID_IMAGE_FORMAT_DESCRIPTOR);
-  UR_ASSERT(pImageDesc->numMipLevel == 0,
-            UR_RESULT_ERROR_INVALID_IMAGE_FORMAT_DESCRIPTOR);
-  UR_ASSERT(pImageDesc->numSamples == 0,
-            UR_RESULT_ERROR_INVALID_IMAGE_FORMAT_DESCRIPTOR);
-  if (!pHost) {
-    UR_ASSERT(pImageDesc->rowPitch == 0,
-              UR_RESULT_ERROR_INVALID_IMAGE_FORMAT_DESCRIPTOR);
-    UR_ASSERT(pImageDesc->slicePitch == 0,
-              UR_RESULT_ERROR_INVALID_IMAGE_FORMAT_DESCRIPTOR);
-  }
 
   // We only support RBGA channel order
   // TODO: check SYCL CTS and spec. May also have to support BGRA