Linux 内核补丁提交（Upstream）完整指南

本文档是一份面向 AMD GPU 驱动开发者的内核补丁提交实操指南涵盖从环境准备到 patch 发送、review 跟进的全部流程。适用于通过邮件列表向 Linux 社区提交 patch series 的场景。目录概述第一阶段环境准备第二阶段代码准备第三阶段Commit Message 规范第四阶段质量检查第五阶段生成 Patch Series第六阶段发送 Patch第七阶段Review 与迭代附录概述Linux 内核采用邮件列表 patch 的协作模式。开发者将代码变更格式化为 patch通过git send-email发送到对应的邮件列表由 maintainer 和社区成员进行 review经过若干轮修改后被 maintainer 合入merge。典型的 AMD GPU 驱动 patch 合入路径开发者 patch → amd-gfx 邮件列表 review → amd-staging-drm-next 分支 → drm-next → linux-next → Linus mainline第一阶段环境准备1.1 安装 git send-emailgit send-email是发送 patch 的标准工具大多数发行版需要单独安装# Debian / Ubuntusudoaptinstallgit-email# Fedora / RHELsudodnfinstallgit-email# Arch Linuxsudopacman-Sgit验证安装gitsend-email--help1.2 配置 SMTP在~/.gitconfig中添加 SMTP 配置。以下为常见邮件服务的示例Office365 / Outlook企业常用[sendemail] smtpserver smtp.office365.com smtpserverport 587 smtpencryption tls smtpuser your.namecompany.com from Your Name your.namecompany.comGmail[sendemail] smtpserver smtp.gmail.com smtpserverport 587 smtpencryption tls smtpuser yournamegmail.com from Your Name yournamegmail.com注意Gmail 需要开启应用专用密码App Password不能使用普通密码。部分企业邮箱需要 IT 部门开启 SMTP 访问或提供 App Password。首次发送时 git 会提示输入密码可通过git credential缓存。1.3 配置 git 用户信息确保 git 用户信息与你的邮件列表注册信息一致gitconfig--globaluser.nameYour Namegitconfig--globaluser.emailyour.namecompany.com1.4 订阅相关邮件列表在发送 patch 之前务必先订阅目标邮件列表否则你的邮件可能被 moderation 队列阻拦且你无法收到 review 回复。常用 DRM / AMD GPU 相关列表邮件列表订阅地址amd-gfxhttps://lists.freedesktop.org/mailman/listinfo/amd-gfxdri-develhttps://lists.freedesktop.org/mailman/listinfo/dri-devellinux-kernel (LKML)http://vger.kernel.org/vger-lists.html#linux-kernel提示LKML 邮件量极大建议不订阅或配置邮件过滤规则。通常只 Cc 即可不需要主动阅读 LKML 上的所有邮件。第二阶段代码准备2.1 选择正确的基线分支你的 patch 必须基于正确的上游分支。选择错误的基线会导致 patch 无法应用。# 添加上游 remote如果还没有gitremoteadddrm-misc https://gitlab.freedesktop.org/drm/misc/kernel.gitgitremoteaddupstream https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git# 获取最新代码gitfetch drm-miscgitfetch upstream# 基于 drm-next 创建工作分支gitcheckout-bmy-feature drm-misc/drm-next不同子系统的基线分支选择子系统推荐基线AMD GPU (amdgpu)amd-staging-drm-next或drm-nextDRM coredrm-misc-next内存管理 (mm)mm-unstable或linux-next通用内核torvalds/master2.2 Rebase 到最新基线gitrebase drm-misc/drm-next解决所有冲突后确保编译通过。2.3 整理 commit 历史每个 commit 应该是一个逻辑完整、可独立编译的变更单元。使用 interactive rebase 整理gitrebase-ibase-commit整理原则一个 commit 做一件事— 不要在一个 commit 中混合功能添加和 bug 修复每个 commit 都能编译通过— bisect 友好合理的提交顺序— 基础设施先行功能实现随后最后接入wire-up不要有 fixup commit— 应该 squash 到对应的 commit 中第三阶段Commit Message 规范3.1 格式要求subsystem: 简短描述 (不超过 72 字符) 详细描述解释 what做了什么和 why为什么要做 而不是 how怎么做的代码本身会说明。 如果有多个段落用空行分隔。 可以使用列表 - 第一点 - 第二点 Signed-off-by: Your Name your.namecompany.com3.2 标题行规则格式:子系统前缀: 简短描述不超过72 个字符首字母小写前缀后的第一个单词不以句号结尾使用祈使语气“add support” 而非 “added support”AMD GPU 驱动常见前缀示例drm/amdgpu: # amdgpu 驱动通用 drm/amdgpu/vcn: # VCN 子模块 drm/amdkfd: # KFD 子模块 drm/amd/pm: # 电源管理 drm/amd/display: # 显示3.3 描述正文解释为什么需要这个变更动机、问题背景描述做了什么高层设计思路如果是 bug 修复描述问题的根因和修复方式引用相关的讨论链接如有每行不超过75 个字符3.4 Signed-off-by (SOB)每个 commit必须有Signed-off-by标签表示你同意 Developer Certificate of Origin (DCO)Signed-off-by: Your Name your.namecompany.com⚠️警告SOB 邮箱必须与 Author 邮箱一致。如果git config user.email是Your.Namecompany.com则 SOB 也必须是同一个地址大小写保持一致。使用git commit -s可以自动添加 SOB。3.5 其他常用标签# 此 patch 修复了某个 commit 引入的 bug Fixes: 12位hash (原 commit 标题) # 经过某人 review 同意 Reviewed-by: Reviewer Name revieweremail.com # 经过某人测试验证 Tested-by: Tester Name testeremail.com # 致谢例如某人提供了想法或早期代码 Suggested-by: Someone someoneemail.com # 抄送将 patch 邮件抄送给特定的人 Cc: Someone someoneemail.com第四阶段质量检查4.1 运行 checkpatch.pl这是必须执行的步骤。checkpatch 会检查代码风格、commit message 格式等# 检查最近 N 个 commitgitformat-patch-N-o/tmp/patches/ scripts/checkpatch.pl /tmp/patches/*.patch# 或者直接检查 git commitscripts/checkpatch.pl--gitHEAD~N..HEAD修复所有ERROR。对于WARNING大部分也应修复如果确实无法避免需要在 cover letter 中说明理由。常见的 checkpatch 问题行超过 80/100 字符缺少空行注释格式不对commit message 标题超过 72 字符尾部多余空白4.2 编译检查确保每个 commit 都能独立编译通过# 基本编译makeMdrivers/gpu/drm/amd/amdgpu# 启用 sparse 静态分析makeC1Mdrivers/gpu/drm/amd/amdgpu# 完整内核编译如果改动涉及头文件make-j$(nproc)# 启用更多警告makeW1Mdrivers/gpu/drm/amd/amdgpu4.3 运行测试根据你的变更运行相关测试IGT GPU Tools:igt_runner测试套件KFD 测试:kfdtest内核自测试:make kselftest在 cover letter 中描述你的测试方法和结果。4.4 检查文档如果你的变更涉及 UAPI用户空间接口、新的 sysfs/debugfs 节点、或新的 ioctl需要同步更新文档# 构建文档检查makehtmldocs# 检查是否有文档警告makehtmldocs21|grep-iwarning第五阶段生成 Patch Series5.1 使用 git format-patch# 生成 patch series含 cover lettergitformat-patch-N--cover-letter-o/tmp/patches/# 参数说明# -N 最近 N 个 commit# --cover-letter 生成 cover letter0000-cover-letter.patch# -o DIR 输出目录# --baseauto 自动记录基线信息推荐# 完整示例gitformat-patch-5--cover-letter--baseauto-o/tmp/patches/\--subject-prefixPATCH5.2 Subject Prefix 约定前缀含义[PATCH]首次提交[PATCH v2]第二版响应 review 修改后[PATCH RFC]征求意见稿不期望直接合入[PATCH RESEND]重新发送无修改[PATCH 0/N]Cover letterN 个 patch 的系列通过--subject-prefix指定# RFC patchgitformat-patch --subject-prefixRFC PATCH...# 第二版gitformat-patch --subject-prefixPATCH v2...5.3 撰写 Cover LetterCover letter 是整个 patch series 的总览是 reviewer 首先阅读的内容。编辑生成的0000-cover-letter.patchSubject: [PATCH 0/N] subsystem: 整个 series 的简短描述 这个 patch series 实现了 XXX 功能。 背景与动机 描述为什么需要这组变更解决什么问题。 设计概述 高层描述整体设计方案。 依赖关系 如果依赖其他尚未合入的 patch series在此说明 - 依赖: [PATCH vN] series title by Author https://lore.kernel.org/链接 测试 描述测试方法 - 硬件平台: GPU 型号 - 测试用例: IGT / kfdtest / 自定义测试 - 测试结果 变更历史v2 及以后版本需要 v2: - 修复了 XXX 问题 (Reviewer 的建议) - 重构了 YYY 函数 v1: - https://lore.kernel.org/初次提交链接 Your Name (N): subsystem: patch 1 标题 subsystem: patch 2 标题 ... file1.c | 100 file2.h | 20 N files changed, X insertions(), Y deletions(-)5.4 确认收件人使用get_maintainer.pl自动确定收件人scripts/get_maintainer.pl /tmp/patches/*.patch输出会列出所有相关的 maintainer 和邮件列表。一般规则To:Subsystem maintainer(s) 主要邮件列表Cc:更上层的 maintainer 更广泛的邮件列表 相关开发者提示get_maintainer.pl的输出可以直接作为git send-email的参数scripts/get_maintainer.pl--separator, /tmp/patches/*.patch第六阶段发送 Patch6.1 先发送测试邮件强烈建议先发给自己测试gitsend-email--toyourselfemail.com /tmp/patches/*.patch检查收到的邮件格式是否正确纯文本非 HTMLpatch 能否通过git am应用编码没有乱码线程关系正确cover letter 为父各 patch 为回复6.2 正式发送gitsend-email\--toMaintainer1 maintainer1email.com\--toMaintainer2 maintainer2email.com\--tosubsystem-listlists.freedesktop.org\--ccdri-devellists.freedesktop.org\--cclinux-kernelvger.kernel.org\/tmp/patches/*.patchgit send-email会逐个发送并提示确认。6.3 验证发送成功发送后在以下平台验证你的 patch 已出现lore.kernel.org: https://lore.kernel.org/ 搜索你的 patch 标题Patchwork: https://patchwork.freedesktop.org/project/amd-gfx/ 如果目标是 amd-gfx 列表第七阶段Review 与迭代7.1 响应 review 意见及时回复— 收到 review 后尽快回复即使是说感谢我会在 v2 中修复逐条回应— 对每条 review 意见给出回复保持礼貌— 即使不同意也要说明理由不要忽略底部回复 (bottom-post)— Linux 社区使用底部回复风格不要顶部回复回复示例 Review comment about your code Suggestion to change XXX Good point. Ill fix this in v2. The new approach will be ...7.2 提交 v2修订版根据 review 修改代码后# 修改 commitrebase -i, amend 等gitrebase-ibase# 生成 v2 patchgitformat-patch-N--cover-letter--baseauto\--subject-prefixPATCH v2-o/tmp/patches-v2/# 在 cover letter 中添加变更历史# 发送gitsend-email... /tmp/patches-v2/*.patch注意v2 发送时收件人列表保持与 v1 相同并加上在 v1 中给出 review 意见的人。7.3 添加 Reviewed-by / Acked-by如果 reviewer 给出了Reviewed-by或Acked-by标签在 v2 中将其添加到对应 commit 的 SOB 区域Signed-off-by: Your Name youremail.com Reviewed-by: Reviewer Name revieweremail.com7.4 等待与催促正常等待— 1-2 周是正常的 review 周期催促 (ping)— 超过 2 周没有回复可以回复自己的 patch 邮件 ping 一下RESEND— 如果怀疑邮件丢失可以用[PATCH RESEND]重发合入确认— patch 被接受后maintainer 会回复或在 patchwork 标记状态附录A. 常用命令速查# 生成 patchgitformat-patch-N--cover-letter--baseauto-o/tmp/patches/# 检查代码风格scripts/checkpatch.pl /tmp/patches/*.patch# 查找 maintainerscripts/get_maintainer.pl /tmp/patches/*.patch# 发送 patchgitsend-email--to...--cc... /tmp/patches/*.patch# 应用收到的 patchreviewer 测试用gitam /path/to/patch.mbox# 检查 commit messagegitlog--oneline-NB. 重要参考文档文档链接内核官方补丁提交指南https://www.kernel.org/doc/html/latest/process/submitting-patches.html内核编码风格https://www.kernel.org/doc/html/latest/process/coding-style.html邮件客户端配置指南https://www.kernel.org/doc/html/latest/process/email-clients.html内核邮件列表存档与搜索https://lore.kernel.org/DRM 子系统 patch 跟踪https://patchwork.freedesktop.org/C. Checklist提交前检查清单环境准备git send-email已安装SMTP 已配置且测试通过已订阅目标邮件列表代码质量基于正确的上游分支drm-next/amd-staging-drm-next每个 commit 逻辑独立、可编译checkpatch.pl无 ERROR编译通过含 sparse 检查相关测试通过Commit Message标题 ≤72 字符格式正确正文描述 what 和 whySigned-off-by邮箱与 Author 一致有Fixes标签如果是 bug 修复提交材料Cover letter 已撰写背景、设计、测试、变更历史get_maintainer.pl确认收件人测试邮件发送成功正式 patch 已发送lore.kernel.org 可搜索到