Added two new tools: cl_tracer and onetrace

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Intel Corportation
+Copyright (C) Intel Corportation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -42,22 +42,25 @@ You may obtain a copy of the License at https://opensource.org/licenses/MIT
 6. Code Annotation
     - based on [Instrumentation and Tracing Technology API (ITT API)](chapters/code_annotation/ITT.md)
 
-## Profiling Tools
-- for OpenCL(TM), DPC++ (with OpenCL(TM) backend) and OpenMP* (with OpenCL(TM) backend):
+## Profiling & Debug Tools
+- unified tools:
+    - [onetrace](tools/onetrace) - host and device tracing tool for OpenCL(TM) and Level Zero backends with support of DPC++ (both for CPU and GPU) and OpenMP* GPU offload;
+- tools for OpenCL(TM), DPC++ (with OpenCL(TM) backend) and OpenMP* GPU offload (with OpenCL(TM) backend):
     - [cl_hot_functions](samples/cl_hot_functions) - provides a list of hottest OpenCL(TM) API calls by backend (CPU and GPU);
     - [cl_hot_kernels](samples/cl_hot_kernels) - provides a list of hottest OpenCL(TM) kernels by backend (CPU and GPU);
     - [cl_debug_info](samples/cl_debug_info) - prints source and assembly (GEN ISA) for kernels on GPU;
     - [cl_gpu_metrics](samples/cl_gpu_metrics) - provides a list of hottest OpenCL(TM) GPU kernels along with percent of cycles it was active, stall and idle;
-- for Level Zero, DPC++ (with Level Zero backend) and OpenMP* (with Level Zero backend):
+    - [cl_tracer](samples/cl_tracer) - "Swiss army knife" for OpenCL(TM) API call tracing and profiling;
+- tools for Level Zero, DPC++ (with Level Zero backend) and OpenMP* GPU offload (with Level Zero backend):
     - [ze_hot_functions](samples/ze_hot_functions) - provides a list of hottest Level Zero API calls;
     - [ze_hot_kernels](samples/ze_hot_kernels) - provides a list of hottest Level Zero kernels;
     - [ze_debug_info](samples/ze_debug_info) - prints source and assembly (GEN ISA) for kernels on GPU;
     - [ze_metric_query](samples/ze_metric_query) - provides a list of hottest Level Zero GPU kernels along with percent of cycles it was active, stall and idle (metrics are collected in *query* mode);
     - [ze_metric_streamer](samples/ze_metric_query) - provides a list of hottest Level Zero GPU kernels along with percent of cycles it was active, stall and idle (metrics are collected in *streamer* mode);
-    - [ze_tracer](samples/ze_tracer) - "Swiss army knife" for Level Zero profiling (former ze_intercept);
-- for OpenMP* (with any backend):
+    - [ze_tracer](samples/ze_tracer) - "Swiss army knife" for Level Zero API call tracing and profiling (former ze_intercept);
+- tools for OpenMP*:
     - [omp_hot_regions](samples/omp_hot_regions) - provides a list of hottest parallel (for CPU) and target (for GPU) OpenMP* regions;
-- unified tools for binary instrumentation (for any GPU runtime):
+- tools for binary instrumentation:
     - [gpu_inst_count](samples/gpu_inst_count) - prints GPU kernel assembly (GEN ISA) annotated by instruction execution count;
     - [gpu_perfmon_read](samples/gpu_perfmon_read) - prints GPU kernel assembly (GEN ISA) annotated by specific HW metric, which is accumulated in EU PerfMon register;
 

VERSION

@@ -1 +1 @@
-0.11.0
+0.12.0

chapters/device_activity_tracing/OpenCL.md

@@ -10,6 +10,8 @@ The same event could be used to get additional profiling information for the dev
  - time counter in nanoseconds when the command identified by event starts execution on the device (`CL_PROFILING_COMMAND_START`);
  - time counter in nanoseconds when the command identified by event has finished execution on the device (`CL_PROFILING_COMMAND_END`).
 
+Intel(R) Xeon(R) Processor / Intel(R) Core(TM) Processor (CPU) Runtimes use `QueryPerformanceCounter` on Windows and `CLOCK_MONOTONIC` on Linux as time sources for the counters described above. Intel(R) Graphics Compute Runtime for oneAPI Level Zero and OpenCL(TM) Driver also uses `QueryPerformanceCounter` on Windows but `CLOCK_MONOTONIC_RAW` on Linux.
+
 **Supported Runtimes**:
 - any OpenCL(TM) 1.0 and above
 
@@ -74,4 +76,5 @@ void CL_CALLBACK EventNotify(cl_event event,
 ## Samples
 - [OpenCL(TM) GEMM](../../samples/cl_gemm)
 - [OpenCL(TM) Hot Kernels](../../samples/cl_hot_kernels)
-- [OpenCL(TM) GPU Metrics](../../samples/cl_gpu_metrics)
+- [OpenCL(TM) GPU Metrics](../../samples/cl_gpu_metrics)
+- [OpenCL(TM) Tracer](../../samples/cl_tracer)

chapters/metrics_collection/MetricsDiscoveryAPI.md

@@ -231,7 +231,7 @@ The problem is that metrics timestamp one can get with Intel(R) Metrics Discover
 
 In Intel(R) Metrics Discovery Application Programming Interface library there is a function `GetGpuCpuTimestamps` that allows to bind GPU metrics timestamp to some CPU timestamp (which is based on `CLOCK_MONOTONIC` on Linux and `QueryPerformanceCounter` on Windows).
 
-So e.g. to convert GPU metrics timestamp (`gpuTimestamp`) to OpenCL timestamp (`cpu_timestamp`), which is based on `CLOCK_MONOTONIC_RAW` on Linux, one should perform the following steps:
+So e.g. to convert GPU metrics timestamp (`gpuTimestamp`) to OpenCL GPU timestamp (`cpu_timestamp`), which is based on `CLOCK_MONOTONIC_RAW` on Linux, one should perform the following steps:
 1. Get "time snap point" to correlate GPU and `CLOCK_MONOTONIC` time:
 ```cpp
 uint64_t cpu_snap_point = 0, gpu_snap_point = 0;

chapters/runtime_api_tracing/OpenCL.md

@@ -42,7 +42,7 @@ cl_int CL_API_CALL clGetTracingStateINTEL(
 
 **Supported Runtimes**:
 - [Intel(R) Graphics Compute Runtime for oneAPI Level Zero and OpenCL(TM) Driver](https://github.com/intel/compute-runtime)
-- Intel(R) CPU Runtime for OpenCL(TM) Applications
+- [Intel(R) Xeon(R) Processor / Intel(R) Core(TM) Processor (CPU) Runtimes](https://software.intel.com/en-us/articles/opencl-drivers#cpu-section)
 
 **Supported OS**:
 - Linux
@@ -115,4 +115,5 @@ void Callback(cl_function_id fid,
 - [OpenCL(TM) Hot Functions](../../samples/cl_hot_functions)
 - [OpenCL(TM) Hot Kernels](../../samples/cl_hot_kernels)
 - [OpenCL(TM) Debug Info](../../samples/cl_debug_info)
-- [OpenCL(TM) GPU Metrics](../../samples/cl_gpu_metrics)
+- [OpenCL(TM) GPU Metrics](../../samples/cl_gpu_metrics)
+- [OpenCL(TM) Tracer](../../samples/cl_tracer)

samples/build_utils/CMakeLists.txt

@@ -1,3 +1,5 @@
+set(PTI_CMAKE_MACRO_DIR ${CMAKE_CURRENT_LIST_DIR} CACHE INTERNAL "")
+
 macro(SetRequiredCMakeVersion)
   set(REQUIRED_CMAKE_VERSION 2.8)
 endmacro()
@@ -27,38 +29,6 @@ macro(SetBuildType)
   endif()
 endmacro()
 
-macro(CheckForIntelCompiler)
-  if(WIN32)
-    set(INTEL_COMPILER_NAME "icl.exe")
-  else()
-    set(INTEL_COMPILER_NAME "icpx")
-  endif()
-  get_filename_component(COMPILER_NAME ${CMAKE_CXX_COMPILER} NAME)
-  if(COMPILER_NAME STREQUAL ${INTEL_COMPILER_NAME})
-    message(STATUS "Intel(R) C++ Compiler is used")
-  else()
-    message(FATAL_ERROR
-      "Intel(R) C++ Compiler is required. "
-      "Use \"CXX=${INTEL_COMPILER_NAME} cmake ..\" command to configure the sample.")
-  endif()
-endmacro()
-
-macro(CheckForDPCCompiler)
-  if(WIN32)
-    set(INTEL_COMPILER_NAME "dpcpp.exe")
-  else()
-    set(INTEL_COMPILER_NAME "dpcpp")
-  endif()
-  get_filename_component(COMPILER_NAME ${CMAKE_CXX_COMPILER} NAME)
-  if(COMPILER_NAME STREQUAL ${INTEL_COMPILER_NAME})
-    message(STATUS "Intel(R) oneAPI DPC++ Compiler is used")
-  else()
-    message(FATAL_ERROR
-      "Intel(R) oneAPI DPC++ Compiler is required. "
-      "Use \"CXX=${INTEL_COMPILER_NAME} cmake ..\" command to configure the sample.")
-  endif()
-endmacro()
-
 macro(FindOpenCLLibrary TARGET)
   if(DEFINED ENV{LD_LIBRARY_PATH})
     string(REPLACE ":" ";" SEARCH_LIB_PATH $ENV{LD_LIBRARY_PATH})
@@ -102,7 +72,7 @@ macro(FindOpenCLHeaders TARGET)
                               "${OPENCL_INC_PATH}/CL/cl_gl.h"
                               "${OPENCL_INC_PATH}/CL/cl_version.h"
                               "${OPENCL_INC_PATH}/CL/cl_platform.h"
-                      COMMAND "${PYTHON_EXECUTABLE}" "${PROJECT_SOURCE_DIR}/../build_utils/get_cl_headers.py" "${OPENCL_INC_PATH}" "${CMAKE_BINARY_DIR}")
+                      COMMAND "${PYTHON_EXECUTABLE}" "${PTI_CMAKE_MACRO_DIR}/get_cl_headers.py" "${OPENCL_INC_PATH}" "${CMAKE_BINARY_DIR}")
 
     target_include_directories(${TARGET}
       PUBLIC "${OPENCL_INC_PATH}")
@@ -122,7 +92,7 @@ macro(GetOpenCLTracingHeaders TARGET)
                             ${OPENCL_TRACING_INC_PATH}/CL/tracing_types.h)
   add_custom_command(OUTPUT ${OPENCL_TRACING_INC_PATH}/CL/tracing_api.h
                             ${OPENCL_TRACING_INC_PATH}/CL/tracing_types.h
-                    COMMAND "${PYTHON_EXECUTABLE}" "${PROJECT_SOURCE_DIR}/../build_utils/get_cl_tracing_headers.py" ${OPENCL_TRACING_INC_PATH} ${CMAKE_BINARY_DIR})
+                    COMMAND "${PYTHON_EXECUTABLE}" "${PTI_CMAKE_MACRO_DIR}/get_cl_tracing_headers.py" ${OPENCL_TRACING_INC_PATH} ${CMAKE_BINARY_DIR})
 
   target_include_directories(${TARGET}
     PUBLIC "${OPENCL_TRACING_INC_PATH}")
@@ -149,7 +119,7 @@ macro(GetITT TARGET)
                             ${ITT_INC_PATH}/ITT/ittnotify_types.h
                             ${ITT_INC_PATH}/ITT/ittnotify.h
                             ${ITT_INC_PATH}/ITT/legacy/ittnotify.h
-                    COMMAND "${PYTHON_EXECUTABLE}" "${PROJECT_SOURCE_DIR}/../build_utils/get_itt.py" ${ITT_INC_PATH} ${CMAKE_BINARY_DIR})
+                    COMMAND "${PYTHON_EXECUTABLE}" "${PTI_CMAKE_MACRO_DIR}/get_itt.py" ${ITT_INC_PATH} ${CMAKE_BINARY_DIR})
 
   target_include_directories(${TARGET}
     PUBLIC "${ITT_INC_PATH}")
@@ -226,7 +196,7 @@ macro(GetIGAHeaders TARGET)
                             ${IGA_INC_PATH}/IGA/iga_bxml_enums.hpp
                             ${IGA_INC_PATH}/IGA/kv.h
                             ${IGA_INC_PATH}/IGA/kv.hpp
-                    COMMAND "${PYTHON_EXECUTABLE}" "${PROJECT_SOURCE_DIR}/../build_utils/get_iga_headers.py" ${IGA_INC_PATH} ${CMAKE_BINARY_DIR})
+                    COMMAND "${PYTHON_EXECUTABLE}" "${PTI_CMAKE_MACRO_DIR}/get_iga_headers.py" ${IGA_INC_PATH} ${CMAKE_BINARY_DIR})
 
   target_include_directories(${TARGET}
     PUBLIC "${IGA_INC_PATH}")
@@ -243,7 +213,7 @@ macro(GetIGCHeaders TARGET)
                             ${IGC_INC_PATH}/IGC/patch_list.h)
   add_custom_command(OUTPUT ${IGC_INC_PATH}/IGC/program_debug_data.h
                             ${IGC_INC_PATH}/IGC/patch_list.h
-                    COMMAND "${PYTHON_EXECUTABLE}" "${PROJECT_SOURCE_DIR}/../build_utils/get_igc_headers.py" ${IGC_INC_PATH} ${CMAKE_BINARY_DIR})
+                    COMMAND "${PYTHON_EXECUTABLE}" "${PTI_CMAKE_MACRO_DIR}/get_igc_headers.py" ${IGC_INC_PATH} ${CMAKE_BINARY_DIR})
 
   target_include_directories(${TARGET}
     PUBLIC "${IGC_INC_PATH}")
@@ -324,7 +294,7 @@ macro(GetMDHeaders TARGET)
                             ${MD_INC_PATH}/MD/metrics_discovery_internal_api.h)
   add_custom_command(OUTPUT ${MD_INC_PATH}/MD/metrics_discovery_api.h
                             ${MD_INC_PATH}/MD/metrics_discovery_internal_api.h
-                    COMMAND "${PYTHON_EXECUTABLE}" "${PROJECT_SOURCE_DIR}/../build_utils/get_md_headers.py" ${MD_INC_PATH} ${CMAKE_BINARY_DIR})
+                    COMMAND "${PYTHON_EXECUTABLE}" "${PTI_CMAKE_MACRO_DIR}/get_md_headers.py" ${MD_INC_PATH} ${CMAKE_BINARY_DIR})
 
   target_include_directories(${TARGET}
     PUBLIC "${MD_INC_PATH}")
@@ -363,7 +333,7 @@ macro(FindGTPinLibrary TARGET)
                                 ${GTPIN_LIB_PATH}/GTPIN/libgtpin_core.so
                                 ${GTPIN_LIB_PATH}/GTPIN/libiga_wrapper.so
                                 ${GTPIN_LIB_PATH}/GTPIN/libstdc++.so.6
-                        COMMAND "${PYTHON_EXECUTABLE}" "${PROJECT_SOURCE_DIR}/../build_utils/get_gtpin_libs.py" ${GTPIN_LIB_PATH} ${CMAKE_BINARY_DIR})
+                        COMMAND "${PYTHON_EXECUTABLE}" "${PTI_CMAKE_MACRO_DIR}/get_gtpin_libs.py" ${GTPIN_LIB_PATH} ${CMAKE_BINARY_DIR})
 
       target_link_libraries(${TARGET}
         "${GTPIN_LIB_PATH}/GTPIN/libgtpin.so")
@@ -420,7 +390,7 @@ macro(GetGTPinHeaders TARGET)
                                 ${GTPIN_INC_PATH}/GTPIN/ged/intel64/ged_enum_types.h
                                 ${GTPIN_INC_PATH}/GTPIN/ged/intel64/ged.h
                                 ${GTPIN_INC_PATH}/GTPIN/ged/intel64/ged_ins_field.h
-                        COMMAND "${PYTHON_EXECUTABLE}" "${PROJECT_SOURCE_DIR}/../build_utils/get_gtpin_headers.py" ${GTPIN_INC_PATH} ${CMAKE_BINARY_DIR})
+                        COMMAND "${PYTHON_EXECUTABLE}" "${PTI_CMAKE_MACRO_DIR}/get_gtpin_headers.py" ${GTPIN_INC_PATH} ${CMAKE_BINARY_DIR})
 
       target_include_directories(${TARGET}
         PUBLIC "${GTPIN_INC_PATH}/GTPIN"
@@ -486,7 +456,7 @@ macro(FindL0HeadersPath TARGET L0_GEN_SCRIPT)
   add_custom_target(ze_gen_headers ALL
                     DEPENDS ${L0_GEN_INC_PATH}/tracing.gen)
   add_custom_command(OUTPUT ${L0_GEN_INC_PATH}/tracing.gen
-                     COMMAND ${CMAKE_COMMAND} -E env PYTHONPATH="${PROJECT_SOURCE_DIR}/../utils" "${PYTHON_EXECUTABLE}" ${L0_GEN_SCRIPT} ${L0_GEN_INC_PATH} "${L0_INC_PATH}/level_zero")
+                     COMMAND "${PYTHON_EXECUTABLE}" ${L0_GEN_SCRIPT} ${L0_GEN_INC_PATH} "${L0_INC_PATH}/level_zero")
   target_include_directories(${TARGET}
     PUBLIC "${L0_GEN_INC_PATH}")
   add_dependencies(${TARGET}

samples/cl_debug_info/cl_debug_info_collector.h

@@ -1,5 +1,5 @@
 //==============================================================
-// Copyright © 2020 Intel Corporation
+// Copyright (C) Intel Corporation
 //
 // SPDX-License-Identifier: MIT
 // =============================================================
@@ -15,7 +15,7 @@
 #include <mutex>
 #include <vector>
 
-#include "cl_tracer.h"
+#include "cl_api_tracer.h"
 #include "cl_utils.h"
 #include "igc_binary_decoder.h"
 #include "gen_symbols_decoder.h"
@@ -52,7 +52,7 @@ class ClDebugInfoCollector {
     ClDebugInfoCollector* collector = new ClDebugInfoCollector(device);
     PTI_ASSERT(collector != nullptr);
 
-    ClTracer* tracer = new ClTracer(device, Callback, collector);
+    ClApiTracer* tracer = new ClApiTracer(device, Callback, collector);
     if (tracer == nullptr || !tracer->IsValid()) {
       std::cerr << "[WARNING] Unable to create OpenCL tracer " <<
         "for target device" << std::endl;
@@ -204,7 +204,7 @@ class ClDebugInfoCollector {
     PTI_ASSERT(device_ != nullptr);
   }
 
-  void EnableTracing(ClTracer* tracer) {
+  void EnableTracing(ClApiTracer* tracer) {
     PTI_ASSERT(tracer != nullptr);
     tracer_ = tracer;
 
@@ -523,7 +523,7 @@ class ClDebugInfoCollector {
   }
 
  private: // Data
-  ClTracer* tracer_ = nullptr;
+  ClApiTracer* tracer_ = nullptr;
   cl_device_id device_ = nullptr;
 
   std::mutex lock_;

samples/cl_debug_info/tool.cc

@@ -1,5 +1,5 @@
 //==============================================================
-// Copyright © 2019-2020 Intel Corporation
+// Copyright (C) Intel Corporation
 //
 // SPDX-License-Identifier: MIT
 // =============================================================

samples/cl_gemm/main.cc

@@ -1,5 +1,5 @@
 //==============================================================
-// Copyright © 2019-2020 Intel Corporation
+// Copyright (C) Intel Corporation
 //
 // SPDX-License-Identifier: MIT
 // =============================================================

samples/cl_gemm_inst/main.cc

@@ -1,5 +1,5 @@
 //==============================================================
-// Copyright © 2019-2020 Intel Corporation
+// Copyright (C) Intel Corporation
 //
 // SPDX-License-Identifier: MIT
 // =============================================================

samples/cl_gemm_itt/ittnotify.cc

@@ -1,5 +1,5 @@
 //==============================================================
-// Copyright © 2019-2020 Intel Corporation
+// Copyright (C) Intel Corporation
 //
 // SPDX-License-Identifier: MIT
 // =============================================================

samples/cl_gemm_itt/main.cc

@@ -1,5 +1,5 @@
 //==============================================================
-// Copyright © 2019-2020 Intel Corporation
+// Copyright (C) Intel Corporation
 //
 // SPDX-License-Identifier: MIT
 // =============================================================

samples/cl_gpu_metrics/CMakeLists.txt

@@ -8,7 +8,10 @@ SetBuildType()
 
 # Tool Library
 
-add_library(clt_gpu_metrics SHARED "${PROJECT_SOURCE_DIR}/../loader/init.cc" tool.cc)
+add_library(clt_gpu_metrics SHARED
+  "${PROJECT_SOURCE_DIR}/../utils/trace_guard.cc"
+  "${PROJECT_SOURCE_DIR}/../loader/init.cc"
+  tool.cc)
 target_include_directories(clt_gpu_metrics
   PRIVATE "${PROJECT_SOURCE_DIR}/../utils"
   PRIVATE "${PROJECT_SOURCE_DIR}/../cl_hot_kernels")

samples/cl_gpu_metrics/cl_metric_collector.h

@@ -1,5 +1,5 @@
 //==============================================================
-// Copyright © 2020 Intel Corporation
+// Copyright (C) Intel Corporation
 //
 // SPDX-License-Identifier: MIT
 // =============================================================
@@ -14,7 +14,7 @@
 #include <thread>
 #include <vector>
 
-#include "cl_tracer.h"
+#include "cl_api_tracer.h"
 #include "cl_utils.h"
 #include "metric_device.h"
 
@@ -51,7 +51,7 @@ class ClMetricCollector {
       new ClMetricCollector(metric_device, group, set);
     PTI_ASSERT(collector != nullptr);
 
-    ClTracer* tracer = new ClTracer(device, Callback, collector);
+    ClApiTracer* tracer = new ClApiTracer(device, Callback, collector);
     if (tracer == nullptr || !tracer->IsValid()) {
       std::cerr << "[WARNING] Unable to create OpenCL tracer " <<
         "for target device" << std::endl;
@@ -182,7 +182,7 @@ class ClMetricCollector {
     PTI_ASSERT(set_ != nullptr);
   }
 
-  void EnableTracing(ClTracer* tracer) {
+  void EnableTracing(ClApiTracer* tracer) {
     PTI_ASSERT(tracer != nullptr);
     tracer_ = tracer;
 
@@ -326,7 +326,7 @@ class ClMetricCollector {
   }
 
  private: // Data
-  ClTracer* tracer_ = nullptr;
+  ClApiTracer* tracer_ = nullptr;
 
   MetricDevice* device_ = nullptr;
   md::IConcurrentGroup_1_5* group_ = nullptr;

samples/cl_gpu_metrics/tool.cc

@@ -1,5 +1,5 @@
 //==============================================================
-// Copyright © 2019-2020 Intel Corporation
+// Copyright (C) Intel Corporation
 //
 // SPDX-License-Identifier: MIT
 // =============================================================
@@ -82,7 +82,7 @@ static KernelMap GetKernelMap() {
     return KernelMap();
   }
 
-  const KernelIntervalList& kernel_interval_list =
+  const ClKernelIntervalList& kernel_interval_list =
     kernel_collector->GetKernelIntervalList();
   if (kernel_interval_list.size() == 0) {
     return KernelMap();

samples/cl_hot_functions/CMakeLists.txt

@@ -8,7 +8,10 @@ SetBuildType()
 
 # Tool Library
 
-add_library(clt_hot_functions SHARED "${PROJECT_SOURCE_DIR}/../loader/init.cc" tool.cc)
+add_library(clt_hot_functions SHARED
+  "${PROJECT_SOURCE_DIR}/../utils/trace_guard.cc"
+  "${PROJECT_SOURCE_DIR}/../loader/init.cc"
+  tool.cc)
 target_include_directories(clt_hot_functions
   PRIVATE "${PROJECT_SOURCE_DIR}/../utils")
 if(CMAKE_INCLUDE_PATH)