Merge branch 'sycl' into move-clean-shadow-to-launchinfo

Author: zhaomaosu

include/ur_api.h

@@ -651,6 +651,7 @@ typedef ur_result_t(UR_APICALL *ur_pfnGetKernelProcAddrTable_t)(
 /// @brief Function-pointer for urKernelSuggestMaxCooperativeGroupCountExp
 typedef ur_result_t(UR_APICALL *ur_pfnKernelSuggestMaxCooperativeGroupCountExp_t)(
     ur_kernel_handle_t,
+    ur_device_handle_t,
     uint32_t,
     const size_t *,
     size_t,

include/ur_ddi.h

@@ -2074,6 +2074,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_platform_info_t value)
     case UR_PLATFORM_INFO_BACKEND:
         os << "UR_PLATFORM_INFO_BACKEND";
         break;
+    case UR_PLATFORM_INFO_ADAPTER:
+        os << "UR_PLATFORM_INFO_ADAPTER";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -2127,6 +2130,19 @@ inline ur_result_t printTagged(std::ostream &os, const void *ptr, ur_platform_in
 
         os << ")";
     } break;
+    case UR_PLATFORM_INFO_ADAPTER: {
+        const ur_adapter_handle_t *tptr = (const ur_adapter_handle_t *)ptr;
+        if (sizeof(ur_adapter_handle_t) > size) {
+            os << "invalid size (is: " << size << ", expected: >=" << sizeof(ur_adapter_handle_t) << ")";
+            return UR_RESULT_ERROR_INVALID_SIZE;
+        }
+        os << (const void *)(tptr) << " (";
+
+        ur::details::printPtr(os,
+                              *tptr);
+
+        os << ")";
+    } break;
     default:
         os << "unknown enumerator";
         return UR_RESULT_ERROR_INVALID_ENUMERATION;
@@ -13187,6 +13203,12 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
     ur::details::printPtr(os,
                           *(params->phKernel));
 
+    os << ", ";
+    os << ".hDevice = ";
+
+    ur::details::printPtr(os,
+                          *(params->phDevice));
+
     os << ", ";
     os << ".workDim = ";
 

include/ur_print.hpp

@@ -336,6 +336,7 @@ plural form *enumerators* is abbreviated to `etors`.
   - An etor requires the following scalar fields: {`name`, `desc`}
     + `desc` will be used as the etors's description comment
     + If the enum has `typed_etors`, `desc` must begin with type identifier: {`"[type]"`}
+    + `desc` may contain the [optional-query] annotation. This denotes the etor as an info query which is optional for adapters to implement, and may legally result in a non-success error code.
     + `name` must be a unique ISO-C standard identifier, and be all caps
   - An etor may take the following optional scalar field: {`value`, `version`}
     + `value` must be an ISO-C standard identifier

scripts/YaML.md

@@ -183,6 +183,24 @@ explicitly created against a context.
     // Release the context handle
     ${x}ContextRelease(hContext);    
 
+Object Queries
+==============
+
+Queries to get information from API objects follow a common pattern. The entry
+points for this are generally of the form:
+
+.. code-block::
+
+   ObjectGetInfo(ur_object_handle_t hObject, ur_object_info_t propName,
+                 size_t propSize, void *pPropValue, size_t *pPropSizeRet)
+
+where ``propName`` selects the information to query out. The object info enum
+representing possible queries will generally be found in the enums section of
+the relevant object. Some info queries would be difficult or impossible to
+support for certain backends, these are denoted with [optional-query] in the
+enum description. Using any enum marked optional in this way may result in
+${X}_RESULT_ERROR_UNSUPPORTED_ENUMERATION if the adapter doesn't support it.
+
 Programs and Kernels
 ====================
 

scripts/core/PROG.rst

@@ -102,16 +102,16 @@ etors:
     - name: USM_FILL2D_SUPPORT
       desc: "[$x_bool_t] to indicate if the $xEnqueueUSMFill2D entrypoint is supported."
     - name: ATOMIC_MEMORY_ORDER_CAPABILITIES
-      desc: "[$x_memory_order_capability_flags_t] return a bit-field of atomic memory order capabilities."
+      desc: "[$x_memory_order_capability_flags_t][optional-query] return a bit-field of atomic memory order capabilities."
     - name: ATOMIC_MEMORY_SCOPE_CAPABILITIES
-      desc: "[$x_memory_scope_capability_flags_t] return a bit-field of atomic memory scope capabilities."
+      desc: "[$x_memory_scope_capability_flags_t][optional-query] return a bit-field of atomic memory scope capabilities."
     - name: ATOMIC_FENCE_ORDER_CAPABILITIES
       desc: |
-            [$x_memory_order_capability_flags_t] return a bit-field of atomic memory fence order capabilities.
+            [$x_memory_order_capability_flags_t][optional-query] return a bit-field of atomic memory fence order capabilities.
             Zero is returned if the backend does not support context-level fences.
     - name: ATOMIC_FENCE_SCOPE_CAPABILITIES
       desc: |
-            [$x_memory_scope_capability_flags_t] return a bit-field of atomic memory fence scope capabilities.
+            [$x_memory_scope_capability_flags_t][optional-query] return a bit-field of atomic memory fence scope capabilities.
             Zero is returned if the backend does not support context-level fences.
 --- #--------------------------------------------------------------------------
 type: function

scripts/core/context.yml

@@ -200,7 +200,7 @@ etors:
     - name: VENDOR_ID
       desc: "[uint32_t] vendor Id of the device"
     - name: DEVICE_ID
-      desc: "[uint32_t] Id of the device"
+      desc: "[uint32_t][optional-query] Id of the device"
     - name: MAX_COMPUTE_UNITS
       desc: "[uint32_t] the number of compute units"
     - name: MAX_WORK_ITEM_DIMENSIONS
@@ -248,7 +248,7 @@ etors:
     - name: MAX_CLOCK_FREQUENCY
       desc: "[uint32_t] max clock frequency in MHz"
     - name: MEMORY_CLOCK_RATE
-      desc: "[uint32_t] memory clock frequency in MHz"
+      desc: "[uint32_t][optional-query] memory clock frequency in MHz"
     - name: ADDRESS_BITS
       desc: "[uint32_t] address bits"
     - name: MAX_MEM_ALLOC_SIZE
@@ -290,7 +290,7 @@ etors:
     - name: GLOBAL_MEM_SIZE
       desc: "[uint64_t] size of global memory in bytes"
     - name: GLOBAL_MEM_FREE
-      desc: "[uint64_t] size of global memory which is free in bytes"
+      desc: "[uint64_t][optional-query] size of global memory which is free in bytes"
     - name: MAX_CONSTANT_BUFFER_SIZE
       desc: "[uint64_t] max constant buffer size in bytes"
     - name: MAX_CONSTANT_ARGS
@@ -377,23 +377,23 @@ etors:
     - name: USM_SYSTEM_SHARED_SUPPORT
       desc: "[$x_device_usm_access_capability_flags_t] support USM system wide shared memory access"
     - name: UUID
-      desc: "[uint8_t[]] return device UUID"
+      desc: "[uint8_t[]][optional-query] return device UUID"
     - name: PCI_ADDRESS
-      desc: "[char[]] return device PCI address"
+      desc: "[char[]][optional-query] return device PCI address"
     - name: GPU_EU_COUNT
-      desc: "[uint32_t] return Intel GPU EU count"
+      desc: "[uint32_t][optional-query] return Intel GPU EU count"
     - name: GPU_EU_SIMD_WIDTH
-      desc: "[uint32_t] return Intel GPU EU SIMD width"
+      desc: "[uint32_t][optional-query] return Intel GPU EU SIMD width"
     - name: GPU_EU_SLICES
-      desc: "[uint32_t] return Intel GPU number of slices"
+      desc: "[uint32_t][optional-query] return Intel GPU number of slices"
     - name: GPU_EU_COUNT_PER_SUBSLICE
-      desc: "[uint32_t] return Intel GPU EU count per subslice"
+      desc: "[uint32_t][optional-query] return Intel GPU EU count per subslice"
     - name: GPU_SUBSLICES_PER_SLICE
-      desc: "[uint32_t] return Intel GPU number of subslices per slice"
+      desc: "[uint32_t][optional-query] return Intel GPU number of subslices per slice"
     - name: GPU_HW_THREADS_PER_EU
-      desc: "[uint32_t] return Intel GPU number of threads per EU"
+      desc: "[uint32_t][optional-query] return Intel GPU number of threads per EU"
     - name: MAX_MEMORY_BANDWIDTH
-      desc: "[uint32_t] return max memory bandwidth in Mb/s"
+      desc: "[uint32_t][optional-query] return max memory bandwidth in Mb/s"
     - name: IMAGE_SRGB
       desc: "[$x_bool_t] device supports sRGB images"
     - name: BUILD_ON_SUBDEVICE
@@ -418,7 +418,7 @@ etors:
     - name: KERNEL_SET_SPECIALIZATION_CONSTANTS
       desc: "[$x_bool_t] support the $xKernelSetSpecializationConstants entry point"
     - name: MEMORY_BUS_WIDTH
-      desc: "[uint32_t] return the width in bits of the memory bus interface of the device."
+      desc: "[uint32_t][optional-query] return the width in bits of the memory bus interface of the device."
     - name: MAX_WORK_GROUPS_3D
       desc: "[size_t[3]] return max 3D work groups"
     - name: ASYNC_BARRIER
@@ -428,17 +428,17 @@ etors:
     - name: HOST_PIPE_READ_WRITE_SUPPORTED
       desc: "[$x_bool_t] Return true if the device supports enqueueing commands to read and write pipes from the host."
     - name: MAX_REGISTERS_PER_WORK_GROUP
-      desc: "[uint32_t] The maximum number of registers available per block."
+      desc: "[uint32_t][optional-query] The maximum number of registers available per block."
     - name: IP_VERSION
-      desc: "[uint32_t] The device IP version. The meaning of the device IP version is implementation-defined, but newer devices should have a higher version than older devices."
+      desc: "[uint32_t][optional-query] The device IP version. The meaning of the device IP version is implementation-defined, but newer devices should have a higher version than older devices."
     - name: VIRTUAL_MEMORY_SUPPORT
       desc: "[$x_bool_t] return true if the device supports virtual memory."
     - name: ESIMD_SUPPORT
       desc: "[$x_bool_t] return true if the device supports ESIMD."
     - name: COMPONENT_DEVICES
-      desc: "[$x_device_handle_t[]] The set of component devices contained by this composite device."
+      desc: "[$x_device_handle_t[]][optional-query] 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."
+      desc: "[$x_device_handle_t][optional-query] 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."
     - name: USM_POOL_SUPPORT

scripts/core/device.yml

@@ -78,6 +78,9 @@ params:
     - type: $x_kernel_handle_t
       name: hKernel
       desc: "[in] handle of the kernel object"
+    - type: $x_device_handle_t
+      name: hDevice
+      desc: "[in] handle of the device object"
     - type: uint32_t
       name: workDim
       desc: "[in] number of dimensions, from 1 to 3, to specify the work-group work-items"

scripts/core/exp-cooperative-kernels.yml

@@ -124,7 +124,7 @@ etors:
     - name: ATTRIBUTES
       desc: "[char[]] Return null-terminated kernel attributes string."
     - name: NUM_REGS
-      desc: "[uint32_t] Return the number of registers used by the compiled kernel (device specific)."
+      desc: "[uint32_t][optional-query] Return the number of registers used by the compiled kernel."
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Get Kernel Work Group information"
@@ -133,7 +133,7 @@ name: $x_kernel_group_info_t
 typed_etors: True
 etors:
     - name: GLOBAL_WORK_SIZE
-      desc: "[size_t[3]] Return Work Group maximum global size"
+      desc: "[size_t[3]][optional-query] Return Work Group maximum global size"
     - name: WORK_GROUP_SIZE
       desc: "[size_t] Return maximum Work Group size"
     - name: COMPILE_WORK_GROUP_SIZE
@@ -146,12 +146,12 @@ etors:
       desc: "[size_t] Return minimum amount of private memory in bytes used by each work item in the Kernel"
     - name: COMPILE_MAX_WORK_GROUP_SIZE
       desc: |
-            [size_t[3]] Return the maximum Work Group size guaranteed by the
-            source code, or (0, 0, 0) if unspecified
+            [size_t[3]][optional-query] Return the maximum Work Group size guaranteed
+            by the source code, or (0, 0, 0) if unspecified
     - name: COMPILE_MAX_LINEAR_WORK_GROUP_SIZE
       desc: |
-            [size_t] Return the maximum linearized Work Group size (X * Y * Z)
-            guaranteed by the source code, or 0 if unspecified
+            [size_t][optional-query] Return the maximum linearized Work Group size
+            (X * Y * Z) guaranteed by the source code, or 0 if unspecified
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Get Kernel SubGroup information"

scripts/core/kernel.yml

@@ -77,7 +77,9 @@ etors:
     - name: BACKEND
       value: "6"
       desc: "[$x_platform_backend_t] The backend of the platform. Identifies the native backend adapter implementing this platform."
-
+    - name: ADAPTER
+      value: "7"
+      desc: "[$x_adapter_handle_t] The adapter handle associated with the platform."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Retrieves various information about platform"