Developer Guide for Intel® SDK for OpenCL™ Applications
The Intel® SDK for OpenCL™ Applications standalone version provides a command line interface. The command line interface is useful for:
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:
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 --forceTo 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. |
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: <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:
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>
subdirectory - containing all the required files for the report.
For --format=csv the following files are generated:
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).
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.
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.
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).
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.
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).
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
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]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
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
CodeBuilder --view <html_file | directory>
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. |
CodeBuilder --view <html_file | directory>
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. |
CodeBuilder --view <html_file | directory>
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.
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