[UR] Add support for feature guards (#18759)

Introduce the ability to wrap UR features in pre-processor guards based
on the presence of the `guard: NAME` attribute in the yaml specs to
support conditionally enabling features.

Author: kbenzie

unified-runtime/include/ur_print.h

@@ -22,6 +22,7 @@ This document describes the YaML format used by the scripts for the API specific
 * A header may take the following optional scalar fields: {`ordinal`, `version`}
   - `ordinal` will be used to override the default order (alphabetical) in which regions appear in the specification; `default="1000"`. Multiple regions with the same ordinal will be ordered alphabetically.
   - `version` can be used to define the minimum API version for all documents in the yml file; `default="1.0"`
+  - `guard` takes a name, which must be a valid C identifier, that will be used to generate pre-processor guards around feature code
 
 <table>
 <tr><th>YaML</th><th>C\C++</th><th>Python</th></tr>
@@ -58,6 +59,7 @@ n/a
   - `version` will be used to define the minimum API version in which the macro will appear; `default="1.0"` This will also affect the order in which the macro appears within its section.
 * A macro may take the following optional field which can be a scalar, a sequence of scalars or scalars to sequences: {`details`}
   - `details` will be used as the macro's detailed comment
+  - `guard` takes a name, which must be a valid C identifier, that will be used to generate pre-processor guards around feature code
 
 <table>
 <tr><th>YaML</th><th>C\C++</th><th>Python</th></tr>
@@ -149,6 +151,7 @@ n/a
   - `version` will be used to define the minimum API version in which the typedef will appear; `default="1.0"` This will also affect the order in which the typedef appears within its section and class.
 * A typedef may take the following optional field which can be a scalar, a sequence of scalars or scalars to sequences: {`details`}
   - `details` will be used as the typedef's detailed comment
+  - `guard` takes a name, which must be a valid C identifier, that will be used to generate pre-processor guards around feature code
 
 <table>
 <tr><th>YaML</th><th>C</th><th>C++</th><th>Python</th></tr>
@@ -201,6 +204,7 @@ class ur_name_t(c_void_p):
   - `desc` will be used as param's description comment
   - `name` must be a unique ISO-C standard identifier
   - `type` must be ISO-C standard data type
+  - `guard` takes a name, which must be a valid C identifier, that will be used to generate pre-processor guards around feature code
 
 <table>
 <tr><th>YaML</th><th>C</th><th>C++</th></tr>
@@ -247,6 +251,7 @@ std::function<void(void*)> ur_callback_t;
   - `loader_only` will be used to decide whether the handle can be instantiated and managed only by the loader.
 * A handle may take the following optional field which can be a scalar, a sequence of scalars or scalars to sequences: {`details`}
   - `details` will be used as the handle's detailed comment
+  - `guard` takes a name, which must be a valid C identifier, that will be used to generate pre-processor guards around feature code
 
 <table>
 <tr><th>YaML</th><th>C</th><th>C++</th><th>Python</th></tr>
@@ -344,6 +349,7 @@ plural form *enumerators* is abbreviated to `etors`.
     + `version` will be used to define the minimum API version in which the etor will appear; `default="1.0"` This will also affect the order in which the etor appears within the enum.
 * An enum may take the following optional field which can be a scalar, a sequence of scalars or scalars to sequences: {`details`}
   - `details` will be used as the enum's detailed comment
+  - `guard` takes a name, which must be a valid C identifier, that will be used to generate pre-processor guards around feature code
 
 <table>
 <tr><th>YaML</th><th>C</th><th>C++</th><th>Python</th></tr>
@@ -491,6 +497,7 @@ class ur_name_flags_v(IntEnum):
     + `tag` applies only to unions and refers to a value for when this member can be accessed.
 * A struct|union may take the following optional field which can be a scalar, a sequence of scalars or scalars to sequences: {`details`}
   - `details` will be used as the struct|union's detailed comment
+  - `guard` takes a name, which must be a valid C identifier, that will be used to generate pre-processor guards around feature code
 
 <table>
 <tr><th>YaML</th><th>C</th><th>C++</th><th>Python</th></tr>
@@ -652,6 +659,7 @@ class ur_name_t(Structure):
   - `returns` may contain a sequence of custom validation layer code blocks
 * A function may take the following optional field which can be a scalar, a sequence of scalars or scalars to sequences: {`details`}
   - `details` will be used as the function's detailed comment
+  - `guard` takes a name, which must be a valid C identifier, that will be used to generate pre-processor guards around feature code
 
 <table>
 <tr><th>YaML</th><th>C</th><th>C++</th><th>Python</th></tr>
@@ -762,6 +770,7 @@ _urClsNameFnName_t = CFUNCTYPE( ur_result_t, ur_cls_handle_t, c_ulong, POINTER(c
   - The next member may be the `_desc_t` used to create the object; the `name` must be `"desc"`
 * A class may take the following optional field which can be a scalar, a sequence of scalars or scalars to sequences: {`details`}
   - `details` will be used as the class's detailed comment
+  - `guard` takes a name, which must be a valid C identifier, that will be used to generate pre-processor guards around feature code
 
 <table>
 <tr><th>YaML</th><th>C++</th></tr>

unified-runtime/include/ur_print.hpp

@@ -65,21 +65,24 @@ def generate_function_type(
     }
     max_etor = get_max_enum(existing_function_type)
     functions = [
-        obj["class"][len("$x") :] + obj["name"]
-        for s in specs
-        for obj in s["objects"]
-        if obj["type"] == "function"
+        obj for s in specs for obj in s["objects"] if obj["type"] == "function"
     ]
     registry = list()
-    for fname in functions:
+    for function in functions:
+        fname = function["class"][len("$x") :] + function["name"]
         etor_name = "$X_FUNCTION_" + util.to_snake_case(fname).upper()
         id = existing_etors.get(etor_name)
         if id is None:
             max_etor += 1
             id = max_etor
-        registry.append(
-            {"name": etor_name, "desc": f"Enumerator for $x{fname}", "value": str(id)}
-        )
+        entry = {
+            "name": etor_name,
+            "desc": f"Enumerator for $x{fname}",
+            "value": str(id),
+        }
+        if "guard" in function:
+            entry["guard"] = function["guard"]
+        registry.append(entry)
     registry = sorted(registry, key=lambda x: int(x["value"]))
     existing_function_type["etors"] = registry
     update_fn(existing_function_type, meta)

unified-runtime/scripts/YaML.md

@@ -512,6 +512,16 @@ def __validate_union_tag(d):
         if d.get("tag") is None:
             raise Exception(f"{d['name']} must include a 'tag' part of the union.")
 
+    def __validate_guard(d):
+        if "guard" not in d:
+            return
+        if not isinstance(d["guard"], str):
+            raise Exception("'guard' must be a string: '%s'" % type(d["guard"]))
+        if not re.match(r"[A-Z][A-Z0-9_]*$", d["guard"]):
+            raise Exception(
+                "'guard' must a valid upper case C identifier: '%s'" % d["guard"]
+            )
+
     try:
         if "type" not in d:
             raise Exception("every document must have 'type'")
@@ -530,6 +540,7 @@ def __validate_union_tag(d):
 
             __validate_ordinal(d)
             __validate_version(d)
+            __validate_guard(d)
 
         elif "macro" == d["type"]:
             if ("desc" not in d) or ("name" not in d) or ("value" not in d):
@@ -544,6 +555,7 @@ def __validate_union_tag(d):
             __validate_details(d)
             __validate_ordinal(d)
             __validate_version(d)
+            __validate_guard(d)
 
         elif "typedef" == d["type"]:
             if ("desc" not in d) or ("name" not in d) or ("value" not in d):
@@ -555,6 +567,7 @@ def __validate_union_tag(d):
             __validate_details(d)
             __validate_ordinal(d)
             __validate_version(d)
+            __validate_guard(d)
 
         elif "handle" == d["type"]:
             if ("desc" not in d) or ("name" not in d):
@@ -566,6 +579,7 @@ def __validate_union_tag(d):
             __validate_details(d)
             __validate_ordinal(d)
             __validate_version(d)
+            __validate_guard(d)
 
         elif "enum" == d["type"]:
             if ("desc" not in d) or ("name" not in d):
@@ -578,6 +592,7 @@ def __validate_union_tag(d):
             __validate_details(d)
             __validate_ordinal(d)
             __validate_version(d)
+            __validate_guard(d)
 
         elif "struct" == d["type"] or "union" == d["type"]:
             if ("desc" not in d) or ("name" not in d):
@@ -594,6 +609,7 @@ def __validate_union_tag(d):
             __validate_details(d)
             __validate_ordinal(d)
             __validate_version(d)
+            __validate_guard(d)
 
         elif "function" == d["type"]:
             if ("desc" not in d) or ("name" not in d):
@@ -612,6 +628,7 @@ def __validate_union_tag(d):
             __validate_details(d)
             __validate_ordinal(d)
             __validate_version(d)
+            __validate_guard(d)
 
         elif "class" == d["type"]:
             if ("desc" not in d) or ("name" not in d):
@@ -623,6 +640,7 @@ def __validate_union_tag(d):
             __validate_details(d)
             __validate_ordinal(d)
             __validate_version(d)
+            __validate_guard(d)
 
         return True
 
@@ -1136,6 +1154,9 @@ def parse(section, version, tags, meta, ref):
 
             if d["type"] == "enum" and d.get("extend"):
                 # enum extensions are resolved later
+                if "guard" in header and "guard" not in d:
+                    for etor in d["etors"]:
+                        etor["guard"] = header["guard"]
                 enum_extensions.append(d)
                 continue
 
@@ -1167,6 +1188,8 @@ def parse(section, version, tags, meta, ref):
                     name = name.replace(c, " ")
             elif header:
                 for d in _make_versions(d, version):
+                    if "guard" in header and "guard" not in d:
+                        d["guard"] = header["guard"]
                     objects.append(d)
                     meta = _generate_meta(d, header["ordinal"], meta)
 

unified-runtime/scripts/generate_ids.py

@@ -7,5 +7,11 @@ from templates import helper as th
 LIBRARY @TARGET_LIBNAME@
 EXPORTS
 %for tbl in th.get_pfntables(specs, meta, n, tags):
+%if 'guard' in tbl:
+#if ${tbl['guard']}
+%endif
 	${tbl['export']['name']}
+%if 'guard' in tbl:
+#endif // ${tbl['guard']}
+%endif
 %endfor

unified-runtime/scripts/parse_specs.py

@@ -7,7 +7,13 @@ from templates import helper as th
 @TARGET_LIBNAME@ {
 	global:
 %for tbl in th.get_pfntables(specs, meta, n, tags):
+%if 'guard' in tbl:
+#if ${tbl['guard']}
+%endif
 		${tbl['export']['name']};
+%if 'guard' in tbl:
+#endif // ${tbl['guard']}
+%endif
 %endfor
 	local:
 		*;

unified-runtime/scripts/templates/adapter.def.in.mako

@@ -24,6 +24,9 @@ from templates import helper as th
 #include "${n}_api.h"
 
 %for obj in th.extract_objs(specs, r"function"):
+%if 'guard' in obj:
+#if ${obj['guard']}
+%endif
 ///////////////////////////////////////////////////////////////////////////////
 %if 'condition' in obj:
 #if ${th.subt(n, tags, obj['condition'])}
@@ -51,5 +54,8 @@ ${th.make_func_name(n, tags, obj)}(
 %if 'condition' in obj:
 #endif // ${th.subt(n, tags, obj['condition'])}
 %endif
+%if 'guard' in obj:
+#endif // ${obj['guard']}
+%endif
 
 %endfor

unified-runtime/scripts/templates/adapter.map.in.mako

@@ -42,15 +42,24 @@ extern "C" {
 
 %for spec in specs:
 %if len(spec['objects']) and 'manifest' not in spec['name']:
+%if 'guard' in spec['header']:
+// ${spec['header']['guard']}
+%endif
 // ${th.subt(n, tags, spec['header']['desc'])}
 #if !defined(__GNUC__)
 #pragma region ${spec['name'].replace(' ', '_')}
 #endif
+%if 'guard' in spec:
+// end ${obj['guard']}
+%endif
 %endif
 %for obj in spec['objects']:
 %if "manifest" in obj['type']:
 <%continue%>
 %elif not re.match(r"class", obj['type']):
+%if 'guard' in obj and 'guard' not in spec['header']:
+// ${obj['guard']}
+%endif
 ///////////////////////////////////////////////////////////////////////////////
 ## MACRO ######################################################################
 %if re.match(r"macro", obj['type']):
@@ -141,13 +150,22 @@ typedef struct ${th.subt(n, tags, obj['name'])}_ *${th.subt(n, tags, obj['name']
 %if re.match(r"macro", obj['type']):
 #endif // ${th.make_macro_name(n, tags, obj, params=False)}
 %endif
+%if 'guard' in obj and 'guard' not in spec['header']:
+// end ${obj['guard']}
+%endif
 
 %endif  # not re.match(r"class", obj['type'])
 %endfor # obj in spec['objects']
 %if len(spec['objects']) and 'manifest' not in spec['name']:
+%if 'guard' in spec:
+// ${obj['guard']}
+%endif
 #if !defined(__GNUC__)
 #pragma endregion
 #endif
+%if 'guard' in spec['header']:
+// end ${spec['header']['guard']}
+%endif
 %endif
 %endfor # spec in specs
 %if n not in ["zet", "zes"]:
@@ -157,6 +175,9 @@ typedef struct ${th.subt(n, tags, obj['name'])}_ *${th.subt(n, tags, obj['name']
 #endif
 %for tbl in th.get_pfncbtables(specs, meta, n, tags):
 %for obj in tbl['functions']:
+%if 'guard' in obj:
+// ${obj['guard']}
+%endif
 %if obj['params']:
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for ${th.make_func_name(n, tags, obj)} 
@@ -175,6 +196,9 @@ typedef struct ${th.make_pfncb_param_type(n, tags, obj)}
 #endif // ${th.subt(n, tags, obj['condition'])}
 %endif
 %endif
+%if 'guard' in obj:
+// end ${obj['guard']}
+%endif
 
 %endfor
 %endfor

unified-runtime/scripts/templates/api.cpp.mako

@@ -28,7 +28,13 @@ from templates import helper as th
 
 %for tbl in th.get_pfntables(specs, meta, n, tags):
 %for obj in tbl['functions']:
+%if 'guard' in obj:
+// ${obj['guard']}
+%endif
 _UR_API(${th.make_func_name(n, tags, obj)})
+%if 'guard' in obj:
+// end ${obj['guard']}
+%endif
 %endfor
 %endfor
 %for obj in th.get_loader_functions(specs, meta, n, tags):