Skip to content

Latest commit

 

History

History
145 lines (103 loc) · 4.45 KB

building.md

File metadata and controls

145 lines (103 loc) · 4.45 KB

Creating a new layer

Layer skeleton code is generated from the Khronos specification XML, allowing new layers to be quickly built based on the latest specifications.

The code for a layer is split into two parts, which are generated separately.

  • Common code provides the dispatch framework which intercept all entrypoints, and then forwards these to an appropriate handler. The common code provides a default pass-through handler for each API entrypoint.
  • User code provides layer-specific implementations of function intercepts and can extend the generated Device and Instance classes with whatever additional stateful persistence is needed to implement the layer.

Checking out the code

From the directory you want to contain the code, check out the project and all third-party dependencies:

git clone https://github.com/ARM-software/libGPUlayers ./
git submodule update --init

Generate the common code

The common code is checked into the repository, and should not need regenerating unless you need to use a newer version of the specification.

Update the version of the Vulkan specification by updating the git version of the khronos/vulkan submodule.

Once updated, regenerate the common code using the Python script:

python3 ./generator/generate_vulkan_common.py

Generate the layer skeleton

To create a new layer, use the Python script to generate a layer driver skeleton for it. Replace the placeholder "Demo" with your layer name.

python3 ./generator/generate_vulkan_layer.py --project-name VkLayerDemo --output layer_demo

The Vulkan layer name must start with VkLayer and have a title-case name, e.g. VkLayerExampleName.

The output directory name should start with layer_ and have a snake-case name, e.g. layer_example_name.

The output directory must be in the root directory of the git checkout, making it a sibling of the source_common directory. This ensures that autogenerated CMake include paths work correctly.

Note: The skeleton layer does nothing other than intercept all of the Vulkan API entry points and forward them to the next layer/driver in the stack. You must edit the skeleton source code to make it do something useful ...

Adding custom intercepts to your layer

Custom intercept functions are implemented in your layer source tree. We use C++ template tag dispatch in the common code to automatically select the specialized function implemented in the layer code, falling back to the common default version if no specialization is available.

Instance function intercepts must be declared in a header called layer_instance_functions.hpp in the layer source directory.

Device function intercepts must be declared in a header called layer_device_functions.hpp in the layer source directory.

The function prototypes for a layer implementation must be templated versions of the normal Vulkan prototype, with the type <user_tag> used for the template specialization.

template <>
VKAPI_ATTR void VKAPI_CALL layer_vkDestroyInstance<user_tag>(
    VkInstance instance,
    const VkAllocationCallbacks* pAllocator);

Build an Android layer

These build instructions require the following tools to be installed and added to your environment PATH:

  • CMake
  • GNU Make

The Android NDK must also be installed, and the path to the root of the NDK installation must be stored in your ANDROID_NDK_HOME environment variable.

cd <your_layer>

cmake \
  -B <your_build_dir> \
  -G "Unix Makefiles" \
  -DCMAKE_SYSTEM_NAME=Android \
  -DANDROID_PLATFORM=29 \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_TOOLCHAIN=clang \
  -DANDROID_STL=c++_static \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK_HOME}/build/cmake/android.toolchain.cmake"

cmake --build <your_build_dir>

CMake builds are build system agnostic. You can replace GNU Make with another build system, such as Ninja, if that is preferred.

An Android build script for Linux hosts, ./android_build.sh, is provided as a convenience wrapper for the above commands. It is not required to use this; it is primarily included to provide a one-line build for our CI test system.

Build a Linux layer

These build instructions require the following tools to be installed and added to your environment PATH:

  • CMake
  • GNU Make
cd <your_layer>

cmake \
  -B <your_build_dir> \
  -G "Unix Makefiles" \
  -DCMAKE_BUILD_TYPE=Release \
  ..

cmake --build <your_build_dir>

Copyright © 2024-2025, Arm Limited and contributors.