diff --git a/.gitmodules b/.gitmodules index 66ada3d1c..f5883336a 100644 --- a/.gitmodules +++ b/.gitmodules @@ -20,3 +20,12 @@ [submodule "third_party/perfetto"] path = third_party/perfetto url = https://android.googlesource.com/platform/external/perfetto +[submodule "third_party/gfxreconstruct/external/SPIRV-Headers"] + path = third_party/gfxreconstruct/external/SPIRV-Headers + url = https://github.com/KhronosGroup/SPIRV-Headers.git +[submodule "third_party/gfxreconstruct/external/SPIRV-Reflect"] + path = third_party/gfxreconstruct/external/SPIRV-Reflect + url = https://github.com/KhronosGroup/SPIRV-Reflect.git +[submodule "third_party/gfxreconstruct/external/Vulkan-Headers"] + path = third_party/gfxreconstruct/external/Vulkan-Headers + url = https://github.com/KhronosGroup/Vulkan-Headers.git \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt index a3f37b572..a7b0b2c0d 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -85,6 +85,7 @@ include(perfetto.cmake) add_subdirectory(capture_service) add_subdirectory(layer) + include_directories(${CMAKE_CURRENT_BINARY_DIR}/dive_core) if(NOT ANDROID) @@ -101,6 +102,35 @@ if(NOT ANDROID) if (EXISTS "${CMAKE_SOURCE_DIR}/ui/CMakeLists.txt" AND NOT DIVE_NO_DISASSEMBLY) add_subdirectory(ui) endif() + + add_subdirectory(third_party/gfxreconstruct) +else() + + set(ENV{JAVA_HOME} "/usr/lib/jvm/java-17-openjdk-amd64") + + execute_process( + COMMAND ./gradlew assembleDebug + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/third_party/gfxreconstruct/android + ) + + execute_process( + COMMAND ./gradlew assembleRelease + WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/third_party/gfxreconstruct/android + ) + + file(ARCHIVE_EXTRACT + INPUT "${CMAKE_CURRENT_SOURCE_DIR}/third_party/gfxreconstruct/android/layer/build/outputs/aar/layer-debug.aar" + DESTINATION "${CMAKE_SOURCE_DIR}/build_android/Debug/third_party/gfxreconstruct/android/layer" + ) + + file(ARCHIVE_EXTRACT + INPUT "${CMAKE_CURRENT_SOURCE_DIR}/third_party/gfxreconstruct/android/layer/build/outputs/aar/layer-release.aar" + DESTINATION "${CMAKE_SOURCE_DIR}/build_android/Release/third_party/gfxreconstruct/android/layer" + ) + + file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/third_party/gfxreconstruct/android/tools/replay/build/outputs/apk/debug DESTINATION ${CMAKE_SOURCE_DIR}/build_android/Debug/third_party/gfxreconstruct/android/tools/replay/build/outputs/apk/debug) + + file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/third_party/gfxreconstruct/android/tools/replay/build/outputs/apk/release DESTINATION ${CMAKE_SOURCE_DIR}/build_android/Release/third_party/gfxreconstruct/android/tools/replay/build/outputs/apk/release) endif() option(DIVE_UNIT_TESTS, "Build unit tests for dive") diff --git a/third_party/gfxreconstruct/.clang-format b/third_party/gfxreconstruct/.clang-format new file mode 100644 index 000000000..0a8efd1a5 --- /dev/null +++ b/third_party/gfxreconstruct/.clang-format @@ -0,0 +1,44 @@ +--- +AlignAfterOpenBracket: Align +AlignConsecutiveAssignments: true +AlignConsecutiveDeclarations: true +AlignEscapedNewlines: true +AlignOperands: true +AlignTrailingComments: true +AllowAllParametersOfDeclarationOnNextLine: true +AllowShortCaseLabelsOnASingleLine: false +AllowShortFunctionsOnASingleLine: Inline +AllowShortIfStatementsOnASingleLine: false +AllowShortLoopsOnASingleLine: true +AlwaysBreakTemplateDeclarations: true +BinPackArguments: false +BinPackParameters: false +BreakBeforeBraces: Custom +BraceWrapping: + AfterCaseLabel: true + AfterClass: true + AfterControlStatement: true + AfterEnum: true + AfterExternBlock: true + AfterFunction: true + AfterNamespace: true + AfterStruct: true + AfterUnion: true + BeforeCatch: true + BeforeElse: true + SplitEmptyFunction: false + SplitEmptyRecord: false + SplitEmptyNamespace: false +BreakConstructorInitializers: AfterColon +# Not supported in 6 +#BreakInheritanceList: BeforeColon +Cpp11BracedListStyle: false +ColumnLimit: 120 +IndentCaseLabels: true +IndentWidth: 4 +PointerAlignment: Left +ReflowComments: true +SortIncludes: false +SpaceAfterTemplateKeyword: true +SpaceBeforeParens: ControlStatements +... diff --git a/third_party/gfxreconstruct/.github/ISSUE_TEMPLATE/capture-failure.md b/third_party/gfxreconstruct/.github/ISSUE_TEMPLATE/capture-failure.md new file mode 100644 index 000000000..51677d0e8 --- /dev/null +++ b/third_party/gfxreconstruct/.github/ISSUE_TEMPLATE/capture-failure.md @@ -0,0 +1,36 @@ +--- +name: Capture failure +about: Create a capture bug report to help us improve +title: "[capture] Give one-line summary of issue here" +labels: '' +assignees: '' + +--- + +**Describe the capture bug:** +Describe the issue here. Is it visual corruption? A hang? A performance problem? + +**Build Environment:** +Please include the SHA and PR or branch name used in capture + +**Capture Settings:** +Include any GFXRECON_... environment variables. + +**To Reproduce:** +Provide any steps here to reproduce the behavior beyond starting the program. + +**Screenshots:** +If applicable, add screenshots to illustrate visual corruption. + +**System environment:** + - GPU and driver version on which capture was taken + +**Title configuration:** + - Title name + - Title version + - Steam ID if applicable + - Is DXR enabled? + +**Additional information (optional):** + - is there a SHA for which capture is known to work? (indicates possible regression in encoder) + - Does capture operate correctly on a different GPU or driver version? diff --git a/third_party/gfxreconstruct/.github/ISSUE_TEMPLATE/replay-failure.md b/third_party/gfxreconstruct/.github/ISSUE_TEMPLATE/replay-failure.md new file mode 100644 index 000000000..9b85a3901 --- /dev/null +++ b/third_party/gfxreconstruct/.github/ISSUE_TEMPLATE/replay-failure.md @@ -0,0 +1,43 @@ +--- +name: Replay failure +about: Create a replay bug report to help us improve. +title: "[replay] Give one-line summary of issue here" +labels: '' +assignees: '' + +--- + +**Describe the replay bug:** +Describe the issue here. Is it visual corruption? A hang? A performance problem? + +**Verify before submission:** +* Was trimming enabled? +* Was replayer renamed if necessary? +* Was --sync used if title is known to need forced synchronization? + +**Build Environment:** +Please include the SHA and PR or branch name used in capture and also used to build the replayer. + +**To Reproduce** +Steps to reproduce the behavior: +1. Get the `.gfxr` file from [insert download location here, e.g. LunarShare] +2. Run gfxrecon-replay with [insert parameters here] + +**Screenshots:** +If applicable, add screenshots to illustrate visual corruption. + +**System environment:** + - GPU and driver version on which capture was taken + - GPU and driver version on which capture file was replayed with issue + +**Title configuration:** + - Title name + - Title version + - Steam ID if applicable + - Is DXR enabled? + +**Additional information (optional):** + - is there a SHA for which replayer is known to replay correctly? (indicates possible regression in decoder/consumer) + - Is there an older trace that works? What SHA was used to build those capture DLLs? (indicates possible regression in capture/encoder) + - Does a newer capture work? (indicates bug fix in capture/encoder that needs to be noted) + - Does the capture file replay correctly on a different GPU? diff --git a/third_party/gfxreconstruct/.github/workflows/ci_build.yml b/third_party/gfxreconstruct/.github/workflows/ci_build.yml new file mode 100644 index 000000000..567dfc874 --- /dev/null +++ b/third_party/gfxreconstruct/.github/workflows/ci_build.yml @@ -0,0 +1,255 @@ +name: CI Build + +# Perform CI builds for pull requests targeting the dev branches. + +on: + pull_request: + branches: + - dev + +jobs: + linux: + name: ${{ matrix.config.name }} + runs-on: ${{ matrix.config.os }} + strategy: + fail-fast: false + matrix: + config: + - { + name: "Ubuntu GCC Release", + os: ubuntu-latest, + artifact: "gfxreconstruct-dev-ubuntu-gcc-release", + type: "release", + build_dir: "build", + cc: "gcc", cxx: "g++" + } + - { + name: "Ubuntu GCC Debug", + os: ubuntu-latest, + artifact: "gfxreconstruct-dev-ubuntu-gcc-debug", + type: "debug", + build_dir: "dbuild", + cc: "gcc", cxx: "g++" + } + steps: + - name: Clone repository + uses: actions/checkout@v4 + with: + submodules: 'recursive' + - name: Install build dependencies + run: | + sudo apt-get update + sudo apt-get install -y libx11-xcb-dev libxcb-keysyms1-dev libwayland-dev libxrandr-dev liblz4-dev libzstd-dev + - uses: lukka/get-cmake@latest + with: + cmakeVersion: 3.16.3 + - name: Run build script + run: | + if [ "${{ matrix.config.type }}" == "release" ] + then + clang-format --version # A check for version 9 should be added. + git fetch origin ${{ github.base_ref }} # Fetch target branch to FETCH_HEAD for code style check. + python3 scripts/build.py --config ${{ matrix.config.type }} --check-code-style-base FETCH_HEAD --parallel 0 + python3 framework/generated/generate_vulkan.py # check generated code isn't out of date + git diff --exit-code + else + python3 scripts/build.py --config ${{ matrix.config.type }} --skip-check-code-style --parallel 0 + fi + - name: Prepare artifacts + run: | + cp LICENSE.txt ${{ matrix.config.build_dir }}/linux/x64/output/bin/ + cp LICENSE_ThirdParty.txt ${{ matrix.config.build_dir }}/linux/x64/output/bin/ + cp USAGE_desktop_Vulkan.md ${{ matrix.config.build_dir }}/linux/x64/output/bin/ + cp layer/vk_layer_settings.txt ${{ matrix.config.build_dir }}/linux/x64/output/bin/ + mv ${{ matrix.config.build_dir }}/linux/x64/output/bin gfxreconstruct-dev + mv ${{ matrix.config.build_dir }}/linux/x64/output/lib*/*.so gfxreconstruct-dev/ + mv ${{ matrix.config.build_dir }}/linux/x64/output/share/vulkan/explicit_layer.d/*.json gfxreconstruct-dev/ + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: ${{ matrix.config.artifact }} + path: ./gfxreconstruct-dev + + windows: + name: ${{ matrix.config.name }} + runs-on: ${{ matrix.config.os }} + strategy: + fail-fast: false + matrix: + config: + - { + name: "Windows MSVC Release", + os: windows-latest, + artifact: "gfxreconstruct-dev-windows-msvc-release", + type: "release", + build_dir: "build", + cc: "cl", cxx: "cl" + } + - { + name: "Windows MSVC Debug", + os: windows-latest, + artifact: "gfxreconstruct-dev-windows-msvc-debug", + type: "debug", + build_dir: "dbuild", + cc: "cl", cxx: "cl" + } + steps: + - name: Require Python 3.10 + uses: actions/setup-python@v5 + with: + python-version: '3.10' + - name: Install Ply Python Module + run: pip install ply + - name: Run with VsDevCmd + uses: ilammy/msvc-dev-cmd@v1 + - name: Install SDK 20348 + uses: GuillaumeFalourd/setup-windows10-sdk-action@v2 + with: + sdk-version: 20348 + - name: Set WindowsSDKVersion + run: + echo ("WindowsSDKVersion=10.0.20348.0\") >> $env:GITHUB_ENV + - name: Clone repository from merge of PR branch and dev branch + uses: actions/checkout@v4 + with: + submodules: 'recursive' + - name: Check generated code + run: | + python3 framework/generated/generate_dx12.py # check generated code isn't out of date + git diff --exit-code + - name: Run build script + run: | + python scripts\build.py --skip-check-code-style --config ${{ matrix.config.type }} --parallel 0 + - name: Prepare artifacts + run: | + copy LICENSE.txt ${{ matrix.config.build_dir }}\windows\x64\output\bin\ + copy LICENSE_ThirdParty.txt ${{ matrix.config.build_dir }}\windows\x64\output\bin\ + copy USAGE_desktop_D3D12.md ${{ matrix.config.build_dir }}\windows\x64\output\bin\ + copy USAGE_desktop_Vulkan.md ${{ matrix.config.build_dir }}\windows\x64\output\bin\ + copy layer\vk_layer_settings.txt ${{ matrix.config.build_dir }}\windows\x64\output\bin\ + move ${{ matrix.config.build_dir }}\windows\x64\output\bin gfxreconstruct-dev + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: ${{ matrix.config.artifact }} + path: .\gfxreconstruct-dev + + macOS: + name: ${{ matrix.config.name }} + runs-on: ${{ matrix.config.os }} + strategy: + fail-fast: false + matrix: + config: + - { + name: "macOS Release", + os: macos-latest, + artifact: "gfxreconstruct-dev-macOS-release", + type: "release", + build_dir: "build" + } + - { + name: "macOS Debug", + os: macos-latest, + artifact: "gfxreconstruct-dev-macOS-debug", + type: "debug", + build_dir: "dbuild" + } + steps: + - name: Clone repository + uses: actions/checkout@v4 + with: + submodules: 'recursive' + - name: Cache dependencies + id: cache-deps + uses: actions/cache@v3 + with: + path: ~/deps + key: ${{ matrix.config.os }} deps ${{ hashFiles('.github/workflows/scripts/build-dependencies-macos.sh') }} + - name: Build dependencies + if: steps.cache-deps.outputs.cache-hit != 'true' + run: .github/workflows/scripts/build-dependencies-macos.sh + - name: Run build script + run: | + python3 scripts/build.py --skip-check-code-style --config ${{ matrix.config.type }} --cmake-extra "CMAKE_PREFIX_PATH=$HOME/deps" --cmake-extra CMAKE_OSX_DEPLOYMENT_TARGET=11.0 --parallel 0 + - name: Prepare artifacts + run: | + cp LICENSE.txt ${{ matrix.config.build_dir }}/darwin/universal/output/bin/ + cp LICENSE_ThirdParty.txt ${{ matrix.config.build_dir }}/darwin/universal/output/bin/ + cp USAGE_desktop_Vulkan.md ${{ matrix.config.build_dir }}/darwin/universal/output/bin/ + cp layer/vk_layer_settings.txt ${{ matrix.config.build_dir }}/darwin/universal/output/bin/ + mv ${{ matrix.config.build_dir }}/darwin/universal/output/bin gfxreconstruct-dev + mv ${{ matrix.config.build_dir }}/darwin/universal/output/lib*/*.dylib gfxreconstruct-dev/ + mv ${{ matrix.config.build_dir }}/darwin/universal/output/share/vulkan/explicit_layer.d/*.json gfxreconstruct-dev/ + # GitHub's artifact uploader doesn't preserve permissions, so zip everything ourselves + # This will result in a zip in a zip, but Finder's unzip will conveniently unzip both at once, so it's not too bad + cd gfxreconstruct-dev + zip -r9 "../${{ matrix.config.artifact }}.zip" * + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: ${{ matrix.config.artifact }} + path: ${{ matrix.config.artifact }}.zip + + android: + name: ${{ matrix.config.name }} + runs-on: ${{ matrix.config.os }} + strategy: + fail-fast: false + matrix: + config: + - { + name: "Android Debug", + os: ubuntu-latest, + type: "debug", + artifact: "gfxreconstruct-dev-android-debug" + } + - { + name: "Android Release", + os: ubuntu-latest, + type: "release", + artifact: "gfxreconstruct-dev-android-release" + } + steps: + - name: Clone repository + uses: actions/checkout@v4 + with: + submodules: 'recursive' + - name: Update submodules + run: | + git submodule update --init + - name: Set up Java + uses: "actions/setup-java@v4" + with: + java-version: 17 + distribution: "temurin" + - name: Gradle build + run: | + cd android + if [ "${{ matrix.config.type }}" == "release" ] + then + sh gradlew assembleRelease -Parm64-v8a + else + sh gradlew assembleDebug -Parm64-v8a + fi + - name: Prepare artifacts + run: | + mkdir gfxreconstruct-dev + mkdir gfxreconstruct-dev/layer + mkdir gfxreconstruct-dev/tools + cp LICENSE.txt gfxreconstruct-dev/ + cp LICENSE_ThirdParty.txt gfxreconstruct-dev/ + cp USAGE_android.md gfxreconstruct-dev/ + cp layer/vk_layer_settings.txt gfxreconstruct-dev/ + if [ "${{ matrix.config.type }}" == "release" ] + then + cp -r android/layer/build/intermediates/cxx/RelWithDebInfo/*/obj/arm64-v8a gfxreconstruct-dev/layer/ + else + cp android/tools/replay/build/outputs/apk/debug/replay-debug.apk gfxreconstruct-dev/tools/ + fi + cp android/scripts/gfxrecon.py gfxreconstruct-dev/tools/ + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: ${{ matrix.config.artifact }} + path: ./gfxreconstruct-dev diff --git a/third_party/gfxreconstruct/.github/workflows/release_build.yml b/third_party/gfxreconstruct/.github/workflows/release_build.yml new file mode 100644 index 000000000..4dd8a0ccb --- /dev/null +++ b/third_party/gfxreconstruct/.github/workflows/release_build.yml @@ -0,0 +1,311 @@ +name: Release Build + +# Perform optimized/release builds, create a release, and attach build +# artifacts to the release when a version tag is pushed. +# +# The tag needs to be pushed by name, as `git push --tags` to push all +# tags does not appear to trigger the action. +# +# The versioned release process is similar to the following: +# 1. Add an annotated tag with the release version string. +# git tag -a v0.9.2 +# 2. Draft a message for the annotated tag that is similar to the +# following. The body of this message will serve as the body of the +# release message that is specified when the release is created. +# Release v0.9.2 +# +# Release Highlights +# - Brief description of new item 1. +# - Brief description of new item 2. +# 3. Push the tag to GitHub. +# git push origin v0.9.2 + +on: + push: + tags: + - v[0-9]* + +jobs: + linux: + name: ${{ matrix.config.name }} + runs-on: ${{ matrix.config.os }} + strategy: + fail-fast: false + matrix: + config: + - { + name: "Ubuntu GCC Release", + os: ubuntu-20.04, + artifact: "gfxreconstruct-ubuntu-gcc-release", + cc: "gcc", cxx: "g++" + } + steps: + - name: Clone repository + uses: actions/checkout@v4 + with: + submodules: 'recursive' + - name: Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y libx11-xcb-dev libxcb-keysyms1-dev libwayland-dev libxrandr-dev liblz4-dev libzstd-dev + - name: Run build script + run: | + python3 scripts/build.py --skip-check-code-style --skip-tests --parallel 0 + - name: Prepare artifacts + run: | + cp LICENSE.txt build/linux/x64/output/bin/ + cp LICENSE_ThirdParty.txt build/linux/x64/output/bin/ + cp USAGE_desktop_Vulkan.md build/linux/x64/output/bin/ + cp layer/vk_layer_settings.txt build/linux/x64/output/bin/ + mv build/linux/x64/output/bin gfxreconstruct-dev + mv build/linux/x64/output/lib*/*.so gfxreconstruct-dev/ + mv build/linux/x64/output/share/vulkan/explicit_layer.d/*.json gfxreconstruct-dev/ + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: ${{ matrix.config.artifact }} + path: ./gfxreconstruct-dev + + windows: + name: ${{ matrix.config.name }} + runs-on: ${{ matrix.config.os }} + strategy: + fail-fast: false + matrix: + config: + - { + name: "Windows MSVC Release", + os: windows-latest, + artifact: "gfxreconstruct-windows-msvc-release", + cc: "cl", cxx: "cl" + } + steps: + - name: Clone repository + uses: actions/checkout@v4 + with: + submodules: 'recursive' + - name: Run build script + run: | + python scripts\build.py --skip-check-code-style --skip-tests --parallel 0 + - name: Prepare artifacts + run: | + copy LICENSE.txt build\windows\x64\output\bin\ + copy LICENSE_ThirdParty.txt build\windows\x64\output\bin\ + copy USAGE_desktop_D3D12.md build\windows\x64\output\bin\ + copy USAGE_desktop_Vulkan.md build\windows\x64\output\bin\ + copy layer\vk_layer_settings.txt build\windows\x64\output\bin\ + move build\windows\x64\output\bin gfxreconstruct-dev + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: ${{ matrix.config.artifact }} + path: .\gfxreconstruct-dev + + macOS: + name: ${{ matrix.config.name }} + runs-on: ${{ matrix.config.os }} + strategy: + fail-fast: false + matrix: + config: + - { + name: "macOS Release", + os: macos-latest, + artifact: "gfxreconstruct-macos-release", + type: "release", + build_dir: "build" + } + steps: + - name: Clone repository + uses: actions/checkout@v4 + with: + submodules: 'recursive' + - name: Cache dependencies + id: cache-deps + uses: actions/cache@v3 + with: + path: ~/deps + key: ${{ matrix.config.os }} deps ${{ hashFiles('.github/workflows/scripts/build-dependencies-macos.sh') }} + - name: Build dependencies + if: steps.cache-deps.outputs.cache-hit != 'true' + run: .github/workflows/scripts/build-dependencies-macos.sh + - name: Run build script + run: | + python3 scripts/build.py --skip-check-code-style --skip-tests --config ${{ matrix.config.type }} --cmake-extra "CMAKE_PREFIX_PATH=$HOME/deps" --cmake-extra CMAKE_OSX_DEPLOYMENT_TARGET=11.0 --parallel 0 + - name: Prepare artifacts + run: | + cp LICENSE.txt ${{ matrix.config.build_dir }}/darwin/universal/output/bin/ + cp LICENSE_ThirdParty.txt ${{ matrix.config.build_dir }}/darwin/universal/output/bin/ + cp USAGE_desktop_Vulkan.md ${{ matrix.config.build_dir }}/darwin/universal/output/bin/ + cp layer/vk_layer_settings.txt ${{ matrix.config.build_dir }}/darwin/universal/output/bin/ + mv ${{ matrix.config.build_dir }}/darwin/universal/output/bin gfxreconstruct-dev + mv ${{ matrix.config.build_dir }}/darwin/universal/output/lib*/*.dylib gfxreconstruct-dev/ + mv ${{ matrix.config.build_dir }}/darwin/universal/output/share/vulkan/explicit_layer.d/*.json gfxreconstruct-dev/ + + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: ${{ matrix.config.artifact }} + path: ./gfxreconstruct-dev + + android: + name: ${{ matrix.config.name }} + runs-on: ${{ matrix.config.os }} + strategy: + fail-fast: false + matrix: + config: + - { + name: "Android Release/Debug", + os: ubuntu-latest, + artifact: "gfxreconstruct-android" + } + steps: + - name: Clone repository + uses: actions/checkout@v4 + with: + submodules: 'recursive' + - name: Update submodules + run: | + git submodule update --init + - name: Set up Java + uses: "actions/setup-java@v4" + with: + java-version: 17 + distribution: "temurin" + - name: Gradle build + run: | + cd android + sh gradlew assembleRelease assembleDebug + - name: Prepare artifacts + run: | + mkdir gfxreconstruct-dev + mkdir gfxreconstruct-dev/layer + mkdir gfxreconstruct-dev/tools + cp LICENSE.txt gfxreconstruct-dev/ + cp LICENSE_ThirdParty.txt gfxreconstruct-dev/ + cp USAGE_android.md gfxreconstruct-dev/ + cp layer/vk_layer_settings.txt gfxreconstruct-dev/ + cp -r android/layer/build/intermediates/cxx/RelWithDebInfo/*/obj/arm64-v8a gfxreconstruct-dev/layer/ + cp -r android/layer/build/intermediates/cxx/RelWithDebInfo/*/obj/armeabi-v7a gfxreconstruct-dev/layer/ + cp android/tools/replay/build/outputs/apk/debug/replay-debug.apk gfxreconstruct-dev/tools/ + cp android/scripts/gfxrecon.py gfxreconstruct-dev/tools/ + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: ${{ matrix.config.artifact }} + path: ./gfxreconstruct-dev + + release: + name: Create Release for Tag + runs-on: ubuntu-latest + needs: [ linux, windows, android, macOS ] + steps: + - name: Clone repository + uses: actions/checkout@v4 + with: + submodules: 'recursive' + - name: Get tag body + id: get_tag_body + run: | + # Retrieve the body of the annotated tag's multi-line message and convert it to + # JSON, as an array of strings, with each line of the message as an array element. + tag_name=`echo "${{ github.ref }}" | cut -d "/" -f 3` + tag_body=`git tag -l --format='%(body)' "$tag_name"` + tag_body_json="[" + while read -r line ; do tag_body_json+="\"${line}\"," ; done < <(echo "$tag_body") + tag_body_json="${tag_body_json::-1}]" # Replace the trailing ',' with ']' + echo "::set-output name=tag_body_json::$tag_body_json" + - name: Create release + id: create_release + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: ${{ github.ref }} + release_name: Release ${{ github.ref }} + body: "${{ join(fromJson(steps.get_tag_body.outputs.tag_body_json), '\n') }}" + draft: false + prerelease: false + - name: Get release URL + run: | + echo "${{ steps.create_release.outputs.upload_url }}" > ./release_url + - name: Upload release URL + uses: actions/upload-artifact@v4 + with: + name: release_url + path: ./release_url + + publish: + name: ${{ matrix.config.name }} + runs-on: ${{ matrix.config.os }} + needs: release + strategy: + fail-fast: false + matrix: + config: + - { + name: "Upload Ubuntu Release Artifact", + os: ubuntu-latest, + artifact: "gfxreconstruct-ubuntu-gcc-release", + command: "tar czf", + suffix: "ubuntu-gcc.tar.gz", + type: "application/x-gtar" + } + - { + name: "Upload Windows Release Artifact", + os: ubuntu-latest, + artifact: "gfxreconstruct-windows-msvc-release", + command: "zip -r", + suffix: "windows-msvc.zip", + type: "application/zip" + } + - { + name: "Upload MacOS Release Artifact", + os: ubuntu-latest, + artifact: "gfxreconstruct-macos-release", + command: "tar czf", + suffix: "macos.tar.gz", + type: "application/x-gtar" + } + - { + name: "Upload Android Release Artifact", + os: ubuntu-latest, + artifact: "gfxreconstruct-android", + command: "zip -r", + suffix: "android.zip", + type: "application/zip" + } + steps: + - name: Get tag name + id: get_tag_name + run: | + tag_name=`echo "${{ github.ref }}" | cut -d "/" -f 3` + echo "::set-output name=tag_name::$tag_name" + - name: Download artifacts + uses: actions/download-artifact@v4 + with: + name: ${{ matrix.config.artifact }} + path: ./gfxreconstruct-${{ steps.get_tag_name.outputs.tag_name }} + - name: Make release artifacts + run: | + ${{ matrix.config.command }} gfxreconstruct-${{ steps.get_tag_name.outputs.tag_name }}-${{ matrix.config.suffix }} gfxreconstruct-${{ steps.get_tag_name.outputs.tag_name }} + - name: Download release URL + uses: actions/download-artifact@v4 + with: + name: release_url + path: ./ + - name: Set upload URL + id: set_upload_url + run: | + upload_url=`cat ./release_url` + echo "::set-output name=upload_url::$upload_url" + - name: Upload release artifacts + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.set_upload_url.outputs.upload_url }} + asset_name: gfxreconstruct-${{ steps.get_tag_name.outputs.tag_name }}-${{ matrix.config.suffix }} + asset_path: ./gfxreconstruct-${{ steps.get_tag_name.outputs.tag_name }}-${{ matrix.config.suffix }} + asset_content_type: ${{ matrix.config.type }} diff --git a/third_party/gfxreconstruct/.github/workflows/scripts/build-dependencies-macos.sh b/third_party/gfxreconstruct/.github/workflows/scripts/build-dependencies-macos.sh new file mode 100755 index 000000000..12a28c5cc --- /dev/null +++ b/third_party/gfxreconstruct/.github/workflows/scripts/build-dependencies-macos.sh @@ -0,0 +1,59 @@ +#!/bin/bash + +set -e + +export MACOSX_DEPLOYMENT_TARGET=11.0 + +INSTALLDIR="${INSTALLDIR:-"$HOME/deps"}" +NPROCS="${NPROCS:-$(getconf _NPROCESSORS_ONLN)}" +ZSTD=1.5.5 +LZ4=1.9.4 +ZLIB=1.3.1 + +mkdir deps-build +cd deps-build + +export PKG_CONFIG_PATH="$INSTALLDIR/lib/pkgconfig:$PKG_CONFIG_PATH" +export CFLAGS="-I$INSTALLDIR/include -Os $CFLAGS" +export CXXFLAGS="-I$INSTALLDIR/include -Os $CXXFLAGS" + +cat > SHASUMS < ./release_url + - name: Upload release URL + uses: actions/upload-artifact@v4 + with: + name: release_url + path: ./release_url + + publish: + name: ${{ matrix.config.name }} + runs-on: ${{ matrix.config.os }} + needs: release + strategy: + fail-fast: false + matrix: + config: + - { + name: "Upload Android Release Tar Gzip Artifact", + os: ubuntu-latest, + artifact: "gfxreconstruct-android", + command: "tar czf", + suffix: "android.tar.gz", + type: "application/x-gtar" + } + - { + name: "Upload Android Release Zip Artifact", + os: ubuntu-latest, + artifact: "gfxreconstruct-android", + command: "zip -r", + suffix: "android.zip", + type: "application/zip" + } + steps: + - name: Get tag name + id: get_tag_name + run: | + tag_name=`echo "${{ github.ref }}" | cut -d "/" -f 3` + echo "::set-output name=tag_name::$tag_name" + - name: Download artifacts + uses: actions/download-artifact@v4 + with: + name: ${{ matrix.config.artifact }} + path: ./gfxreconstruct-${{ steps.get_tag_name.outputs.tag_name }} + - name: Make release artifacts + run: | + ${{ matrix.config.command }} gfxreconstruct-${{ steps.get_tag_name.outputs.tag_name }}-${{ matrix.config.suffix }} gfxreconstruct-${{ steps.get_tag_name.outputs.tag_name }} + - name: Download release URL + uses: actions/download-artifact@v4 + with: + name: release_url + path: ./ + - name: Set upload URL + id: set_upload_url + run: | + upload_url=`cat ./release_url` + echo "::set-output name=upload_url::$upload_url" + - name: Upload release artifacts + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.set_upload_url.outputs.upload_url }} + asset_name: gfxreconstruct-${{ steps.get_tag_name.outputs.tag_name }}-${{ matrix.config.suffix }} + asset_path: ./gfxreconstruct-${{ steps.get_tag_name.outputs.tag_name }}-${{ matrix.config.suffix }} + asset_content_type: ${{ matrix.config.type }} diff --git a/third_party/gfxreconstruct/.gitignore b/third_party/gfxreconstruct/.gitignore new file mode 100644 index 000000000..fc4f45766 --- /dev/null +++ b/third_party/gfxreconstruct/.gitignore @@ -0,0 +1,14 @@ +build*/ +dbuild*/ +Debug/ +Release/ +__pycache__/ +.vs/ +.vscode/ +*.db +*.pyc +*.rdbg +._* +.cache +.DS_Store +external/wayland-protocols/ diff --git a/third_party/gfxreconstruct/.gitmodules b/third_party/gfxreconstruct/.gitmodules new file mode 100644 index 000000000..b2ee74512 --- /dev/null +++ b/third_party/gfxreconstruct/.gitmodules @@ -0,0 +1,9 @@ +[submodule "external/Vulkan-Headers"] + path = external/Vulkan-Headers + url = https://github.com/KhronosGroup/Vulkan-Headers.git +[submodule "external/SPIRV-Headers"] + path = external/SPIRV-Headers + url = https://github.com/KhronosGroup/SPIRV-Headers.git +[submodule "external/SPIRV-Reflect"] + path = external/SPIRV-Reflect + url = https://github.com/KhronosGroup/SPIRV-Reflect.git diff --git a/third_party/gfxreconstruct/BUILD.md b/third_party/gfxreconstruct/BUILD.md new file mode 100644 index 000000000..87bffd9ba --- /dev/null +++ b/third_party/gfxreconstruct/BUILD.md @@ -0,0 +1,510 @@ +# Build Instructions + +Instructions for building the GFXReconstruct project source code on Linux, +Windows, and Android platforms. + +[![Creative Commons][1]][2] + +[1]: https://i.creativecommons.org/l/by-nd/4.0/88x31.png "Creative Commons License" +[2]: https://creativecommons.org/licenses/by-nd/4.0/ + +Copyright © 2018-2023 LunarG, Inc. + +## Index + +1. [Introduction](#introduction) +2. [Repository Content](#repository-content) +3. [Repository Set-Up](#repository-set-up) +4. [Windows Build](#building-for-windows) +5. [Linux Build](#building-for-linux) +6. [Android Build](#building-for-android) + +## Introduction + +The following documentation provides end user build instructions for +the GFXReconstruct software. Developers interested in contributing to the +project should also see [CONTRIBUTING.md](CONTRIBUTING.md) for additional +setup instructions. + +## Repository Content + +The GFXReconstruct repository contains the source code for a Vulkan API +capture layer and associated tools for processing captured files. It is +organized with the following file structure: + +| Top Folder | Sub-Folder | Description | +|---|---|---| +| android | | Android build files and script for deploying and launching the replay tool. | +| cmake | | CMake utility files to assist with the build process. | +| external | | Third party components provided as either Git sub-modules or pre-compiled binaries. | +| framework | | Framework library components used to create the capture layer and associated tools.| +| | application | Library providing components to manage replay execution and adapt to different windowing systems. | +| | decode | Library providing components to decode and process GFXR capture file content. | +| | encode | Library providing components to encode and write GFXR capture file content. | +| | format | Library providing utilities and type definitions for the GFXR capture file format. | +| | generated | Python code generators for the Vulkan XML Registry, along with the generated C++ source code to be used for encoding and decoding Vulkan API-related data. | +| | util | Library providing utility functions. | +| layer | | GFXReconstruct capture layer for recording Vulkan API data. | +| tools | | Tools for processing capture files. | +| | compress | Tool to compress or decompress GFXR capture files. | +| | extract | Tool to extract SPIR-V binaries from GFXR capture files. | +| | info | Tool to print information describing GFXR capture files. | +| | replay | Tool to replay GFXR capture files. | +| | convert | Tool to convert GFXR capture files to a JSON Lines listing of API calls. | + +## Repository Set-Up + +### Clone the Repository + +Use the following Git command to create a local copy of the GFXReconstruct +repository: + +```bash +git clone https://github.com/LunarG/gfxreconstruct.git +``` + +### Repository Dependencies + +The GFXReconstruct project has both required and optional dependencies. See +the [External Dependencies README.md](external/README.md) for details regarding +individual dependencies. + +Required dependencies are included with the GFXReconstruct repository as Git +submodules. After cloning the repository, execute the following command +from within the GFXReconstruct project folder to initialize the submodules: + +```bash +git submodule update --init +``` + +Submodules will be updated periodically as the GFXReconstruct project is +updated to support new Vulkan API releases. To obtain submodule updates, +execute the following command from within the GFXReconstruct project folder: + +```bash +git submodule update +``` + +Submodules will need to be updated when the repository status (e.g. +`git status`) shows the submodule folders as having been modified +after a repository update (e.g. `git pull`). + +## Common build instructions + +For desktop builds, there is a Python 3 build script, `scripts/build.py`, that can +be used to update Git submodule dependencies, configure, and build the GFXReconstruct +software. The script works with both Windows and Linux, and requires Python 3.5 or +above. + +A 64 bit ARM Windows build can be achieved on an ARM64 Windows host system with the +following command: + +```bat +python scripts/build.py -a arm64 +``` + +By default, the script performs some optional build steps that are intended for +developer builds. If the target build system has not been configured for +developer builds as described in [CONTRIBUTING.md](CONTRIBUTING.md), the script +can be run with the following options to disable the developer build steps: + +```bash +python scripts/build.py --skip-check-code-style --skip-tests +``` + +The above invocation will run on a single core. +To speed up the build with parallel processes, +the standard CMake environment variable +[`CMAKE_BUILD_PARALLEL_LEVEL`](https://cmake.org/cmake/help/latest/envvar/CMAKE_BUILD_PARALLEL_LEVEL.html) +may be used. +For example, to use eight processes from within Bash: + +```bash +CMAKE_BUILD_PARALLEL_LEVEL=8 python scripts/build.py --skip-check-code-style --skip-tests +``` + +By default, the script builds support for capturing and replaying +Direct3D 12. To omit Direct3D 12 components, specify +`--skip-d3d12-support`. For example: + +```bash +python scripts/build.py --skip-d3d12-support +``` + +Run the script with the `-h` option for additional usage information. + +## Building for Windows + +### Windows Development Environment Requirements + +- Microsoft [Visual Studio](https://www.visualstudio.com/) + - Supported Versions + - [2022](https://www.visualstudio.com/vs/downloads/) + - [2019](https://www.visualstudio.com/vs/older-downloads/) + - [2017](https://www.visualstudio.com/vs/older-downloads/) + - The Community Edition for each of the above versions is sufficient +- [CMake](http://www.cmake.org/download/) (Version 3.16.3 or newer) + - The build instructions assume that CMake has been added to the system PATH +- Git Client Support + - [Git for Windows](http://git-scm.com/download/win) is a popular solution + for Windows + - Some IDEs (e.g., [Visual Studio](https://www.visualstudio.com/), + [GitHub Desktop](https://desktop.github.com/)) have integrated + Git client support + +### Windows Build - Microsoft Visual Studio + +The general approach is to first run CMake to generate the Visual Studio project +files. Then either run CMake with the `--build` option to build from the command +line or use the Visual Studio IDE to open the generated solution and work with the +solution interactively. + +#### Generate Visual Studio Project Files with `CMake` + +Change your current directory to the top level directory for the cloned +GFXReconstruct repository, create a build folder, and generate the Visual +Studio project files. + +The following example demonstrates the generation of project files for the +Visual Studio 2017 x64 build configuration: + +```bat +cd gfxreconstruct +mkdir build +cmake . -Bbuild -G "Visual Studio 15 Win64" +``` + +The following commands can be used to generate project files for different +variations of the Visual Studio 2017 WIN32 and x64 build configurations: + +- 64-bit for VS 2017: `cmake . -Bbuild -G "Visual Studio 15 Win64"` +- 32-bit for VS 2017: `cmake . -Bbuild -G "Visual Studio 15"` + +Running any of the above commands will create a Windows solution file named +`GFXReconstruct.sln` in the build directory. + +Visual Studio configuration will include support for capturing and replaying Direct3D 12 by default. To omit Direct3D 12 components, specify `-DD3D12_SUPPORT=OFF` to cmake. + +At this point, you can build the solution from the command line or open the +generated solution with Visual Studio. + +**Note: The D3D12 build uses Windows 10 SDK 10.0.20348.0. Other Windows SDK versions may not be compatible. If you need to specify a Windows SDK, please use `-DCMAKE_SYSTEM_VERSION=10.0.20348.0`. If Python code generation is required, the shell used to run it should set the environment variable `WindowsSDKVersion=10.0.20348.0`.** + +When generating a native build on an ARM64 Windows host the Visual Studio +Installer can be used to install the required Windows SDK version, `10.0.20348.0`. +Once the correct Windows SDK is installed, from a newly opened developer command +prompt for Visual Studio 2022, the following CMake invocation will generate a Visual +Studio solution and projects. + +```bat +cmake . -Bbuild -G "Visual Studio 17 2022" -A ARM64 -DCMAKE_SYSTEM_VERSION=10.0.20348.0 +``` + +#### Build the Solution From the Command Line + +To build the Debug configuration, run the following command from the build +directory: + +```bat +cmake --build . +``` + +To build the Release configuration, run the following command from the build +directory: + +```bat +cmake --build . --config Release +``` + +#### Build the Solution With Visual Studio + +Launch **Visual Studio** and open the `GFXReconstruct.sln` solution file +from the build folder. You may select "Debug" or "Release" from the Solution +Configurations drop-down list. Start a build by selecting the Build->Build +Solution menu item. + +## Building for Linux + +### Required Package List + +Building on Linux requires the installation of the following packages: + +- A C++ compiler with C++-17 support +- Git +- CMake +- X11 + XCB and/or Wayland development libraries + +#### Ubuntu + +GFXReconstruct is built and tested for SDK development using Ubuntu 20.04 and 22.04. Older Ubuntu releases are unsupported. + +For Ubuntu, the required packages can be installed with the following command: + +```bash +sudo apt-get install git cmake build-essential libx11-xcb-dev libxcb-keysyms1-dev \ + libwayland-dev libxrandr-dev zlib1g-dev liblz4-dev libzstd-dev +``` + +For 32-bit builds (DXVK might require 32-bit): +```bash +sudo apt-get install g++-multilib libx11-xcb-dev:i386 libxcb-keysyms1-dev:i386 \ + libwayland-dev:i386 libxrandr-dev:i386 zlib1g-dev:i386 liblz4-dev:i386 libzstd-dev:i386 +``` + +For arm64 builds (cross compilation): + +```bash +sudo apt-get install g++-aarch64-linux-gnu +``` + +#### Fedora + +For Fedora, the required packages can be installed with the following +command: + +```bash +sudo dnf install git cmake libxcb-devel libX11-devel xcb-util-keysyms-devel \ + libXrandr-devel wayland-devel zlib-devel lz4-devel libzstd-devel g++ +``` + +For arm64 builds (cross compilation): + +```bash +sudo dnf install g++-aarch64-linux-gnu +``` + + +### Linux Build + +The general approach is to run CMake to generate makefiles. Then either run +CMake with the `--build` option or `make` to build from the command line. + +#### Use CMake to Create the Makefiles + +Change your current directory to the top level directory for the cloned +GFXReconstruct repository, create a build folder, and generate the make +files. + +The following example demonstrates makefile generation for a 64-bit Debug build: + +```bash +cd gfxreconstruct +mkdir build +cmake . -Bbuild -DCMAKE_BUILD_TYPE=Debug +``` + +The following commands can be used to generate makefiles for different +variations of Debug and Release, as well as different architectures. +`-DCMAKE_BUILD_TYPE` is used to specify `Debug` or `Release` build +profiles and the `-DCMAKE_TOOLCHAIN_FILE` with a matching toolcain file +can be changed to compile for different architectures: + +- 64-bit x64 Release (default): cmake . -Bbuild -DCMAKE_BUILD_TYPE=Release +- 32-bit x86 Debug: cmake . -Bbuild -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain/linux_x86_32.cmake +- 32-bit x86 Release: cmake . -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain/linux_x86_32.cmake +- 32-bit arm Release: cmake . -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain/linux_arm.cmake +- 64-bit arm Release: cmake . -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain/linux_arm64.cmake + +For 32-bit builds, the 32-bit versions of the required packages specified above +must be installed. + +#### Build the Project + +Run either the `make` or `cmake --build .` command from the build directory +to build the GFXReconstruct project source. + +For faster builds on multi-core systems with `make`, use `make -jN` to +specify the number of jobs that are allowed to run at the same time with +the build. For example: + +```bash +make -j4 +``` + +For build systems that support ccache, it can be enabled with the CMake +`-DUSE_CCACHE=On` option. + +#### Install the project + +Files can be installed to "/usr/local/" with `sudo make install` + +For Linux, the default install directory `/usr/local` can be changed by setting CMake's CMAKE_INSTALL_PREFIX +variable. For example, to install to a "/tmp/gfxreconstruct" directory, run `cmake -DCMAKE_INSTALL_PREFIX=/tmp/gfxreconstruct .` +from gfxreconstruct's root source directory. Then install with `make install`. + + +## Building for MacOS + + +### Required Package List + +Building on MacOS requires the installation of the following packages: + +- Command Line Tools (CLT) for Xcode: + - from `xcode-select --install` + - or https://developer.apple.com/download/all/) + - or [Xcode](https://itunes.apple.com/us/app/xcode/id497799835) +- Git +- CMake + - install e.g. via https://brew.sh/ + +### MacOS Build +The approach is identical to a linux-build with few additions. + +#### Explicit CPU-Architecture +Building for specific cpu-architectures can be accomplished by using the cmake-variable `CMAKE_OSX_ARCHITECTURES` +with values `x86_64` (Intel) or `arm64` (Apple Silicon). +The default behavior is to build only for the architecture present in the build-machine. +A universal build, containing code for both architectures, can be done like this: + +```bash +cd gfxreconstruct +mkdir build +cmake . -Bbuild -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" +cd build +make -j4 +``` + +#### Code signing +Capturing applications that are code-signed will require `libVkLayer_gfxreconstruct.dylib` to be code-signed as well. + +If a signed application tries to load an unsigned layer, an error-message will be issued by the OS: +``` +ERROR: dlopen(/path/to/libVkLayer_gfxreconstruct.dylib, 0x0005): ... +'libVkLayer_gfxreconstruct.dylib' not valid for use in process: mapping process and mapped file (non-platform) have different Team IDs) +``` + +In this case the layer can be signed using the same certificate, allowing it to be loaded at runtime. +This can be achieved with either XCode or via command-line using `Apple's codesign utility`. + +Example usage of Apple's codesign commandline utility: +```bash +# unlock keychain +security unlock-keychain + +# invoke Apple's codesign-utility +codesign --force --timestamp --sign "Your Apple Developer Team ID" -v libVkLayer_gfxreconstruct.dylib + +# optionally print/verify resulting information +codesign -dvvv libVkLayer_gfxreconstruct.dylib` +``` + +Apple's developer information about code-signing can be found here: +https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/Introduction/Introduction.html + +## Building for Android + +### Android Development Requirements + +- The latest version of [Android Studio](https://developer.android.com/studio/) with additional items: + - The [Android Platform tools](https://developer.android.com/studio/releases/platform-tools) for your specific platform + - [Android SDK 33 (13 Tiramisu) or newer](https://guides.codepath.com/android/installing-android-sdk-tools) + - [Android NDK 21.3.6528147 (r21d)](https://developer.android.com/ndk/guides/) +- [Java JDK 17](https://jdk.java.net/17/) + +#### Additional Linux Command-Linux Prerequisites + +Additional requirements for building from the Linux command-line: +- Define `ANDROID_HOME`to be the path to the SDK installed on your system by Android Studio. + - Refer to Android Studio to find out where the files are installed + - **NOTE:** For older Android Studio's you may also have to set `ANDROID_SDK_ROOT` to the same value + - For example: + +```bash + export ANDROID_HOME=$HOME/Android/Sdk +``` + +- Define JAVA_HOME to the path to the directory of the JDK. + - For example: + +```bash + export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 +``` + +### Android Build + +#### Building with Gradle + +Run the following command from the `gfxreconstruct/android` folder to perform a +debug build with Gradle: + +On Windows: + +```bat +gradlew assembleDebug +``` + +On Linux: + +```bash +./gradlew assembleDebug +``` + +To perform a release build, replace the `assembleDebug` task name with `assembleRelease`. + +#### Building with Android Studio + +1. Open Android Studio +2. Choose `Import Project`, browse to the `gfxreconstruct/android` folder, and click `OK`. + - This option is available through either the opening Dialog box or the `File -> New -> Import Project...` menu item + - If import succeeds, the following two project modules will be displayed by the Project browser: + - layer - The GFXReconstruct capture layer for recording Vulkan API data + - replay - The GFXReconstruct tool to replay GFXR capture files +3. Build the project by selecting the `Build -> Make Project` menu item or pressing `Ctrl+F9` + +#### Adding the Layer to Existing Projects + +The GFXReconstruct layer project may be added as a dependency of an existing +Android application project. After the layer has been added as an application +dependency, it will be built when the application is built and automatically +included with the application's APK. A manifest file provided by the +GFXReconstruct layer project will also be merged with the application's +Manifest file, adding `uses-permission` elements for the permissions required +by the layer (e.g. `WRITE_EXTERNAL_STORAGE`). + +To add the GFXReconstruct project as an application dependency, first add the +following lines to the application's `settings.gradle` file, replacing the +`{gfxreconstruct_root}` value with the actual path to the top level +GFXReconstruct project folder: + +```text +include ':VkLayer_gfxreconstruct' +project(':VkLayer_gfxreconstruct').projectDir = file('{gfxreconstruct_root}/android/layer') +``` + +Next, add the following lines to the application's `build.gradle` file: + +```text + dependencies { + implementation project(':VkLayer_gfxreconstruct') + } +``` + +**NOTE:** Make sure it is the app version of `build.gradle` (usually found in an +app folder). +This may not necessarily be the top `build.gradle` in the tree. + +#### Adding the Vulkan Validation Layer to `gfxrecon-replay` + +1. Download the latest Android Vulkan Validation Layer binaries from the [GitHub release page](https://github.com/KhronosGroup/Vulkan-ValidationLayers/releases) +2. Extract the prebuilt layer binaries and include them in the `gfxrecon-replay` APK by adding them to the following directories: +```text +gfxreconstruct/android/tools/replay/src/main/jniLibs/ + arm64-v8a/ + libVkLayer_khronos_validation.so + armeabi-v7a/ + libVkLayer_khronos_validation.so + x86/ + libVkLayer_khronos_validation.so + x86-64/ + libVkLayer_khronos_validation.so +``` +3. Rebuild and deploy `gfxrecon-replay` + +The [Android Vulkan Validation Guide](https://developer.android.com/ndk/guides/graphics/validation-layer) has further instructions for advanced validation layer usage on Android + + +#### Android Detailed Examples + +For more information and detailed examples on building and using GFXReconstruct +on Android can be found in the [HOWTO_android.md](./HOWTO_android.md) document. diff --git a/third_party/gfxreconstruct/CMakeLists.txt b/third_party/gfxreconstruct/CMakeLists.txt new file mode 100644 index 000000000..69505e068 --- /dev/null +++ b/third_party/gfxreconstruct/CMakeLists.txt @@ -0,0 +1,379 @@ +############################################################################### +# Copyright (c) 2018-2023 LunarG, Inc. +# Copyright (c) 2019-2020 Advanced Micro Devices, Inc. +# All rights reserved +# +# 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. +# +# Author: LunarG Team +# Author: AMD Developer Tools Team +# Description: CMake script for framework util target +############################################################################### +cmake_minimum_required(VERSION 3.16.3) +project(GFXReconstruct LANGUAGES CXX) + +set_property(GLOBAL PROPERTY TEST_SCRIPT ${CMAKE_ROOT}) + +include(GNUInstallDirs) + +set(CMAKE_CXX_STANDARD 17) +set(CXX_STANDARD_REQUIRED ON) +set(CMAKE_POSITION_INDEPENDENT_CODE ON) +set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake" "${CMAKE_CURRENT_SOURCE_DIR}/external/cmake-modules") + +# Version info +set(GFXRECONSTRUCT_PROJECT_VERSION_MAJOR 1) +set(GFXRECONSTRUCT_PROJECT_VERSION_MINOR 0) +set(GFXRECONSTRUCT_PROJECT_VERSION_PATCH 5) + +set(GFXRECON_PROJECT_VERSION_SHA1 "unknown-build-source") + + +option(BUILD_STATIC "Build static binaries for HPC clusters (will not build the tracer library)" OFF) + +if (NOT DEFINED HEADLESS) + set(HEADLESS TRUE) +endif() + +include(GetGitRevisionDescription) +get_git_head_revision(GIT_REFSPEC GIT_SHA1) +git_get_exact_tag(GIT_TAG) +set(GIT_BRANCH "") + +if (GIT_REFSPEC) + string(REGEX REPLACE ".*/(.+)$" "\\1" GIT_BRANCH ${GIT_REFSPEC}) + string(COMPARE EQUAL ${GIT_BRANCH} "master" GIT_IS_MASTER) + string(REGEX MATCH "^vulkan-sdk-[0-9]+\.[0-9]+\.[0-9]+$" GIT_IS_SDK ${GIT_BRANCH}) + + if (GIT_IS_MASTER OR GIT_IS_SDK) + if (GIT_TAG) + set(GIT_BRANCH ${GIT_TAG}) + else() + set(GIT_BRANCH "") + endif() + if(NOT DEFINED GFXRECON_PROJECT_VERSION_DESIGNATION) + set(GFXRECON_PROJECT_VERSION_DESIGNATION "") + endif() + elseif(NOT DEFINED GFXRECON_PROJECT_VERSION_DESIGNATION) + set(GFXRECON_PROJECT_VERSION_DESIGNATION "-dev") + endif() +elseif(GIT_TAG) + string(REGEX MATCH "^v[0-9]+\.[0-9]+\.[0-9]+$" GIT_IS_VERSION_RELEASE_TAG ${GIT_TAG}) + if (GIT_IS_VERSION_RELEASE_TAG) + set(GIT_BRANCH ${GIT_TAG}) + set(GFXRECON_PROJECT_VERSION_DESIGNATION "") + endif() +elseif(NOT DEFINED GFXRECON_PROJECT_VERSION_DESIGNATION) + set(GFXRECON_PROJECT_VERSION_DESIGNATION "-unknown") +endif() + +if (GIT_SHA1) + string(SUBSTRING ${GIT_SHA1} 0 7 GFXRECON_PROJECT_VERSION_SHA1) + + if (GIT_BRANCH) + string(CONCAT GFXRECON_PROJECT_VERSION_SHA1 ${GIT_BRANCH} ":" ${GFXRECON_PROJECT_VERSION_SHA1}) + endif() + + git_local_changes(GIT_LOCAL_STATE) + string(COMPARE EQUAL ${GIT_LOCAL_STATE} "DIRTY" GIT_DIRTY) + if (GIT_DIRTY) + string(CONCAT GFXRECON_PROJECT_VERSION_SHA1 ${GFXRECON_PROJECT_VERSION_SHA1} "*") + endif() +endif() + +# Adds all the configure time information into project_version_temp.h.in +configure_file("${CMAKE_CURRENT_SOURCE_DIR}/project_version.h.in" "${CMAKE_BINARY_DIR}/project_version_temp.h.in") + +# Generate a "project_version_$.h" for the current config - necessary to determine the current build configuration +file(GENERATE OUTPUT "${CMAKE_BINARY_DIR}/project_version_$.h" INPUT "${CMAKE_BINARY_DIR}/project_version_temp.h.in") + +# Since project_version_$.h differs per build, set a compiler definition that files can use to include it +add_definitions(-DPROJECT_VERSION_HEADER_FILE="project_version_$.h") + +option(BUILD_WERROR "Build with warnings as errors" ON) + +# Code checks +include("CodeStyle") +include("Lint") +include("Test") +include("FindVulkanVersion") + +# Apply misc build directives to the given target +macro(common_build_directives TARGET) + target_code_style_build_directives(${TARGET}) + target_lint_build_directives(${TARGET}) + add_target_to_test_package(${TARGET}) +endmacro() + +option(GFXRECON_ENABLE_RELEASE_ASSERTS "Enable release builds to output failed conditions caught by GFXRECON_ASSERT macro." OFF) +if(${GFXRECON_ENABLE_RELEASE_ASSERTS}) + add_definitions(-DGFXRECON_ENABLE_RELEASE_ASSERTS) +endif() + +option(GFXRECON_TOCPP_SUPPORT "Build ToCpp export tool as part of GFXReconstruct builds." TRUE) + +if(MSVC) + + # The host toolchain architecture (i.e. are the compiler and other tools compiled to ARM/Intel 32bit/64bit binaries): + message(STATUS "CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE: " ${CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE}) + # The platform name (architecture), we want to build our project for: + # e.g. passed through the commandline -A option: cmake -G "Visual Studio 17 2022" -A ARM64 + message(STATUS "CMAKE_GENERATOR_PLATFORM: " ${CMAKE_GENERATOR_PLATFORM}) + + message(STATUS "CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION: " ${CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION}) + + set(GFXR_ARM_WINDOWS_BUILD FALSE) + if(CMAKE_GENERATOR_PLATFORM STREQUAL "ARM64") + set(GFXR_ARM_WINDOWS_BUILD TRUE) + endif() + + # Default to using the precompiled LZ4 and ZLIB binaries for VisualStudio builds. + set (PRECOMPILED_ARCH "64") + if(CMAKE_SIZEOF_VOID_P EQUAL 4) + set (PRECOMPILED_ARCH "32") + endif(CMAKE_SIZEOF_VOID_P EQUAL 4) + + if(GFXR_ARM_WINDOWS_BUILD) + set (PRECOMPILED_ARCH "64-arm") + endif() + + set(CMAKE_PREFIX_PATH + ${CMAKE_PREFIX_PATH} + "${CMAKE_CURRENT_SOURCE_DIR}/external/precompiled/win${PRECOMPILED_ARCH}" + "${CMAKE_CURRENT_SOURCE_DIR}/external/precompiled/win${PRECOMPILED_ARCH}") + + # Enable LARGEADDRESSAWARE to increase memory address space for 32-bit executables + set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} /LARGEADDRESSAWARE") + + # Add option to enable/disable D3D12 support. + option(D3D12_SUPPORT "Build with Direct3D 12 support enabled" ON) + + # Add option to enable/disable launcher and interceptor. + option(BUILD_LAUNCHER_AND_INTERCEPTOR "Build launcher and interceptor" OFF) + + # Enable STL locks to work after building capture libs with certain versions of VS + add_definitions(-D_DISABLE_CONSTEXPR_MUTEX_CONSTRUCTOR) + + if(${D3D12_SUPPORT}) + set(D3D12_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_SOURCE_DIR}/external/AgilitySDK/inc") + add_definitions(-DD3D12_SUPPORT) + + # Check Windows SDK version and print warning if there is a mismatch. + set(EXPECTED_WIN_SDK_VER "10.0.20348.0") + if (NOT ${CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION} STREQUAL ${EXPECTED_WIN_SDK_VER}) + message(WARNING + "D3D12 support is authored against Windows SDK ${EXPECTED_WIN_SDK_VER}. Windows SDK version " + "${CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION} may not be compatible. If you encounter build errors, " + "set D3D12_SUPPORT=OFF or configure the build with the recommended Windows SDK version. See BUILD.md " + "for more information.") + endif() + + find_package(DXC) + if (DXC_FOUND) + set(D3D12_INCLUDE_DIRECTORIES ${D3D12_INCLUDE_DIRECTORIES} ${DXC_INCLUDE_DIR}) + add_definitions(-DGFXRECON_DXC_SUPPORT) + endif() + + else() + set(BUILD_LAUNCHER_AND_INTERCEPTOR OFF) + endif() + + + if(${BUILD_LAUNCHER_AND_INTERCEPTOR}) + add_definitions(-DBUILD_LAUNCHER_AND_INTERCEPTOR) + endif() + + # Add option to enable/disable AGS support. + option(GFXRECON_AGS_SUPPORT "Build with AGS support enabled. Ignored if D3D12_SUPPORT=OFF." ON) + + if (${D3D12_SUPPORT}) + if (${GFXRECON_AGS_SUPPORT}) + if (CMAKE_SIZEOF_VOID_P EQUAL 8) + find_package(AGS) + if (AGS_FOUND) + add_definitions(-DGFXRECON_AGS_SUPPORT) + + set(D3D12_INCLUDE_DIRECTORIES ${D3D12_INCLUDE_DIRECTORIES} ${AGS_INCLUDE_DIR}) + + # The value for option GFXRECON_AGS_SUPPORT gets cached so use a non-cached variable + # to determine the final result. + set(GFXRECON_AGS_SUPPORT_FINAL ON) + else() + message(WARNING "GFXRECON_AGS_SUPPORT was requested but the required dependencies were not found. " + "AGS support will be disabled.") + endif() # AGS_FOUND + else() + message(WARNING "GFXRECON_AGS_SUPPORT was requested but is not supported. An x64 build is required. " + "AGS support will be disabled.") + endif() # CMAKE_SIZEOF_VOID_P EQUAL 8 + endif() # GFXRECON_AGS_SUPPORT + endif() # D3D12_SUPPORT + +else(MSVC) + # Turn off D3D12 support for non MSVC builds. + set(D3D12_SUPPORT OFF) + set(BUILD_LAUNCHER_AND_INTERCEPTOR OFF) + if(CMAKE_SYSTEM_PROCESSOR STREQUAL "aarch64") + set(CMAKE_PREFIX_PATH + ${CMAKE_PREFIX_PATH} + "${CMAKE_CURRENT_SOURCE_DIR}/external/precompiled/linux/lib/arm64-v8a") + elseif(CMAKE_SYSTEM_PROCESSOR STREQUAL "arm") + set(CMAKE_PREFIX_PATH + ${CMAKE_PREFIX_PATH} + "${CMAKE_CURRENT_SOURCE_DIR}/external/precompiled/linux/lib/arm") + endif() +endif(MSVC) + +if(APPLE) + add_link_options(-Wl,-dead_strip -Wl,-dead_strip_dylibs) + set(CMAKE_PREFIX_PATH + "${CMAKE_CURRENT_SOURCE_DIR}/external/precompiled/macos" + ${CMAKE_PREFIX_PATH}) +endif() + +# GFXReconstruct provided find modules +if(WIN32) +find_package(Detours) +endif() # WIN32 + +option(LZ4_OPTIONAL "Allow building without LZ4-compression" OFF) +find_package(LZ4) + +if(NOT LZ4_FOUND) + if(LZ4_OPTIONAL) + message(STATUS "LZ4 library not found, but declared optional. LZ4 support is disabled.") + else() + message(FATAL_ERROR "LZ4 library not found. Please install LZ4 or allow building without it by setting LZ4_OPTIONAL to ON.") + endif()# LZ4_OPTIONAL +endif()# NOT LZ4_FOUND + +find_package(ZSTD) + +if(MSVC) +find_package(jsoncpp) +endif() # MSVC + +if(UNIX AND NOT APPLE) + option(BUILD_WSI_XCB_SUPPORT "Build XCB WSI support" ON) + option(BUILD_WSI_WAYLAND_SUPPORT "Build Wayland WSI support" ON) + option(BUILD_WSI_DISPLAY_SUPPORT "Build direct-to-display swapchain support" ON) + + if(BUILD_WSI_XCB_SUPPORT) + find_package(XCB) + endif() + + if(BUILD_WSI_WAYLAND_SUPPORT) + find_package(WAYLAND) + endif() +endif(UNIX AND NOT APPLE) + +# CMake provided find modules +if(BUILD_STATIC) + find_library(ZLIB NAMES libz.a REQUIRED PATH_SUFFIXES lib lib/x86_64-linux-gnu lib64) +else() + find_package(ZLIB) +endif() +if(UNIX AND NOT APPLE) + option(BUILD_WSI_XLIB_SUPPORT "Build Xlib WSI support" ON) + if(BUILD_WSI_XLIB_SUPPORT) + find_package(X11) + endif() +endif(UNIX AND NOT APPLE) + +add_library(windows_specific INTERFACE) + +target_compile_definitions(windows_specific INTERFACE + WIN32_LEAN_AND_MEAN + NOMINMAX + VK_USE_PLATFORM_WIN32_KHR + $<$:VK_USE_PLATFORM_HEADLESS> + $<$:"GFXR_INTERCEPTOR_PATH=\"$\""> + $<$:"GFXR_D3D12_CAPTURE_PATH=\"$\""> + $<$:"GFXR_D3D12_PATH=\"$\""> + $<$:"GFXR_DXGI_PATH=\"$\"">) + + +add_library(linux_specific INTERFACE) +target_compile_definitions(linux_specific INTERFACE _FILE_OFFSET_BITS=64 PAGE_GUARD_ENABLE_UCONTEXT_WRITE_DETECTION + $<$:VK_USE_PLATFORM_XLIB_KHR> + $<$:VK_USE_PLATFORM_XLIB_XRANDR_EXT> + $<$:VK_USE_PLATFORM_XCB_KHR> + $<$:VK_USE_PLATFORM_WAYLAND_KHR> + $<$:VK_USE_PLATFORM_DISPLAY_KHR> + $<$:VK_USE_PLATFORM_HEADLESS>) + +add_library(macos_specific INTERFACE) +target_compile_definitions(macos_specific INTERFACE + VK_USE_PLATFORM_METAL_EXT + $<$:VK_USE_PLATFORM_HEADLESS>) + +add_library(platform_specific INTERFACE) +target_link_libraries(platform_specific INTERFACE + $<$:windows_specific> + $<$:macos_specific> + $<$,$>>:linux_specific>) + +if(BUILD_WERROR) + if(MSVC) + target_compile_options(platform_specific INTERFACE /WX) + else() + target_compile_options(platform_specific INTERFACE -Werror) + endif() +endif() + +add_library(vulkan_registry INTERFACE) +target_include_directories(vulkan_registry INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/external/Vulkan-Headers/include) +target_compile_definitions(vulkan_registry INTERFACE VK_NO_PROTOTYPES VK_ENABLE_BETA_EXTENSIONS) + +add_library(spirv_registry INTERFACE) +target_include_directories(spirv_registry INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/external/SPIRV-Headers/include) + +add_library(vulkan_memory_allocator INTERFACE) +target_compile_options(vulkan_memory_allocator INTERFACE + $<$,$>: + -Wno-nullability-completeness> +) +target_include_directories(vulkan_memory_allocator INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/external/VulkanMemoryAllocator/include) + +# SPIRV-Reflect included as submodule -> libspirv-reflect-static.a +set(SPIRV_REFLECT_EXAMPLES OFF) +set(SPIRV_REFLECT_EXECUTABLE OFF) +set(SPIRV_REFLECT_STATIC_LIB ON) +set(CMAKE_POLICY_DEFAULT_CMP0077 NEW) +add_subdirectory(external/SPIRV-Reflect EXCLUDE_FROM_ALL) + +if (${RUN_TESTS}) + add_library(catch2 INTERFACE) + target_include_directories(catch2 INTERFACE external) +endif() + +add_subdirectory(external/nlohmann) +add_subdirectory(framework) +if(NOT BUILD_STATIC) + add_subdirectory(layer) +endif() +add_subdirectory(tools) + +if (${RUN_TESTS}) + add_test_package_file(${CMAKE_CURRENT_LIST_DIR}/scripts/build.py) + add_test_package_file(${CMAKE_CURRENT_LIST_DIR}/scripts/test.py) + generate_test_package(gfx_reconstruct_test) +endif() + +add_subdirectory(scripts) diff --git a/third_party/gfxreconstruct/CONTRIBUTING.md b/third_party/gfxreconstruct/CONTRIBUTING.md new file mode 100644 index 000000000..462f1471f --- /dev/null +++ b/third_party/gfxreconstruct/CONTRIBUTING.md @@ -0,0 +1,495 @@ +# Contributing to the GFXReconstruct Project + +Guidelines for contributing to the GFXReconstruct project. + +[![Creative Commons][1]][2] + +[1]: https://i.creativecommons.org/l/by-nd/4.0/88x31.png "Creative Commons License" +[2]: https://creativecommons.org/licenses/by-nd/4.0/ + +Copyright © 2018-2024 LunarG, Inc. + +## **Index** + +1. [Introduction](#introduction) +1. [License and Copyrights](#license-and-copyrights) +1. [Work In Forks](#work-in-forks) +1. [Creating A Branch For Work](#creating-a-branch-for-work) + 1. [Updating Your Dev Branch](#updating-your-dev-branch) + 1. [Issue Fix](#issue-fix) + 1. [New Feature or Improvement](#new-feature-or-improvement) + 1. [Shared Forks](#shared-forks) +1. [Coding Guidelines](#coding-guidelines) + 1. [GFXR Do's](#gfxr-dos) + 1. [GFXR Don'ts](#gfxr-donts) + 1. [C++ Styling](#c-styling) + 1. [Python Styling](#python-styling) + 1. [Commit Message Format](#commit-message-format) +1. [Testing Changes](#testing-changes) +1. [Before Submission](#before-submission) + 1. [Rebase on Dev](#rebase-on-dev) +1. [Submitting Changes](#submitting-changes) + 1. [Contributor License Agreement](#contributor-license-agreement-cla) +1. [Finishing the PR](#finishing-the-pr) +1. [Platform-specific ClangFormat Installation](#platform-specific-clangformat-installation) + +
+ +## **Introduction** + +Although the GFXReconstruct project is under active development, external +contributions are always welcome. + +Open issues and available tasks can can be found in the project +[issues list](https://github.com/LunarG/gfxreconstruct/issues). + +When working on changes that are not already in the issues list, please +consider creating a new issue to avoid duplication of effort, and +feel free to contact any of the project developers should you wish to +coordinate further. + +Repository Issue labels: + +- _Bug_: These issues refer to invalid or broken functionality and + are the highest priority. +- _Enhancement_: These issues refer to tasks for extending or improving the + GFXReconstruct software. + +If you would like to work on an issue that is already assigned, please coordinate +with the current assignee. + +
+ +## License and Copyrights + +All contributions made to the GFXReconstruct repository are LunarG branded and +as such, any new files **must** have the MIT license and copyright included. +Please see an existing file in this repository for an example. + +You can include your individual copyright after any existing copyrights. + +
+ +## Work In Forks + +For PR development, the GFXReconstruct project does not allow commits +directly into the main repository. + +Instead, all developers are expected to create a +[personal fork](https://help.github.com/articles/fork-a-repo/) of the +`LunarG/gfxreconstruct` repo, commit their changes to that repository during +development, and only when the changes are done should a +[pull request](https://github.com/LunarG/gfxreconstruct/pulls) be created +to pull the source into the main repository. + +After creating the fork, pull down the source and add the original +`LunarG/gfxreconstruct` repo as a remote with the name `upstream`: + +```bash +git remote add upstream git@github.com:LunarG/gfxreconstruct.git +``` + +Adding this `upstream` remote will allow updating your tree with newer +source from the original repo with ease. + +
+ +## Creating A Branch For Work + +GFXR has some guidelines with regards to branch names when performing work. +These guidelines suggest that every branch be named with a clear descriptive +name indicating the purpose of the branch. + +Each branch should be based off of the `dev` branch which is where all active +work is eventually submitted to. + +### Updating Your Dev Branch + +Before creating your branch, it is recommended that you pull down all +recent changes to your fork's `dev` branch from the main repository. + +First, make sure you are in your `dev` branch on your local machine + +```bash +git checkout dev +``` + +Next, fetch all the branch info from the server: + +```bash +git fetch --all --prune +``` + +Then you will need to merge in the changes from the `LunarG/gfxreconstruct` +repository (mine remote pointing to that repo is called `upstream`): + +```bash +git merge upstream/dev +``` + +You may have to update submodules as part of this change if the branch +has update `Vulkan-Headers` or some other important repository. +So to be safe, just re-update all submodules: + +```bash +git submodule update +``` + +Then push your changes to your Github fork: + +```bash +git push origin dev +``` + +Now you can freely create your branch + +### Branch Naming + +Naming your branches a clear name will also help to identify what changes +are present in a branch just by looking at the availabe branches on your +local machine or a remote repo. +Because of this, we suggest naming in the following fashion: + +#### Issue Fix + +If fixing an issue, create a branch based on the issue number, like `fix-1234` +where `1234` is the issue number in Github. + +#### New Feature or Improvement + +If adding a new feature or cleaning up existing changes, provide a descriptive +branch name. + +If the change fixes a race condition in pipeline submit, it could be named +`fix-pipeline-submit-race-condition`. +Even if the name conflicts with another developer's branch, the branch +resides on your fork and appears to the main Github repo as +`(fork):(branch)`. + +#### Shared Forks + +If sharing a fork with multiple people (for example all from the same company), +it might be useful to prepend the branch with your user nam. + +For example, instead of `fix-1234` one might create a branch `bob-fix-1234` +to differentiate the work from other people working in the repo. + +
+ +## Coding Guidelines + +### GFXR Do's + +1. Use `GFXRECON_ASSERT` and not `assert` +2. Explicitly compare pointer values against `nullptr` + For example: `if (pointer_variable == nullptr)` +3. Avoid editing code unrelated to the new functionality or bugfix. + + +### GFXR Don'ts + +1. Don’t hand-edit C++ headers or implementation files in `framework/generated`. + To change those files, edit the Python generator scripts and run the + generator as noted in [Rebase on Dev](#rebase-on-dev) + + +2. Don't perform unnecessary work in your change (like performing additional + cleanup beyond your change). +3. Do not alter existing capture file block structs or IDs. + Instead, create new IDs and structs, and deprecate the old blocks so they + continue to be decoded and consumed. + + * Add a new metacommand to format.h, (e.g. kCreateHardwareBufferCommand2) + * Change capture to write the new metacommand + * Rename the old metacommand to ensure developers writing the command are + notified and add documentation to the file at the deprecated name change. + * Add code to handle the new metacommand on replay + * Add a note to replay of the deprecated metacommand if it indicates + limited or incorrect operation + +### C++ Styling + +Changes to the GFXReconstruct project's C++ code should conform to the coding +style defined by the +[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html). + +C++ Code formatting is managed with a custom ClangFormat configuration file. +This is the `.clang-format` file found at the base of the repo tree. +It is intended for use with **ClangFormat version 9.0.1** (see +[Platform-specific ClangFormat Installation](#platform-specific-clangformat-installation) +for instructions on installing this version for your particular platform) + +C++ code formatting can be applied to pending changes with the `clang-format` + or `git clang-format` commands. + +Here's an example of the workflow using `clang-format` to clean up formating +issues in code changes: + +```bash +# Make changes to the source. + +# Add the changes to git's staging area +$ git add -u . + +# Run clang-format on the files in the staging area +# any changes will appear in the unstaged portion of git +$ git clang-format + +# Check for changes applied by clang-format, and if so: +$ git add -u . + +$ git commit +``` + +#### Verifying Changes with the Build Script + +For desktop, the Python 3 `scripts\build.py` script can be used to verify changes +before they are committed. By default, the script performs a pre-build step to +verify that the formatting of uncommitted changes adheres to the project's +ClangFormat style. + +The build script also has an option to apply `clang-format` to project files +before build. Run the script with the `-h` option for additional usage +information. + + +### Python Styling + +Changes to the GFXReconstruct project's Python code should conform to the +coding style defined by [PEP 8](https://www.python.org/dev/peps/pep-0008/) + +Python code formatting may be automatically applied with +[yapf](https://github.com/google/yapf), based on the rules specified in +the repository's .style.yapf file, using the following command: + +```bash +# Apply formatting to files in place. +$ yapf -i + +# Apply formatting to all python files in this path. +$ yapf -i -r +``` + + +### Commit Message Format + +Keep commit message summary (the first line) to 50 characters and format the +remainder of the message to 72-characters. + +* This allows the information to display correctly in git/Github logs +* Because a 50-character commit summary [works well](https://cbea.ms/git-commit/) + with `git log --oneline --graph` on an 80-column window, e.g.: + + ![Example Commit](docs/img/gfxreconstruct-pr-process-01.png) + +Separate subject from body with a blank line + +* Wrap the body at 72 characters +* Capitalize the subject line +* Do not end the subject line with a period +* Use the body to explain what and why vs. how +* Use the imperative mode in the subject line; this just means to write it + as a command (e.g. `Fix the sprocket`) +* Don't mention any proprietary application titles in the commits + +Strive for commits that implement a single or related set of functionality, +using as many commits as is necessary (more is better). +That said, please ensure that the repository compiles and passes tests without +error for each commit in your pull request. + +Here's an example of a good commit message: + +``` +Fix `OverrideAllocateMemory` for trimmed traces + +When capturing a replay of a capture and `vkAllocateMemory` is called +with `VkMemoryOpaqueCaptureAddressAllocateInfo` already in the `pNext` +chain, the precedent behavior was to "add" another +VkMemoryOpaqueCaptureAddressAllocateInfo` in front of it. +``` + +Of course there are always exceptions. +Prefer clarity in the history over pedantically keeping under limits. + +
+ +## Testing Changes + +To best test any changes, a variety of applications should be captured and +replayed via GFXReconstruct. +If a new feature (or a broken feature) is known to be resolved by the changes +being submitted, attempt to find or create a sample application that +utilizes it appropriately. + +It is recommended to capture and replay one or more Vulkan applications out +of the following repositories: +* VkCube | [Vulkan-Tools Repository](https://github.com/KhronosGroup/Vulkan-Tools) +* One or more samples | [Sascha Willems Vulkan Repository](https://github.com/SaschaWillems/Vulkan) +* One or more samples | [Khronos Vulkan Samples Repostiory](https://github.com/KhronosGroup/Vulkan-Samples) + +If you modified one of the other tools, such as `gfxrecon-info` +or `gfxrecon-convert`, make sure to generate the output and compare before +and after snapshots. + +Verify your changes on whatever OS/platforms you can. + +**NOTE** The automated internal testing will verify on all platforms, but it would be +best for you to do your own verification prior to submitting the changes to reduce +the chance of failed automated testing during PR submission. + +
+ +## Before Submission + +**Do not submit without testing!** + +* Run `git clang-format` and commit the changes and push before making the PR. + (There’s no real danger to the build if you forget; GitHub Actions CI will + fail on the PR until `clang-format` is applied anyway.) +* Squash unnecessary commits + * Squash commits that are simple things (i.e. commits like “apply + clang-format” or “clean up”). + * Squash pairs of commits that introduce a change and revert the change. + * Multiple commits within a single PR are encouraged if the PR contains + multiple sub-functions that make sense to be represented in the Git log. + +### Rebase on Dev + +Since the `dev` branch may have changed since you started your branch, +prior to submission you should update your fork's `dev` branch +(as mentioned in [Updating Your Dev Branch](#updating-your-dev-branch) above). + +Once this is done, rebase your working branch on the updated `dev` branch +and also update submodules just in case: + +```bash +git rebase dev +git submodule update +``` + +If this results in a submodule update and pulls in a new version of the +Vulkan Headers at `external/Vulkan-Headers` or your branch has +touched Python files related to Vulkan code generation, you may need to run the +Python 3 code generator to regenerate some Vulkan component sources. + +To regenerate generated source for Vulkan, `cd` to `framework/generated` and run: + +```bash +python3 generate_vulkan.py +``` + +If you are attempting to update support for the DirectX headers or your +branch has touched Python files related to DirectX code generation, +you may need to run the Python 3 code generator to regenerate some Vulkan +component sources. + +To regenerate generated source for DirectX 12, `cd` to `framework/generated` and run: + +```bash +python3 generate_dx12.py +``` +**NOTE** The minimum supported Python version is 3.10. + +**NOTE** On some systems, e.g. Windows, the Python 3 executable may be named +just `python`. + +
+ +## Submitting Changes + +Changes to the GFXReconstruct project should be made in a branch created off of +the`dev` branch (as mentioned in [Creating a Branch For Work](#creating-a-branch-for-work)). + +When creating a [Pull Request](https://help.github.com/articles/using-pull-requests/): +* Make sure that `base repository` is set to the `LunarG/gfxreconstruct` repository +* Make sure the `base` branch is set to `dev` +* Update the `head repository` to point to your fork +* Update `compare` to point to your branch. + +It should look something like this: + + ![Example PR Creation](docs/img/gfxreconstruct-pr-process-03.png) + +Also make sure the PR title clearly states the purpose of the issue, +like `Fix crash in vulkaninfo` or +`Add tracking for all types derived from Wrapper`. +* If a PR is submitted in order to share and receive comments and run CI + before the PR is submitted for final approvals: + * Add `WIP - ` in front of the title of the PR + * Mark it as `Draft` in Github + +Make sure the description is also clear. +* If it is targeting a specific platform, say which one (`Linux`, `Android`, etc) +* In the case of an issue fix, put the issue number being fixed in the final + commit message or at least in the PR description so the Github issue and PR + are linked, and the issue is updated when the PR is merged. + It has to be a particular phrasing to match the pattern to link the PR with + the issue, like `fixes #341` or `Fixes #341`; see the Github page on this. + +If your change modified something such as `gfxrecon-convert` or `gfxrecon-info`: +* Include a cut-and-paste of output before and after for review. +* Verify that the JSON output validate correctly e.g. through the JSON tool [`jq`](https://stedolan.github.io/jq/) + +### Contributor License Agreement (CLA) + +The first time you submit to the GFXReconstruct repository, you will be +prompted with a one-time "click-through" CLA dialog as part of submitting your +pull request or other contribution to GitHub. + +
+ +## Finishing the PR + +* Did relevant test cases get run by hand against the PR? + * See [Testing Changes](#testing-changes) +* Did Github Workflows CI pass? + * This is the "checks passed" or "checks failed" section at the bottom of the PR + * It represents whether the automated build in a container succeeded. + * This set of “CI builds” includes no replay of capture files. +![Github Workflows CI Screenshot](docs/img/gfxreconstruct-pr-process-02.png "Github Workflows CI Screenshot") +* Did the extended LunarG CI pass? + * LunarG runs additional tests on our own machine and posts the results to the PR. + * This will appear in the `Conversation` part of the PR and appear as comments made. +![LunarG CI Screenshot](docs/img/gfxreconstruct-pr-process-04.png "LunarG CI Screenshot") +* Have you responded and/or resolved all code-review feedback? + +
+ +## Platform-specific ClangFormat Installation + +The following is a collection of notes for obtaining ClangFormat version 9.0.1 +on various platforms. + +### Visual Studio + +- Visual Studio 2019 has built-in support for ClangFormat version 9. +- Visual Studio 2017 has built-in support for an older version of ClangFormat, + but can be changed to use a separately installed ClangFormat version 9 + by following the instructions described here: + - Under **Tools->Options...**, expand **Text Editor > C/C++ > Formatting**. + At the bottom is a checkbox for **Use custom clang-format.exe file**. + Select this, and browse to the location of the 9.0.1 version of + `clang-format.exe` that was installed separately. + +### Ubuntu + +For Ubuntu 20, `clang-format-9` is the default provided by the package manager. + +For earlier versions of Ubuntu, the required version of `clang-format` can be +obtained through the [LLVM toolchain repository](https://apt.llvm.org) by +following the instructions described here: + + +On any version of Ubuntu, continue with: + +```bash +sudo apt update +sudo apt-get install clang-format-9 clang-tidy-9 +``` + +Configure `clang-format` and `clang-tidy` so that the new version is used by default: + +```bash +sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-9 900 +sudo update-alternatives --install /usr/bin/clang-tidy clang-tidy /usr/bin/clang-tidy-9 900 +``` diff --git a/third_party/gfxreconstruct/HOWTO_android.md b/third_party/gfxreconstruct/HOWTO_android.md new file mode 100644 index 000000000..dec043e51 --- /dev/null +++ b/third_party/gfxreconstruct/HOWTO_android.md @@ -0,0 +1,588 @@ + + +

LunarG

+ +[![Creative Commons][1]][2] + +[1]: https://i.creativecommons.org/l/by-nd/4.0/88x31.png "Creative Commons License" +[2]: https://creativecommons.org/licenses/by-nd/4.0/ + +Copyright © 2023 LunarG, Inc. + +# Android Walkthrough + +## Index + +1. [Purpose](#purpose) +2. [Building Vulkan Samples with the Capture Layer](#building-vulkan-samples-with-the-capture-layer) +3. [Capturing Vulkan Samples](#capturing-vulkan-samples) +4. [Capturing Released Application on Rooted System](#capturing-released-application-on-rooted-system) + +## Purpose + +This document shows several examples of how to use the GFXReconstruct tools. +These examples will help work through issues you may discover while attempting +to perform the same process on your own application. + +**NOTE:** +Many of these examples are given based on using a Linux system as the build +and/or host, but you should be able to replicate the behavior on a Windows +system with very few changes. + +## Building Vulkan Samples with the Capture Layer + +Let's look at adding the GFXReconstruct layer as a requirement of the +[Khronos Vulkan Samples](https://github.com/KhronosGroup/Vulkan-Samples) +project. +These steps assume that you have installed all the appropriate dependencies +necessary to build that project. +Please refer to that repository to ensure these dependencies have been +met before continuing. + +### 1. Pull down the GFXReconstruct source + +If you haven't already, pull down the GFXReconstruct source from GitHub so that +it also updates any necessary submodules as part of the clone operation: + +```bash +git clone --recurse-submodules https://github.com/LunarG/gfxreconstruct.git +``` + +The full location of the `gfxreconstruct` folder generated from this step +is to be used in all cases below for `{gfxreconstruct_root}`. + +### 2. Pull down the source for Vulkan Samples + +```bash +git clone --recurse-submodules https://github.com/KhronosGroup/Vulkan-Samples.git +``` + +Alternatively, if this is not the first time the tree is cloned, simply enter +the folder containing the source and update to the latest, but also make sure +that the submodules are re-inited and updated (because additional submodules may +have been added). + +```bash +cd Vulkan-Samples +git pull +git submodule init +git submodule update --recursive +``` + +### 3. Enter the Vulkan Samples source directory + +```bash +cd Vulkan-Samples +``` + +### 4. Build the necessary Android files + +To build/setup the Vulkan-Samples source for Android, follow the instructions in +[the README](https://github.com/KhronosGroup/Vulkan-Samples/blob/main/docs/build.adoc#android) +found in that GitHub repo. + +Follow these instructions up until the instructions to activate the build using +Gradle, and then stop until GFXReconstruct has been enabled. + +In a nutshell, the following command should be executed to generate the +necessary files, but it has been known to change: + +#### Current Vulkan-Samples Android generation + +On a clean tree, the first step is to generate the necessary Android files: + +```bash +python3 scripts/generate.py android +``` + +#### Previous Vulkan-Samples Android generation + +On some older versions of `Vulkan-Samples` the Android files were +generated using a different script: + +```bash +./bldsys/scripts/generate_android_gradle.sh +``` + +### 5. Edit the top-level settings.gradle file + (./build/android_gradle/settings.gradle) + and add the following lines to the end + +```text +include(':app',':VkLayer_gfxreconstruct') +project(':VkLayer_gfxreconstruct').projectDir = file('{gfxreconstruct_root}/android/layer') +``` + +**NOTE**: Replace {gfxreconstruct_root} with the full path location of the +source you cloned from the GFXReconstruct repo in Step 1. + +### 6. Add the capture layer to the samples application + +Open ./build/android_gradle/app/build.gradle and add the following line at the +top of the `dependencies` block at the end of the file: + +```text + implementation project(':VkLayer_gfxreconstruct') +``` + +It should look something like this when you are done: + +```text +dependencies { + implementation project(':VkLayer_gfxreconstruct') + implementation 'androidx.appcompat:appcompat:1.3.0' + implementation 'com.google.android.material:material:1.4.0' + implementation 'androidx.constraintlayout:constraintlayout:2.0.4' +} +``` + +### 7. Change to the appropriate build folder + +From the top-level samples folder you now need to enter the following sub- +folder to build + +```bash +cd build/android_gradle +``` + +### 8. Build the appropriate target + +Some common targets are `assembleDebug` and `assembleRelease`. +We'll build for debug in this scenario: + +```bash +gradle assembleDebug +``` + + +## Capturing Vulkan Samples + +The example that follows uses the Khronos Vulkan Samples built above and assumes +that you built the debug version. +The benefit of building the application in this way is that it will +automatically incorporate the GFXReconstruct capture layer into the .APK file +for the built application. + +### 1. Run Logcat + +```bash +adb logcat -s gfxrecon,vulkan +``` + +### 2. Install the debug version with storage access + +Install the debug version of the samples we just built with the +`-g` option to request storage access: + +```bash +adb install -g ./build/android_gradle/app/build/outputs/apk/debug/vulkan_samples-debug.apk +``` + +This should guarantee that the application (and any associated layers) can +output anything generated. + +### 3. Enable GFXReconstruct + +Enable the GFXReconstruct layer only for the application using the global +settings Android provides: + +```bash +adb shell settings put global enable_gpu_debug_layers 1 +adb shell settings put global gpu_debug_app com.khronos.vulkan_samples +adb shell settings put global gpu_debug_layers "VK_LAYER_LUNARG_gfxreconstruct" +``` + +### 4. Set the capture options + +Now, set the command to capture frames 500-700 so we can see what's happening +and write the file to the `/sdcard/Download` folder: + +```bash +adb shell "setprop debug.gfxrecon.capture_file '/sdcard/Download/samples_capture.gfxr'" +adb shell "setprop debug.gfxrecon.capture_frames '500-700'" +``` + +More capture options can be found in the [USAGE_android.md](./USAGE_android.md) +under the [Capture Options](./USAGE_android.md#capture-options) section. + +### 5. Run the application + +Keep the logcat output in a separate window/terminal so you can monitor it for +any useful information. + +To run the application, look at the application list on the Android device, +then click the `Vulkan Samples` application to launch. +Android may ask you to "Allow access to manage all files." +When asked, enable the option and click the back arrow to get to the +application. + +Once launched, you will see something similar to the following in the `logcat` +window/terminal: + +```text +D vulkan : added global layer 'VK_LAYER_LUNARG_gfxreconstruct' from library '/data/app/~~3mMLAga5cfTsFt19iAcISQ==/com.khronos.vulkan_samples-cwdD6xdzmqmyo6QTZDsjng==/base.apk!/lib/arm64-v8a/libVkLayer_gfxreconstruct.so' +``` + +This message states that it found the GFXReconstruct capture layer in the +base.apk file which we built earlier -- meaning there's no need to add an +additional external layer to any folders. + +Now, click on one of the samples. +In this scenario, let's click on the "Dynamic uniform buffers" test. + +Logcat should show: + +```text +gfxrecon: Finished recording graphics API capture +``` + +Exit the application. + +**NOTE:** +If the application rendered correctly, proceed to Step 6. +If the application rendered incorrectly during the capture, review the guidance +below. + +Running certain Vulkan samples tests results in corruption and requires +additional changes to capture properly. +For example, if you attempted to capture the "Instancing" sample, it will render +without the asteroids. +This is because the GFXReconstruct layer needs some additional settings to +properly align and track the memory. + +First, we will enable page guard on the memory: + +```bash +adb shell "setprop debug.gfxrecon.page_guard_persistent_memory true" +``` + +When this option is enabled, an allocation with a size equal to that of the +object being mapped is made once on the first map and is not freed until the +object is destroyed. +Use this option with applications that frequently map and unmap large memory +ranges -- avoiding frequent allocation and copy operations that can have a +negative impact on performance. + +Next, we will force page guard buffer sizes to be aligned to page size: + +```bash +adb shell "setprop debug.gfxrecon.page_guard_align_buffer_sizes true" +``` + +This option overrides the Vulkan API calls that report buffer memory properties +to report that buffer sizes and alignments must be a multiple of the system page +size. +Use this option with applications that perform CPU writes and GPU writes/copies +to different buffers that are bound to the same page of mapped memory, which may +result in data being lost when copying pages from the `page_guard` shadow +allocation to the real allocation. +This data loss can result in visible corruption during capture. +Forcing buffer sizes and alignments to a multiple of the system page size +prevents multiple buffers from being bound to the same page, avoiding data loss +from simultaneous CPU writes to the shadow allocation and GPU writes to the real +allocation for different buffers bound to the same page. + +After making these changes, re-open the application and re-attempt recapture. + + +### 6. Verify the Capture File + +With `adb logcat` open, look at the output to determine the location to which +the file was recorded. +In my case, the file was recorded to `/sdcard/Download`. +**NOTE**: It actually lists the full file in the message like the following: + +```text +gfxrecon: Recording graphics API capture to /sdcard/Download/gfxrecon_capture_frames_500_through_700_20221211T130328.gfxr +``` + +But, let's say you didn't know, so double check that folder: + +```bash +adb shell ls /sdcard/Download +``` + +The output might look like this: + +```text +gfxrecon_capture_frames_500_through_700_20221211T130328.gfxr +``` + +There's our file right there. + +### 7. Disable The GFXReconstruct layer + +We want to make sure that the layer is not present for any further work we +are going to do. +In this case, we're going to check our replay, so disable any active debug +layers so they don't interfere with the tool. + +```bash +adb shell settings put global enable_gpu_debug_layers 0 +adb shell "settings put global gpu_debug_layers ''" +``` + +### 8. Install the replay application + +Now, we need to install the Replay application that we built as part of the +GFXReconstruct source. +From the top of the source pulled down from the repo by using the +`gfxrecon.py` script: + +```bash +./android/scripts/gfxrecon.py install-apk android/tools/replay/build/outputs/apk/debug/replay-debug.apk +``` + +#### Additional Permissions + +A recent change to enable the replay tool on Android 12 and greater has resulted +in the need of enabling additional permissions on some versions of Android. +This was the result of updating the replay's Android Manifest file to add the +`MANAGE_EXTERNAL_STORAGE` permission flag. + +##### Android 10 + +For replay devices running Android 10, the replay tool now requires the enabling +of legacy storage access: + +```bash +adb shell appops set com.lunarg.gfxreconstruct.replay android:legacy_storage allow +``` + +##### Android 11 and Newer + +For replay devices running Android 11 and newer, the replay tool requires that +the Android permission for `MANAGE_EXTERNAL_STORAGE` be granted either through +the following `adb` command or by clicking on the permission dialog when it +opens up: + +```bash +adb shell appops set com.lunarg.gfxreconstruct.replay MANAGE_EXTERNAL_STORAGE allow +``` + +### 9. Run the replay + +Try running the replay using the `gfxrecon.py` script: + +```bash +./android/scripts/gfxrecon.py replay /sdcard/Download/gfxrecon_capture_frames_500_through_700_20221211T130328.gfxr +``` + +Voila! +It worked, the replay executes properly. + +### 10. Pull down the replay if needed + +If you need to share your replay file, make sure to pull it off of the +device for sharing: + +```bash +adb pull /sdcard/Download/gfxrecon_capture_frames_500_through_700_20221211T130328.gfxr +``` + +## Capturing Released Application On Rooted System + +In this example, we'll capture a set of frames from the GPUScore benchmark. +This set of instructions assume that you have already properly rooted your +device, reinstalled the correct Android image, and installed the target +application (in this case the benchmark). + +### 1. Create an ADB shell with admin capabilities + +```bash +adb shell +su +``` + +We'll refer to this as the admin ADB shell from here on out. + +### 2. Find out full name of application + +In another terminal/command window, run `logcat` to see application messages: + +```bash +adb logcat -s vulkan +``` + +Then run the application and watch for the message with the full name. + +In my case, I see that the full application name is +`com.basemark.gpuscore.sacredpath`. + +Alternatively, you can browse the list of installed applications: + +```bash +adb shell cmd package list packages -3 +``` + +### 3. Find out path for data + +In the admin adb shell, run the following: + +```bash +find /data/app -name *${Full Application Name}* +``` + +Where `${Full Application Name}` is the name we discovered in step 2 above. + +On my system, running `find /data/app -name *com.basemark.gpuscore.sacredpath*` +returned: + +```text +/data/app/~~CklMw7KUY3NvpJa1VxdzCg==/com.basemark.gpuscore.sacredpath-y4DeeR7lnUlvifTr1xSRWA== +``` + +### 4. Copy over the GFXReconstruct capture layer + +In another terminal/command window, change directory to the location of your +GFXReconstruct source. +After building, perform the following command: + +```bash +adb push \ + ./android/layer/build/intermediates/cxx/debug/*/obj/arm64-v8a/libVkLayer_gfxreconstruct.so \ + /storage/emulated/0/Download +``` + +Now, copy it into the application folder discovered in step 3 above using the +admin ADB shell: + +```bash +mv /storage/emulated/0/Download/libVkLayer_gfxreconstruct.so \ + ${Application Data Path}/lib/arm64/libVkLayer_gfxreconstruct.so +``` + +Again, my full command was: + +```bash +mv /storage/emulated/0/Download/libVkLayer_gfxreconstruct.so \ + /data/app/~~CklMw7KUY3NvpJa1VxdzCg==/com.basemark.gpuscore.sacredpath-y4DeeR7lnUlvifTr1xSRWA==/lib/arm64/libVkLayer_gfxreconstruct.so +``` + +Finally, make the capture layer executable: + +```bash +chmod 777 /data/app/~~CklMw7KUY3NvpJa1VxdzCg==/com.basemark.gpuscore.sacredpath-y4DeeR7lnUlvifTr1xSRWA==/lib/arm64/libVkLayer_gfxreconstruct.so +``` + +### 5. Enable the layer for capture + +Several differences versus the non-rooted path include: + * You must enable the layer system wide in this configuration + * You need to disable the Vulkan usage for the UI or it would interfere with + the capture: + +```bash +adb shell "setprop debug.vulkan.layers 'VK_LAYER_LUNARG_gfxreconstruct'" +adb shell "setprop debug.hwui.renderer 'skiagl'" +``` + +### 6. Set GFXReconstruct capture options + +Now, set the command to capture frames 100-200 so we can see what's happening: + +```bash +adb shell "setprop debug.gfxrecon.capture_frames '100-200'" +``` + +And set the output filename to the proper location: + +```bash +adb shell "setprop debug.gfxrecon.capture_file /storage/emulated/0/Download/sacredpath_capture.gfxr" +``` + +We will enable page guard on the memory: + +```bash +adb shell "setprop debug.gfxrecon.page_guard_persistent_memory true" +``` + +When this option is enabled, an allocation with a size equal to that of the +object being mapped is made once on the first map and is not freed until the +object is destroyed. +This option is intended to be used with applications that frequently map and +unmap large memory ranges, to avoid frequent allocation and copy operations that +can have a negative impact on performance. + +Next, we will force page guard buffers are aligned to pages: + +```bash +adb shell "setprop debug.gfxrecon.page_guard_align_buffer_sizes true" +``` + +This option overrides the Vulkan API calls that report buffer memory properties +to report that buffer sizes and alignments must be a multiple of the system page +size. +This option is intended to be used with applications that perform CPU writes and +GPU writes/copies to different buffers that are bound to the same page of mapped +memory, which may result in data being lost when copying pages from the +`page_guard` shadow allocation to the real allocation. +This data loss can result in visible corruption during capture. +Forcing buffer sizes and alignments to a multiple of the system page size +prevents multiple buffers from being bound to the same page, avoiding data loss +from simultaneous CPU writes to the shadow allocation and GPU writes to the real +allocation for different buffers bound to the same page. + +More capture options can be found in the [USAGE_android.md](./USAGE_android.md) +under the [Capture Options](./USAGE_android.md#capture-options) section. + +### 7. Give the application permission to write + +```bash +adb shell pm grant com.basemark.gpuscore.sacredpath android.permission.WRITE_EXTERNAL_STORAGE +``` + +### 8. Run the application + +In my case, I opened up the menu, found the GPUScore application and chose +the official "Sacred Path" benchmark. + +Watching the log output in the above `adb logcat` terminal, I waited until +the benchmark completed and then exited the application. + +I made sure that I saw the following to make sure the recording started: + +```text +I gfxrecon: Recording graphics API capture to /storage/emulated/0/Download/sacredpath_capture_frames_100_through_200_20221215T174939.gfxr +``` + +### 9. Verify the capture file + +Check that the above file exists: + +```bash +adb shell ls /storage/emulated/0/Download/sacredpath_capture_frames*.gfxr +``` + +### 10. Disable the capture layer + +Disable the capture layer globally and also restore the Vulkan usage of the +HWUI: + +```bash +adb shell "setprop debug.vulkan.layers ''" +adb shell "setprop debug.hwui.renderer 'skiavk'" +``` + +### 11. Install the replay application + +Now, we need to install the Replay application that we built as part of the +GFXReconstruct source. +Install the replay APK from the root of the built source tree by using the +`gfxrecon.py` script: + +```bash +./android/scripts/gfxrecon.py install-apk android/tools/replay/build/outputs/apk/debug/replay-debug.apk +``` + +### 12. Run the replay + +Try running the replay using the `gfxrecon.py` script: + +```bash +./android/scripts/gfxrecon.py replay /storage/emulated/0/Download/sacredpath_capture_frames_100_through_200_20221215T174939.gfxr +``` + +**NOTE:** Please refer to [Additional Permissions](#additional-permissions) +above for additional permissions that may need to be enabled to run the +replay application on certain versions of Android. diff --git a/third_party/gfxreconstruct/LICENSE.txt b/third_party/gfxreconstruct/LICENSE.txt new file mode 100644 index 000000000..31daebb1f --- /dev/null +++ b/third_party/gfxreconstruct/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2018-2020 LunarG, Inc. + +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. diff --git a/third_party/gfxreconstruct/LICENSE_ThirdParty.txt b/third_party/gfxreconstruct/LICENSE_ThirdParty.txt new file mode 100644 index 000000000..520ee8cf8 --- /dev/null +++ b/third_party/gfxreconstruct/LICENSE_ThirdParty.txt @@ -0,0 +1,480 @@ +# License Information + +This file contains the license information for third-party software dependencies +of GFXReconstruct. + + +## LZ4 Library + +Copyright (c) 2011-2016, Yann Collet +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, this + list of conditions and the following disclaimer in the documentation and/or + other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +## Vulkan-Headers + +Copyright (c) 2015-2019 The Khronos Group Inc. + +Licensed under the Apache License, Version 2.0 (the "License"). +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + + +## VulkanMemoryAllocator + +Copyright (c) 2017-2020 Advanced Micro Devices, Inc. All rights reserved. + +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. + + +## zlib + + (C) 1995-2017 Jean-loup Gailly and Mark Adler + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. + + +## Zstandard + +Copyright (c) 2016-present, Facebook, Inc. All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + + * Neither the name Facebook nor the names of its contributors may be used to + endorse or promote products derived from this software without specific + prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +## cmake-modules (https://github.com/rpavlik/cmake-modules) + +Copyright Iowa State University 2009-2014, or Copyright Sensics, Inc. 2014-2015, or Copyright Ryan A. Pavlik 2009-2015 + +Distributed under the Boost Software License, Version 1.0. + +(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + + +## CppHeaderParser + +Copyright (C) 2011, Jashua R. Cloutier +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + +* Neither the name of Jashua R. Cloutier nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. Stories, + blog entries etc making reference to this project may mention the + name Jashua R. Cloutier in terms of project originator/creator etc. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN +ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. + +The CppHeaderParser.py script is written in Python 2.4 and released to +the open source community for continuous improvements under the BSD +2.0 new license, which can be found at: + +http://www.opensource.org/licenses/bsd-license.php + + +## Detours + +# Copyright (c) Microsoft Corporation + +All rights reserved. + +# MIT License + +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. + + +## AGS + +# Copyright (c) 2023 Advanced Micro Devices, Inc. All rights reserved. + +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. + + +## Agility SDK (headers) + +Copyright (c) Microsoft Corporation. + +MIT License + +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. + + +## Agility SDK (binaries) + +MICROSOFT SOFTWARE LICENSE TERMS + +MICROSOFT DIRECTX + +These license terms are an agreement between you and Microsoft +Corporation (or one of its affiliates). They apply to the software named +above and any Microsoft services or software updates (except to the +extent such services or updates are accompanied by new or additional +terms, in which case those different terms apply prospectively and do +not alter your or Microsoft’s rights relating to pre-updated software or +services). IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS +BELOW. BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS. + +INSTALLATION AND USE RIGHTS. + +General. Subject to the terms of this agreement, you may install and use any number of copies of the software, and solely for use on Windows. + +Included Microsoft Applications. The software may include other Microsoft applications. These license terms apply to those included applications, if any, unless other license terms are provided with the other Microsoft applications. + +Microsoft Platforms. The software may include components from Microsoft Windows. These components are governed by separate agreements and their own product support policies, as described in the license terms found in the installation directory for that component or in the “Licenses” folder accompanying the software. + +Third Party Components. The software may include third party components with separate legal notices or governed by other agreements, as may be described in the ThirdPartyNotices file(s) accompanying the software. + +DATA. + +Data Collection. The software may collect information about you and your use of the software, and send that to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may opt-out of many of these scenarios, but not all, as described in the product documentation.  There are also some features in the software that may enable you to collect data from users of your applications. If you use these features to enable data collection in your applications, you must comply with applicable law, including providing appropriate notices to users of your applications. You can learn more about data collection and use in the help documentation and the privacy statement at https://aka.ms/privacy. Your use of the software operates as your consent to these practices. + +Processing of Personal Data. To the extent Microsoft is a processor or subprocessor of personal data in connection with the software, Microsoft makes the commitments in the European Union General Data Protection Regulation Terms of the Online Services Terms to all customers effective May 25, 2018, at https://docs.microsoft.com/en-us/legal/gdpr. + +DISTRIBUTABLE CODE. The software may contain code you are permitted to distribute (i.e. make available for third parties) in applications you develop, as described in this Section. + +Distribution Rights. The code and test files described below are distributable if included with the software. + +Distributables. You may copy and distribute the object code form of the software listed in the distributables file list in the software; and + +Third Party Distribution. You may permit distributors of your applications to copy and distribute any of this distributable code you elect to distribute with your applications. + +Distribution Requirements. For any code you distribute, you must: + +add significant primary functionality to it in your applications; + +i. require distributors and external end users to agree to terms that protect it and Microsoft at least as much as this agreement; and + +ii. indemnify, defend, and hold harmless Microsoft from any claims, including attorneys’ fees, related to the distribution or use of your applications, except to the extent that any claim is based solely on the unmodified distributable code. + +Distribution Restrictions. You may not: + +use Microsoft’s trademarks or trade dress in your application in any way that suggests your application comes from or is endorsed by Microsoft; or modify or distribute the source code of any distributable code so that any part of it becomes subject to any license that requires that the distributable code, any other part of the software, or any of Microsoft’s other intellectual property be disclosed or distributed in source code form, or that others have the right to modify it. + +SCOPE OF LICENSE. The software is licensed, not sold. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you will not (and have no right to): + +work around any technical limitations in the software that only allow you to use it in certain ways; + +reverse engineer, decompile or disassemble the software, or otherwise attempt to derive the source code for the software, except and to the extent required by third party licensing terms governing use of certain open source components that may be included in the software; + +remove, minimize, block, or modify any notices of Microsoft or its suppliers in the software; + +use the software in any way that is against the law or to create or propagate malware; or + +share, publish, distribute, or lease the software (except for any distributable code, subject to the terms above), provide the software as a stand-alone offering for others to use, or transfer the software or this agreement to any third party. + +EXPORT RESTRICTIONS. You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users, and end use. For further information on export restrictions, visit https://aka.ms/exporting. + +SUPPORT SERVICES. Microsoft is not obligated under this agreement to provide any support services for the software. Any support provided is “as is”, “with all faults”, and without warranty of any kind. + +UPDATES. The software may periodically check for updates, and download and install them for you. You may obtain updates only from Microsoft or authorized sources. Microsoft may need to update your system to provide you with updates. You agree to receive these automatic updates without any additional notice. Updates may not include or support all existing software features, services, or peripheral devices. + +ENTIRE AGREEMENT. This agreement, and any other terms Microsoft may provide for supplements, updates, or third-party applications, is the entire agreement for the software. + +APPLICABLE LAW AND PLACE TO RESOLVE DISPUTES. If you acquired the software in the United States or Canada, the laws of the state or province where you live (or, if a business, where your principal place of business is located) govern the interpretation of this agreement, claims for its breach, and all other claims (including consumer protection, unfair competition, and tort claims), regardless of conflict of laws principles. If you acquired the software in any other country, its laws apply. If U.S. federal jurisdiction exists, you and Microsoft consent to exclusive jurisdiction and venue in the federal court in King County, Washington for all disputes heard in court. If not, you and Microsoft consent to exclusive jurisdiction and venue in the Superior Court of King County, Washington for all disputes heard in court. + +CONSUMER RIGHTS; REGIONAL VARIATIONS. This agreement describes certain legal rights. You may have other rights, including consumer rights, under the laws of your state or country. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software. This agreement does not change those other rights if the laws of your state or country do not permit it to do so. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you: + +a. Australia. You have statutory guarantees under the Australian + Consumer Law and nothing in this agreement is intended to affect + those rights. + +b. Canada. If you acquired this software in Canada, you may stop + receiving updates by turning off the automatic update feature, + disconnecting your device from the Internet (if and when you + re-connect to the Internet, however, the software will resume + checking for and installing updates), or uninstalling the software. + The product documentation, if any, may also specify how to turn off + updates for your specific device or software. + +c. Germany and Austria. + + i. Warranty. The properly licensed software will perform substantially + as described in any Microsoft materials that accompany the software. + However, Microsoft gives no contractual guarantee in relation to the + licensed software. + + ii. Limitation of Liability. In case of intentional conduct, gross + negligence, claims based on the Product Liability Act, as well as, in + case of death or personal or physical injury, Microsoft is liable + according to the statutory law. + +Subject to the foregoing clause ii., Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in (so-called "cardinal obligations"). In other cases of slight negligence, Microsoft will not be liable for slight negligence. + +DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES, OR CONDITIONS. TO THE EXTENT PERMITTED UNDER APPLICABLE LAWS, MICROSOFT EXCLUDES ALL IMPLIED WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. + +LIMITATION ON AND EXCLUSION OF DAMAGES. IF YOU HAVE ANY BASIS FOR RECOVERING DAMAGES DESPITE THE PRECEDING DISCLAIMER OF WARRANTY, YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U.S. $5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT, OR INCIDENTAL DAMAGES. + +This limitation applies to (a) anything related to the software, +services, content (including code) on third party Internet sites, or +third party applications; and (b) claims for breach of contract, +warranty, guarantee, or condition; strict liability, negligence, or +other tort; or any other claim; in each case to the extent permitted by +applicable law. + +It also applies even if Microsoft knew or should have known about the +possibility of the damages. The above limitation or exclusion may not +apply to you because your state, province, or country may not allow the +exclusion or limitation of incidental, consequential, or other damages. + +Please note: As this software is distributed in Canada, some of the +clauses in this agreement are provided below in French. + +Remarque: Ce logiciel étant distribué au Canada, certaines des clauses +dans ce contrat sont fournies ci-dessous en français. + +EXONÉRATION DE GARANTIE. Le logiciel visé par une licence est offert « +tel quel ». Toute utilisation de ce logiciel est à votre seule risque et +péril. Microsoft n’accorde aucune autre garantie expresse. Vous pouvez +bénéficier de droits additionnels en vertu du droit local sur la +protection des consommateurs, que ce contrat ne peut modifier. La ou +elles sont permises par le droit locale, les garanties implicites de +qualité marchande, d’adéquation à un usage particulier et d’absence de +contrefaçon sont exclues. + +LIMITATION DES DOMMAGES-INTÉRÊTS ET EXCLUSION DE RESPONSABILITÉ POUR LES +DOMMAGES. Vous pouvez obtenir de Microsoft et de ses fournisseurs une +indemnisation en cas de dommages directs uniquement à hauteur de 5,00 $ +US. Vous ne pouvez prétendre à aucune indemnisation pour les autres +dommages, y compris les dommages spéciaux, indirects ou accessoires et +pertes de bénéfices. + +Cette limitation concerne: + +• tout ce qui est relié au logiciel, aux services ou au contenu (y +compris le code) figurant sur des sites Internet tiers ou dans des +programmes tiers; et + +• les réclamations au titre de violation de contrat ou de garantie, ou +au titre de responsabilité stricte, de négligence ou d’une autre faute +dans la limite autorisée par la loi en vigueur. + +Elle s’applique également, même si Microsoft connaissait ou devrait +connaître l’éventualité d’un tel dommage. Si votre pays n’autorise pas +l’exclusion ou la limitation de responsabilité pour les dommages +indirects, accessoires ou de quelque nature que ce soit, il se peut que +la limitation ou l’exclusion ci-dessus ne s’appliquera pas à votre +égard. + +EFFET JURIDIQUE. Le présent contrat décrit certains droits juridiques. +Vous pourriez avoir d’autres droits prévus par les lois de votre pays. +Le présent contrat ne modifie pas les droits que vous confèrent les lois +de votre pays si celles-ci ne le permettent pas. + +## DirectX Shader Compiler - d3d12shader.h + +Copyright (c) Microsoft Corporation. + +MIT License + +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. + +## DirectX Shader Compiler - all other files + +============================================================================== +LLVM Release License +============================================================================== +University of Illinois/NCSA +Open Source License + +Copyright (c) 2003-2015 University of Illinois at Urbana-Champaign. +All rights reserved. + +Developed by: + + LLVM Team + + University of Illinois at Urbana-Champaign + + http://llvm.org + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal with +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: + + * Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimers. + + * Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimers in the + documentation and/or other materials provided with the distribution. + + * Neither the names of the LLVM Team, University of Illinois at + Urbana-Champaign, nor the names of its contributors may be used to + endorse or promote products derived from this Software without specific + prior written permission. + +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 +CONTRIBUTORS 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 WITH THE +SOFTWARE. diff --git a/third_party/gfxreconstruct/README.md b/third_party/gfxreconstruct/README.md new file mode 100644 index 000000000..0e3ae8f61 --- /dev/null +++ b/third_party/gfxreconstruct/README.md @@ -0,0 +1,67 @@ +# Project Components + +The GFXReconstruct project provides tools for the capture and replay of graphics +API calls, allowing the graphics commands executed by an application +to be recorded to a file that may later be replayed to reconstruct the +graphics-specific behavior of the captured application. The replay code has +been organized with a framework design to make it easy to create additional +tools for processing capture files. + +The GFXReconstruct components currently provided with this repository are: + +* The `VK_LAYER_LUNARG_gfxreconstruct` Vulkan layer for capturing + Vulkan application commands. +* The D3D12 capture libraries for capturing D3D12 application commands. +* The `gfxrecon-replay` tool to replay GFXReconstruct capture files. +* The `gfxrecon-info` tool to print information describing GFXReconstruct + capture files. +* The `gfxrecon-compress` tool to compress/decompress GFXReconstruct + capture files. + * **NOTE:** The gfxrecon-compress tool requires LZ4, Zstandard, and/or + zlib, which are currently optional build dependencies. +* The `gfxrecon-extract` tool to extract SPIR-V binaries from + GFXReconstruct capture files. +* The `gfxrecon-convert` tool to convert GFXReconstruct capture files to + a [JSON Lines](https://jsonlines.org/) listing of API calls. (experimental + for D3D12 captures) +* The `gfxrecon-optimize` tool to produce new capture files with + improved replay performance. + + + +## Contributing + +If you intend to contribute, the preferred work flow is for you to develop +your contribution in a fork of this repo in your GitHub account and then +submit a pull request. +Please see the [CONTRIBUTING](CONTRIBUTING.md) file in this repository for +more details + +## Building + +Instructions for building the contents of this repository can be found in +the [BUILD.md](BUILD.md) documentation. + +## Usage + +Instructions for using the GFXReconstruct capture and replay tools can be +found at the following locations: + +* [Desktop Usage - Vulkan](USAGE_desktop_Vulkan.md) +* [Desktop Usage - D3D12](USAGE_desktop_D3D12.md) +* [Android Usage](USAGE_android.md) + +## License + +This work is licensed under the terms of the MIT License; see +[LICENSE](LICENSE.txt) for more information. + +## Appropriate Use + +GFXReconstruct is a suite of tools intended for the purpose of +improving application and platform quality by allowing the analysis +of capture and replay of graphics command streams. Use cases +include, for example, regression testing, silicon and platform +bringup, and reporting bugs. Using GFXReconstruct to extract assets +from an application or game for which you don’t have an appropriate +license may violate copyrights or software licenses. diff --git a/third_party/gfxreconstruct/USAGE_android.md b/third_party/gfxreconstruct/USAGE_android.md new file mode 100644 index 000000000..5324c9f12 --- /dev/null +++ b/third_party/gfxreconstruct/USAGE_android.md @@ -0,0 +1,1074 @@ + + +

LunarG

+ +[![Creative Commons][1]][2] + +[1]: https://i.creativecommons.org/l/by-nd/4.0/88x31.png "Creative Commons License" +[2]: https://creativecommons.org/licenses/by-nd/4.0/ + +Copyright © 2018-2023 LunarG, Inc. + +# GFXReconstruct API Capture and Replay - Android + +***This document describes the GFXReconstruct software for capturing and +replaying Vulkan API calls on Android devices.*** + +If you are looking for capturing/replaying on a different platform, please refer +to one of these other documents: + * [GFXReconstruct for Desktop Vulkan](./USAGE_desktop_Vulkan.md) + * [GFXReconstruct for Desktop D3D12](./USAGE_desktop_D3D12.md) + +## Index + +1. [Capturing API Calls](#capturing-api-calls) + 1. [Before Use](#before-use) + 2. [Enabling the Capture Layer](#enabling-the-capture-layer) + 3. [Capture Options](#capture-options) + 4. [Capture Files](#capture-files) + 6. [Capture Limitations](#capture-limitations) + 7. [Troubleshooting Capturing of Applications](#troubleshooting-capturing-of-applications) +2. [Replaying API Calls](#replaying-api-calls) + 1. [Launch Script](#launch-script) + 2. [Install APK Command](#install-apk-command) + 3. [Replay Command](#replay-command) + 4. [Touch Controls](#touch-controls) + 5. [Key Controls](#key-controls) + 6. [Limitations of Replay On Android](#limitations-of-replay-on-android) + 7. [Troubleshooting Replay of Applications](#troubleshooting-replay-of-applications) + 8. [Dumping resources](#dumping-resources) +3. [Android Detailed Examples](#android-detailed-examples) + + +## Behavior on Android + +The purpose of this section is to describe some of the software changes made to +the GFXReconstruct software to add Android support. +This section will not provide a comprehensive list of changes, but will instead +highlight some of the primary adjustments required to adapt the GFXReconstruct +software to the Android ecosystem. + +### Android Writable Locations + +The contents of the traces should be written to external storage on the +Android device. +The final "external storage" result varies based on Android version but some +locations that can be tried are: + + - `/sdcard/Download` + - `/storage/emulated/0/Download` + - `/sdcard/Android/data/${Application Full Name}` + - `/sdcard` + - `/mnt/shell/emulated/0` + +Where `${Application Full Name}` is the full name of the application, such +as `com.khronos.vulkand_samples`. + +Some devices won't allow access to those folders for certain applications. +In those cases, the following folders can be used, but will require `adb` root +access to retrieve the files: + + - `/data/data/${Application Full Name}/` + - `/data/user/0/${Application Full Name}/` + +**NOTE:** These directories may not be visible to other applications (including +gfxrecon-replay, adb pull), so any capture files will need to be copied to a +readable location with adb shell before they can be replayed. + +## Capturing API Calls + +The GFXReconstruct capture layer is a Vulkan layer that intercepts Vulkan API +calls made by the capture target application and logs them to a GFXReconstruct capture file. + +> [!Note] +> This document uses `${Package Name}` as a placeholder for the full package name +> of a capture target application, such as com.khronos.vulkan_samples. + +### Before Use + +#### Android Writable Locations + +The GFXReconstruct layer, and therefore the capture target application, *must* +have access to the path provided by the `debug.gfxrecon.capture_file` property. +This is typically a location within external storage. The best external storage +path varies based on application and Android version, but some recommended +locations include: + +* `/sdcard/Android/data/${Package Name}` (should not require additional permissions) +* `/sdcard/Download` +* `/sdcard` + +External locations outside of the app-specific directory (first list item) +require that the target capture application have additional storage permissions +as described in the [Android Data Storage](https://developer.android.com/training/data-storage/manage-all-files) +documentation. + +If external storage cannot be used, internal storage may be used instead. While +these locations require no additional permissions, they may require `adb` root +access to retrieve the resulting capture files and/or copy them to a location +that the replay tool can read. + +* `/data/data/${Package Name}/` +* `/data/user/0/${Package Name}/` + +> [!Warning] +>Failure to provide a suitable location for the capture file will cause +>the layer to return `VK_ERROR_INITIALIZATION_FAILED` from its +>`vkCreateInstance` function and produce the following error in logcat: +> +>```text +> E gfxrecon: fopen(/sdcard/gfxrecon_capture.gfxr, wb) failed (errno = 1) +> F gfxrecon: Failed to initialize CaptureManager +>``` + +#### Understanding GFXReconstruct Layer Memory Capture + +The Vulkan API allows Vulkan memory objects to be mapped by an application +for direct modification. +To successfully capture an application, the GFXReconstruct layer must be able to +detect if the application modifies the mapped memory in order to dump the changes +in the capture file so that they can be re-applied while replaying. +To achieve this GFXR utilizes four different modes: + +##### 1. `assisted` +This mode expects the application to call `vkFlushMappedMemoryRanges` +after memory is modified; the memory ranges specified to the +`vkFlushMappedMemoryRanges` call will be written to the capture file +during the call. + +##### 2. `unassisted` +This mode writes the full content of mapped memory to the capture file +on calls to `vkUnmapMemory` and `vkQueueSubmit`. It is very inefficient +for performance and it will bloat capture file sizes. May be unusable +with real-world applications that map large amounts of memory. + +##### 3. `page_guard` +`page_guard` tracks modifications to individual memory pages, which are +written to the capture file on calls to `vkFlushMappedMemoryRanges`, +`vkUnmapMemory`, and `vkQueueSubmit`. This method requires allocating +shadow memory for all mapped memory. The way the changes are being tracked +varies depending on the operating system. +- On Windows `Vectored Exception Handling` mechanism is used on the shadow +memories that correspond to the mapped device memory regions. +- On Linux and Android the shadow memory regions are similarly trapped by +changing its access protection to `PROT_NONE`. Every access from the +application will generate a `SIGSEGV` which is handled by the appropriate +signal handler installed by the page guard manager. + +Because a shadow memory is allocated and returned to the application instead +of the actual mapped memory returned by the driver, both reads and writes need +to be tracked. + +- Writes need to be dumped to the capture file. +- Reads must trigger a memory copy from the actual mapped memory into the shadow +memory so that the application will read the correct/updated data each time. + +`page_guard` is the most efficient, both performance and capture file size +wise, mechanism. However, as described in +[Conflicts With Crash Detection Libraries](#conflicts-with-crash-detection-libraries), +it has some limitation when capturing applications that install their own +signal handler for handling the `SIGSEGV` signal. This limitation exists +only on Linux and Android applications. To work around this +limitation there is the `userfaultfd` mechanism. + +##### 4. `userfaultfd` +This mode utilizes the userfaultfd mechanism provided by the Linux kernel which +allows user space applications to detect and handle page faults. +Under the hood `userfaultfd` is the same mechanism as `page_guard` but instead of trapping +the shadow memory regions with the `PROT_NONE` + `SIGSEGV` trick, it +registers those memory regions for tracking to the userfaultfd mechanism. + +Shadow memory regions are registered using the +`UFFDIO_REGISTER_MODE_WP | UFFDIO_REGISTER_MODE_MISSING` flags with the +userfaultfd mechanism and a handler thread is started and polls for faults +to trigger. The combination of those flags will trigger a fault in two cases: +- When an unallocated page is accessed with either a write or a read. +- When a page is written. + +This imposes a limitation: When the shadow memory is freshly allocated all +pages will be unallocated, making tracking both reads and writes simple as +both will trigger a fault. However, after the first time the accesses are +tracked and dumped to the capture file, the reads cannot be tracked any longer +as the pages will be already allocated and won't trigger a fault. +To workaround this each time the memory is examined, the dirty regions are +being "reset". This involves unregistering those subregions from userfaultfd, +requesting new pages from the OS to be provided at the same virtual addresses +and then the subregions are registered again for tracking. +This has a performance penalty as in this case both reads and writes need +to be copied from the actual mapped memory into the shadow memory when +detected, while the `page_guard` method requires this only for reads. + +Also there is another limitation. The way the new pages are requested each +time and the regions are unregistered and registered again, makes this +mechanism prone to race conditions when there are multiple threads. If a +thread is accessing a specific page within a region and at the same time +that region is being reset, then the access is not trapped and undefined +behavior occurs. + +In order to work around this a list of the thread ids that access each +region is kept. When that specific region is being reset a signal is +sent to each thread which will force them to enter a signal handler that +GFXR registers for that signal. The signal handler essentially performs a +form of synchronization between the thread that is triggering the reset and +the rest of the threads that potentially are touching pages that are being +reset. The signal used one of the real time signals, the first in the range +[`SIGRTMIN`, `SIGRTMAX`] that has no handler already installed. + +`userfaultfd` is less efficient performance wise than `page_guard` but +should be fast enough for real-world applications and games. + +##### Disabling Debug Breaks Triggered by the GFXReconstruct Layer + +When running an application in a debugger with the layer enabled, the +access violations triggered by the layer's memory tracking behavior may +cause the debugger to break. These debug breaks may be disabled for LLDB with +the following command: + +```text +process handle SIGSEGV -n true -p true -s false +``` + +This command may be entered manually through the LLDB tab on Android Studio's +Debug panel. + +It may also be set as a post attach command in the project configuration: + +* Click on "Run" in the menu +* Choose "Edit Configurations..." +* In the dialog box, select the "Debugger" tab +* In the "Debugger" tab, select the "LLDB Post Attach Commands" tab +* Click the `+` to add the command to the command list +* Enter the `process handle SIGSEGV -n true -p true -s false` command +* Click "Apply" + +### Enabling the Capture Layer + +#### Install the Replay APK + +The GFXReconstruct capture layer is included in the replay tool APK. Follow the [Install APK Command](#install-apk-command) instructions to make it available on the target device. + +#### Enable the Layer for a Specific Application + +There are 5 steps to enable the GFXReconstruct capture layer for a capture target application: + + 1. Make sure the target application is debuggable + 2. Enable GPU Debug layers + 3. Indicate what app you are enabling GPU Debug on + 4. Identify the layers used to debug (in this case the layer is `VK_LAYER_LUNARG_gfxreconstruct`) + 5. Indicate what package to load debug layers from (in this case the package is `com.lunarg.gfxreconstruct.replay`) + +Together, the last 4 commands look like the following: + +```bash +adb shell settings put global enable_gpu_debug_layers 1 +adb shell settings put global gpu_debug_app ${Package Name} +adb shell settings put global gpu_debug_layers VK_LAYER_LUNARG_gfxreconstruct +adb shell settings put global gpu_debug_layer_app com.lunarg.gfxreconstruct.replay +``` + +If you attempt to capture and nothing is happening, check the `logcat` output. +A successful run of GFXReconstruct should show a message like the following: + +```text +I gfxrecon: Initializing GFXReconstruct capture layer +``` + +### Capture Options + +The GFXReconstruct layer supports the following options, which may be enabled +through Android system properties or a layer settings file. Each Android +system property begins with the prefix `debug.gfxrecon`, and can be set +through ADB with the following command syntax: + +```bash +adb shell "setprop