Developer Guide for Intel® SDK for OpenCL™ Applications 2017
A newer version of this document is available. Customers should click here to go to the newest version.
Command Line Interface
The Intel® SDK for OpenCL™ Applications standalone version provides a command line interface. The command line interface is useful for:
- scripted commands
- software validation
- conducting a system that monitors software performance over time.
The command line interface provides a set of options that enables you to perform most of the tasks that are available through the GUI. You can use the command line interface to:
- Collect performance analysis data on an OpenCL application.
- Capture a kernel execution for an OpenCL application
- Execute a kernel from a captured session
- Collect performance analysis data for a kernel execution from a captured session
- Perform a deep analysis for a kernel from a captured session
- View kernel performance analysis results
Guidelines
Use the following guidelines for specifying the options:
Specify an option with its short name preceded by single dash (-). You can omit the space before the value.
The following examples run the myApp.exe with and override the output folder:
CodeBuilder -e myApp.exe -f CodeBuilder -emyApp.exe -f
Specify an option with its long name preceded by two dashes (--). You can separate the value with a space or the equal sign (=)
The following example performs the same operation as the previous examples, using long names:
CodeBuilder --executable myApp.exe --force
CodeBuilder --executable=myApp.exe --force
Collect performance analysis data on an OpenCL™ application
To run a performance analysis for OpenCL application and generate analysis reports use:
CodeBuilder.exe --executable <executable> [OPTIONS]
Or
CodeBuilder.exe -e <executable> [OPTIONS]
Where:
<executable> is the application executable to be analyzed.
[OPTIONS] are options defining the Code Analyzer behavior as described in the following table:
| Option short name | Option long name | Description |
|---|---|---|
| -a <arguments> | --arguments | Specifies the arguments of the analyzed application. Use double quotes (") to specify multiple arguments. |
| -f | --force | Deletes the existing output folder and generates a new output folder. |
| -m <format> | --format | Specifies the output file format. Valid options are html or csv. The default output file format is html. |
| -n <name> | --name | Specifies the name of the subdirectory to store analysis results in. The default subdirectory is <APPLICATION_NAME>_out where APPLICATION_NAME is the name of the application to be executed is specified as <EXECUTABLE> argument. |
| -o <outDir> | --outdir | Specifies the output directory to store analysis results in. By default the analysis results are stored in the current directory. |
| -w <workDir> | --workdir | Specifies the working directory for the profiled application. By default the working directory is the path to the application binary. |
| --disable-deep | Disables sessions generation for kernel
NOTE:
You won't be able to run deep kernel analysis. Useful when interested in host analysis only, will speed up the analysis process.
|
|
| --disable-counters | Disables hardware counters collection for executed kernels. | |
| --autoview | Opens the report automatically when analysis is done. |
Generated Reports
When you run the CodeBuilder.exe, a new subdirectory is created.
By default the subdirectory is created in the current directory. The subdirectory name uses this format: < text="application_name" ?> application_name>_Out
where <application_name> is the name of the executable as specified in the <EXECUTABLE> argument.
To specify a different subdirectory name user the -n option.
To specify a different location for the subdirectory, use the -o option.
The following types of files are generated in the subdirectory:
For --format=html the following files are generated:
application_name.html
Representing the profiling data in rich UI components. Run the following command to view the results in the CodeBuilder viewer:
CodeBuilder --view <html_file | directory>
application_name_Files
subdirectory - containing all the required files for the report.
For --format=csv the following files are generated:
apiCallsSummary.csv
Contains the following data for each OpenCL API occurred during the application run: API name, total duration (Μs), average duration (Ms), minimum duration (Ms) and maximum duration (Ms).
apiCallsDetails.csv
Contains the following data for each OpenCL API call occurred during the application run: API name, API arguments, error code, return value, duration (Ms), start tick and end tick.
kernelLaunchDetails.csv
Contains the following data for each kernel execution occurred during the application run: kernel name, global work size, local work size, type, duration (Ms), queued time (Ms),start time (Ms), end time (Ms), latency (Ms), return value, command queue, context, global work offset.
kernelLaunchSummary.csv
Contains the following data for each kernel that was executed during the application run: kernel name, global Work size, local work size, count, total duration (Ms), average duration (Ms), minimum duration and maximum Duration (Ms).
memoryCommandsDetails.csv
Contains the following data for each OpenCL memory API call occurred during the application run: command name, return value, duration (Ms), latency (Ms), size (byte), queued time (Ms), start time (Ms), end Time (Ms), context and objects.
memoryCommandsSummary.csv
Contains the following data for each OpenCL memory API occurred during the application run: command name, count, error count, total duration (Ms), average duration (Ms), minimum duration and maximum Duration (Ms).
Capture a kernel execution session from an OpenCL application
To generate a session from an existing application that runs OpenCL kernel APIs, use:
CodeBuilder.exe capture-session --executable <EXECUTABLE> [OPTIONS]
Or
CodeBuilder.exe capture-session -e <EXECUTABLE> [OPTIONS]
Where:
<EXCUTABLE> is the application executable to be analyzed.
[OPTIONS] are options defining the Code Builder behavior as described in the following table:
| Option short name | Option long name | Description |
|---|---|---|
| -a <arguments> | --arguments | Specifies the arguments of the analyzed application. Use double quotes (") to specify multiple arguments. |
| -f | --force | Deletes the existing output folder and generates a new output folder. |
| -m <format> | --format | Specifies the output file format. Valid options are html or csv. The default output file format is html. |
| -n <name> | --name | Specifies the name of the subdirectory to store analysis results in. The default subdirectory is <APPLICATION_NAME>_out where APPLICATION_NAME is the name of the application to be executed is specified as <EXECUTABLE> argument. |
| -o <outDir> | --outdir | Specifies the output directory to store analysis results in. By default the analysis results are stored in the current directory. |
| -w <workDir> | --workdir | Specifies the working directory for the profiled application. By default the working directory is the path to the application binary. |
| --capture-conf-limit | Sets a limit on the number of kernel executions to be captured for aconfiguration. Use "all" to capture all executions for each configuration. The default is 1. |
For more information, see Generate a Session
Generated Files
Capturing a kernel execution session from an OpenCL application generates the following files:
- <application_name>Session0.cbsession - contains the captured session data. Can be used for executing a kernel from the captured session.
- Session data files - build artifacts, buffers and images of the executed kernels and other files that are required for running the session.
Execute a kernel from a captured session
To execute a kernel from a captured session, use:
CodeBuilder.exe run-session --cs-session <SESSION_FILE> --cb-kernel <KERNEL_NAME> --cb-configuration <CONFIGURATION> [OPTIONS]
Or
CodeBuilder.exe run-session -s <SESSION_FILE> -k <KERNEL_NAME> --c <CONFIGURATION> [OPTIONS]
Examples
To get a list of all kernel names and configuration names captured by a session, use:
CodeBuilder.exe run-session --cs-session <SESSION_FILE> Or
CodeBuilder.exe run-session -s <SESSION_FILE>
To get a list of all configuration names of a specific kernel captured by a session, use: CodeBuilder.exe run-session --cs-session <SESSION_FILE> --cb-kernel<KERNEL_NAME> Or CodeBuilder.exe run-session -s <SESSION_FILE> --k <KERNEL_NAME>
Where:
<SESSION_FILE> is the session file (.cbsession) captured by capture-session command.
<KERNEL_NAME> is the name of the kernel to be executed.
<CONFIGURATION> is the configuration file for the kernel execution.
[OPTIONS] are options defining the Code Builder behavior as described in the following table:
| Option short name | Option long name | Description |
|---|---|---|
| -a <arguments> | --arguments | Specifies the arguments of the analyzed application. Use double quotes (") to specify multiple arguments. |
| -f | --force | Deletes the existing output folder and generates a new output folder. |
| -n <name> | --name | Specifies the name of the subdirectory to store captured session files. |
| -o <outDir> | --outdir | Specifies the output directory to store analysis results in. By default the analysis results are stored in the current directory. |
| -w <workDir> | --workdir | Specifies the working directory for the profiled application. By default the working directory is the path to the application binary. |
| --capture-conf-limit | Sets a limit on the number of kernel executions to be captured for aconfiguration. Use "all" to capture all executions for each configuration. The default is 1. |
For more information, see Generate a Session
Generated Files
Running a captured session generates the following files:
<application_name>_out.html - representing the kernel execution output in a rich UI components. Run the following command to view the results in the CodeBuilder viewer:
CodeBuilder --view <html_file | directory>
- <application_name>_Files - subdirectory containing all the required files for the report.
Collect performance analysis data for a kernel execution from a captured session
To perform a basic performance analysis for a kernel execution from a captured session, use:
CodeBuilder.exe analyze-session --cs-session <SESSION_FILE> --cb-kernel <KERNEL_NAME> --cb-configuration <CONFIGURATION> [OPTIONS]
Or
CodeBuilder.exe analyze-session -s <SESSION_FILE> -k <KERNEL_NAME> --c <CONFIGURATION> [OPTIONS]
Where:
<SESSION_FILE> is the session file (.cbsession) captured by capture-session command.
<KERNEL_NAME> is the name of the kernel to be executed.
<CONFIGURATION> is the configuration file for the kernel execution.
[OPTIONS] are options defining the Code Builder behavior as described in the following table:
| Option short name | Option long name | Description |
|---|---|---|
-n <name> |
--name | Specifies the name of the subdirectory to store captured session files. |
| -o <outDir> | --outdir | Specifies the output directory to store analysis results in. By default the analysis results are stored in the current directory. |
| -f | --force | Deletes the existing output folder and generates a new output folder. |
| --autoview | Opens the report automatically when analysis is done. |
Generated Files
Analyzing a captured session generates the following files:
<application_name>_out.html - representing the profiling data in rich UI components. Run the following command to view the results in the CodeBuilder viewer:
CodeBuilder --view <html_file | directory>- <application_name>_Files - subdirectory containing all the required files for the report.
Perform a deep analysis for a kernel from a captured session
To perform a deep performance analysis for a kernel execution from a captured session, use:
CodeBuilder.exe analyze-kernel --cs-session <SESSION_FILE> --cb-kernel <KERNEL_NAME> --cb-configuration <CONFIGURATION> [OPTIONS]
Or
CodeBuilder.exe analyze-session -s <SESSION_FILE> -k <KERNEL_NAME> --c <CONFIGURATION> [OPTIONS]
Where:
<SESSION_FILE> is the session file (.cbsession) captured by capture-session command.
<KERNEL_NAME> is the name of the kernel to be executed.
<CONFIGURATION> is the configuration file for the kernel execution.
[OPTIONS] are options defining the Code Builder behavior as described in the following table:
| Option short name | Option long name | Description |
|---|---|---|
-n <name> |
--name | Specifies the name of the subdirectory to store captured session files. |
| -o <outDir> | --outdir | Specifies the output directory to store analysis results in. By default the analysis results are stored in the current directory. |
| -f | --force | Deletes the existing output folder and generates a new output folder. |
| --autoview | Opens the report automatically when analysis is done. | |
| --latency | Perform a latency analysis. | |
| --occupancy | Perform an occupancy analysis. |
Generated Files
Deep analysis on a captured session generates the following files:
<application_name>_out.html - representing the profiling data in rich UI components. Run the following command to view the results in the CodeBuilder viewer:
CodeBuilder --view <html_file | directory>- <application_name>_Files - subdirectory containing all the required files for the report.
View kernel performance analysis results
To view the generated reports in the standalone viewer, use:
CodeBuilder.exe --view <FILE|DIRECTORY>
Where:
<FILE|DIRECTORY> is the html report file or its containing directory.
This usage is a great workaround for HTML browsers that blocks local files access, it also makes deep analysis execution much simpler.
Examples
To perform an application analysis on myApp.exe and export html reports to C:\document\ directory, use one of the following:
CodeBuilder analyze --executable myApp.exe --output c:\document CodeBuilder analyze -e myApp.exe -o c:\document CodeBuilder analyze -emyApp.exe -oc:\document
To perform an application analysis on myTargetApp.exe and export html reports to the current directory, use:
CodeBuilder analyze -e myTargetApp.exe
To perform an application analysis on myTargetApp.exe and export csv reports to the current directory, use:
CodeBuilder analyze -e myTargetApp.exe -m csv
To capture a session from myTargetApp.exe and create a session directory in C:\document\ directory, use:
CodeBuilder capture-session -e myTargetApp.exe -o c:\document
To get a list of kernels and configuration files from a captured session, use:
CodeBuilder run-session -s c:\document\myApp_Out\MyApp\MyApp0\mySession.cbsession
The command prints the following output:
+ Session "IntelGodRaysSession0" | + Kernel "MyKernel" | | + Configuration "Workgroup_5632_64_conf_0"To execute a kernel from a captured session, use:
CodeBuilder run-session -s c:\document\myApp_Out\MyApp\MyApp0\mySession.cbsession -k MyKernel -c Workgroup_5632_64_conf_0