[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 should set the `extend` field 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"

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;