11. AMD uProf Application Programming Interfaces

The AMDProfileControl APIs allow you to limit the profiling scope to a specific portion of the code within the target application. This is particularly helpful when within a long running application, the user wants to focus on performance monitoring and analysis of a specific area of code.

Usually, while profiling an application, samples for the entire control flow of the application execution will be collected, that is, from the start of execution till end of the application execution. The control APIs can be used to enable the profiler to collect data only for a specific part of application, for example, a CPU intensive loop, a hot function etc.

The target application needs to be recompiled after instrumenting that with profiling enable/disable APIs to profile the required code regions only.

11.1. CPU Profile Control APIs

Profile Control APIs allow you to pause and resume profiling at runtime from within the application being profiled. You can call these APIs from C/C++ or Python code. Note that these APIs control profiling only—they do not pause or resume the execution of the application itself.

It is mandatory to use the CLI command line option: –start-paused or keep Enable start paused option ON in GUI, while launching the application instrumented by profile control APIs, otherwise the behavior is undefined.

To switch on the GUI Enable start paused option:

1. Select the Profile Target page and click Next.

2. Click Advanced Options.

3. On the Advanced Options page, in the Profile Scheduling section, switch on the Enable start paused option.

There are two groups of APIs for pause/resume. APIs from different groups cannot be mixed within a single run of an application.

• Group1: The APIs amdProfileResume(); and amdProfilePause(); are respectively for resuming and pausing the profiling.

• Group2: The APIs amdProfileStrictPause() and amdProfileStrictResume() for resuming and pausing the profiling.

11.1.1. Difference between Group1 and Group2 APIs

As described earlier, Profile Control APIs are for profiling a small (in which user is interested) portion of the typically long running program.

For Group1 APIs, on a amdProfilePause() call, the profile-pause message, from the amdProfilePause() call, propagates through the application layers to reach a point where the actual stop of the profiling happens. Meanwhile, the application continues to run with profiling on state. Hence some additional instructions are also profiled, after the pause call.

Similar thing happens with amdProfileResume() call, where application continues to run few more instructions after its amdProfileResume() call without profiling.

In general, this is not an issue, but when the user is trying to monitor/profile a short running functions, this behavior is undesirable.

Group2 APIs i.e. amdProfileStrictPause() and amdProfileStrictResume() remove the above-mentioned issue by strictly pausing or resuming on these calls respectively. But Group2 APIs do this at the cost of speed.

So, Group1 APIs are faster but slip few instructions, while Group2 APIs are slower but produce no error.

11.1.2. C/C++ API Descriptions

To use C++ APIs, user need to include the header AMDProfileController.h. This file is available in the include directory under AMD uProf’s install path: ~/Foo/AMDuProf_Linux_x64_5.x.x/include/AMDProfileController.h, hence that include folder ~/Foo/AMDuProf_Linux_x64_5.x.x/include/ must be in the include path, while building the instrumented application.

For linking, the library user must include the library path of libAMDProfileController.so, whose path is: /lib/x64/shared/libAMDProfileController.so.

Hence, C++ compilation command can be:

$ g++ -std=c++11 -g <sourcefile.cpp> -I /include -L/lib/x64/ -lAMDProfileController -lrt -pthread

where for C code, the compilation can be:

$ gcc -g <sourcefile.c> -I /include -L/lib/x64/ - lAMDProfileController -lrt -pthread

11.1.3. Static Library

The instrumented application should link with the AMDProfileController static library available in:

11.1.3.1. Windows

<AMDuProf-install-dir>\lib\x86\AMDProfileController.lib
<AMDuProf-install-dir>\lib\x64\AMDProfileController.lib

11.1.3.2. Linux

<AMDuProf-install-dir>/lib/x64/libAMDProfileController.a

11.1.4. C/C++ API Descriptions

11.1.4.1. Group1

There are two C/C++ based APIs from Group1:

11.1.4.2. Group2

There are two C/C++ based APIs for Group2. For more information, refer to Difference between Group1 and Group2 APIs.

11.1.5. Python API Descriptions

Python Profile Control APIs are like C/C++ APIs. For python, Pause/Resume APIs are supported for Python version 3.7 onwards.

To use these APIs, you must:

1. Set environment variable PYTHONPATH to the path of the module amd_instrument.py, located in: /lib/x64/python/

2. Import the module amd_instrument in your source file, which defines the domain/task APIs.

Like C++, there are two python-based APIs from Group1:

11.1.5.1. Group2

There are two Python based APIs for Group2. For more information, refer to Difference between Group1 and Group2 APIs.

These Pause/resume APIs can be called multiple times within the application.

Above code is self-explanatory with the provided comments. Functions f1(), f2(), … etc. to be declared and defined properly.

11.1.5.2. Unmatched API Calls

Profile Control APIs can cause an unmatched AMDTaskBegin() or AMDTaskEnd(), i.e. one of these two calls for which corresponding AMDTaskEnd() or AMDTaskBegin() (respectively) calls are not found within the same thread in the profiled run and generated data. There can be multiple unmatched AMDTaskBegin() or AMDTaskEnd() in a generated profile data. One of the possible reasons of Unmatched AMDTaskBegin() or AMDTaskEnd() API call can be usage of Pause/Resume APIs along with Domain/Task API incorrectly. Example: one item of the pair falls in paused state and the other in resume state. In those cases, we just ignore the unmatched API calls.

Refer to Unmatched Task for additional details.

11.2. Instrument APIs - Domain and Task

uProf provides time information at module level, process level, thread level and function level. All of them are programming language or system defined levels. Can we have some time information about some user defined code-block level, where code block can contain single line of instruction or multiple function calls and/or multiple lines of instructions. “Task” defines that code-block and is identified by a unique name. A domain like namespace, helps to organize tasks, by qualifying the task with domain names. In other words, domain is container of tasks.

11.2.1. Definition and Concepts

Domain: A domain defines a name and creates a namespace for the tasks. Hence each domain can contain one or more or no task(s).

• Within a domain, task names must be unique and task names can be the same within different domains.

• (domain, task) combination is to be unique within a thread and this tuple uniquely identifies a Task Item. Same (domain, task), that is, the same task item can appear multiple times within a thread, each such appearance is called a Task Instance. Time taken by all such Task - Items would be summed up in the report.

• Currently, nested domains are not allowed, that is, one domain cannot contain another domain.

Task: A task is sequence of synchronous/blocking code executed between the calls amdTaskBegin(…) and amdTaskEnd(…).

• Blocking code in the definition of the task means each instruction or function call within the task is first completed, before proceeding to the next instruction or function call. In case of thread launch, process launch or some other asynchronous call, time consumed by that thread or process or that asynchronous call is not included in the task, only the launch overhead(which contributes to the elapse time between the calls amdTaskBegin(...) and amdTaskEnd(...)) is included in the task time.

• Code executed may be different from the code listed between the calls amdTaskBegin(...) and amdTaskEnd(...). because at runtime control may go to different areas of the code as seen in the following example.

  

  Code listed between the calls amdTaskBegin(...) and amdTaskEnd(...) contains the sequence of instructions: Instruction 73 to Instruction 78.

  But actual instructions(code) executed within that task are the following and are in the following sequence: Instruction 73, Instruction 74, Instruction 1, Instruction 2, Instruction 3, Instruction 77, Instruction 78.

• A task cannot span over multiple threads, that is, it cannot start in one thread and end in another.

• amdTaskEnd(...) takes the domain as parameter, but not a task. It closes the last open task (that is, the task created and started by last encountered amdTaskBegin(...) in the runtime) from the same domain. Hence, within a domain the behavior is like a stack, where conceptually for each domain there is a separate stack in which amdTaskBegin(...) is pushed and whenever amdTaskEnd(…) with the same domain is encountered, top of the stack is popped and combined with the current amdTaskEnd(...) to define this task-instance.

• Nested tasks are allowed, but nested domains are not allowed.

• Overlapping tasks are allowed.

• Incomplete tasks, where amdTaskBegin(...) is defined and encountered at the runtime, but amdTaskEnd(...) is not defined or not encountered at the runtime, are ignored.

• If a task-item (defined by unique combination of (domain, task) tuple) is repeated in multiple threads of a process, then time consumed by all such task-instances (any instance of appearance of task-item in the code; there can be multiple appearance of same task-item even within a single thread or function) are summed up and reported in the hotspot and per process section (added with –detail option).

For C++ based multi-process application, when a task-item is present in multiple processes, Hottest Task section shows the sum of all times consumed by all task-instances from all the processes. But, with –detail option, for each task-items, per process sum for that task-item is reported in the Task Summary section which is per process.

This example shows how to mix Domain/Task APIs and Profile Control APIs.

Here we have four tasks: Task1, Task2, Task3 and Task4 and two domains: DomainABC and DomainABC1. Task1 is defined within paused state of application and hence will not be included in the profiled data.

Here, we assumed python functions f1() to f7() are defined. As we start profiling with –start-paused option, f1() and f2() will not be profiled. After the call amd_profile_resume() f3() and f4() will be profiled. Then the call amd_profile_pause() makes the f5() not to be profiled. Again, the second call of amd_profile_resume() makes the profiling on, hence f6() and f7() would be profiled.

11.3. Instrument APIs - Event

Event APIs are similar APIs as Task and events are listed under task sections in GUI/CLI, execpt for events user does not need to specify the domain name. All events are listed under the domain User, which is reserved for events and not to be used as a user defined domain for any task. One more difference with task is that the event start API call which is not matched with corresponding Event end API call, is considered as vlid event of 0.0 duration unlike task.

11.3.1. Definition and Concepts

Event: An event, in ITT context, is sequence of synchronous/blocking code executed between the calls amdEventStart(…) and amdEventEnd(…).

• Like Task, events are per thread, can be nested and overlapped, but unlike tasks, events have no user specified domain.

• Task and events can be mixed within a program.

• For a given event start API call, when there is no matching end call in the runtime of the code, this is considered as instantaneous event of 0.00 duration and listed.

• This behavior is different from Task for which unmatched begin calls are ignored. Event that is only created and ended, but not started (no matching start), are just ignored.

• Same events (like task) are aggregated within and across functions, threads and processes and also even when self-nesting is done.

• Nested events/tasks are allowed (event the tasks nesting events and event nesting tasks) are also allowed. Outer task/event would contains/include the time of inner task/event i.e. inclusive time.

• If the outer task/event launch a thread and inner task/event is there within that thread function, then outer task/event will not contain/include time of that inner task/event. This is true for such asynchronous calls. Only exclusive time is reported not the inclusive time.

11.3.2. Overall workflow with small example

Suppose we want to find top hottest overheads for initializations of n algorithms, where each algorithm has 1 or more initialization steps (some function calls, some computation statements etc.). Left side show original codes for algorithm1, algorithm2, …, algorithm n. In the middle, it shows codes after instrumentation and how tasks (user defined units of code) are generated, and finally right side shows the task-wise data displayed in CLI/GUI.

11.3.3. How to Run and Get Task/Event detail

You start with a source code, where some code snippets to be defined as tasks and then using profiling with proper configuration, you get defined task details (time information etc.) in the report.csv. Presently, it is supported in CLI mode profiling only and no GUI is supported.

1. Have your buildable source code to be profiled with Task/Event APIs. 2.Instrument the source code with task APIs.

1. Include the header AMDProfileController.h in the source file where you want to create a task. Path of this header is:

   <Installation Directory>/include/AMDProfileController.h
   

   Example

   ~/Foo/AMDuProf_Linux_x64_5.x.x/include/AMDProfileController.h
   

   Hence that folder must be in the include path, while building the instrumented application.

2. Create domain and get domain handle using amdDomainCreate(…).

3. Create string handle, using amdStringHandleCreate(…), which is used to name a task.

4. Using domain handle and string handle create a task and mark the start of the task – both are done with single call amdTaskBegin(…) and then your code (which is part of the task) comes.

5. Call amdTaskEnd(…) to mark the end of the task.

6. Can add more than one tasks in similar way.

7. Events can be added using Event APIs similarly.

3. For linking, the library user must include the library path of libAMDProfileController.so whose path is: <Installation Directory>/lib/x64/shared/libAMDProfileController.so.

4. Build the instrumented application.

5. Run the application under CLI profiler:

   $ AMDuProfCLI collect --config tbp -o <outputFolderPath> <applicationNameToBeProfiled>
   

6. Generate the report: (i)

   $ AMDuProfCLI report –i < outputFolderPath > or (ii) detailed report: AMDuProfCLI report –i < outputFolderPath > --detail
   

7. Summary report:

   $ AMDuProfCLI report –i < outputFolderPath >
   

8. Detailed report:

   $AMDuProfCLI report –i < outputFolderPath > --detail
   

Examples codes are given for different use cases in the following directories:

• C++: <Installation Directory>/Examples/ClassicDomainTaskAPI

• Python: <Installation Directory>/Examples/ClassicDomainTaskAPI/python

11.3.3.1. Description

Currently, for Domain and Task APIs C/C++ and Python APIs are supported for instrumenting codes in those respective programming languages. For Event APIs, only C++ support is available.

11.3.3.1.1. Using the Task APIs

C/C++ and Python APIs are described here for instrumenting codes.

11.3.3.2. C++ Task APIs

To use C++ APIs, include the header AMDProfileController.h. Path of this header is: <Installation Directory>/include/AMDProfileController.h. Example: ~/Foo/AMDuProf_Linux_x64_5.x.x/include/AMDProfileController.h. Hence, that folder must be in the include path, while building the instrumented application.

For linking, the library, include the library path of libAMDProfileController.so, whose path is: <Installation Directory>/lib/x64/shared/libAMDProfileController.so.

There are four C++ based APIs for supporting domain and task.

Example

void *execDomain = amdDomainCreate ("Main.ExecuteBenchmark");
void *mulStr = amdStringHandleCreate ("MultiplyMatrices");
// some activities, not within task
int matrixSize =1000;
initialize_matrices(matrixSize);

amdTaskBegin (execDomain, 0, 0, mulStr);
// some activities within task
multiply_matrices(1000);
printOutout();
amdTaskEnd (execDomain);

// some activities, not within task
CleanUp();

11.3.3.3. Python APIs

To use these Python APIs:

1. Set environment variable PYTHONPATH to the path of the module amd_instrument.py, located in: <uProf Install Directory>/lib/x64/python/.

2. Import the module amd_instrument, which defines the domain/task APIs.

3. There are two groups of APIs: Python APIs and C++ based APIs, for supporting domain and task. APIs from one group cannot be mixed with APIs for another group.

Python- group 1 contains 2 APIs.

Example

import amd_instrument as a
#... other code e.g. function calls and/or statements
a. amd_start_task("DomainABC::TaskPQR")

# ... blocking function calls and/or statements, considered within this task
# or non-blocking function calls and/or statements, not considered within tasks
a.amd_end_task(“DomainABC”)

Python- group 2 contains 3 APIs.

Example

import amd_instrument as a
#... other code e.g. function calls and/or statements
d = a.domain_create("DomainABC")
a.task_begin(d, "TaskPQR")

# ... blocking function calls and/or statements, considered within this task
# or non-blocking function calls and/or statements, not considered within tasks
a.task_end(d)

11.3.3.3.1. Using the Event APIs

C/C++ Event APIs are described here for instrumenting codes.

To use C++ APIs, include the header AMDProfileController.h. Path of this header is: <Installation Directory>/include/AMDProfileController.h. Example: ~/Foo/AMDuProf_Linux_x64_5.x.x/include/AMDProfileController.h. Hence, that folder must be in the include path, while building the instrumented application.

For linking, the library, include the library path of libAMDProfileController.so, whose path is: <Installation Directory>/lib/x64/shared/libAMDProfileController.so. There are three C++ based APIs for supporting Events.

Example

void *execEvent = amdEventCreate ("MyNewEvent");
// some activities, not within the event
int matrixSize =2048;
initialize_matrices(matrixSize);

amdEventStart (execEvent);
// some activities within events
LU_decompose_matrix(matrixSize);
printResults();
amdEventEnd (execEvent);

// some activities, not within task
CleanUp();

11.3.4. Compiling Instrumented Target Application

Complete the following procedure to compile a instrumented target application:

1. Include the header AMDProfileController.h in the source file where you want to create a task. The path of this header is:

   <Installation Directory>/include/AMDProfileController.h
   

   Example

   ~/Foo/AMDuProf_Linux_x64_5.x.x/include/AMDProfileController.h
   

   Hence that folder must be in the include path, while building the instrumented application.

2. For linking, the library user must include the library path of libAMDProfileController.so, whose path is: <Installation Directory>/lib/x64/shared/libAMDProfileController.so.

3. Build the instrumented application, based on the present compiler option(s) and commands.

11.3.5. Profiling Instrumented Target Application

Complete the following procedure to profile an instrumented target application:

1. Run the application AMDuProfCLI collect --config tbp -o <outputFolderPath> <applicationNameToBeProfiled>.

   The raw output is generated in the directory Session Directory>/instrument.

2. To generate:

   Summary report:

   AMDuProfCLI report –i < outputFolderPath >
   

   Detailed report:

   AMDuProfCLI report –i < outputFolderPath > --detail
   

11.3.6. Disabling Instrumentation APIs

In cases user need to have a quick way to disable the Instrumentation APIs from the code. Manually commenting each occurrence of them may be tedious. You can disable the Instrumentation APIs quickly using one of the following options:

1. Compile time disabling by using macro AMDUPROF_DISABLE_INSTRUMENT_API: Define the macro in a common header included by all the files which contains calls to Instrumentation APIs.

2. Runtime disabling by using the environment variable: Setting the environment variable AMDUPROF_INSTRUMENT_ENABLE to 0 leads to disabling the effect of the Instrumentaion APIs.

11.3.7. Example Steps to Attach Instrumented Process

1. Run an application in one terminal or as demon with environment variable set AMDUPROF_INSTRUMENT_ENABLE=1.

   Example

   $AMDUPROF_INSTRUMENT_ENABLE=1 python3 /TestProfileControlApi.py
   

2. Get the pid of the running application using command in some other terminal.

   Example

   $ps -u
   

3. Launch CLI with that process attach.

   Example

   $<path>/AMDuProfCLI --config hotspots --timer-interval 10 -o ./ -p <pidOfTheTargetProcess>
   

   You can use the -d option to set the duration for which profiling should be allowed.

4. Finally generate the report as usual and the generated report.csv will show top 10 (or as selected by provided option) hottest tasks. If multiple attachment of the same prcess (say long running process) is performed, then multiple session files would created. Each would display the corresponding data in its report.csv file.

11.3.8. Unmatched Task/Event

11.3.8.1. Definition

Unmatch in Task: An unmatched AMDTaskBegin() or AMDTaskEnd() is one of these two calls for which corresponding AMDTaskEnd() or AMDTaskBegin() (respectively) calls are not found in the generated profiled data. There can be multiple unmatched AMDTaskBegin() or AMDTaskEnd() in a generated profile data.

Note that, by definition, unmatched AMDTaskBegin() and AMDTaskEnd() means that no match for those are found from same domain and same thread.

Unmatch in Event: An unmatched amdEventStart() or amdEventEnd() is one of these two calls for which corresponding amdEventEnd() or amdEventStart() (respectively) calls are not found in the generated profiled data. There can be multiple unmatched amdEventStart() or amdEventEnd() in a generated profile data.

11.3.8.2. Reason for Unmatched Task/Event

The following are a few possible cases where we get unmatched AMDTaskBegin() or amdEventStart() or AMDTaskEnd() or amdEventEnd() in the generated data (that is, # AMDTaskBegin() or amdEventStart() is not same as # AMDTaskEnd() or amdEventEnd() entries in the data).

1. Case 1 - The usage of start-pause – one item of the pair was in paused state and other in resume state.

2. Case 2 - Multiple times attachment of same process - one item of the pair was in not attached state and other in attached state.

3. Case 3 - Coding error while instrumenting, forgetting to write balanced AMDTaskBegin() or amdEventStart() and AMDTaskEnd() or amdEventEnd() pair.

4. Case 4 - Runtime condition.

   Example: some unforeseen jump or exception handling made one of AMDTaskBegin()/amdEventStart() or AMDTaskEnd()/AMDTaskEnd() call unreached.

11.3.8.3. Handling the Unmatched Task

Any unmatched task is completely ignored, that is, not considered or listed in reported tasks.

When there is no matching end call in the runtime of the code, this is considered as instantaneous event of 0.00 duration and listed. This behavior is different from Task for which unmatched begin calls are ignored. Un-matched end call are always ignored both for events and tasks. Un-matched end call are always ignored for events and tasks.

11.3.9. Depth Within Domain

11.3.9.1. Definition

When tasks/event from same thread and same domain( anyway, all events are always from same domain viz. User) are nesting, the level of nesting is described by Depth Within Domain. Following pseudo code of small example illustrate the concept

Explanations

1. .... indicates user activities like function call or some code.

2. Here 2 domains are there. Domain1111 and Domain2222. Domain1111 contains TaskA and TaskC, while Domain2222 contains TaskB, TaskD and TaskE.

3. Since the nesting is per Domain, the Depth Within Domain for the above tasks are like:

   Table 11.9 Depth Within Domain#

   Task	Depth Within Domain	Enclosing Task within same Domain
   TaskA	0	Nothing
   TaskB	0	Nothing
   TaskC	1	TaskA
   TaskD	1	TaskB
   TaskE	2	TaskD

For events, no need to consider the domain, because all events are from same domain viz. User. Hence within the same thread, one event’s Depth Within Domain increases as nesting level increases.

11.3.10. Output

The report command generates a list of task hotspots in the Hotspot section of the <Session Directory>/report.csv. For example: AMDuProf-ClassicDomainTaskAPI-TBP_Sep-02-2024_16-50-28/report.csv.

The corresponding task section would look similar to this:

"10 HOTTEST TASKS (Sort Event - CPU_TIME)"
DOMAIN,TASK,TASK COUNT,ELAPSED TIME(seconds),"CPU_TIME" (seconds)
"Task0", "BASIC_TASK_MATRIX", 1, 0.0537,0.0500
"User", "Event18", 1, 0.0352,0.0400
"User", "Event14", 1, 0.0352,0.0400
"User", "Event4", 1, 0.0352,0.0400
"User", "Event10", 1, 0.0352,0.0400
"User", "Event0", 1, 0.0385,0.0400
"User", "Event8", 1, 0.0353,0.0400
"User", "Event16", 1, 0.0352,0.0300
"Task14", "BASIC_TASK_MATRIX", 1, 0.0274,0.0300
"Task8", "BASIC_TASK_MATRIX", 1, 0.0274,0.0300

With the --detail option, report generation (AMDuProfCLI report -i <Session Directory> –detail) tasks can be grouped by process (grouping by modules/threads are not supported now), and will appear in the per process section after Hotspot section as Task Summary.

TASK SUMMARY
DOMAIN,TASK,TASK COUNT,ELAPSED TIME(seconds),"CPU_TIME" (seconds)
"Task0","BASIC_TASK_MATRIX",1,0.0537,0.0500
"User","Event18",1,0.0352,0.0400
"User","Event14",1,0.0352,0.0400
"User","Event4",1,0.0352,0.0400
"User","Event10",1,0.0352,0.0400
"User","Event0",1,0.0385,0.0400
"User","Event8",1,0.0353,0.0400
"User","Event16",1,0.0352,0.0300
"Task14","BASIC_TASK_MATRIX",1,0.0274,0.0300
"User","Event12",1,0.0352,0.0300
"Task2","BASIC_TASK_MATRIX",1,0.0274,0.0300
"Task12","BASIC_TASK_MATRIX",1,0.0274,0.0300
"User","Event6",1,0.0352,0.0300
"User","Event2",1,0.0352,0.0300
"Task10","BASIC_TASK_MATRIX",1,0.0274,0.0300
"Task6","BASIC_TASK_MATRIX",1,0.0274,0.0300
"Task16","BASIC_TASK_MATRIX",1,0.0274,0.0300
"Task18","BASIC_TASK_MATRIX",1,0.0274,0.0200
"Task4","BASIC_TASK_MATRIX",1,0.0274,0.0200
"Task8","BASIC_TASK_MATRIX",1,0.0274,0.0000

Note that there are 4 constants columns call:

• DOMAIN - Domain name

• TASK - Task name

• TASK COUNT - Count of task instance i.e. number of time this task was encountered in runtime of the application, over all processes and threads

• ELAPSED TIME(seconds) - The wall time of the task (not to be confused with CPU TIME).

Remaining columns are based on collect command configuration and view.

11.3.10.1. GUI Task Hotspot Summary

The following figure shows static Task Hotspot Summary table where time or other column (used for sorting the data of the table) is shown in the Summary page.

11.3.11. Limitations

Here is a list of limitations:

• Currently, the Domain/Task/Event APIs are supported in Linux (not on Android, Windows, FreeBSD, Yocto). For Python, supports are for 3.10+.

• The Pause-resume option which is invoked with start-paused option, work with domain-task APIs, but limitation of each of the two set of APIs remains.

• group-by module Option is not supported with --detail option in the report generation command. Only thread and process (the default option (process)) are supported.

• In Python API amd_start_task(domain_task_name), domain or task name cannot contain the :: substring, as that is used as separator. No - validation of this string is there, to avoid performance overhead, hence giving incorrect string as input (example: missing :: or multiple ::) may lead to incorrect behavior.

• Event APIs are not supported in Python.

• In C++ API comma(,) cannot be used in the domain/task/event name. No - validation of this string is there, to avoid performance overhead, hence giving incorrect string as input may lead to incorrect behavior.

• Attach process option is supported with the current version 5.2, but the process to be attached must be started with the environment setting AMDUPROF_INSTRUMENT_ENABLE=1. Attaching same process multiple times, are supported.

• Blocking/Synchronous function calls and/or statements within task begin and task end are considered part of the current task and non-blocking/asynchronous function calls and/or statements within task begin and task end are not considered part of the current tasks. Hence, when a new process, thread, etc., is launched from the parent process, thread etc., the child’s consumption of time, etc., would not be part of the parent.

• Domain/Task/Event APIs all can be mixed in a single application.

11.4. OneAPI support in AMDuProf

AMDuProf enables profiling of applications instrumented with OneAPI, allowing developers to analyze performance metrics and execution timelines effectively.

11.4.1. Overview

OneAPI offers a unified programming model for heterogeneous computing environments and includes support for Instrumentation and Tracing Technology (ITT) APIs to enhance performance analysis.

• Domain-Task/Event ITT APIs allow developers to define logical tasks/events within application threads, providing fine-grained visibility into execution timelines.

• Collection Control APIs enable selective data capture, helping focus analysis on critical code regions.

These features integrate seamlessly with AMDuProf Profiler, allowing visualization of user-defined tasks and correlation with CPU time in profiling reports. This helps developers identify bottlenecks and optimize performance across heterogeneous workloads.

11.4.2. Supported APIs

The following APIs from the OneAPI are currently supported for profiling using uProf.

1. Domain/Task APIs

   __itt_domain* __itt_domain_create(const char* name);
   __itt_string_handle* __itt_string_handle_create(const char* name);
   void __itt_task_begin(const __itt_domain* domain, __itt_id taskid, __itt_id parentid, __itt_string_handle* name);
   void __itt_task_end(const __itt_domain* domain);
   

2. Event APIs

   __itt_event __itt_event_create(const char *name, int namelen);
   int __itt_event_start(__itt_event event);
   int __itt_event_end(__itt_event event);
   

3. Collection Control APIs

   void __itt_pause(void);
   void __itt_resume(void);
   

11.4.3. How to Run

To profile application tasks using OneAPI ITT APIs and visualize them in AMDuProf reports:

1. Prepare Your Source Code

   Ensure you have a buildable source code that will be profiled using supported OneAPI ITT APIs.

2. Instrument the Source Code

   Add ITT instrumentation to define tasks:

   1. Include the ITT header file.

      Add ittnotify.h in the source file where tasks will be created.

      Header path:

      <Installation Directory>/sdk/include/ittnotify.h
      

      Make sure this folder is in your include path during compilation.

      Example:

      /opt/intel/oneapi/vtune/2025.4/sdk/include/ittnotify.h
      

   2. Create a domain

      Use __itt_domain_create(...) to create a domain and obtain its handle.

   3. Create a string handle

      Use __itt_string_handle_create(...) to name the task.

   4. Define and start a task

      Call __itt_task_begin(...) with the domain and string handle, then execute the code for that task.

   5. End the task

      Call __itt_task_end(...) after the task code completes.

   6. You can define multiple tasks by repeating the above steps.

3. Link the ITT Library

   Include the path to libittnotify.a during linking:<Installation Directory>/sdk/lib64/libittnotify.a

4. Build the Instrumented Application

   Compile and link the application with the ITT instrumentation.

5. Set Environment Variable

   Point INTEL_LIBITTNOTIFY64 to AMD’s ITT implementation library:

   export INTEL_LIBITTNOTIFY64=<Installation Directory>/bin/libAMDInstrumentationDataCollector.so
   

6. Run the application under CLI profiler

   Collect profiling data:

   $ AMDuProfCLI collect --config tbp -o <outputFolderPath> <applicationNameToBeProfiled>
   

7. Generate the reports

   $ AMDuProfCLI report –i <outputFolderPath> or (ii) detailed report: AMDuProfCLI report –i <outputFolderPath> --detail
   

   1. Summary Report

      $ AMDuProfCLI report –i <outputFolderPath>
      

   2. Detailed Report

      $ AMDuProfCLI report –i <outputFolderPath> --detail
      

11.4.4. Compiling an Instrumented Target Application

Follow these steps to compile a OneAPI-instrumented application:

1. Include the ITT Header

   Add the header file ittnotify.h in the source file where you want to create tasks.

   Header path

   <Installation Directory>/sdk/include/ittnotify.h
   

   Example

   /opt/intel/oneapi/vtune/2025.4/sdk/include/ittnotify.h
   

   Ensure this folder is in your include path during compilation.

2. Link the ITT Library

   Include the path to libittnotify.a` during linking:

   <Installation Directory>/sdk/lib64/libittnotify.a
   

   Example

   /opt/intel/oneapi/vtune/2025.4/sdk/lib64/libittnotify.a
   

3. Build the Instrumented Application

   Compile and link the application using your existing compiler options and commands.

11.4.5. Profiling Instrumented Target Application

Follow these steps to profile an application instrumented with OneAPI ITT APIs:

1. Set the Environment Variable

   Point INTEL_LIBITTNOTIFY64 to AMD’s ITT implementation library:

   export INTEL_LIBITTNOTIFY64=<Installation Directory>/bin/libAMDInstrumentationDataCollector.so
   

2. Run the Application Under AMDuProf CLI

   Collect profiling data using the Time-Based Profiling (tbp) configuration:

   $ AMDuProfCLI collect --config tbp -o <outputFolderPath> <applicationNameToBeProfiled>
   

   The raw output is stored in <Session Directory>/instrument directory.

3. Generate Reports:

   1. Summary report:

      $ AMDuProfCLI report –i < outputFolderPath >
      

   2. Detailed report:

      $ AMDuProfCLI report –i < outputFolderPath > --detail
      

11.4.6. Example Steps to Attach Instrumented Process

1. Set the Environment Variable

   Point INTEL_LIBITTNOTIFY64 to AMD’s ITT implementation library:

   export INTEL_LIBITTNOTIFY64=<Installation Directory>/bin/libAMDInstrumentationDataCollector.so
   

2. Start the Application

   Run the application in one terminal (or as a daemon) with the environment variable AMDUPROF_INSTRUMENT_ENABLE set to 1:

   Example:

   $ AMDUPROF_INSTRUMENT_ENABLE=1 ./TestDomainTaskOneAPI
   

3. Get the process id

   In another terminal, find the PID of the running application:

   Example

   $ ps -u
   

4. Attach AMDuProf CLI

   Launch CLI with that process attach.

   Example

   $ <path>/AMDuProfCLI --config hotspots --timer-interval 10 -o ./ -p <pidOfTheTargetProcess>
   

   You can use the -d option to set the duration for which profiling should be allowed.

5. Generate the Report

   Run the report command as usual. The generated report`.csv` will include the top 10 (or as configured) hottest tasks.

11.4.7. Output

The report command generates a list of task hotspots in the Hotspot section of the <Session Directory>/report.csv.

For example: AMDuProf-ITT_OneAPI-TBP_Nov-05-2025_09-11-20/report.csv

The corresponding task section would look similar to this:

"10 HOTTEST TASKS (Sort Event - CPU_TIME)"
DOMAIN,TASK,TASK COUNT,ELAPSED TIME(seconds),"CPU_TIME" (seconds)
"DomainAAA", "Task0", 1, 9.5736,8.7910
"DomainBBB", "Task19", 1, 8.3636,8.3640
"DomainAAA", "Task18", 1, 8.2230,8.2240
"DomainBBB", "Task17", 1, 6.1693,6.1700
"DomainAAA", "Task16", 1, 4.1271,4.1280
"DomainBBB", "Task15", 1, 3.4609,3.4620
"DomainAAA", "Task14", 1, 2.9403,2.9420
"DomainBBB", "Task13", 1, 2.5704,2.5710
"DomainAAA", "Task12", 1, 2.3202,2.3220
"DomainBBB", "Task11", 1, 2.1727,2.1730

With the --detail option, report generation (AMDuProfCLI report -i <Session Directory> –detail) tasks are grouped by process/thread (grouping by modules is not supported), and appear in the per process/per thread section respectively after Hotspot section as Task Summary.

TASK SUMMARY
DOMAIN,TASK,TASK COUNT,ELAPSED TIME(seconds),"CPU_TIME" (seconds)
"DomainAAA","Task0",1,9.5736,8.7910
"DomainBBB","Task19",1,8.3636,8.3640
"DomainAAA","Task18",1,8.2230,8.2240
"DomainBBB","Task17",1,6.1693,6.1700
"DomainAAA","Task16",1,4.1271,4.1280
"DomainBBB","Task15",1,3.4609,3.4620
"DomainAAA","Task14",1,2.9403,2.9420
"DomainBBB","Task13",1,2.5704,2.5710
"DomainAAA","Task12",1,2.3202,2.3220
"DomainBBB","Task11",1,2.1727,2.1730
"DomainAAA","Task10",1,2.0951,2.0960
"DomainBBB","Task9",1,2.0675,2.0690
"DomainAAA","Task8",1,2.0634,2.0640
"DomainBBB","Task7",1,1.3972,1.3990
"DomainAAA","Task6",1,0.8767,0.8770
"DomainBBB","Task5",1,0.5070,0.5080
"DomainAAA","Task4",1,0.2568,0.2580
"DomainBBB","Task3",1,0.1093,0.1110
"DomainAAA","Task2",1,0.0317,0.0320
"DomainBBB","Task1",1,0.0039,0.0050

11.4.7.1. GUI Task Hotspot Summary

The following figure shows static Task Hotspot Summary table where time or other column (used for sorting the data of the table) is shown in the Summary page.

11.4.8. APIs Usage Example

1. Domain/Task APIs:

   /* Domain API usage example with classic_multiply_matrices() to simulate work. */
   
   void Test_DomainTask_API()
   {
       std::cout << "[START] Test_DomainTask_API\n";
   
       /* Create Odd and Even domains to distrubute tasks */
       __itt_domain* domainOdd = __itt_domain_create("BASIC_DOMAIN_ODD");
       __itt_domain* domainEven = __itt_domain_create("BASIC_DOMAIN_EVEN");
   
       /* Create domain & task/string handle for aggregation task */
       __itt_domain* domainAgg = __itt_domain_create("BASIC_DOMAIN_AGG");
       __itt_string_handle* taskAgg = __itt_string_handle_create("BASIC_TASK_MATRIX_AGG");
   
       /* First call of aggregation Task APIs */
       __itt_task_begin(domainAgg, __itt_null, __itt_null, taskAgg);
       classic_multiply_matrices(1);
       __itt_task_end(domainAgg);
   
       /* Logic to test Odd-Even association of tasks */
       for (int i = 0; i < 4; i++)
       {
           std::string task_name = "BASIC_TASK_MATRIX_" + std::to_string(i);
           __itt_string_handle* task = __itt_string_handle_create(task_name.c_str());
   
           if( i % 2 == 0)
               __itt_task_begin(domainEven, __itt_null, __itt_null, task);
           else
               __itt_task_begin(domainOdd, __itt_null, __itt_null, task);
   
           classic_multiply_matrices(i+1);
   
           if( i % 2 == 0)
               __itt_task_end(domainEven);
           else
               __itt_task_end(domainOdd);
       }
   
       /* Second call of aggregation Task APIs */
       __itt_task_begin(domainAgg, __itt_null, __itt_null, taskAgg);
       classic_multiply_matrices(2);
       __itt_task_end(domainAgg);
   
       std::cout << "[DONE] Test_DomainTask_API\n\n";
   }
   

   Output:

   GUI:

   

   CLI:

   "10 HOTTEST TASKS (Sort Event - CPU_TIME)"
   DOMAIN,TASK,TASK COUNT,ELAPSED TIME(seconds),"CPU_TIME" (seconds)
   "BASIC_DOMAIN_ODD", "BASIC_TASK_MATRIX_3", 1, 16.0178,16.0050
   "BASIC_DOMAIN_AGG", "BASIC_TASK_MATRIX_AGG", 2, 12.7786,12.0400
   "BASIC_DOMAIN_EVEN", "BASIC_TASK_MATRIX_2", 1, 12.0135,12.0140
   "BASIC_DOMAIN_ODD", "BASIC_TASK_MATRIX_1", 1, 8.0090,8.0100
   "BASIC_DOMAIN_EVEN", "BASIC_TASK_MATRIX_0", 1, 4.0046,4.0050
   

   Explanation:

   • The function classic_multiply_matrices() simulates approximately 4 seconds of work per repetition, with its parameter controlling the number of repetitions.

   • The task BASIC_TASK_MATRIX_AGG aggregates time across both start-end calls, and its TASK COUNT increases for each invocation.

   • The domains are correctly associated: BASIC_DOMAIN_ODD handles odd-numbered tasks (BASIC_TASK_MATRIX_1, BASIC_TASK_MATRIX_3), while BASIC_DOMAIN_EVEN handles even-numbered tasks (BASIC_TASK_MATRIX_0, BASIC_TASK_MATRIX_2).

2. Event APIs:

   /* Event API usage example with classic_multiply_matrices() to simulate work. */
   
   void Test_Event_API()
   {
       std::cout << "[START] Test_Event_API\n";
   
       /* Create two events */
       __itt_event event1 = __itt_event_create("BASIC_EVENT_1", sizeof("BASIC_EVENT_1") - 1);
       __itt_event event2 = __itt_event_create("BASIC_EVENT_2", sizeof("BASIC_EVENT_2") - 1);
   
       /* Create a event to test aggregation */
       __itt_event eventAgg = __itt_event_create("BASIC_EVENT_AGG", sizeof("BASIC_EVENT_AGG") - 1);
   
       /* First call of aggregation Event APIs */
       __itt_event_start(eventAgg);
       classic_multiply_matrices(1);
       __itt_event_end(eventAgg);
   
       __itt_event_start(event1);
       classic_multiply_matrices(1);
       __itt_event_end(event1);
   
       __itt_event_start(event2);
       classic_multiply_matrices(2);
       __itt_event_end(event2);
   
       /* Second call of aggregation Event APIs */
       __itt_event_start(eventAgg);
       classic_multiply_matrices(2);
       __itt_event_end(eventAgg);
   
       std::cout << "[DONE] Test_Event_API\n\n";
   }
   

   Output:

   GUI:

   

   CLI:

   "10 HOTTEST TASKS (Sort Event - CPU_TIME)"
   DOMAIN,TASK,TASK COUNT,ELAPSED TIME(seconds),"CPU_TIME" (seconds)
   "User", "BASIC_EVENT_AGG", 2, 12.6475,12.0140
   "User", "BASIC_EVENT_2", 1, 8.0188,8.0110
   "User", "BASIC_EVENT_1", 1, 4.0065,4.0060
   

   Explanation:

   • The function classic_multiply_matrices() simulates about 4 seconds of work per repetition. Its parameter directly controls the number of repetitions.

   • The event BASIC_EVENT_AGG combines time from both start–end calls, and its TASK COUNT reflects the total number of event invocations.

3. Collection Control APIs:

   /* Collection Control API usage example with classic_multiply_matrices() to simulate work. Profiling starts in paused state*/
   
   void Test_Collection_Control()
   {
       std::cout << "[START] Test_Collection_Control\n";
   
       classic_initialize_matrices_1();
   
       __itt_resume();
   
       classic_initialize_matrices_2();
       classic_initialize_matrices_3();
   
       __itt_pause();
   
       classic_initialize_matrices_4();
   
       std::cout << "[DONE] Test_Collection_Control\n\n";
   }
   

   Output:

   GUI:

   

   

   CLI:

   Profile Start Time:,"Wed Nov 12 09:39:30 2025"
   Profile End Time:,"Wed Nov 12 09:40:40 2025"
   Profile Duration:,"70.049 seconds"
   Pause Duration:,"21.582 seconds"
   ...
   "10 HOTTEST FUNCTIONS (Sort Event - CPU_TIME)"
   FUNCTION,"CPU_TIME" (seconds),Module
   "classic_initialize_matrices_3()",12.0280,"/home/Repo/Test/ITT_Test/ITT_Test_App"
   "classic_initialize_matrices_2()",8.0060,"/home/Repo/Test/ITT_Test/ITT_Test_App"
   

   Explanation:

   • The report now includes Pause Duration, indicating how long profiling was paused, along with Profile Duration, which covers the entire profiling session including pauses.

   • Only classic_multiply_matrices_2() & classic_multiply_matrices_3() are reflected in report as profiling is in resume state when these are called.

   • classic_multiply_matrices_1() & classic_multiply_matrices_4() are not reflected in report as profiling is in paused state when these are called.

11.4.9. Limitations

Here is a list of limitations:

• Currently, limited OneAPIs are supported and only Linux platform is supported.

• The Pause-resume option which is invoked with start-paused option, work with domain-task APIs, but limitation of each of the two set of APIs remains.

• Comma (,) cannot be used in domain/task/event name.

• Options group-by module is not supported with –detail option in the report generation command.

• Attach process option is supported with the current version 5.2, but the process to be attached must be started with the environment setting AMDUPROF_INSTRUMENT_ENABLE=1.

• System-wide support is not available with current version 5.2.

• Blocking or synchronous function calls and statements within __itt_task_begin and __itt_task_end are considered as part of the current task. In contrast, it does not consider non-blocking or asynchronous function calls and statements within the same boundaries as part of the current task. When a parent process or thread launches a new process or thread, UProf does not include the child’s time consumption in the parent’s task metrics.