Quick Start Guide

This Quick Start Guide explains how to configure an application to use Qualcomm® Snapdragon™ Heterogeneous Compute SDK (HetCompute) given the binary distribution. The installer package available from Qualcomm Developer Network contains precompiled dynamic libraries for Android (32-bit and 64-bit ARM). Install the distribution on your system following the installer prompts, and then see the appropriate section below on how to use it on your particular platform.

Additional information about this process is available in the SDK documentation.

Legal Disclaimer: Your use of this guide, including but not limited to the instructions, steps, and commands below, is subject to the Website Terms of Use and may contain references to third party or open source software that is not distributed by Qualcomm Technologies, Inc. or its affiliates. You are solely responsible for the installation, configuration, and use of any such third party or open source software and compliance with any applicable licenses. 

System Requirements

Windows 7 or later, Mac OS X 10.10 or later, or Ubuntu14.04 or later.

Devices

We currently support Android devices running Android 6.0 (Marshmallow) or later powered by the following Qualcomm® Snapdragon™ mobile platforms:

  • Snapdragon 425/430/435
  • Snapdragon 630/650/652/653/660
  • Snapdragon 808/810/820/821/835/845

Software

Android
The precompiled Heterogeneous SDK libraries can be easily integrated with an existing native Android application. The Heterogeneous SDK assumes the existence of a working Android NDK and SDK. We recommend using NDK r13c or later.

Verifying your installation

By default, the binary installer places the HetCompute library, headers, and samples in the following directory:

Linux & Mac

/opt/Qualcomm/SnapdragonHeterogeneousComputeSDK//

Windows

C:\Qualcomm\SnapdragonHeterogeneousComputeSDK\\

This is referred to as the HETCOMPUTE_DIR directory throughout. Substitute platform with either 32-bit (armeabi-v7a) or 64-bit (arm84-v8a) variants. If installed in a different location, that location becomes HETCOMPUTE_DIR.

Android 32-bit (armeabi-v7a)

  • CPU, GPU, and Hexagon DSP support: libhetCompute-1.0.0.so

Android 64-bit (arm64-v8a)

  • CPU, GPU, and Hexagon DSP support: libhetCompute-1.0.0.so

HetCompute assumes the existence of a working Android NDK and SDK. We recommend using NDK r13b or later.

Note: The Qualcomm® Hexagon™ SDK (available on Qualcomm Developer Network) is needed to provide support for the Hexagon DSP in the Qualcomm HetCompute library. The recommended version of the Hexagon SDK for use with HetCompute is 3.3.0 or later.

Before compiling the samples, specify the path to the root of OpenCL directory containing the headers and the library by initializing QSHETCOMPUTE_OPENCL_PATH in:

$HETCOMPUTE_DIR/samples/build/android/jni/Android.mk.

To verify the installation, perform the following using ndk-build:

cd $HETCOMPUTE_DIR/samples/build/android/jni
$ANDROID_NDK/ndk-build

# Create a directory on the device to push the executable $ANDROID_SDK/adb shell mkdir /data/local/tmp/hetcompute

# Push the executable to the device # Replace armeabi-v7a by arm64-v8a for 64 bit devices $ANDROID_SDK/adb push ../obj/local/armeabi-v7a/hetcompute_sample_helloworld /data/local/tmp/hetcompute

# Push the hetcompute dynamic library to the device.
# The 32-bit library should be pushed to /system/vendor/lib,
# while the 64-bit library should be pushed to /system/vendor/lib64
# Make sure to replace QSHETCOMPUTE_VERSION and Target
# Architecture with appropriate values in the below command.
$ANDROID_SDK/adb push $HETCOMPUTE_DIR/lib/$(TARGET_ARCH_ABI)/libhetCompute-$(QSHETCOMPUTE_VERSION).so / system/vendor/lib

$ANDROID_SDK/adb shell /data/local/tmp/hetcompute/hetcompute_sample_helloworld

The above ndk-build will build both the 32-bit and 64-bit variants of the samples.

Note that some of the HetCompute GPU samples require image files. The samples assume that the image files are under /mnt/sdcard on the device. Sample image files can be found in HETCOMPUTE_DIR/samples/src.

Integrating HetCompute with Android NDK Applications

The precompiled HetCompute libraries can be integrated with an existing native Android application. These libraries have been compiled with Google NDK r13b, using the clang toolchain and linked against the c++_static runtime. The default build for Android is android-21. Using the same NDK, compiler, and runtime C++ library is recommended.

You will need to make the following changes to your project files to use the HetCompute libraries.

First, edit your project’s jni/Application.mkfile to include the following entries:

# APP_STL defines the C++ runtime to use
APP_STL := c++_static

# For 64-bit android,
APP_ABI := arm64-v8a APP_ABI := armeabi-v7a
NDK_TOOLCHAIN_VERSION := clang

# set the APP_PLATFORM to match your platform version
APP_PLATFORM := android-21

Next, edit your project’s jni/Android.mk to define the location of the HetCompute libraries and headers and generate prebuilt shared library.

# Heterogeneous Compute SDK prebuilt
include $(CLEAR_VARS)

LOCAL_MODULE := qshetcompute
LOCAL_SRC_FILES := $(HETCOMPUTE_DIR)/$(TARGET_ARCH_ABI)/libhetCompute-$(QSHETCOMPUTE_VERSION).so
LOCAL_EXPORT_C_INCLUDES := $(HETCOMPUTE_DIR)/include

include $(PREBUILT_SHARED_LIBRARY)

If you want to disable exceptions for your applications, make the following changes in the Android.nk and Application.mk files.

# Add the following CFLAGS in Android.mk
LOCAL_CFLAGS := -DHETCOMPUTE_DISABLE_EXCEPTIONS

# Disable exceptions for the app in Application.mk
APP_CPPFLAGS += -fno-exceptions

Here is the sample Android.mk file that is used to build the shipped samples:

define hetcompute_add_sample
 include $(CLEAR_VARS)
 LOCAL_MODULE := hetcompute_sample_$1
 LOCAL_C_INCLUDES := $(QSHETCOMPUTE_CORE_INCLUDE_PATH) \
  $(QSHETCOMPUTE_OPENCL_INC_PATH) \
  $(QSHETCOMPUTE_DSP_STUB_PATH)

 LOCAL_SHARED_LIBRARIES := qshetcompute libhetcompute-hexagon-prebuilt libOpenCL-prebuilt
 LOCAL_CPPFLAGS := -pthread -std=c++11 -stdlib=libstdc++
 LOCAL_LDLIBS := -llog -lGLESv3 –lEGL
 LOCAL_CFLAGS := -DHAVE_CONFIG_H=1 -DHAVE_ANDROID_LOG_H=1 -DHETCOMPUTE_HAVE_RTTI=1
  -DHETCOMPUTE_HAVE_OPENCL=1 -DHETCOMPUTE_HAVE_GPU=1 -DHETCOMPUTE_HAVE_GLES=1
  -DHETCOMPUTE_HAVE_QTI_DSP=1 DHETCOMPUTE_THROW_ON_API_ASSERT=1
  -DHETCOMPUTE_LOG_FIRE_EVENT=1
 ifeq ($(TARGET_ARCH_ABI), arm64-v8a)
  LOCAL_LDFLAGS := -Wl,-allow-shlib-undefined
 endif

 LOCAL_SRC_FILES := $(QSHETCOMPUTE_SAMPLES_SRC_PATH)/$1.cc
 include $(BUILD_EXECUTABLE)
endef

To build your application, run:

$ANDROID_NDK/ndk-build HetCompute

The SDK supports Heterogeneous Compute with offloads on the GPU and DSP. GPU offload is supported using OpenCL and OpenGL kernels. The offload mechanism is either OpenCL 1.2 or later, or the native Qualcomm Technologies, Inc. GPU driver. The community has been collecting a list of Android devices that support OpenCL.

Using HetCompute with OpenCL as a GPU backend requires the OpenCL C++ header file cl.hpp, which needs to be patched. For details on how to patch cl.hpp see OpenCL C++ Support. In the Android.mk file, set LOCAL_C_INCLUDES to include the path to OpenCL headers. In the above Android.mk, this is referred by QSHETCOMPUTE_OPENCL_INC_PATH. libOpenCL-prebuit refers to the corresponding OpenCL library for the 32-bit or 64-bit variant.

To build an application with the Hexagon-supported library, set LOCAL_C_INCLUDES to include the DSP stub headers generated using the Hexagon SDK. This is referred by QSHETCOMPUTE_DSP_STUB_PATH in the sample’s Android.mk file.

Hexagon DSP Support

Using HetCompute with Hexagon DSP tasks requires a working installation of the Hexagon SDK. This section assumes the programmer is familiar with the Hexagon SDK. Also, HetCompute Hexagon DSP offloading requires a proper installation of OpenCL libraries.

Building the HetCompute DSP samples is a two-step process. First, you build the hetcompute_dsp stub and skel library with the Hexagon SDK, then compile and build the HetCompute DSP samples with the previously generated stub library. For ease of use, the installation distributes the stub & skel library used by the samples. These libraries can be found in $HETCOMPUTE_DIR/external/dsp/.

Both the skel and stub libraries should be pushed into the device before running HetCompute DSP samples. Please refer to Hexagon SDK to determine the location where the libraries need to be installed in the device.

Running the HetCompute DSP samples:

  • A README file is provided in $HETCOMPUTE_DIR/external/dsp/ that explains how to compile the DSP skel and stub libraries in case you want to add new functions in the stub and skel libraries. This step can be skipped if you want to use the precompiled DSP skel and stub libraries distributed in the HetCompute SDK package.
  • Push the libraries onto the device and run the DSP samples.$ANDROID_SDK/adb shell mkdir -p /data/local/tmp/hetcompute/
    cd $HETCOMPUTE_DIR
    $ANDROID_SDK/adb push lib/armeabi-v7a/libhetcompute-@QS_HETCOMPUTE_VERSION@.so /system/vendor/lib $ANDROID_SDK/adb push samples/build/android/libs/armeabi-v7a/hetcompute_sample_hexagon_is_prime /data/local /tmp/hetcompute

    $ANDROID_SDK/adb push external/dsp/lib/libhetcompute_dsp_skel.so /system/lib/rfsa/adsp $ANDROID_SDK/adb push external/dsp/lib/libhetcompute_dsp.so /system/vendor/lib

    $ANDROID_SDK/adb shell chmod 0755 /data/local/tmp/hetcompute/hetcompute_sample_hexagon_is_prime $ANDROID_SDK/adb shell /data/local/tmp/hetcompute/hetcompute_sample_hexagon_is_prime

    Note: If issues are encountered, verify that the calculator example contained within the Hexagon SDK works properly on your device and that your device properly supports DSP execution.

OpenCL C++ Support

Using HetCompute with OpenCL as the GPU backend requires the presence of the OpenCL C++ header file from Khronos (version must match to your OpenCL driver installation).

The header file should be installed in a subdirectory ${includedir}/OpenCL/ that is searched by the compiler (e.g., /usr/local/include). Alternatively, additional options would need to be passed as compilation flags (e.g., -I${includedir}).