CodeXL User Guide1.
Go to the location of the GPU Profiler
binaries.
The GPU Profiler binaries are located in either the x86 or x64 (x86_64
on Linux) subdirectory under the CodeXL installation directory. Alternatively,
you can include the location of the Profiler binaries into the system's path
environment variable.
2. Run the Profiler using the following instructions.
Usage: CodeXLGpuProfiler <options> InputApplication [InputApplication's command line arguments]
Note: When profiling JOCL (Java OpenCL) application the full path to the java VM must be provided. E.g CodeXLGpuProfiler <options> /usr/bin/java –jar <jar_file>
Note: On some Linux systems which have an older version of
the libstdc++ shared object, you may get an error when trying to profile an
application from the command line. The error will say “Failed to generate
profile result”. If you encounter this error, please try using the CodeXLGpuProfilerRun
shell script to profile. This shell script will first set up the
LD_LIBRARY_PATH environment variable to allow the profiler to find the correct
version of the libstdc++ shared object. The command-line syntax for the CodeXLGpuProfilerRun
shell script is identical to the syntax used for CodeXLGpuProfiler.
General options:
|
-d [ --startdisabled ] |
Start the application with profiling disabled. This is useful for applications that call amdtStopProfiling and amdtResumeProfiling from the AMDTActivityLogger library. |
|
-e [ --envvar ] arg |
Environment variable that should be defined when running the profiled application. Argument should be in the format NAME=VALUE. |
|
-E [ --envvarfile ] arg |
Path to a file containing a list of environment variables that should be defined when running the profiled application. The file should contain one line for each variable in the format NAME=VALUE. |
|
-f [ --fullenv ] |
The environment variables specified with the envvar switch represent the full environment block. If not specified, then the environment variables represent additions or changes to the system environment block. |
|
-l [ --list ] |
Print the list of valid counter names. |
|
-N [ --sessionname ] arg |
Name of the generated session. If not specified, the name is the parent directory of the OutputFile. |
|
-o [ --outputfile ] arg |
Path to OutputFile. If not provided, the default is Session1.csv in an "CodeXL" directory under the current user's Documents directory; when performing an API trace, the default is apitrace.atp in the same location. For Linux, the default location is the current user’s home directory. |
|
-v [ --version ] |
Print the CodeXLGpuProfiler version number. |
|
-w [ --workingdirectory ] arg |
Set the working directory. If not provided, the default is the app binary's path. |
|
-h [ --help ] |
Show a help message. |
Profile mode options:
|
-t [ --apitrace ] |
Trace OpenCL™ application and generate CPU and GPU time stamps and detailed API call traces. |
|
-p [ --perfcounter ] |
Get the performance counters for each OpenCL™or DirectCompute kernel dispatched by the application. |
|
-A [ --hsatrace] |
Trace HSA application and generate CPU and GPU time stamps and detailed API call traces. (Linux only) |
|
-C [ --hsapmc] |
Get the performance counters for each HSA kernel dispatched by the application. |
|
-O [ --occupancy ] |
Generate kernel occupancy information file (.occupancy). |
|
-P [ --occupancydisplay ] arg |
Path to configuration file to use to generate an occupancy display file. Specify the occupancy display file that is to be generated with --outputfile. See below for information about the configuration file format. |
|
-T [ --tracesummary ] |
Generate summary page from an input .atp file. |
Application Trace mode options (for --apitrace and --hsatrace):
|
-F [ --apifilterfile ] |
Path to the API filter file which contains a list of OpenCL™ APIs to be filtered out when performing an API trace. See below for information about the API filter file format. |
|
-i [ --interval ] arg (=100) |
Timeout interval. Ignored when not performing an API trace and using timeout mode. |
|
-m [ --timeout ] |
Flush Trace data periodically, default timeout interval is 100 milliseconds (can be changed with -i option). Ignored when not performing an API trace. (Windows only, this is the default mode for Linux.) |
|
-M [ --maxapicalls ] (=1000000) |
Maximum number of API calls. |
|
-n [ --nocollapse ] |
Do not collapse consecutive identical clGetEventInfo calls into a single call in the trace output. Ignored when not performing an API trace. |
|
-r [ --ret ] |
Always include the OpenCL™ API return code in API trace, even if client application does not query it. Ignored when not performing an API trace. |
|
-y [ --sym ] |
Generate symbol information file (.st) for API trace, if available. Ignored when not performing an API trace. |
Performance Counter mode options (for --perfcounter and --hsapmc):
|
-c [ --counterfile ] arg |
Path to the counter file to enable selected counters (case-sensitive). If not provided, all counters are used. Ignored when performing an API trace. See below for information about the counter file format. |
|
-g [ --singlepass ] |
Only allow a single pass when collecting performance counters. Any counters that cannot fit into a single pass will be ignored. If specified, the GPUTime will not be collected, as a separate pass is required to query the GPUTime (OpenCL™or DirectCompute only, this is the default for HSA). |
|
-G [ --nogputime ] |
Skip collection of GPUTime when profiling a kernel (GPUTime requires a separate pass) (OpenCL™or DirectCompute only, this is the default for HSA). |
|
-k [ --kerneloutput ] arg |
Output the specified kernel file (OpenCL™or DirectCompute only). Valid argument values are: il: output kernel IL files isa: output kernel ISA files cl: output kernel CL files hsail: output kernel HSAIL files asm: output DirectCompute shader ASM files all: output all files |
|
-K [ --kernellistfile ] arg |
Path to the kernel list file which contains a case-sensitive list of kernels to profile. If not provided, all kernels will be profiled. See below for information about the kernel list file format. |
|
-s [ --outputseparator ] arg |
Character used to separate fields in the OutputFile. Ignored when performing an API trace. |
|
-x [ --maxkernels] arg (=100000) |
Maximum number of kernels to profile. |
Trace Summary mode options (for --tracesummary):
|
-a [ --atpfile ] arg |
Path to the .atp file from which to generate summary pages. Optional when performing an API trace. Required if -T is specified when not performing an API trace. The handle of the kernel. |
|
-R [ --apirulesfile ] arg |
Path to OpenCL™ API analyzer configuration file. If not specified, all rules are enabled. Ignored when –tracesummary is not specified. See below for information about the configuration file format. |
Examples
· An example to collect OpenCL™ or DirectCompute performance counters:
CodeXLGpuProfiler -o "/path/to/output.csv" -p -w "/path/to/app/working/directory" "/path/to/app.exe" --device gpu
· An example to collect an OpenCL™ API trace:
CodeXLGpuProfiler -o "/path/to/output.atp" -t -w "/path/to/app/working/directory" "/path/to/app.exe" --device gpu
· An example to collect HSA performance counters:
CodeXLGpuProfiler -o "/path/to/output.csv" -C -w "/path/to/app/working/directory" "/path/to/app.exe"
· An example to collect an HSA API trace:
CodeXLGpuProfiler -o "/path/to/output.atp" -A -w "/path/to/app/working/directory" "/path/to/app.exe"
· An example to collect an OpenCL™ API trace with summary pages:
CodeXLGpuProfiler -o "/path/to/output.atp" -t -T -w "/path/to/app/working/directory" "/path/to/app.exe" --device gpu
· An example to generate summary pages from an .atp file:
CodeXLGpuProfiler -a "/path/to/output.atp" -T
· An example to generate an occupancy display page:
CodeXLGpuProfiler -P "/path/to/occupancy/params/file.txt" -o "path/to/output.html"
After you have used the command line to profile an application., you can view the results within CodeXL using the Import Session command in the CodeXL Explorer .
The format of the configuration files passed to the --counterfile, --apirulesfile, --apifilterfile, --envvarfile and --occupancydisplay options can be found in the Description of Configuration Files topic.