Quick Start Guide

This Quick Start Guide explains how to configure an application to use Symphony SDK given the binary distribution. The installer package contains precompiled dynamic libraries for Android (32-bit and 64-bit ARM), GNU/Linux (ARM and x86_64), Microsoft Windows, and Mac OS X. 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.

The following dynamic versions of the Symphony SDK Library are provided:

  • Full hetero
    • Platforms: Android 32-bit (arm-linux-androideabi) and Android 64-bit (aarch64-linux-android)
    • Three versions of the library: a cpu-only library, a library with cpu+gpu support, and a library with cpu+gpu+hexagon dsp support
  • CPU and GPU
    • Platforms: Linux x86 (x86_64-linux-gnu), Mac OS X (x86_64-apple-darwin)
    • Two versions of the library: a cpu-only library, and a library with cpu+gpu support
  • CPU only
    • Platforms: Linux ARM (arm-linux-gnueabihf), Linux ARM 64-bit (aarch64-linux-gnu), Microsoft Windows 32-bit (i386-windows), Microsoft Windows 64-bit (x86_64-windows)
    • A cpu-only version of the library

The selection of a specific library is peformed by using the SYMPHONY_LIB_TYPE variable. To select the CPU-only version of the Symphony SDK library, SYMPHONY_LIB_TYPE is set to release-cpu. On Android, to select the the cpu+gpu+hexagon dsp version, SYMPHONY_LIB_TYPE is set to release. The default is to select the cpu+gpu version, which occurs when SYMPHONY_LIB_TYPE is set to release-gpu.

System Requirements

Hardware

  • Windows PC, Mac OS X, and Linux

Devices

  • We currently support Android devices powered by Qualcomm® Snapdragon™ processors. You can also work on PC, Mac OS X, and Linux systems.

Software

  • Windows: Symphony SDK requires Microsoft Visual Studio 2015. We make extensive use of C++11 features, and the set we require is supported properly in this release. Symphony SDK is supported only for 32-bit and 64-bit Intel platforms on Microsoft Visual Studio. Symphony SDK does not currently offer GPU support on Windows.
  • Mac OS X and Linux: Symphony SDK requires GCC 4.8 or later which provides the necessary C++11 functionality. The recommended Symphony SDK development environment is an Ubuntu Linux 14.04 LTS or later system. If starting with a basic Ubuntu system, the necessary compilers and build tools may not be installed by default (the versions for 14.04LTS are not). In this case, install the required versions manually using apt-get. On Linux, OpenCL is generally well-supported, OpenCL header files (including OpenCL C++ headers) are packaged by various Linux distributions (e.g., opencl-headers on Ubuntu/Debian). On Mac OSX the OpenCL framework is pre-installed. However, the OpenCL C++ headers must be installed (no patching necessary). Currently, clang is the only compiler included with Xcode that supports C++11 and can compile Symphony SDK. When using -std=c++11, use -stdlib=libc++ to include the proper library support. Additionally, install a recent version of gcc using the appropriate package management system: fink, homebrew, or macports, all of which provide g++-4.8 or later.
  • Android: The precompiled Symphony SDK libraries can be easily integrated with an existing native Android application. These libraries have been compiled with the Google NDK r10c that includes GCC 4.8. Using the same NDK and compiler is recommended. GCC 4.8.x or later is necessary to link against the precompiled library. The Qualcomm® Hexagon™ SDK is needed to enable support for cpu+gpu+hexagon dsp in the Symphony SDK library. The recommended version of the Qualcomm Hexagon SDK for use with Symphony SDK is 1.2.2. Please note that support for Hexagon SDK is not available on 64-bit Android at this time.

Launch Setup and Configuration

  1. Verifying Installation:
    To verify the installation, perform the following:

    On Android, using ndk-build:

    cd $SYMPHONY_DIR/examples

    $ANDROID_NDK/ndk-build SYMPHONY_LIB_TYPE=release-cpu

    # Create a directory on the device to push the executable

    $ANDROID_SDK/adb shell mkdir /data/local/tmp/symphony

    # Push the executable to the device
    # Replace armeabi-v7a by arm64-v8a for 64 bit devices

    $ANDROID_SDK/adb push obj/local/armeabi-v7a/symphony_examples_helloworld /data/local/tmp/symphony

    # Push the symphony 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

    $ANDROID_SDK/adb push ../lib/libsymphony-cpu-1.0.0.so /system/vendor/lib
    $ANDROID_SDK/adb shell /data/local/tmp/symphony/symphony_examples_helloworld

    On Android, using cmake:

    cd $SYMPHONY_DIR/examples

    cmake . -DSYMPHONY_LIB_TYPE=release-cpu
    -DCMAKE_TOOLCHAIN_FILE=../lib/CMake/symphony/android.toolchain.cmake
    make
    $ANDROID_SDK/adb shell mkdir /data/local/tmp/symphony
    $ANDROID_SDK/adb push symphony_examples_helloworld /data/local/tmp/symphony
    $ANDROID_SDK/adb push ../lib/libsymphony-cpu-1.0.0.so /system/vendor/lib
    $ANDROID_SDK/adb shell /data/local/tmp/symphony/symphony_examples_helloworld

    Note: To build for 64-bit Android, the 64-bit toolchain must be passed to the cmake command using the following option:

    -DANDRODID_TOOLCHAIN_NAME=aarch64-linux-android-4.9

    Additionally, to build for Android Lollipop, the Android API level should be set to 21 by passing the following option to the cmake command:

    -DANDROID_API_LEVEL=21

    On Linux or Mac OS X:
    cd $SYMPHONY_DIR/examples

    cmake . -DSYMPHONY_LIB_TYPE=release-cpu
    make
    ./symphony_examples_helloworld

    On Microsoft Windows (at CMD prompt):
    cd $SYMPHONY_DIR\examples

    cmake . -DSYMPHONY_LIB_TYPE=release-cpu
    cmake --build . --config Release
    .\symphony_examples_helloworld

    In the above snippets, the cpu+gpu version or cpu+gpu+hexagon dsp version of the Symphony SDK library can be selected by substitutingrelease-cpu with release-gpu orrelease, respectively, for the value of SYMPHONY_LIB_TYPE.

  2. Integrating Symphony SDK with Android NDK Applications:

    The precompiled Symphony SDK libraries can be easily integrated with an existing native Android application. These libraries have been compiled with the Google NDK r10c that includes GCC 4.8. Using the same NDK and compiler is recommended. GCC 4.8.x or later is necessary to link against the precompiled library.

    You will need to make the following changes to your project files to use the Symphony SDK libraries. First, edit your project's jni/Application.mk file to include the following entries:

    APP_STL := gnustl_static
    # For 64-bit android, APP_ABI := arm64-v8a
    APP_ABI := armeabi-v7a
    NDK_TOOLCHAIN_VERSION := 4.8
    # set the APP_PLATFORM to match your platform version.
    APP_PLATFORM := android-18

    When using Symphony SDK, statically linking against the libstdc++ library by using gnustl_static is recommended. Additionally, when using the 64-bit Symphony SDK library, APP_ABI needs to be set to arm64-v8a, and NDK_TOOLCHAIN should be set to 4.9. Additionally, for devices running Android L, APP_PLATFORM should be set to android-21.

    Next, edit your project's jni/Android.mk to define the location of the Symphony SDK libraries and headers, SYMPHONY_DIR. For Android, SYMPHONY_DIR may be an absolute path, or a path relative to your current project. Include the SYMPHONY.mk at that location file as follows:

    SYMPHONY_VERSION := 1.0.0
    SYMPHONY_LIB_TYPE := <release-gpu|release-cpu|release>
    SYMPHONY_DIR := $(HOME)/Qualcomm/Symphony/$(SYMPHONY_VERSION)/arm-linux-androideabi
    include ${SYMPHONY_DIR}/lib/SYMPHONY.mk

    The default configuration will select the multicore release version. Other configurations may be selected for the library by setting the SYMPHONY_LIB_TYPE variable to one of: release-cpu, release-gpu or release (which contains support for the CPU, GPU, and Hexagon DSP).

    Finally, edit your project's Android.mk file for each build target to include the following:

    LOCAL_ARM_MODE := arm
    ifeq ($(TARGET_ARCH_ABI), armeabi-v7a)
    LOCAL_ARM_NEON := true

    endif
    LOCAL_CPP_FEATURES := exceptions
    LOCAL_SHARED_LIBRARIES := libsymphony

    Note that the $(SYMPHONY_CXX_FLAGS) are automatically picked by the Android ndk build system from SYMPHONY.mk, so it need not be appended explicitly.

    To build your application using ndk-build run:

    $ANDROID_NDK/ndk-build

    Symphony SDK also provides support for heterogeneous compute, with offload on the GPU and DSP. GPU offload is supported using OpenCL kernels. The offload mechanism is either OpenCL 1.2 or later, or the native Qualcomm GPU driver. The community has been collecting a list of Android devices that support OpenCL. In addition, a Qualcomm-based platform that provides OpenCL support is the DragonBoard APQ8074.

    Using Symphony SDK with OpenCL as GPU backend requires the OpenCL C++ header file cl.hpp, which needs to be patched. In the Android.mk file, set the ANDROID_CL_DIR variable, before including SYMPHONY.mk, as follows:

    ANDROID_CL_DIR := <path to directory containing include (with patched cl.hpp)
    and lib folder containing libOpenCL.so>

    ANDROID_CL_DIR/include will be used as include path. ANDROID_CL_DIR/lib will be used as lib path.

    Optionally, ANDROID_CL_DIR can also be passed as a command line parameter to ndk-build as follows:

    ndk-build ANDROID_CL_DIR=<path>

    To build an application with the Hexagon-enabled library, the HEXAGON_SDK variable must be set to the root directory of the Hexagon SDK. This is the directory that contains the inc and lib directories. Again, the use of Hexagon SDK version 1.2.2 is recommended. This can also be passed as a command-line parameter as follows:

    ndk-build ANDROID_CL_DIR=<path> HEXAGON_SDK=<path>

    GNU/Linux and Mac OS X

    Symphony SDK can also be compiled on most GNU/Linux and Mac OS X systems. This is useful if using a portable application that can be tested on a standard PC before running it on an Android device.

    Symphony SDK requires GCC 4.8 or later which provides the necessary C++11 functionality. The recommended Symphony SDK development environment is an Ubuntu Linux 14.04 LTS or later system. If starting with a basic Ubuntu system, the necessary compilers and build tools may not be installed by default (the versions for 14.04LTS are not). In this case, install the required versions manually using apt-get.

    Symphony SDK heterogeneous execution (e.g., GPU offload) is supported on *nix systems through OpenCL.

    For details on how to patch cl.hpp see the OpenCL C++ Support chapter in the Symphony SDK documentation.

    Microsoft Windows

    Symphony SDK binaries have been compiled for Microsoft Visual Studio.

    1. This is useful to develop for Microsoft Windows, and in particular, developing a portable concurrent application that can be easily targeted to Android.

    Requirements
    Symphony SDK requires Microsoft Visual Studio 2015. We make extensive use of C++11 features, and the set we require is supported properly in this release. Symphony SDK is supported only for 32-bit and 64-bit Intel platforms on Microsoft Visual Studio. Symphony SDK does not currently offer GPU support on Windows.

    Adding Symphony SDK to your Microsoft Windows application
    Precompiled libraries have been provided for both Win32 and x64 architectures. Your project will need some changes to support compiling with the Symphony SDK headers and libraries. If you are using cmake, please see the instructions for Linux and Mac OS X. Otherwise, make sure that your solution is compatible with Microsoft Visual Studio 2015, and right-click on your project and go to the properties editor. Make the following changes in the "Configuration Properties" section: C/C++ - General - Additional Include Directives

    Add the following include paths to the end of your current include list, and replace %(SYMPHONY_DIR) to point to the location of your Symphony SDK distribution relative to the current project file:

    ;%(SYMPHONY_DIR)\include

    C/C++ - Code Generation - Runtime Library
    Change to use "Multi-threaded (/MT)" or "Multithreaded-specific DLL (/MD)". Libraries need to be consistent across the solution

    Linker - Input - Additional Dependencies
    Add the following libraries to the end of your current library list:

    ;%(SYMPHONY_DIR)\lib\libsymphony.lib

    Substitute %(SYMPHONY_DIR) to point to the location of your Symphony SDK distribution, relative to the current project file, including the <platform> folders. Substitute platform with one of: i386-windows or x86_64-windows.

    Configure build types
    You need to make sure the above changes are made for all configurations, and for both Win32 and Win64 builds.

    Debugging output
    Debug versions of the libraries are not provided.

    Building
    At this point, you should be able to build the entire solution, and your executable is now enabled for use with Symphony SDK.

  3. Using Symphony SDK in your application with CMake:

    The binary distribution includes a cmake configuration option that allows you to configure your application to use Symphony SDK using the find_package command. Edit your application's CMakeLists.txt to include the following fragment:

    find_package(SYMPHONY PATHS ${SYMPHONY_DIR}/lib/CMake/symphony NO_DEFAULT_PATH)
    if(NOT SYMPHONY_FOUND)
    message(FATAL_ERROR "Symphony not found")
    endif()
    include_directories(${SYMPHONY_INCLUDE_DIRS})
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${SYMPHONY_CXX_FLAGS}")
    add_executable(your_application ${your_application_SRCS})
    target_link_libraries(your_application ${SYMPHONY_LIBRARIES})

    Then configure your application (for Linux and Mac OS X) using:

    cmake . -DSYMPHONY_DIR=${HOME}/Qualcomm/Symphony/1.0.0/<platform>
    -DSYMPHONY_LIB_TYPE=<release-cpu|release-gpu>

    To configure your application for Android, use the CMAKE_TOOLCHAIN_FILE option as follows:

    cmake . -DSYMPHONY_DIR=${HOME}/Qualcomm/Symphony/1.0.0/<platform>
    -DSYMPHONY_LIB_TYPE=<release-cpu|release-gpu> -DCMAKE_TOOLCHAIN_FILE=<path to android.toolchain.cmake>

    If your application is using a different build system, refer to the definitions in$SYMPHONY_DIR/lib/CMake/lib/CMake/symphony/SYMPHONYConfig.cmake, and:

    • Add to your C++ compiler flags the flags listed in SYMPHONY_CXX_FLAGS_<lib_type>.
    • Add to your C++ include files the directories listed in SYMPHONY_INCLUDE_DIRS_<lib_type>.
    • Add to your libraries flags, the libraries listed in SYMPHONY_LIBRARIES_<lib_type>.

    Hexagon enabled Library usage with CMake
    If using the Hexagon-enabled Symphony SDK library for Android, the required libraries can be included by adding the following snippet to the CMakelists.txt:

    if(NOT HEXAGON_SDK)
    message(FATAL_ERROR "Please specify path to HEXAGON SDK")
    endif()
    include_directories (${HEXAGON_SDK}/inc/stddef ${HEXAGON_SDK}/lib/common/rpcmem)
    link_directories (${HEXAGON_SDK}/lib/common/remote/android_Release)
    add_executable(your_application ${your_application_SRCS})
    target_link_libraries(symphony_examples_${__example} ${SYMPHONY_LIBRARIES}
    ${HEXAGON_SDK}/lib/common/rpcmem/android_Debug/ship/rpcmem.lib)

    The application can then be configured using the following cmake command:

    cmake . -DSYMPHONY_DIR=${HOME}/Qualcomm/SYMPHONY/1.0.0/<platform>
    -DCMAKE_TOOLCHAIN_FILE=<path to android.toolchain.cmake> -DSYMPHONY_LIB_TYPE=release
    -DHEXAGON_SDK=<path_to_hexagon_sdk>

Known Limitations

Certain features like support for OpenCL, OpenGL ES Compute, Hexagon DSP are dependent on the platform support. So please check with the product specifications before targeting those features.