Code Monkey home page Code Monkey logo

perfdoc's Introduction

PerfDoc


⚠️ WARNING
This project has been donated to Khronos Group. Development has now moved to:

- Vulkan-ValidationLayers

Please open issues and pull requests there.
This means that best practice checks are now part of VK_LAYER_KHRONOS_validation. For more information on how to enable them, see this blog.

perfdocbanner

PerfDoc is a Vulkan layer which aims to validate applications against the Mali Application Developer Best Practices document.

Just like the LunarG validation layers, this layer tracks your application and attempts to find API usage which is discouraged. PerfDoc focuses on checks which can be done up-front, and checks which can portably run on all platforms which support Vulkan.

The intended use of PerfDoc is to be used during development to catch potential performance issues early. The layer will run on any Vulkan implementation, so Mali-related optimizations can be found even when doing bringup on desktop platforms. Just like Vulkan validation layers, errors are reported either through VK_EXT_debug_report to the application as callbacks, or via console/logcat if enabled.

Dynamic checking (i.e. profiling) of how an application is behaving in run-time is currently not in the scope of PerfDoc.

Some heuristics in PerfDoc are based on "arbitrary limits" in case where there is no obvious limit to use. These values can be tweaked later via config files if needed. Some checks which are CPU intensive (index scanning for example), can also be disabled by the config file.

Features

Currently, the layer implements the checks below. The layer uses this enumeration to pass down a message code to the application. The debug callback has a message string with more description.

enum MessageCodes
{
	MESSAGE_CODE_COMMAND_BUFFER_RESET = 1,
	MESSAGE_CODE_COMMAND_BUFFER_SIMULTANEOUS_USE = 2,
	MESSAGE_CODE_SMALL_ALLOCATION = 3,
	MESSAGE_CODE_SMALL_DEDICATED_ALLOCATION = 4,
	MESSAGE_CODE_TOO_LARGE_SAMPLE_COUNT = 5,
	MESSAGE_CODE_NON_LAZY_MULTISAMPLED_IMAGE = 6,
	MESSAGE_CODE_NON_LAZY_TRANSIENT_IMAGE = 7,
	MESSAGE_CODE_MULTISAMPLED_IMAGE_REQUIRES_MEMORY = 8,
	MESSAGE_CODE_RESOLVE_IMAGE = 9,
	MESSAGE_CODE_FRAMEBUFFER_ATTACHMENT_SHOULD_BE_TRANSIENT = 10,
	MESSAGE_CODE_FRAMEBUFFER_ATTACHMENT_SHOULD_NOT_BE_TRANSIENT = 11,
	MESSAGE_CODE_INDEX_BUFFER_SPARSE = 12,
	MESSAGE_CODE_INDEX_BUFFER_CACHE_THRASHING = 13,
	MESSAGE_CODE_TOO_MANY_INSTANCED_VERTEX_BUFFERS = 14,
	MESSAGE_CODE_DISSIMILAR_WRAPPING = 15,
	MESSAGE_CODE_NO_PIPELINE_CACHE = 16,
	MESSAGE_CODE_DESCRIPTOR_SET_ALLOCATION_CHECKS = 17,
	MESSAGE_CODE_COMPUTE_NO_THREAD_GROUP_ALIGNMENT = 18,
	MESSAGE_CODE_COMPUTE_LARGE_WORK_GROUP = 19,
	MESSAGE_CODE_COMPUTE_POOR_SPATIAL_LOCALITY = 20,
	MESSAGE_CODE_POTENTIAL_PUSH_CONSTANT = 21,
	MESSAGE_CODE_MANY_SMALL_INDEXED_DRAWCALLS = 22,
	MESSAGE_CODE_DEPTH_PRE_PASS = 23,
	MESSAGE_CODE_PIPELINE_BUBBLE = 24,
	MESSAGE_CODE_NOT_FULL_THROUGHPUT_BLENDING = 25,
	MESSAGE_CODE_SAMPLER_LOD_CLAMPING = 26,
	MESSAGE_CODE_SAMPLER_LOD_BIAS = 27,
	MESSAGE_CODE_SAMPLER_BORDER_CLAMP_COLOR = 28,
	MESSAGE_CODE_SAMPLER_UNNORMALIZED_COORDS = 29,
	MESSAGE_CODE_SAMPLER_ANISOTROPY = 30,
	MESSAGE_CODE_TILE_READBACK = 31,
	MESSAGE_CODE_CLEAR_ATTACHMENTS_AFTER_LOAD = 32,
	MESSAGE_CODE_CLEAR_ATTACHMENTS_NO_DRAW_CALL = 33,
	MESSAGE_CODE_REDUNDANT_RENDERPASS_STORE = 34,
	MESSAGE_CODE_REDUNDANT_IMAGE_CLEAR = 35,
	MESSAGE_CODE_INEFFICIENT_CLEAR = 36,
	MESSAGE_CODE_LAZY_TRANSIENT_IMAGE_NOT_SUPPORTED = 37,

	MESSAGE_CODE_COUNT
};

The objectType reported by the layer matches the standard VK_EXT_debug_report object types.

To build

See BUILD.md.

Config file

The config file is optional.

There are certain values in PerfDoc which are used as thresholds for heuristics, which can flag potential issues in an application. Sometimes, these thresholds are somewhat arbitrary and may cause unnecessary false positives for certain applications. For these scenarios it is possible to provide a config file. See the sections below for how to enable the config file for Linux/Windows and Android.

Some common options like logging can be overridden directly with environment variables or setprop on Android. A config file should not be necessary in the common case.

The default config file can be found in layer/perfdoc-default.cfg. This default config file contains all the options available to the layer. The default config file contains all the default values which are used by the layer if a config file is not present.

Enabling layers on Linux and Windows

The JSON and binary file must be in the same folder, which is the case after building.

To have the Vulkan loader find the layers, export the following environment variable:

VK_LAYER_PATH=/path/to/directory/with/json/and/binary

This allows the application to enumerate the layer manually and enable the debug callback from within the app. The layer name is VK_LAYER_ARM_mali_perf_doc. The layer should appear in vkEnumerateInstanceLayerProperties and vkEnumerateDeviceLayerProperties.

Enabling layers outside the application

To force-enable PerfDoc outside the application, some environment variables are needed.

VK_LAYER_PATH=/path/to/directory/with/json/and/binary
VK_INSTANCE_LAYERS=VK_LAYER_ARM_mali_perf_doc
VK_DEVICE_LAYERS=VK_LAYER_ARM_mali_perf_doc

However, without a VK_EXT_debug_report debug callback, you will not get any output, so to add logging to file or console:

# Either one of these
MALI_PERFDOC_LOG=stdout
MALI_PERFDOC_LOG=stderr
MALI_PERFDOC_LOG=/path/to/log.txt
MALI_PERFDOC_LOG=debug_output # OutputDebugString, Windows only

It is also possible to use a config file which supports more options as well as logging output:

MALI_PERFDOC_CONFIG=/tmp/path/to/config.cfg"

Enabling layers on Android

ABI (ARMv7 vs. AArch64)

The package contains both ARMv7 binaries and AArch64. Make sure to use the right version which matches your application.

Within application

The layer .so must be present in the APKs library directory. The Android loader will find the layers when enumerating layers, just like the validation layers.

The PerfDoc layer must be enabled explicitly by the app in both vkCreateInstance and vkCreateDevice. The layer name is VK_LAYER_ARM_mali_perf_doc. The layer should appear in vkEnumerateInstanceLayerProperties and vkEnumerateDeviceLayerProperties.

Outside the application

Vulkan layers can be placed in /data/local/debug/vulkan on any device. Depending on your device, /data/local/debug/ may be writeable without root access. It is also possible to place the layer directly inside the application library folder in /data/data, but this will certainly require root.

To force-enable the layer for all Vulkan applications:

setprop debug.vulkan.layers VK_LAYER_ARM_mali_perf_doc:

Here is an example for how to enable PerfDoc for any Vulkan application:

# For ARMv7-A
adb push build-android-armeabi-v7a/layer/libVkLayer_mali_perf_doc.so /data/local/debug/vulkan/
# For AArch64
adb push build-android-arm64-v8a/layer/libVkLayer_mali_perf_doc.so /data/local/debug/vulkan/

adb shell

setprop debug.mali.perfdoc.log logcat
setprop debug.vulkan.layers VK_LAYER_ARM_mali_perf_doc:

exit
adb logcat -c && adb logcat -s MaliPerfDoc

Enabling logcat/file logging

It is sometimes desirable to use PerfDoc from outside an application, e.g. when debugging random APKs which do not have PerfDoc integrated.

There are two ways to enable external logging on Android. Both of the methods described below can also be used when the layer is embedded in the APK (but not enabled by the app), but they are most relevant when dealing with arbitrary Vulkan applications.

To filter logcat output, you can use:

adb logcat -s MaliPerfDoc
setprop method (Recommended)

To force-enable logging from outside an application, you can set an Android system property:

setprop debug.mali.perfdoc.log logcat

To log to a file, replace logcat with a filename. Be aware that system properties on Android have a very limited number of characters available, so a long path might not be possible to represent.

setprop debug.mali.perfdoc.log /sdcard/path/to/log.txt
Config file method

An alternative to setprop is via the config file. This method is a bit more cumbersome than setprop, but might be more convenient if you are already using a config file for other purposes.

Place a config file on the SD card looking like this:

loggingFilename logcat

or

loggingFilename /sdcard/path/to/log.txt

Then, point the layer to this config file by typing this into adb shell:

setprop debug.mali.perfdoc.config /sdcard/path/to/perfdoc.cfg

Be careful with permissions however. Not all paths on the SD card can be made visible to an application.

perfdoc's People

Contributors

ddd-arm avatar hanskristian-work avatar joseemilio-arm avatar solidpixel avatar wasimabbas-arm avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

perfdoc's Issues

VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT is required for IBOs

https://github.com/ARM-software/perfdoc/blob/master/layer/buffer.cpp#L40: “memoryRequirements.memoryTypeBits = INDEXBUFFER_MEMORY_PROPERTIES;”
Perfdoc seems to be forcing the requirement that memory for ibos are created with memory requirements VK_MEMORY_PROPERTY_HOST_COHERENT_BIT | VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT enabled. There is a major difference between desktop/mobile in terms of the memory types supported.

Perfdoc seems to be promoted for desktop PC use (besides the obvious mobile use case): https://community.arm.com/graphics/b/blog/posts/perfdoc-how-to-optimize-early-with-vulkan-validation-layer-tools-at-gdc18

The great thing about PerfDoc is that you can run it on the PC before you even begin to port it to mobile in order to validate the basics right from the start, making the process of porting considerably smoother and less frustrating.

So it would be great if this didn't trigger on desktop or the memory requirements would be different for desktop/mobile.

"your device does not match the hardware requirements of this application"

I build perfdoc sucessfully, and get file libVkLayer_mali_perf_doc.so . Besides the code of perfdoc, I clone data of KhronosGroup/SPIRV-Cross (https://github.com/KhronosGroup/SPIRV-Cross) to perfdoc-master/layer/SPIRV-Cross.

Machine: Huawei Mate 10, Xiaomi6
OS: Android 8.0
APP: build from a free Unity AssetStore project, https://www.assetstore.unity3d.com/cn/#!/content/52977
export ANDROID_ABI=arm64-v8a # Kirin970 of Mate10 uses Cortex-A73

When open the app, it prompt "your device does not match the hardware requirements of this application". After touch "continue", it just show me a full screen picture with purple color. (See the attached pictures). No error message being showed in logcat.

Any body use this vulkan layer successfully?

screenshot_2018-01-18-14-46-56-332_com unity3d nature3d
image

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.