Developer Guide for Intel® SDK for

OpenCL™ Applications
Developer Guide for Intel® SDK for OpenCL™ Applications

Contents
Chapter 1: Intel® SDK for OpenCL™ Applications Developer Guide
Introducing the Intel® SDK for OpenCL™ Applications ...................................... 3
What's New in This Release.........................................................................4
Which Version of the Intel® SDK for OpenCL™ Applications Should I Use? ........... 5
Intel® FPGA Emulation Platform for OpenCL™ Getting Started Guide .................. 5
Building with Intel® SDK for OpenCL™ Applications - Offline Compiler
Command-Line Interface ........................................................................8
CPU Kernel Debugging Issues...................................................................... 9
Getting Help and Support ...........................................................................9
Notices and Disclaimers............................................................................ 10

2
 Intel® SDK for OpenCL™ Applications Developer Guide 1

Intel® SDK for OpenCL™

Applications Developer Guide 1
Version: 2020 Gold Update 1

Intel SDK for OpenCL Applications (also known as OpenCL Tools) is a software development tool that enables
development of OpenCL applications via well-known integrated development environments, targeting Intel®
architecture processors with Intel® Processor Graphics.
OpenCL Tools is available as a bundled component of Intel® System Studio, Intel® Media Server Studio, and
Intel® FPGA SDK for OpenCL™.
The tool supports local (host-based) and remote (target-based) development on the following platforms and
devices:
Operating System Host/Target Available as part of Available as part of Available as part of
Intel System Intel Media Server Intel FPGA SDK for
Studio Studio OpenCL
Microsoft Windows* Host Yes No Yes
Target Yes No Yes
Linux* Host Yes Yes Yes
Target Yes Yes Yes

Introducing the Intel® SDK for OpenCL™ Applications

OpenCL™ (Open Computing Language) standard provides a uniform programming environment for
software developers to write portable general-purpose parallel code for high-performance computing servers,
client computer systems, and other computing systems. OpenCL is developed by multiple companies through
the Khronos* OpenCL committee, and Intel is a key contributor to the OpenCL standard since its inception.
You can acquire the Intel SDK for OpenCL Applications as a part of Intel® System Studio and Intel® Media
Server Studio suites or as a part of Intel® FPGA SDK for OpenCL™ software technology.
Supported features:
Feature Microsoft Visual Studio* Eclipse* Development Stage
OpenCL™ 1.2 support Yes Yes Create and Build
OpenCL™ 2.0 support with Yes Yes
5th - 9th generation Intel®
Core™ processors
Kernel development - -
framework (discontinued in
2019 Update 4)
OpenCL Project wizard Yes
Syntax highlighting Yes Yes
Code auto-completion Yes Yes
Offline compilation Yes Yes
SPIR* 1.2 generation and - -
consumption (deprecated
in favor of SPIRV in 2019
Update 4)
SPIR* V generation and Yes Yes
consumption
API-level debugging - Debug
(discontinued in 2020
Update 1)

3
 1 Developer Guide for Intel® SDK for OpenCL™ Applications

Feature Microsoft Visual Studio* Eclipse* Development Stage

Image and memory view -
(discontinued in 2020
Update 1)
API call tracing -
(discontinued in 2020
Gold)
Step-by-step debugging for Yes
CPU kernels
Step-by-step debugging for -
GPU kernels (discontinued
in 2020 Update 1)
API calls and memory - Analyze
command analysis
(discontinued in 2020
Gold)

What's New in This Release

NOTE If your workflows require features discontinued in this release, you may still download legacy
versions from the download page.

2020 Gold Update 1

• Updated OpenCL™ API Headers and OpenCL ICD Loader.
• Removed assembly code generation for GPU functionality. If you need this functionality, use the OpenCL
Offline Compiler.
• Removed Intel® Debugger for Heterogeneous Compute (GPU kernel debugger). If you need this
functionality, use the initial 2020 release, available on the download page.
• Removed Intel® CPU Runtime for OpenCL Applications 18.1 from the Windows* installer. You can install it
manually from /OpenCL/runtime/cpu/opencl_runtime.msi.Note: Disable your graphic card before
installation to avoid installation issues.
• Removed support for Ubuntu* 16.04.
• Intel SDK for OpenCL Applications 2020 Update 1 includes bug fixes and security updates. All users should
update to the latest version.

2020 Gold
• Added support for Microsoft Visual Studio* 2019.
• Added support for the CentOS-8* platform
• Added support for generating an optimized ELF binary file from a SPIR-V file to the Offline Compiler
command-line interface
• Removal of SPIR* functionality (use SPIR-V* instead)
• Removal of Intel® Code Builder for OpenCL™ functionality
• Removal of Kernel Development Framework functionality (you can configure Intel® VTune™ Profiler to see
OpenCL API calls)
• Removal of OpenCL API Debugger functionality (you can use the Intercept Layer for OpenCL™ Applications
for debugging)
For more information, including system requirements, known issues, and installation notes, refer to the
Release Notes.

4
 Intel® SDK for OpenCL™ Applications Developer Guide 1

Which Version of the Intel® SDK for OpenCL™ Applications

Should I Use?
The Intel® System Studio is designed to improve system device application performance on Intel® platforms
using, in particular, OpenCL software technology. Intel SDK for OpenCL Applications is included to Intel
System Studio packages for the Linux* and Windows* OS.
The Intel® Media Server Studio is designed to support enterprise media developers with media capabilities
and OpenCL software technology. The Intel Media Server Studio supports Linux OS on Intel® Xeon® processor
E3 family and Core™ i7 processors.
Intel® FPGA SDK for OpenCL allows you to build and analyze OpenCL applications targeting Intel® FPGA.
For the full list of features, refer to the Intel SDK for OpenCL Applications Release Notes.
See the following tables to identify the version that best fits your needs:
Operating System Host/Target Intel SDK for Intel SDK for Intel SDK for
OpenCL OpenCL OpenCL
Applications as Applications as Applications as
part of Intel part of Intel Media part of Intel FPGA
System Studio Server Studio SDK for OpenCL
Windows* Host Yes - Yes
Target Yes - Yes
Linux* Host Yes Yes Yes
Target Yes Yes Yes

Devices Intel SDK for OpenCL Intel SDK for OpenCL Intel SDK for OpenCL
Applications as part of Applications as part of Applications as part of
Intel System Studio Intel Media Server Intel FPGA SDK for
Studio OpenCL
Intel® Graphics (GPU) Yes Yes -
Intel® Processors (CPU) Yes Yes -
Intel FPGA - - Yes

IDE integration Host OS Intel SDK for Intel SDK for Intel SDK for
OpenCL OpenCL OpenCL
Applications as Applications as Applications as
part of Intel part of Intel Media part of Intel FPGA
System Studio Server Studio SDK for OpenCL
Microsoft Visual Windows Yes - Yes
Studio*
Eclipse* Windows No - No
Linux No No No

Intel® FPGA Emulation Platform for OpenCL™ Getting

Started Guide
This guide provides quick steps to install the technical preview of Intel® FPGA Emulation Platform for
OpenCL™, compile and run OpenCL kernels on the Emulator.

About the Intel® FPGA Emulation Platform for OpenCL™

Intel® FPGA Emulation Platform for OpenCL™ technical preview includes the runtime and compiler, which runs
on Intel® Core™ and Intel® Xeon® processors. It is capable of compiling and running programs written with
Intel® OpenCL™ FPGA extensions (for example, with the FPGA 'channels' extension).
The emulator aims to provide:

5
 1 Developer Guide for Intel® SDK for OpenCL™ Applications

• rapid compilation time (seconds)

• source code portability between emulator and FPGA
• reasonable performance (average benchmarks run at 5x-10x slowdown in comparison with FPGA
hardware)
This version of the emulator is a technical preview, and it does not provide full functional equivalence with an
FPGA device. It is provided for evaluation purposes only without any warranties.

System Requirements
Refer to theIntel® oneAPI DPC++ Compiler and Intel® oneAPI DPC++ Library System Requirements.

NOTE The runtime cannot create more than four threads per logical core (physical cores with Intel®
HT Technology). For example, if application executes 32 kernels simultaneously it will require at least 8
logical cores (8 physical cores or 4 physical cores with HT option enabled).

Installing Intel® FPGA Emulation Platform for OpenCL™ Technical Preview

To configure environment of current session for using OpenCL™ standalone binaries do the following steps:
1. Unpack provided binaries to any working directory
2. Create new .icd file with following content as shown below:

echo /path/to/binaries/libintelocl_emu.so >> /etc/OpenCL/vendors/

intel_fpga_fast_emu.icd
3. Set INSTALLDIR variable in setupvars.sh script to the path where binaries have been unpacked.

If installation succeeded the following OpenCL™ platform will be available:

Platform [#1] :
Profile : FULL_PROFILE
Version : OpenCL 2.0 LINUX
Name : Intel(R) FPGA Emulation Platform for OpenCL(TM) (preview)
Vendor : Intel(R) Corporation
Devices : 1
Device [#1] :
Type : accelerator
Profile : FULL_PROFILE
Version : OpenCL 2.0 (Build 5)
Name : Intel(R) FPGA Emulation Device (preview)
Vendor : Intel(R) Corporation
C version : OpenCL C 2.0
Driver version : 1.2.0.5

Getting Started with Intel® FPGA Emulation Platform for OpenCL™ Technical Preview
The emulator provides a separate OpenCL™ platform with one OpenCL™ CPU device. It supports Intel® FPGA
OpenCL™ extensions.

6
 Intel® SDK for OpenCL™ Applications Developer Guide 1
OpenCL programs written for FPGA device can be compiled and executed on this device, using standard
OpenCL API (including clCreateProgramWithBinary(), see the Offline Compilation section).

There are sets of environment variable affecting emulator execution.

• The set of emulator specific libraries:
• OCL_FPGA_EMU - should be set to enable FPGA style of channels. This environment variable is
mandatory to use FPGA specific extensions.
• OCL_TBB_NUM_WORKERS ([1..]) - maximum number of threads which can be used by TBB.
• VOLCANO_CPU_ARCH (core-avx2, skx) - can be set to force SIMD instruction set used for OpenCL
kernel compilation where skx corresponds to AVX-512 support
• VOLCANO_CLANG_OPTIONS - internal environment variable allowing to force some options to OpenCL
compiler. For example:
•
-fopenmp -fintel-openmp -fopenmp-tbb - enables OpenMP* support
•
-ffast-math - forces fast math built-ins
•
-DINTEL_OCL_FPGA_CPU_EMU - adds corresponding define to the OpenCL kernel
• VOLCANO_LLVM_OPTIONS (-vector-library=SVML) - Internal option that allows force usage of short
vector math library. Must be set if OpenMP support is enabled.
• OpenCL related environment variables:
• CL_CONFIG_USE_VECTORIZER (True, False) - NDRange vectorizer control. Does not affect OpenMP
pragma vectorization of single work-item kernels. Should be set to False to speedup kernel
compilation time.
• CL_CONFIG_CPU_FORCE_LOCAL_MEM_SIZE (e.g 256KB) - amount of available OpenCL local memory.
• OpenMP environment variables (see OpenMP documentation for details):
• KMP_AFFINITY - affinity settings for OpenMP threads. For example, "norespect,physical,20"
• OMP_NUM_THREADS ([1..]) - Number of available OpenMP threads
Optimization guide using OpenMP is available in the directory with binaries (Optimization_guide.pdf).

Offline Compilation
The Emulator supports OpenCL™ kernels compilation into binaries (similar to .aocx files used for FPGA
device), which can be used in clCreateProgramWithBinary().

Use Intel® SDK for OpenCL™ Applications - offline compiler ('ioc64' tool) to compile kernel binaries for the
emulator from OpenCL C source code. This tool is distributed as part of Intel® Code Builder for OpenCL™ API:
> ioc64 -bo='-cl-std=CL2.0' -device-fpga_fast_emu -input=source.cl -
ir=kernel_binary.elf
Name for the output file is arbitrary, and it can have .aocx extension to let a host program use the same
names for both FPGA device and the emulator.
Kernel binaries produced by the 'ioc' tool are not compatible with binaries compiled for FPGA device and vice
versa.

Execution
Set of environment variables mentioned in the Getting Started section can affect the emulator behavior.
Bash script (setupvars.sh) distributed with binaries can be used to simplify the environment setting. Please
uncomment/modify value for required variable in the script and run the command below:
> . /path/to/binaries/setupvars.sh
After that all application running in current console will use environment variables set in the script.

7
 1 Developer Guide for Intel® SDK for OpenCL™ Applications

Building with Intel® SDK for OpenCL™ Applications - Offline

Compiler Command-Line Interface
The Intel® SDK for OpenCL™ Applications provides an offline compiler command-line interface. The tool
supports Intel® processors and Intel® Graphics, and provides full offline OpenCL language compilation, which
includes:
• Creating executable Intermediate Representation (IR) from source code
• Creating compiled object from source code
• Creating executable IR or library from object IR and libraries
The command-line tool is located in $(INTELOCLSDKROOT)\bin\ under the x86 or x64 folder, depending on
OS.
To use the offline compiler command-line interface:
1. Start the command-line.
2. Type ioc64 to run the 64-bit version
3. Type the run parameters in the following sequence:
ioc<version> -cmd=<command> -<argument> -<options>
The offline compiler supports the following commands:
Command Description
-cmd=build Creates executable IR from source code. Default
command

in case nothing is specified.

-cmd=compile Creates compiled object IR from source code.

-cmd=link Creates executable IR or library from object IR and

libraries.

The offline compiler supports the following arguments:

Argument Description
-input=<input_file_path> Builds OpenCL code from the input_file_path file.

Use the -input argument with the build and compile

commands.
-binary=<"binary_files"> Links comma-separated binary files. Use with the link
command.
-version Shows the tool version.

-help Shows help menu, containing the list of available

commands,

arguments, and options.

The offline compiler supports the following options:

Option Use Description
-device=<device_type> Selects target device type:
• cpu - Intel CPU device, which is Default
• gpu - Intel Graphics device

-targetos=<os> Set target operating system if it is different from current.

The command is supported only in 32-bit version of the

tool.
-simd=<instruction_set_arch> Selects target instruction set architecture. Available
on CPU device only. The following instruction set
architectures are available:

8
 Intel® SDK for OpenCL™ Applications Developer Guide 1
• sse42 - Streaming SIMD Extensions 4.2
• avx - Intel Advanced Vector Extensions (Intel
AVX)
• avx2 - Intel Advanced Vector Extensions 2 (Intel
AVX2)

-output[=<output_file_path>] Writes build log into the output_file_path. When this

option is specified,

the build log does not appear in the command-line.

-llvm[=<file_path>] Generates LLVM code.

-ir[=<file_path>] Generates intermediate representation binary.

-spirv32[=<file_path>] Generates a 32-bit SPIR-V binary.

-spirv64[=<file_path>] Generates a 64-bit SPIR-V binary.

-txt-spirv32[=<file_path>] Generates 32-bit SPIR-V code.

-txt-spirv64[=<file_path>] Generates 64-bit SPIR-V code.

-bo[="<build_options>"] Adds comma-separated build options.

CPU Kernel Debugging Issues

Symptom: kernel debugging issues
Solution: generate log file to find the cause
1. Set the following environment variables:

INTEL_OCL_DBG_LOG=1 INTEL_OCL_DBG_LOG_FILE=c:\temp\debugger.txt
2. Restart the Microsoft Visual Studio* IDE.
3. Continue debugging.
Using these environment variables, you generate a log file. Use it to determine the root cause of the issue.
You can submit the generated log through our support channels.

See Also
Intel® SDK for OpenCL™ Applications support site

Getting Help and Support

To get support, visit the product support forum at https://software.intel.com/en-us/forums/opencl or use
Online Service Center.
For information on Intel® SDK for OpenCL™ Applications requirements, known issues and limitations, refer to
the Intel® SDK for OpenCL™ Applications Release Notes at https://software.intel.com/en-us/articles/intel-sdk-
for-opencl-applications-release-notes.

9
 1 Developer Guide for Intel® SDK for OpenCL™ Applications

Notices and Disclaimers

No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this
document. Intel technologies' features and benefits depend on system configuration and may require enabled
hardware, software or service activation. Performance varies depending on system configuration. No product
or component can be absolutely secure. Check with your system manufacturer or retailer or learn more at
www.intel.com.
Intel disclaims all express and implied warranties, including without limitation, the implied warranties of
merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from
course of performance, course of dealing, or usage in trade.
This document contains information on products, services and/or processes in development. All information
provided here is subject to change without notice. Contact your Intel representative to obtain the latest
forecast, schedule, specifications and roadmaps.
The products and services described may contain defects or errors known as errata which may cause
deviations from published specifications. Current characterized errata are available on request.
Copies of documents which have an order number and are referenced in this document may be obtained by
calling 1-800-548-4725 or by visiting www.intel.com/design/literature.htm.
Intel, the Intel logo, Intel Core, Iris, Itanium, Pentium, Ultrabook, VTune, and Xeon are trademarks of Intel
Corporation in the U.S. and other countries.
This document contains information on products in the design phase of development.
* Other names and brands may be claimed as the property of others.
OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission from Khronos.
Microsoft product screen shot(s) reprinted with permission from Microsoft Corporation.
© Intel Corporation. All rights reserved.

10