[SYCL][Doc] Update ITT instrumentation docs (#4503)

Add more details about ITT annotations implementation in SYCL runtime and update feature controls documentation.

Author: Alexander Batashev

sycl/doc/EnvironmentVariables.md

@@ -49,6 +49,7 @@ subject to change. Do not rely on these variables in production code.
 | `SYCL_CACHE_MIN_DEVICE_IMAGE_SIZE` | Positive integer | Minimum size of device code image in bytes which is reasonable to cache on disk because disk access operation may take more time than do JIT compilation for it. Default value is 0 to cache all images. |
 | `SYCL_CACHE_MAX_DEVICE_IMAGE_SIZE` | Positive integer | Maximum size of device image in bytes which is cached. Too big kernels may overload disk too fast. Default value is 1 GB. |
 | `SYCL_ENABLE_DEFAULT_CONTEXTS` | '1' or '0' | Enable ('1') or disable ('0') creation of default platform contexts in SYCL runtime. The default context for each platform contains all devices in the platform. Refer to [Platform Default Contexts](extensions/PlatformContext/PlatformContext.adoc) extension to learn more. Enabled by default on Linux and disabled on Windows. |
+| `INTEL_ENABLE_OFFLOAD_ANNOTATIONS` | Any(\*) | Enables ITT Annotations support for SYCL runtime. This variable should only be used by tools, that support ITT Annotations. |
 
 `(*) Note: Any means this environment variable is effective when set to any non-null value.`
 

sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst renamed to sycl/doc/ITTAnnotations.md

@@ -1,5 +1,4 @@
-ITT annotations support
-=======================
+# ITT annotations support
 
 This extension enables a set of functions implementing
 the Instrumentation and Tracing Technology (ITT) functionality
@@ -8,64 +7,64 @@ in SYCL device code.
 There are three sets of functions defined by this extension,
 and they serve different purposes.
 
-User APIs
----------
+## User APIs
 
 The user code calling these functions must include the corresponding header
-file(s) provided by ``ittnotify`` project (TBD: reference ITT repo here).
+file(s) provided by `ittnotify` project (TBD: reference ITT repo here).
 
-These functions are named using ``__itt_notify_`` prefix.
+These functions are named using `__itt_notify_` prefix.
 
-Stub APIs
----------
+## 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.
+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
+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
----------------------
+## 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.
+These functions have `_wrapper` suffix in their names.
 
-Example
-~~~~~~~
+**Example**
 
-.. code: c++
-   DEVICE_EXTERN_C void __itt_offload_wi_start_stub(
-       size_t[3], size_t, uint32_t);
+```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);
-     }
-   }
+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``
+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
------------------------
+## Conditional compilation
 
+Data Parallel C++ compiler automatically instruments user code through
+SPIRITTAnnotations LLVM pass, which is enabled for targets, that natively
+support specialization constants (i.e., SPIR-V targets). Annotations are
+generated for barriers, atomics, work item start and finish.
 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
@@ -74,6 +73,10 @@ 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
+`4285822057` (`0xFF747469`). The users/tools/runtimes should set this
 specialization constant to non-zero value to enable the ITT annotations
 in SYCL device code.
+
+The specialization constant value is controlled by
+INTEL_ENABLE_OFFLOAD_ANNOTATIONS environment variable. Tools, that support ITT
+annotations must set this environment variable to any value.

sycl/doc/extensions/README.md

@@ -36,7 +36,6 @@ 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 | |
 | [Platform Context](PlatformContext/PlatformContext.adoc) | Proposal | |
 | [SYCL_EXT_ONEAPI_DEVICE_IF](DeviceIf/device_if.asciidoc) | Proposal | |
 | [SYCL_INTEL_group_sort](GroupAlgorithms/SYCL_INTEL_group_sort.asciidoc)                                                     | Proposal                                  | |

sycl/doc/index.rst

@@ -39,4 +39,5 @@ Developing oneAPI DPC++ Compiler
    MultiTileCardWithLevelZero
    OptionalDeviceFeatures
    SYCLInstrumentationUsingXPTI
+   ITTAnnotations