intel/ittapi

Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) API

Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) API

This ITT/JIT open source profiling API includes:

• Instrumentation and Tracing Technology (ITT) API
• Just-In-Time (JIT) Profiling API

The Instrumentation and Tracing Technology (ITT) API enables your application to generate and control the collection of trace data during its execution across different Intel tools.

ITT API consists of two parts: a static part and a dynamic part. The dynamic part is specific for a tool and distributed only with a particular tool. The static part is a common part shared between tools. Currently, the static part of ITT API is distributed as a static library and released under a BSD/GPLv2 dual license with every tool supporting ITT API.

Build

To build the library:

• On Windows, Linux, FreeBSD and OSX: requires cmake to be set in PATH
• Windows: requires Visual Studio installed or requires Ninja to be set in PATH
• To list available build options execute: python buildall.py -h

usage: buildall.py [-h] [-d] [-c] [-v] [-pt] [--force_bits] [-ft]

optional arguments:
  -h, --help      show this help message and exit
  -d, --debug     specify debug build configuration (release by default)
  -c, --clean     delete any intermediate and output files
  -v, --verbose   enable verbose output from build process
  -pt, --ptmark   enable anomaly detection support
  --force_bits    specify bit version for the target
  -ft, --fortran  enable fortran support

License

All code in the repo is dual licensed under GPLv2 and 3-Clause BSD licenses

Security

Please refer to the security policy for reporting vulnerabilties.

ittapi's Issues

License issue about object files

Hi,

I found there are some object files in the repo, such as "ittapi/include/fortran/posix/x86_64/ittfortran.o".
Are those object files under the same license? How to regenerate those files?

Thanks,
Yongxin

Codespell errors

Codespell errors on the following lines -
src/ittnotify/ittnotify_static.h:353: hist ==> heist, his
src/ittnotify/ittnotify_static.h:353: hist ==> heist, his
include/ittnotify.h:3649: immidiatelly ==> immediately
include/ittnotify.h:3962: hist ==> heist, his
include/ittnotify.h:3967: hist ==> heist, his
include/ittnotify.h:3972: hist ==> heist, his
include/ittnotify.h:3976: hist ==> heist, his

Add CI steps

This repository would benefit from having a CI workflow set up to build and test both the C and Rust components.

Clarification on License

Hi, sorry for a pedantic question, but could you clarify the dual licensing aspect.

Can downstream recipients of this code choose to license it just under 3-Clause BSD terms or just under GPLv2 terms. Or is dual licensing meant to be the combination of 3-Clause BSD AND GPLv2 terms.
Thanks!

__itt_marker on VTune

What is the correct way to use __itt_marker to get it to display a marker on VTune?

I think I tried everything such as (with all possible scopes):

__itt_marker(domain, __itt_null, message, __itt_scope_global);

I can get overlapped tasks working but not markers.

Profiling a function from Dynamic Loaded library

Os/Distro: Archlinux and vtune installed with the intel-oneapi-basekit package (2023 0.0.25537-3)

Context: I want to debug the performance of a specialized generated C code that do some kind of matrix multiplication computation. The C code is generated and compiled in a shared object and used in a driver code written in rust. The driver code prepare data, load the lib.so and profile it.

Issue: Little/no info available in the bottom-up view inside vtune-gui about the task involving a call to an external function defined in the dynamic library.

Doing exactly the same with a statically linked extern fn works as expected and gives performance info.

Is this a known issue ? Is there any workaround ?

Minimal reproducible project in the zip.

minimalissueittnotify.zip

Add a conventional Rust layer to ittapi_rs

Working with ittapi is not the most simple thing I have done (😁) and, in order to increase adoption and speed up integration with other projects, I could use a shim layer that makes ittapi_rs use Rust conventions (e.g., it could pass around &str instead of *const c_char). What is published currently corresponds to a *-sys crate: a direct transcription of the C API to Rust. I am requesting a higher level crate built on top of that.

The intel-seapi crate had this higher-level API--see the docs. But that crate is no longer maintained. Can we add this type of functionality to ittapi_rs, potentially creating separate ittapi and ittapi-sys crates?

error: useless cast to type ‘long long unsigned int’

When I compile, gcc complains:

/opt/intel/oneapi/vtune/latest/sdk/include/ittnotify.h:1907:13: error: useless cast to type ‘long long unsigned int’ [-Werror=useless-cast]
 1907 |     id.d2 = (unsigned long long)extra;
      |             ^~~~~~~~~~~~~~~~~~~~~~~~~

and compile breaks due to "all warnings being treated as errors"

Where is `IttnotifyInfo` defined/declared?

LLVM includes the IntelJITEventsWrapper that was updated in Profiling the code generated by MCJIT engine using Intel VTune profiler.

The commit message mentions-

To overcome limitations described above, we have introduced new APIs as a part of Intel ITT APIs to report the entire in-memory ELF module to be further processed as regular ELF binaries with debug information.

And from the diff, it seems to revolve around calling the iJitIttNotifyInfo func with the memory region that contains the generated ELF.

...Except, IttnotifyInfoFunc is initialized to 0. And there is no mention of a similarly-named method inside jitprofiling.h as there is for iJIT_NotifyEvent (the older API).

As a result, the default IntelJITEventListener in LLVM is totally non-functional. It simply ignores the events when IttnotifyInfoFunc is 0.

So the question is- where is IttnotifyInfoFunc declared, and how can we use it from inside the LLVM listener?

Rust ittapi-sys bindings out of date, bindgen-up-to-date.rs possibly broken.

I recently discovered Intel Vtune https://www.intel.com/content/www/us/en/docs/vtune-profiler/user-guide/2024-0/anomaly-detection-analysis.html
It required the following functions to be integrated with the application:

__itt_mark_pt_region_begin(region);
__itt_mark_pt_region_end(region);

But they're not available in the rust ittapi(-sys) bindings.
I tried regenerating with BLESS=1 but the functions didn't show up.
Any chance bindgen-up-to-date.rs is broken?

Off note:
Most functions in the public API have a ITTAPI which seem to be missing here for both of these functions. Not sure if this is relevant or problematic.

Move LICENSE files?

It may be more clear what license this code is released under if the src/ittnotify/LICENSE.BSD and src/ittnotify/LICENSE.GPL licenses were moved to the top-level directory. I am confused whether the include files are also released under these licenses?

ci: building the C library silently fails

In #40, I added a way to build the C library during CI to verify that things are working as expected. The CI workflow passed (as expected) using python buildall.py and I didn't give it much more thought. Recently, @bnjbvr brought to my attention that the python buildall.py can silently fail, giving us the impression that the C library has been built when in fact it has not. In a recent commit, here are the results:

• on Windows, CI seems to be fine: the libraries are built with no issue (log)
• on macOS, the script calls CMake incorrectly (log); it looks like the --target flag should have a parameter (BUILD_ALL is used on Windows)
• on Ubuntu, the script emits the same error as macOS but additionally fails with a missing include, bits/libc-header-start.h (log); it is unclear whether these glibc headers need to be installed as a separate dependency or if some include path is missing

There are multiple issues here that need to be fixed:

1. buildall.py should not fail silently; it should exit immediately with a non-zero error code if any command fails
2. the buildall.py --target flag should be filled in for non-Windows builds
3. any needed include paths (or dependencies that provide them) should be a) documented in the README and b) updated in the main.yml GitHub workflow

Request to replace the .o files with source code compilation in the include folder

I tried to integrate the ittapi repo into pytorch as its third party library, but Meta has concerns of having .o files in source tree for the integration.
pytorch/pytorch#93119

OpenBSD like FreeBSD uses stdlib.h not malloc.h

Trying to build wasmtime on OpenBSD noticed it's trying to pull in malloc.h. It should be using stdlib.h like FreeBSD. Unless you get to it first, I'll submit a MR shortly. Thanks

[Tsan] Data race detection in mutex_init_and_lock

Because the global __itt__global is initialized in a critical section (here), Clang Thread Sanitizer flags it as a race condition.
We stumbled upon it by calling itt_string_create in a parallel section.

It is not critical, but it forces users to suppress those warnings. Maybe separating the initialization from the lock, and statically initializing the mutex would avoid this issue.

CMake 3.19 writes deprecation warning

CMake 3.19 writes deprecation for IttApi:

CMake Deprecation Warning at Externals/IttApi/CMakeLists.txt:7 (cmake_minimum_required):
  Compatibility with CMake < 2.8.12 will be removed from a future version of
  CMake.

  Update the VERSION argument <min> value or use a ...<max> suffix to tell
  CMake that the project does not need compatibility with older versions.

How to use __itt_pt_region_create

I use __itt_pt_region_create in C program and include library files(include/ittnotify.h). But when I compile the program, I get an error: "undefined reference to `__itt_pt_region_create_ptr__3_0' ". Are there steps I'm missing?

Enable debugging of source language of Wasm files

@jlb6740, I suspect this issue isn't exclusive to the code in this repository, but it is related: when I'm running a program in a Wasm runtime, can we provide a way for ittapi_rs to map executed code back to both 1) its Wasm form and 2) its original source language (e.g., C, Rust, AssemblyScript)?

Data races over function pointer initialization

The check of a function pointer can be performed concurrently with initialization phase of function pointers. It is not a big deal for x86 but we need to suppress (oneapi-src/oneTBB#659) Thread Sanitizer reports. Moreover, C/C++ does not state that pointers are atomic and considers such accesses as data races.

buildall.py requires 32bit compatibility layer

buildall.py requires 32bit compatibility layer but there is no information about this dependency.
The same time buildall.py has code:

    target_bits = ['64']
    if (sys.platform != 'darwin'):  # on MAC OSX we produce FAT library including both 32 and 64 bits
        target_bits.append('32')

    print("target_bits", target_bits)

suggesting that it should be somehow configured. I didn't find how to disable 32bit build. It seems to be an error.

Check that the Rust build script stays in sync with CMake configuration

To avoid a cmake dependency, the Rust bindings (ittapi-rs) use direct cc commands in its build.rs script to build the ittnotify library. These cc commands could eventually get out of sync with the CMakeLists.txt configuration. To avoid this, we could add a CI step that builds the C library using cmake, builds the C library using the build.rs script, hash both libraries, and check that the results are the same. This depends on #17 being implemented.

Better error messages

Currently, the Rust JIT profiling API can only report an error with message "error when notifying event". That doesn't give me much to go on when troubleshooting, especially when all I have is this message and a stack trace reported by somebody else.

At minimum I think it would help if it called iJIT_IsProfilingActive and returned a different error message when loading the shared library failed, as opposed to something else going wrong.

Add Security Policy

Adding a security policy (security.md) for vulnerability reporting is generally a good practice, and projects like Envoy have this as a requirement for adding external dependencies.
If there are no objections, I can add a barebones one. Is there any point of contact for such vulnerabilities?
Otherwise, if any maintainer can configuring private vulnerability reporting, that would work as well. The security policy needs to have one of the above options.

About the latest release

👋 is 3.24.6 the latest release, if so, it looks like the release did not get completed (ie the release notes did not finish). Thanks!

relates to Homebrew/homebrew-core#159338

Compile ittapi-rs' C code on Windows

I've noticed that the ittapi Rust wrappers don't build anything during execution of the build script on Windows: https://github.com/intel/ittapi/blob/master/ittapi-rs/build.rs#L8-L9

When trying to remove the OS-specific guard (that is, have build.rs compile on Windows with the same code that's for Linux), I get a compiler error with MSVC's 2022 compiler. Unfortunately, the error message itself seems to be lost, so I don't have any idea of what goes wrong under the hood.

I have no actual proof of this, but I actually suspect that the bindings may have to be different for Windows: could there be ABI differences, e.g. field alignment / ordering?

cc @jlb6740 @abrown

Crash when running with VTune 2020 (build 605129)

My application crashes when I link with ittapi statically and run it with VTune. If I link against the static library provided by VTune it works. Tested on Ubuntu 19.04.

My guess: looks like VTune is using its own libc and it is conflicting with the sytem's libc.

Crash looks like this:

#0  __strlen_avx2 () at ../sysdeps/x86_64/multiarch/strlen-avx2.S:96
#1  0x00007f365f5d322e in ?? () from /opt/intel/vtune_profiler_2020.0.0.605129/lib64/runtime/libittnotify_collector.so
#2  0x00007f365f5617ab in ?? () from /opt/intel/vtune_profiler_2020.0.0.605129/lib64/runtime/libittnotify_collector.so
#3  0x00007f365f56191a in __itt_domain_create () from /opt/intel/vtune_profiler_2020.0.0.605129/lib64/runtime/libittnotify_collector.so
#4  0x00007f365f5620b4 in __itt_api_init () from /opt/intel/vtune_profiler_2020.0.0.605129/lib64/runtime/libittnotify_collector.so
#5  0x000056354e3a6a58 in __itt_init_ittlib ()
#6  0x000056354e3a2f1c in __itt_frame_begin_v3_init_3_0 ()
#7  0x000056354e3390bc in app::run() ()
#8  0x000056354e32246f in main ()

Cross-compiling ITTAPI in LLVM with mingw32

Cross compiling LLVM prior to LLVM 12 with mingw32 and -DLLVM_USE_INTEL_JITEVENTS used to work.

LLVM 12 switchted to ittapi in https://reviews.llvm.org/D86435 and in the cross-compilation environment for Julia's dependencies I am seeing:

[16:17:45] ninja: job failed: /opt/bin/i686-w64-mingw32-libgfortran4-cxx11/i686-w64-mingw32-gcc --sysroot=/opt/i686-w64-mingw32/i686-w64-mingw32/sys-root/ -DGTEST_HAS_RTTI=0 -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE -D__STDC_CONSTANT_MACROS -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -Ilib/ExecutionEngine/IntelJITEvents -I/workspace/srcdir/llvm-project/llvm/lib/ExecutionEngine/IntelJITEvents -Iinclude -I/workspace/srcdir/llvm-project/llvm/include -I/workspace/srcdir/llvm-project/llvm/lib/ExecutionEngine/IntelJITEvents/.. -Iittapi/include -remap -D__USING_SJLJ_EXCEPTIONS__ -D__CRT__NO_INLINE -fno-gnu-unique -Werror=date-time -Wall -Wextra -Wno-unused-parameter -Wwrite-strings -Wno-missing-field-initializers -pedantic -Wno-long-long -Wimplicit-fallthrough -Wno-comment -O3 -DNDEBUG -MD -MT lib/ExecutionEngine/IntelJITEvents/CMakeFiles/LLVMIntelJITEvents.dir/__/__/__/ittapi/src/ittnotify/ittnotify_static.c.obj -MF lib/ExecutionEngine/IntelJITEvents/CMakeFiles/LLVMIntelJITEvents.dir/__/__/__/ittapi/src/ittnotify/ittnotify_static.c.obj.d -o lib/ExecutionEngine/IntelJITEvents/CMakeFiles/LLVMIntelJITEvents.dir/__/__/__/ittapi/src/ittnotify/ittnotify_static.c.obj   -c ittapi/src/ittnotify/ittnotify_static.c
[16:17:45] In file included from ittapi/src/ittnotify/ittnotify_static.c:7:0:
[16:17:45] ittapi/src/ittnotify/ittnotify_config.h:243:1: error: multiple storage classes in declaration specifiers
[16:17:45]  ITT_INLINE long
[16:17:45]  ^~~~~~~~~~
[16:17:45] ittapi/src/ittnotify/ittnotify_config.h:245:1: error: multiple storage classes in declaration specifiers
[16:17:45]  ITT_INLINE long __itt_interlocked_increment(volatile long* ptr)
[16:17:45]  ^~~~~~~~~~
[16:17:45] ittapi/src/ittnotify/ittnotify_static.c:10:0: warning: "PATH_MAX" redefined
[16:17:45]  #define PATH_MAX 512
[16:17:45]  
[16:17:45] In file included from /opt/i686-w64-mingw32/lib/gcc/i686-w64-mingw32/7.1.0/include-fixed/limits.h:194:0,
[16:17:45]                  from /opt/i686-w64-mingw32/lib/gcc/i686-w64-mingw32/7.1.0/include-fixed/syslimits.h:7,
[16:17:45]                  from /opt/i686-w64-mingw32/lib/gcc/i686-w64-mingw32/7.1.0/include-fixed/limits.h:34,
[16:17:45]                  from /opt/i686-w64-mingw32/i686-w64-mingw32/sys-root/include/stdlib.h:11,
[16:17:45]                  from /opt/i686-w64-mingw32/lib/gcc/i686-w64-mingw32/7.1.0/include/mm_malloc.h:27,
[16:17:45]                  from /opt/i686-w64-mingw32/lib/gcc/i686-w64-mingw32/7.1.0/include/xmmintrin.h:34,
[16:17:45]                  from /opt/i686-w64-mingw32/lib/gcc/i686-w64-mingw32/7.1.0/include/emmintrin.h:31,
[16:17:45]                  from /opt/i686-w64-mingw32/i686-w64-mingw32/sys-root/include/winnt.h:2299,
[16:17:45]                  from /opt/i686-w64-mingw32/i686-w64-mingw32/sys-root/include/minwindef.h:163,
[16:17:45]                  from /opt/i686-w64-mingw32/i686-w64-mingw32/sys-root/include/windef.h:8,
[16:17:45]                  from /opt/i686-w64-mingw32/i686-w64-mingw32/sys-root/include/windows.h:69,
[16:17:45]                  from ittapi/src/ittnotify/ittnotify_config.h:201,
[16:17:45]                  from ittapi/src/ittnotify/ittnotify_static.c:7:

https://dev.azure.com/JuliaPackaging/Yggdrasil/_build/results?buildId=10551&view=logs&jobId=64e4dabb-4ec3-501c-2d64-463504d2fa74&j=64e4dabb-4ec3-501c-2d64-463504d2fa74&t=884cc234-77a0-5797-1cd5-7376d470f420