{"id":28710997,"url":"https://github.com/arm-software/perfdoc","last_synced_at":"2026-04-01T17:00:49.244Z","repository":{"id":74210142,"uuid":"105034628","full_name":"ARM-software/perfdoc","owner":"ARM-software","description":"A cross-platform Vulkan layer which checks Vulkan applications for best practices on Arm Mali devices.","archived":false,"fork":false,"pushed_at":"2022-01-20T15:46:30.000Z","size":174,"stargazers_count":117,"open_issues_count":1,"forks_count":19,"subscribers_count":15,"default_branch":"master","last_synced_at":"2026-03-05T11:42:59.289Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ARM-software.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-09-27T15:17:58.000Z","updated_at":"2025-07-20T23:06:40.000Z","dependencies_parsed_at":"2024-01-03T06:42:44.348Z","dependency_job_id":"72bbc1d1-a30d-4ca8-9188-bbff7ce92d62","html_url":"https://github.com/ARM-software/perfdoc","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ARM-software/perfdoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2Fperfdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2Fperfdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2Fperfdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2Fperfdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ARM-software","download_url":"https://codeload.github.com/ARM-software/perfdoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARM-software%2Fperfdoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31013762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-27T02:58:54.984Z","status":"ssl_error","status_checked_at":"2026-03-27T02:58:46.993Z","response_time":164,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-14T21:08:43.415Z","updated_at":"2026-03-27T03:05:47.197Z","avatar_url":"https://github.com/ARM-software.png","language":"C++","readme":"# PerfDoc\n\n***\n| :warning: WARNING          |\n|:---------------------------|\n| This project has been donated to Khronos Group. Development has now moved to:\u003cbr\u003e\u003cbr\u003e- [Vulkan-ValidationLayers](https://github.com/KhronosGroup/Vulkan-ValidationLayers)\u003cbr\u003e\u003cbr\u003ePlease open issues and pull requests there.|\n| 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](https://community.arm.com/arm-community-blogs/b/graphics-gaming-and-vr-blog/posts/arm-best-practice-warnings-in-vulkan-sdk).|\n***\n\n![perfdocbanner](https://user-images.githubusercontent.com/11390552/31229971-5d89fc18-a9da-11e7-978b-9d806ef39450.png)\n\n\nPerfDoc is a Vulkan layer which aims to validate applications against the\n[Mali Application Developer Best Practices](https://developer.arm.com/graphics/developer-guides/mali-gpu-best-practices) document.\n\nJust like the LunarG validation layers, this layer tracks your application and attempts to find API usage which is discouraged.\nPerfDoc focuses on checks which can be done up-front, and checks which can portably run on all platforms which support Vulkan.\n\nThe intended use of PerfDoc is to be used during development to catch potential performance issues early.\nThe layer will run on any Vulkan implementation, so Mali-related optimizations can be found even when doing bringup on desktop platforms.\nJust like Vulkan validation layers, errors are reported either through `VK_EXT_debug_report` to the application as callbacks, or via console/logcat if enabled.\n\nDynamic checking (i.e. profiling) of how an application is behaving in run-time is currently not in the scope of PerfDoc.\n\nSome heuristics in PerfDoc are based on \"arbitrary limits\" in case where there is no obvious limit to use.\nThese values can be tweaked later via config files if needed.\nSome checks which are CPU intensive (index scanning for example), can also be disabled by the config file.\n\n## Features\n\nCurrently, the layer implements the checks below.\nThe layer uses this enumeration to pass down a message code to the application.\nThe debug callback has a message string with more description.\n\n```\nenum MessageCodes\n{\n\tMESSAGE_CODE_COMMAND_BUFFER_RESET = 1,\n\tMESSAGE_CODE_COMMAND_BUFFER_SIMULTANEOUS_USE = 2,\n\tMESSAGE_CODE_SMALL_ALLOCATION = 3,\n\tMESSAGE_CODE_SMALL_DEDICATED_ALLOCATION = 4,\n\tMESSAGE_CODE_TOO_LARGE_SAMPLE_COUNT = 5,\n\tMESSAGE_CODE_NON_LAZY_MULTISAMPLED_IMAGE = 6,\n\tMESSAGE_CODE_NON_LAZY_TRANSIENT_IMAGE = 7,\n\tMESSAGE_CODE_MULTISAMPLED_IMAGE_REQUIRES_MEMORY = 8,\n\tMESSAGE_CODE_RESOLVE_IMAGE = 9,\n\tMESSAGE_CODE_FRAMEBUFFER_ATTACHMENT_SHOULD_BE_TRANSIENT = 10,\n\tMESSAGE_CODE_FRAMEBUFFER_ATTACHMENT_SHOULD_NOT_BE_TRANSIENT = 11,\n\tMESSAGE_CODE_INDEX_BUFFER_SPARSE = 12,\n\tMESSAGE_CODE_INDEX_BUFFER_CACHE_THRASHING = 13,\n\tMESSAGE_CODE_TOO_MANY_INSTANCED_VERTEX_BUFFERS = 14,\n\tMESSAGE_CODE_DISSIMILAR_WRAPPING = 15,\n\tMESSAGE_CODE_NO_PIPELINE_CACHE = 16,\n\tMESSAGE_CODE_DESCRIPTOR_SET_ALLOCATION_CHECKS = 17,\n\tMESSAGE_CODE_COMPUTE_NO_THREAD_GROUP_ALIGNMENT = 18,\n\tMESSAGE_CODE_COMPUTE_LARGE_WORK_GROUP = 19,\n\tMESSAGE_CODE_COMPUTE_POOR_SPATIAL_LOCALITY = 20,\n\tMESSAGE_CODE_POTENTIAL_PUSH_CONSTANT = 21,\n\tMESSAGE_CODE_MANY_SMALL_INDEXED_DRAWCALLS = 22,\n\tMESSAGE_CODE_DEPTH_PRE_PASS = 23,\n\tMESSAGE_CODE_PIPELINE_BUBBLE = 24,\n\tMESSAGE_CODE_NOT_FULL_THROUGHPUT_BLENDING = 25,\n\tMESSAGE_CODE_SAMPLER_LOD_CLAMPING = 26,\n\tMESSAGE_CODE_SAMPLER_LOD_BIAS = 27,\n\tMESSAGE_CODE_SAMPLER_BORDER_CLAMP_COLOR = 28,\n\tMESSAGE_CODE_SAMPLER_UNNORMALIZED_COORDS = 29,\n\tMESSAGE_CODE_SAMPLER_ANISOTROPY = 30,\n\tMESSAGE_CODE_TILE_READBACK = 31,\n\tMESSAGE_CODE_CLEAR_ATTACHMENTS_AFTER_LOAD = 32,\n\tMESSAGE_CODE_CLEAR_ATTACHMENTS_NO_DRAW_CALL = 33,\n\tMESSAGE_CODE_REDUNDANT_RENDERPASS_STORE = 34,\n\tMESSAGE_CODE_REDUNDANT_IMAGE_CLEAR = 35,\n\tMESSAGE_CODE_INEFFICIENT_CLEAR = 36,\n\tMESSAGE_CODE_LAZY_TRANSIENT_IMAGE_NOT_SUPPORTED = 37,\n\n\tMESSAGE_CODE_COUNT\n};\n\n```\n\nThe objectType reported by the layer matches the standard `VK_EXT_debug_report` object types.\n\n## To build\n\nSee [BUILD.md](BUILD.md).\n\n## Config file\n\n**The config file is optional.**\n\nThere are certain values in PerfDoc which are used as thresholds for heuristics, which can flag potential issues in an application.\nSometimes, these thresholds are somewhat arbitrary and may cause unnecessary false positives for certain applications.\nFor these scenarios it is possible to provide a config file.\nSee the sections below for how to enable the config file for Linux/Windows and Android.\n\nSome common options like logging can be overridden directly with environment variables or setprop on Android.\nA config file should not be necessary in the common case.\n\nThe default config file can be found in `layer/perfdoc-default.cfg`.\nThis default config file contains all the options available to the layer.\nThe default config file contains all the default values which are used by the layer if a config file is not present.\n\n## Enabling layers on Linux and Windows\n\nThe JSON and binary file must be in the same folder, which is the case after building.\n\nTo have the Vulkan loader find the layers, export the following environment variable:\n\n```\nVK_LAYER_PATH=/path/to/directory/with/json/and/binary\n```\n\nThis allows the application to enumerate the layer manually and enable the debug callback from within the app.\nThe layer name is `VK_LAYER_ARM_mali_perf_doc`.\nThe layer should appear in `vkEnumerateInstanceLayerProperties` and `vkEnumerateDeviceLayerProperties`.\n\n### Enabling layers outside the application\n\nTo force-enable PerfDoc outside the application, some environment variables are needed.\n\n```\nVK_LAYER_PATH=/path/to/directory/with/json/and/binary\nVK_INSTANCE_LAYERS=VK_LAYER_ARM_mali_perf_doc\nVK_DEVICE_LAYERS=VK_LAYER_ARM_mali_perf_doc\n```\n\nHowever, without a `VK_EXT_debug_report` debug callback,\nyou will not get any output, so to add logging to file or console:\n\n```\n# Either one of these\nMALI_PERFDOC_LOG=stdout\nMALI_PERFDOC_LOG=stderr\nMALI_PERFDOC_LOG=/path/to/log.txt\nMALI_PERFDOC_LOG=debug_output # OutputDebugString, Windows only\n```\n\nIt is also possible to use a config file which supports more options as well as logging output:\n\n```\nMALI_PERFDOC_CONFIG=/tmp/path/to/config.cfg\"\n```\n\n## Enabling layers on Android\n\n### ABI (ARMv7 vs. AArch64)\n\nThe package contains both ARMv7 binaries and AArch64.\nMake sure to use the right version which matches your application.\n\n### Within application\n\nThe layer .so must be present in the APKs library directory.\nThe Android loader will find the layers when enumerating layers, just like the validation layers.\n\nThe PerfDoc layer must be enabled explicitly by the app in both `vkCreateInstance` and `vkCreateDevice`.\nThe layer name is `VK_LAYER_ARM_mali_perf_doc`.\nThe layer should appear in `vkEnumerateInstanceLayerProperties` and `vkEnumerateDeviceLayerProperties`.\n\n### Outside the application\n\nVulkan layers can be placed in `/data/local/debug/vulkan` on any device.\nDepending on your device, `/data/local/debug/` may be writeable without root access.\nIt is also possible to place the layer directly inside the application library folder in `/data/data`,\nbut this will certainly require root.\n\nTo force-enable the layer for all Vulkan applications:\n\n```\nsetprop debug.vulkan.layers VK_LAYER_ARM_mali_perf_doc:\n```\n\nHere is an example for how to enable PerfDoc for any Vulkan application:\n```\n# For ARMv7-A\nadb push build-android-armeabi-v7a/layer/libVkLayer_mali_perf_doc.so /data/local/debug/vulkan/\n# For AArch64\nadb push build-android-arm64-v8a/layer/libVkLayer_mali_perf_doc.so /data/local/debug/vulkan/\n\nadb shell\n\nsetprop debug.mali.perfdoc.log logcat\nsetprop debug.vulkan.layers VK_LAYER_ARM_mali_perf_doc:\n\nexit\nadb logcat -c \u0026\u0026 adb logcat -s MaliPerfDoc\n```\n\n#### Enabling logcat/file logging\n\nIt is sometimes desirable to use PerfDoc from outside an application,\ne.g. when debugging random APKs which do not have PerfDoc integrated.\n\nThere are two ways to enable external logging on Android.\nBoth of the methods described below can also be used when the layer is embedded in the APK (but not enabled by the app),\nbut they are most relevant when dealing with arbitrary Vulkan applications.\n\nTo filter logcat output, you can use:\n```\nadb logcat -s MaliPerfDoc\n```\n\n##### setprop method (Recommended)\n\nTo force-enable logging from outside an application, you can set an Android system property:\n```\nsetprop debug.mali.perfdoc.log logcat\n```\n\nTo log to a file, replace logcat with a filename. Be aware that system properties on Android\nhave a very limited number of characters available, so a long path might not be possible to represent.\n```\nsetprop debug.mali.perfdoc.log /sdcard/path/to/log.txt\n```\n\n##### Config file method\n\nAn alternative to setprop is via the config file. This method is a bit more cumbersome than setprop,\nbut might be more convenient if you are already using a config file for other purposes.\n\nPlace a config file on the SD card looking like this:\n\n```\nloggingFilename logcat\n```\n\nor\n\n```\nloggingFilename /sdcard/path/to/log.txt\n```\n\nThen, point the layer to this config file by typing this into adb shell:\n\n```\nsetprop debug.mali.perfdoc.config /sdcard/path/to/perfdoc.cfg\n```\n\nBe careful with permissions however. Not all paths on the SD card can be made visible to an application.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farm-software%2Fperfdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farm-software%2Fperfdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farm-software%2Fperfdoc/lists"}