[SYCL][XPTI] Add XPTI notifications for SYCL 2020 images (#9770)

This commit adds XPTI notifications for SYCL 2020 image classes
(`sampled_image` and `unsampled_image`) as well as for the associated
accessor classes (`sampled_image_accessor`,
`host_sampled_image_accessor`, `unsampled_image_accessor` and
`host_unsampled_image_accessor`).

---------

Signed-off-by: Larsen, Steffen <[email protected]>

Author: steffenlarsen

sycl/doc/design/SYCLInstrumentationUsingXPTI.md

@@ -287,12 +287,22 @@ All trace point types in bold provide semantic information about the graph, node
 
 | Trace Point Type           | Parameter Description | Metadata |
 | :------------------------: | :-------------------- | :------- |
-| `offload_alloc_construct` | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_buffer_data_t` that marks offload buffer creation point</li> <li> **parent**: Event ID created for all functions in the `oneapi.experimental.buffer` layer.</li> <li> **event**: `xpti::trace_event_data_t` - contains information about source location.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed. </li> <li> **user_data**: A pointer to `offload_buffer_data_t` object, that includes buffer object ID, host pointer used to create/initialize buffer, buffer element information (type name, size), number of buffer dimensions and buffer size for each dimension. </li></div> | None     |
-| `offload_alloc_associate`   | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_buffer_association_data_t` that provides association between user level buffer object and platform specific memory object</li> <li> **parent**: Event ID created for all functions in the `oneapi.experimental.buffer` layer.</li> <li> **event**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed.</li> <li> **user_data**: A pointer to `offload_buffer_association_data_t` object, that includes user object ID and platform-specific representation for offload buffer. </li></div> | None     |
-| `offload_alloc_destruct` | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_buffer_data_t` that marks offload buffer destruction point</li> <li> **parent**: Event ID created for all functions in the `oneapi.experimental.buffer` layer.</li> <li> **event**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed. </li> <li> **user_data**: A pointer to `offload_buffer_data_t` object, that includes buffer object ID. </li></div> | None     |
-| `offload_alloc_release`   | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_buffer_release_data_t` that provides information about release of platform specific memory object</li> <li> **parent**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **event**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed.</li> <li> **user_data**: A pointer to `offload_buffer_association_data_t` object, that includes user object ID and platform-specific representation for offload buffer. </li></div> | None     |
+| `offload_alloc_memory_object_construct` | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_memory_object_data_t` that marks offload buffer creation point</li> <li> **parent**: Event ID created for all functions in the `oneapi.experimental.buffer` layer.</li> <li> **event**: `xpti::trace_event_data_t` - contains information about source location.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed. </li> <li> **user_data**: A pointer to `offload_memory_object_data_t` object, that includes buffer object ID, host pointer used to create/initialize buffer, buffer element information (type name, size), number of buffer dimensions and buffer size for each dimension. </li></div> | None     |
+| `offload_alloc_memory_object_associate`   | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_association_data_t` that provides association between user level buffer object and platform specific memory object</li> <li> **parent**: Event ID created for all functions in the `oneapi.experimental.buffer` layer.</li> <li> **event**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed.</li> <li> **user_data**: A pointer to `offload_association_data_t` object, that includes user object ID and platform-specific representation for offload buffer. </li></div> | None     |
+| `offload_alloc_memory_object_destruct` | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_memory_object_data_t` that marks offload buffer destruction point</li> <li> **parent**: Event ID created for all functions in the `oneapi.experimental.buffer` layer.</li> <li> **event**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed. </li> <li> **user_data**: A pointer to `offload_memory_object_data_t` object, that includes buffer object ID. </li></div> | None     |
+| `offload_alloc_memory_object_release`   | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_memory_object_release_data_t` that provides information about release of platform specific memory object</li> <li> **parent**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **event**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed.</li> <li> **user_data**: A pointer to `offload_association_data_t` object, that includes user object ID and platform-specific representation for offload buffer. </li></div> | None     |
 | `offload_alloc_accessor` | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_accessor_data_t` that marks offload accessor creation point</li> <li> **parent**: Event ID created for all functions in the `oneapi.experimental.buffer` layer.</li> <li> **event**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed. </li> <li> **user_data**: A pointer to `offload_accessor_data_t` object, that includes buffer object ID, accessor handle created from specific buffer, accessor information (access target and mode). </li></div> | None     |
 
+## Image management stream `"sycl.experimental.image"` Notification Signatures
+
+| Trace Point Type           | Parameter Description | Metadata |
+| :------------------------: | :-------------------- | :------- |
+| `offload_alloc_memory_object_construct` | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_image_data_t` that marks offload image creation point</li> <li> **parent**: Event ID created for all functions in the `oneapi.experimental.image` layer.</li> <li> **event**: `xpti::trace_event_data_t` - contains information about source location.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed. </li> <li> **user_data**: A pointer to `offload_image_data_t` object, that includes image object ID, host pointer used to create/initialize image, number of image dimensions, the image format and sampler information (addressing mode, coordinate normalization mode, filtering mode). </li></div> | None     |
+| `offload_alloc_memory_object_associate`   | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_association_data_t` that provides association between user level image object and platform specific memory object</li> <li> **parent**: Event ID created for all functions in the `oneapi.experimental.image` layer.</li> <li> **event**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed.</li> <li> **user_data**: A pointer to `offload_association_data_t` object, that includes user object ID and platform-specific representation for offload image. </li></div> | None     |
+| `offload_alloc_memory_object_destruct` | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_image_data_t` that marks offload image destruction point</li> <li> **parent**: Event ID created for all functions in the `oneapi.experimental.image` layer.</li> <li> **event**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed. </li> <li> **user_data**: A pointer to `offload_image_data_t` object, that includes image object ID. </li></div> | None     |
+| `offload_alloc_memory_object_release`   | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_association_data_t` that provides information about release of platform specific memory object</li> <li> **parent**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **event**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed.</li> <li> **user_data**: A pointer to `offload_association_data_t` object, that includes user object ID and platform-specific representation for offload image. </li></div> | None     |
+| `offload_alloc_accessor` | <div style="text-align: left"><li>**trace_type**: `xpti::trace_point_type_t::offload_image_accessor_data_t` that marks offload image accessor creation point</li> <li> **parent**: Event ID created for all functions in the `oneapi.experimental.image` layer.</li> <li> **event**: `nullptr` - since the stream of data just captures functions being called.</li> <li> **instance**: `nullptr` since no begin-end event alignment is needed. </li> <li> **user_data**: A pointer to `offload_image_accessor_data_t` object, that includes image object ID, accessor handle created from specific image, access target (if the accessor is not a host accessor), access mode (if the accessor is to an unsampled image) and element information (type name, size). </li></div> | None     |
+
 ## SYCL Memory Allocations Stream `"sycl.experimental.mem_alloc"` Notification Signatures
 
 | Trace Point Type           | Parameter Description | Metadata |

sycl/include/sycl/accessor.hpp

@@ -34,6 +34,7 @@
 #include <sycl/sampler.hpp>
 
 #include <iterator>
+#include <optional>
 #include <type_traits>
 
 #include <utility>
@@ -246,6 +247,15 @@ void __SYCL_EXPORT constructorNotification(void *BufferObj, void *AccessorObj,
                                            access::mode Mode,
                                            const code_location &CodeLoc);
 
+void __SYCL_EXPORT unsampledImageConstructorNotification(
+    void *ImageObj, void *AccessorObj, std::optional<image_target> Target,
+    access::mode Mode, const void *Type, uint32_t ElemSize,
+    const code_location &CodeLoc);
+
+void __SYCL_EXPORT sampledImageConstructorNotification(
+    void *ImageObj, void *AccessorObj, std::optional<image_target> Target,
+    const void *Type, uint32_t ElemSize, const code_location &CodeLoc);
+
 template <typename T>
 using IsPropertyListT = typename std::is_base_of<PropertyListBase, T>;
 
@@ -3595,9 +3605,10 @@ class __SYCL_EBO unsampled_image_accessor :
   using const_reference = const DataT &;
 
   template <typename AllocatorT>
-  unsampled_image_accessor(unsampled_image<Dimensions, AllocatorT> &ImageRef,
-                           handler &CommandGroupHandlerRef,
-                           const property_list &PropList = {})
+  unsampled_image_accessor(
+      unsampled_image<Dimensions, AllocatorT> &ImageRef,
+      handler &CommandGroupHandlerRef, const property_list &PropList = {},
+      const detail::code_location CodeLoc = detail::code_location::current())
 #ifdef __SYCL_DEVICE_ONLY__
       {}
 #else
@@ -3616,6 +3627,9 @@ class __SYCL_EBO unsampled_image_accessor :
           "Device associated with command group handler does not have "
           "aspect::image.");
 
+    detail::unsampledImageConstructorNotification(
+        detail::getSyclObjImpl(ImageRef).get(), this->impl.get(), AccessTarget,
+        AccessMode, (const void *)typeid(DataT).name(), sizeof(DataT), CodeLoc);
     detail::associateWithHandler(CommandGroupHandlerRef, this, AccessTarget);
     GDBMethodsAnchor();
   }
@@ -3734,14 +3748,19 @@ class __SYCL_EBO host_unsampled_image_accessor
   template <typename AllocatorT>
   host_unsampled_image_accessor(
       unsampled_image<Dimensions, AllocatorT> &ImageRef,
-      const property_list &PropList = {})
+      const property_list &PropList = {},
+      const detail::code_location CodeLoc = detail::code_location::current())
       : base_class(detail::convertToArrayOfN<3, 1>(ImageRef.get_range()),
                    AccessMode, detail::getSyclObjImpl(ImageRef).get(),
                    Dimensions, ImageRef.getElementSize(),
                    {ImageRef.getRowPitch(), ImageRef.getSlicePitch(), 0},
                    ImageRef.getChannelType(), ImageRef.getChannelOrder(),
                    PropList) {
     addHostUnsampledImageAccessorAndWait(base_class::impl.get());
+
+    detail::unsampledImageConstructorNotification(
+        detail::getSyclObjImpl(ImageRef).get(), this->impl.get(), std::nullopt,
+        AccessMode, (const void *)typeid(DataT).name(), sizeof(DataT), CodeLoc);
   }
 
   /* -- common interface members -- */
@@ -3852,9 +3871,10 @@ class __SYCL_EBO sampled_image_accessor :
   using const_reference = const DataT &;
 
   template <typename AllocatorT>
-  sampled_image_accessor(sampled_image<Dimensions, AllocatorT> &ImageRef,
-                         handler &CommandGroupHandlerRef,
-                         const property_list &PropList = {})
+  sampled_image_accessor(
+      sampled_image<Dimensions, AllocatorT> &ImageRef,
+      handler &CommandGroupHandlerRef, const property_list &PropList = {},
+      const detail::code_location CodeLoc = detail::code_location::current())
 #ifdef __SYCL_DEVICE_ONLY__
       {}
 #else
@@ -3873,6 +3893,9 @@ class __SYCL_EBO sampled_image_accessor :
           "Device associated with command group handler does not have "
           "aspect::image.");
 
+    detail::sampledImageConstructorNotification(
+        detail::getSyclObjImpl(ImageRef).get(), this->impl.get(), AccessTarget,
+        (const void *)typeid(DataT).name(), sizeof(DataT), CodeLoc);
     detail::associateWithHandler(CommandGroupHandlerRef, this, AccessTarget);
     GDBMethodsAnchor();
   }
@@ -3965,15 +3988,21 @@ class __SYCL_EBO host_sampled_image_accessor
   using const_reference = const DataT &;
 
   template <typename AllocatorT>
-  host_sampled_image_accessor(sampled_image<Dimensions, AllocatorT> &ImageRef,
-                              const property_list &PropList = {})
+  host_sampled_image_accessor(
+      sampled_image<Dimensions, AllocatorT> &ImageRef,
+      const property_list &PropList = {},
+      const detail::code_location CodeLoc = detail::code_location::current())
       : base_class(detail::convertToArrayOfN<3, 1>(ImageRef.get_range()),
                    detail::getSyclObjImpl(ImageRef).get(), Dimensions,
                    ImageRef.getElementSize(),
                    {ImageRef.getRowPitch(), ImageRef.getSlicePitch(), 0},
                    ImageRef.getChannelType(), ImageRef.getChannelOrder(),
                    ImageRef.getSampler(), PropList) {
     addHostSampledImageAccessorAndWait(base_class::impl.get());
+
+    detail::sampledImageConstructorNotification(
+        detail::getSyclObjImpl(ImageRef).get(), this->impl.get(), std::nullopt,
+        (const void *)typeid(DataT).name(), sizeof(DataT), CodeLoc);
   }
 
   /* -- common interface members -- */