Merge pull request #696 from veselypeta/petr/538/handle-unions

[UR] print unions correctly in ur_params

Author: veselypeta

include/ur.py

@@ -848,15 +848,15 @@ class ur_device_partition_value_t(Structure):
         ("count", c_ulong),                                             ## [in] Number of compute units in a sub-device when partitioning with
                                                                         ## ::UR_DEVICE_PARTITION_BY_COUNTS.
         ("affinity_domain", ur_device_affinity_domain_flags_t)          ## [in] The affinity domain to partition for when partitioning with
-                                                                        ## $UR_DEVICE_PARTITION_BY_AFFINITY_DOMAIN.
+                                                                        ## ::UR_DEVICE_PARTITION_BY_AFFINITY_DOMAIN.
     ]
 
 ###############################################################################
 ## @brief Device partition property
 class ur_device_partition_property_t(Structure):
     _fields_ = [
         ("type", ur_device_partition_t),                                ## [in] The partitioning type to be used.
-        ("value", ur_device_partition_value_t)                          ## [in] The partitioning value.
+        ("value", ur_device_partition_value_t)                          ## [in][tagged_by(type)] The partitioning value.
     ]
 
 ###############################################################################
@@ -1579,7 +1579,7 @@ class ur_program_metadata_t(Structure):
         ("type", ur_program_metadata_type_t),                           ## [in] the type of metadata value.
         ("size", c_size_t),                                             ## [in] size in bytes of the data pointed to by value.pData, or 0 when
                                                                         ## value size is less than 64-bits and is stored directly in value.data.
-        ("value", ur_program_metadata_value_t)                          ## [in] the metadata value storage.
+        ("value", ur_program_metadata_value_t)                          ## [in][tagged_by(type)] the metadata value storage.
     ]
 
 ###############################################################################

include/ur_api.h

@@ -1348,15 +1348,15 @@ typedef union ur_device_partition_value_t {
     uint32_t count;                                    ///< [in] Number of compute units in a sub-device when partitioning with
                                                        ///< ::UR_DEVICE_PARTITION_BY_COUNTS.
     ur_device_affinity_domain_flags_t affinity_domain; ///< [in] The affinity domain to partition for when partitioning with
-                                                       ///< $UR_DEVICE_PARTITION_BY_AFFINITY_DOMAIN.
+                                                       ///< ::UR_DEVICE_PARTITION_BY_AFFINITY_DOMAIN.
 
 } ur_device_partition_value_t;
 
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Device partition property
 typedef struct ur_device_partition_property_t {
     ur_device_partition_t type;        ///< [in] The partitioning type to be used.
-    ur_device_partition_value_t value; ///< [in] The partitioning value.
+    ur_device_partition_value_t value; ///< [in][tagged_by(type)] The partitioning value.
 
 } ur_device_partition_property_t;
 
@@ -3553,11 +3553,11 @@ typedef union ur_program_metadata_value_t {
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Program metadata property.
 typedef struct ur_program_metadata_t {
-    char *pName;                       ///< [in] null-terminated metadata name.
+    const char *pName;                 ///< [in] null-terminated metadata name.
     ur_program_metadata_type_t type;   ///< [in] the type of metadata value.
     size_t size;                       ///< [in] size in bytes of the data pointed to by value.pData, or 0 when
                                        ///< value size is less than 64-bits and is stored directly in value.data.
-    ur_program_metadata_value_t value; ///< [in] the metadata value storage.
+    ur_program_metadata_value_t value; ///< [in][tagged_by(type)] the metadata value storage.
 
 } ur_program_metadata_t;
 

scripts/YaML.md

@@ -454,6 +454,8 @@ class ur_name_flags_v(IntEnum):
   - `name` must be a unique ISO-C standard identifier, start with `$` tag, be snake_case and end with `_t`
     + The special-case descriptor struct should always end with `_desc_t`
     + The special-case property struct should always end with `_properties_t`
+* A union requires the following 
+  - `tag` is a reference to an enum type that will be used to describe which field of the union to access.
 * A struct|union may take the following optional scalar fields: {`class`, `base`, `condition`, `ordinal`, `version`}
   - `class` will be used to scope the struct|union declaration within the specified C++ class
   - `base` will be used as the base type of the structure
@@ -468,6 +470,8 @@ class ur_name_flags_v(IntEnum):
       - `out` is used for members that are write-only; if the member is a pointer, then the memory being pointed to is also write-only
       - `in,out` is used for members that are both read and write; typically this is used for pointers to other data structures that contain both read and write members
       - `nocheck` is used to specify that no additional validation checks will be generated.
+    + `desc` must also include the following annotation when describing a union: {`"tagged_by(param)"`}
+      - `tagged_by` is used to specify which parameter will be used as the tag for accessing the union.
     + `desc` may include one the following annotations: {`"[optional]"`, `"[typename(typeVarName, sizeVarName)]"`}
       - `optional` is used for members that are pointers where it is legal for the value to be `nullptr`
       - `typename` is used to denote the type enum for params that are opaque pointers to values of tagged data types.
@@ -477,6 +481,7 @@ class ur_name_flags_v(IntEnum):
     + `init` will be used to initialize the C++ struct|union member's value
     + `init` must be an ISO-C standard identifier or literal
     + `version` will be used to define the minimum API version in which the member will appear; `default="1.0"` This will also affect the order in which the member appears within the struct|union.
+    + `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
 

scripts/core/device.yml

@@ -518,16 +518,20 @@ type: union
 desc: "Device partition value."
 name: $x_device_partition_value_t
 class: $xDevice
+tag: $x_device_partition_t
 members:
     - type: uint32_t
       name: equally
       desc: "[in] Number of compute units per sub-device when partitioning with $X_DEVICE_PARTITION_EQUALLY."
+      tag: $X_DEVICE_PARTITION_EQUALLY
     - type: uint32_t
       name: count
       desc: "[in] Number of compute units in a sub-device when partitioning with $X_DEVICE_PARTITION_BY_COUNTS."
+      tag: $X_DEVICE_PARTITION_BY_COUNTS
     - type: $x_device_affinity_domain_flags_t
       name: affinity_domain
-      desc: "[in] The affinity domain to partition for when partitioning with $UR_DEVICE_PARTITION_BY_AFFINITY_DOMAIN."
+      desc: "[in] The affinity domain to partition for when partitioning with $X_DEVICE_PARTITION_BY_AFFINITY_DOMAIN."
+      tag: $X_DEVICE_PARTITION_BY_AFFINITY_DOMAIN
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Device partition property"
@@ -539,7 +543,7 @@ members:
       desc: "[in] The partitioning type to be used."
     - type: $x_device_partition_value_t
       name: value
-      desc: "[in] The partitioning value."
+      desc: "[in][tagged_by(type)] The partitioning value."
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Device Partition Properties"

scripts/core/program.yml

@@ -29,26 +29,31 @@ type: union
 desc: "Program metadata value union."
 class: $xProgram
 name: $x_program_metadata_value_t
+tag: $x_program_metadata_type_t
 members:
     - type: uint32_t
       name: data32
       desc: "[in] inline storage for the 32-bit data, type $X_PROGRAM_METADATA_TYPE_UINT32."
+      tag: $X_PROGRAM_METADATA_TYPE_UINT32
     - type: uint64_t
       name: data64
       desc: "[in] inline storage for the 64-bit data, type $X_PROGRAM_METADATA_TYPE_UINT64."
+      tag: $X_PROGRAM_METADATA_TYPE_UINT64
     - type: char*
       name: pString
       desc: "[in] pointer to null-terminated string data, type $X_PROGRAM_METADATA_TYPE_STRING."
+      tag: $X_PROGRAM_METADATA_TYPE_STRING
     - type: void*
       name: pData
       desc: "[in] pointer to binary data, type $X_PROGRAM_METADATA_TYPE_BYTE_ARRAY."
+      tag: $X_PROGRAM_METADATA_TYPE_BYTE_ARRAY
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Program metadata property."
 class: $xProgram
 name: $x_program_metadata_t
 members:
-    - type: char*
+    - type: const char*
       name: pName
       desc: "[in] null-terminated metadata name."
     - type: $x_program_metadata_type_t
@@ -59,7 +64,7 @@ members:
       desc: "[in] size in bytes of the data pointed to by value.pData, or 0 when value size is less than 64-bits and is stored directly in value.data."
     - type: $x_program_metadata_value_t
       name: value
-      desc: "[in] the metadata value storage."
+      desc: "[in][tagged_by(type)] the metadata value storage."
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Program creation properties."

scripts/parse_specs.py

@@ -292,6 +292,9 @@ def __validate_members(d, tags):
             if item['type'].endswith("flag_t"):
                 raise Exception(prefix+"'type' must not be '*_flag_t': %s"%item['type'])
 
+            if d['type'] == 'union'and item.get('tag') is None:
+                raise Exception(prefix + f"union member {item['name']} must include a 'tag' annotation")
+
             ver = __validate_version(item, prefix=prefix, base_version=d_ver)
             if ver < max_ver:
                 raise Exception(prefix+"'version' must be increasing: %s"%item['version'])
@@ -339,7 +342,11 @@ def __validate_params(d, tags):
             if ver < max_ver:
                 raise Exception(prefix+"'version' must be increasing: %s"%item['version'])
             max_ver = ver
-
+    
+    def __validate_union_tag(d):
+        if d.get('tag') is None:
+            raise Exception(f"{d['name']} must include a 'tag' part of the union.")
+        
     try:
         if 'type' not in d:
             raise Exception("every document must have 'type'")
@@ -401,6 +408,8 @@ def __validate_params(d, tags):
             if ('desc' not in d) or ('name' not in d):
                 raise Exception("'%s' requires the following scalar fields: {`desc`, `name`}"%d['type'])
 
+            if d['type'] == 'union':
+                __validate_union_tag(d)
             __validate_type(d, 'name', tags)
             __validate_base(d)
             __validate_members(d, tags)

scripts/templates/helper.py

@@ -319,6 +319,7 @@ class param_traits:
     RE_RANGE    = r".*\[range\((.+),\s*(.+)\)\][\S\s]*"
     RE_RELEASE  = r".*\[release\].*"
     RE_TYPENAME = r".*\[typename\((.+),\s(.+)\)\].*"
+    RE_TAGGED   = r".*\[tagged_by\((.+)\)].*"
 
     @classmethod
     def is_mbz(cls, item):
@@ -369,6 +370,20 @@ def is_range(cls, item):
         except:
             return False
 
+    @classmethod
+    def is_tagged(cls, item):
+        try:
+            return True if re.match(cls.RE_TAGGED, item['desc']) else False
+        except:
+            return False
+    
+    @classmethod
+    def tagged_member(cls, item):
+        try:
+            return re.sub(cls.RE_TAGGED, r"\1", item['desc'])
+        except:
+            return None
+
     @classmethod
     def range_start(cls, item):
         try:

scripts/templates/params.hpp.mako

@@ -41,6 +41,16 @@ from templates import helper as th
     %endif
 </%def>
 
+<%
+def findUnionTag(_union):
+    tag = [_obj for _s in specs for _obj in _s['objects'] if _obj['name'] == _union['tag']]
+    return tag[0] if len(tag) > 0 else None
+
+def findMemberType(_item):
+    query = [_o for _s in specs for _o in _s['objects'] if _o['name'] == _item['type']]
+    return query[0] if len(query) > 0 else None
+%>
+
 <%def name="line(item, n, params, params_dict)">
     <%
         iname = th._get_param_name(n, tags, item)
@@ -57,7 +67,7 @@ from templates import helper as th
     %if n != 0:
         os << ", ";
     %endif
-    ## can't iterate over 'void *'...
+## can't iterate over 'void *'...
     %if th.param_traits.is_range(item) and "void*" not in itype:
         os << ".${iname} = {";
         for (size_t i = ${th.param_traits.range_start(item)}; ${deref}(params${access}${pname}) != NULL && i < ${deref}params${access}${prefix + th.param_traits.range_end(item)}; ++i) {
@@ -69,6 +79,9 @@ from templates import helper as th
             </%call>
         }
         os << "}";
+    %elif findMemberType(item) is not None and findMemberType(item)['type'] == "union":
+        os << ".${iname} = ";
+        ${x}_params::serializeUnion(os, ${deref}(params${access}${item['name']}), params${access}${th.param_traits.tagged_member(item)});
     %elif typename is not None:
         os << ".${iname} = ";
         ${x}_params::serializeTagged(os, ${deref}(params${access}${pname}), ${deref}(params${access}${prefix}${typename}), ${deref}(params${access}${prefix}${typename_size}));
@@ -96,6 +109,15 @@ template <typename T> inline void serializeTagged(std::ostream &os, const void *
     %endif
 %endif
 
+%if re.match(r"union", obj['type']) and obj['name']:
+    <% tag = [_obj for _s in specs for _obj in _s['objects'] if _obj['name'] == obj['tag']][0] %>
+    inline void serializeUnion(
+        std::ostream &os,
+        const ${obj['type']} ${th.make_type_name(n, tags, obj)} params,
+        const ${tag['type']} ${th.make_type_name(n, tags, tag)} tag
+    );
+%endif
+
 
 %if th.type_traits.is_flags(obj['name']):
     template<> inline void serializeFlag<${th.make_enum_name(n, tags, obj)}>(std::ostream &os, uint32_t flag);
@@ -109,7 +131,7 @@ template <typename T> inline void serializeTagged(std::ostream &os, const void *
 ## ENUM #######################################################################
 %if re.match(r"enum", obj['type']):
     inline std::ostream &operator<<(std::ostream &os, enum ${th.make_enum_name(n, tags, obj)} value);
-%elif re.match(r"struct|union", obj['type']):
+%elif re.match(r"struct", obj['type']):
     inline std::ostream &operator<<(std::ostream &os, const ${obj['type']} ${th.make_type_name(n, tags, obj)} params);
 %endif
 %endfor # obj in spec['objects']
@@ -260,7 +282,7 @@ inline void serializeFlag<${th.make_enum_name(n, tags, obj)}>(std::ostream &os,
 } // namespace ${x}_params
 %endif
 ## STRUCT/UNION ###############################################################
-%elif re.match(r"struct|union", obj['type']):
+%elif re.match(r"struct", obj['type']):
 inline std::ostream &operator<<(std::ostream &os, const ${obj['type']} ${th.make_type_name(n, tags, obj)} params) {
     os << "(${obj['type']} ${th.make_type_name(n, tags, obj)}){";
     <%
@@ -277,6 +299,33 @@ inline std::ostream &operator<<(std::ostream &os, const ${obj['type']} ${th.make
     os << "}";
     return os;
 }
+%elif re.match(r"union", obj['type']) and obj['name']:
+<% tag = findUnionTag(obj) %>
+inline void ${x}_params::serializeUnion(
+    std::ostream &os,
+    const ${obj['type']} ${th.make_type_name(n, tags, obj)} params,
+    const ${tag['type']} ${th.make_type_name(n, tags, tag)} tag
+){
+    os << "(${obj['type']} ${th.make_type_name(n, tags, obj)}){";
+<%
+params_dict = dict()
+for item in obj['members']:
+    iname = th._get_param_name(n, tags, item)
+    itype = th._get_type_name(n, tags, obj, item)
+    params_dict[iname] = itype
+%>
+    switch(tag){
+%for mem in obj['members']:
+    case ${th.subt(n, tags, mem['tag'])}:
+        ${line(mem, 0, False, params_dict)}
+        break;
+%endfor
+    default:
+        os << "<unknown>";
+        break;
+    }
+    os << "}";
+}
 %endif
 %endfor # obj in spec['objects']
 %endfor