Clarify the behaviour of urUSMMemAdvise and urUSMPrefetch when the hi…

…nt is unsupported (#854)
oneapi-src · Sep 14, 2023 · fdffac3 · fdffac3
1 parent db69f90
commit fdffac3
Show file tree

Hide file tree

Showing 4 changed files with 37 additions and 1 deletion.
diff --git a/include/ur_api.h b/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

diff --git a/scripts/core/enqueue.yml b/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

diff --git a/source/loader/ur_libapi.cpp b/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

diff --git a/source/ur_api.cpp b/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