[SPEC] Clarify the behaviour of UR warning messages

* This commits updates the specification to clarify the behaviour
of UR_RESULT_ERROR_ADAPTER_SPECIFIC when returning warning messages.
* This is a temporary change until we add specific error codes
for warnings.

include/ur_api.h

@@ -847,14 +847,18 @@ urAdapterRetain(
 );
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Get the last adapter specific error.
+/// @brief Get the last adapter specific warning or error.
 ///
 /// @details
 /// To be used after another entry-point has returned
 /// ::UR_RESULT_ERROR_ADAPTER_SPECIFIC in order to retrieve a message describing
 /// the circumstances of the underlying driver error and the error code
 /// returned by the failed driver entry-point.
 ///
+/// * If `pError` is ::UR_RESULT_SUCCESS, ::UR_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.
+///
 /// * Implementations *must* store the message and error code in thread-local
 ///   storage prior to returning ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
 ///

scripts/core/adapter.yml

@@ -73,12 +73,16 @@ params:
           [in] Adapter handle to retain
 --- #--------------------------------------------------------------------------
 type: function
-desc: "Get the last adapter specific error."
+desc: "Get the last adapter specific warning or error."
 details: |
     To be used after another entry-point has returned
     $X_RESULT_ERROR_ADAPTER_SPECIFIC in order to retrieve a message describing
     the circumstances of the underlying driver error and the error code
     returned by the failed driver entry-point.
+  
+    * 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.
 
     * Implementations *must* store the message and error code in thread-local
       storage prior to returning $X_RESULT_ERROR_ADAPTER_SPECIFIC.

source/loader/ur_libapi.cpp

@@ -353,14 +353,18 @@ ur_result_t UR_APICALL urAdapterRetain(
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Get the last adapter specific error.
+/// @brief Get the last adapter specific warning or error.
 ///
 /// @details
 /// To be used after another entry-point has returned
 /// ::UR_RESULT_ERROR_ADAPTER_SPECIFIC in order to retrieve a message describing
 /// the circumstances of the underlying driver error and the error code
 /// returned by the failed driver entry-point.
 ///
+/// * If `pError` is ::UR_RESULT_SUCCESS, ::UR_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.
+///
 /// * Implementations *must* store the message and error code in thread-local
 ///   storage prior to returning ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
 ///

source/ur_api.cpp

@@ -311,14 +311,18 @@ ur_result_t UR_APICALL urAdapterRetain(
 }
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Get the last adapter specific error.
+/// @brief Get the last adapter specific warning or error.
 ///
 /// @details
 /// To be used after another entry-point has returned
 /// ::UR_RESULT_ERROR_ADAPTER_SPECIFIC in order to retrieve a message describing
 /// the circumstances of the underlying driver error and the error code
 /// returned by the failed driver entry-point.
 ///
+/// * If `pError` is ::UR_RESULT_SUCCESS, ::UR_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.
+///
 /// * Implementations *must* store the message and error code in thread-local
 ///   storage prior to returning ::UR_RESULT_ERROR_ADAPTER_SPECIFIC.
 ///