Skip to content

Hexagon SDK examples

Each example illustrates one or more SDK features as summarized in the List of examples section.

All examples are designed to run on both the simulator and target.

Setup

Follow the setup instructions before running any example. Remember to always run the setup_sdk_env script to set up the SDK local environment.

Walkthrough scripts

Most example projects come with a walkthrough python script that automates the following steps:

  • Sign the device so that libraries can be loaded on it.
  • Build the executable that runs on the application processor.
  • Build the Hexagon DSP library, which implements the functions that the application processor will invoke.
  • Run the example on the simulator.
  • Push the executable, DSP library, and, if required, any test data on the target.
  • Run the example on the target.

Usage of the script is as follows, which is displayed by using the -h option:

<walkthrough script> [-h] [-T] [-B] [-C] [-U] [-D] [-s] [-M] [-N] [-32] [-V]

note: Using either -T or -s is mandatory for running the script

HLOS argument:
                            Specify target HLOS (default: LA)
Other arguments:
  -h, --help                Show this help message and exit
  -T,--target               Name of the connected target (default: None)
  -B,--build-system         Specify the build system (default: CMake)
  -C,--build-config         Specify the build config (default: None)
  -U,--unsigned             Run on specified PD: 1 for Unsigned PD and 0 for Signed PD (default: 1)
  -D,--domain               Specify the DSP on the device (default: None)
  -s,--device-id            Device ID. For example, ADB serial number for LA & LE devices (default: None)
  -M, --skip-rebuild        Do not rebuild (default: False)
  -N, --skip-testsig        Skip test signature installation (default: False)
  -32, --thirty-two-bit     Specify only if the HLOS arch of the target is 32 bit (default: False)
  -V, --verbose             Enable verbose logging during compilation (default: False)

To get the HLOS specific help message use below command:

python calculator_walkthrough.py <LE/LA> -h

One of the most useful options is -N: it skips the step of signing the device, which only needs to be performed on a newly flashed device.

Out of -T(TARGET) and -s(DEVICE_ID), only one is mandatory.

Default device paths used by example walkthrough scripts

For LA targets::

  • HLOS exe destination: /vendor/bin
  • HLOS lib destination: /vendor/lib (32 bit) OR /vendor/lib64 (64 bit)
  • DSP lib destination: /vendor/lib/rfsa/dsp/sdk

For LE targets::

  • HLOS exe destination: /usr/bin
  • HLOS lib destination: /usr/lib (32 bit) OR /usr/lib64 (64 bit)
  • DSP lib destination: /usr/lib/rfsa/dsp/sdk

Usage examples

python calculator_walkthrough.py -T lahaina -32

The command above will:

  • build the calculator 32-bit executable and libraries for the LA HLOS(Android) using CMake build system
  • build the calculator Hexagon libraries using CMake build system
  • push the built binaries and run the example on target

The following configurations will be used:

  • DSP used for offloading: cDSP
  • HLOS exe destination: /vendor/bin
  • HLOS lib destination: /vendor/lib
  • cDSP lib destination: /vendor/lib/rfsa/dsp/sdk
    python calculator_walkthrough.py -T lahaina -B maked -D 0 -U 0

The command above will:

  • sign the Lahaina device
  • build the calculator 64-bit executable and libraries for the LA HLOS(Android) using make.d build system
  • build the calculator Hexagon libraries using make.d build system
  • run the example on the simulator as specified in the hexagon.min rules
  • push the built binaries and run the example on target

The following configurations will be used:

  • DSP used for offloading: aDSP
  • HLOS exe destination: /vendor/bin
  • HLOS lib destination: /vendor/lib64
  • aDSP lib destination: /vendor/lib/rfsa/dsp/sdk
    python calculator_walkthrough.py LE -T qcs405 -N -a data -l data/lib

The command above will:

  • skip the device signing
  • build the calculator 64-bit executable and libraries for the LE HLOS(UbuntuARM) using CMake build system
  • build the calculator Hexagon libraries using CMake build system
  • push the built binaries and run the example on target

The following configurations will be used:

  • DSP used for offloading: cDSP
  • HLOS exe destination: /data/bin
  • HLOS lib destination: /data/lib
  • cDSP lib destination: /data/lib/rfsa/dsp/sdk

NOTE: For building Hexagon libraries, the Hexagon architecture is determined based on the target name or device ID passed as arguments.

NOTE: The option -T can be used to identify the required device if multiple devices are connected simultaneously. If multiple devices of the same type are connected, for example if there are two Waipio devices connected simultaneously, then use the -s option to differentiate between devices based on the ADB serial numbers.

The ADB serial number of a device is a string created by ADB to uniquely identify the device by its port number.

adb devices -l
e76a39c6               device product:taro model:Taro_for_arm64 device:taro
f68b78d7               device product:taro model:Taro_for_arm64 device:taro

python calculator_walkthrough.py -s e76a39c6 -N

The command above will:

  • skip the device signing
  • build the calculator 64-bit executable and libraries for the LA HLOS(Android) using CMake build system
  • build the calculator Hexagon libraries using CMake build system
  • push the built binaries and run the example on target

List of examples

The following table lists all the examples that are included in the base SDK and the various features that they illustrate.

Example Features illustrated in the example
android_app Demonstrates two sessions running concurrently by offloading work onto DSP
asyncdspq_example Demonstrate the usage of the asynchronous message queue
calculator FastRPC
Building
Simulating
Target testing
Multi-domain/multi-DSP support
Unsigned PD
Versioning
calculator_c++ C++ on the DSP
calculator_c++_apk C++ on the application processor
dspqueue Asynchronous DSP Packet Queue
gtest Demonstrate usage of the Google test framework
HAP example HAP APIs
Remote DSP capabilities APIs
itrace Illustrates how to use the itrace library to monitor CPU and DSP activity using various profiling events.
LPI example LPI mode
multithreading Multithreading using QuRT threads, barriers and mutexes
Debugging
IDE
oemconfig Generate example oemconfig.so
profiling CPU and DSP timers and cycle counters
Simulator profiling
sysMon
Hexagon Trace Analyzer
qhl QHL (Qualcomm Hexagon Libraries)
qhl_hvx QHL HVX (Qualcomm Hexagon Libraries for HVX)
HVX
qprintf qprintf (printf library extension for HVX and assembly)