Add ITT/JIT API documentation source files and gh-action to deploy docs to gh-pages #175
Conversation
|
@vikramts please review this PR |
| @@ -0,0 +1,22 @@ | |||
| .. _index: | |||
|
|
|||
| Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) API Documentation | |||
There was a problem hiding this comment.
The Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) APIs
| ============================================================================================ | ||
|
|
||
| .. note:: | ||
|
|
There was a problem hiding this comment.
Remove "Note". Do not start a topic with a Note.
| The ITT/JIT API Documentation from the Intel® VTune Profiler and Intel® Graphics | ||
| Performance Analyzers User Guides has been consolidated into this repository, | ||
| providing a single, unified source of information. | ||
|
|
There was a problem hiding this comment.
The Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) APIs are open source applications that you use with Intel software tools to collect and manage trace data during performance analysis. The APIs are available in Intel® VTune Profiler and Intel® Graphics Performance Analyzers (Intel® GPA).
This repository contains documentation that explains the use of these APIs.
| source feature of Intel's Analyzers tools that allows applications to generate and control | ||
| trace data during their execution. It enables developers to pinpoint and measure specific areas | ||
| of their code, providing valuable insights into performance bottlenecks and resource utilization. | ||
|
|
There was a problem hiding this comment.
When you use Intel analyzer tools to improve the performance of your software application, during execution, use the Intel® Instrumentation and Tracing Technology (ITT) and Just-In-Time (JIT) APIs to generate trace data and control its collection. You use the ITT/JIT APIs to identify and measure specific areas of code to get insights into performance bottlenecks and resource utilization.
| - JIT (Just-In-Time) Profiling API. | ||
| It provides functionality to report information about just-in-time generated code that | ||
| can be used by performance profiling tools. | ||
|
|
There was a problem hiding this comment.
The ITT API powers your application to generate and control the collection of trace data during its execution across Intel tools. The JIT API reports information about just-in-time generated code for use by performance profiling tools.
There was a problem hiding this comment.
Question - what is the benefit of JIT code? it sounds like the ITT description is almost identical to the ITT-JIT description. So can we differentiate the value provided by these two APIs?
| It provides functionality to report information about just-in-time generated code that | ||
| can be used by performance profiling tools. | ||
|
|
||
| The ITT/JIT API consists of two parts: a **static** part and a **dynamic** part. |
There was a problem hiding this comment.
Are we talking about ONE API or TWO APIs? The content started off with ITT and JIT APIs but here, I see ITT/JIT API. Please stick to a single version, whatever you choose.
| a dynamic(shared) library. The reference implementation of the **dynamic** part is provided | ||
| `here <ref_collector>`__ as a Reference Collector. | ||
| - The **static** part is a common part shared between tools. Currently, the static part is | ||
| distributed as an open source static library: `ittapi <https://github.com/intel/ittapi>`__ |
There was a problem hiding this comment.
The ITT/JIT APIs contain two parts:
- The dynamic part is specific for a tool. This part is distributed as a dynamic (shared) library with a particular tool
only. You can find the
reference implementation of the **dynamic** part as a Reference Collector here <ref_collector>__ . - The static part is a common part that is shared between tools. The static part is
distributed as an open source static library (ittapi <https://github.com/intel/ittapi>__).
Question : What do you mean by dynamic part is specific for a tool? Which tool or tools? Also, avoid using words like "currently/recently" etc because these words are relative. The info we publish should always be current and accurate, until it is time for an update :)
| @@ -0,0 +1,57 @@ | |||
| .. _build: | |||
|
|
|||
| Build from Source | |||
There was a problem hiding this comment.
Build the APIs
('from Source' does not make sense to me...from what source? )
| - To enable Fortran support, requires `Intel Fortran Compiler | ||
| <https://www.intel.com/content/www/us/en/developer/tools/oneapi/fortran-compiler-download.html>`__ | ||
| installed. | ||
|
|
There was a problem hiding this comment.
Technical Requirements
Before you build the ITT/JIT APIs, make sure you have the following hardware and software tools:
- Get general development tools, including the Intel® oneAPI DPC++/C++ Compiler.
- Install Python https://python.org__ (version 3.6 or newer)
- Install CMake https://cmake.org__ (version 3.5 or newer)
- For a Windows* system, install one of these:
--Microsoft Visual Studio https://visualstudio.microsoft.com__ (version 2015 or newer)
--Ninja https://ninja-build.org__ (version 1.9 or newer) - To enable support for Fortran, install the Intel® Fortran Compiler https://www.intel.com/content/www/us/en/developer/tools/oneapi/fortran-compiler-download.html
| installed. | ||
|
|
||
|
|
||
| Download the Source Code |
| .. code-block:: console | ||
|
|
||
| git clone https://github.com/intel/ittapi.git | ||
|
|
There was a problem hiding this comment.
To get the source code for the ITT/JIT APIs, do one of the following:
- Download
the code <https://github.com/intel/ittapi/releases>__ - Clone the repository https://github.com/intel/ittapi.git`__.
.. code-block:: console
git clone https://github.com/intel/ittapi.git
|
|
||
| Build | ||
| ----- | ||
|
|
| Build | ||
| ----- | ||
|
|
||
| To build the ITT/JIT API static library execute: |
There was a problem hiding this comment.
To build the static part of the ITT/JIT APIs, run this command:
.. code-block:: console
python buildall.py
Use these options to build the static part:
.. code-block:: console
usage: python buildall.py [-h] [-d] [-c] [-v] [-pt] [-ft] [--force_bits]
optional arguments:
-h, --help Display this help message and exit
-d, --debug Specify a debug build configuration (release by default)
-c, --clean Delete any intermediate and output files
-v, --verbose Enable verbose output from the build process
-pt, --ptmark Enable support for anomaly detection
-ft, --fortran Enable support for Fortran
--force_bits Specify the bit version for the target
--vs Specify the version of Microsoft* Visual Studio (Windows systems only)
--cmake_gen Specify the cmake build generator (Windows systems only)
| @@ -0,0 +1,33 @@ | |||
| .. _api-support: | |||
|
|
|||
| API Usage and Reference | |||
| The ITT API is a set of pure C/C++ functions. There are no Java* or .NET* | ||
| APIs. If you need runtime environment support, you can use a JNI, or C/C++ | ||
| function call from the managed code. | ||
|
|
There was a problem hiding this comment.
(Remove the Note)
This section describes how you use ITT/JIT APIs with various language bindings. The ITT/JIT APIs are a set of C/C++ functions and use no Java* or .NET* code. For support with your runtime environment, use a Java Native Interface (JNI) or C/C++ function call from the code you manage.
|
|
||
| C/C++ API Usage and Reference: | ||
| ------------------------------ | ||
|
|
| @@ -0,0 +1,43 @@ | |||
| .. _itt-api-support: | |||
|
|
|||
| ITT API | |||
There was a problem hiding this comment.
Intel® Instrumentation and Tracing Technology API (ITT API)
| The Instrumentation and Tracing Technology API (ITT API) enables | ||
| your application to generate and control the collection of trace | ||
| data during its execution. | ||
|
|
There was a problem hiding this comment.
Use the Intel® Instrumentation and Tracing Technology API (ITT API) to
generate trace data and control its collection during the execution of your application.
There was a problem hiding this comment.
(My concern here is that we are are repeating what was already said earlier. Any new info we can share?)
| - Supports applications in C/C++ and Fortran environments on Windows*, | ||
| Linux* or FreeBSD* systems. | ||
| - Supports instrumentation for tracing application code. | ||
|
|
There was a problem hiding this comment.
Use the ITT API to:
- Collect traces that help you manage the overhead on application performance
- Enable trace collection without having to recompiling your application
- Enable instrumentation for deeper analysis. (How is this different from the first bullet?)
You can use the ITT API to collect trace data from C, C++, or Fortran applications that run on Windows*, Linux* or FreeBSD* systems.
| User applications/modules linked to the static ITT API library do not | ||
| have a runtime dependency on a dynamic library. Therefore, they can be | ||
| executed independently. | ||
|
|
There was a problem hiding this comment.
(This line is a bit of a jump from the previous lines)
The ITT API has static and dynamic library components. The applications and modules you link to the static library do not have a runtime dependency on the dynamic library. Therefore, you can run these components independently.
|
|
||
|
|
||
| ITT API enables you to manually instrument your application for further | ||
| application performance analysis. |
There was a problem hiding this comment.
This was already covered in bullet#3 above. So do we need this sentence?
| .. _compile-and-link-with-itt-api: | ||
|
|
||
| Compile and Link with ITT API | ||
| ============================= |
There was a problem hiding this comment.
You mean compile your app?
Can we make this "Link ITT API With Your Application"?
|
|
||
|
|
||
| Before instrumenting your application, configure your build system to be | ||
| able to reach the API headers and libraries: |
There was a problem hiding this comment.
Step 1: Configure Your Build System
Before instrumenting your application with ITT API, configure your build system to establish access to the headers and libraries of the API:
| to your ``LIBRARIES`` path | ||
|
|
||
|
|
||
| Include the ITT API Header or Module in Your Application |
There was a problem hiding this comment.
Step 2: Include the ITT API Header/Module in Your Application
| -------------------------------------------------------- | ||
|
|
||
|
|
||
| **For C/C++ Applications** |
|
|
||
| Add the following ``#include`` statements to every source file that you | ||
| want to instrument: | ||
|
|
There was a problem hiding this comment.
For every source file that you want to instrument, add the following #include statements :
| The ``ittnotify.h`` header contains definitions of ITT API routines and | ||
| important macros which provide the correct logic of API invocation from | ||
| a user application. | ||
|
|
There was a problem hiding this comment.
The ittnotify.h header contains definitions for ITT API routines and important macros that provide the correct logic to invoke the API from your application.
| ``INTEL_NO_ITTNOTIFY_API`` macro in your project at compile time, either | ||
| on the compiler command line, or in your source file, prior to including | ||
| the ``ittnotify.h`` file. | ||
|
|
There was a problem hiding this comment.
When tracing is disabled, The ITT API incur almost zero overhead. To achieve completely zero overhead, you can compile out all ITT API calls from your application.
To do this, prior to including the ittnotify.h file, define the INTEL_NO_ITTNOTIFY_API macro in your project at compile time. You can do this from the compiler command line or in your source file.
| the ``ittnotify.h`` file. | ||
|
|
||
|
|
||
| **For Fortran Applications** |
|
|
||
| Add the ``ITTNOTIFY`` module to your source files with the following | ||
| source line: | ||
|
|
There was a problem hiding this comment.
Add the ITTNOTIFY module to your source files. Use the following
source line:
| USE ITTNOTIFY | ||
|
|
||
|
|
||
| Insert ITT Notifications in Your Application |
There was a problem hiding this comment.
Step 3: Insert ITT Notifications in Your Application
|
|
||
| Insert ``__itt_*`` (C/C++) or ``ITT_*`` (Fortran) notifications in your | ||
| source code. | ||
|
|
There was a problem hiding this comment.
Can we change this into a small table? I am sorry that my formatting is not great here!
To insert ITT notifications in your application, use:
Notification Example
C/C++ applications `_itt*`` .. code:: cpp
__itt_pause();
Fortran applications ITT_* .. code:: cpp
CALL ITT_PAUSE()
| CALL ITT_PAUSE() | ||
|
|
||
|
|
||
| For more information, see `Instrumenting Your Application |
There was a problem hiding this comment.
To learn more, open:
Instrumenting Your Application<instrument-your-application.html>__ITT API Reference<itt-api-reference.html>__.
|
|
||
| Link the libittnotify Static Library to Your Application | ||
| -------------------------------------------------------- | ||
|
|
There was a problem hiding this comment.
Step 4: Link the libittnotify Static Library to Your Application
| this static library loads the ITT API data dynamic collector and forwards ITT | ||
| API instrumentation data to it. If tracing is disabled, the static library | ||
| ignores ITT API calls, providing nearly zero instrumentation overhead. | ||
|
|
There was a problem hiding this comment.
Once you finish inserting ITT notifications in your application, the next step is to link the libittnotify static library. This library is libittnotify.a in Linux* and FreeBSD* systems and libittnotify.lib in Windows* systems.
If you have enabled tracing, the static library loads the dynamic collector of the ITT API data and forwards to the collector instrumentation data from the ITT API.
If you have disabled tracing, the static library ignores ITT API calls, resulting in near-zero instrumentation overhead.
|
|
||
| Set the INTEL_LIBITTNOTIFY environment variables to enable data collection | ||
| -------------------------------------------------------------------------- | ||
|
|
There was a problem hiding this comment.
Step 5: Load the Dynamic Library (Do we need to specify the variable name in the section title?)
After you link the static library, you must load the dynamic library of the ITT API to your application. To do this, depending on your system architecture, set the INTEL_LIBITTNOTIFY32 or the INTEL_LIBITTNOTIFY64
environment variable.
|
|
||
|
|
||
| Make sure to set these environment variables to enable data collection: | ||
|
|
There was a problem hiding this comment.
This line is confusing. The previous paragraph seems to imply that the loading of the dynamic lib depends on the variable status...but here we ask the user to set the variable. So why not mention that upfront and avoid any confusion? I would suggest using the revision I propose so we can remove line 113.
| Make sure to set these environment variables to enable data collection: | ||
|
|
||
|
|
||
| **On Windows** |
| set INTEL_LIBITTNOTIFY64=<install-dir>\bin64\runtime\ittnotify_collector.dll | ||
|
|
||
|
|
||
| **On Linux** |
| export INTEL_LIBITTNOTIFY64=<install-dir>/lib64/runtime/libittnotify_collector.so | ||
|
|
||
|
|
||
| **On FreeBSD** |
|
|
||
| Unicode Support | ||
| --------------- | ||
|
|
There was a problem hiding this comment.
We have listed 5 steps so far as a procedure. This section is not a step. Is this just reference info? Does this section need to remain here?
| setenv INTEL_LIBITTNOTIFY64=<target-package>/lib64/runtime/libittnotify_collector.so | ||
|
|
||
|
|
||
| Unicode Support |
There was a problem hiding this comment.
Support for Unicode
(Why is Unicode in lower case and in upper case as UNICODE in the next paragraph?)
|
|
||
| All API functions that take parameters of type ``__itt_char`` follow the | ||
| Windows OS unicode convention. If UNICODE is defined when compiling on a | ||
| Windows OS, ``__itt_char`` is ``wchar_t``, otherwise it is ``char``. The |
There was a problem hiding this comment.
Is UNICODE supposed to be an env variable?
| actual function names are suffixed with ``A`` for the ASCII APIs and | ||
| ``W`` for the unicode APIs. Both types of functions are defined in the | ||
| DLL that implements the API. | ||
|
|
There was a problem hiding this comment.
All API functions that take parameters of type __itt_char follow the
Windows OS unicode convention.
When compilation happens on a Windows system, if the UNICODE environment variable is defined, __itt_char is set to wchar_t. If the UNICODE variable is not defined, __itt_char is set to char.
The actual function names are suffixed with A for the ASCII APIs and
W for the Unicode APIs. Both types of functions are defined in the
DLL that implements the API.
| Strings that are all ASCII characters are internally equivalent for both | ||
| the unicode and the ASCII API versions. For example, the following | ||
| strings are equivalent: | ||
|
|
There was a problem hiding this comment.
Strings that contain only ASCII characters are internally equivalent for both
the Unicode and ASCII API versions. For example, the following
strings are equivalent:
The ITT/JIT API Documentation from the Intel® VTune Profiler and Intel® Graphics Performance Analyzers User Guides has been consolidated into this repository, providing a single, unified source of information.
This PR introduces the following changes:
docsfolder containing .rst source files for the project documentation, readme with build steps using sphinx and sphinx configuration files.gh-pagesbranch. The workflow triggers on changes to thedocsfolder and ensures the latest documentation is always available online. The documentation is deployed to GitHub Pages, making it accessible via the repository's GitHub Pages URL.The Preview of the rendered documentation is available here: https://eparshut.github.io/ittapi