Skip to content

Latest commit

 

History

History
148 lines (108 loc) · 5.59 KB

running_android.md

File metadata and controls

148 lines (108 loc) · 5.59 KB

Running using a layer on Android

To make it easy to install and configure layers for Android, we provide an installation script which automatically configures a device to use one or more layers.

These instructions assume that you have already built the layers that you want to install. See the Building a layer page, or the per-layer README files, for build instructions.

Script configuration

From the root directory of the project checkout, run the Android installation utility, specifying the directory containing the layer that you want to install:

python3 lgl_android_install.py --layer layer_gpu_example

By default the script will automatically search to find connected Android devices, and debuggable packages on the chosen device. If there are multiple options the script will present a menu and prompt you for a selection. You avoid the interactive prompt by manually specifying the device (--device/-D) and package (--package/-P) to instrument.

Once you have selected a device and package, wait for the layer to be installed and configured. The script will notify you when this has been done.

You can now perform you work by running the target application. The layer will be loaded automatically.

After you are finished, return to the script and press a key to notify it that you have finished. It will clean up the device and remove the layers.

Package launch and configuration

By default, the installer will configure the layer but will not launch the Android package. You must manually restart the package after the layers are installed to ensure that they get loaded.

If you specify --auto-start, the installer will automatically start the application after the layers are configured and stop the application when you finish profiling.

Auto-start will default to using the main launchable activity for the package, but you might override this using --package-activity to specify the name of another activity to launch.

You optionally pass in additional activity command line arguments by using the --package-arguments option to specify the argument string to pass to am start. This string will often contain spaces, so ensure that it is quoted correctly on the host shell. For example:

... --package-arguments "-e cmd 'R.InternalRenderScaling 0.5'"

Layer configuration

Some layers require a configuration file to control their behavior. Most layers that need a configuration file ship with a default config, layer_config.json, in their layer directory. Users override this with a custom config by using the --config/-C option to specify a custom config file.

NOTE: The layer that each config file applies to is specified in the config file itself, and is not implied by order of the command line options.

Multi-layer installation

The script is able to install multiple layers in a stack. Specify the --layer/-L option multiple times, once per layer. Layers are stacked in command line order, with the first layer specified being the top of the stack closest to the application.

Khronos validation layer installation

The script supports installing the Khronos validation layer. A dummy layer directory, layer_khronos_validation, is provided. Download the latest binary release from the Vulkan-ValidationLayers/releases GitHub, and place the binaries into the dummy build tree at the correct location.

Once this is done you install the validation layer like any other.

NOTE: When installing the Khronos validation layer you need to decide where to install it in the layer stack. If you install it as the first layer in the stack it will only report issues from the application. If you install it last, it will report errors from the application and all layers above it in the stack.

Capturing Android logcat

During development it is often useful to capture the Android log, using logcat to save it to a file on the host.

If you specify the --logcat <file> option the script will automatically clear the logcat log after installing the layers, and start recording logcat to the specified file. Logcat recording will end during device clean up.

Manual configuration

For users with existing configuration flows, Vulkan layers can be manually configured using adb to copy the files and set the system properties.

For layers with configuration files, the configuration file must be named after the layer (e.g. VK_LAYER_LGL_gpu_support.json) and then pushed to the /data/local/tmp directory with global (0666) access permissions.

Note: Android will fail to start an application if it has a layer enabled, but the layer library cannot be found. Ensure that you disable your layer when you have finished using it.

Install

PACKAGE=com.example.app
LAYER_LIB=libVkLayerDemo.so
LAYER_NAME=VK_LAYER_LGL_DEMO

adb push $LAYER_LIB /data/local/tmp
adb shell run-as $PACKAGE cp /data/local/tmp/$LAYER_LIB .
adb shell settings put global enable_gpu_debug_layers 1
adb shell settings put global gpu_debug_app $PACKAGE
adb shell settings put global gpu_debug_layer_app $PACKAGE
adb shell settings put global gpu_debug_layers $LAYER_NAME

Uninstall

PACKAGE=com.example.app
LAYER_LIB=libVkLayerDemo.so
LAYER_NAME=VK_LAYER_LGL_DEMO

adb shell rm /data/local/tmp/$LAYER_LIB
adb shell run-as $PACKAGE rm $LAYER_LIB
adb shell settings delete global enable_gpu_debug_layers
adb shell settings delete global gpu_debug_app
adb shell settings delete global gpu_debug_layers
adb shell settings delete global gpu_debug_layer_app

Copyright © 2024-2025, Arm Limited and contributors.