ITT stubs and wrappers for SPIR-V devices.

sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst

@@ -0,0 +1,79 @@
+ITT annotations support
+=======================
+
+This extension enables a set of functions implementing
+the Instrumentation and Tracing Technology (ITT) functionality
+in SYCL device code.
+
+There are three sets of functions defined by this extension,
+and they serve different purposes.
+
+User APIs
+---------
+
+The user code calling these functions must include the corresponding header
+file(s) provided by `ittnotify` project (TBD: reference ITT repo here).
+
+These functions are named using `__itt_notify_` prefix.
+
+Stub APIs
+---------
+
+These functions are not defined in any header file, and their declarations
+follow exactly the declarations of the corresponding user APIs, except that
+they have an extra `_stub` suffix in their names.
+
+These functions implement the ITT functionality in a way that allows
+the tools, such as Intel(R) Inspector, to recognize the ITT annotations
+and run their analysis methods based on that.
+
+For SYCL device code these functions are implemented as `noinline` and `optnone`
+functions so that the corresponding calls may be distinguished in the execution
+trace. This is just one way for implementing them, and the actual implementation
+may change in future.
+
+Compiler wrapper APIs
+---------------------
+
+These functions are not defined in any header file, and they are supposed
+to be called from the compiler generated code. These thin wrappers
+just provide a convenient way for compilers to produce ITT annotations
+without generating too much code in the compilers' IR.
+
+These functions have `_wrapper` suffix in their names.
+
+Example
+~~~~~~~
+
+.. code: c++
+   DEVICE_EXTERN_C void __itt_offload_wi_start_stub(
+       size_t[3], size_t, uint32_t);
+
+   DEVICE_EXTERN_C void __itt_offload_wi_start_wrapper() {
+     if (__spirv_SpecConstant(0xFF747469, 0)) {
+       size_t GroupID[3] = ...;
+       size_t WIId = ...;
+       uint32_t WGSize = ...;
+       __itt_offload_wi_start_stub(GroupID, WIId, WGSize);
+     }
+   }
+
+A compiler may generate a simple call to `__itt_offload_wi_start_wrapper`
+to annotate a kernel entry point. Compare this to the code inside the wrapper
+function, which a compiler would have to generate if there were no such
+a wrapper.
+
+Conditional compilation
+-----------------------
+
+To minimize the effect of ITT annotations on the performance of the device code,
+the implementation is guarded with a specialization constant check. This allows
+users and tools to have one version of the annotated code that may be built
+with and without ITT annotations "enabled". When the ITT annotations are not
+enabled, we expect that the overall effect of the annotations will be minimized
+by the dead code elimination optimization(s) made by the device compilers.
+
+For this purpose we reserve a 1-byte specialization constant numbered
+`4285822057` (`0xFF747469`). The users/tools/runtimes should set this
+specialization constant to non-zero value to enable the ITT annotations
+in SYCL device code.

sycl/doc/extensions/README.md

@@ -36,6 +36,7 @@ DPC++ extensions status:
 | [Unified Shared Memory](USM/USM.adoc)                                                                                       | Supported(OpenCL)                         | |
 | [Use Pinned Memory Property](UsePinnedMemoryProperty/UsePinnedMemoryPropery.adoc)                                           | Supported                                 | |
 | [Level-Zero backend specification](LevelZeroBackend/LevelZeroBackend.md)                                           	      | Supported                                 | |
+| [ITT annotations support](ITTAnnotations/ITTAnnotations.rst) | Supported | |
 
 Legend: