Update docs, rename macro.

Author: aarongreig

scripts/YaML.md

@@ -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/core/PROG.rst

@@ -197,8 +197,8 @@ points for this are generally of the form:
 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)" in the enum
-description. Using any enum marked optional may result in
+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/generate_code.py

@@ -549,6 +549,11 @@ def generate_level_zero_queue_api(path, section, namespace, tags, version, 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)

scripts/templates/helper.py

@@ -542,9 +542,9 @@ def is_global(item, tags):
             return False
 
 """
-    Extracts traits from an enum
+    Extracts traits from an enumerator
 """
-class enum_traits:
+class etor_traits:
     RE_OPTIONAL_QUERY = r".*\[optional-query\].*"
 
     @classmethod
@@ -797,7 +797,6 @@ def etor_get_associated_type(namespace, tags, item):
         associated_type = match.group(1)
         return subt(namespace, tags, associated_type)
     else:
-        print("couldn't figure type from %s" % item['desc'])
         return None
 
 """
@@ -1719,7 +1718,7 @@ def get_optional_queries(specs, namespace, tags):
             if obj['type'] == 'enum':
                 optional_etors = []
                 for e in obj['etors']:
-                    if enum_traits.is_optional_query(e):
+                    if etor_traits.is_optional_query(e):
                         name = make_enum_name(namespace, tags, e)
                         optional_etors.append(name)
                 if optional_etors:

scripts/templates/optional_queries.h.mako

@@ -3,8 +3,7 @@ import re
 from templates import helper as th
 %><%
 optional_queries = th.get_optional_queries(specs, namespace, tags)
-%>
-/*
+%>/*
  *
  * Copyright (C) 2024 Intel Corporation
  *

test/conformance/adapter/urAdapterGetInfo.cpp

@@ -35,7 +35,7 @@ INSTANTIATE_TEST_SUITE_P(
 TEST_P(urAdapterGetInfoTest, Success) {
     size_t size = 0;
     ur_adapter_info_t info_type = GetParam();
-    ASSERT_QUERY_SUCCESS(
+    ASSERT_SUCCES_OR_OPTIONAL_QUERY(
         urAdapterGetInfo(adapter, info_type, 0, nullptr, &size), info_type);
     ASSERT_NE(size, 0);
 

test/conformance/context/urContextGetInfo.cpp

@@ -43,7 +43,7 @@ UUR_TEST_SUITE_P(urContextGetInfoTestWithInfoParam,
 TEST_P(urContextGetInfoTestWithInfoParam, Success) {
     ur_context_info_t info = getParam();
     size_t info_size = 0;
-    ASSERT_QUERY_SUCCESS(
+    ASSERT_SUCCES_OR_OPTIONAL_QUERY(
         urContextGetInfo(context, info, 0, nullptr, &info_size), info);
     ASSERT_NE(info_size, 0);
 

test/conformance/device/urDeviceGetInfo.cpp

@@ -274,7 +274,7 @@ TEST_P(urDeviceGetInfoTest, Success) {
     ur_device_info_t info_type = GetParam();
     for (auto device : devices) {
         size_t size = 0;
-        ASSERT_QUERY_SUCCESS(
+        ASSERT_SUCCES_OR_OPTIONAL_QUERY(
             urDeviceGetInfo(device, info_type, 0, nullptr, &size), info_type);
 
         if (doesReturnArray(info_type) && size == 0) {

test/conformance/event/urEventGetInfo.cpp

@@ -11,8 +11,8 @@ TEST_P(urEventGetInfoTest, Success) {
 
     ur_event_info_t info_type = getParam();
     size_t size;
-    ASSERT_QUERY_SUCCESS(urEventGetInfo(event, info_type, 0, nullptr, &size),
-                         info_type);
+    ASSERT_SUCCES_OR_OPTIONAL_QUERY(
+        urEventGetInfo(event, info_type, 0, nullptr, &size), info_type);
     ASSERT_NE(size, 0);
     std::vector<uint8_t> data(size);
     ASSERT_SUCCESS(

test/conformance/event/urEventGetProfilingInfo.cpp

@@ -12,7 +12,7 @@ TEST_P(urEventGetProfilingInfoTest, Success) {
 
     ur_profiling_info_t info_type = getParam();
     size_t size;
-    ASSERT_QUERY_SUCCESS(
+    ASSERT_SUCCES_OR_OPTIONAL_QUERY(
         urEventGetProfilingInfo(event, info_type, 0, nullptr, &size),
         info_type);
     ASSERT_EQ(size, 8);