From 125b996f2c575e2bca162e8900b0640b939f9d07 Mon Sep 17 00:00:00 2001 From: Petr Vesely Date: Mon, 19 Jun 2023 14:41:32 +0100 Subject: [PATCH] [UR] use 'extend' to outline extended enums --- include/ur.py | 3 --- include/ur_api.h | 3 --- scripts/YaML.md | 5 ++++- scripts/core/CONTRIB.rst | 8 ++++++++ scripts/core/common.yml | 9 --------- scripts/parse_specs.py | 3 +++ source/common/ur_params.hpp | 12 ------------ 7 files changed, 15 insertions(+), 28 deletions(-) diff --git a/include/ur.py b/include/ur.py index 8fc14440a5..8f3f2d53bf 100644 --- a/include/ur.py +++ b/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): diff --git a/include/ur_api.h b/include/ur_api.h index b3712e43b1..26dcaae6d1 100644 --- a/include/ur_api.h +++ b/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 diff --git a/scripts/YaML.md b/scripts/YaML.md index 3dddf45443..bbd1e76e0d 100644 --- a/scripts/YaML.md +++ b/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`} diff --git a/scripts/core/CONTRIB.rst b/scripts/core/CONTRIB.rst index 0cf2532855..c483ce8b18 100644 --- a/scripts/core/CONTRIB.rst +++ b/scripts/core/CONTRIB.rst @@ -216,6 +216,14 @@ implement your experimental feature. $ python scripts/add_experimental_feature.py +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 ----------------- diff --git a/scripts/core/common.yml b/scripts/core/common.yml index c3808b7a15..cbf8cb7a68 100644 --- a/scripts/core/common.yml +++ b/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" diff --git a/scripts/parse_specs.py b/scripts/parse_specs.py index df90cd1be1..cb3c8ddd2f 100644 --- a/scripts/parse_specs.py +++ b/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: diff --git a/source/common/ur_params.hpp b/source/common/ur_params.hpp index 9cbfdf0671..fedb5ffb1e 100644 --- a/source/common/ur_params.hpp +++ b/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;