Command Line Interface

Developer Guide for Intel® SDK for OpenCL™ Applications 2017

Download PDF

ID 773042

Date 10/22/2018

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-62C89A50-2E2F-4995-9EDF-B9AE2BDA7DCA

View Details

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]

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]

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]

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]

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]

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

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Guide for Intel® SDK for OpenCL™ Applications 2017

Command Line Interface

Guidelines

Collect performance analysis data on an OpenCL™ application

Capture a kernel execution session from 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