如何验证错误并二分查找回归¶

本文档描述了如何检查某个 Linux 内核问题是否发生在开发人员当前支持的代码中——然后解释如果它是一个回归（例如，在早期版本中没有发生）的话，如何定位导致该问题的更改。

本文档面向在商用硬件上运行主流 Linux 发行版内核并希望向 Linux 上游开发人员报告内核错误的用户。尽管有此意图，但这些说明对于已经熟悉构建自己的内核的用户同样有效：它们有助于避免即使是经验丰富的开发人员偶尔也会犯的错误。

流程精髓（即“TL;DR”）¶

[如果您是 Linux 构建或二分查找的新手，请忽略本节，直接查看下面的‘分步指南’。它使用与本节相同的命令，但以简明的方式进行描述。这些步骤易于遵循，并且与参考部分中的配套条目一起提到了许多替代方案、陷阱和附加方面，所有这些在您当前的情况下可能都是必不可少的。]

如果您想检查错误是否存在于开发人员当前支持的代码中，只需执行准备工作和第 1 部分；在此过程中，将您日常使用的最新 Linux 内核视为“工作”内核。在以下示例中，假设它是 6.0，因此将使用其源代码来准备 .config 文件。

如果您遇到回归，请至少遵循步骤直到第 2 部分结束。然后您可以提交一份初步报告——或者继续进行第 3 部分，其中描述了如何执行二分查找以获得一份完整的回归报告。在以下示例中，假设 6.0.13 是“工作”内核，6.1.5 是第一个“损坏”的内核，因此 6.0 将被视为“良好”版本，并用于准备 .config 文件。

准备工作：设置所有内容以构建您自己的内核

# * Remove any software that depends on externally maintained kernel modules
#   or builds any automatically during bootup.
# * Ensure Secure Boot permits booting self-compiled Linux kernels.
# * If you are not already running the 'working' kernel, reboot into it.
# * Install compilers and everything else needed for building Linux.
# * Ensure to have 15 Gigabyte free space in your home directory.
git clone -o mainline --no-checkout \
  https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git ~/linux/
cd ~/linux/
git remote add -t master stable \
  https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
git switch --detach v6.0
# * Hint: if you used an existing clone, ensure no stale .config is around.
make olddefconfig
# * Ensure the former command picked the .config of the 'working' kernel.
# * Connect external hardware (USB keys, tokens, ...), start a VM, bring up
#   VPNs, mount network shares, and briefly try the feature that is broken.
yes '' | make localmodconfig
./scripts/config --set-str CONFIG_LOCALVERSION '-local'
./scripts/config -e CONFIG_LOCALVERSION_AUTO
# * Note, when short on storage space, check the guide for an alternative:
./scripts/config -d DEBUG_INFO_NONE -e KALLSYMS_ALL -e DEBUG_KERNEL \
  -e DEBUG_INFO -e DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT -e KALLSYMS
# * Hint: at this point you might want to adjust the build configuration;
#   you'll have to, if you are running Debian.
make olddefconfig
cp .config ~/kernel-config-working

第 1 部分：从最新的主线代码库构建内核。

这尤其检查了问题是否已经修复，以及后续需要通知哪些开发人员有关该问题；如果发生回归，这排除了 .config 更改是问题根源的可能性。

检出最新的主线代码

cd ~/linux/
git switch --discard-changes --detach mainline/master

构建、安装并启动内核

cp ~/kernel-config-working .config
make olddefconfig
make -j $(nproc --all)
# * Make sure there is enough disk space to hold another kernel:
df -h /boot/ /lib/modules/
# * Note: on Arch Linux, its derivatives and a few other distributions
#   the following commands will do nothing at all or only part of the
#   job. See the step-by-step guide for further details.
sudo make modules_install
command -v installkernel && sudo make install
# * Check how much space your self-built kernel actually needs, which
#   enables you to make better estimates later:
du -ch /boot/*$(make -s kernelrelease)* | tail -n 1
du -sh /lib/modules/$(make -s kernelrelease)/
# * Hint: the output of the following command will help you pick the
#   right kernel from the boot menu:
make -s kernelrelease | tee -a ~/kernels-built
reboot
# * Once booted, ensure you are running the kernel you just built by
#   checking if the output of the next two commands matches:
tail -n 1 ~/kernels-built
uname -r
cat /proc/sys/kernel/tainted

检查此内核是否也出现问题。

第 2 部分：确保“良好”内核也是“工作”内核。

这尤其验证了精简的 .config 文件是否确实运行良好，否则使用它进行二分查找将是浪费时间。
1. 首先检出“良好”版本的源代码
```
cd ~/linux/
git switch --discard-changes --detach v6.0
```
2. 按照前面第 1 部分，b 节所述构建、安装并启动内核——您不必执行“du”命令，因为您已经有一个大致的估算。
3. 确保在“损坏”内核中出现回归的功能在此内核中确实正常工作。
第 3 部分：执行并验证二分查找。
1. 检索您的“损坏”版本的源代码
```
git remote set-branches --add stable linux-6.1.y
git fetch stable
```
2. 初始化二分查找
```
cd ~/linux/
git bisect start
git bisect good v6.0
git bisect bad v6.1.5
```
3. 按照前面第 1 部分，b 节所述构建、安装并启动内核。
  
  如果因无关原因导致内核构建或启动失败，请运行 git bisect skip。在所有其他情况下，检查回归功能是否在新构建的内核中工作。如果工作，通过执行 git bisect good 告知 Git；如果不工作，则运行 git bisect bad。
  
  所有这三个命令都会让 Git 检出另一个提交；然后重新执行此步骤（例如，构建、安装、启动和测试内核，然后告知 Git 结果）。如此反复，直到 Git 显示是哪个提交导致了问题。如果在此过程中磁盘空间不足，请查看下面的“补充任务：流程中及流程后的清理”部分。
4. 完成二分查找后，请收拾一些东西
```
cd ~/linux/
git bisect log > ~/bisect-log
cp .config ~/bisection-config-culprit
git bisect reset
```
5. 尝试验证二分查找结果
```
git switch --discard-changes --detach mainline/master
git revert --no-edit cafec0cacaca0
cp ~/kernel-config-working .config
./scripts/config --set-str CONFIG_LOCALVERSION '-local-cafec0cacaca0-reverted'
```
这是可选的，因为有些提交无法回滚。但如果第二个命令完美运行，请构建、安装并启动一个内核；只是这次跳过复制基础 .config 文件的第一个命令，因为这已经处理过了。
补充任务：流程中及流程后的清理。
1. 为避免在二分查找期间磁盘空间不足，您可能需要删除一些早期构建的内核。您很可能希望保留在第 1 部分和第 2 部分构建的内核一段时间，但您很可能不再需要实际二分查找（第 3 部分 c）期间测试的内核。您可以使用以下命令按构建顺序列出它们
```
ls -ltr /lib/modules/*-local*
```
然后，例如，要擦除一个自识别为“6.0-rc1-local-gcafec0cacaca0”的内核，请使用此命令
sudo rm -rf /lib/modules/6.0-rc1-local-gcafec0cacaca0 sudo kernel-install -v remove 6.0-rc1-local-gcafec0cacaca0 # * Note, on some distributions kernel-install is missing # or does only part of the job.
1. 如果您已执行二分查找并成功验证结果，请随意删除在实际二分查找（第 3 部分 c）期间构建的所有内核；您可能希望将早期和后期构建的内核保留一两周。

可选任务：稍后测试调试补丁或提议的修复

git fetch mainline
git switch --discard-changes --detach mainline/master
git apply /tmp/foobars-proposed-fix-v1.patch
cp ~/kernel-config-working .config
./scripts/config --set-str CONFIG_LOCALVERSION '-local-foobars-fix-v1'

按照第 1 部分，b 节所述构建、安装并启动内核——但这次省略复制构建配置的第一个命令，因为这已经处理过了。

如何验证错误和二分查找回归的分步指南¶

本指南描述了如何设置您自己的 Linux 内核以调查您打算报告的错误或回归。您希望遵循说明的程度取决于您的问题

执行所有步骤直到第 1 部分结束，以验证您的内核问题是否存在于 Linux 内核开发人员支持的代码中。如果存在，您就可以报告错误了——除非它在早期内核版本中没有发生，因为那样您至少需要继续进行第 2 部分，以检查该问题是否符合回归条件，从而获得优先处理。根据结果，您可以准备报告错误或提交初步回归报告；而不是后者，您也可以直接继续并遵循第 3 部分，以执行二分查找，以便提交开发人员有义务处理的完整回归报告。

准备工作：设置所有内容以构建您自己的内核.

第 1 部分：尝试使用最新代码库重现问题.

第 2 部分：检查您构建的内核是否正常工作.

第 3 部分：执行二分查找并验证结果.

补充任务：遵循本指南期间和之后的清理工作.

可选任务：测试回滚、补丁或后续版本.

每个部分的步骤都阐明了流程的重要方面，而全面的参考部分包含了几乎所有步骤的额外细节。参考部分有时还会概述替代方法、陷阱以及在特定步骤可能出现的问题——以及如何重新启动。

有关如何报告 Linux 内核问题或回归的更多详细信息，请查阅报告问题，它与本文档结合使用。它特别解释了为什么即使您面临来自“稳定/长期”系列内核（例如 6.0.13）的问题，您也需要使用最新的“主线”内核（例如 6.0、6.1-rc1 或 6.1-rc6 等版本）来验证错误。

对于面临回归的用户，该文档还解释了为什么在第 2 部分之后发送初步报告可能是明智之举，因为回归及其罪魁祸首可能已经为人所知。有关实际构成回归的更多详细信息，请查阅报告回归。

如果您在遵循本指南时遇到任何问题，或者有改进它的想法，请告知内核开发人员。

准备工作：设置所有内容以构建您自己的内核¶

以下步骤为所有后续任务奠定了基础。

注意：这些说明假设您在同一台机器上进行构建和测试；如果您想在另一台系统上编译内核，请查看下面的在不同的机器上构建内核。

创建一份全新的备份，并备好系统修复和恢复工具，以防万一出现意外情况。

[详情]

删除所有依赖于外部开发内核驱动程序或自动构建它们的软件。这包括但不限于 DKMS、openZFS、VirtualBox 和 Nvidia 的图形驱动程序（包括 GPL 许可的内核模块）。

[详情]

在具有“安全启动”或类似解决方案的平台上，准备好一切以确保系统允许您自行编译的内核启动。在商用 x86 系统上实现这一点的最快最简单方法是在 BIOS 设置实用程序中禁用此类技术；或者，通过由 mokutil --disable-validation 启动的流程来解除其限制。

[详情]

确定本指南中被视为“良好”和“损坏”的内核版本
- 您是否遵循本指南来验证主要开发人员关注的代码中是否存在错误？那么，将您目前经常使用的最新内核版本视为“良好”版本（例如 6.0、6.0.13 或 6.1-rc2）。
- 您是否面临回归，例如切换到较新内核版本后出现问题或性能变差？在这种情况下，这取决于问题出现的版本范围
  - 当从稳定/长期版本（例如 6.0.13）更新到较新的主线系列（例如 6.1-rc7 或 6.1）或基于它们的稳定/长期版本（例如 6.1.5）时出现回归？那么，将您的工作内核所基于的主线版本视为“良好”版本（例如 6.0），并将第一个出现问题的版本视为“损坏”版本（例如 6.1-rc7、6.1 或 6.1.5）。请注意，此时仅假设 6.0 正常；这个假设将在第 2 部分中进行检查。
  - 当从一个主线版本（例如 6.0）切换到后续版本（例如 6.1-rc1）或基于它的稳定/长期版本（例如 6.1.5）时出现回归？那么，将最后一个正常工作的版本（例如 6.0）视为“良好”版本，将第一个出现问题的版本（例如 6.1-rc1 或 6.1.5）视为“损坏”版本。
  - 当在稳定/长期系列中更新（例如从 6.0.13 到 6.0.15）时出现回归？那么，将这些版本视为“良好”和“损坏”版本（例如 6.0.13 和 6.0.15），因为您需要在该系列中进行二分查找。
请注意，不要混淆“良好”版本和“工作”内核；在本指南中，“工作内核”一词将指最后一个运行正常的内核。

[详情]

启动进入“工作”内核并简要使用明显有问题的特性。

[详情]

确保有足够的空闲空间来构建 Linux。您的主目录中 15 GB 通常就足够了。如果可用空间较少，请务必注意后续关于检索 Linux 源代码和处理调试符号的步骤：两者都解释了减少空间量的方法，这应该能让您在大约 4 GB 空闲空间的情况下完成这些任务。

[详情]

安装构建 Linux 内核所需的所有软件。通常您需要：‘bc’、‘binutils’（‘ld’等）、‘bison’、‘flex’、‘gcc’、‘git’、‘openssl’、‘pahole’、‘perl’以及‘libelf’和‘openssl’的开发头文件。参考部分展示了如何在各种流行的 Linux 发行版上快速安装这些软件。

[详情]

检索主线 Linux 源代码；然后进入包含这些源代码的目录，因为本指南中的所有后续命令都应从该目录执行。

注意，以下描述如何使用完整的主线克隆来检索源代码，截至 2024 年初，这将下载大约 2.75 GB。参考部分描述了两种替代方法：一种下载小于 500 MB，另一种更适用于不可靠的互联网连接。

执行以下命令以检索最新的主线代码库，同时准备好后续添加稳定/长期系列分支
```
git clone -o mainline --no-checkout \
  https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git ~/linux/
cd ~/linux/
git remote add -t master stable \
  https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
```
[详情]

您之前确定为“良好”或“损坏”的版本中，是否有一个是稳定版或长期版（例如 6.1.5）？那么，请下载它所属系列的源代码（在本例中为“linux-6.1.y”）
```
git remote set-branches --add stable linux-6.1.y
git fetch stable
```

开始准备内核构建配置（“.config”文件）。

在此之前，请确保您仍在运行前面步骤中指示您启动的“工作”内核；如果您不确定，请使用 uname -r 检查当前的 kernelrelease 标识符。

之后，检出您之前确定为“良好”版本的源代码。在以下示例命令中，假设其版本为 6.0；请注意，在此以及所有后续 Git 命令中，版本号需要加上“v”前缀
```
git switch --discard-changes --detach v6.0
```
现在创建一个构建配置文件
```
make olddefconfig
```
内核构建脚本将尝试定位正在运行内核的构建配置文件，然后根据您检出的内核源代码的需求进行调整。在此过程中，它将打印几行您需要检查的信息。

寻找以“# using defaults found in”开头的行。它后面应该跟着一个指向“/boot/”中文件的路径，该文件包含您当前工作内核的发布标识符。如果该行而是以“arch/x86/configs/x86_64_defconfig”之类的内容继续，则构建基础设施未能找到您正在运行的内核的 .config 文件——在这种情况下，您必须手动将其放置在那里，如参考部分所述。

如果您找不到这样的行，请寻找包含“# configuration written to .config”的行。如果是这种情况，则说明您有一个过时的构建配置。除非您打算使用它，否则请将其删除；然后再次运行“make olddefconfig”并检查它是否现在已选取正确的配置文件作为基础。

[详情]

禁用您设置中明显多余的任何内核模块。这是可选的，但对于二分查找来说尤其明智，因为它能极大地加快构建过程——至少除非上一步中选择的 .config 文件已经根据您和您的硬件需求进行了定制，在这种情况下您应该跳过此步骤。

为了准备精简，请连接您偶尔使用的外部硬件（USB 密钥、令牌等），快速启动虚拟机，并启用 VPN。如果您自开始本指南后重启过，请确保您自启动系统以来尝试使用过导致问题的功能。只有这样才能精简您的 .config
```
yes '' | make localmodconfig
```
这里有一个陷阱，正如本步骤开头句中的“明显”和准备说明中已经暗示的那样

“localmodconfig”目标可以很容易地禁用仅偶尔使用的功能的内核模块——例如自启动以来尚未连接的外部外设模块、尚未使用的虚拟化软件、VPN 隧道以及其他一些东西。这是因为某些任务依赖于 Linux 仅在您首次执行上述任务时才加载的内核模块。

localmodconfig 的这个缺点不值得您为此失眠，但需要记住：如果在遵循本指南构建的内核中出现异常行为，这很可能是原因。您可以通过参考部分中概述的技巧来减少或几乎消除风险；但如果只是为了快速测试而构建内核，通常不值得投入大量精力，只要它能启动并允许正确测试导致问题的功能即可。

[详情]

确保您将构建的所有内核都使用特殊标签和唯一版本号清晰可识别

./scripts/config --set-str CONFIG_LOCALVERSION '-local'
./scripts/config -e CONFIG_LOCALVERSION_AUTO

[详情]

决定如何处理调试符号。

在本文档的上下文中，通常明智的做法是启用它们，因为您很可能需要解码来自“panic”、“Oops”、“warning”或“BUG”的堆栈跟踪信息
```
./scripts/config -d DEBUG_INFO_NONE -e KALLSYMS_ALL -e DEBUG_KERNEL \
  -e DEBUG_INFO -e DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT -e KALLSYMS
```
但是，如果您的存储空间非常紧张，您可能希望禁用调试符号
```
./scripts/config -d DEBUG_INFO -d DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT \
  -d DEBUG_INFO_DWARF4 -d DEBUG_INFO_DWARF5 -e CONFIG_DEBUG_INFO_NONE
```
[详情]

检查您是否可能需要调整其他一些内核配置选项
- 您正在运行 Debian 吗？那么您需要通过参考部分中解释的额外调整来避免已知问题。
  
  [详情]。
- 如果您想影响配置的其他方面，请立即使用您喜欢的工具进行操作。请注意，要使用‘menuconfig’或‘nconfig’等 make 目标，您需要安装 ncurses 的开发文件；对于‘xconfig’，您同样需要 Qt5 或 Qt6 头文件。
  
  [详情]。

在最新调整后重新处理 .config 并将其存储在一个安全的地方
```
make olddefconfig
cp .config ~/kernel-config-working
```
[详情]

第 1 部分：尝试使用最新代码库重现问题¶

以下步骤验证问题是否发生在开发人员当前支持的代码中。如果您遇到回归，它还会检查问题是否不是由 .config 更改引起的，因为那样报告问题将是浪费时间。 [详情]

检出最新的 Linux 代码库。
- 您的“良好”和“损坏”版本是否来自同一个稳定或长期系列？那么请检查kernel.org 的首页：如果它列出了该系列中的一个版本且没有“[EOL]”标签，请检出该系列最新版本（在以下示例中为“linux-6.1.y”）
```
cd ~/linux/
git switch --discard-changes --detach stable/linux-6.1.y
```
  如果您的系列未列出或带有“生命周期结束”标签，则表示它不受支持。在这种情况下，您可能需要检查后续系列（例如 linux-6.2.y）或主线（参见下一点）是否修复了该错误。
- 在所有其他情况下，运行
```
cd ~/linux/
git switch --discard-changes --detach mainline/master
```
[详情]

使用您准备好的配置文件构建您的第一个内核的镜像和模块
```
cp ~/kernel-config-working .config
make olddefconfig
make -j $(nproc --all)
```
如果您想将内核打包成 deb、rpm 或 tar 文件，请查看参考部分中的替代方案，这显然也需要其他安装步骤。

[详情]

安装您新构建的内核。

在此之前，请考虑检查是否仍有足够的空间用于它
```
df -h /boot/ /lib/modules/
```
目前假设 /boot/ 中有 150 MB，/lib/modules/ 中有 200 MB 就足够了；您的内核实际需要多少空间将在本指南的稍后部分确定。

现在安装内核的模块和镜像，它们将与您的 Linux 发行版的内核并行存储
```
sudo make modules_install
command -v installkernel && sudo make install
```
第二个命令理想情况下将处理此时所需的三个步骤：将内核镜像复制到 /boot/，生成 initramfs，以及为两者添加一个引导加载器配置条目。

不幸的是，一些发行版（包括 Arch Linux 及其衍生版，以及许多不可变 Linux 发行版）将不执行或只执行其中一些任务。因此，您需要检查是否所有任务都已处理完毕，并手动执行那些未处理的任务。参考部分提供了更多详细信息；您的发行版文档也可能有所帮助。

一旦您弄清了此时所需的步骤，请考虑将其记录下来：如果您将按照第 2 部分和第 3 部分的描述构建更多内核，您将不得不在执行 command -v installkernel [...] 后再次执行这些步骤。

[详情]

如果您打算继续遵循本指南，请检查内核、其模块以及 initramfs 等其他相关文件占用了多少存储空间
```
du -ch /boot/*$(make -s kernelrelease)* | tail -n 1
du -sh /lib/modules/$(make -s kernelrelease)/
```
记下或记住这两个值以备后用：它们使您能够在二分查找期间防止意外耗尽磁盘空间。

[详情]

显示并存储您刚刚构建的内核的 kernelrelease 标识符
```
make -s kernelrelease | tee -a ~/kernels-built
```
暂时记住此标识符，因为它将帮助您在重启时从引导菜单中选择正确的内核。
重启到您新构建的内核。为确保您实际启动的是您刚刚构建的内核，您可能需要验证这些命令的输出是否匹配
```
tail -n 1 ~/kernels-built
uname -r
```

检查内核是否将自身标记为“tainted”
```
cat /proc/sys/kernel/tainted
```
如果该命令不返回‘0’，请查阅参考部分，因为其原因可能会干扰您的测试。

[详情]

验证您的错误是否在新构建的内核中出现。如果没有，请查阅参考部分中的说明，以确保您的测试期间没有出现任何意外情况。

[详情]

您刚刚构建了一个稳定版或长期版内核吗？并且您能够用它重现回归吗？那么您也应该测试最新的主线代码库，因为结果决定了该错误必须提交给哪些开发人员。

为了准备该测试，请检出当前主线
```
cd ~/linux/
git switch --discard-changes --detach mainline/master
```
现在使用检出的代码，按照前面步骤中已更详细描述的命令，构建并安装另一个内核
```
cp ~/kernel-config-working .config
make olddefconfig
make -j $(nproc --all)
# * Check if the free space suffices holding another kernel:
df -h /boot/ /lib/modules/
sudo make modules_install
command -v installkernel && sudo make install
make -s kernelrelease | tee -a ~/kernels-built
reboot
```
确认您启动了您打算启动的内核并检查其污染状态
```
tail -n 1 ~/kernels-built
uname -r
cat /proc/sys/kernel/tainted
```
现在验证此内核是否显示问题。如果显示，则需要向主要开发人员报告该错误；如果未显示，则报告给稳定版团队。有关详细信息，请参阅报告问题。

[详情]

您是否遵循本指南来验证问题是否存在于 Linux 内核开发人员当前支持的代码中？那么您到此就完成了。如果您以后想删除刚刚构建的内核，请查阅补充任务：遵循本指南期间和之后的清理工作。

如果您遇到回归，请继续并至少执行下一个部分。

第 2 部分：检查您构建的内核是否正常工作¶

如果出现回归，您现在需要确保您之前创建的精简配置文件按预期工作；否则使用 .config 文件进行二分查找将是浪费时间。 [详情]

构建您自己的“工作”内核变体，并检查出现回归的特性是否按预期工作。

首先检出您之前确定为“良好”版本的源代码（这里再次假设为 6.0）
```
cd ~/linux/
git switch --discard-changes --detach v6.0
```
现在使用检出的代码，按照前一小节更详细解释的命令，配置、构建并安装另一个内核
```
cp ~/kernel-config-working .config
make olddefconfig
make -j $(nproc --all)
# * Check if the free space suffices holding another kernel:
df -h /boot/ /lib/modules/
sudo make modules_install
command -v installkernel && sudo make install
make -s kernelrelease | tee -a ~/kernels-built
reboot
```
系统启动后，您可能需要再次验证您启动的内核是否就是您刚刚构建的内核
```
tail -n 1 ~/kernels-built
uname -r
```
现在检查此内核是否按预期工作；如果不是，请查阅参考部分以获取进一步说明。

[详情]

第 3 部分：执行二分查找并验证结果¶

在所有准备工作和预防性构建都完成后，您现在可以开始二分查找了。这将使您构建相当多的内核——通常在更新到较新系列（例如从 6.0.13 到 6.1.5）时遇到回归，大约需要构建 15 个内核。但请不要担心，由于之前创建了精简的构建配置，这比许多人想象的要快得多：总的来说，在商用 x86 机器上，平均每个内核的编译时间通常只需 10 到 15 分钟。

开始二分查找并告知 Git 之前确定为“良好”版本（在以下示例命令中为 6.0）和“损坏”版本（6.1.5）
```
cd ~/linux/
git bisect start
git bisect good v6.0
git bisect bad v6.1.5
```
[详情]

现在使用 Git 检出的代码，按照之前介绍的命令构建、安装并启动内核
```
cp ~/kernel-config-working .config
make olddefconfig
make -j $(nproc --all)
# * Check if the free space suffices holding another kernel:
df -h /boot/ /lib/modules/
sudo make modules_install
command -v installkernel && sudo make install
make -s kernelrelease | tee -a ~/kernels-built
reboot
```
如果编译因某种原因失败，请运行 git bisect skip 并从头开始重新执行命令堆栈。

如果您在指南中跳过了“测试最新代码库”步骤，请查看其描述以了解为何此处有“df [...]”和“make -s kernelrelease [...]”命令。

重要提示：从这一点开始，后一个命令将打印可能让您觉得奇怪或错误的发布标识符——但它们并非如此，因为如果您在版本 6.1 和 6.2 之间进行二分查找，看到像“6.0-rc1-local-gcafec0cacaca0”这样的发布标识符是完全正常的。

[详情]

现在检查您刚刚构建的内核中出现回归的功能是否正常工作。

您可能再次需要首先确保您启动的内核就是您刚刚构建的内核
```
cd ~/linux/
tail -n 1 ~/kernels-built
uname -r
```
现在验证出现回归的功能在此内核二分查找点是否正常工作。如果正常工作，运行此命令
```
git bisect good
```
如果不行，运行此命令
```
git bisect bad
```
请务必确定您告诉 Git 的内容，因为一旦出错，剩余的二分查找将完全偏离轨道。

在二分查找进行期间，Git 将使用您提供的信息来查找并检出另一个二分查找点供您测试。在此过程中，它将打印类似“Bisecting: 675 revisions left to test after this (roughly 10 steps)”（二分查找中：此后还剩 675 个修订版本待测试（大约 10 步））的信息，以指示它预计还有多少更改需要测试。现在，使用上一步的说明构建并安装另一个内核；之后再次遵循此步骤中的说明。

重复此操作，直到完成二分查找——当 Git 在将更改标记为“良好”或“损坏”后打印出类似“cafecaca0c0dacafecaca0c0dacafecaca0c0da 是第一个坏提交”的信息时，即表示完成；紧接着它将显示有关罪魁祸首的一些详细信息，包括该更改的补丁描述。后者可能会填满您的终端屏幕，因此您可能需要向上滚动才能看到提及罪魁祸首的消息；或者，运行 git bisect log > ~/bisection-log。

[详情]

在告诉 Git 将源代码重置到二分查找之前的状态之前，将 Git 的二分查找日志和当前的 .config 文件存储在一个安全的地方
```
cd ~/linux/
git bisect log > ~/bisection-log
cp .config ~/bisection-config-culprit
git bisect reset
```
[详情]

尝试在最新主线代码的基础上回滚问题提交，以查看这是否修复了您的回归。

这是可选的，因为它可能无法实现或难以实现。如果是二分查找确定合并提交是罪魁祸首，则属于前一种情况；如果其他更改依赖于罪魁祸首，则属于后一种情况。但如果回滚成功，则值得构建另一个内核，因为它验证了二分查找的结果，二分查找很容易偏离轨道；它还将让内核开发人员知道，他们是否可以通过快速回滚来解决回归。

首先根据您二分查找的范围检出最新的代码库
- 您是否在稳定/长期系列中（例如 6.0.13 到 6.0.15 之间）遇到回归，但主线中没有发生？那么请像这样检出受影响系列的最新代码库
```
git fetch stable
git switch --discard-changes --detach linux-6.0.y
```
- 在所有其他情况下，检出最新的主线代码
```
git fetch mainline
git switch --discard-changes --detach mainline/master
```
  如果您二分查找的回归在稳定/长期系列中发生，并且也在主线中发生，那么还有一件事要做：查找主线提交 ID。为此，请使用 git show abcdcafecabcd 这样的命令来查看罪魁祸首的补丁描述。顶部附近会有一行类似“commit cafec0cacaca0 upstream.”或“Upstream commit cafec0cacaca0”；在下一个命令中使用该提交 ID，而不是二分查找所指责的 ID。
现在尝试通过指定其提交 ID 来回滚问题提交
```
git revert --no-edit cafec0cacaca0
```
如果失败，请放弃尝试并继续下一步；如果成功，请调整标签以方便识别并防止意外覆盖另一个内核
```
cp ~/kernel-config-working .config
./scripts/config --set-str CONFIG_LOCALVERSION '-local-cafec0cacaca0-reverted'
```
使用熟悉的命令序列构建内核，只是不复制基础 .config 文件
```
make olddefconfig &&
make -j $(nproc --all)
# * Check if the free space suffices holding another kernel:
df -h /boot/ /lib/modules/
sudo make modules_install
command -v installkernel && sudo make install
make -s kernelrelease | tee -a ~/kernels-built
reboot
```
现在最后一次检查让您执行二分查找的功能是否在该内核中正常工作：如果一切顺利，它应该不会出现回归。

[详情]

补充任务：二分查找期间和之后的清理¶

在遵循本指南期间和之后，您可能希望或需要删除一些已安装的内核：否则启动菜单会变得混乱或空间可能不足。

要删除您安装的某个内核，请查找其“kernelrelease”标识符。本指南将它们存储在“~/kernels-built”中，但以下命令也会打印它们
```
ls -ltr /lib/modules/*-local*
```
在大多数情况下，您会希望删除在实际二分查找期间（例如本指南的第 3 部分）构建的最旧内核。您事先创建的两个内核（例如，用于测试最新代码库和被认为是“良好”的版本）可能在以后验证某些内容时派上用场——因此最好保留它们，除非您的存储空间确实不足。

要删除内核（其 kernelrelease 标识符为“6.0-rc1-local-gcafec0cacaca0”）的模块，请首先删除包含其模块的目录
```
sudo rm -rf /lib/modules/6.0-rc1-local-gcafec0cacaca0
```
之后尝试以下命令
```
sudo kernel-install -v remove 6.0-rc1-local-gcafec0cacaca0
```
在相当多的发行版上，这将删除所有其他已安装的内核文件，同时从启动菜单中删除内核条目。但在某些发行版上，kernel-install 不存在，或者会留下引导加载器条目、内核映像和相关文件；在这种情况下，请按照参考部分所述将其删除。

[详情]

完成二分查找后，不要立即删除您设置的任何内容，因为您可能需要再次使用一些东西。哪些可以安全删除取决于二分查找的结果
- 您是否最初能用最新代码库重现回归，并且在二分查找后，通过在最新代码库上回滚问题提交解决了问题？那么您会希望保留这两个内核一段时间，但可以安全地删除所有发布标识符中带有“-local”的其他内核。
- 二分查找是否以合并提交结束，或因其他原因看起来可疑？那么您会希望尽可能多地保留内核几天：很可能您会被要求重新检查一些东西。
- 在其他情况下，最好保留以下内核一段时间：从最新代码库构建的内核，从被认为是“良好”版本创建的内核，以及您在实际二分查找过程中编译的最后三到四个内核。
[详情]

可选：测试回滚、补丁或后续版本¶

在报告错误期间或之后，您可能希望或可能会被要求测试回滚、调试补丁、提议的修复或其他版本。在这种情况下，请遵循这些说明。

更新您的 Git 克隆并检出最新代码。
- 如果您想测试主线，请在检出其代码之前获取其最新更改
```
git fetch mainline
git switch --discard-changes --detach mainline/master
```
- 如果您想测试稳定版或长期版内核，请首先添加包含您感兴趣系列的（在本例中为 6.2）分支，除非您之前已经这样做过
```
git remote set-branches --add stable linux-6.2.y
```
  然后获取最新更改并检出该系列的最新版本
```
git fetch stable
git switch --discard-changes --detach stable/linux-6.2.y
```
复制您的内核构建配置
```
cp ~/kernel-config-working .config
```
您的下一步取决于您想做什么
- 如果您只想测试最新的代码库，请直接进行下一步，您已经准备就绪了。
- 如果您想测试回滚是否修复了问题，请通过指定其提交 ID 来回滚一个或多个更改
```
git revert --no-edit cafec0cacaca0
```
  现在给该内核一个特殊标签，以方便识别并防止意外覆盖另一个内核
```
./scripts/config --set-str CONFIG_LOCALVERSION '-local-cafec0cacaca0-reverted'
```
- 如果您想测试补丁，请将补丁存储在一个文件（例如“/tmp/foobars-proposed-fix-v1.patch”）中，并像这样应用它
```
git apply /tmp/foobars-proposed-fix-v1.patch
```
  如果存在多个补丁，请对其他补丁重复此步骤。
  
  现在给该内核一个特殊标签，以方便识别并防止意外覆盖另一个内核
```
./scripts/config --set-str CONFIG_LOCALVERSION '-local-foobars-fix-v1'
```

使用熟悉的命令构建内核，只是不复制内核构建配置，因为这已经处理过了

make olddefconfig &&
make -j $(nproc --all)
# * Check if the free space suffices holding another kernel:
df -h /boot/ /lib/modules/
sudo make modules_install
command -v installkernel && sudo make install
make -s kernelrelease | tee -a ~/kernels-built
reboot

现在验证您是否启动了新构建的内核并进行检查。

[详情]

总结¶

您已到达分步指南的末尾。

您在遵循逐步指南时是否遇到了下文参考章节未能说明的麻烦？您发现了错误吗？或者您有改进指南的想法吗？

如果有以上任何情况，请发送简短说明或补丁给 Thorsten Leemhuis <linux@leemhuis.info> 以告知开发人员，理想情况下请抄送公共 Linux 文档邮件列表 <linux-doc@vger.kernel.org>。此类反馈对于进一步改进此文本至关重要，这符合每个人的利益，因为它将使更多的人能够掌握此处描述的任务。

分步指南的参考部分¶

本节包含上述分步指南中几乎所有项目的附加信息。

构建您自己的内核的准备工作¶

本节中的步骤为所有进一步的测试奠定了基础。 [...]

本指南所有后续部分的步骤都依赖于此处描述的步骤。

[返回分步指南]。

为紧急情况做好准备¶

创建一份全新备份，并备好系统修复和恢复工具。 [...]

请记住，您正在处理计算机，它们有时会做一些意想不到的事情——特别是如果您修改了操作系统内核等关键部分。这正是您在此过程中将要做的。因此，最好为可能出现的意外情况做好准备，即使它不应该发生。

如何验证错误并二分查找回归¶

流程精髓（即“TL;DR”）¶

如何验证错误和二分查找回归的分步指南¶

准备工作：设置所有内容以构建您自己的内核¶

第 1 部分：尝试使用最新代码库重现问题¶

第 2 部分：检查您构建的内核是否正常工作¶

第 3 部分：执行二分查找并验证结果¶

补充任务：二分查找期间和之后的清理¶

可选：测试回滚、补丁或后续版本¶

总结¶

分步指南的参考部分¶

构建您自己的内核的准备工作¶

为紧急情况做好准备¶

删除所有与外部维护的内核模块相关的内容¶

处理安全启动等技术¶

启动上一个正常工作的内核¶

空间要求¶

二分查找范围¶

安装构建要求¶

使用 Git 下载源代码¶

使用 bundle 下载 Linux 主线源代码¶

使用浅克隆下载 Linux 主线源代码¶

开始定义您的内核构建配置¶

精简您的内核构建配置¶

标记即将构建的内核¶

决定启用或禁用调试符号¶

调整构建配置¶

发行版特定调整¶

个性化调整¶

将 .config 文件放到一边¶

尝试使用最新代码库重现问题¶

检出最新的 Linux 代码库¶

构建您的内核¶

处理构建错误¶

打包您的内核¶

放置内核¶

每个内核的存储要求¶

检查您新构建的内核是否认为自己“被污染”¶

检查从最新主线代码库构建的内核¶

检查从最新稳定版/长期支持版代码库构建的内核¶

确保“良好”版本确实运行良好¶

构建您自己的“良好”内核版本¶

执行二分查找并验证结果¶

开始二分查找¶

从二分查找点构建内核¶

二分查找检查点¶

保存二分查找日志¶

尝试回溯肇事者¶

遵循本指南期间和之后的清理步骤¶

二分查找期间的清理¶

二分查找后的清理¶

测试回溯、补丁或后续版本¶

附加信息¶

在不同的机器上构建内核¶

其他阅读材料¶