Explicitly define which info queries are optional.

This is now reflected in the spec and in the CTS tests.

Also includes a number of minor fixes for adapter implementations of
related info queries.

Author: Aaron Greig

include/ur_api.h

@@ -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

@@ -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

@@ -387,9 +387,9 @@ etors:
     - name: BINARIES
       desc: "[unsigned char[]] Return program binaries for all devices for this Program."
     - name: NUM_KERNELS
-      desc: "[size_t] Number of kernels in Program, return type size_t."
+      desc: "[size_t][optional-query] Number of kernels in Program, return type size_t."
     - name: KERNEL_NAMES
-      desc: "[char[]] Return a null-terminated, semi-colon separated list of kernel names in Program."
+      desc: "[char[]][optional-query] Return a null-terminated, semi-colon separated list of kernel names in Program."
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Query information about a Program object"

scripts/core/program.yml

@@ -37,7 +37,7 @@ etors:
             if the queue was created with the `ON_DEVICE` queue flag, otherwise
             `$xQueueGetInfo` will return `$X_RESULT_ERROR_INVALID_QUEUE`.
     - name: EMPTY
-      desc: "[$x_bool_t] return true if the queue was empty at the time of the query"
+      desc: "[$x_bool_t][optional-query] return true if the queue was empty at the time of the query."
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Queue property flags"

scripts/core/queue.yml

@@ -74,7 +74,7 @@ etors:
     - name: DEVICE
       desc: "[$x_device_handle_t] Memory allocation device info"
     - name: POOL
-      desc: "[$x_usm_pool_handle_t] Memory allocation pool info"
+      desc: "[$x_usm_pool_handle_t][optional-query] Memory allocation pool info"
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "USM memory advice"

scripts/core/usm.yml

@@ -548,3 +548,24 @@ def generate_level_zero_queue_api(path, section, namespace, tags, version, specs
             specs=specs,
             meta=meta)
     print("QUEUE Generated %s lines of code.\n" % loc)
+
+"""
+Entry-point:
+    generates headers used by the CTS, for example containing meta-information
+    about info query enums
+"""
+def generate_cts_headers(path, section, namespace, tags, version, specs, meta):
+    template = "optional_queries.h.mako"
+    fin = os.path.join("templates", template)
+    name = "optional_queries"
+    filename = "optional_queries.h"
+    dstpath = os.path.join(path, "conformance", "testing", "include", "uur")
+    fout  = os.path.join(dstpath, filename)
+
+    print("Generating %s..." % fout)
+
+    loc = util.makoWrite(fin, fout,
+            filename = name, namespace = namespace,
+            tags = tags, specs = specs, meta = meta)
+
+    print("CTS Generated %s lines of code.\n" % loc)