AMDVLK

适用于 Vulkan® 的 AMD 开源驱动程序

AMD Open Source Driver for Vulkan® 是适用于 Linux® 上 Radeon™ 图形适配器的开源 Vulkan 驱动程序。它构建在 AMD 的平台抽象库 (PAL) 之上，这是一个共享组件，旨在封装许多 AMD 3D 和计算驱动程序的某些硬件和操作系统特定的编程细节。利用 PAL 有助于提供跨平台的一致体验，包括对最近发布的 GPU 的支持以及与 AMD 开发人员工具的兼容性。

组成特定VkPipeline对象的着色器使用基于 LLVM 的管道编译器 (LLPC) 库编译为单个实体。 LLPC 构建在 LLVM 现有的 AMD GPU 着色器编译基础设施之上，以生成与 PAL 管道 ABI 兼容的代码对象。值得注意的是，AMD的闭源Vulkan驱动目前使用不同的管道编译器，这是AMD开源和闭源Vulkan驱动之间的主要区别。

产品支持

适用于 Vulkan 的 AMD 开源驱动程序旨在支持以下 AMD GPU：

• Radeon™ RX 7900/7800/7700/7600 系列
• Radeon™ RX 6900/6800/6700/6600/6500 系列
• Radeon™ RX 5700/5600/5500 系列
• Radeon™ Pro W5700/W5500 系列

注意对于 GFX10 之前的 GPU，请使用 v-2023.Q3.3 或更早版本。

操作系统支持

适用于 Vulkan 的 AMD 开源驱动程序旨在支持 AMDGPU 上游驱动程序堆栈和 AMDGPU Pro 驱动程序堆栈上的以下发行版和版本：

• Ubuntu 24.04（amd64版本）
• Ubuntu 22.04（amd64版本）
• RedHat 8.6（x86-64 版本）
• RedHat 9.0（x86-64 版本）

该驱动程序尚未在其他发行版和版本上经过良好的测试。您可以在您选择的其他发行版和版本上尝试一下。

注意要在 SI 和 CI 代 GPU 上运行具有 AMDGPU 上游驱动程序堆栈的 Vulkan 驱动程序，需要在内核中启用 amdgpu.si_support 和 amdgpu.cik_support

功能支持和性能

适用于 Vulkan 的 AMD 开源驱动程序旨在支持以下功能：

• 伏尔甘1.3
• 超过 170 个扩展
• Radeon™ GPUProfiler 跟踪
• 内置调试和分析工具
• 中间命令缓冲区抢占和 SR-IOV 虚拟化

未来版本计划实现以下功能和改进（各版本更新请参阅版本说明）：

• Vulkan API 的即将推出的版本
• 通过 RenderDoc 收集硬件性能计数器
• LLPC 优化可提高 GPU 限制的性能和编译时间
• 优化以提高 CPU 限制的性能

已知问题

• 如果您使用上游堆栈，则可能需要从 https://git.kernel.org/pub/scm/ 将内核升级到 5.3 或更高版本，并将固件（在 /lib/firmware/amdgpu/ 下）升级到正确的版本linux/kernel/git/firmware/linux-firmware.git/tree/amdgpu，然后更新 ramfs (sudo mkinitramfs -o /boot/initrd.img- uname -r uname -r或 sudo mkinitcpio --generate /boot/initrd .img- uname -r uname -r )
• Linux 内核直到版本 5.5 才完全支持时间轴信号量。如果您使用的是早期版本的 Linux 内核，您可以安装 Vulkan 时间线信号量层来启用扩展

如何贡献

欢迎您向 AMD Vulkan 开源驱动程序提交代码贡献。

该驱动程序是根据五个存储库中的源代码构建的：LLVM、XGL、LLPC、GPURT 和 PAL。

对于 LLVM 的更改，您应该向 LLVM 主干提交贡献。那里的提交将被定期评估并合并到 amd-gfx-gpuopen-master 分支中。

对于 XGL、LLPC、GPURT 和 PAL 的更改，请针对dev 分支创建拉取请求。您的更改经过审核并被接受后，将在后续定期升级中评估是否合并到主分支中。

重要提示：通过创建拉取请求，您同意项目所有者根据 MIT 许可证条款对您的贡献进行许可。

当贡献 XGL、LLPC、GPURT 和 PAL 时，您的代码应该：

• 匹配附近现有代码的风格。当您的代码合并到主分支时，可能会对其进行编辑以符合我们的编码标准。
• 避免添加新的依赖项，包括对 STL 的依赖项。

请使每项贡献都相当小。如果您想做出重大贡献，例如新功能或扩展，请首先提出问题，以便规划评估和审查您的工作。

注意由于 PAL 是一个共享组件，必须支持其他 API、其他操作系统和预生产硬件，因此可能会要求您修改 PAL 更改，而从纯 Linux Vulkan 驱动程序的角度来看，这些原因可能并不明显。

构建说明

系统要求

建议在构建系统中安装至少 16GB RAM。

构建系统

• 需要 CMake 3.21 或更高版本。如果 cmake 版本低于 3.21，请下载并安装正确的版本。
• 需要 C++ 20 支持。像gcc9、clang11。
• 需要忍者。

安装开发和工具包

乌班图

 sudo apt-get install build-essential cmake curl g++-multilib gcc-multilib git ninja-build pkg-config python3 python3-jinja2 python3-ruamel.yaml

64位

 sudo apt-get install libssl-dev libx11-dev libxcb1-dev x11proto-dri2-dev libxcb-dri3-dev libxcb-dri2-0-dev libxcb-present-dev libxshmfence-dev libxrandr-dev libwayland-dev

32位

 dpkg --add-architecture i386
sudo apt-get install libssl-dev:i386 libx11-dev:i386 libxcb1-dev:i386 libxcb-dri3-dev:i386 libxcb-dri2-0-dev:i386 libxcb-present-dev:i386 libxshmfence-dev:i386 libwayland-dev libwayland-dev:i386 libxrandr-dev:i386

红帽

64位

 sudo yum -y install openssl-devel gcc-c++ python3 python3-pip curl glibc-devel libstdc++-devel libxcb-devel libX11-devel libxshmfence-devel libXrandr-devel wayland-devel
pip3 install jinja2 ruamel.yaml 

32位

 sudo yum -y install openssl-devel.i686 gcc-c++ python3 python3-pip curl glibc-devel.i686 libstdc++-devel.i686 libxcb-devel.i686 libX11-devel.i686 libxshmfence-devel.i686 libXrandr-devel.i686 wayland-devel.i686
pip3 install jinja2 ruamel.yaml 

安装着色器编译工具

需要安装 DirectXShaderCompiler 和 glslang 等着色器编译工具来构建光线跟踪支持。

乌班图22.04

建议从 VulkanSDK 1.3.290 或更高版本安装它们。

Ubuntu 22.04（杰米）

 wget -qO- https://packages.lunarg.com/lunarg-signing-key-pub.asc | sudo tee /etc/apt/trusted.gpg.d/lunarg.asc
sudo wget -qO /etc/apt/sources.list.d/lunarg-vulkan-1.3.290-jammy.list https://packages.lunarg.com/vulkan/1.3.290/lunarg-vulkan-1.3.290-jammy.list
sudo apt update
sudo apt install vulkan-sdk

其他的

获取 DirectXShaderCompiler 和 glslang 源代码并在本地构建工具。

 #!/bin/bash

if [ ! -d DirectXShaderCompiler ]; then
git clone --depth=1 -b release-1.8.2403 https://github.com/microsoft/DirectXShaderCompiler.git
fi

if [ ! -d glslang ]; then
git clone --depth=1 -b vulkan-sdk-1.3.290.0 https://github.com/KhronosGroup/glslang.git
fi

cd DirectXShaderCompiler
git submodule init
git submodule update
cmake -H. -Bbuilds -GNinja -DCMAKE_BUILD_TYPE=Release -C ./cmake/caches/PredefinedParams.cmake
cmake --build builds
cd ..

cd glslang
cmake -H. -Bbuilds -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX='builds/install'
cd builds
make -j8 install
cd ../../

在 amdvlk 驱动程序构建之前设置 env PATH 和 LD_LIBRARY_PATH。

 export PATH=/builds/bin:/install/bin:$PATH
export LD_LIBRARY_PATH=/builds/lib:$LD_LIBRARY_PATH

获取回购工具

 mkdir ~/bin
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo
export PATH=~/bin:"$PATH"

获取源代码

 mkdir vulkandriver
cd vulkandriver
repo init -u https://github.com/GPUOpen-Drivers/AMDVLK.git -b master
repo sync

注意dev 分支中的源代码可以通过在“repo init”命令中使用“-b dev”来获取。

构建驱动程序并生成 JSON 文件

 cmake -G Ninja -S xgl -B builds/Release64
cmake --build builds/Release64

cmake -G Ninja -S xgl -B builds/Release32 -DCMAKE_C_FLAGS=-m32 -DCMAKE_CXX_FLAGS=-m32
cmake --build builds/Release32

笔记

• 对于调试构建，请使用-DCMAKE_BUILD_TYPE=Debug -DLLVM_PARALLEL_LINK_JOBS=2 （链接 llvm 的调试构建非常占用内存，因此我们仅使用两个并行作业）。
• 如果您想与驱动程序一起构建工具（例如 amdllpc），请在 repo init 中添加-m build_with_tools.xml并添加构建选项-DXGL_BUILD_TOOLS=ON 。

安装说明

安装Vulkan SDK

您可以在这里下载并安装SDK包。

安装依赖项

乌班图

 sudo apt install libssl3

红帽

 sudo yum install openssl-libs

安装驱动程序和 JSON 文件

 sudo cmake --install builds/Release64 --component icd
sudo cmake --install builds/Release32 --component icd

如果要将驱动安装到自定义目录，可以在cmake build命令中添加“-DCMAKE_INSTALL_PREFIX={安装目录}”。 JSON 文件将安装到 /etc/vulkan/icd.d，而其他文件将安装到您指定的安装目录。

如果系统中还安装了RADV，则安装后将默认启用AMDVLK驱动程序。您可以通过环境变量 AMD_VULKAN_ICD = AMDVLK 或 RADV 在 AMDVLK 和 RADV 之间切换驱动程序。

注意：仅当运行 AMDGPU 上游驱动程序堆栈时才需要执行其余步骤。

打开 DRI3 并禁用模式设置 X 驱动程序

在 /usr/share/X11/xorg.conf.d/10-amdgpu.conf 中添加以下行：

 Section "Device"

Identifier "AMDgpu"

Option  "DRI" "3"

EndSection

并确保以下行不包含在该部分中：

 Driver      "modesetting"

所需设置

在 libdrm 版本低于 2.4.92 的 AMDGPU 上游驱动程序堆栈上，每次提交的最大 IB 数量必须限制为 4（Vulkan 的 AMD 开源驱动程序中的默认设置为 16）。这可以通过运行时设置机制通过将以下行添加到 amdPalSettings.cfg 来完成：

 MaxNumCmdStreamsPerSubmit,4
CommandBufferCombineDePreambles,1

使用预构建驱动程序安装

您可以在构建驱动程序时使用以下命令生成安装包：

乌班图

 cmake -G Ninja -S xgl -B builds/Release64 [-DPACKAGE_VERSION=package version]
cmake --build builds/Release64 --target makePackage

红帽

 cmake -G Ninja -S xgl -B builds/Release64 [-DPACKAGE_VERSION=package version]
cmake --build builds/Release64 --target makePackage

您还可以从 https://github.com/GPUOpen-Drivers/AMDVLK/releases 下载预构建的软件包，用于 master 分支中的每个代码升级。

下面是安装说明：

乌班图

 sudo dpkg -r amdvlk  # If old version is installed on the machine, remove it first 
sudo dpkg -i amdvlk_x.x.x_amd64.deb
sudo apt-get -f install

红帽

 sudo rpm -e amdvlk   # If old version is installed on the machine, remove it first 
sudo rpm -i amdvlk-x.x.x.x86_64.rpm

对于 Ubuntu，您还可以从 https://repo.radeon.com 安装最新的驱动程序版本：

 sudo wget -qO - http://repo.radeon.com/amdvlk/apt/debian/amdvlk.gpg.key | sudo apt-key add -
sudo sh -c 'echo deb [arch=amd64,i386] http://repo.radeon.com/amdvlk/apt/debian/ bionic main > /etc/apt/sources.list.d/amdvlk.list'
sudo apt-get remove amdvlk # If old version is installed on the machine, remove it first 
sudo apt update
sudo apt-get install amdvlk

运行时设置

该驱动程序公开了许多可以自定义驱动程序行为并促进调试的设置。您可以在以下路径之一下的 amdVulkanSettings.cfg 或 amdPalSettings.cfg 文件中添加/编辑设置，格式为每行一个name,value对：

• /etc/amd
• $AMD_CONFIG_DIR

下面列出了一些示例设置：

设置名称	有效值	评论
AllowVkPipelineCachingToDisk	0：不允许 1：默认	1 是默认值，它启用 Pal 的基于存档文件的缓存。 存档文件存储在 ~/.cache/AMD/VkCache 下。
ShaderCacheMode	0：禁用缓存 1：运行时缓存 2：缓存到磁盘	运行时缓存是默认模式。对于“缓存到磁盘”，缓存文件在 $AMD_SHADER_DISK_CACHE_PATH/AMD/LlpcCache 或 $XDG_CACHE_HOME/AMD/LlpcCache 或 $HOME/.cache/AMD/LlpcCache 下生成
IFH	0：默认 1：删除所有提交	无限快速的硬件。提交调用在发送到硬件之前被丢弃。对于测量 CPU 限制的性能很有用。
EnableVmAlwaysValid	0：禁用 1：默认 2：强制使能	1 是默认设置，可为内核 4.16 及更高版本启用 VM-always-valid 功能。该功能可以减少与虚拟内存管理相关的命令缓冲区提交开销。
IdleAfterSubmitGpuMask	GPU 的位掩码（即位 0 是 GPU0 等）	强制 CPU 立即等待指定 GPU 组上的每个 GPU 提交完成。

所有可用的设置都可以通过检查下面定义它们的源文件来确定。

• .../xgl/icd/settings/settings.cfg（API 层设置）
• .../pal/src/core/settings_core.json（与 PAL 硬件无关的设置）
• .../pal/src/core/hw/gfxip/gfx6/settings_gfx6.json（PAL GFX6-8 设置）
• .../pal/src/core/hw/gfxip/gfx9/settings_gfx9.json（PAL GFX9+ 设置）

运行时设置仅在设备初始化时读取，并且在不重新启动应用程序的情况下无法更改。如果在具有多个 GPU 的系统上运行，则相同的设置将应用于所有 GPU。设置文件中以;开头的行将被视为评论。

启用正在开发的扩展

正在开发的扩展在驱动程序中默认不启用。您可以通过环境变量启用它们：

[...]"">

 export AMDVLK_ENABLE_DEVELOPING_EXT=" [...]"

或者

 export AMDVLK_ENABLE_DEVELOPING_EXT="all"

扩展名不区分大小写。

PAL GpuProfiler 层

GpuProfiler 是一个可选层，旨在拦截 PAL 接口以提供基本的 GPU 分析支持。目前，该层仅通过运行时设置进行控制，并将其结果输出到文件。

您可以使用以下运行时设置生成 .csv 文件，其中包含在应用程序的指定帧期间执行的工作的 GPU 计时（每一帧一个文件）：

设置名称	价值	评论
GpuProfilerMode	0：禁用 1：启用并关闭 sqtt 2：使用 sqtt 启用线程跟踪 3：使用 sqtt 启用 RGP	启用并设置 GPU 性能分析器层的 SQTT 模式。性能数据的实际捕获必须通过 GpuProfilerConfig_StartFrame 的帧号或按 Shift-F11 来指定。
GpuProfilerConfig.LogDirectory	<目录路径>	目录路径相对于 $AMD_DEBUG_DIR 或 $TMPDIR 或 /var/tmp/，默认值为“amdpal/”。您的应用程序必须对该目录具有写权限。分析日志输出到以 格式命名的子目录。
GpuProfilerConfig.Granularity	0：每次抽奖 1：每个cmdbuf	定义测量/分析的内容。 Per-draw计算命令缓冲区内的各个命令（例如绘制、调度等），而per-cmdbuf仅汇总整个命令缓冲区。
GpuProfilerConfig.StartFrame	正整数	捕获数据的第一帧。如果未设置 StartFrame 和 FrameCount，则将分析所有帧。
GpuProfilerConfig.FrameCount	正整数	要捕获数据的帧数。
GpuProfilerConfig.RecordPipelineStats	0, 1	如果启用，则收集每个条目的管道统计查询数据。

您可以使用脚本timingReport.py来分析分析日志：

 python timingReport.py 

转储管道和着色器

timeReport.py 的输出包括顶级管道的信息，如下所示：

 Top Pipelines (>= 1%)
Compiler Hash         | Type         | Avg. Call Count | Avg. GPU Time [us] | Avg. Frame %
1. 0xd91d15e42d62dcbb | VsPs         |              43 |          11,203.15 |      10.20 %
2. 0x724e9af55f2adf1b | Cs           |               1 |           9,347.50 |       8.51 %
3. 0x396e5ad6f7a789f7 | VsHsDsPs     |             468 |           8,401.35 |       7.65 %

您可以在 amdPalSettings.cfg 中添加以下设置来转储每个管道的信息：

 EnablePipelineDump,1
PipelineDumpDir,

PipelineDumpDir 是相对于 $AMD_DEBUG_DIR 或 $TMPDIR 或 /var/tmp/ 的子路径，默认值为“spvPipeline/”。管道转储文件的命名格式类似于 Pipeline_.pipe。例如，上面的 top 1 管道转储到 PipelineVsFs_0xD91D15E42D62DCBB.pipe。每个管道引用的着色器也会转储到 .spv 文件中。

PAL 调试覆盖

可以启用 PAL 的调试覆盖层以在正在运行的应用程序之上显示实时统计数据和信息。这包括滚动 FPS 平均值、CPU 和 GPU 帧时间，以及跟踪从每个可用堆分配了多少视频内存的分类帐。当前不支持基准测试（即“基准测试 (F11)”）。

设置名称	价值	评论
DebugOverlayEnabled	0, 1	启用调试覆盖。
DebugOverlayConfig.DebugOverlayLocation	0：左上角 1：右上角 2：左下角 3：右下角	确定应显示覆盖文本的位置。可用于避免与应用程序的重要渲染发生冲突。
DebugOverlayConfig.PrintFrameNumber	0, 1	报告当前帧编号。在确定使用 GpuProfiler 层进行分析的良好帧范围时非常有用。
DebugOverlayConfig.TimeGraphEnable	0, 1	启用最近 CPU 和 GPU 帧时间图表的渲染。

第三方软件

适用于 Vulkan 的 AMD 开源驱动程序包含第三方编写的代码。

• LLVM 根据 Apache License v2.0 进行分发，但有 LLVM 例外情况。请参阅 LLVM 存储库顶部目录中的 LICENSE.TXT 文件。
• MetroHash 是根据 Apache License 2.0 条款分发的。请参阅 MetroHash 存储库顶部目录中的 LICENSE 文件。
• CWPack 根据 MITLicense 条款进行分发。请参阅 CWPack 存储库顶部目录中的 LICENSE 文件。
• 请参阅 PAL、LLPC、GPURT 和 XGL 存储库中的 README.md 文件，了解有关这些库使用的第三方软件的信息。

免责声明

本文包含的信息仅供参考，如有更改，恕不另行通知。本文档可能包含技术错误、遗漏和印刷错误，AMD 没有义务更新或更正此信息。 Advanced Micro Devices, Inc. 不对本文档内容的准确性或完整性做出任何声明或保证，并且不承担任何形式的责任，包括关于不侵权、适销性或特定用途适用性的暗示保证。 AMD 硬件、软件或本文所述的其他产品的操作或使用。本文档未授予任何知识产权许可（包括默示许可或禁止反言许可）。适用于购买或使用 AMD 产品的条款和限制在双方签署的协议或 AMD 的标准销售条款和条件中规定。

AMD、AMD 箭头徽标、Radeon、FirePro 及其组合是 Advanced Micro Devices, Inc. 的商标。本出版物中使用的其他产品名称仅用于识别目的，可能是其各自公司的商标。

Vega 是 AMD 架构的代号，而不是产品名称。

Linux 是 Linus Torvalds 在美国和其他国家的注册商标。

Vulkan 和 Vulkan 徽标是 Khronos Group, Inc. 的注册商标。