Add initial support trickbox layer (#44)

Adds the first version of a trick box layer which can be used to 
experimentally diagnose common problems in applications 
during support investigations.

This version adds configurable workload serialization within 
command buffers, allowing users to diagnose scheduling issues
caused by insufficient pipeline barriers. Queue serialization, will
be added in a follow-on PR.

.github/workflows/build_test.yaml

@@ -61,6 +61,14 @@ jobs:
           cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ..
           make -j4
 
+      - name: Build layer_gpu_support
+        run: |
+          export CXX=clang++
+          mkdir layer_gpu_support/build_rel
+          cd layer_gpu_support/build_rel
+          cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ..
+          make -j4
+
       - name: Build layer_gpu_timeline
         run: |
           export CXX=clang++
@@ -95,6 +103,14 @@ jobs:
           cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ..
           make -j4
 
+      - name: Build layer_gpu_support
+        run: |
+          export CXX=g++
+          mkdir layer_gpu_support/build_rel
+          cd layer_gpu_support/build_rel
+          cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ..
+          make -j4
+
       - name: Build layer_gpu_timeline
         run: |
           export CXX=g++
@@ -117,6 +133,16 @@ jobs:
           cd layer_example
           bash ./android_build.sh Release
 
+      - name: Build layer_gpu_support
+        run: |
+          cd layer_gpu_support
+          bash ./android_build.sh Release
+
+      - name: Build layer_gpu_timeline
+        run: |
+          cd layer_gpu_timeline
+          bash ./android_build.sh Release
+
   build-ubuntu-x64-clang-new-common:
     name: Ubuntu x64 generate common
     runs-on: ubuntu-22.04

.pylintrc

@@ -290,7 +290,7 @@ exclude-too-few-public-methods=
 ignored-parents=
 
 # Maximum number of arguments for function / method.
-max-args=5
+max-args=6
 
 # Maximum number of attributes for a class (see R0902).
 max-attributes=12

layer_gpu_support/CMakeLists.txt

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MIT
+# -----------------------------------------------------------------------------
+# Copyright (c) 2025 Arm Limited
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# -----------------------------------------------------------------------------
+
+cmake_minimum_required(VERSION 3.17)
+
+set(CMAKE_CXX_STANDARD 20)
+
+project(VkLayerGPUSupport VERSION 1.0.0)
+
+# Common configuration
+set(LGL_LOG_TAG "VkLayerGPUSupport")
+set(LGL_CONFIG_TRACE 0)
+set(LGL_CONFIG_LOG 1)
+
+include(../source_common/compiler_helper.cmake)
+
+# Build steps
+add_subdirectory(source)
+add_subdirectory(../source_common/framework source_common/framework)

layer_gpu_support/README_LAYER.md

@@ -0,0 +1,84 @@
+# Layer: GPU Support
+
+This layer is a tech support trick box that is designed to help diagnose causes
+of functional and performance issues in applications. It works by letting you
+quickly test your application with a set of API behavior overrides applied,
+which can help to identify likely problem areas in the application if an
+override causes an issue to disappear.
+
+## Using this layer
+
+This layer requires you to provide a configuration file that specifies the
+overrides to apply. Details of the configuration options in each override
+group are document in the Behavior overrides section below.
+
+The [`layer_config.json`](layer_config.json) file in this directory is a
+complete template configuration file you can start from. However, note that it
+does not enable any overrides by default, so running the layer with this
+configuration used "as is" will not do anything useful. Take a copy and
+modify it to enable the options you want to try.
+
+For Android you can run this layer with the following command line:
+
+```sh
+python3 lgl_android_install.py --layer layer_gpu_support --config <your.json>
+```
+
+## What devices are supported?
+
+This layer is device agnostic and should support any GPU.
+
+## Behavior overrides
+
+The current override groups are supported:
+
+* **Serialization:** control serialization of GPU workload scheduling to
+  diagnose issues caused by missing queue or command stream synchronization.
+
+### Serialization
+
+The serialization overrides allow forceful serialization of submitted
+workloads, ensuring that they run in queue submit order. The synchronization
+can be configured per workload type, allowing control over where serialization
+is added to command buffers and queues.
+
+#### Configuration options
+
+The configuration file allows control over specific options, as well as
+convenience options to force disable or enable all serialization.
+
+* If the `none` option is `true` then no serialization is applied, irrespective
+of other settings.
+* Else, if the `all` option is `true` then all serialization is applied,
+irrespective of other settings.
+* Else, the individual options are applied as specified.
+
+```jsonc
+"serialize": {
+    "none": false,          // Enable no serialization options
+    "all": false,           // Enable all serialization options
+    "queue": false,         // Enable cross-queue serialization of submits
+    "commandstream": {
+        "compute": {
+            "pre": false,   // Insert full barrier before dispatches
+            "post": false   // Insert full barrier after dispatches
+        },
+        "renderpass": {
+            "pre": false,   // Insert full barrier before render passes
+            "post": false   // Insert full barrier after render passes
+        },
+        "tracerays": {
+            "pre": false,   // Insert full barrier before trace rays
+            "post": false   // Insert full barrier after trace rays
+        },
+        "transfer": {
+            "pre": false,   // Insert full barrier before transfers
+            "post": false   // Insert full barrier after transfers
+        }
+    }
+}
+```
+
+- - -
+
+_Copyright © 2025, Arm Limited and contributors._

layer_gpu_support/android_build.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MIT
+# ----------------------------------------------------------------------------
+# Copyright (c) 2024 Arm Limited
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+# ----------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------
+# Configuration
+
+# Exit immediately if any component command errors
+set -e
+
+BUILD_DIR_64=build_arm64
+BUILD_DIR_PACK=build_package
+
+# ----------------------------------------------------------------------------
+# Process command line options
+if [ "$#" -lt 1 ]; then
+    BUILD_TYPE=Release
+else
+    BUILD_TYPE=$1
+fi
+
+# Process command line options
+if [ "$#" -lt 2 ]; then
+    PACKAGE=0
+else
+    PACKAGE=$2
+fi
+
+if [ "${PACKAGE}" -gt "0" ]; then
+    echo "Building a ${BUILD_TYPE} build with packaging"
+else
+    echo "Building a ${BUILD_TYPE} build without packaging"
+fi
+
+# ----------------------------------------------------------------------------
+# Build the 64-bit layer
+mkdir -p ${BUILD_DIR_64}
+pushd ${BUILD_DIR_64}
+
+cmake \
+    -DCMAKE_SYSTEM_NAME=Android \
+    -DANDROID_PLATFORM=29 \
+    -DANDROID_ABI=arm64-v8a \
+    -DANDROID_TOOLCHAIN=clang \
+    -DANDROID_STL=c++_static \
+    -DCMAKE_BUILD_TYPE=${BUILD_TYPE} \
+    -DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK_HOME}/build/cmake/android.toolchain.cmake" \
+    ..
+
+make -j1
+
+popd
+
+# ----------------------------------------------------------------------------
+# Build the release package
+if [ "${PACKAGE}" -gt "0" ]; then
+    # Setup the package directories
+    mkdir -p ${BUILD_DIR_PACK}/bin/android/arm64
+
+    # Install the 64-bit layer
+    cp ${BUILD_DIR_64}/source/*.so ${BUILD_DIR_PACK}/bin/android/arm64
+fi

layer_gpu_support/android_install.json

@@ -0,0 +1,5 @@
+{
+    "layer_name": "VK_LAYER_LGL_GPUSUPPORT",
+    "layer_binary": "libVkLayerGPUSupport.so",
+    "has_config": true
+}

layer_gpu_support/layer_config.json

@@ -0,0 +1,26 @@
+{
+    "layer": "VK_LAYER_LGL_GPUSUPPORT",
+    "serialize": {
+        "all": false,
+        "none": false,
+        "commandstream": {
+            "compute": {
+                "pre": false,
+                "post": false
+            },
+            "renderpass": {
+                "pre": false,
+                "post": false
+            },
+            "tracerays": {
+                "pre": false,
+                "post": false
+            },
+            "transfer": {
+                "pre": false,
+                "post": false
+            }
+        },
+        "queue": false
+    }
+}

layer_gpu_support/source/CMakeLists.txt

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: MIT
+# -----------------------------------------------------------------------------
+# Copyright (c) 2025 Arm Limited
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+# -----------------------------------------------------------------------------
+
+# Set output file names
+if (CMAKE_BUILD_TYPE STREQUAL "Release")
+    set(VK_LAYER VkLayerGPUSupport_sym)
+    set(VK_LAYER_STRIP libVkLayerGPUSupport.so)
+else()
+    set(VK_LAYER VkLayerGPUSupport)
+endif()
+
+# Set strings used by configure
+set(LGL_LAYER_NAME_STR "VK_LAYER_LGL_GPUSUPPORT")
+set(LGL_LAYER_DESC_STR "VkLayerGPUSupport by LGL")
+
+# Vulkan layer library
+configure_file(
+    version.hpp.in
+    version.hpp
+    ESCAPE_QUOTES @ONLY)
+
+add_library(
+    ${VK_LAYER} SHARED
+        ${PROJECT_SOURCE_DIR}/../source_common/framework/entry.cpp
+        device.cpp
+        instance.cpp
+        layer_config.cpp
+        layer_device_functions_dispatch.cpp
+        layer_device_functions_queue.cpp
+        layer_device_functions_render_pass.cpp
+        layer_device_functions_trace_rays.cpp
+        layer_device_functions_transfer.cpp)
+
+target_include_directories(
+    ${VK_LAYER} PRIVATE
+        ${PROJECT_SOURCE_DIR}/../source_common
+        ${CMAKE_CURRENT_BINARY_DIR}
+        .)
+
+target_include_directories(
+    ${VK_LAYER} SYSTEM PRIVATE
+        ${PROJECT_SOURCE_DIR}/../source_third_party
+        ${PROJECT_SOURCE_DIR}/../khronos/vulkan/include)
+
+lgl_set_build_options(${VK_LAYER})
+
+target_link_libraries(
+    ${VK_LAYER}
+        lib_layer_framework
+        $<$<PLATFORM_ID:Android>:log>)
+
+if (CMAKE_BUILD_TYPE STREQUAL "Release")
+    add_custom_command(
+        TARGET "${VK_LAYER}" POST_BUILD
+        DEPENDS "${VK_LAYER}"
+        COMMAND ${CMAKE_STRIP}
+        ARGS --strip-all -o ${VK_LAYER_STRIP} $<TARGET_FILE:${VK_LAYER}>
+        COMMENT "Stripped lib${VK_LAYER}.so to ${VK_LAYER_STRIP}")
+endif()