Clarify the behaviour of urUSMMemAdvise and urUSMPrefetch when the hint is unsupported (#854)

Author: fabiomestre

include/ur_api.h

@@ -6627,6 +6627,11 @@ urEnqueueUSMMemcpy(
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Enqueue a command to prefetch USM memory
 ///
+/// @details
+///     - Prefetching may not be supported for all devices or allocation types.
+///       If memory prefetching is not supported, the prefetch hint will be
+///       ignored.
+///
 /// @returns
 ///     - ::UR_RESULT_SUCCESS
 ///     - ::UR_RESULT_ERROR_UNINITIALIZED
@@ -6668,6 +6673,11 @@ urEnqueueUSMPrefetch(
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Enqueue a command to set USM memory advice
 ///
+/// @details
+///     - Not all memory advice hints may be supported for all devices or
+///       allocation types. If a memory advice hint is not supported, it will be
+///       ignored.
+///
 /// @returns
 ///     - ::UR_RESULT_SUCCESS
 ///     - ::UR_RESULT_ERROR_UNINITIALIZED

scripts/core/enqueue.yml

@@ -1088,6 +1088,9 @@ desc: "Enqueue a command to prefetch USM memory"
 class: $xEnqueue
 name: USMPrefetch
 ordinal: "0"
+details:
+    - "Prefetching may not be supported for all devices or allocation types. If memory prefetching 
+    is not supported, the prefetch hint will be ignored."
 params:
     - type: $x_queue_handle_t
       name: hQueue
@@ -1128,10 +1131,13 @@ returns:
     - $X_RESULT_ERROR_OUT_OF_RESOURCES
 --- #--------------------------------------------------------------------------
 type: function
-desc: "Enqueue a command to set USM memory advice" 
+desc: "Enqueue a command to set USM memory advice"
 class: $xEnqueue
 name: USMAdvise
 ordinal: "0"
+details:
+    - "Not all memory advice hints may be supported for all devices or allocation types. 
+    If a memory advice hint is not supported, it will be ignored."
 params:
     - type: $x_queue_handle_t
       name: hQueue

source/loader/ur_libapi.cpp

@@ -5685,6 +5685,11 @@ ur_result_t UR_APICALL urEnqueueUSMMemcpy(
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Enqueue a command to prefetch USM memory
 ///
+/// @details
+///     - Prefetching may not be supported for all devices or allocation types.
+///       If memory prefetching is not supported, the prefetch hint will be
+///       ignored.
+///
 /// @returns
 ///     - ::UR_RESULT_SUCCESS
 ///     - ::UR_RESULT_ERROR_UNINITIALIZED
@@ -5737,6 +5742,11 @@ ur_result_t UR_APICALL urEnqueueUSMPrefetch(
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Enqueue a command to set USM memory advice
 ///
+/// @details
+///     - Not all memory advice hints may be supported for all devices or
+///       allocation types. If a memory advice hint is not supported, it will be
+///       ignored.
+///
 /// @returns
 ///     - ::UR_RESULT_SUCCESS
 ///     - ::UR_RESULT_ERROR_UNINITIALIZED

source/ur_api.cpp

@@ -4830,6 +4830,11 @@ ur_result_t UR_APICALL urEnqueueUSMMemcpy(
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Enqueue a command to prefetch USM memory
 ///
+/// @details
+///     - Prefetching may not be supported for all devices or allocation types.
+///       If memory prefetching is not supported, the prefetch hint will be
+///       ignored.
+///
 /// @returns
 ///     - ::UR_RESULT_SUCCESS
 ///     - ::UR_RESULT_ERROR_UNINITIALIZED
@@ -4875,6 +4880,11 @@ ur_result_t UR_APICALL urEnqueueUSMPrefetch(
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Enqueue a command to set USM memory advice
 ///
+/// @details
+///     - Not all memory advice hints may be supported for all devices or
+///       allocation types. If a memory advice hint is not supported, it will be
+///       ignored.
+///
 /// @returns
 ///     - ::UR_RESULT_SUCCESS
 ///     - ::UR_RESULT_ERROR_UNINITIALIZED