• HowToDoLinuxKernelDevelopment

HOWTO do Linux kernel development

如何從事 Linux 核心 開發

This is the be-all, end-all document on this topic. It contains instructions on how to become a Linux kernel developer and how to learn to work with the Linux kernel development community. It tries to not contain anything related to the technical aspects of kernel programming, but will help point you in the right direction for that.

這是 這個主題最重要的文件. 它包括如何成為 Linux 核心開發者 以及 如何學習 和 Linux 核心開發社群 一同作業的指示. 這份文件試著不包括任何有關撰寫核心 程式技術性論點, 但將幫助導引你至相關的正確方向.

If anything in this document becomes out of date, please send in patches to the maintainer of this file, who is listed at the bottom of the document.

如果這份文件裡的任何事物過時了, 請在修補程式裡傳送給此文件的維護人員. 維 護人員列於文件結尾.

Introduction

序言

So, you want to learn how to become a Linux kernel developer? Or you have been told by your manager, "Go write a Linux driver for this device." This document's goal is to teach you everything you need to know to achieve this by describing the process you need to go through, and hints on how to work with the community. It will also try to explain some of the reasons why the community works like it does.

所以,你想要學習如何成為一個 Linux 系統核心開發者? 或者你被經理告知, " 替這個設備寫一份驅動程式吧." 這份文件的目標是教導每件你需要知道來達成 這個目標的事. 藉由闡述你必須經歷的過程, 以及 如何和社群合作的注意事項. 這份文件也試解釋某些社群如此運作的理由.

The kernel is written mostly in C, with some architecture-dependent parts written in assembly. A good understanding of C is required for kernel development. Assembly (any architecture) is not required unless you plan to do low-level development for that architecture. Though they are not a good substitute for a solid C education and/or years of experience, the following books are good for, if anything, reference:

• - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] - "Practical C Programming" by Steve Oualline [O'Reilly]

核心大多以 C 語言 撰寫, 加上某些架構依附的組合語言. 對 C 有良好程度的瞭 解是對核心開發而言是必須的. 組合語言 (任何架構) 不是必要的 除非你計劃針 對某架構作低階開發. 雖然它們不是提供一個穩固的C的訓練 以及/或 多年經驗 的 良好的替代品, 底下的書籍, 若有區別的話, 是不錯的參考:

• - "The C Programming Language" Kernighan 和 Ritchie著 [Prentice Hall] - "Practical C Programming" Steve Oualline著 [O'Reilly]

The kernel is written using GNU C and the GNU toolchain. While it adheres to the ISO C89 standard, it uses a number of extensions that are not featured in the standard. The kernel is a freestanding C environment, with no reliance on the standard C library, so some portions of the C standard are not supported. Arbitrary long long divisions and floating point are not allowed. It can sometimes be difficult to understand the assumptions the kernel has on the toolchain and the extensions that it uses, and unfortunately there is no definitive reference for them. Please check the gcc info pages (`info gcc`) for some information on them.

核心是使用 GNU C 和 GNU 的軟體開發工具撰寫.它遵守 ISO C89 標準,然而也使 用一些非標準的延伸語法. 核心是一個獨立式的 C 環境,並不依賴標準的 C 函式 庫, 所以部份程度的 C 標準 語法並不支援. 隨意的長除法[?]和浮點數並不被允 許. 它有時後很難去理解核心在開發工具上擁有的假設 以及 它使用的延伸語法, 還有很不幸地 沒有可靠的參考文獻. 針對它們上面的某些資訊請查詢 gcc info 頁面 (info gcc).

Please remember that you are trying to learn how to work with the existing development community. It is a diverse group of people, with high standards for coding, style and procedure. These standards have been created over time based on what they have found to work best for such a large and geographically dispersed team. Try to learn as much as possible about these standards ahead of time, as they are well documented; do not expect people to adapt to you or your company's way of doing things.

請記得你是試著學習如何和既存的開發社群合作. 它是一個多元化的人們組成的 團體, 有著高水準的程式碼, 風格 和 規範. 這些標準已經行之有年 奠基於他 們發現對如此龐大和地理區域分散的團隊最佳的工作模式. 試著儘量提早學習這 些標準, 如同它們被良好文件記錄; 別期待其它人適應你或你的公司作事的方事.

Legal Issues

法律議題

The Linux kernel source code is released under the GPL. Please see the file, COPYING, in the main directory of the source tree, for details on the license. If you have further questions about the license, please contact a lawyer, and do not ask on the Linux kernel mailing list. The people on the mailing lists are not lawyers, and you should not rely on their statements on legal matters.

For common questions and answers about the GPL, please see:

• http://www.gnu.org/licenses/gpl-faq.html

Linux 核心原始碼是依據GPL釋出. 詳細授權方式請參照COPYING檔,它在原始碼的 主要目錄裡. 如果對授權方式有進一步的問題, 請聯繫律師, 且勿在Linux核心 郵件論壇詢問. 論壇上的人不是律師, 且在法律事務上你不應該依賴他們的聲明.

針對GPL一般問題和解答, 請參考:

• http://www.gnu.org/licenses/gpl-faq.html

Documentation

文件

The Linux kernel source tree has a large range of documents that are invaluable for learning how to interact with the kernel community. When new features are added to the kernel, it is recommended that new documentation files are also added which explain how to use the feature. When a kernel change causes the interface that the kernel exposes to userspace to change, it is recommended that you send the information or a patch to the manual pages explaining the change to the manual pages maintainer at mtk-manpages@gmx.net.

Linux 核心原始碼有一系列大量的文件 那些文件對於學習如何和核心社群溝通是 非常重要的. 當新的特色被加入到核心, 通常會被建議新的文件檔也該被加入以 說明如何使用該項功能. 當核心改變導致使用者空間的核心介面改變, 通常建議 你傳送資訊或是修補程式手冊解釋改變給 mtk-manpages@gmx.net 的手冊維護人員.

Here is a list of files that are in the kernel source tree that are required reading:

• README
  • This file gives a short background on the Linux kernel and describes what is necessary to do to configure and build the kernel. People who are new to the kernel should start here.

這兒是一份在核心原始碼裡需要被閱讀的檔案清單:

• README[1]
  • 這份檔案提供Linux核心簡短的背景和說明設定(configure)和建構(build)核 心需要作的事. 剛接觸核心的人應該從這裡開始.
  Documentation/Changes
  • This file gives a list of the minimum levels of various software packages that are necessary to build and run the kernel successfully.
  Documentation/Changes[1]
  • 這份檔案提供能成功地建構(build)和執行(run)核心所需最少限度各式軟體 套件清單.
  Documentation/CodingStyle
  • This describes the Linux kernel coding style, and some of the rationale behind it. All new code is expected to follow the guidelines in this document. Most maintainers will only accept patches if these rules are followed, and many people will only review code if it is in the proper style.
  Documentation/CodingStyle[1]
  • 這份文件闡述Linux 核心撰寫方式, 以及背後部份理由. 所有新的程式碼 被預期遵守這份文件裡的方針. 大多數維護人員僅接受遵守歸則的修補程 式, 且大部份的人將只重新檢閱合宜的程式碼.
  Documentation/SubmittingPatches Documentation/SubmittingDrivers
  • These files describe in explicit detail how to successfully create and send a patch, including (but not limited to):
    • - Email contents - Email format - Who to send it to
    Following these rules will not guarantee success (as all patches are subject to scrutiny for content and style), but not following them will almost always prevent it.
  Documentation/SubmittingPatches[1] Documentation/SubmittingDrivers[1]
  • Other excellent descriptions of how to create patches properly are:
    • "The Perfect Patch"

      • http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt

      "Linux kernel patch submission format"

      • http://linux.yyz.us/patch-format.html

    其它優秀的解說如何正確地製作修補程式有:
    • "完美的修補程式"

      • http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt

      "Linux 核心修補程式遞交格式"

      • http://linux.yyz.us/patch-format.html

  Documentation/stable_api_nonsense.txt
  • This file describes the rationale behind the conscious decision to not have a stable API within the kernel, including things like:
    • - Subsystem shim-layers (for compatibility?) - Driver portability between Operating Systems. - Mitigating rapid change within the kernel source tree (or
      • preventing rapid change)
    This document is crucial for understanding the Linux development philosophy and is very important for people moving to Linux from development on other Operating Systems.
  Documentation/stable_api_nonsense.txt[1]
  • 這份檔案解釋核心裡不要有穩定的 應用程式介面(API) 意識決策的背後原因, 包括:
    • - 子系統 填隙階層(shim-layers) - 驅動程式 在作業系統間的移植性 - 減緩核心來源樹快速變動 (或 避免快速變動)
    這份文件對瞭解Linux開發哲學很關鍵且對人們從其它作業系統開發轉移至 Linux相當重要.
  Documentation/SecurityBugs
  • If you feel you have found a security problem in the Linux kernel, please follow the steps in this document to help notify the kernel developers, and help solve the issue.
  Documentation/SecurityBugs[1]
  • 如果你覺得你已經找到一個Linux 核心裡的安全性問題, 請依照這份文件裡 的步驟幫助通知核心開發者, 及幫助解決該議題.
  Documentation/ManagementStyle
  • This document describes how Linux kernel maintainers operate and the shared ethos behind their methodologies. This is important reading for anyone new to kernel development (or anyone simply curious about it), as it resolves a lot of common misconceptions and confusion about the unique behavior of kernel maintainers.
  Documentation/ManagementStyle[1]
  • 這份文件解釋Linux核心維護人員如何操作和分想他們方法論背後的特質. 這 對任何新接觸核心開發的人很重要的閱讀材料(或 任何僅對核心好奇的人), 因為它解答了許多錯誤觀念和關於核心維護人原獨特行為的困惑.
  Documentation/stable_kernel_rules.txt
  • This file describes the rules on how the stable kernel releases happen, and what to do if you want to get a change into one of these releases.
  Documentation/stable_kernel_rules.txt[1]
  • 這份檔案描述穩定的核心的釋出如何發生的規則, 以及 如果你想要在這些釋出 當中取得一份變更該怎麼作.
  Documentation/kernel-docs.txt
  • A list of external documentation that pertains to kernel development. Please consult this list if you do not find what you are looking for within the in-kernel documentation.
  Documentation/kernel-docs.txt[1]
  • 關於核心開發的一份外部文件清單. 請參考這份清單如果在核心文件裡搜尋找 不著你想要的.
  Documentation/applying-patches.txt
  • A good introduction describing exactly what a patch is and how to apply it to the different development branches of the kernel.
  Documentation/applying-patches.txt[1]
  • 一個好的簡介精確的說明什麼是修補程式以及如何使其適用於其它不同的核心 開發支線.

The kernel also has a large number of documents that can be automatically generated from the source code itself. This includes a full description of the in-kernel API, and rules on how to handle locking properly. The documents will be created in the Documentation/DocBook/ directory and can be generated as PDF, Postscript, HTML, and man pages by running:

• make pdfdocs make psdocs make htmldocs make mandocs

respectively from the main kernel source directory.

核心也有可以從原始碼自動產生的大量文件. 這包括了一份完整的核心API說明, 及 如何正確處理死結的規則. 文件都會被建立在 Document/DocBook 目錄底下且可以 產生成PDF, Postscript, HTML, 還有 man pages 藉由執行:

• make pdfdocs make psdocs make htmldocs make mandocs

個別地從主要核心原始目錄.

Becoming A Kernel Developer

成為一個核心開發者

If you do not know anything about Linux kernel development, you should look at the Linux KernelNewbies project:

• http://kernelnewbies.org

It consists of a helpful mailing list where you can ask almost any type of basic kernel development question (make sure to search the archives first, before asking something that has already been answered in the past.) It also has an IRC channel that you can use to ask questions in real-time, and a lot of helpful documentation that is useful for learning about Linux kernel development.

如果你不知道任何Linux 核心開發事務, 你應該查詢 Linux 核心新手(KernelNewbies) 專案:

• http://kernelnewbies.org

它包括了一個有用的郵件論壇 那兒你可以詢問任何形式的基礎核心開發問題.(在 詢問某些已經被回答過事情之前, 先確定搜詢過檔案記錄.) 它也有一個 IRC頻道 你可以用來問即時問題, 且有大量對學習核心開發有幫助的文件.

The website has basic information about code organization, subsystems, and current projects (both in-tree and out-of-tree). It also describes some basic logistical information, like how to compile a kernel and apply a patch.

該網站有關於組織, 子系統, 和目前專案(主支和非主支兩者皆有)的基礎資訊.它 也說明某寫基本邏輯資訊, 比如說 如何編譯核心和適用修補程式.

If you do not know where you want to start, but you want to look for some task to start doing to join into the kernel development community, go to the Linux Kernel Janitor's project:

• http://janitor.kernelnewbies.org/

It is a great place to start. It describes a list of relatively simple problems that need to be cleaned up and fixed within the Linux kernel source tree. Working with the developers in charge of this project, you will learn the basics of getting your patch into the Linux kernel tree, and possibly be pointed in the direction of what to go work on next, if you do not already have an idea.

如果你不曉得你想從那開始, 但你查看某些作業開始加入核心開發社群, 到Linux 核心 守衛專案 (Janitor's Project):

• http://janitor.kernelnewbies.org/

它是一個很棒的起始地點. 它說明一份在核心原始碼內需要整理和修正相對簡單地 問題的清單. 和這個專案負責的開發者一起工作, 你會學到基本的讓你的修補程式 進到核心樹裡, 還有可能導引你至下一個作業的方向, 如果你尚未有既定的主意.

If you already have a chunk of code that you want to put into the kernel tree, but need some help getting it in the proper form, the kernel-mentors project was created to help you out with this. It is a mailing list, and can be found at:

• http://selenic.com/mailman/listinfo/kernel-mentors

如果你已經有一段程式碼想放入核心樹中, 但需要一些協助以便取得正確的形式, 核心的良師益友專案(kernel-mentors) 被建立來幫助你上述事項. 它是一個郵件 論壇, 且可以在底下找到:

• http://selenic.com/mailman/listinfo/kernel-mentors

Before making any actual modifications to the Linux kernel code, it is imperative to understand how the code in question works. For this purpose, nothing is better than reading through it directly (most tricky bits are commented well), perhaps even with the help of specialized tools. One such tool that is particularly recommended is the Linux Cross-Reference project, which is able to present source code in a self-referential, indexed webpage format. An excellent up-to-date repository of the kernel code may be found at:

• http://sosdg.org/~coywolf/lxr/

在讓任何實際修改進入Linux核心之前之前, 瞭解討論中程式碼如何運作是極為重 要的. 因為這個目地, 沒有比直接閱讀它來得好 (最技巧的方式是良好的註解), 也許 藉用特殊工具的幫忙. 其中一個這樣的工具被特別推薦的是Linux 交互關聯 (Cross-Reference)專案, 該案可以以自我參照, 索引網頁格式來呈現原始碼.一個 優秀的核心碼即時儲存庫可以在底下被找到:

• http://sosdg.org/~coywolf/lxr/

The development process

開發過程

Linux kernel development process currently consists of a few different main kernel "branches" and lots of different subsystem-specific kernel branches. These different branches are:

• - main 2.6.x kernel tree - 2.6.x.y -stable kernel tree - 2.6.x -git kernel patches - 2.6.x -mm kernel patches - subsystem specific kernel trees and patches

Linux 核心開發過程目前由少數不同的核心分支和大量不同的特定目地子系統 核心分支組成. 這些不同分支是:

• - 主要 2.6.x 核心樹 - 2.6.x.y - 穩定的核心樹 - 2.6.x - git 核心修補程式 - 2.6.x - 記憶體管理(mm) 核心修補程式 - 子系統 特定目地 核心樹 和修補程式

2.6.x kernel tree

2.6.x kernels are maintained by Linus Torvalds, and can be found on kernel.org in the pub/linux/kernel/v2.6/ directory. Its development process is as follows:

• - As soon as a new kernel is released a two weeks window is open,
  • during this period of time maintainers can submit big diffs to Linus, usually the patches that have already been included in the -mm kernel for a few weeks. The preferred way to submit big changes is using git (the kernel's source management tool, more information

    can be found at http://git.or.cz/) but plain patches are also just fine.

  - After two weeks a -rc1 kernel is released it is now possible to push
  • only patches that do not include new features that could affect the stability of the whole kernel. Please note that a whole new driver (or filesystem) might be accepted after -rc1 because there is no risk of causing regressions with such a change as long as the change is self-contained and does not affect areas outside of the code that is being added. git can be used to send patches to Linus after -rc1 is released, but the patches need to also be sent to a public mailing list for review.
  - A new -rc is released whenever Linus deems the current git tree to
  • be in a reasonably sane state adequate for testing. The goal is to release a new -rc kernel every week.
  - Process continues until the kernel is considered "ready", the
  • process should last around 6 weeks.

2.6.x 核心樹

2.6.x 核心樹是由 Linus Torvalds 維護, 且可以在 Kernel.org 的 pub/linux/kernel/v2.6/ 目錄裡找到. 它的開發過程如下:

• - 新核心一釋出一個每兩個禮拜窗口就打開, 在這段期間維護人員可以提交大的
  • 行數檔案比較(diffs)給Linus, 經常是已經被包括在 記憶體管理(-mm) 數個 星期的核心修補程式. 較受歡迎的提交大量變動方式是使用git (核心碼的 管理工具, 更多資訊可以在http://git.or.cz被找到) 但普通的修補程式也是 可以的.
  - 兩個禮拜後 一個 -rc1 核心被釋出 現在它可能推出不包括會影響整個核
  • 心穩定性的新功能的修補程式. 請注意 整個新的驅動程式 (或檔案系統) 可能在 -rc1 後被接受 因為沒有這樣的改變而導致系統倒退的風險 只要改變 是涵蓋自身的 且 不影響外部被加入的程式碼. git 可以被用來傳送修補程式 給 Linus 在 -rc1 釋出後, 但修補程式也需要被送到郵件論壇供覆審.
  - 一個新的 -rc 會被釋出 不論何時Linus 認為目前git樹 在合理健全適合測試
  • 的狀態. 目標是每個禮拜釋出新的 -rc 核心.
  - 行程會持續 直到核心被認為 "準備好了", 該流程應該維持約6星期.

It is worth mentioning what Andrew Morton wrote on the linux-kernel mailing list about kernel releases:

• "Nobody knows when a kernel will be released, because it's released according to perceived bug status, not according to a preconceived timeline."

值得一提的 Andrew Morton 在 Linux-kernel 郵件論壇上寫道關於Kernel釋出:

• "沒有人知到何時一個核心將會被釋出, 因為 它市依據被察覺得臭蟲 狀態(bug status)釋出, 而非預先構想的時間表."

2.6.x.y -stable kernel tree

Kernels with 4 digit versions are -stable kernels. They contain relatively small and critical fixes for security problems or significant regressions discovered in a given 2.6.x kernel.

This is the recommended branch for users who want the most recent stable kernel and are not interested in helping test development/experimental versions.

If no 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is the current stable kernel.

2.6.x.y are maintained by the "stable" team <stable@kernel.org>, and are released almost every other week.

The file Documentation/stable_kernel_rules.txt in the kernel tree documents what kinds of changes are acceptable for the -stable tree, and how the release process works.

2.6.x.y - 穩定的核心樹

四個數字的核心版本 是 -stable 的核心. 它們包括相關聯小且關鍵的安全問題修 正或重大的回溯在某個被發現的2.6.x核心.

這是推薦給想要近期穩定核心且對幫助測試開發試驗性質版本不感興趣使用者的分 支.

如果沒有2.6.x.y核心可用, 那麼最大號數2.6.x核心會是目前最穩定的核心.

2.6.x.y 是由 "stable" 團隊<stable@kernel.org>維護, 且幾乎每個禮拜釋出.

檔案 Documentation/stable_kernel_rules.txt 在核心樹裡記載何種改變是可以 被 -stable 主支 接受, 以及釋出的流程如何作業.

2.6.x -git patches

These are daily snapshots of Linus' kernel tree which are managed in a git repository (hence the name.) These patches are usually released daily and represent the current state of Linus' tree. They are more experimental than -rc kernels since they are generated automatically without even a cursory glance to see if they are sane.

2.6.x - git 修補程式 這是Linus核心樹的每日快照, 它是在git儲藏庫裡被維護(因此得名.) 這些修補程 式經常每天釋出且呈現目前Linus樹的狀態. 它們比起 -rc 核心更具實驗性質因為 它們是自動被產生甚至沒有粗略的掃視是否它們是沒有問題的.

2.6.x -mm kernel patches

These are experimental kernel patches released by Andrew Morton. Andrew takes all of the different subsystem kernel trees and patches and mushes them together, along with a lot of patches that have been plucked from the linux-kernel mailing list. This tree serves as a proving ground for new features and patches. Once a patch has proved its worth in -mm for a while Andrew or the subsystem maintainer pushes it on to Linus for inclusion in mainline.

It is heavily encouraged that all new patches get tested in the -mm tree before they are sent to Linus for inclusion in the main kernel tree.

These kernels are not appropriate for use on systems that are supposed to be stable and they are more risky to run than any of the other branches.

If you wish to help out with the kernel development process, please test and use these kernel releases and provide feedback to the linux-kernel mailing list if you have any problems, and if everything works properly.

In addition to all the other experimental patches, these kernels usually also contain any changes in the mainline -git kernels available at the time of release.

The -mm kernels are not released on a fixed schedule, but usually a few -mm kernels are released in between each -rc kernel (1 to 3 is common).

2.6.x -mm 核心修補程式

這些是實驗性質的核心修補程式由Andrew Morton釋出. Andrew 揀取所有不同子系 統核心樹和修補程式且讓它們和在一起, 一起加上大量已經從linux-kernel 郵件論 壇摘取修補程式. 此樹提供新特徵和修補程式的平臺. 一但一份修補程式一段時間 後被證實它在 -mm 的價值 Andrew 或 子系統維護人員把它推向Linus以便包括在主 支裡.

在新的修補程式被傳給Linus包括在主支前所有的修補程式在-mm樹裡接受測式是被 強烈地鼓勵.

這些核心並不合適給將來預定是穩定的系統且比起其它分支運作起來它們是更具風 險的.

如果你希望幫助核心流程開發, 請測式和使用這些釋出核心並提供回報給 linux-kernel郵件論壇 如果你有任何問題, 且如果每件事都恰當地運作.

除了 所有其它試驗性質修補程式, 這些核心也經常在釋出的時後包括在主支-git 核心裡任何有效改變.

-mm 核心並不在固定的時間表被釋出, 但經常少數幾個 -mm 核心被釋出在每個-rc 核心期間(1到3是很常見).

Subsystem Specific kernel trees and patches

A number of the different kernel subsystem developers expose their development trees so that others can see what is happening in the different areas of the kernel. These trees are pulled into the -mm kernel releases as described above.

特殊子系統核心樹和修補程式

一定數量不同的核心子系統開發人員開放他們開發樹所以其他人可以看到在 不同區域的核心發生情況. 這些樹 被推入 -mm 核心釋出 同上所述.

Here is a list of some of the different kernel trees available:

• git trees:

  • - Kbuild development tree, Sam Ravnborg <sam@ravnborg.org>

    • kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git

這是一份部份不同的核心樹有效清單:

• git 樹:

  • - Kbuild 開發樹, Sam Ravnborg <sam@ravnborg.org>

    • kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git

    - ACPI development tree, Len Brown <len.brown@intel.com>

    • kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git

    - ACPI 開發樹, Len Brown <len.brown@intel.com>

    • kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git

    - Block development tree, Jens Axboe <axboe@suse.de>

    • kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git

    - 區塊開發樹, Jens Axboe <axboe@suse.de>

    • kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git

    - DRM development tree, Dave Airlie <airlied@linux.ie>

    • kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git

    - 數位內容使用權利管理開發樹, Dave Airlie <airlied@linux.ie>

    • kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git

    - ia64 development tree, Tony Luck <tony.luck@intel.com>

    • kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git

    - ia64 開發樹, Tony Luck <tony.luck@intel.com>

    • kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git

    - ieee1394 development tree, Jody McIntyre <scjody@modernduck.com>

    • kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git

    - ieee1394 開發樹, Jody McIntyre <scjody@modernduck.com>

    • kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git

    - infiniband, Roland Dreier <rolandd@cisco.com>

    • kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git

    - 無限頻道, Roland Dreier <rolandd@cisco.com>

    • kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git

    - libata, Jeff Garzik <jgarzik@pobox.com>

    • kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git

    - libata, Jeff Garzik <jgarzik@pobox.com>

    • kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git

    - network drivers, Jeff Garzik <jgarzik@pobox.com>

    • kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git

    - 網路驅動程式, Jeff Garzik <jgrzik@pobox.com>

    • kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git

    - pcmcia, Dominik Brodowski <linux@dominikbrodowski.net>

    • kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git

    - pcmcia, Dominik Brodowski <linux@dominikbrodowski.net>

    • kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git

    - SCSI, James Bottomley <James.Bottomley@SteelEye.com>

    • kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git

    - SCSI, James Bottomley <James.Bottomley@SteelEye.com>

    • kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git

  Other git kernel trees can be found listed at http://kernel.org/git 其他 git 核心樹可以在http://kernel.org/git列表找到. quilt trees:

  • - USB, PCI, Driver Core, and I2C, Greg Kroah-Hartman <gregkh@suse.de>

    • kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/

    - x86-64, partly i386, Andi Kleen <ak@suse.de>

    • ftp.firstfloor.org:/pub/ak/x86_64/quilt/
  quilt trees:

  • - USB, PCI, Driver Core, and I2C, Greg Kroah-Hartman <gregkh@suse.de>

    • kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/

    - x86-64, partly i386, Andi Kleen <ak@suse.de>

    • ftp.firstfloor.org:/pub/ak/x86_64/quilt/

Bug Reporting

臭蟲 回報

bugzilla.kernel.org is where the Linux kernel developers track kernel bugs. Users are encouraged to report all bugs that they find in this tool. For details on how to use the kernel bugzilla, please see:

• http://test.kernel.org/bugzilla/faq.html

bugzilla.kernel.org 是Linux核心開發人員追溯核心臭蟲的地方. 使用者被鼓勵 回報他們在這個工具裡發現的所有臭蟲. 更詳細的如何使用核心bugzilla,請參照:

• http://test.kernel.org/bugzilla/faq.html

The file REPORTING-BUGS in the main kernel source directory has a good template for how to report a possible kernel bug, and details what kind of information is needed by the kernel developers to help track down the problem.

檔案REPORTING-BUS 在主要核心原始目錄裡有一份好的範本針對如何回報一個可能 的核心臭蟲, 且細說何種資訊是必須由核心開法者幫助追溯問題.

Managing bug reports

管理臭蟲報表

One of the best ways to put into practice your hacking skills is by fixing bugs reported by other people. Not only you will help to make the kernel more stable, you'll learn to fix real world problems and you will improve your skills, and other developers will be aware of your presence. Fixing bugs is one of the best ways to earn merit amongst the developers, because not many people like wasting time fixing other people's bugs.

鍛鍊你駭客技術的最好辦法之一是藉由修正由其他人回報的臭蟲. 不僅你將幫助核心 更穩固, 你將學到修正真實世界問題且你將改善你的技巧, 且其他開發者將意識到你 的存在. .修正錯誤是在開發者當中贏得功績的最佳方式, 因為不是很多人喜歡浪費 時間修正其他人的錯誤.

To work in the already reported bug reports, go to http://bugzilla.kernel.org. If you want to be advised of the future bug reports, you can subscribe to the bugme-new mailing list (only new bug reports are mailed here) or to the bugme-janitor mailing list (every change in the bugzilla is mailed here)

• http://lists.osdl.org/mailman/listinfo/bugme-new http://lists.osdl.org/mailman/listinfo/bugme-janitors

在已回報的臭蟲報告裡作業, 到 http://bugzilla.kernel.org. 如果你希望得到未來 的臭蟲回報, 你可以訂閱bugme-new 郵件論壇(僅有新的臭蟲報告會寄到這) 或到 bugme-janitor 郵件論壇(在bugzilla的每次改變會被寄到這).

• http://lists.osdl.org/mailman/listinfo/bugme-new http://lists.osdl.org/mailman/listinfo/bugme-janitors

Managing bug reports

One of the best ways to put into practice your hacking skills is by fixing bugs reported by other people. Not only you will help to make the kernel more stable, you'll learn to fix real world problems and you will improve your skills, and other developers will be aware of your presence. Fixing bugs is one of the best ways to get merits among other developers, because not many people like wasting time fixing other people's bugs.

To work in the already reported bug reports, go to http://bugzilla.kernel.org. If you want to be advised of the future bug reports, you can subscribe to the bugme-new mailing list (only new bug reports are mailed here) or to the bugme-janitor mailing list (every change in the bugzilla is mailed here)

• http://lists.osdl.org/mailman/listinfo/bugme-new http://lists.osdl.org/mailman/listinfo/bugme-janitors

Mailing lists

郵件論壇

As some of the above documents describe, the majority of the core kernel developers participate on the Linux Kernel Mailing list. Details on how to subscribe and unsubscribe from the list can be found at:

• http://vger.kernel.org/vger-lists.html#linux-kernel

There are archives of the mailing list on the web in many different places. Use a search engine to find these archives. For example:

• http://dir.gmane.org/gmane.linux.kernel

It is highly recommended that you search the archives about the topic you want to bring up, before you post it to the list. A lot of things already discussed in detail are only recorded at the mailing list archives.

如同上述部份文件描述, 大部份的主要核心開發者 參與 Linux 核心郵件論壇.如何 訂閱和取消訂閱郵件論壇可以在底下找到:

• http://vger.kernel.org/vger-lists.html#linux-kernel

在不同地方的網路上有郵件論壇的文件記錄. 使用搜尋引擎可以找到這些文件記錄. 舉例來說:

• http://dir.gmane.org/gmane.linux.kernel

高度推薦你搜尋關於你想要的文件記錄主題, 在你張貼到論壇前. 大部份的已經被 詳細討論過東西僅記在郵件論壇記錄裡.

Most of the individual kernel subsystems also have their own separate mailing list where they do their development efforts. See the MAINTAINERS file for a list of what these lists are for the different groups.

大部份單獨的核心子系統也有它們自己的個別郵件論壇 在那兒他們從事自己的開發 成果. 查看MAINTAINERS 檔 找一份針對不同團體這些清單是何作用的清單.

Many of the lists are hosted on kernel.org. Information on them can be found at:

• http://vger.kernel.org/vger-lists.html

許多的清單放在kernel.org. 在它們身上的資訊可以在底下找到:

• http://vger.kernel.org/vger-lists.html

Please remember to follow good behavioral habits when using the lists. Though a bit cheesy, the following URL has some simple guidelines for interacting with the list (or any list):

• http://www.albion.com/netiquette/

記住請遵守良好的行為習慣當使用這些清單時. 雖然不是很有價值, 底下的鏈結 有一些針對清單(或任何)的溝通方式簡單的原則:

• http://www.albion.com/netiquette/

If multiple people respond to your mail, the CC: list of recipients may get pretty large. Don't remove anybody from the CC: list without a good reason, or don't reply only to the list address. Get used to receiving the mail twice, one from the sender and the one from the list, and don't try to tune that by adding fancy mail-headers, people will not like it.

如果很多人回覆到你的信箱, 收件人的 副本收件者清單可能會非常龐大.沒有好的 理由不要從副本收件者清單移除任何人, 或只回覆到清單地址. 習慣接收郵件兩遍, 一次從寄件者和一次從論壇, 且不要試著藉由加入炫目的郵件標頭調整它, 大家不喜 那樣.

Remember to keep the context and the attribution of your replies intact, keep the "John Kernelhacker wrote ...:" lines at the top of your reply, and add your statements between the individual quoted sections instead of writing at the top of the mail.

記得保持文意和你的回覆的屬性原封不動, 保持"駭客John ... 寫:" 字樣在你回覆信 的頂端, 且加入你的說明在個人引用區段之間而非寫在郵件的頂端.

If you add patches to your mail, make sure they are plain readable text as stated in Documentation/SubmittingPatches. Kernel developers don't want to deal with attachments or compressed patches; they may want to comment on individual lines of your patch, which works only that way. Make sure you use a mail program that does not mangle spaces and tab characters. A good first test is to send the mail to yourself and try to apply your own patch by yourself. If that doesn't work, get your mail program fixed or change it until it works.

如果增加修補程式到你的郵件, 確定它們是可閱讀的純文字文件如同在 Document/SubmittingPatches裡的說明. 核心開發人員不希望礎裡附件或壓縮的修補程 式; 他們可能希望註解在你的修補程式個別的行數上, 要那樣只有這種作法. 確認你使 用的郵件程式不亂砍空白和tab字元. 一個好的第一次測試是傳送郵件給你自己且試著自 己套用你自己的修補程式. 如果那樣作沒有效用, 修改你的郵件程式或改變到它運作為 止.

Above all, please remember to show respect to other subscribers. 最重要的, 請記得尊重其他訂閱人.

Working with the community

和社群一起作業

The goal of the kernel community is to provide the best possible kernel there is. When you submit a patch for acceptance, it will be reviewed on its technical merits and those alone. So, what should you be expecting?

• - criticism - comments - requests for change - requests for justification - silence

核心設群的目標是提供最佳可能有的核心. 當你提交一份希望被接受的修補程式時, 僅按它的技術價值 它會被再一次檢查. 所以, 你應該期待什麼?

• - 評論 - 註解 - 要求變更 - 要求整理說明 - 保持沈默

Remember, this is part of getting your patch into the kernel. You have to be able to take criticism and comments about your patches, evaluate them at a technical level and either rework your patches or provide clear and concise reasoning as to why those changes should not be made. If there are no responses to your posting, wait a few days and try again, sometimes things get lost in the huge volume.

記住, 這是讓你的修補程式進入核心的部份. 你必須可以接受關於你的修補程式的 評論和註解, 在技術層次評估它們且要不重作你的修補程式不然提供清楚又簡要的 理由為何不應該作這些改變. 如果對你的貼文沒有回覆, 多等幾天且再試一次, 有 時後東西遺失在大量的

What should you not do?

• - expect your patch to be accepted without question - become defensive - ignore comments - resubmit the patch without making any of the requested changes

你不應該作什麼?

• - 期待你的修補程式沒有任何疑問的被接受 - 變得防衛 - 忽視註解 - 從新提交沒有作任何被要求變更的修補程式

In a community that is looking for the best technical solution possible, there will always be differing opinions on how beneficial a patch is. You have to be cooperative, and willing to adapt your idea to fit within the kernel. Or at least be willing to prove your idea is worth it. Remember, being wrong is acceptable as long as you are willing to work toward a solution that is right.

在社群裡這是尋找最佳技術解法的可能, 總是有對修補程式有何好處上不同的意見. 你必須是樂意合作的, 且願意改寫你的想法以適應核心. 或至少願意證明你的想法 是值得的. 記住, 錯誤是可以被接受的只要你願意朝正確的解決方案努力.

It is normal that the answers to your first patch might simply be a list of a dozen things you should correct. This does _not_ imply that your patch will not be accepted, and it is _not_ meant against you personally. Simply correct all issues raised against your patch and resend it.

回應你的第一個修補程式可能僅是一份大量你應該修改的清單是很普通的. 這不意 味著你的修補程式將不被接受, 且這不表示是針對你個人地. 只要修正所有因你修 補程式而起的議題和重新提交它.

Differences between the kernel community and corporate structures

核心社群和配合結構之間的不同點

The kernel community works differently than most traditional corporate development environments. Here are a list of things that you can try to do to try to avoid problems:

核心社群作法不同於其它傳統合作開發環境. 這兒是一張清單你可以嘗試以避免問 題:

• Good things to say regarding your proposed changes:
  • - "This solves multiple problems." - "This deletes 2000 lines of code." - "Here is a patch that explains what I am trying to describe." - "I tested it on 5 different architectures..." - "Here is a series of small patches that..." - "This increases performance on typical machines..."
  考慮到你提議改變的好方式:
  • - "這解決多個問題." - "這刪掉2000行的程式碼." - "這是一份解釋我試著說明的修補程式." - "我在五種不同的架構測試它." - "這是一系列的小型的修補程式, 它 ..." - "這增加在典型機器上的效能 ..."
  Bad things you should avoid saying:
  • - "We did it this way in AIX/ptx/Solaris, so therefore it must be
    • good..."
    - "I've being doing this for 20 years, so..." - "This is required for my company to make money" - "This is for our Enterprise product line." - "Here is my 1000 page design document that describes my idea" - "I've been working on this for 6 months..." - "Here's a 5000 line patch that..." - "I rewrote all of the current mess, and here it is..." - "I have a deadline, and this patch needs to be applied now."
  你應該試著避免說的壞方式:
  • - "我們在 AIX/ptx/Solaris上寫它, 所以它必定是好的..." - "我以經作這個20年了, 所以 ..." - "這是給我們的企業產品線." - "這是我1000業描述我想法的設計文件" - "我在這上面努力了6個月 ..." - "這是5000千行的修補程式..." - "我重寫目前所有雜亂的東西, 它在這 ..." - "我有結止時間, 且這份修補程式必需現在被採用."

Another way the kernel community is different than most traditional software engineering work environments is the faceless nature of interaction. One benefit of using email and irc as the primary forms of communication is the lack of discrimination based on gender or race. The Linux kernel work environment is accepting of women and minorities because all you are is an email address. The international aspect also helps to level the playing field because you can't guess gender based on a person's name. A man may be named Andrea and a woman may be named Pat. Most women who have worked in the Linux kernel and have expressed an opinion have had positive experiences.

另一個核心社群不同大部份軟體工程作業環境的地方是非面對面的溝通特性.以 電子郵件和多人線上系統當作主要溝通形式的好處是缺少基於性別或種族的歧視. Linux 核心作業環境是接受女性和少數群體因為你們所有是一個郵件地址. 國際 觀點也幫助平等化遊樂場因為你不能猜測性別基於一個人的姓名.一個男性被取名 為Andrea且一個女性可能被取名為Pat. 大部份的女性有在Linux核心作業且表 達過意見已有正面積極的經驗.

The language barrier can cause problems for some people who are not comfortable with English. A good grasp of the language can be needed in order to get ideas across properly on mailing lists, so it is recommended that you check your emails to make sure they make sense in English before sending them.

語言的隔閡可能對部份對英文不習慣的人造成問題. 語言好的領會是必要的為了讓 想法適當地在論壇上傳遞, 所以通常會建議你傳送前檢查你的郵件以確認它在英文 裡是有意義的.

Break up your changes

拆解你的變更

The Linux kernel community does not gladly accept large chunks of code dropped on it all at once. The changes need to be properly introduced, discussed, and broken up into tiny, individual portions. This is almost the exact opposite of what companies are used to doing. Your proposal should also be introduced very early in the development process, so that you can receive feedback on what you are doing. It also lets the community feel that you are working with them, and not simply using them as a dumping ground for your feature. However, don't send 50 emails at one time to a mailing list, your patch series should be smaller than that almost all of the time.

Linux 核心社群並不喜歡接受一次傾倒的大量程式碼. 變動需要被適當地導引, 討論, 且拆解成小塊, 個別的部份. 這基乎和一家公司習慣作法徹底相反. 你的 提議應該在開發過程非常前期裡也被導引, 所以你可以接收對你作的事的回應.它也 讓社群感受到你正在與他們一起工作, 且不只是利用大家當作傾倒程式特色的場地. 然而, 不要一次傳送50份郵件到郵件論壇, 你的修補程式系列應該小於大部份的時 間的修補程式.

The reasons for breaking things up are the following:

把東西拆成小塊的理由如下:

1) Small patches increase the likelihood that your patches will be

• applied, since they don't take much time or effort to verify for correctness. A 5 line patch can be applied by a maintainer with barely a second glance. However, a 500 line patch may take hours to review for correctness (the time it takes is exponentially proportional to the size of the patch, or something). Small patches also make it very easy to debug when something goes wrong. It's much easier to back out patches one by one than it is to dissect a very large patch after it's been applied (and broken something).

1) 小的修補程式增加你的修補程式被採用的可能性, 因為它們不花太多時間或

• 力氣去核對正確性. 一個五行的修補程式很少被看第二次就可以被維護人員 採用.然而,一份五百行的修補程式可能花數個小時重看校正(花費的時間依 修補程式大小,或某些東西成等比級數).

2) It's important not only to send small patches, but also to rewrite

• and simplify (or simply re-order) patches before submitting them.

2) 不僅是傳送較小的修補程式, 而且在提交前重寫又簡化(或簡單

• 地重新排序)修補程式是很重要的.

Here is an analogy from kernel developer Al Viro:

• "Think of a teacher grading homework from a math student. The teacher does not want to see the student's trials and errors before they came up with the solution. They want to see the cleanest, most elegant answer. A good student knows this, and would never submit her intermediate work before the final solution."

這兒是一份相似從核心開發者 Al Viro :

• "思考一個老師對一個數學科學生給分. 在學生提出解決方法前老師不會 希望看到學生的過程和錯誤. 他們希望看到最簡潔, 最優雅的解答. 一 個好的學生知到這點, 且在最後結果前不會交出他中間過程的作業." The same is true of kernel development. The maintainers and reviewers do not want to see the thought process behind the solution to the problem one is solving. They want to see a simple and elegant solution." 核心開發也是一樣的道理. 維護人員和檢閱者不希望看到對於某人正 在解決的問題其解決方案後頭的的思考過程. 他們想看到一個簡單且 優雅的解法."

It may be challenging to keep the balance between presenting an elegant solution and working together with the community and discussing your unfinished work. Therefore it is good to get early in the process to get feedback to improve your work, but also keep your changes in small chunks that they may get already accepted, even when your whole task is not ready for inclusion now.

在呈現一個優雅的解法和社群一起作業且討論你未完工作間保持平衡可能是個挑戰. 因此在過程裡提早取得回應以改善你的作業是件好事, 但也保持你的變更在小幅度 數量那樣大家可能已準備好接受, 即使當你全部的工作現在還沒準備好被包入.

Also realize that it is not acceptable to send patches for inclusion that are unfinished and will be "fixed up later."

同樣地瞭解傳送未完成且稍後將被修正的修補程式是不能被接受包入的.

Justify your change

證明你的變更

Along with breaking up your patches, it is very important for you to let the Linux community know why they should add this change. New features must be justified as being needed and useful.

和你打散的修補程式一起, 對你而言讓Linux 社群瞭解為什麼他們應該加入這個變 動是很重要的. 新的特徵必須被證明是必要且有用的.

Document your change

記錄你的變更

When sending in your patches, pay special attention to what you say in the text in your email. This information will become the ChangeLog information for the patch, and will be preserved for everyone to see for all time. It should describe the patch completely, containing:

• - why the change is necessary - the overall design approach in the patch - implementation details - testing results

當傳送時在你的修補程式裡, 注意你郵件文字裡的說明. 這個資訊將變成該修補程 式的修正記錄(ChangeLog) 資訊, 且將被保留給每個人隨時查閱. 它應該完整地描述 修補程式, 包括:

• - 為何變更是須要的 - 修補程式裡整體設計進程 - 實作的細節 - 測試結果

For more details on what this should all look like, please see the ChangeLog section of the document:

• "The Perfect Patch"

  • http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt

更多的細節對於這整個看起來的樣子, 請查文件修正記錄部份:

• 完美的修補程式("The Perfect Patch")

  • http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt

All of these things are sometimes very hard to do. It can take years to perfect these practices (if at all). It's a continuous process of improvement that requires a lot of patience and determination. But don't give up, it's possible. Many have done it before, and each had to start exactly where you are now.

這些所有的事有時後非常難達成. 它可以花費數年時間完美這些實踐(如果有的話). 這是持續性的改善過程那需要大量的耐心和決心. 但不放棄, 這是可能的. 先前很 多人已經這樣作了, 且每個人必須確實從你現在所在的地方開始.

Thanks to Paolo Ciarrocchi who allowed the "Development Process" (http://linux.tar.bz/articles/2.6-development_process) section to be based on text he had written, and to Randy Dunlap and Gerrit Huizenga for some of the list of things you should and should not say. Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard for their review, comments, and contributions. Without their help, this document would not have been possible.

感謝Paolo Ciarrocchi 他允許 "開發過程" (http://linux.tar.bz/articles/2.6-development_process) 部份 利用他寫好的 文件, 且 對於 部份清單上的事物 你應該和不應該說的要 感謝 Randy Dunlap 及 Gerrit Huzenga. 也要謝謝Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi Kleen, Vadim Lbanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, David A. Wheeler, Junio Hamano, Michael Kerrisk, 及 Alex Shepard 的校閱, 註記, 和貢獻. 沒有他們的幫忙, 這篇文章不可能完成.

Maintainer: Greg Kroah-Hartman <greg@kroah.com>

維護人員: Greg Kroah-Hartman <greg@kroah.com>

Note: [1]. I choose not to translate Documentation/xxx into Traditional Chinese

• because those are file names. Thus, it would make user confused if he want to find those files.