Run sample applications

The following workflow shows how to get started with a graphics application on a Qualcomm device. The preceding flowchart outlines the steps involved in utilizing the Platform SDK for running and analyzing graphics and compute sample applications:

1. Begin by generating the SDK tailored for the platform.
2. Run OpenGL ES, OpenCL, and Vulkan sample applications to validate the functionality.
3. Perform debugging to identify and resolve issues during the sample run.
4. Use the Snapdragon Profiler tool to analyze graphics performance issues.

​

Compile and run OpenGL ES-based applications

The Platform SDK provides an OpenGL ES-based sample application called glmark2. This application renders a variety of scenes using the OpenGL ES API. To compile and run OpenGL ES-based applications, you must have an understanding of the OpenGL ES API. Prerequisites

• Install the Platform SDK using either of the following methods:
  • Using Qualcomm release archive
  • Manually compile the Qualcomm Linux SDK
• Establish an SSH connection from the Linux host computer to the device. For instructions, see Sign in using SSH.
• Ensure that the Weston application is running. If not, start the Weston application by running the following command:

  mount -o remount,rw /
  export XDG_RUNTIME_DIR=/run/user/1000 && mkdir -p $XDG_RUNTIME_DIR
  weston --idle-time=0 --continue-without-input
  

  For more information about the Weston application, see Qualcomm Linux Display Guide.

For information about the OpenGL ES extensions supported on Qualcomm Linux devices, see EGL extensions. Compile and run the glmark2 application

1. To set the SDK environment on the Linux host computer, run the following command:
   source environment-setup-armv8a-qcom-linux
   
2. To compile and generate a binary, run the following command:
   cd glmark2
   meson setup build -Dflavors=wayland-glesv2 --prefix=$PWD/build
   ninja -C build install
   
   If you encounter any umask error, set the umask to 022. After successful compilation, you can find the output files in the <path-to-installed-sdk>/workspace/sources/glmark2/oe-workdir/image/usr/bin directory.
3. To push the binary to the device, run the following commands:
   scp -r <path-to-installed-Platform-sdk>/workspace/sources/glmark2/oe-workdir/image/usr/bin/glmark2-es2-wayland root@[IP-address-of-the-device]:/tmp
   
   scp -r <path-to-installed-Platform-sdk>/workspace/sources/glmark2/oe-workdir/image/usr/share/glmark2 root@[IP-address-of-the-device]:/tmp
   
4. To run the application on the device, open the SSH terminal using the IP address of the device and run the following commands:
   export XDG_RUNTIME_DIR=/run/user/1000 && export WAYLAND_DISPLAY=wayland-1
   chmod 777 /tmp/glmark2-es2-wayland
   chmod -R 777 /tmp/glmark2
   cd /tmp
   ./glmark2-es2-wayland --data-path /tmp/glmark2 -b jellyfish
   
   Note To run the sample application from the UART shell, remount the file system using the following command:
   mount -o remount,rw /
   
   Note The glmark2 and X11 applications encounter an X connection to :0 broken condition. The upcoming release will include a fix for this issue.

​

Compile and run OpenCL-based applications

The Adreno OpenCL SDK has many sample applications. The steps to compile and run them are the same. You can develop several applications using the Adreno OpenCL SDK. However, consider the GPU capabilities before you compile and run applications. The steps to run the hello world application are as follows: Prerequisites

• Install the Platform SDK using either of the following methods:
  • Using Qualcomm release archive
  • Manually compile the Qualcomm Linux SDK
• Establish an SSH connection from the Linux host computer to the device. For instructions, see Sign in using SSH.
• Download the Adreno OpenCL SDK. Note
  • You must be a registered user to download the Adreno OpenCL SDK.
  • When working with QLI 2.0, ensure that you use OpenCL SDK version 2.4 or newer.

For information about the OpenCL extensions supported on Qualcomm Linux devices, see OpenCL extensions. Compile and run the hello world sample application

1. To compile the application, run the following commands on the Linux host computer:
   cd opencl-sdk
   
   source <path-to-installed-Platform-sdk>/environment-setup-armv8a-qcom-linux
   
   cmake -B build -DCLSDK_OPENCL_LIBRARY=$OECORE_TARGET_SYSROOT/usr/lib/libOpenCL.so -DOPEN_EMBEDDED=1 -DOPEN_EMBEDDED_PATH=$OECORE_TARGET_SYSROOT
   cmake --build build
   
   After you successfully compile the code, the system generates binary files in the /build directory.
2. To run the application, open the SSH terminal using the IP address of the device and run the following commands:
   mkdir -p /tmp/data
   mkdir -p /tmp/data/opencl
   
   Note To run the sample application from the UART shell, remount the file system using the following command:
   mount -o remount,rw /
   
3. To push the binary to the device, run the following commands:
   scp -r <opencl-sdk>/build/* root@[IP-address-of-the device]:/tmp/data/opencl/
   
   scp -r <opencl-sdk>/example_images/* root@[IP-address-of-the device]:/tmp/data/opencl/
   
4. To start the application, run the following command on the device using the SSH terminal. For all OpenCL use cases, ensure that the export OCL_ICD_FILENAMES=/usr/lib/libOpenCL_adreno.so.1 command is exported when using an overlay or qcom‑multimedia‑proprietary‑image.
   cd /tmp/data/opencl/
   mkdir out
   chmod 777 ./*
   echo "run hello world 2.0 opencl sdk" > hello_world_input.txt
   touch out/hello_world_output.txt
   cat out/hello_world_output.txt
   ./cl_sdk_hello_world hello_world_input.txt out/hello_world_output.txt
   cat out/hello_world_output.txt
   

​

Compile and run Vulkan-based applications

The Adreno SDK has many sample applications based on Vulkan. The steps to compile and run any Vulkan-based application are the same. You can develop Vulkan-based applications using the Adreno SDK. To compile and run these applications, see the following procedures. As an example, this section describes the steps to run Sascha Willems and Khronos Vulkan-based applications. Note The Dragonwing IQ-615 device doesn’t support the Vulkan-based applications that depend on the VK_EXT_debug_utils extension. Support for this extension will be provided in the upcoming release.

​

Compile and run Sascha Willems Vulkan-based applications

You can find the Sascha Willems Vulkan sample applications at https://github.com/SaschaWillems/Vulkan.git. The steps to compile and run any Sascha Willems Vulkan application are the same. For information about the Vulkan extensions supported on Qualcomm Linux devices, see Vulkan extensions. Prerequisites

• Install the Platform SDK using either of the following methods:
  • Using Qualcomm release archive
  • Manually compile the Qualcomm Linux SDK
• Establish an SSH connection from the Linux host computer to the device. For instructions, see Sign in using SSH.

Steps to compile and run the triangle bin sample application

1. To compile the application, run the following commands on the Linux host computer:
   git clone --recurse-submodules https://github.com/SaschaWillems/Vulkan.git
   cd Vulkan
   
   source <path-to-installed-Platform-sdk>/environment-setup-armv8a-qcom-linux
   
   cmake -G "Unix Makefiles" -Bbuild/linux -DUSE_WAYLAND_WSI=ON -DRESOURCE_INSTALL_DIR="/tmp/"
   cmake --build build/linux --config Release  -j$(nproc)
   
   After successful compilation, you can find the binary files in the build/linux/bin directory.
2. To push the binary to the device, run the following commands:
   scp -r assets root@[IP-address-of-the-device]:/tmp/
   
   scp -r shaders root@[IP-address-of-the-device]:/tmp/
   
   scp -r build/linux/bin/triangle root@[IP-address-of-the-device]:/tmp/
   
3. To run the application, open the SSH terminal using the IP address of the device and run the following commands. For all Vulkan-based use cases, ensure that the export VK_DRIVER_FILES=/usr/share/vulkan/icd.d/adrenovk.json command is exported when using an overlay or qcom‑multimedia‑proprietary‑image.
   cd /tmp
   chmod -R 777 assets/
   chmod -R 777 shaders/
   chmod 777 triangle
   export XDG_RUNTIME_DIR=/run/user/1000 && export WAYLAND_DISPLAY=wayland-1
   ./triangle
   

​

Compile and run Khronos Vulkan-based applications

You can find the Khronos Vulkan-based applications at https://github.com/KhronosGroup/Vulkan-Samples.git. The steps to compile and run any Khronos Vulkan-based application are the same. For information about the Vulkan extensions supported on Qualcomm Linux devices, see Vulkan extensions. Prerequisites

• Install the Platform SDK using either of the following methods:
  • Using Qualcomm release archive
  • Manually compile the Qualcomm Linux SDK
• Establish an SSH connection from the Linux host computer to the device. For instructions, see Sign in using SSH.

Steps to compile and run the vulkan_samples application

1. To compile the application, run the following commands on the Linux host computer:
   sudo apt-get install -y libwayland-dev
   git clone --recurse-submodules https://github.com/KhronosGroup/Vulkan-Samples.git
   cd Vulkan-Samples/
   
   source <path-to-installed-Platform-sdk>/environment-setup-armv8a-qcom-linux
   
   cmake -G "Unix Makefiles" -Bbuild/linux -DCMAKE_BUILD_TYPE=Release -DVKB_WSI_SELECTION=WAYLAND -DGLFW_BUILD_X11=OFF
   
   If the compilation fails, do the following:
   1. Open the Vulkan-Samples/build/linux/CmakeCache.txt file.
   2. Change GLFW_BUILD_X11 to OFF.
   3. Run the following command:
      cmake -G "Unix Makefiles" -Bbuild/linux -DCMAKE_BUILD_TYPE=Release -DVKB_WSI_SELECTION=WAYLAND -DGLFW_BUILD_X11=OFF -DVKB_compute_shaders_with_tensors=OFF -DVKB_simple_tensor_and_data_graph=OFF -DVKB_graph_constants:BOOL=OFF
      
2. To generate the binary files, run the following command:
   cmake --build build/linux --config Release --target vulkan_samples -j$(nproc)
   
   After successful compilation, you can find the binary files in the Vulkan-Samples/build/linux/app/bin/Release/aarch64 directory.
3. To push the binary to the device, run the following commands:
   scp -r assets root@[IP-address-of-the-device]:/tmp/
   
   scp -r shaders root@[IP-address-of-the-device]:/tmp/
   
   scp -r build/linux/app/bin/Release/aarch64/vulkan_samples root@[IP-address-of-the-device]:/tmp/
   
4. To run the application, open the SSH terminal using the IP address of the device and run the following commands. For all Vulkan-based use cases, ensure that the export VK_DRIVER_FILES=/usr/share/vulkan/icd.d/adrenovk.json command is exported when using an overlay or qcom‑multimedia‑proprietary‑image.
   cd /tmp
   chmod -R 777 assets/
   chmod -R 777 shaders/
   chmod 777 vulkan_samples
   export XDG_RUNTIME_DIR=/run/user/1000 && export WAYLAND_DISPLAY=wayland-1
   ./vulkan_samples sample swapchain_images
   
   Note If you are facing issues compiling the application or running it, use the following commands to check out the specific version. Later, repeat the steps from 2 to 4 and recompile the application and run.
   git checkout b3cb3822e8896ab650c4310f2c5f66a101469e9e
   git submodule sync
   git submodule update
   
   If you are unable to run these sample applications from the /tmp directory due to storage issues, try alternative directories such as /etc.

​

Compile and run X11-based applications

The X11-based applications are graphical programs designed for the X Window system, a widely used display protocol on Linux and other Unix-like OS. Prerequisites

• Install the Platform SDK using either of the following methods:
  • Using Qualcomm release archive
  • Manually compile the Qualcomm Linux SDK
• Establish an SSH connection from the Linux host computer to the device. For instructions, see Sign in using SSH.
• Install X11-related binaries from GitLab.

  • Install libXt (X Toolkit Intrinsics)

    git clone https://gitlab.freedesktop.org/xorg/lib/libxt.git
    cd libxt
    

    source <path-to-installed-Platform-sdk>/environment-setup-armv8a-qcom-linux
    

    ./autogen.sh --host=aarch64-linux-gnu --prefix=<path-to-installed-Platform-sdk>/tmp/sysroots/qcom-armv8a/usr
    

    ./configure --host=aarch64-linux-gnu --prefix=<path-to-installed-Platform-sdk>/tmp/sysroots/qcom-armv8a/usr
    

    make
    make install
    cd src/.libs/
    

    cp -r libX* <path-to-installed-Platform-sdk>/tmp/sysroots/qcom-armv8a/usr/lib
    

    cd ../../..
    

  • Install libxmu (miscellaneous utility functions for X11)

    git clone https://gitlab.freedesktop.org/xorg/lib/libxmu.git
    cd libxmu
    

    source <path-to-installed-Platform-sdk>/environment-setup-armv8a-qcom-linux
    

    ./autogen.sh --host=aarch64-linux-gnu --prefix=<path-to-installed-Platform-sdk>/tmp/sysroots/qcom-armv8a/usr
    

    ./configure --host=aarch64-linux-gnu --prefix=<path-to-installed-Platform-sdk>/tmp/sysroots/qcom-armv8a/usr
    

    make
    make install
    cd src/.libs/
    

    cp -r libX* <path-to-installed-Platform-sdk>/tmp/sysroots/qcom-armv8a/usr/lib
    

    cd ../../..
    

  • Install X development libraries for host computer

    sudo apt-get install xorg-dev
    

• Set up Meson

  1. Create the aarch64-qcom-linux-meson.cross file.

     cd <path-to-installed-Platform-sdk>/tmp/sysroot/X86_64/usr/share/meson
     vi aarch64-qcom-linux-meson.cross
     

  2. Add the following text to the aarch64-qcom-linux-meson.cross file and save the changes.

     [binaries]
     c = ['aarch64-qcom-linux-gcc', '-march=armv8.2-a+crypto', '-mbranch-protection=standard', '-fstack-protector-strong', '-O2', '-D_FORTIFY_SOURCE=2', '-Wformat', '-Wformat-security', '-Werror=format-security', '--sysroot=<path-to-installed-Platform-sdk>/tmp/sysroots/qcom-armv8a']
     cpp = ['aarch64-qcom-linux-g++', '-march=armv8.2-a+crypto', '-mbranch-protection=standard', '-fstack-protector-strong', '-O2', '-D_FORTIFY_SOURCE=2', '-Wformat', '-Wformat-security', '-Werror=format-security', '--sysroot=<path-to-installed-Platform-sdk>/tmp/sysroots/qcom-armv8a']
     ar = 'aarch64-qcom-linux-ar'
     nm = 'aarch64-qcom-linux-nm'
     strip = 'aarch64-qcom-linux-strip'
     pkgconfig = 'pkg-config'
     
     [built-in options]
     c_args = ['-O2', '-pipe', '-g', '-feliminate-unused-debug-types']
     c_link_args = ['-Wl,-O1', '-Wl,--hash-style=gnu', '-Wl,--as-needed', '-Wl,-z,relro,-z,now']
     cpp_args = []
     cpp_link_args = ['-Wl,-O1', '-Wl,--hash-style=gnu', '-Wl,--as-needed', '-Wl,-z,relro,-z,now']
     
     [properties]
     needs_exe_wrapper = true
     sys_root = '<path-to-installed-Platform-sdk>/tmp/sysroots/qcom-armv8a'
     [host_machine]
     system = 'linux'
     cpu_family = 'x86_64'
     cpu = 'x86_64'
     endian = 'little'
     

  3. Create the meson.native file.

     cd <path-to-installed-Platform-sdk>/tmp/sysroot/X86_64/usr/share/meson
     vi meson.native
     

  4. Add the following text to the meson.native file and save the changes.

     [binaries]
     c = 'gcc'
     cpp = 'g++'
     ar = 'ar'
     nm = 'nm'
     strip = 'strip'
     readelf = 'readelf'
     pkgconfig = 'pkg-config-native'
     
     [built-in options]
     c_args = ['-isystem/<path-to-installed-Platform-sdk>/tmp/sysroots/x86_64/usr/include' , '-O2', '-pipe']
     c_link_args = ['-L/<path-to-installed-Platform-sdk>/tmp/sysroots/x86_64/usr/lib', '-L/<path-to-installed-Platform-sdk>/tmp/sysroots/x86_64/lib', '-Wl,-rpath-link,/<path-to-installed-Platform-sdk>/tmp/sysroots/x86_64/usr/lib', '-Wl,-rpath-link,/<path-to-        installed-Platform-sdk>/tmp/sysroots/x86_64/lib', '-Wl,--allow-shlib-undefined', '-Wl,--dynamic-linker=/<path-to-installed-Platform-sdk>/tmp/sysroots/x86_64/lib/ld-linux-x86-64.so.2']
     cpp_args = ['-isystem/<path-to-installed-Platform-sdk>/tmp/sysroots/x86_64/usr/include' , '-O2', '-pipe']
     cpp_link_args = ['-L/<path-to-installed-Platform-sdk>/tmp/sysroots/x86_64/usr/lib', '-L/<path-to-installed-Platform-sdk>/tmp/sysroots/x86_64/lib', '-Wl,-rpath-link,/<path-to-installed-Platform-sdk>/tmp/sysroots/x86_64/usr/lib', '-Wl,-rpath-link,/<path-to-
     installed-Platform-sdk>/tmp/sysroots/x86_64/lib', '-Wl,--allow-shlib-undefined', '-Wl,--dynamic-linker=/<path-to-installed-Platform-sdk>/tmp/sysroots/x86_64/lib/ld-linux-x86-64.so.2']
     
     [properties]
     sys_root = '/<path-to-installed-Platform-sdk>/tmp/sysroots/x86_64'
     

Compile and run X11-based glmark2 application

1. To set the SDK environment run the following command in the Linux terminal:

   source <path-to-installed-Platform-sdk>/environment-setup-armv8a-qcom-linux
   

2. To clone the glmark2 source, run the following command:

   git clone https://github.com/glmark2/glmark2.git
   cd glmark2
   

3. To configure, run the following command:

   meson setup build -Dflavors=x11-glesv2 --prefix=$PWD/build
   

4. To compile and generate a binary, run the following command:

   ninja -C build install
   

   The generated binary file is available at: build/bin directory. For example, build/src/es-glmark2. The data file is available at: build/share/glmark2. For example, <path-to-installed-Platform-sdk>/glmark2/source/build/share/glmark2.

5. To start the procedure, run the following commands:

   scp -r build/bin/glmark2-es2 root@[IP-address-of-the-device]:/tmp
   

   scp -r build/share/glmark2 root@[IP-address-of-the-device]:/tmp
   

6. To run Weston, open a new SSH terminal using the IP address of the device and run the following command:

   killall weston
   export XDG_RUNTIME_DIR=/run/user/1000 && mkdir -p $XDG_RUNTIME_DIR && weston --continue-without-input --idle-time=0 --backend=drm-backend.so --xwayland
   

7. To run the glmark2 application, open the original SSH terminal using the IP address of the device and run the following command:

   . /etc/profile
   chmod 777 /tmp/glmark2-es2
   chmod 777 /tmp/glmark2
   export XDG_RUNTIME_DIR=/run/user/1000
   mkdir --parents $XDG_RUNTIME_DIR
   chmod 0700 $XDG_RUNTIME_DIR
   export WAYLAND_DISPLAY=wayland-1
   export DISPLAY=:0
   cd /tmp/
   ./glmark2-es2 --data-path /tmp/glmark2
   

Note When you run the glmark2 application, consider the run successful once the benchmark is complete and the final score is displayed. You can disregard any messages after this point. Compile and run X11-based VKCube application

1. To set the SDK environment run the following command in the Linux terminal:

   source <path-to-installed-Platform-sdk>/environment-setup-armv8a-qcom-linux
   

2. To clone the VKCube source, run the following command:

   git clone https://github.com/krh/vkcube.git
   cd vkcube
   

3. To configure, run the following command:

   meson setup build -Dxcb=true
   

4. To compile and generate a binary, run the following command:

   ninja -C build
   

   The generated binary file is available at: $PWD/build/. For example, <path-to-installed-Platform-sdk>/vkcube/build/.

5. To start the procedure, open a new SSH terminal using the IP address of the device and run the following command:

   mount -o remount,rw /
   mount -o remount,rw /usr
   killall weston
   export XDG_RUNTIME_DIR=/run/user/1000 && mkdir -p $XDG_RUNTIME_DIR && weston --continue-without-input --idle-time=0 --backend=drm-backend.so --xwayland
   

6. To start the VKCube application, open the original SSH terminal using the IP address of the device and run the following commands:

   cd <path-to-installed-Platform-sdk>/vkcube/build
   

   mkdir -p /etc/data
   

   scp -r vkcube root@[IP-address-of-the-device]: /etc/data
   

   scp -r <path-to-installed-Platform-sdk>/tmp/sysroots/qcom-armv8a/usr/lib/libxc*/usr/lib/
   

7. Open a new SSH terminal using the IP address of the device, and run the following command:
   . /etc/profile
   export XDG_RUNTIME_DIR=/run/user/1000
   mkdir --parents $XDG_RUNTIME_DIR
   chmod 0700 $XDG_RUNTIME_DIR
   export WAYLAND_DISPLAY=wayland-1
   export DISPLAY=:0
   chmod 777 /etc/data/vkcube
   ./etc/data/vkcube
   

​

Next steps

• Debug graphic issues
• Profile GPU performance issues
• Supported extensions