[SYCL][Doc] Update ITT instrumentation docs

sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst → 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/InternalEnvironmentVariables.md

@@ -0,0 +1,13 @@
+# Internal Environment Variables
+
+**Warning:** the environment variables described in this document are used for
+development and debugging of DPC++ compiler and runtime, or for interaction with
+other tools. Their semantics are subject to change. Do not rely on these
+variables in production code.
+
+| Environment variable | Values | Description |
+| -------------------- | ------ | ----------- |
+| `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/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

@@ -28,6 +28,7 @@ Developing oneAPI DPC++ Compiler
    CompilerAndRuntimeDesign
    KernelParameterPassing
    EnvironmentVariables
+   InternalEnvironmentVariables
    PluginInterface
    ABIPolicyGuide
    SpecializationConstants
@@ -39,4 +40,5 @@ Developing oneAPI DPC++ Compiler
    MultiTileCardWithLevelZero
    OptionalDeviceFeatures
    SYCLInstrumentationUsingXPTI
+   ITTAnnotations