Command Line Interface

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:

Guidelines

Use the following guidelines for specifying the options:

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: <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:

 

For --format=csv the following files are generated:

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:

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

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:

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:

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:

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