7.1 显卡驱动概论

使用 bsdinstall 安装的 FreeBSD 系统不会自动安装图形用户界面。本节介绍如何为图形处理器（GPU）选择和安装驱动程序。

7.1.1 何时需要安装显卡驱动？

未安装显卡驱动的报错图

上图展示了未安装显卡驱动时可能出现的错误界面。

警告
请勿使用 sysutils/desktop-installer，该工具在当前环境下可能引发错误和配置冲突。

7.1.2 显卡支持情况

FreeBSD 的 i915 和 AMD 显卡驱动与基本系统分离，以 Port 形式提供，这些驱动移植自 Linux 内核的 DRM（Direct Rendering Manager，直接渲染管理器），采用长期支持（Long Term Support，LTS）版本。不同系统版本对应的 Linux 内核版本有所不同。

注意
使用 Ports 安装时，drm 驱动需要在 /usr/src 中有一份当前版本的系统源代码，具体可参考系统更新章节。如果已参考本书其他章节安装，系统中通常已有一份源代码，无需再次获取。

DRM 是 Linux 内核的子系统，负责与现代显卡的 GPU 交互。FreeBSD 在内核中实现了 Linux 内核编程接口（LinuxKPI，Linux Kernel Programming Interface）并移植了 Linux DRM，部分无线网卡驱动也采用了这种移植方式。

注意
这种移植并不覆盖 Linux 现有的全部 DRM GPU 驱动，目前仅包括 i915、amdgpu 和 radeon，vmwgfx、xe、virtio 等均未移植。这些未移植的 GPU 通常无法在 Wayland 上运行，只能使用 X11 显示协议。

显卡支持情况：

非 LTS 版本（Port graphics/drm-latest-kmod，仅 15.0/16.0，目前为 6.9）：
- Intel：Meteor Lake 图形在 6.7 后默认启用；
- AMD：覆盖 GCN 到 RDNA 3 全部架构。RDNA 4 驱动需等待更新的 Linux 内核版本移植。

技巧
可在 port 开发者手册的最后一章中查询 OSVERSION 对应的版本和 Git 提交。
查看本机 OSVERSION，显示系统版本构建标识符：
sh
# uname -U
1500019
1
2

警告
每次小版本或大版本升级时，可能需要重新获取系统源代码并重新编译安装显卡驱动模块，方可顺利完成升级并避免停留在黑屏界面；或者也可使用“模块源”方式。

7.1.3 加入 video 组

video 组是负责访问 DRM 和 DRI 视频设备的用户组。只有加入该组的用户才能正常使用显卡的硬件加速功能以及 Wayland 会话功能。

需将指定用户添加到 video 用户组：

# pw groupmod video -m 实际用户名

警告
即使已加入 wheel 组，也应再加入 video 组，否则视频硬件解码功能可能出现异常，且 Wayland 下普通用户将无权限调用显卡。

7.1.4 亮度调节

7.1.4.1 通用设置

一般计算机需要在 /boot/loader.conf 文件中启用 ACPI 视频支持：

# sysrc -f /boot/loader.conf acpi_video_load="YES"

ThinkPad 可启用 IBM ACPI 支持和 ACPI 视频支持。

在 /boot/loader.conf 文件中启用 IBM ACPI 支持：

# sysrc -f /boot/loader.conf acpi_ibm_load="YES"

在 /boot/loader.conf 文件中启用 ACPI 视频支持：

# sysrc -f /boot/loader.conf acpi_video_load="YES"

7.1.4.2 英特尔/AMD 显卡

backlight 工具自 FreeBSD 13 引入。

# backlight          # 打印当前亮度
# backlight -q       # 仅输出亮度数值，便于脚本使用
# backlight -i       # 查询背光设备信息（名称、类型）
# backlight decr 20  # 降低 20% 亮度
# backlight +        # 默认调整亮度增加 10%
# backlight -        # 默认调整亮度减少 10%

如果上述操作未生效，可检查 /dev/backlight 路径下的可用设备。

示例（使用 ls /dev/backlight 命令查看实际设备）：

设置 amdgpu_bl00 背光亮度为 10：

# backlight -f /dev/backlight/amdgpu_bl00 10

设置 backlight0 背光亮度为 10：

# backlight -f /dev/backlight/backlight0 10

7.1.4.3 参考文献

Vadot E. backlight -- configure backlight hardware[EB/OL]. (2022-07-19)[2026-03-25]. https://man.freebsd.org/cgi/man.cgi?query=backlight&sektion=8. 经测试，此部分教程适用于 Renoir 显卡。

7.1.5 状态检查

检查显卡是否已成功驱动：

$ pciconf -lv | grep -B4 VGA   # 列出系统中所有 VGA 兼容设备及其型号
$ ls -al /dev/dri/card0
lrwxr-xr-x  1 root wheel 8 Jul  2 19:39 /dev/dri/card0 -> ../drm/0

$ ls -al /dev/backlight/backlight0
crw-rw---- 1 root video 1, 177 2025年 8月22日 /dev/backlight/backlight0  # 台式机 HDMI 等输出可能没有

显卡驱动加载成功后，系统中将出现 card0 设备（默认编号为 0，如有第二块显卡则为 card1），同时还可能出现 backlight0 设备（HDMI 输出下通常不存在该设备）。可使用 kldstat | grep -E "i915kms|amdgpu|radeonkms" 进一步确认对应的内核模块已成功加载。

7.1.6 故障排除与未竟事宜

注意
遇到任何问题时，请先使用 Ports 重新编译安装，尤其是在版本升级时。

如果显卡驱动存在问题，请直接联系维护者：https://github.com/freebsd/drm-kmod/issues。
如果笔记本出现唤醒时屏幕无法点亮的问题，可在 /boot/loader.conf 文件中添加 hw.acpi.reset_video="1" 以在唤醒时重置显示适配器。
普通用户可能未加入 wheel 组或 video 组。如果普通用户未加入 video 组（仅加入 wheel 组不够），KDE 设置中将始终显示显卡驱动为“llvmpipe”，这会影响 Wayland 下普通用户的显示或硬件解码功能。

7.1.6.1 KLD XXX.ko depends on kernel - not available or version mismatch.

提示内核版本不符，请先升级系统或使用 ports 编译安装。14.3-RELEASE 及以上版本可使用内置的内核模块源（参见其他章节），应不会出现类似问题。

AMD 驱动错误提示

7.1.7 课后习题

使用 pciconf -lv | grep -B3 display 查看本机显卡型号，根据显卡品牌（Intel、AMD 或 NVIDIA）安装对应的 DRM 驱动，用 kldstat 确认驱动模块已加载。
安装显卡驱动后，检查 /dev/dri/card0 设备是否存在，将当前用户加入 video 组，重启后运行 glxinfo | grep "OpenGL renderer" 确认硬件加速是否生效。
在 /boot/loader.conf 中启用 ACPI 视频支持，使用 backlight 命令调节屏幕亮度，记录 backlight decr 和 backlight + 的实际效果。

7.1 显卡驱动概论 ​

7.1.1 何时需要安装显卡驱动？ ​

7.1.2 显卡支持情况 ​

7.1.3 加入 video 组 ​

7.1.4 亮度调节 ​

7.1.4.1 通用设置 ​

7.1.4.2 英特尔/AMD 显卡 ​

7.1.4.3 参考文献 ​

7.1.5 状态检查 ​

7.1.6 故障排除与未竟事宜 ​

7.1.6.1 KLD XXX.ko depends on kernel - not available or version mismatch. ​

7.1.7 课后习题 ​