[UR] use 'extend' to outline extended enums

include/ur.py

@@ -197,11 +197,8 @@ class ur_result_v(IntEnum):
  ERROR_ADAPTER_SPECIFIC = 67 ## An adapter specific warning/error has been reported and can be
  ## retrieved via the urPlatformGetLastError entry point.
  ERROR_INVALID_COMMAND_BUFFER_EXP = 0x1000 ## Invalid Command-Buffer
- ERROR_INVALID_COMMAND_BUFFER_EXP = 0x1000 ## Invalid Command-Buffer
- ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP = 0x1001## Sync point is not valid for the command-buffer
  ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP = 0x1001## Sync point is not valid for the command-buffer
  ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP = 0x1002 ## Sync point wait list is invalid
- ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP = 0x1002 ## Sync point wait list is invalid
  ERROR_UNKNOWN = 0x7ffffffe ## Unknown or internal error
 
 class ur_result_t(c_int):

include/ur_api.h

@@ -220,11 +220,8 @@ typedef enum ur_result_t {
  UR_RESULT_ERROR_ADAPTER_SPECIFIC = 67, ///< An adapter specific warning/error has been reported and can be
  ///< retrieved via the urPlatformGetLastError entry point.
  UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP = 0x1000, ///< Invalid Command-Buffer
- UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP = 0x1000, ///< Invalid Command-Buffer
- UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP = 0x1001, ///< Sync point is not valid for the command-buffer
  UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP = 0x1001, ///< Sync point is not valid for the command-buffer
  UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP = 0x1002, ///< Sync point wait list is invalid
- UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP = 0x1002, ///< Sync point wait list is invalid
  UR_RESULT_ERROR_UNKNOWN = 0x7ffffffe, ///< Unknown or internal error
  /// @cond
  UR_RESULT_FORCE_UINT32 = 0x7fffffff

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,14 @@ 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 you should you should set the `extend` field to true and 
+list extension enumerations required. 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"

scripts/parse_specs.py

@@ -221,6 +221,9 @@ def __validate_etors(d, tags):
  if ('desc' not in item) or ('name' not in item):
  raise Exception(prefix+"requires the following scalar fields: {`desc`, `name`}")
 
+ if 'extend' in d and d.get('extend') == True and 'value' not in item:
+ raise Exception(prefix+"must include a value for experimental features: {`value`: `0xabcd`}")
+
  if typed:
  type = extract_type(item['desc'])
  if type is None:

source/common/ur_params.hpp

@@ -651,14 +651,6 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_result_t value) {
  os << "UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP";
  break;
 
- case UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP:
- os << "UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_EXP";
- break;
-
- case UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP:
- os << "UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP";
- break;
-
  case UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP:
  os << "UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_EXP";
  break;
@@ -667,10 +659,6 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_result_t value) {
  os << "UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP";
  break;
 
- case UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP:
- os << "UR_RESULT_ERROR_INVALID_COMMAND_BUFFER_SYNC_POINT_WAIT_LIST_EXP";
- break;
-
  case UR_RESULT_ERROR_UNKNOWN:
  os << "UR_RESULT_ERROR_UNKNOWN";
  break;