#分享 怎麼給 Linux Kernel 發 patch?

2022年12月6日 21:37 (已編輯)
一直以來都很希望可以參與Linux kernel 的開發,但是一直都沒去實踐。 直到最近在等上工的空檔,終於實際的發第一個patch啦~~
sticker
內文主要提供給想發patch的開發者參考,如果任何地方有誤還請大神們指正! 附上 Hackmd好讀版
------ 以下正文------ ¶ 建議直接閱讀 FirstKernelPatch(註1) # 怎麼給 Linux Kernel 發 patch? 花了兩天的時間按照FirstKernelPatch的步驟做了一遍後,成功的提交patch,本文希望讓不得其門而入的開發者,可以更容易的加入貢獻Linux Kernel的行列。 建議本文讀者使用過Unix-like作業系統,且熟悉shell操作 ## 事前準備 由於我是直接使用 Ubuntu 做測試,因此若使用虛擬機或不同發行版本,所使用的指令以及結果會不盡相同。 - 一部Ubuntu主機 ### 安裝開發工具 ```shell= sudo apt-get install vim libncurses5-dev gcc make git exuberant-ctags libssl-dev bison flex libelf-dev bc dwarves zstd git-email esmtp mutt gitk ``` ### 下載原始碼 1. 用以下指令下載原始碼 執行下列指令 ```shell= git clone -b staging-testing git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git cd staging ``` 2. 設定kernel配置 執行下列指令 ```shell= cp /boot/config-`uname -r`* .config ``` ### 工具設定 1. 設定vim為預設編輯器 執行下列指令 ```shell= sudo update-alternatives --config editor ``` 選擇`/usr/bin/vim.basic`為預設編輯器 2. 設定Email 由於我用的是Gmail,因此只列出Gmail的設定方式,FirstKernelPatch中有Yahoo的設定方式 設定步驟:設定 -> 轉寄和PIP/IMAP -> IMAP存取 -> 儲存變更 4. esmtp配置 執行下列指令 ```shell= touch ~/.esmtprc chmod g-rwx ~/.esmtprc chmod o-rwx ~/.esmtprc ``` 編輯`.esmtprc`,新增下列幾行,將Email帳號密碼改成自己的 ```= identity "my.email@gmail.com" hostname smtp.gmail.com:587 username "my.email@gmail.com" password "ThisIsNotARealPassWord" starttls required ``` 編輯`.muttrc`,新增下列幾行,將Email帳號改成自己的 ```= set sendmail="/usr/bin/esmtp" set envelope_from=yes set from="Your Name <my.email@gmail.com>" set use_from=yes set edit_headers=yes ``` 4. 測試Email設定 執行下列指令 ```shell= mutt ``` 進入`mutt`應用程式,然後按照下列步驟寄信給自己作為測試,#之後為解釋 1. no #不要建立收件夾 2. m #建立新的訊息 3. my.email@gmail.com #輸入自己的信箱 4. test #標題 #這時會跳出`vim`的畫面,內容如下 ```= From: example <example@gmail.com> To: example@gmail.com Cc: Bcc: Subject: test Reply-To: ``` 5. 在`Reply-To`的下一行打入信件內容,`i`進入編輯模式,`Esc`離開編輯模式,其他操作可參考 Vim 筆記(註2) 6. 離開編輯模式,輸入`:wq`儲存並離開`vim` 7. y #寄出訊息 如果沒有成功收到測試信件,可以用`mutt -d 2`再做一次操作,查看錯誤訊息 5. 設定git 編輯`.gitconfig`,加入下列內容,將名字跟Email改成自己的。 ```= [user] name = my.name email = my.email@example.com [sendmail] smtpserver = /usr/bin/esmtp ``` 須注意該Email要跟前面設定的是同一個,否則不會被接受 ¶ The Linux kernel developers will not accept a patch where the "From" email differs from the "Signed-off-by" line, which is what will happen if these two emails do not match. ### 更新kernel到最新板 由於kernel時常在更新,若你的版本不是最新版,patch有可能會被拒絕 ```shell= git fetch origin ``` 在`fetch`之後,觀察以下指令之輸出,可以發現當前的檔案並沒有任何的修改 ```shell= git log ``` 加上特定的branch name即可看到變化 ```shell= git log origin/staging-testing ``` 由於我們主要是針對最新板的程式碼做改動,因此要`rebase`更新,其中如果有發生衝突,要再修改你的commit ```shell= git rebase origin/staging-testing ``` ### 修改Driver 透過`lsmod`查看當前電腦載入的驅動程式,從中選出任意的驅動程式,以下用驅動程式`ee1004`為例 ```shell= git grep ee1004 -- '*Makefile' # 找出ee1004驅動程式原始碼,以下為輸出 # drivers/misc/eeprom/Makefile:obj-$(CONFIG_EEPROM_EE1004) += ee1004.o vim drivers/misc/eeprom/ee1004.c # 在該檔案的ee1004_probe() function中 # 加入 printk(KERN_DEBUG "I can modify the Linux kernel!\n"); ``` ### 編譯kernel ```shell= make # 單核心編譯 make -jX # 多核心編譯,X = 核心數量 ``` ### 安裝改動 ```shell= sudo make modules_install install ``` ### 測試改動 在完成上述步驟之後,需要重新啟動,查看改動是否成功。 重起之後,用以下指令檢查是否有 "I can modify the Linux kernel!" ```shell= dmesg | grep "I can modify the Linux kernel!" ``` 如果有的話代表你成功編譯並啟動了kernel。 若未成功,請到 IRC 的 #kernel-outreachy 尋求幫助 ### 恢復改動 到目前為止只是簡單的測試,你並不會提交這個改動,因此你可以透過下列指令恢復改動 ```shell= git reset --hard HEAD ``` ## 開始你的第一個patch ### 自動檢查 git commit 首先,由於kernel有很多的協作者,因此制定了很嚴格的coding style(註3),由於太多規則,因此開發者們製作了`checkpatch.pl`來自動檢查,你無須開啟每個檔案用人工的上檢查是否符合規範,僅須透過該工具找出不符合規範的程式碼做修改。 其次,除了程式碼的撰寫風格有嚴謹的規範以外,commit也同樣有撰寫風格的規範,也同樣有檢查工具,我們要修改`.git/hooks/post-commit`的內容為 ```= #!/bin/sh exec git show --format=email HEAD | ./scripts/checkpatch.pl --strict --codespell ``` 透過下列指令啟用 ```shell= apt-get install codespell python-ply python-git chmod a+x .git/hooks/post-commit ``` 設定完成後,未來`git`會自動檢查你所寫的commit,若有任何的錯誤或警告是你所新增的,可以透過下列指令對commit做修改 ```shell= git commit --amend ``` ### 測試自動檢查是否成功運作 使用指令,直接對最新的commit做改動,加入多餘的空行 ```shell= git commit --amend ``` 理應偵測到最新的改動,並且發出警示,若沒有發出警示,請上 IRC 尋求幫助 ### 了解patch 在你建立自己的patch之前,你必須先了解如何建立一個好的patch,這可以讓你的patch更容易被維護者接受。 請閱讀PatchPhilosophy(註4)以及CodingStyle。 雖然有`checkpatch.pl`,但還是要自己判端是否需要進行改動。另外,請閱讀CheckpatchTips(註5)以避免提交非必要的改動。 ### 清理driver 在`drivers/staging/`中,有許多的driver是不符合CodingStyle的,因此我們的第一個patch可以很簡單的從這裡開始。 另外,有些驅動程式還有一些尚未實做完成的功能,可以查找`TODO`來知道有哪些功能需要您的貢獻 ```shell= find drivers/staging -name TODO ``` 我們可以透過下列指令找出是否有檔案存在coding style的問題,我用`vme_user`作為範例 ```shell= perl scripts/checkpatch.pl -f drivers/staging/vme_user/* | less ``` 選定其中的任一警告作為你的第一個patch做修正。未來你可以一次修改多個警告,但是建議遵從PatchPhilosophy的指示發patch,以免被拒絕。 最後,請重新編譯以及載入驅動程式 ```shell= make -j2 && sudo make modules_install sudo modprobe -r <module_name> sudo modprobe <module_name> ``` ### commit 你的改動 1. 查看你的改動 ```shell= git status git diff ``` 2. 添加你的改動 ```shell= git add # 一次加入所有改動過得檔案 git add <file> # 加入檔案 ``` 這時候你再執行`git diff`時,就不會看到輸出,因為diff會輸出 unstaged changes,但是你`add`之後,那些改動就是staged changes了,可以使用下列指令查看staged changes ```shell= git diff --cached ``` 3. 回復你的改動 ```shell= git reset <file> ``` 4. commit改動 使用以下指令編寫commit,`-s`代表添加 `Signed-off-by`到patch的底部,`-v`代表在patch中放入你改動的部份 ```shell= git commit -s -v ``` commit 的標題必須以`staging:`開頭,建議透過`git log --oneline`查看前人的撰寫方式。 commit 的標題與內容之間應有一行的空行。 5. 檢視你的commit ```shell= git show HEAD ``` ### 提交你的patch 1. 找到你的patch要提交給誰。 每一個driver都有不同的維護者,而你的patch就是要提交給維護該driver的維護者。同樣的,可以透過工具查找出該driver的維護者有哪些。 ```shell= git show HEAD | perl scripts/get_maintainer.pl --separator , --nokeywords --nogit --nogit-fallback --norolestats -f drivers/staging/ # 或者,直接指定檔名,找出維護者 perl scripts/get_maintainer.pl --separator , --nokeywords --nogit --nogit-fallback --norolestats -f drivers/staging/vme_user # 輸出如下 # Martyn Welch <martyn@welchs.me.uk>,Manohar Vanga <manohar.vanga@gmail.com>,Greg Kroah-Hartman <gregkh@linuxfoundation.org>,linux-kernel@vger.kernel.org,linux-staging@lists.linux.dev ``` 2. 使用`git format-patch`建立patch ```shell= git format-patch -o /tmp/ HEAD^ ``` 3. 寄出patch 1. 透過`mutt`寄出你的patch ```shell= mutt -H /tmp/0001-<Whaever your filename is> ``` 2. 透過`git send-email`寄出(我是用這個) ```shell= git send-email --annotate HEAD^ ``` 這會接著問你要寄給誰,直接將剛剛找到的維護者名單(包含Email)貼上,接著寄出即可。 ## 後記 我在 2022/12/04 寄出patch,並於 2022/12/05收到回覆說會放到`staging-testing` branch中。 現在`staging-testing`分支中,已經有加上我的patch啦~~ 註1
註2
註3
註4
註5
愛心
50
留言 6
文章資訊