From 8c798b286b9211bf216ecc3db684b5c611c09c55 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A1bio=20Mestre?= Date: Thu, 9 Nov 2023 15:06:37 +0000 Subject: [PATCH 1/3] [SPEC] Clarify the behaviour of UR warning messages * This commit updates the specification to clarify the behaviour of UR_RESULT_ERROR_ADAPTER_SPECIFIC when returning warning messages. * This is a temporary change until specific error codes for warnings are added. --- include/ur_api.h | 6 +++++- scripts/core/adapter.yml | 6 +++++- source/loader/ur_libapi.cpp | 6 +++++- source/ur_api.cpp | 6 +++++- 4 files changed, 20 insertions(+), 4 deletions(-) diff --git a/include/ur_api.h b/include/ur_api.h index 6fff45c249..2e9569dda0 100644 --- a/include/ur_api.h +++ b/include/ur_api.h @@ -847,7 +847,7 @@ 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 @@ -855,6 +855,10 @@ urAdapterRetain( /// 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. /// diff --git a/scripts/core/adapter.yml b/scripts/core/adapter.yml index a2331244e1..63ffa42106 100644 --- a/scripts/core/adapter.yml +++ b/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. diff --git a/source/loader/ur_libapi.cpp b/source/loader/ur_libapi.cpp index de9e029536..46bd0e2174 100644 --- a/source/loader/ur_libapi.cpp +++ b/source/loader/ur_libapi.cpp @@ -353,7 +353,7 @@ 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 @@ -361,6 +361,10 @@ ur_result_t UR_APICALL urAdapterRetain( /// 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. /// diff --git a/source/ur_api.cpp b/source/ur_api.cpp index 85cc45d246..3515abbfbf 100644 --- a/source/ur_api.cpp +++ b/source/ur_api.cpp @@ -311,7 +311,7 @@ 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 @@ -319,6 +319,10 @@ ur_result_t UR_APICALL urAdapterRetain( /// 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. /// From 64765ea622a3c6c5ab703f8c34eccbfa9c5d93cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A1bio=20Mestre?= Date: Tue, 28 Nov 2023 15:34:13 +0000 Subject: [PATCH 2/3] Clarify that warnings are optional --- include/ur_api.h | 3 +++ scripts/core/adapter.yml | 3 +++ source/loader/ur_libapi.cpp | 3 +++ source/ur_api.cpp | 3 +++ 4 files changed, 12 insertions(+) diff --git a/include/ur_api.h b/include/ur_api.h index 2e9569dda0..0f21b96a83 100644 --- 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 index 63ffa42106..383dee733a 100644 --- 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 index 46bd0e2174..739d42bd47 100644 --- 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 index 3515abbfbf..6eed7151bb 100644 --- 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. /// From e5dd7bd8a8b627f5284d81c02b24da3e98aa5f65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A1bio=20Mestre?= Date: Wed, 29 Nov 2023 11:43:53 +0000 Subject: [PATCH 3/3] Fix indentation --- include/ur_api.h | 6 +++--- scripts/core/adapter.yml | 6 +++--- source/loader/ur_libapi.cpp | 6 +++--- source/ur_api.cpp | 6 +++--- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/include/ur_api.h b/include/ur_api.h index 0f21b96a83..588207bc6e 100644 --- a/include/ur_api.h +++ b/include/ur_api.h @@ -856,11 +856,11 @@ urAdapterRetain( /// 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. +/// 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. +/// 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 index 383dee733a..dbcd9bf5b7 100644 --- a/scripts/core/adapter.yml +++ b/scripts/core/adapter.yml @@ -81,11 +81,11 @@ details: | 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. + 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. + 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 index 739d42bd47..692a7e6ae5 100644 --- a/source/loader/ur_libapi.cpp +++ b/source/loader/ur_libapi.cpp @@ -362,11 +362,11 @@ ur_result_t UR_APICALL urAdapterRetain( /// 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. +/// 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. +/// 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 index 6eed7151bb..7aa55f4a2b 100644 --- a/source/ur_api.cpp +++ b/source/ur_api.cpp @@ -320,11 +320,11 @@ ur_result_t UR_APICALL urAdapterRetain( /// 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. +/// 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. +/// 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.