From ffcc2d2f0c31d00115593b7416e6d11590048b89 Mon Sep 17 00:00:00 2001 From: Alexander Batashev Date: Tue, 7 Sep 2021 14:27:12 +0300 Subject: [PATCH 1/7] [SYCL][Doc] Update ITT instrumentation docs --- sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst b/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst index 0b72d138549ce..4e844407dbd91 100644 --- a/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst +++ b/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst @@ -65,7 +65,9 @@ a wrapper. 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). 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 @@ -77,3 +79,7 @@ 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. + +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. From a3571c5184cf535975f55f2fe9ae0ac7b37acb24 Mon Sep 17 00:00:00 2001 From: Alexander Batashev Date: Tue, 7 Sep 2021 14:35:04 +0300 Subject: [PATCH 2/7] Update sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst Co-authored-by: Alexey Bader --- sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst b/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst index 4e844407dbd91..222e873907ab5 100644 --- a/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst +++ b/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst @@ -65,6 +65,7 @@ a wrapper. 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). From 5ea7a2f2af524b3fa5f00a34ccc87091852ebdca Mon Sep 17 00:00:00 2001 From: Alexander Batashev Date: Tue, 7 Sep 2021 18:50:00 +0300 Subject: [PATCH 3/7] Update docs --- sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst b/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst index 222e873907ab5..aeb68852a96ee 100644 --- a/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst +++ b/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst @@ -68,7 +68,8 @@ 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). +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 From 7ae82832576a95eebdebc460a9f49ec40e27d020 Mon Sep 17 00:00:00 2001 From: Alexander Batashev Date: Wed, 8 Sep 2021 21:18:26 +0300 Subject: [PATCH 4/7] Address feedback --- sycl/doc/EnvironmentVariables.md | 1 + .../ITTAnnotations.rst => ITTAnnotations.md} | 57 +++++++++---------- sycl/doc/extensions/README.md | 1 - sycl/doc/index.rst | 1 + 4 files changed, 28 insertions(+), 32 deletions(-) rename sycl/doc/{extensions/ITTAnnotations/ITTAnnotations.rst => ITTAnnotations.md} (68%) diff --git a/sycl/doc/EnvironmentVariables.md b/sycl/doc/EnvironmentVariables.md index 43af7fc852f00..b56f82c4e12ae 100644 --- a/sycl/doc/EnvironmentVariables.md +++ b/sycl/doc/EnvironmentVariables.md @@ -47,6 +47,7 @@ subject to change. Do not rely on these variables in production code. | `SYCL_CACHE_THRESHOLD` | Positive integer | Cache eviction threshold in days (default value is 7 for 1 week). Set to 0 for disabling time-based cache eviction. | | `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. | +| `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.` diff --git a/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst b/sycl/doc/ITTAnnotations.md similarity index 68% rename from sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst rename to sycl/doc/ITTAnnotations.md index aeb68852a96ee..aa8b72b5b15a6 100644 --- a/sycl/doc/extensions/ITTAnnotations/ITTAnnotations.rst +++ b/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,63 +7,59 @@ 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 @@ -78,7 +73,7 @@ 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. diff --git a/sycl/doc/extensions/README.md b/sycl/doc/extensions/README.md index ae345a98920e2..f5a4a9f14002e 100755 --- a/sycl/doc/extensions/README.md +++ b/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 | | | [SYCL_EXT_ONEAPI_DEVICE_IF](DeviceIf/device_if.asciidoc) | Proposal | | | [SYCL_INTEL_group_sort](GroupAlgorithms/SYCL_INTEL_group_sort.asciidoc) | Proposal | | | [Invoke SIMD](InvokeSIMD/InvokeSIMD.asciidoc) | Proposal | | diff --git a/sycl/doc/index.rst b/sycl/doc/index.rst index f32e12a53715e..73323ac083091 100644 --- a/sycl/doc/index.rst +++ b/sycl/doc/index.rst @@ -39,4 +39,5 @@ Developing oneAPI DPC++ Compiler MultiTileCardWithLevelZero OptionalDeviceFeatures SYCLInstrumentationUsingXPTI + ITTAnnotations From d4c1fefb03ecc0204300c1fb6c86e2ec18bc4fde Mon Sep 17 00:00:00 2001 From: Alexander Batashev Date: Thu, 9 Sep 2021 14:16:04 +0300 Subject: [PATCH 5/7] Split env vars --- sycl/doc/EnvironmentVariables.md | 1 - sycl/doc/InternalEnvironmentVariables.md | 12 ++++++++++++ sycl/doc/index.rst | 1 + 3 files changed, 13 insertions(+), 1 deletion(-) create mode 100644 sycl/doc/InternalEnvironmentVariables.md diff --git a/sycl/doc/EnvironmentVariables.md b/sycl/doc/EnvironmentVariables.md index b56f82c4e12ae..43af7fc852f00 100644 --- a/sycl/doc/EnvironmentVariables.md +++ b/sycl/doc/EnvironmentVariables.md @@ -47,7 +47,6 @@ subject to change. Do not rely on these variables in production code. | `SYCL_CACHE_THRESHOLD` | Positive integer | Cache eviction threshold in days (default value is 7 for 1 week). Set to 0 for disabling time-based cache eviction. | | `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. | -| `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.` diff --git a/sycl/doc/InternalEnvironmentVariables.md b/sycl/doc/InternalEnvironmentVariables.md new file mode 100644 index 0000000000000..c89376d94613e --- /dev/null +++ b/sycl/doc/InternalEnvironmentVariables.md @@ -0,0 +1,12 @@ +# Internal Environment Variables + +**Warning:** the environment variables described in this document are used for +development and debugging of DPC++ compiler and runtime. 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.` + diff --git a/sycl/doc/index.rst b/sycl/doc/index.rst index 73323ac083091..fd40c46a598ea 100644 --- a/sycl/doc/index.rst +++ b/sycl/doc/index.rst @@ -28,6 +28,7 @@ Developing oneAPI DPC++ Compiler CompilerAndRuntimeDesign KernelParameterPassing EnvironmentVariables + InternalEnvironmentVariables PluginInterface ABIPolicyGuide SpecializationConstants From ac36b4e70266a668df8fdb247489985f4e3fa1a3 Mon Sep 17 00:00:00 2001 From: Alexander Batashev Date: Thu, 9 Sep 2021 14:46:18 +0300 Subject: [PATCH 6/7] apply suggesion from review --- sycl/doc/InternalEnvironmentVariables.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/sycl/doc/InternalEnvironmentVariables.md b/sycl/doc/InternalEnvironmentVariables.md index c89376d94613e..b61e4dff6cbc9 100644 --- a/sycl/doc/InternalEnvironmentVariables.md +++ b/sycl/doc/InternalEnvironmentVariables.md @@ -1,8 +1,9 @@ # Internal Environment Variables **Warning:** the environment variables described in this document are used for -development and debugging of DPC++ compiler and runtime. Their semantics are -subject to change. Do not rely on these variables in production code. +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 | | -------------------- | ------ | ----------- | From e0e0750a03ed211b2f660b63c4e43b806cce58b8 Mon Sep 17 00:00:00 2001 From: Alexander Batashev Date: Tue, 14 Sep 2021 11:20:11 +0300 Subject: [PATCH 7/7] update env vars --- sycl/doc/EnvironmentVariables.md | 2 ++ sycl/doc/InternalEnvironmentVariables.md | 13 ------------- sycl/doc/index.rst | 1 - 3 files changed, 2 insertions(+), 14 deletions(-) delete mode 100644 sycl/doc/InternalEnvironmentVariables.md diff --git a/sycl/doc/EnvironmentVariables.md b/sycl/doc/EnvironmentVariables.md index 43af7fc852f00..1e0fb6c469509 100644 --- a/sycl/doc/EnvironmentVariables.md +++ b/sycl/doc/EnvironmentVariables.md @@ -47,6 +47,8 @@ subject to change. Do not rely on these variables in production code. | `SYCL_CACHE_THRESHOLD` | Positive integer | Cache eviction threshold in days (default value is 7 for 1 week). Set to 0 for disabling time-based cache eviction. | | `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. | +| `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.` diff --git a/sycl/doc/InternalEnvironmentVariables.md b/sycl/doc/InternalEnvironmentVariables.md deleted file mode 100644 index b61e4dff6cbc9..0000000000000 --- a/sycl/doc/InternalEnvironmentVariables.md +++ /dev/null @@ -1,13 +0,0 @@ -# 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.` - diff --git a/sycl/doc/index.rst b/sycl/doc/index.rst index fd40c46a598ea..73323ac083091 100644 --- a/sycl/doc/index.rst +++ b/sycl/doc/index.rst @@ -28,7 +28,6 @@ Developing oneAPI DPC++ Compiler CompilerAndRuntimeDesign KernelParameterPassing EnvironmentVariables - InternalEnvironmentVariables PluginInterface ABIPolicyGuide SpecializationConstants