Merge branch 'main' into cl-subgroupsizes

Author: ayylol

include/ur_api.h

@@ -4277,6 +4277,11 @@ urProgramCompile(
 ///       in `phProgram` will contain a binary of the
 ///       ::UR_PROGRAM_BINARY_TYPE_EXECUTABLE type for each device in
 ///       `hContext`.
+///     - If a non-success code is returned and `phProgram` is not `nullptr`, it
+///       will contain an unspecified program or `nullptr`. Implementations may
+///       use the build log of this program (accessible via
+///       ::urProgramGetBuildInfo) to provide an error log for the linking
+///       failure.
 ///
 /// @remarks
 ///   _Analogues_
@@ -6894,7 +6899,6 @@ urEnqueueMemUnmap(
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
 ///         + `patternSize == 0 || size == 0`
 ///         + `patternSize > size`
-///         + `(patternSize & (patternSize - 1)) != 0`
 ///         + `size % patternSize != 0`
 ///         + If `size` is higher than the allocation size of `ptr`
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
@@ -7665,6 +7669,7 @@ urBindlessImagesImageFreeExp(
 ///         + `pImageDesc && UR_MEM_TYPE_IMAGE1D_ARRAY < pImageDesc->type`
 ///     - ::UR_RESULT_ERROR_INVALID_IMAGE_SIZE
 ///     - ::UR_RESULT_ERROR_INVALID_OPERATION
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
 UR_APIEXPORT ur_result_t UR_APICALL
 urBindlessImagesUnsampledImageCreateExp(
     ur_context_handle_t hContext,          ///< [in] handle of the context object
@@ -7703,6 +7708,7 @@ urBindlessImagesUnsampledImageCreateExp(
 ///     - ::UR_RESULT_ERROR_INVALID_IMAGE_SIZE
 ///     - ::UR_RESULT_ERROR_INVALID_SAMPLER
 ///     - ::UR_RESULT_ERROR_INVALID_OPERATION
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
 UR_APIEXPORT ur_result_t UR_APICALL
 urBindlessImagesSampledImageCreateExp(
     ur_context_handle_t hContext,          ///< [in] handle of the context object
@@ -8386,7 +8392,6 @@ urCommandBufferAppendUSMMemcpyExp(
 ///     - ::UR_RESULT_ERROR_INVALID_SIZE
 ///         + `patternSize == 0 || size == 0`
 ///         + `patternSize > size`
-///         + `(patternSize & (patternSize - 1)) != 0`
 ///         + `size % patternSize != 0`
 ///         + If `size` is higher than the allocation size of `ptr`
 ///     - ::UR_RESULT_ERROR_INVALID_MEM_OBJECT
@@ -9276,6 +9281,11 @@ urProgramCompileExp(
 ///       in `phProgram` will contain a binary of the
 ///       ::UR_PROGRAM_BINARY_TYPE_EXECUTABLE type for each device in
 ///       `phDevices`.
+///     - If a non-success code is returned and `phProgram` is not `nullptr`, it
+///       will contain an unspecified program or `nullptr`. Implementations may
+///       use the build log of this program (accessible via
+///       ::urProgramGetBuildInfo) to provide an error log for the linking
+///       failure.
 ///
 /// @remarks
 ///   _Analogues_
@@ -9568,7 +9578,6 @@ typedef void (*ur_exp_enqueue_native_command_function_t)(
 ///         + `NULL == hQueue`
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pfnNativeEnqueue`
-///         + `NULL == phEvent`
 ///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
 ///         + `NULL != pProperties && ::UR_EXP_ENQUEUE_NATIVE_COMMAND_FLAGS_MASK & pProperties->flags`
 ///     - ::UR_RESULT_ERROR_INVALID_EVENT_WAIT_LIST
@@ -9588,7 +9597,7 @@ urEnqueueNativeCommandExp(
     const ur_event_handle_t *phEventWaitList,                      ///< [in][optional][range(0, numEventsInWaitList)] pointer to a list of
                                                                    ///< events that must be complete before the kernel execution.
                                                                    ///< If nullptr, the numEventsInWaitList must be 0, indicating no wait events.
-    ur_event_handle_t *phEvent                                     ///< [in,out] return an event object that identifies the work that has
+    ur_event_handle_t *phEvent                                     ///< [out][optional] return an event object that identifies the work that has
                                                                    ///< been enqueued in nativeEnqueueFunc.
 );
 

scripts/core/EXP-NATIVE-ENQUEUE.rst

@@ -65,11 +65,13 @@ Functions
 Changelog
 --------------------------------------------------------------------------------
 
-+-----------+------------------------+
-| Revision  | Changes                |
-+===========+========================+
-| 1.0       | Initial Draft          |
-+-----------+------------------------+
++-----------+-------------------------+
+| Revision  | Changes                 |
++===========+=========================+
+| 1.0       | Initial Draft           |
++-----------+-------------------------+
+| 1.1       | Make `phEvent` optional |
++-----------+-------------------------+
 
 
 Support
@@ -83,3 +85,4 @@ Contributors
 --------------------------------------------------------------------------------
 
 * Hugh Delaney `hugh.delaney@codeplay.com <hugh.delaney@codeplay.com>`_
+* Kenneth Benzie (Benie) `k.benzie@codeplay.com <k.benzie@codeplay.com>`_

scripts/core/enqueue.yml

@@ -1061,7 +1061,6 @@ returns:
     - $X_RESULT_ERROR_INVALID_SIZE:
         - "`patternSize == 0 || size == 0`"
         - "`patternSize > size`"
-        - "`(patternSize & (patternSize - 1)) != 0`"
         - "`size % patternSize != 0`"
         - "If `size` is higher than the allocation size of `ptr`"
     - $X_RESULT_ERROR_INVALID_EVENT_WAIT_LIST:
@@ -1129,8 +1128,7 @@ 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."
+    - "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
@@ -1178,8 +1176,7 @@ 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."
+    - "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

scripts/core/exp-bindless-images.yml

@@ -469,6 +469,7 @@ returns:
       - "`pImageDesc && UR_MEM_TYPE_IMAGE1D_ARRAY < pImageDesc->type`"
     - $X_RESULT_ERROR_INVALID_IMAGE_SIZE
     - $X_RESULT_ERROR_INVALID_OPERATION
+    - $X_RESULT_ERROR_ADAPTER_SPECIFIC
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Create a bindless sampled image handle"
@@ -507,6 +508,7 @@ returns:
     - $X_RESULT_ERROR_INVALID_IMAGE_SIZE
     - $X_RESULT_ERROR_INVALID_SAMPLER
     - $X_RESULT_ERROR_INVALID_OPERATION
+    - $X_RESULT_ERROR_ADAPTER_SPECIFIC
 --- #--------------------------------------------------------------------------
 type: function
 desc: "Copy image data Host to Device or Device to Host"

scripts/core/exp-command-buffer.yml

@@ -408,7 +408,6 @@ returns:
     - $X_RESULT_ERROR_INVALID_SIZE:
         - "`patternSize == 0 || size == 0`"
         - "`patternSize > size`"
-        - "`(patternSize & (patternSize - 1)) != 0`"
         - "`size % patternSize != 0`"
         - "If `size` is higher than the allocation size of `ptr`"
     - $X_RESULT_ERROR_INVALID_MEM_OBJECT

scripts/core/exp-multi-device-compile.yml

@@ -94,6 +94,7 @@ analogue:
 details:
     - "The application may call this function from simultaneous threads."
     - "Following a successful call to this entry point the program returned in `phProgram` will contain a binary of the $X_PROGRAM_BINARY_TYPE_EXECUTABLE type for each device in `phDevices`."
+    - "If a non-success code is returned and `phProgram` is not `nullptr`, it will contain an unspecified program or `nullptr`. Implementations may use the build log of this program (accessible via $xProgramGetBuildInfo) to provide an error log for the linking failure."
 params:
     - type: $x_context_handle_t
       name: hContext

scripts/core/exp-native-enqueue.yml

@@ -111,7 +111,7 @@ params:
     - type: $x_event_handle_t*
       name: phEvent
       desc: |
-            [in,out] return an event object that identifies the work that has
+            [out][optional] return an event object that identifies the work that has
             been enqueued in nativeEnqueueFunc.
 returns:
     - $X_RESULT_ERROR_INVALID_NULL_HANDLE

scripts/core/program.yml

@@ -223,6 +223,7 @@ analogue:
 details:
     - "The application may call this function from simultaneous threads."
     - "Following a successful call to this entry point the program returned in `phProgram` will contain a binary of the $X_PROGRAM_BINARY_TYPE_EXECUTABLE type for each device in `hContext`."
+    - "If a non-success code is returned and `phProgram` is not `nullptr`, it will contain an unspecified program or `nullptr`. Implementations may use the build log of this program (accessible via $xProgramGetBuildInfo) to provide an error log for the linking failure."
 params:
     - type: $x_context_handle_t
       name: hContext

scripts/templates/helper.py

@@ -1248,6 +1248,30 @@ def get_pfntables(specs, meta, namespace, tags):
 
     return tables
 
+"""
+Public:
+    returns an expression setting required output parameters to null on entry
+"""
+def get_initial_null_set(obj):
+    cname = obj_traits.class_name(obj)
+    lvalue = {
+        ('$xProgram', 'Link'): 'phProgram',
+        ('$xProgram', 'LinkExp'): 'phProgram',
+    }.get((cname, obj['name']))
+    if lvalue is not None:
+        return 'if (nullptr != {0}) {{*{0} = nullptr;}}'.format(lvalue)
+    return ""
+
+"""
+Public:
+    returns true if the function always wraps output pointers in loader handles
+"""
+def always_wrap_outputs(obj):
+    cname = obj_traits.class_name(obj)
+    return (cname, obj['name']) in [
+        ('$xProgram', 'Link'),
+        ('$xProgram', 'LinkExp'),
+    ]
 
 """
 Private:

scripts/templates/ldrddi.cpp.mako

@@ -49,7 +49,7 @@ namespace ur_loader
     {
         ${x}_result_t result = ${X}_RESULT_SUCCESS;<%
         add_local = False
-    %>
+    %>${th.get_initial_null_set(obj)}
 
         %if re.match(r"\w+AdapterGet$", th.make_func_name(n, tags, obj)):
 
@@ -271,7 +271,7 @@ namespace ur_loader
         del add_local
         %>
         %for i, item in enumerate(epilogue):
-        %if 0 == i and not item['release']:
+        %if 0 == i and not item['release'] and not th.always_wrap_outputs(obj):
         if( ${X}_RESULT_SUCCESS != result )
             return result;
 
@@ -309,7 +309,7 @@ namespace ur_loader
                     ${item['factory']}.getInstance( ${item['name']}[ i ], dditable ) );
             %else:
             // convert platform handle to loader handle
-            %if item['optional']:
+            %if item['optional'] or th.always_wrap_outputs(obj):
             if( nullptr != ${item['name']} )
                 *${item['name']} = reinterpret_cast<${item['type']}>(
                     ${item['factory']}.getInstance( *${item['name']}, dditable ) );