[UR] Allow for extending enums

include/ur.py

@@ -236,10 +236,10 @@ class ur_structure_type_v(IntEnum):
     SAMPLER_NATIVE_PROPERTIES = 24                  ## ::ur_sampler_native_properties_t
     QUEUE_NATIVE_DESC = 25                          ## ::ur_queue_native_desc_t
     DEVICE_PARTITION_PROPERTIES = 26                ## ::ur_device_partition_properties_t
-    EXP_COMMAND_BUFFER_DESC = 27                    ## ::ur_exp_command_buffer_desc_t
-    EXP_SAMPLER_MIP_PROPERTIES = 28                 ## ::ur_exp_sampler_mip_properties_t
-    KERNEL_ARG_MEM_OBJ_PROPERTIES = 29              ## ::ur_kernel_arg_mem_obj_properties_t
-    PHYSICAL_MEM_PROPERTIES = 30                    ## ::ur_physical_mem_properties_t
+    KERNEL_ARG_MEM_OBJ_PROPERTIES = 27              ## ::ur_kernel_arg_mem_obj_properties_t
+    PHYSICAL_MEM_PROPERTIES = 28                    ## ::ur_physical_mem_properties_t
+    EXP_COMMAND_BUFFER_DESC = 0x1000                ## ::ur_exp_command_buffer_desc_t
+    EXP_SAMPLER_MIP_PROPERTIES = 0x2000             ## ::ur_exp_sampler_mip_properties_t
 
 class ur_structure_type_t(c_int):
     def __str__(self):
@@ -1724,7 +1724,7 @@ class ur_command_v(IntEnum):
     DEVICE_GLOBAL_VARIABLE_READ = 24                ## Event created by ::urEnqueueDeviceGlobalVariableRead
     READ_HOST_PIPE = 25                             ## Event created by ::urEnqueueReadHostPipe
     WRITE_HOST_PIPE = 26                            ## Event created by ::urEnqueueWriteHostPipe
-    COMMAND_BUFFER_ENQUEUE_EXP = 27                 ## Event created by ::urCommandBufferEnqueueExp
+    COMMAND_BUFFER_ENQUEUE_EXP = 0x1000             ## Event created by ::urCommandBufferEnqueueExp
     INTEROP_SEMAPHORE_WAIT_EXP = 0x2000             ## Event created by ::urBindlessImagesWaitExternalSemaphoreExp
     INTEROP_SEMAPHORE_SIGNAL_EXP = 0x2001           ## Event created by ::urBindlessImagesSignalExternalSemaphoreExp
 

include/ur_api.h

@@ -259,10 +259,10 @@ typedef enum ur_structure_type_t {
     UR_STRUCTURE_TYPE_SAMPLER_NATIVE_PROPERTIES = 24,       ///< ::ur_sampler_native_properties_t
     UR_STRUCTURE_TYPE_QUEUE_NATIVE_DESC = 25,               ///< ::ur_queue_native_desc_t
     UR_STRUCTURE_TYPE_DEVICE_PARTITION_PROPERTIES = 26,     ///< ::ur_device_partition_properties_t
-    UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC = 27,         ///< ::ur_exp_command_buffer_desc_t
-    UR_STRUCTURE_TYPE_EXP_SAMPLER_MIP_PROPERTIES = 28,      ///< ::ur_exp_sampler_mip_properties_t
-    UR_STRUCTURE_TYPE_KERNEL_ARG_MEM_OBJ_PROPERTIES = 29,   ///< ::ur_kernel_arg_mem_obj_properties_t
-    UR_STRUCTURE_TYPE_PHYSICAL_MEM_PROPERTIES = 30,         ///< ::ur_physical_mem_properties_t
+    UR_STRUCTURE_TYPE_KERNEL_ARG_MEM_OBJ_PROPERTIES = 27,   ///< ::ur_kernel_arg_mem_obj_properties_t
+    UR_STRUCTURE_TYPE_PHYSICAL_MEM_PROPERTIES = 28,         ///< ::ur_physical_mem_properties_t
+    UR_STRUCTURE_TYPE_EXP_COMMAND_BUFFER_DESC = 0x1000,     ///< ::ur_exp_command_buffer_desc_t
+    UR_STRUCTURE_TYPE_EXP_SAMPLER_MIP_PROPERTIES = 0x2000,  ///< ::ur_exp_sampler_mip_properties_t
     /// @cond
     UR_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -4689,7 +4689,7 @@ typedef enum ur_command_t {
     UR_COMMAND_DEVICE_GLOBAL_VARIABLE_READ = 24,      ///< Event created by ::urEnqueueDeviceGlobalVariableRead
     UR_COMMAND_READ_HOST_PIPE = 25,                   ///< Event created by ::urEnqueueReadHostPipe
     UR_COMMAND_WRITE_HOST_PIPE = 26,                  ///< Event created by ::urEnqueueWriteHostPipe
-    UR_COMMAND_COMMAND_BUFFER_ENQUEUE_EXP = 27,       ///< Event created by ::urCommandBufferEnqueueExp
+    UR_COMMAND_COMMAND_BUFFER_ENQUEUE_EXP = 0x1000,   ///< Event created by ::urCommandBufferEnqueueExp
     UR_COMMAND_INTEROP_SEMAPHORE_WAIT_EXP = 0x2000,   ///< Event created by ::urBindlessImagesWaitExternalSemaphoreExp
     UR_COMMAND_INTEROP_SEMAPHORE_SIGNAL_EXP = 0x2001, ///< Event created by ::urBindlessImagesSignalExternalSemaphoreExp
     /// @cond

scripts/YaML.md

@@ -318,11 +318,14 @@ class ur_name_handle_t(c_void_p):
   - `desc` will be used as the enum's description comment
   - `name` must be a unique ISO-C standard identifier, start with `$` tag, be snake_case and end with `_t`
   - `name` that endswith `_flags_t` will be used to create bitfields
-* An enum may take the following optional scalar fields: {`class`, `condition`, `ordinal`, `version`, `typed_etors`}
+* An enum may take the following optional scalar fields: {`class`, `condition`, `ordinal`, `version`, `typed_etors`, `extend`}
   - `class` will be used to scope the enum declaration within the specified C++ class
   - `condition` will be used as a C/C++ preprocessor `#if` conditional expression
   - `ordinal` will be used to override the default order (in which they appear) the enum appears within its section; `default="1000"`
   - `version` will be used to define the minimum API version in which the enum will appear; `default="1.0"` This will also affect the order in which the enum appears within its section and class.
+  - `extend` will be used to extend an existing enum with additional `etors`, 
+  usually used to implement experimental features. `type` *must* refer to an 
+  exiting enum and each `etor` must include a unique `value`.
   - `typed_etors` boolean value that will be used to determine whether the enum's values have associated types.
 * An enum requires the following sequence of mappings: {`etors`}
   - An etor requires the following scalar fields: {`name`, `desc`}

scripts/core/CONTRIB.rst

@@ -216,6 +216,15 @@ implement your experimental feature.
     $ python scripts/add_experimental_feature.py <name-of-your-experimental-feature>
 
 
+Experimental features *must* not make any changes to the core YaML files and 
+*must* be described entirely in their own YaML file. Sometimes, however 
+experimental feature require extending enumerations of the core specification. 
+If this is necessary, create a new enum with the ``extend`` field set to true 
+and list the required enumerations to support the experimental feature. These 
+additional enumerations will updated the specification with the appropriate 
+values.
+
+
 Naming Convention
 -----------------
 

scripts/core/common.yml

@@ -261,15 +261,6 @@ etors:
     - name: ERROR_ADAPTER_SPECIFIC
       desc: "An adapter specific warning/error has been reported and can be retrieved
              via the urPlatformGetLastError entry point."
-    - name: ERROR_INVALID_COMMAND_BUFFER_EXP
-      value: "0x1000"
-      desc: "Invalid Command-Buffer"
-    - name: ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
-      value: "0x1001"
-      desc: "Sync point is not valid for the command-buffer"
-    - name: ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP
-      value: "0x1002"
-      desc: "Sync point wait list is invalid"
     - name: ERROR_UNKNOWN
       value: "0x7ffffffe"
       desc: "Unknown or internal error"
@@ -332,10 +323,6 @@ etors:
       desc: $x_queue_native_desc_t
     - name: DEVICE_PARTITION_PROPERTIES
       desc: $x_device_partition_properties_t
-    - name: EXP_COMMAND_BUFFER_DESC
-      desc: $x_exp_command_buffer_desc_t
-    - name: EXP_SAMPLER_MIP_PROPERTIES
-      desc: $x_exp_sampler_mip_properties_t
     - name: KERNEL_ARG_MEM_OBJ_PROPERTIES
       desc: $x_kernel_arg_mem_obj_properties_t
     - name: PHYSICAL_MEM_PROPERTIES

scripts/core/device.yml

@@ -383,54 +383,6 @@ etors:
       desc: "[uint32_t] 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."
-    - name: BINDLESS_IMAGES_SUPPORT_EXP
-      value: "0x2000"
-      desc: "[$x_bool_t] returns true if the device supports the creation of bindless images"
-    - name: BINDLESS_IMAGES_1D_USM_SUPPORT_EXP
-      value: "0x2001"
-      desc: "[$x_bool_t] returns true if the device supports the creation of 1D bindless images backed by USM"
-    - name: BINDLESS_IMAGES_2D_USM_SUPPORT_EXP
-      value: "0x2002"
-      desc: "[$x_bool_t] returns true if the device supports the creation of 2D bindless images backed by USM"
-    - name: BINDLESS_IMAGES_3D_USM_SUPPORT_EXP
-      value: "0x2003"
-      desc: "[$x_bool_t] returns true if the device supports the creation of 3D bindless images backed by USM"
-    - name: IMAGE_PITCH_ALIGN_EXP
-      value: "0x2004"
-      desc: "[uint32_t] returns the required alignment of the pitch between two rows of an image in bytes"
-    - name: MAX_IMAGE_LINEAR_WIDTH_EXP
-      value: "0x2005"
-      desc: "[size_t] returns the maximum linear width allowed for images allocated using USM"
-    - name: MAX_IMAGE_LINEAR_HEIGHT_EXP
-      value: "0x2006"
-      desc: "[size_t] returns the maximum linear height allowed for images allocated using USM"
-    - name: MAX_IMAGE_LINEAR_PITCH_EXP
-      value: "0x2007"
-      desc: "[size_t] returns the maximum linear pitch allowed for images allocated using USM"
-    - name: MIPMAP_SUPPORT_EXP
-      value: "0x2008"
-      desc: "[$x_bool_t] returns true if the device supports allocating mipmap resources"
-    - name: MIPMAP_ANISOTROPY_SUPPORT_EXP
-      value: "0x2009"
-      desc: "[$x_bool_t] returns true if the device supports sampling mipmap images with anisotropic filtering"
-    - name: MIPMAP_MAX_ANISOTROPY_EXP
-      value: "0x200A"
-      desc: "[uint32_t] returns the maximum anisotropic ratio supported by the device"
-    - name: MIPMAP_LEVEL_REFERENCE_SUPPORT_EXP
-      value: "0x200B"
-      desc: "[$x_bool_t] returns true if the device supports using images created from individual mipmap levels"
-    - name: INTEROP_MEMORY_IMPORT_SUPPORT_EXP
-      value: "0x200C"
-      desc: "[$x_bool_t] returns true if the device supports importing external memory resources"
-    - name: INTEROP_MEMORY_EXPORT_SUPPORT_EXP
-      value: "0x200D"
-      desc: "[$x_bool_t] returns true if the device supports exporting internal memory resources"
-    - name: INTEROP_SEMAPHORE_IMPORT_SUPPORT_EXP
-      value: "0x200E"
-      desc: "[$x_bool_t] returns true if the device supports importing external semaphore resources"
-    - name: INTEROP_SEMAPHORE_EXPORT_SUPPORT_EXP
-      value: "0x200F"
-      desc: "[$x_bool_t] returns true if the device supports exporting internal event resources"
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Retrieves various information about device"

scripts/core/event.yml

@@ -73,14 +73,6 @@ etors:
       desc: Event created by $xEnqueueReadHostPipe
     - name: WRITE_HOST_PIPE
       desc: Event created by $xEnqueueWriteHostPipe
-    - name: COMMAND_BUFFER_ENQUEUE_EXP
-      desc: Event created by $xCommandBufferEnqueueExp
-    - name: INTEROP_SEMAPHORE_WAIT_EXP
-      value: "0x2000"
-      desc: Event created by $xBindlessImagesWaitExternalSemaphoreExp
-    - name: INTEROP_SEMAPHORE_SIGNAL_EXP
-      value: "0x2001"
-      desc: Event created by $xBindlessImagesSignalExternalSemaphoreExp
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Event Status"

scripts/core/exp-bindless-images.yml

@@ -24,6 +24,82 @@ class: $xBindlessImages
 name: "$x_exp_interop_semaphore_handle_t"
 --- #--------------------------------------------------------------------------
 type: enum
+extend: true
+typed_etors: true
+desc: "Extension enums to $x_device_info_t to support bindless images."
+name: $x_device_info_t
+etors: 
+    - name: BINDLESS_IMAGES_SUPPORT_EXP
+      value: "0x2000"
+      desc: "[$x_bool_t] returns true if the device supports the creation of bindless images"
+    - name: BINDLESS_IMAGES_1D_USM_SUPPORT_EXP
+      value: "0x2001"
+      desc: "[$x_bool_t] returns true if the device supports the creation of 1D bindless images backed by USM"
+    - name: BINDLESS_IMAGES_2D_USM_SUPPORT_EXP
+      value: "0x2002"
+      desc: "[$x_bool_t] returns true if the device supports the creation of 2D bindless images backed by USM"
+    - name: BINDLESS_IMAGES_3D_USM_SUPPORT_EXP
+      value: "0x2003"
+      desc: "[$x_bool_t] returns true if the device supports the creation of 3D bindless images backed by USM"
+    - name: IMAGE_PITCH_ALIGN_EXP
+      value: "0x2004"
+      desc: "[uint32_t] returns the required alignment of the pitch between two rows of an image in bytes"
+    - name: MAX_IMAGE_LINEAR_WIDTH_EXP
+      value: "0x2005"
+      desc: "[size_t] returns the maximum linear width allowed for images allocated using USM"
+    - name: MAX_IMAGE_LINEAR_HEIGHT_EXP
+      value: "0x2006"
+      desc: "[size_t] returns the maximum linear height allowed for images allocated using USM"
+    - name: MAX_IMAGE_LINEAR_PITCH_EXP
+      value: "0x2007"
+      desc: "[size_t] returns the maximum linear pitch allowed for images allocated using USM"
+    - name: MIPMAP_SUPPORT_EXP
+      value: "0x2008"
+      desc: "[$x_bool_t] returns true if the device supports allocating mipmap resources"
+    - name: MIPMAP_ANISOTROPY_SUPPORT_EXP
+      value: "0x2009"
+      desc: "[$x_bool_t] returns true if the device supports sampling mipmap images with anisotropic filtering"
+    - name: MIPMAP_MAX_ANISOTROPY_EXP
+      value: "0x200A"
+      desc: "[uint32_t] returns the maximum anisotropic ratio supported by the device"
+    - name: MIPMAP_LEVEL_REFERENCE_SUPPORT_EXP
+      value: "0x200B"
+      desc: "[$x_bool_t] returns true if the device supports using images created from individual mipmap levels"
+    - name: INTEROP_MEMORY_IMPORT_SUPPORT_EXP
+      value: "0x200C"
+      desc: "[$x_bool_t] returns true if the device supports importing external memory resources"
+    - name: INTEROP_MEMORY_EXPORT_SUPPORT_EXP
+      value: "0x200D"
+      desc: "[$x_bool_t] returns true if the device supports exporting internal memory resources"
+    - name: INTEROP_SEMAPHORE_IMPORT_SUPPORT_EXP
+      value: "0x200E"
+      desc: "[$x_bool_t] returns true if the device supports importing external semaphore resources"
+    - name: INTEROP_SEMAPHORE_EXPORT_SUPPORT_EXP
+      value: "0x200F"
+      desc: "[$x_bool_t] returns true if the device supports exporting internal event resources"
+--- #--------------------------------------------------------------------------
+type: enum
+extend: true
+desc: "Structure Type experimental enumerations."
+name: $x_structure_type_t
+etors: 
+    - name: EXP_SAMPLER_MIP_PROPERTIES
+      desc: $x_exp_sampler_mip_properties_t
+      value: "0x2000"
+--- #--------------------------------------------------------------------------
+type: enum
+extend: true
+desc: "Command Type experimental enumerations."
+name: $x_command_t
+etors:
+    - name: INTEROP_SEMAPHORE_WAIT_EXP
+      value: "0x2000"
+      desc: Event created by $xBindlessImagesWaitExternalSemaphoreExp
+    - name: INTEROP_SEMAPHORE_SIGNAL_EXP
+      value: "0x2001"
+      desc: Event created by $xBindlessImagesSignalExternalSemaphoreExp
+--- #--------------------------------------------------------------------------
+type: enum
 desc: "Dictates the type of memory copy."
 class: $xBindlessImages
 name: $x_exp_image_copy_flags_t

scripts/core/exp-command-buffer.yml

@@ -12,6 +12,39 @@ type: header
 desc: "Intel $OneApi Unified Runtime Experimental APIs for Command-Buffers"
 ordinal: "99"
 --- #--------------------------------------------------------------------------
+type: enum
+extend: true
+desc: "Experimental Command Buffer result type enums."
+name: $x_result_t
+etors:
+    - name: ERROR_INVALID_COMMAND_BUFFER_EXP
+      value: "0x1000"
+      desc: "Invalid Command-Buffer"
+    - name: ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP
+      value: "0x1001"
+      desc: "Sync point is not valid for the command-buffer"
+    - name: ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP
+      value: "0x1002"
+      desc: "Sync point wait list is invalid"
+--- #--------------------------------------------------------------------------
+type: enum
+extend: true
+desc: "Extend enumeration of Command Buffer Structure Type."
+name: $x_structure_type_t
+etors:
+    - name: EXP_COMMAND_BUFFER_DESC
+      desc: $x_exp_command_buffer_desc_t
+      value: "0x1000"
+--- #--------------------------------------------------------------------------
+type: enum
+extend: true
+desc: "Extend command type enumeration for Command-Buffer experimental feature."
+name: $x_command_t
+etors:
+    - name: COMMAND_BUFFER_ENQUEUE_EXP
+      desc: Event created by $xCommandBufferEnqueueExp
+      value: "0x1000"
+--- #--------------------------------------------------------------------------
 type: macro
 desc: "The extension string which defines support for command-buffers which is returned when querying device extensions."
 name: $X_COMMAND_BUFFER_EXTENSION_STRING_EXP