Merge pull request #626 from veselypeta/petr/606/extend-enums

[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