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] 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. ///