Clarify that warnings are optional

oneapi-src · Nov 28, 2023 · 64765ea · 64765ea
1 parent 8c798b2
commit 64765ea
Show file tree

Hide file tree

Showing 4 changed files with 12 additions and 0 deletions.
diff --git a/include/ur_api.h b/include/ur_api.h
@@ -859,6 +859,9 @@ urAdapterRetain(
 /// represents a warning instead. This means that the entry-point call did not
 /// fail. However it might not have behaved as expected.
 ///
+/// * Using ::UR_RESULT_ERROR_ADAPTER_SPECIFIC to emit warnings is an optional
+/// feature. Its usage is left at the discretion of adapter maintainers.
+///
 /// * Implementations *must* store the message and error code in thread-local
 ///   storage prior to returning ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
 ///

diff --git a/scripts/core/adapter.yml b/scripts/core/adapter.yml
@@ -83,6 +83,9 @@ details: |
     * If `pError` is $X_RESULT_SUCCESS, $X_RESULT_ERROR_ADAPTER_SPECIFIC
     represents a warning instead. This means that the entry-point call did not
     fail. However it might not have behaved as expected.
+  
+    * Using $X_RESULT_ERROR_ADAPTER_SPECIFIC to emit warnings is an optional
+    feature. Its usage is left at the discretion of adapter maintainers.
 
     * Implementations *must* store the message and error code in thread-local
       storage prior to returning $X_RESULT_ERROR_ADAPTER_SPECIFIC.

diff --git a/source/loader/ur_libapi.cpp b/source/loader/ur_libapi.cpp
@@ -365,6 +365,9 @@ ur_result_t UR_APICALL urAdapterRetain(
 /// represents a warning instead. This means that the entry-point call did not
 /// fail. However it might not have behaved as expected.
 ///
+/// * Using ::UR_RESULT_ERROR_ADAPTER_SPECIFIC to emit warnings is an optional
+/// feature. Its usage is left at the discretion of adapter maintainers.
+///
 /// * Implementations *must* store the message and error code in thread-local
 ///   storage prior to returning ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
 ///

diff --git a/source/ur_api.cpp b/source/ur_api.cpp
@@ -323,6 +323,9 @@ ur_result_t UR_APICALL urAdapterRetain(
 /// represents a warning instead. This means that the entry-point call did not
 /// fail. However it might not have behaved as expected.
 ///
+/// * Using ::UR_RESULT_ERROR_ADAPTER_SPECIFIC to emit warnings is an optional
+/// feature. Its usage is left at the discretion of adapter maintainers.
+///
 /// * Implementations *must* store the message and error code in thread-local
 ///   storage prior to returning ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
 ///