CPU Profile Control APIs - CPU Profile Control APIs - 57368

Profile control APIs are APIs which can be called from C/C++ or python application being profiled, to pause and resume the profiling at runtime (not the run of the application itself).

It is recommended 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. Blocking Pause/Resume APIs are not supported on the Windows platform.
2. Select the Profile Target page and click Next.
3. Click Advanced Options.
4. 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.

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.

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/Bar/AMDuProf_Linux_x64_5.0.775/include/AMDProfileController.h, hence that include folder ~/Foo/Bar/AMDuProf_Linux_x64_5.0.775/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

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

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

Static Library

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

• Windows

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

• Linux

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

C/C++ API Descriptions

Group1

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

Group2

There are two C/C++ based APIs for Group2. (Refer to the "Difference between Group1 and Group2 APIs" section of this topic)

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:

There are 2 python-based APIs from Group2 (refer to the "Difference between Group1 and Group2 APIs" section above).

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

Figure 1. Example Code1 - C++

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

Figure 2. Example Code2 - C++

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.

Figure 3. Example Code2 - Python

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.

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.