Merge pull request #646 from veselypeta/petr/update-enum-docs

[UR] Add documentation to experimental feature support
oneapi-src · Jun 26, 2023 · 52c98d0 · 52c98d0
2 parents c7b0caf + e1de661
commit 52c98d0
Show file tree

Hide file tree

Showing 5 changed files with 22 additions and 3 deletions.
diff --git a/include/ur.py b/include/ur.py
@@ -158,7 +158,8 @@ class ur_result_v(IntEnum):
  ERROR_IMAGE_FORMAT_NOT_SUPPORTED = 35 ## Image format not supported
  ERROR_MEM_OBJECT_ALLOCATION_FAILURE = 36 ## Memory object allocation failure
  ERROR_INVALID_PROGRAM_EXECUTABLE = 37 ## Program object parameter is invalid.
- ERROR_UNINITIALIZED = 38 ## [Validation] adapter is not initialized
+ ERROR_UNINITIALIZED = 38 ## [Validation] adapter is not initialized or specific entry-point is not
+ ## implemented
  ERROR_OUT_OF_HOST_MEMORY = 39 ## Insufficient host memory to satisfy call
  ERROR_OUT_OF_DEVICE_MEMORY = 40 ## Insufficient device memory to satisfy call
  ERROR_OUT_OF_RESOURCES = 41 ## Out of resources

diff --git a/include/ur_api.h b/include/ur_api.h
@@ -181,7 +181,8 @@ typedef enum ur_result_t {
  UR_RESULT_ERROR_IMAGE_FORMAT_NOT_SUPPORTED = 35, ///< Image format not supported
  UR_RESULT_ERROR_MEM_OBJECT_ALLOCATION_FAILURE = 36, ///< Memory object allocation failure
  UR_RESULT_ERROR_INVALID_PROGRAM_EXECUTABLE = 37, ///< Program object parameter is invalid.
- UR_RESULT_ERROR_UNINITIALIZED = 38, ///< [Validation] adapter is not initialized
+ UR_RESULT_ERROR_UNINITIALIZED = 38, ///< [Validation] adapter is not initialized or specific entry-point is not
+ ///< implemented
  UR_RESULT_ERROR_OUT_OF_HOST_MEMORY = 39, ///< Insufficient host memory to satisfy call
  UR_RESULT_ERROR_OUT_OF_DEVICE_MEMORY = 40, ///< Insufficient device memory to satisfy call
  UR_RESULT_ERROR_OUT_OF_RESOURCES = 41, ///< Out of resources

diff --git a/scripts/core/common.yml b/scripts/core/common.yml
@@ -201,7 +201,7 @@ etors:
  - name: ERROR_INVALID_PROGRAM_EXECUTABLE
  desc: "Program object parameter is invalid."
  - name: ERROR_UNINITIALIZED
- desc: "[Validation] adapter is not initialized"
+ desc: "[Validation] adapter is not initialized or specific entry-point is not implemented"
  - name: ERROR_OUT_OF_HOST_MEMORY
  desc: "Insufficient host memory to satisfy call"
  - name: ERROR_OUT_OF_DEVICE_MEMORY

diff --git a/scripts/templates/exp_feat.rst.mako b/scripts/templates/exp_feat.rst.mako
@@ -70,6 +70,16 @@ Changelog
 | 1.0 | Initial Draft |
 +-----------+------------------------+
 
+Support
+--------------------------------------------------------------------------------
+
+Adapters which support this experimental feature *must* return the valid string 
+defined in ``${"${X}"}_${"_".join(name.split("-")).upper()}_EXTENSION_STRING_EXP`` 
+as one of the options from ${"${x}"}DeviceGetInfo when querying for 
+${"${X}"}_DEVICE_INFO_EXTENSIONS. Conversly, before using any of the 
+functionality defined in this experimental feature the user *must* use the 
+device query to determine if the adapter supports this feature.
+
 Contributors
 --------------------------------------------------------------------------------
 .. comment:

diff --git a/scripts/templates/exp_feat.yml.mako b/scripts/templates/exp_feat.yml.mako
@@ -17,3 +17,10 @@ import datetime
 type: header
 desc: "Intel $OneApi Unified Runtime Experimental APIs for ${" ".join(name.split("-")).title()}"
 ordinal: "99"
+--- #--------------------------------------------------------------------------
+type: macro
+desc: |
+ The extension string which defines support for ${name}
+ which is returned when querying device extensions.
+name: $X_${"_".join(name.split("-")).upper()}_EXTENSION_STRING_EXP
+value: "\"$x_exp_${"_".join(name.split("-"))}\""