aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@woody.linux-foundation.org>2007-07-18 21:28:34 -0400
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-07-18 21:28:34 -0400
commit7209a1dc2557b127ee75a49e200812366532510d (patch)
treee89f39446c0bd8dfead5524110963cfbe65f05c7
parent29e7ee378e2327c808ede66dec4d4d964f4d375f (diff)
parentede178e216b5dd9200cf2c483c746e0672fbe503 (diff)
Merge master.kernel.org:/pub/scm/linux/kernel/git/gregkh/docs-2.6
* master.kernel.org:/pub/scm/linux/kernel/git/gregkh/docs-2.6: zh_CN/HOWTO: update URLs of git trees Chinese translation of Documentation/stable_api_nonsense.txt HOWTO: add Chinese translation of Documentation/HOWTO Documentation: add Japanese translated stable_api_nonsense.txt HOWTO: add Japanese translation of Documentation/HOWTO
-rw-r--r--Documentation/ja_JP/HOWTO650
-rw-r--r--Documentation/ja_JP/stable_api_nonsense.txt263
-rw-r--r--Documentation/zh_CN/HOWTO536
-rw-r--r--Documentation/zh_CN/stable_api_nonsense.txt157
4 files changed, 1606 insertions, 0 deletions
diff --git a/Documentation/ja_JP/HOWTO b/Documentation/ja_JP/HOWTO
new file mode 100644
index 000000000000..b2446a090870
--- /dev/null
+++ b/Documentation/ja_JP/HOWTO
@@ -0,0 +1,650 @@
1NOTE:
2This is Japanese translated version of "Documentation/HOWTO".
3This one is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com>
4and JF Project team <www.linux.or.jp/JF>.
5If you find difference with original file or problem in translation,
6please contact maintainer of this file or JF project.
7
8Please also note that purpose of this file is easier to read for non
9English natives and not to be intended to fork. So, if you have any
10comments or updates of this file, please try to update Original(English)
11file at first.
12
13Last Updated: 2007/06/04
14==================================
15これは、
16linux-2.6.21/Documentation/HOWTO
17の和訳です。
18
19翻訳団体: JF プロジェクト < http://www.linux.or.jp/JF/ >
20翻訳日: 2007/06/04
21翻訳者: Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com>
22校正者: 松倉さん <nbh--mats at nifty dot com>
23 小林 雅典さん (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp>
24 武井伸光さん、<takei at webmasters dot gr dot jp>
25 かねこさん (Seiji Kaneko) <skaneko at a2 dot mbn dot or dot jp>
26 野口さん (Kenji Noguchi) <tokyo246 at gmail dot com>
27 河内さん (Takayoshi Kochi) <t-kochi at bq dot jp dot nec dot com>
28 岩本さん (iwamoto) <iwamoto.kn at ncos dot nec dot co dot jp>
29==================================
30
31Linux カーネル開発のやり方
32-------------------------------
33
34これは上のトピック( Linux カーネル開発のやり方)の重要な事柄を網羅した
35ドキュメントです。ここには Linux カーネル開発者になるための方法と
36Linux カーネル開発コミュニティと共に活動するやり方を学ぶ方法が含まれて
37います。カーネルプログラミングに関する技術的な項目に関することは何も含
38めないようにしていますが、カーネル開発者となるための正しい方向に向かう
39手助けになります。
40
41もし、このドキュメントのどこかが古くなっていた場合には、このドキュメン
42トの最後にリストしたメンテナーにパッチを送ってください。
43
44はじめに
45---------
46
47あなたは Linux カーネルの開発者になる方法を学びたいのでしょうか? そ
48れともあなたは上司から「このデバイスの Linux ドライバを書くように」と
49言われているのでしょうか? 
50この文書の目的は、あなたが踏むべき手順と、コミュニティと一緒にうまく働
51くヒントを書き下すことで、あなたが知るべき全てのことを教えることです。
52また、このコミュニティがなぜ今うまくまわっているのかという理由の一部も
53説明しようと試みています。
54
55カーネルは 少量のアーキテクチャ依存部分がアセンブリ言語で書かれている
56以外は大部分は C 言語で書かれています。C言語をよく理解していることはカー
57ネル開発者には必要です。アーキテクチャ向けの低レベル部分の開発をするの
58でなければ、(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要あり
59ません。以下の本は、C 言語の十分な知識や何年もの経験に取って代わるもの
60ではありませんが、少なくともリファレンスとしてはいい本です。
61 - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
62 -『プログラミング言語C第2版』(B.W. カーニハン/D.M. リッチー著 石田晴久訳) [共立出版]
63 - "Practical C Programming" by Steve Oualline [O'Reilly]
64 - 『C実践プログラミング第3版』(Steve Oualline著 望月康司監訳 谷口功訳) [オライリージャパン]
65 - "C: A Reference Manual" by Harbison and Steele [Prentice Hall]
66 - 『新・詳説 C 言語 H&S リファレンス』
67 (サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク]
68
69カーネルは GNU C と GNU ツールチェインを使って書かれています。カーネル
70は ISO C89 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って
71います。カーネルは標準 C ライブラリとは関係がないといった、C 言語フリー
72スタンディング環境です。そのため、C の標準で使えないものもあります。任
73意の long long の除算や浮動小数点は使えません。
74ときどき、カーネルがツールチェインや C 言語拡張に置いている前提がどう
75なっているのかわかりにくいことがあり、また、残念なことに決定的なリファ
76レンスは存在しません。情報を得るには、gcc の info ページ( info gcc )を
77みてください。
78
79あなたは既存の開発コミュニティと一緒に作業する方法を学ぼうとしているこ
80とに留意してください。そのコミュニティは、コーディング、スタイル、
81開発手順について高度な標準を持つ、多様な人の集まりです。
82地理的に分散した大規模なチームに対してもっともうまくいくとわかったこと
83をベースにしながら、これらの標準は長い時間をかけて築かれてきました。
84これらはきちんと文書化されていますから、事前にこれらの標準についてでき
85るだけたくさん学んでください。また皆があなたやあなたの会社のやり方に合わ
86せてくれると思わないでください。
87
88法的問題
89------------
90
91Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま
92す。ライセンスの詳細については、ソースツリーのメインディレクトリに存在
93する、COPYING のファイルをみてください。もしライセンスについてさらに質
94問があれば、Linux Kernel メーリングリストに質問するのではなく、どうぞ
95法律家に相談してください。メーリングリストの人達は法律家ではなく、法的
96問題については彼らの声明はあてにするべきではありません。
97
98GPL に関する共通の質問や回答については、以下を参照してください。
99 http://www.gnu.org/licenses/gpl-faq.html
100
101ドキュメント
102------------
103
104Linux カーネルソースツリーは幅広い範囲のドキュメントを含んでおり、それ
105らはカーネルコミュニティと会話する方法を学ぶのに非常に貴重なものです。
106新しい機能がカーネルに追加される場合、その機能の使い方について説明した
107新しいドキュメントファイルも追加することを勧めます。
108カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの
109変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報
110をマニュアルページのメンテナ mtk-manpages@gmx.net に送ることを勧めます。
111
112以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で
113す-
114
115 README
116 このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注
117 configure )し、生成(訳注 build )するために必要なことは何かが書かれ
118 ています。カーネルに関して初めての人はここからスタートするとよいで
119 しょう。
120
121 Documentation/Changes
122 このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最
123 小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい
124 ます。
125
126 Documentation/CodingStyle
127 これは Linux カーネルのコーディングスタイルと背景にある理由を記述
128 しています。全ての新しいコードはこのドキュメントにあるガイドライン
129 に従っていることを期待されています。大部分のメンテナーはこれらのルー
130 ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード
131 だけをレビューします。
132
133 Documentation/SubmittingPatches
134 Documentation/SubmittingDrivers
135 これらのファイルには、どうやってうまくパッチを作って投稿するかに
136 ついて非常に詳しく書かれており、以下を含みます(これだけに限らない
137 けれども)
138 - Email に含むこと
139 - Email の形式
140 - だれに送るか
141 これらのルールに従えばうまくいくことを保証することではありません
142 が (すべてのパッチは内容とスタイルについて精査を受けるので)、
143 ルールに従わなければ間違いなくうまくいかないでしょう。
144 この他にパッチを作る方法についてのよくできた記述は-
145
146 "The Perfect Patch"
147 http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
148 "Linux kernel patch submission format"
149 http://linux.yyz.us/patch-format.html
150
151 Documentation/stable_api_nonsense.txt
152 このファイルはカーネルの中に不変のAPIを持たないことにした意識的な
153 決断の背景にある理由について書かれています。以下のようなことを含
154 んでいます-
155 - サブシステムとの間に層を作ること(コンパチビリティのため?)
156 - オペレーティングシステム間のドライバの移植性
157 - カーネルソースツリーの素早い変更を遅らせる(もしくは素早い変更
158 を妨げる)
159 このドキュメントは Linux 開発の思想を理解するのに非常に重要です。
160 そして、他のOSでの開発者が Linux に移る時にとても重要です。
161
162 Documentation/SecurityBugs
163 もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ
164 のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を
165 支援してください。
166
167 Documentation/ManagementStyle
168 このドキュメントは Linux カーネルのメンテナー達がどう行動するか、
169 彼らの手法の背景にある共有されている精神について記述しています。こ
170 れはカーネル開発の初心者なら(もしくは、単に興味があるだけの人でも)
171 重要です。なぜならこのドキュメントは、カーネルメンテナー達の独特な
172 行動についての多くの誤解や混乱を解消するからです。
173
174 Documentation/stable_kernel_rules.txt
175 このファイルはどのように stable カーネルのリリースが行われるかのルー
176 ルが記述されています。そしてこれらのリリースの中のどこかで変更を取
177 り入れてもらいたい場合に何をすればいいかが示されています。
178
179 Documentation/kernel-docs.txt
180  カーネル開発に付随する外部ドキュメントのリストです。もしあなたが
181 探しているものがカーネル内のドキュメントでみつからなかった場合、
182 このリストをあたってみてください。
183
184 Documentation/applying-patches.txt
185 パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに
186 適用するのかについて正確に記述した良い入門書です。
187
188カーネルはソースコードから自動的に生成可能な多数のドキュメントを自分自
189身でもっています。これにはカーネル内 API のすべての記述や、どう正しく
190ロックをかけるかの規則が含まれます。このドキュメントは
191Documentation/DocBook/ ディレクトリに作られ、以下のように
192 make pdfdocs
193 make psdocs
194 make htmldocs
195 make mandocs
196コマンドを実行するとメインカーネルのソースディレクトリから
197それぞれ、PDF, Postscript, HTML, man page の形式で生成されます。
198
199カーネル開発者になるには
200---------------------------
201
202もしあなたが、Linux カーネル開発について何も知らないならば、
203KernelNewbies プロジェクトを見るべきです
204 http://kernelnewbies.org
205
206このサイトには役に立つメーリングリストがあり、基本的なカーネル開発に関
207するほとんどどんな種類の質問もできます (既に回答されているようなことを
208聞く前にまずはアーカイブを調べてください)。
209またここには、リアルタイムで質問を聞くことができる IRC チャネルや、Linux
210カーネルの開発に関して学ぶのに便利なたくさんの役に立つドキュメントがあ
211ります。
212
213web サイトには、コードの構成、サブシステム、現在存在するプロジェクト(ツ
214リーにあるもの無いものの両方)の基本的な管理情報があります。
215ここには、また、カーネルのコンパイルのやり方やパッチの当て方などの間接
216的な基本情報も記述されています。
217
218あなたがどこからスタートしてよいかわからないが、Linux カーネル開発コミュ
219ニティに参加して何かすることをさがしている場合には、Linux kernel
220Janitor's プロジェクトにいけばよいでしょう -
221 http://janitor.kernelnewbies.org/
222ここはそのようなスタートをするのにうってつけの場所です。ここには、
223Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな
224らない、単純な問題のリストが記述されています。このプロジェクトに関わる
225開発者と一緒に作業することで、あなたのパッチを Linuxカーネルツリーに入
226れるための基礎を学ぶことができ、そしてもしあなたがまだアイディアを持っ
227ていない場合には、次にやる仕事の方向性が見えてくるかもしれません。
228
229もしあなたが、すでにひとまとまりコードを書いていて、カーネルツリーに入
230れたいと思っていたり、それに関する適切な支援を求めたい場合、カーネル
231メンターズプロジェクトはそのような皆さんを助けるためにできました。
232ここにはメーリングリストがあり、以下から参照できます
233 http://selenic.com/mailman/listinfo/kernel-mentors
234
235実際に Linux カーネルのコードについて修正を加える前に、どうやってその
236コードが動作するのかを理解することが必要です。そのためには、特別なツー
237ルの助けを借りてでも、それを直接よく読むことが最良の方法です(ほとんど
238のトリッキーな部分は十分にコメントしてありますから)。そういうツールで
239特におすすめなのは、Linux クロスリファレンスプロジェクトです。これは、
240自己参照方式で、索引がついた web 形式で、ソースコードを参照することが
241できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり
242ます-
243 http://sosdg.org/~coywolf/lxr/
244
245開発プロセス
246-----------------------
247
248Linux カーネルの開発プロセスは現在幾つかの異なるメインカーネル「ブラン
249チ」と多数のサブシステム毎のカーネルブランチから構成されます。
250これらのブランチとは-
251 - メインの 2.6.x カーネルツリー
252 - 2.6.x.y -stable カーネルツリー
253 - 2.6.x -git カーネルパッチ
254 - 2.6.x -mm カーネルパッチ
255 - サブシステム毎のカーネルツリーとパッチ
256
2572.6.x カーネルツリー
258-----------------
259
2602.6.x カーネルは Linus Torvalds によってメンテナンスされ、kernel.org
261の pub/linux/kernel/v2.6/ ディレクトリに存在します。この開発プロセスは
262以下のとおり-
263
264 - 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、
265 この期間中に、メンテナー達は Linus に大きな差分を送ることができま
266 す。このような差分は通常 -mm カーネルに数週間含まれてきたパッチで
267 す。 大きな変更は git(カーネルのソース管理ツール、詳細は
268 http://git.or.cz/ 参照) を使って送るのが好ましいやり方ですが、パッ
269 チファイルの形式のまま送るのでも十分です。
270
271 - 2週間後、-rc1 カーネルがリリースされ、この後にはカーネル全体の安定
272 性に影響をあたえるような新機能は含まない類のパッチしか取り込むこと
273 はできません。新しいドライバ(もしくはファイルシステム)のパッチは
274 -rc1 の後で受け付けられることもあることを覚えておいてください。な
275 ぜなら、変更が独立していて、追加されたコードの外の領域に影響を与え
276 ない限り、退行のリスクは無いからです。-rc1 がリリースされた後、
277 Linus へパッチを送付するのに git を使うこともできますが、パッチは
278 レビューのために、パブリックなメーリングリストへも同時に送る必要が
279 あります。
280
281 - 新しい -rc は Linus が、最新の git ツリーがテスト目的であれば十分
282 に安定した状態にあると判断したときにリリースされます。目標は毎週新
283 しい -rc カーネルをリリースすることです。
284
285 - このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま
286 す。このプロセスはだいたい 6週間継続します。
287
288Andrew Morton が Linux-kernel メーリングリストにカーネルリリースについ
289て書いたことをここで言っておくことは価値があります-
290 「カーネルがいつリリースされるかは誰も知りません。なぜなら、これは現
291 実に認識されたバグの状況によりリリースされるのであり、前もって決めら
292 れた計画によってリリースされるものではないからです。」
293
2942.6.x.y -stable カーネルツリー
295---------------------------
296
297バージョンに4つ目の数字がついたカーネルは -stable カーネルです。これに
298は、2.6.x カーネルで見つかったセキュリティ問題や重大な後戻りに対する比
299較的小さい重要な修正が含まれます。
300
301これは、開発/実験的バージョンのテストに協力することに興味が無く、
302最新の安定したカーネルを使いたいユーザに推奨するブランチです。
303
304もし、2.6.x.y カーネルが存在しない場合には、番号が一番大きい 2.6.x
305が最新の安定版カーネルです。
306
3072.6.x.y は "stable" チーム <stable@kernel.org> でメンテされており、だ
308いたい隔週でリリースされています。
309
310カーネルツリーに入っている、Documentation/stable_kernel_rules.txt ファ
311イルにはどのような種類の変更が -stable ツリーに受け入れ可能か、またリ
312リースプロセスがどう動くかが記述されています。
313
3142.6.x -git パッチ
315------------------
316
317git リポジトリで管理されているLinus のカーネルツリーの毎日のスナップ
318ショットがあります。(だから -git という名前がついています)。これらのパッ
319チはおおむね毎日リリースされており、Linus のツリーの現状を表します。こ
320れは -rc カーネルと比べて、パッチが大丈夫かどうかも確認しないで自動的
321に生成されるので、より実験的です。
322
3232.6.x -mm カーネルパッチ
324------------------------
325
326Andrew Morton によってリリースされる実験的なカーネルパッチ群です。
327Andrew は個別のサブシステムカーネルツリーとパッチを全て集めてきて
328linux-kernel メーリングリストで収集された多数のパッチと同時に一つにま
329とめます。
330このツリーは新機能とパッチが検証される場となります。ある期間の間パッチ
331が -mm に入って価値を証明されたら、Andrew やサブシステムメンテナが、メ
332インラインへ入れるように Linus にプッシュします。
333
334メインカーネルツリーに含めるために Linus に送る前に、すべての新しいパッ
335チが -mm ツリーでテストされることが強く推奨されます。
336
337これらのカーネルは安定して動作すべきシステムとして使うのには適切ではあ
338りませんし、カーネルブランチの中でももっとも動作にリスクが高いものです。
339
340もしあなたが、カーネル開発プロセスの支援をしたいと思っているのであれば、
341どうぞこれらのカーネルリリースをテストに使ってみて、そしてもし問題があ
342れば、またもし全てが正しく動作したとしても、linux-kernel メーリングリ
343ストにフィードバックを提供してください。
344
345すべての他の実験的パッチに加えて、これらのカーネルは通常リリース時点で
346メインラインの -git カーネルに含まれる全ての変更も含んでいます。
347
348-mm カーネルは決まったスケジュールではリリースされません、しかし通常幾
349つかの -mm カーネル (1 から 3 が普通)が各-rc カーネルの間にリリースさ
350れます。
351
352サブシステム毎のカーネルツリーとパッチ
353-------------------------------------------
354
355カーネルの様々な領域で何が起きているかを見られるようにするため、多くの
356カーネルサブシステム開発者は彼らの開発ツリーを公開しています。これらの
357ツリーは説明したように -mm カーネルリリースに入れ込まれます。
358
359以下はさまざまなカーネルツリーの中のいくつかのリスト-
360
361 git ツリー-
362 - Kbuild の開発ツリー、Sam Ravnborg <sam@ravnborg.org>
363 kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git
364
365 - ACPI の開発ツリー、 Len Brown <len.brown@intel.com>
366 kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git
367
368 - Block の開発ツリー、Jens Axboe <axboe@suse.de>
369 kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git
370
371 - DRM の開発ツリー、Dave Airlie <airlied@linux.ie>
372 kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git
373
374 - ia64 の開発ツリー、Tony Luck <tony.luck@intel.com>
375 kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
376
377 - ieee1394 の開発ツリー、Jody McIntyre <scjody@modernduck.com>
378 kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git
379
380 - infiniband, Roland Dreier <rolandd@cisco.com>
381 kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git
382
383 - libata, Jeff Garzik <jgarzik@pobox.com>
384 kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git
385
386 - ネットワークドライバ, Jeff Garzik <jgarzik@pobox.com>
387 kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git
388
389 - pcmcia, Dominik Brodowski <linux@dominikbrodowski.net>
390 kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git
391
392 - SCSI, James Bottomley <James.Bottomley@SteelEye.com>
393 kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git
394
395 その他の git カーネルツリーは http://kernel.org/git に一覧表がありま
396 す。
397
398 quilt ツリー-
399 - USB, PCI ドライバコアと I2C, Greg Kroah-Hartman <gregkh@suse.de>
400 kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/
401
402バグレポート
403-------------
404
405bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを追跡する
406場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。
407どう kernel bugzilla を使うかの詳細は、以下を参照してください-
408 http://test.kernel.org/bugzilla/faq.html
409
410メインカーネルソースディレクトリにあるファイル REPORTING-BUGS はカーネ
411ルバグらしいものについてどうレポートするかの良いテンプレートであり、問
412題の追跡を助けるためにカーネル開発者にとってどんな情報が必要なのかの詳
413細が書かれています。
414
415メーリングリスト
416-------------
417
418上のいくつかのドキュメントで述べていますが、コアカーネル開発者の大部分
419は Linux kernel メーリングリストに参加しています。このリストの登録/脱
420退の方法については以下を参照してください-
421 http://vger.kernel.org/vger-lists.html#linux-kernel
422
423このメーリングリストのアーカイブは web 上の多数の場所に存在します。こ
424れらのアーカイブを探すにはサーチエンジンを使いましょう。例えば-
425 http://dir.gmane.org/gmane.linux.kernel
426
427リストに投稿する前にすでにその話題がアーカイブに存在するかどうかを検索
428することを是非やってください。多数の事がすでに詳細に渡って議論されて
429おり、アーカイブにのみ記録されています。
430
431大部分のカーネルサブシステムも自分の個別の開発を実施するメーリングリス
432トを持っています。個々のグループがどんなリストを持っているかは、
433MAINTAINERS ファイルにリストがありますので参照してください。
434
435多くのリストは kernel.org でホストされています。これらの情報は以下にあ
436ります-
437 http://vger.kernel.org/vger-lists.html
438
439メーリングリストを使う場合、良い行動習慣に従うようにしましょう。
440少し安っぽいが、以下の URL は上のリスト(や他のリスト)で会話する場合の
441シンプルなガイドラインを示しています-
442 http://www.albion.com/netiquette/
443
444もし複数の人があなたのメールに返事をした場合、CC: で受ける人のリストは
445だいぶ多くなるでしょう。良い理由がない場合、CC: リストから誰かを削除を
446しないように、また、メーリングリストのアドレスだけにリプライすることの
447ないようにしましょう。1つは送信者から、もう1つはリストからのように、メー
448ルを2回受けることになってもそれに慣れ、しゃれたメールヘッダーを追加し
449てこの状態を変えようとしないように。人々はそのようなことは好みません。
450
451今までのメールでのやりとりとその間のあなたの発言はそのまま残し、
452"John Kernlehacker wrote ...:" の行をあなたのリプライの先頭行にして、
453メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで
454す。
455
456もしパッチをメールに付ける場合は、Documentaion/SubmittingPatches に提
457示されているように、それは プレーンな可読テキストにすることを忘れない
458ようにしましょう。カーネル開発者は 添付や圧縮したパッチを扱いたがりま
459せん-
460彼らはあなたのパッチの行毎にコメントを入れたいので、そのためにはそうす
461るしかありません。あなたのメールプログラムが空白やタブを圧縮しないよう
462に確認した方がいいです。最初の良いテストとしては、自分にメールを送って
463みて、そのパッチを自分で当ててみることです。もしそれがうまく行かないな
464ら、あなたのメールプログラムを直してもらうか、正しく動くように変えるべ
465きです。
466
467とりわけ、他の登録者に対する尊敬を表すようにすることを覚えておいてくだ
468さい。
469
470コミュニティと共に働くこと
471--------------------------
472
473カーネルコミュニティのゴールは可能なかぎり最高のカーネルを提供すること
474です。あなたがパッチを受け入れてもらうために投稿した場合、それは、技術
475的メリットだけがレビューされます。その際、あなたは何を予想すべきでしょ
476うか?
477 - 批判
478 - コメント
479 - 変更の要求
480 - パッチの正当性の証明要求
481 - 沈黙
482
483思い出してください、ここはあなたのパッチをカーネルに入れる話です。あ
484なたは、あなたのパッチに対する批判とコメントを受け入れるべきで、それら
485を技術的レベルで評価して、パッチを再作成するか、なぜそれらの変更をすべ
486きでないかを明確で簡潔な理由の説明を提供してください。
487もし、あなたのパッチに何も反応がない場合、たまにはメールの山に埋もれて
488見逃され、あなたの投稿が忘れられてしまうこともあるので、数日待って再度
489投稿してください。
490
491あなたがやるべきでないものは?
492 - 質問なしにあなたのパッチが受け入れられると想像すること
493 - 守りに入ること
494 - コメントを無視すること
495 - 要求された変更を何もしないでパッチを出し直すこと
496
497可能な限り最高の技術的解決を求めているコミュニティでは、パッチがどのく
498らい有益なのかについては常に異なる意見があります。あなたは協調的である
499べきですし、また、あなたのアイディアをカーネルに対してうまく合わせるよ
500うにすることが望まれています。もしくは、最低限あなたのアイディアがそれ
501だけの価値があるとすすんで証明するようにしなければなりません。
502正しい解決に向かって進もうという意志がある限り、間違うことがあっても許
503容されることを忘れないでください。
504
505あなたの最初のパッチに単に 1ダースもの修正を求めるリストの返答になるこ
506とも普通のことです。これはあなたのパッチが受け入れられないということで
507は *ありません*、そしてあなた自身に反対することを意味するのでも *ありま
508せん*。単に自分のパッチに対して指摘された問題を全て修正して再送すれば
509いいのです。
510
511カーネルコミュニティと企業組織のちがい
512-----------------------------------------------------------------
513
514カーネルコミュニティは大部分の伝統的な会社の開発環境とは異ったやり方で
515動いています。以下は問題を避けるためにできるとよいことののリストです-
516
517 あなたの提案する変更について言うときのうまい言い方:
518
519 - "これは複数の問題を解決します"
520 - "これは2000行のコードを削除します"
521 - "以下のパッチは、私が言おうとしていることを説明するものです"
522 - "私はこれを5つの異なるアーキテクチャでテストしたのですが..."
523 - "以下は一連の小さなパッチ群ですが..."
524 - "これは典型的なマシンでの性能を向上させます.."
525
526 やめた方がいい悪い言い方:
527
528 - このやり方で AIX/ptx/Solaris ではできたので、できるはずだ
529 - 私はこれを20年もの間やってきた、だから
530 - これは、私の会社が金儲けをするために必要だ
531 - これは我々のエンタープライズ向け商品ラインのためである
532 - これは 私が自分のアイディアを記述した、1000ページの設計資料である
533 - 私はこれについて、6ケ月作業している。
534 - 以下は ... に関する5000行のパッチです
535 - 私は現在のぐちゃぐちゃを全部書き直した、それが以下です...
536 - 私は〆切がある、そのためこのパッチは今すぐ適用される必要がある
537
538カーネルコミュニティが大部分の伝統的なソフトウェアエンジニアリングの労
539働環境と異なるもう一つの点は、やりとりに顔を合わせないということです。
540email と irc を第一のコミュニケーションの形とする一つの利点は、性別や
541民族の差別がないことです。Linux カーネルの職場環境は女性や少数民族を受
542容します。なぜなら、email アドレスによってのみあなたが認識されるからで
543す。
544国際的な側面からも活動領域を均等にするようにします。なぜならば、あなた
545は人の名前で性別を想像できないからです。ある男性が アンドレアという名
546前で、女性の名前は パット かもしれません (訳注 Andrea は米国では女性、
547それ以外(欧州など)では男性名として使われることが多い。同様に、Pat は
548Patricia (主に女性名)や Patrick (主に男性名)の略称)。
549Linux カーネルの活動をして、意見を表明したことがある大部分の女性は、前
550向きな経験をもっています。
551
552言葉の壁は英語が得意でない一部の人には問題になります。
553メーリングリストの中できちんとアイディアを交換するには、相当うまく英語
554を操れる必要があることもあります。そのため、あなたは自分のメール
555を送る前に英語で意味が通じているかをチェックすることをお薦めします。
556
557変更を分割する
558---------------------
559
560Linux カーネルコミュニティは、一度に大量のコードの塊を喜んで受容するこ
561とはありません。変更は正確に説明される必要があり、議論され、小さい、個
562別の部分に分割する必要があります。これはこれまで多くの会社がやり慣れて
563きたことと全く正反対のことです。あなたのプロポーザルは、開発プロセスのと
564ても早い段階から紹介されるべきです。そうすれば あなたは自分のやってい
565ることにフィードバックを得られます。これは、コミュニティからみれば、あ
566なたが彼らと一緒にやっているように感じられ、単にあなたの提案する機能の
567ゴミ捨て場として使っているのではない、と感じられるでしょう。
568しかし、一度に 50 もの email をメーリングリストに送りつけるようなことは
569やってはいけません、あなたのパッチ群はいつもどんな時でもそれよりは小さ
570くなければなりません。
571
572パッチを分割する理由は以下です-
573
5741) 小さいパッチはあなたのパッチが適用される見込みを大きくします、カー
575 ネルの人達はパッチが正しいかどうかを確認する時間や労力をかけないか
576 らです。5行のパッチはメンテナがたった1秒見るだけで適用できます。し
577 かし、500行のパッチは、正しいことをレビューするのに数時間かかるかも
578 しれません(時間はパッチのサイズなどにより指数関数に比例してかかりま
579 す)
580 小さいパッチは何かあったときにデバッグもとても簡単になります。パッ
581 チを1個1個取り除くのは、とても大きなパッチを当てた後に(かつ、何かお
582 かしくなった後で)解剖するのに比べればとても簡単です。
583
5842) 小さいパッチを送るだけでなく、送るまえに、書き直して、シンプルにす
585 る(もしくは、単に順番を変えるだけでも)ことも、とても重要です。
586
587以下はカーネル開発者の Al Viro のたとえ話しです:
588
589 "生徒の数学の宿題を採点する先生のことを考えてみてください、先
590 生は生徒が解に到達するまでの試行錯誤をみたいとは思わないでしょ
591 う。先生は簡潔な最高の解をみたいのです。良い生徒はこれを知って
592 おり、そして最終解の前の中間作業を提出することは決してないので
593 す"
594 カーネル開発でもこれは同じです。メンテナー達とレビューア達は、
595 問題を解決する解の背後になる思考プロセスをみたいとは思いません。
596 彼らは単純であざやかな解決方法をみたいのです。
597
598あざやかな解を説明するのと、コミュニティと共に仕事をし、未解決の仕事を
599議論することのバランスをキープするのは難しいかもしれません。
600ですから、開発プロセスの早期段階で改善のためのフィードバックをもらうよ
601うにするのもいいですが、変更点を小さい部分に分割して全体ではまだ完成し
602ていない仕事を(部分的に)取り込んでもらえるようにすることもいいことです。
603
604また、でき上がっていないものや、"将来直す" ようなパッチを、本流に含め
605てもらうように送っても、それは受け付けられないことを理解してください。
606
607あなたの変更を正当化する
608-------------------
609
610あなたのパッチを分割するのと同時に、なぜその変更を追加しなければならな
611いかを Linux コミュニティに知らせることはとても重要です。新機能は必要
612性と有用性で正当化されなければなりません。
613
614あなたの変更の説明
615--------------------
616
617あなたのパッチを送付する場合には、メールの中のテキストで何を言うかにつ
618いて、特別に注意を払ってください。この情報はパッチの ChangeLog に使わ
619れ、いつも皆がみられるように保管されます。これは次のような項目を含め、
620パッチを完全に記述するべきです-
621
622 - なぜ変更が必要か
623 - パッチ全体の設計アプローチ
624 - 実装の詳細
625 - テスト結果
626
627これについて全てがどのようにあるべきかについての詳細は、以下のドキュメ
628ントの ChangeLog セクションをみてください-
629 "The Perfect Patch"
630 http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
631
632これらのどれもが、時にはとても困難です。これらの慣例を完璧に実施するに
633は数年かかるかもしれません。これは継続的な改善のプロセスであり、そのた
634めには多数の忍耐と決意を必要とするものです。でも、諦めないで、これは可
635能なことです。多数の人がすでにできていますし、彼らも皆最初はあなたと同
636じところからスタートしたのですから。
637
638Paolo Ciarrocchi に感謝、彼は彼の書いた "Development Process"
639(http://linux.tar.bz/articles/2.6-development_process)セクショ
640ンをこのテキストの原型にすることを許可してくれました。
641Rundy Dunlap と Gerrit Huizenga はメーリングリストでやるべきこととやっ
642てはいけないことのリストを提供してくれました。
643以下の人々のレビュー、コメント、貢献に感謝。
644Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
645Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi
646Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
647David A. Wheeler, Junio Hamano, Michael Kerrisk, と Alex Shepard
648彼らの支援なしでは、このドキュメントはできなかったでしょう。
649
650Maintainer: Greg Kroah-Hartman <greg@kroah.com>
diff --git a/Documentation/ja_JP/stable_api_nonsense.txt b/Documentation/ja_JP/stable_api_nonsense.txt
new file mode 100644
index 000000000000..b3f2b27f0881
--- /dev/null
+++ b/Documentation/ja_JP/stable_api_nonsense.txt
@@ -0,0 +1,263 @@
1NOTE:
2This is a Japanese translated version of
3"Documentation/stable_api_nonsense.txt".
4This one is maintained by
5IKEDA, Munehiro <m-ikeda@ds.jp.nec.com>
6and JF Project team <http://www.linux.or.jp/JF/>.
7If you find difference with original file or problem in translation,
8please contact the maintainer of this file or JF project.
9
10Please also note that purpose of this file is easier to read for non
11English natives and not to be intended to fork. So, if you have any
12comments or updates of this file, please try to update
13Original(English) file at first.
14
15==================================
16これは、
17linux-2.6.22-rc4/Documentation/stable_api_nonsense.txt の和訳
18です。
19翻訳団体: JF プロジェクト < http://www.linux.or.jp/JF/ >
20翻訳日 : 2007/06/11
21原著作者: Greg Kroah-Hartman < greg at kroah dot com >
22翻訳者 : 池田 宗広 < m-ikeda at ds dot jp dot nec dot com >
23校正者 : Masanori Kobayashi さん < zap03216 at nifty dot ne dot jp >
24 Seiji Kaneko さん < skaneko at a2 dot mbn dot or dot jp >
25==================================
26
27
28
29Linux カーネルのドライバインターフェース
30(あなたの質問すべてに対する回答とその他諸々)
31
32Greg Kroah-Hartman <greg at kroah dot com>
33
34
35この文書は、なぜ Linux ではバイナリカーネルインターフェースが定義
36されていないのか、またはなぜ不変のカーネルインターフェースを持たな
37いのか、ということを説明するために書かれた。ここでの話題は「カーネ
38ル内部の」インターフェースについてであり、ユーザー空間とのインター
39フェースではないことを理解してほしい。カーネルとユーザー空間とのイ
40ンターフェースとはアプリケーションプログラムが使用するものであり、
41つまりシステムコールのインターフェースがこれに当たる。これは今まで
42長きに渡り、かつ今後も「まさしく」不変である。私は確か 0.9 か何か
43より前のカーネルを使ってビルドした古いプログラムを持っているが、そ
44れは最新の 2.6 カーネルでもきちんと動作する。ユーザー空間とのイン
45ターフェースは、ユーザーとアプリケーションプログラマが不変性を信頼
46してよいものの一つである。
47
48
49要旨
50----
51
52あなたは不変のカーネルインターフェースが必要だと考えているかもしれ
53ないが、実際のところはそうではない。あなたは必要としているものが分
54かっていない。あなたが必要としているものは安定して動作するドライバ
55であり、それはドライバがメインのカーネルツリーに含まれる場合のみ得
56ることができる。ドライバがメインのカーネルツリーに含まれていると、
57他にも多くの良いことがある。それは、Linux をより強固で、安定な、成
58熟したオペレーティングシステムにすることができるということだ。これ
59こそ、そもそもあなたが Linux を使う理由のはずだ。
60
61
62はじめに
63--------
64
65カーネル内部のインターフェース変更を心配しなければならないドライバ
66を書きたいなどというのは、変わり者だけだ。この世界のほとんどの人は、
67そのようなドライバがどんなインターフェースを使っているかなど知らな
68いし、そんなドライバのことなど全く気にもかけていない。
69
70
71まず初めに、クローズソースとか、ソースコードの隠蔽とか、バイナリの
72みが配布される使い物にならない代物[訳注(1)]とか、実体はバイナリ
73コードでそれを読み込むためのラッパー部分のみソースコードが公開され
74ているとか、その他用語は何であれ GPL の下にソースコードがリリース
75されていないカーネルドライバに関する法的な問題について、私は「いか
76なる議論も」行うつもりがない。法的な疑問があるのならば、プログラマ
77である私ではなく、弁護士に相談して欲しい。ここでは単に、技術的な問
78題について述べることにする。(法的な問題を軽視しているわけではない。
79それらは実際に存在するし、あなたはそれをいつも気にかけておく必要が
80ある)
81
82訳注(1)
83「使い物にならない代物」の原文は "blob"
84
85
86さてここでは、バイナリカーネルインターフェースについてと、ソースレ
87ベルでのインターフェースの不変性について、という二つの話題を取り上
88げる。この二つは互いに依存する関係にあるが、まずはバイナリインター
89フェースについて議論を行いやっつけてしまおう。
90
91
92バイナリカーネルインターフェース
93--------------------------------
94
95もしソースレベルでのインターフェースが不変ならば、バイナリインター
96フェースも当然のように不変である、というのは正しいだろうか?正しく
97ない。Linux カーネルに関する以下の事実を考えてみてほしい。
98 - あなたが使用するCコンパイラのバージョンによって、カーネル内部
99 の構造体の配置構造は異なったものになる。また、関数は異なった方
100 法でカーネルに含まれることになるかもしれない(例えばインライン
101 関数として扱われたり、扱われなかったりする)。個々の関数がどの
102 ようにコンパイルされるかはそれほど重要ではないが、構造体のパデ
103 ィングが異なるというのは非常に重要である。
104 - あなたがカーネルのビルドオプションをどのように設定するかによっ
105 て、カーネルには広い範囲で異なった事態が起こり得る。
106 - データ構造は異なるデータフィールドを持つかもしれない
107 - いくつかの関数は全く実装されていない状態になり得る
108 (例:SMP向けではないビルドでは、いくつかのロックは中身が
109 カラにコンパイルされる)
110 - カーネル内のメモリは、異なった方法で配置され得る。これはビ
111 ルドオプションに依存している。
112 - Linux は様々な異なるプロセッサアーキテクチャ上で動作する。
113 あるアーキテクチャ用のバイナリドライバを、他のアーキテクチャで
114 正常に動作させる方法はない。
115
116
117ある特定のカーネル設定を使用し、カーネルをビルドしたのと正確に同じ
118Cコンパイラを使用して単にカーネルモジュールをコンパイルするだけで
119も、あなたはこれらいくつもの問題に直面することになる。ある特定の
120Linux ディストリビューションの、ある特定のリリースバージョン用にモ
121ジュールを提供しようと思っただけでも、これらの問題を引き起こすには
122十分である。にも関わらず Linux ディストリビューションの数と、サ
123ポートするディストリビューションのリリース数を掛け算し、それら一つ
124一つについてビルドを行ったとしたら、今度はリリースごとのビルドオプ
125ションの違いという悪夢にすぐさま悩まされることになる。また、ディス
126トリビューションの各リリースバージョンには、異なるハードウェア(プ
127ロセッサタイプや種々のオプション)に対応するため、何種類かのカーネ
128ルが含まれているということも理解して欲しい。従って、ある一つのリ
129リースバージョンだけのためにモジュールを作成する場合でも、あなたは
130何バージョンものモジュールを用意しなければならない。
131
132
133信じて欲しい。このような方法でサポートを続けようとするなら、あなた
134はいずれ正気を失うだろう。遠い昔、私はそれがいかに困難なことか、身
135をもって学んだのだ・・・
136
137
138不変のカーネルソースレベルインターフェース
139------------------------------------------
140
141メインカーネルツリーに含まれていない Linux カーネルドライバを継続
142してサポートしていこうとしている人たちとの議論においては、これは極
143めて「引火性の高い」話題である。[訳注(2)]
144
145訳注(2)
146「引火性の高い」の原文は "volatile"。
147volatile には「揮発性の」「爆発しやすい」という意味の他、「変わり
148やすい」「移り気な」という意味がある。
149「(この話題は)爆発的に激しい論争を巻き起こしかねない」ということ
150を、「(カーネルのソースレベルインターフェースは)移ろい行くもので
151ある」ということを連想させる "volatile" という単語で表現している。
152
153
154Linux カーネルの開発は継続的に速いペースで行われ、決して歩みを緩め
155ることがない。その中でカーネル開発者達は、現状のインターフェースに
156あるバグを見つけ、より良い方法を考え出す。彼らはやがて、現状のイン
157ターフェースがより正しく動作するように修正を行う。その過程で関数の
158名前は変更されるかもしれず、構造体は大きく、または小さくなるかもし
159れず、関数の引数は検討しなおされるかもしれない。そのような場合、引
160き続き全てが正常に動作するよう、カーネル内でこれらのインターフェー
161スを使用している個所も全て同時に修正される。
162
163
164具体的な例として、カーネル内の USB インターフェースを挙げる。USB
165サブシステムはこれまでに少なくとも3回の書き直しが行われ、その結果
166インターフェースが変更された。これらの書き直しはいくつかの異なった
167問題を修正するために行われた。
168 - 同期的データストリームが非同期に変更された。これにより多数のド
169 ライバを単純化でき、全てのドライバのスループットが向上した。今
170 やほとんど全ての USB デバイスは、考えられる最高の速度で動作し
171 ている。
172 - USB ドライバが USB サブシステムのコアから行う、データパケット
173 用のメモリ確保方法が変更された。これに伴い、いくつもの文書化さ
174 れたデッドロック条件を回避するため、全ての USB ドライバはより
175 多くの情報を USB コアに提供しなければならないようになっている。
176
177
178このできごとは、数多く存在するクローズソースのオペレーティングシス
179テムとは全く対照的だ。それらは長期に渡り古い USB インターフェース
180をメンテナンスしなければならない。古いインターフェースが残ることで、
181新たな開発者が偶然古いインターフェースを使い、正しくない方法で開発
182を行ってしまう可能性が生じる。これによりシステムの安定性は危険にさ
183らされることになる。
184
185
186上に挙げたどちらの例においても、開発者達はその変更が重要かつ必要で
187あることに合意し、比較的楽にそれを実行した。もし Linux がソースレ
188ベルでインターフェースの不変性を保証しなければならないとしたら、新
189しいインターフェースを作ると同時に、古い、問題のある方を今後ともメ
190ンテナンスするという余計な仕事を USB の開発者にさせなければならな
191い。Linux の USB 開発者は、自分の時間を使って仕事をしている。よっ
192て、価値のない余計な仕事を報酬もなしに実行しろと言うことはできない。
193
194
195セキュリティ問題も、Linux にとっては非常に重要である。ひとたびセキ
196ュリティに関する問題が発見されれば、それは極めて短期間のうちに修正
197される。セキュリティ問題の発生を防ぐための修正は、カーネルの内部イ
198ンターフェースの変更を何度も引き起こしてきた。その際同時に、変更さ
199れたインターフェースを使用する全てのドライバもまた変更された。これ
200により問題が解消し、将来偶然に問題が再発してしまわないことが保証さ
201れる。もし内部インターフェースの変更が許されないとしたら、このよう
202にセキュリティ問題を修正し、将来再発しないことを保証することなど不
203可能なのだ。
204
205
206カーネルのインターフェースは時が経つにつれクリーンナップを受ける。
207誰も使っていないインターフェースは削除される。これにより、可能な限
208りカーネルが小さく保たれ、現役の全てのインターフェースが可能な限り
209テストされることを保証しているのだ。(使われていないインターフェー
210スの妥当性をテストすることは不可能と言っていいだろう)
211
212
213
214これから何をすべきか
215-----------------------
216
217では、もしメインのカーネルツリーに含まれない Linux カーネルドライ
218バがあったとして、あなたは、つまり開発者は何をするべきだろうか?全
219てのディストリビューションの全てのカーネルバージョン向けにバイナリ
220のドライバを供給することは悪夢であり、カーネルインターフェースの変
221更を追いかけ続けることもまた過酷な仕事だ。
222
223
224答えは簡単。そのドライバをメインのカーネルツリーに入れてしまえばよ
225い。(ここで言及しているのは、GPL に従って公開されるドライバのこと
226だということに注意してほしい。あなたのコードがそれに該当しないなら
227ば、さよなら。幸運を祈ります。ご自分で何とかしてください。Andrew
228と Linus からのコメント<Andrew と Linus のコメントへのリンクをこ
229こに置く>をどうぞ)ドライバがメインツリーに入れば、カーネルのイン
230ターフェースが変更された場合、変更を行った開発者によってドライバも
231修正されることになるだろう。あなたはほとんど労力を払うことなしに、
232常にビルド可能できちんと動作するドライバを手に入れることができる。
233
234
235ドライバをメインのカーネルツリーに入れると、非常に好ましい以下の効
236果がある。
237 - ドライバの品質が向上する一方で、(元の開発者にとっての)メンテ
238 ナンスコストは下がる。
239 - あなたのドライバに他の開発者が機能を追加してくれる。
240 - 誰かがあなたのドライバにあるバグを見つけ、修正してくれる。
241 - 誰かがあなたのドライバにある改善点を見つけてくれる。
242 - 外部インターフェースが変更されドライバの更新が必要になった場合、
243 誰かがあなたの代わりに更新してくれる。
244 - ドライバを入れてくれとディストロに頼まなくても、そのドライバは
245 全ての Linux ディストリビューションに自動的に含まれてリリース
246 される。
247
248
249Linux では、他のどのオペレーティングシステムよりも数多くのデバイス
250が「そのまま」使用できるようになった。また Linux は、どのオペレー
251ティングシステムよりも数多くのプロセッサアーキテクチャ上でそれらの
252デバイスを使用することができるようにもなった。このように、Linux の
253開発モデルは実証されており、今後も間違いなく正しい方向へと進んでい
254くだろう。:)
255
256
257
258------
259
260この文書の初期の草稿に対し、Randy Dunlap, Andrew Morton, David
261Brownell, Hanna Linder, Robert Love, Nishanth Aravamudan から査読
262と助言を頂きました。感謝申し上げます。
263
diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO
new file mode 100644
index 000000000000..48fc67bfbe3d
--- /dev/null
+++ b/Documentation/zh_CN/HOWTO
@@ -0,0 +1,536 @@
1Chinese translated version of Documentation/HOWTO
2
3If you have any comment or update to the content, please contact the
4original document maintainer directly. However, if you have problem
5communicating in English you can also ask the Chinese maintainer for
6help. Contact the Chinese maintainer, if this translation is outdated
7or there is problem with translation.
8
9Maintainer: Greg Kroah-Hartman <greg@kroah.com>
10Chinese maintainer: Li Yang <leoli@freescale.com>
11---------------------------------------------------------------------
12Documentation/HOWTO 的中文翻译
13
14如果想评论或更新本文的内容,请直接联系原文档的维护者。如果你使用英文
15交流有困难的话,也可以向中文版维护者求助。如果本翻译更新不及时或者翻
16译存在问题,请联系中文版维护者。
17
18英文版维护者: Greg Kroah-Hartman <greg@kroah.com>
19中文版维护者: 李阳 Li Yang <leoli@freescale.com>
20中文版翻译者: 李阳 Li Yang <leoli@freescale.com>
21中文版校译者: 钟宇 TripleX Chung <xxx.phy@gmail.com>
22 陈琦 Maggie Chen <chenqi@beyondsoft.com>
23 王聪 Wang Cong <xiyou.wangcong@gmail.com>
24
25以下为正文
26---------------------------------------------------------------------
27
28如何参与Linux内核开发
29---------------------
30
31这是一篇将如何参与Linux内核开发的相关问题一网打尽的终极秘笈。它将指导你
32成为一名Linux内核开发者,并且学会如何同Linux内核开发社区合作。它尽可能不
33包括任何关于内核编程的技术细节,但会给你指引一条获得这些知识的正确途径。
34
35如果这篇文章中的任何内容不再适用,请给文末列出的文件维护者发送补丁。
36
37
38入门
39----
40
41你想了解如何成为一名Linux内核开发者?或者老板吩咐你“给这个设备写个Linux
42驱动程序”?这篇文章的目的就是教会你达成这些目标的全部诀窍,它将描述你需
43要经过的流程以及给出如何同内核社区合作的一些提示。它还将试图解释内核社区
44为何这样运作。
45
46Linux内核大部分是由C语言写成的,一些体系结构相关的代码用到了汇编语言。要
47参与内核开发,你必须精通C语言。除非你想为某个架构开发底层代码,否则你并
48不需要了解(任何体系结构的)汇编语言。下面列举的书籍虽然不能替代扎实的C
49语言教育和多年的开发经验,但如果需要的话,做为参考还是不错的:
50 - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
51 《C程序设计语言(第2版·新版)》(徐宝文 李志 译)[机械工业出版社]
52 - "Practical C Programming" by Steve Oualline [O'Reilly]
53 《实用C语言编程(第三版)》(郭大海 译)[中国电力出版社]
54 - "C: A Reference Manual" by Harbison and Steele [Prentice Hall]
55 《C语言参考手册(原书第5版)》(邱仲潘 等译)[机械工业出版社]
56
57Linux内核使用GNU C和GNU工具链开发。虽然它遵循ISO C89标准,但也用到了一些
58标准中没有定义的扩展。内核是自给自足的C环境,不依赖于标准C库的支持,所以
59并不支持C标准中的部分定义。比如long long类型的大数除法和浮点运算就不允许
60使用。有时候确实很难弄清楚内核对工具链的要求和它所使用的扩展,不幸的是目
61前还没有明确的参考资料可以解释它们。请查阅gcc信息页(使用“info gcc”命令
62显示)获得一些这方面信息。
63
64请记住你是在学习怎么和已经存在的开发社区打交道。它由一群形形色色的人组成,
65他们对代码、风格和过程有着很高的标准。这些标准是在长期实践中总结出来的,
66适应于地理上分散的大型开发团队。它们已经被很好得整理成档,建议你在开发
67之前尽可能多的学习这些标准,而不要期望别人来适应你或者你公司的行为方式。
68
69
70法律问题
71--------
72
73Linux内核源代码都是在GPL(通用公共许可证)的保护下发布的。要了解这种许可
74的细节请查看源代码主目录下的COPYING文件。如果你对它还有更深入问题请联系
75律师,而不要在Linux内核邮件组上提问。因为邮件组里的人并不是律师,不要期
76望他们的话有法律效力。
77
78对于GPL的常见问题和解答,请访问以下链接:
79 http://www.gnu.org/licenses/gpl-faq.html
80
81
82文档
83----
84
85Linux内核代码中包含有大量的文档。这些文档对于学习如何与内核社区互动有着
86不可估量的价值。当一个新的功能被加入内核,最好把解释如何使用这个功能的文
87档也放进内核。当内核的改动导致面向用户空间的接口发生变化时,最好将相关信
88息或手册页(manpages)的补丁发到mtk-manpages@gmx.net,以向手册页(manpages)
89的维护者解释这些变化。
90
91以下是内核代码中需要阅读的文档:
92 README
93 文件简要介绍了Linux内核的背景,并且描述了如何配置和编译内核。内核的
94 新用户应该从这里开始。
95
96 Documentation/Changes
97 文件给出了用来编译和使用内核所需要的最小软件包列表。
98
99 Documentation/CodingStyle
100 描述Linux内核的代码风格和理由。所有新代码需要遵守这篇文档中定义的规
101 范。大多数维护者只会接收符合规定的补丁,很多人也只会帮忙检查符合风格
102 的代码。
103
104 Documentation/SubmittingPatches
105 Documentation/SubmittingDrivers
106 这两份文档明确描述如何创建和发送补丁,其中包括(但不仅限于):
107 - 邮件内容
108 - 邮件格式
109 - 选择收件人
110 遵守这些规定并不能保证提交成功(因为所有补丁需要通过严格的内容和风格
111 审查),但是忽视他们几乎就意味着失败。
112
113 其他关于如何正确地生成补丁的优秀文档包括:
114 "The Perfect Patch"
115 http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
116 "Linux kernel patch submission format"
117 http://linux.yyz.us/patch-format.html
118
119 Documentation/stable_api_nonsense.txt
120 论证内核为什么特意不包括稳定的内核内部API,也就是说不包括像这样的特
121 性:
122 - 子系统中间层(为了兼容性?)
123 - 在不同操作系统间易于移植的驱动程序
124 - 减缓(甚至阻止)内核代码的快速变化
125 这篇文档对于理解Linux的开发哲学至关重要。对于将开发平台从其他操作系
126 统转移到Linux的人来说也很重要。
127
128 Documentation/SecurityBugs
129 如果你认为自己发现了Linux内核的安全性问题,请根据这篇文档中的步骤来
130 提醒其他内核开发者并帮助解决这个问题。
131
132 Documentation/ManagementStyle
133 描述内核维护者的工作方法及其共有特点。这对于刚刚接触内核开发(或者对
134 它感到好奇)的人来说很重要,因为它解释了很多对于内核维护者独特行为的
135 普遍误解与迷惑。
136
137 Documentation/stable_kernel_rules.txt
138 解释了稳定版内核发布的规则,以及如何将改动放入这些版本的步骤。
139
140 Documentation/kernel-docs.txt
141 有助于内核开发的外部文档列表。如果你在内核自带的文档中没有找到你想找
142 的内容,可以查看这些文档。
143
144 Documentation/applying-patches.txt
145 关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍
146
147内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何
148妥善处理加锁的规则。生成的文档会放在 Documentation/DocBook/目录下。在内
149核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册
150页等不同格式的文档:
151 make pdfdocs
152 make psdocs
153 make htmldocs
154 make mandocs
155
156
157如何成为内核开发者
158------------------
159如果你对Linux内核开发一无所知,你应该访问“Linux内核新手”计划:
160 http://kernelnewbies.org
161它拥有一个可以问各种最基本的内核开发问题的邮件列表(在提问之前一定要记得
162查找已往的邮件,确认是否有人已经回答过相同的问题)。它还拥有一个可以获得
163实时反馈的IRC聊天频道,以及大量对于学习Linux内核开发相当有帮助的文档。
164
165网站简要介绍了源代码组织结构、子系统划分以及目前正在进行的项目(包括内核
166中的和单独维护的)。它还提供了一些基本的帮助信息,比如如何编译内核和打补
167丁。
168
169如果你想加入内核开发社区并协助完成一些任务,却找不到从哪里开始,可以访问
170“Linux内核房管员”计划:
171 http://janitor.kernelnewbies.org/
172这是极佳的起点。它提供一个相对简单的任务列表,列出内核代码中需要被重新
173整理或者改正的地方。通过和负责这个计划的开发者们一同工作,你会学到将补丁
174集成进内核的基本原理。如果还没有决定下一步要做什么的话,你还可能会得到方
175向性的指点。
176
177如果你已经有一些现成的代码想要放到内核中,但是需要一些帮助来使它们拥有正
178确的格式。请访问“内核导师”计划。这个计划就是用来帮助你完成这个目标的。它
179是一个邮件列表,地址如下:
180 http://selenic.com/mailman/listinfo/kernel-mentors
181
182在真正动手修改内核代码之前,理解要修改的代码如何运作是必需的。要达到这个
183目的,没什么办法比直接读代码更有效了(大多数花招都会有相应的注释),而且
184一些特制的工具还可以提供帮助。例如,“Linux代码交叉引用”项目就是一个值得
185特别推荐的帮助工具,它将源代码显示在有编目和索引的网页上。其中一个更新及
186时的内核源码库,可以通过以下地址访问:
187 http://sosdg.org/~coywolf/lxr/
188
189
190开发流程
191--------
192
193目前Linux内核开发流程包括几个“主内核分支”和很多子系统相关的内核分支。这
194些分支包括:
195 - 2.6.x主内核源码树
196 - 2.6.x.y -stable内核源码树
197 - 2.6.x -git内核补丁集
198 - 2.6.x -mm内核补丁集
199 - 子系统相关的内核源码树和补丁集
200
201
2022.6.x内核主源码树
203-----------------
2042.6.x内核是由Linus Torvalds(Linux的创造者)亲自维护的。你可以在
205kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循以下步
206骤:
207 - 每当一个新版本的内核被发布,为期两周的集成窗口将被打开。在这段时间里
208 维护者可以向Linus提交大段的修改,通常这些修改已经被放到-mm内核中几个
209 星期了。提交大量修改的首选方式是使用git工具(内核的代码版本管理工具
210 ,更多的信息可以在http://git.or.cz/获取),不过使用普通补丁也是可以
211 的。
212 - 两个星期以后-rc1版本内核发布。之后只有不包含可能影响整个内核稳定性的
213 新功能的补丁才可能被接受。请注意一个全新的驱动程序(或者文件系统)有
214 可能在-rc1后被接受是因为这样的修改完全独立,不会影响其他的代码,所以
215 没有造成内核退步的风险。在-rc1以后也可以用git向Linus提交补丁,不过所
216 有的补丁需要同时被发送到相应的公众邮件列表以征询意见。
217 - 当Linus认为当前的git源码树已经达到一个合理健全的状态足以发布供人测试
218 时,一个新的-rc版本就会被发布。计划是每周都发布新的-rc版本。
219 - 这个过程一直持续下去直到内核被认为达到足够稳定的状态,持续时间大概是
220 6个星期。
221
222关于内核发布,值得一提的是Andrew Morton在linux-kernel邮件列表中如是说:
223 “没有人知道新内核何时会被发布,因为发布是根据已知bug的情况来决定
224 的,而不是根据一个事先制定好的时间表。”
225
226
2272.6.x.y -stable(稳定版)内核源码树
228-----------------------------------
229由4个数字组成的内核版本号说明此内核是-stable版本。它们包含基于2.6.x版本
230内核的相对较小且至关重要的修补,这些修补针对安全性问题或者严重的内核退步。
231
232这种版本的内核适用于那些期望获得最新的稳定版内核并且不想参与测试开发版或
233者实验版的用户。
234
235如果没有2.6.x.y版本内核存在,那么最新的2.6.x版本内核就相当于是当前的稳定
236版内核。
237
2382.6.x.y版本由“稳定版”小组(邮件地址<stable@kernel.org>)维护,一般隔周发
239布新版本。
240
241内核源码中的Documentation/stable_kernel_rules.txt文件具体描述了可被稳定
242版内核接受的修改类型以及发布的流程。
243
244
2452.6.x -git补丁集
246----------------
247Linus的内核源码树的每日快照,这个源码树是由git工具管理的(由此得名)。这
248些补丁通常每天更新以反映Linus的源码树的最新状态。它们比-rc版本的内核源码
249树更具试验性质,因为这个补丁集是全自动生成的,没有任何人来确认其是否真正
250健全。
251
252
2532.6.x -mm补丁集
254---------------
255这是由Andrew Morton维护的试验性内核补丁集。Andrew将所有子系统的内核源码
256和补丁拼凑到一起,并且加入了大量从linux-kernel邮件列表中采集的补丁。这个
257源码树是新功能和补丁的试炼场。当补丁在-mm补丁集里证明了其价值以后Andrew
258或者相应子系统的维护者会将补丁发给Linus以便集成进主内核源码树。
259
260在将所有新补丁发给Linus以集成到主内核源码树之前,我们非常鼓励先把这些补
261丁放在-mm版内核源码树中进行测试。
262
263这些内核版本不适合在需要稳定运行的系统上运行,因为运行它们比运行任何其他
264内核分支都更具有风险。
265
266如果你想为内核开发进程提供帮助,请尝试并使用这些内核版本,并在
267linux-kernel邮件列表中提供反馈,告诉大家你遇到了问题还是一切正常。
268
269通常-mm版补丁集不光包括这些额外的试验性补丁,还包括发布时-git版主源码树
270中的改动。
271
272-mm版内核没有固定的发布周期,但是通常在每两个-rc版内核发布之间都会有若干
273个-mm版内核发布(一般是1至3个)。
274
275
276子系统相关内核源码树和补丁集
277----------------------------
278相当一部分内核子系统开发者会公开他们自己的开发源码树,以便其他人能了解内
279核的不同领域正在发生的事情。如上所述,这些源码树会被集成到-mm版本内核中。
280
281下面是目前可用的一些内核源码树的列表:
282 通过git管理的源码树:
283 - Kbuild开发源码树, Sam Ravnborg <sam@ravnborg.org>
284 git.kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git
285
286 - ACPI开发源码树, Len Brown <len.brown@intel.com>
287 git.kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git
288
289 - 块设备开发源码树, Jens Axboe <axboe@suse.de>
290 git.kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git
291
292 - DRM开发源码树, Dave Airlie <airlied@linux.ie>
293 git.kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git
294
295 - ia64开发源码树, Tony Luck <tony.luck@intel.com>
296 git.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
297
298 - ieee1394开发源码树, Jody McIntyre <scjody@modernduck.com>
299 git.kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git
300
301 - infiniband开发源码树, Roland Dreier <rolandd@cisco.com>
302 git.kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git
303
304 - libata开发源码树, Jeff Garzik <jgarzik@pobox.com>
305 git.kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git
306
307 - 网络驱动程序开发源码树, Jeff Garzik <jgarzik@pobox.com>
308 git.kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git
309
310 - pcmcia开发源码树, Dominik Brodowski <linux@dominikbrodowski.net>
311 git.kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git
312
313 - SCSI开发源码树, James Bottomley <James.Bottomley@SteelEye.com>
314 git.kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git
315
316 使用quilt管理的补丁集:
317 - USB, PCI, 驱动程序核心和I2C, Greg Kroah-Hartman <gregkh@suse.de>
318 kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/
319 - x86-64, 部分i386, Andi Kleen <ak@suse.de>
320 ftp.firstfloor.org:/pub/ak/x86_64/quilt/
321
322 其他内核源码树可以在http://git.kernel.org的列表中和MAINTAINERS文件里
323 找到。
324
325报告bug
326-------
327
328bugzilla.kernel.org是Linux内核开发者们用来跟踪内核Bug的网站。我们鼓励用
329户在这个工具中报告找到的所有bug。如何使用内核bugzilla的细节请访问:
330 http://test.kernel.org/bugzilla/faq.html
331
332内核源码主目录中的REPORTING-BUGS文件里有一个很好的模板。它指导用户如何报
333告可能的内核bug以及需要提供哪些信息来帮助内核开发者们找到问题的根源。
334
335
336利用bug报告
337-----------
338
339练习内核开发技能的最好办法就是修改其他人报告的bug。你不光可以帮助内核变
340得更加稳定,还可以学会如何解决实际问题从而提高自己的技能,并且让其他开发
341者感受到你的存在。修改bug是赢得其他开发者赞誉的最好办法,因为并不是很多
342人都喜欢浪费时间去修改别人报告的bug。
343
344要尝试修改已知的bug,请访问http://bugzilla.kernel.org网址。如果你想获得
345最新bug的通知,可以订阅bugme-new邮件列表(只有新的bug报告会被寄到这里)
346或者订阅bugme-janitor邮件列表(所有bugzilla的变动都会被寄到这里)。
347
348 http://lists.osdl.org/mailman/listinfo/bugme-new
349 http://lists.osdl.org/mailman/listinfo/bugme-janitors
350
351
352邮件列表
353--------
354
355正如上面的文档所描述,大多数的骨干内核开发者都加入了Linux Kernel邮件列
356表。如何订阅和退订列表的细节可以在这里找到:
357 http://vger.kernel.org/vger-lists.html#linux-kernel
358网上很多地方都有这个邮件列表的存档(archive)。可以使用搜索引擎来找到这些
359存档。比如:
360 http://dir.gmane.org/gmane.linux.kernel
361在发信之前,我们强烈建议你先在存档中搜索你想要讨论的问题。很多已经被详细
362讨论过的问题只在邮件列表的存档中可以找到。
363
364大多数内核子系统也有自己独立的邮件列表来协调各自的开发工作。从
365MAINTAINERS文件中可以找到不同话题对应的邮件列表。
366
367很多邮件列表架设在kernel.org服务器上。这些列表的信息可以在这里找到:
368 http://vger.kernel.org/vger-lists.html
369
370在使用这些邮件列表时,请记住保持良好的行为习惯。下面的链接提供了与这些列
371表(或任何其它邮件列表)交流的一些简单规则,虽然内容有点滥竽充数。
372 http://www.albion.com/netiquette/
373
374当有很多人回复你的邮件时,邮件的抄送列表会变得很长。请不要将任何人从抄送
375列表中删除,除非你有足够的理由这么做。也不要只回复到邮件列表。请习惯于同
376一封邮件接收两次(一封来自发送者一封来自邮件列表),而不要试图通过添加一
377些奇特的邮件头来解决这个问题,人们不会喜欢的。
378
379记住保留你所回复内容的上下文和源头。在你回复邮件的顶部保留“某某某说到……”
380这几行。将你的评论加在被引用的段落之间而不要放在邮件的顶部。
381
382如果你在邮件中附带补丁,请确认它们是可以直接阅读的纯文本(如
383Documentation/SubmittingPatches文档中所述)。内核开发者们不希望遇到附件
384或者被压缩了的补丁。只有这样才能保证他们可以直接评论你的每行代码。请确保
385你使用的邮件发送程序不会修改空格和制表符。一个防范性的测试方法是先将邮件
386发送给自己,然后自己尝试是否可以顺利地打上收到的补丁。如果测试不成功,请
387调整或者更换你的邮件发送程序直到它正确工作为止。
388
389总而言之,请尊重其他的邮件列表订阅者。
390
391
392同内核社区合作
393----------------
394
395内核社区的目标就是提供尽善尽美的内核。所以当你提交补丁期望被接受进内核的
396时候,它的技术价值以及其他方面都将被评审。那么你可能会得到什么呢?
397 - 批评
398 - 评论
399 - 要求修改
400 - 要求证明修改的必要性
401 - 沉默
402
403要记住,这些是把补丁放进内核的正常情况。你必须学会听取对补丁的批评和评论,
404从技术层面评估它们,然后要么重写你的补丁要么简明扼要地论证修改是不必要
405的。如果你发的邮件没有得到任何回应,请过几天后再试一次,因为有时信件会湮
406没在茫茫信海中。
407
408你不应该做的事情:
409 - 期望自己的补丁不受任何质疑就直接被接受
410 - 翻脸
411 - 忽略别人的评论
412 - 没有按照别人的要求做任何修改就重新提交
413
414在一个努力追寻最好技术方案的社区里,对于一个补丁有多少好处总会有不同的见
415解。你必须要抱着合作的态度,愿意改变自己的观点来适应内核的风格。或者至少
416愿意去证明你的想法是有价值的。记住,犯错误是允许的,只要你愿意朝着正确的
417方案去努力。
418
419如果你的第一个补丁换来的是一堆修改建议,这是很正常的。这并不代表你的补丁
420不会被接受,也不意味着有人和你作对。你只需要改正所有提出的问题然后重新发
421送你的补丁。
422
423内核社区和公司文化的差异
424------------------------
425
426内核社区的工作模式同大多数传统公司开发队伍的工作模式并不相同。下面这些例
427子,可以帮助你避免某些可能发生问题:
428 用这些话介绍你的修改提案会有好处:
429 - 它同时解决了多个问题
430 - 它删除了2000行代码
431 - 这是补丁,它已经解释了我想要说明的
432 - 我在5种不同的体系结构上测试过它……
433 - 这是一系列小补丁用来……
434 - 这个修改提高了普通机器的性能……
435
436 应该避免如下的说法:
437 - 我们在AIX/ptx/Solaris就是这么做的,所以这么做肯定是好的……
438 - 我做这行已经20年了,所以……
439 - 为了我们公司赚钱考虑必须这么做
440 - 这是我们的企业产品线所需要的
441 - 这里是描述我观点的1000页设计文档
442 - 这是一个5000行的补丁用来……
443 - 我重写了现在乱七八糟的代码,这就是……
444 - 我被规定了最后期限,所以这个补丁需要立刻被接受
445
446另外一个内核社区与大部分传统公司的软件开发队伍不同的地方是无法面对面地交
447流。使用电子邮件和IRC聊天工具做为主要沟通工具的一个好处是性别和种族歧视
448将会更少。Linux内核的工作环境更能接受妇女和少数族群,因为每个人在别人眼
449里只是一个邮件地址。国际化也帮助了公平的实现,因为你无法通过姓名来判断人
450的性别。男人有可能叫李丽,女人也有可能叫王刚。大多数在Linux内核上工作过
451并表达过看法的女性对在linux上工作的经历都给出了正面的评价。
452
453对于一些不习惯使用英语的人来说,语言可能是一个引起问题的障碍。在邮件列表
454中要正确地表达想法必需良好地掌握语言,所以建议你在发送邮件之前最好检查一
455下英文写得是否正确。
456
457
458拆分修改
459--------
460
461Linux内核社区并不喜欢一下接收大段的代码。修改需要被恰当地介绍、讨论并且
462拆分成独立的小段。这几乎完全和公司中的习惯背道而驰。你的想法应该在开发最
463开始的阶段就让大家知道,这样你就可以及时获得对你正在进行的开发的反馈。这
464样也会让社区觉得你是在和他们协作,而不是仅仅把他们当作倾销新功能的对象。
465无论如何,你不要一次性地向邮件列表发送50封信,你的补丁序列应该永远用不到
466这么多。
467
468将补丁拆开的原因如下:
469
4701) 小的补丁更有可能被接受,因为它们不需要太多的时间和精力去验证其正确性。
471 一个5行的补丁,可能在维护者看了一眼以后就会被接受。而500行的补丁则
472 需要数个小时来审查其正确性(所需时间随补丁大小增加大约呈指数级增长)。
473
474 当出了问题的时候,小的补丁也会让调试变得非常容易。一个一个补丁地回溯
475 将会比仔细剖析一个被打上的大补丁(这个补丁破坏了其他东西)容易得多。
476
4772)不光发送小的补丁很重要,在提交之前重新编排、化简(或者仅仅重新排列)
478 补丁也是很重要的。
479
480这里有内核开发者Al Viro打的一个比方:
481 “想象一个老师正在给学生批改数学作业。老师并不希望看到学生为了得
482 到正确解法所进行的尝试和产生的错误。他希望看到的是最干净最优雅的
483 解答。好学生了解这点,绝不会把最终解决之前的中间方案提交上去。”
484
485 内核开发也是这样。维护者和评审者不希望看到一个人在解决问题时的思
486 考过程。他们只希望看到简单和优雅的解决方案。
487
488直接给出一流的解决方案,和社区一起协作讨论尚未完成的工作,这两者之间似乎
489很难找到一个平衡点。所以最好尽早开始收集有利于你进行改进的反馈;同时也要
490保证修改分成很多小块,这样在整个项目都准备好被包含进内核之前,其中的一部
491分可能会先被接收。
492
493必须了解这样做是不可接受的:试图将未完成的工作提交进内核,然后再找时间修
494复。
495
496
497证明修改的必要性
498----------------
499除了将补丁拆成小块,很重要的一点是让Linux社区了解他们为什么需要这样修改。
500你必须证明新功能是有人需要的并且是有用的。
501
502
503记录修改
504--------
505
506当你发送补丁的时候,需要特别留意邮件正文的内容。因为这里的信息将会做为补
507丁的修改记录(ChangeLog),会被一直保留以备大家查阅。它需要完全地描述补丁,
508包括:
509 - 为什么需要这个修改
510 - 补丁的总体设计
511 - 实现细节
512 - 测试结果
513
514想了解它具体应该看起来像什么,请查阅以下文档中的“ChangeLog”章节:
515 “The Perfect Patch”
516 http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
517
518
519这些事情有时候做起来很难。要在任何方面都做到完美可能需要好几年时间。这是
520一个持续提高的过程,它需要大量的耐心和决心。只要不放弃,你一定可以做到。
521很多人已经做到了,而他们都曾经和现在的你站在同样的起点上。
522
523
524---------------
525感谢Paolo Ciarrocchi允许“开发流程”部分基于他所写的文章
526(http://linux.tar.bz/articles/2.6-development_process),感谢Randy
527Dunlap和Gerrit Huizenga完善了应该说和不该说的列表。感谢Pat Mochel, Hanna
528Linder, Randy Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer,
529Kees Cook, Andrew Morton, Andi Kleen, Vadim Lobanov, Jesper Juhl, Adrian
530Bunk, Keri Harris, Frans Pop, David A. Wheeler, Junio Hamano, Michael
531Kerrisk和Alex Shepard的评审、建议和贡献。没有他们的帮助,这篇文档是不可
532能完成的。
533
534
535
536英文版维护者: Greg Kroah-Hartman <greg@kroah.com>
diff --git a/Documentation/zh_CN/stable_api_nonsense.txt b/Documentation/zh_CN/stable_api_nonsense.txt
new file mode 100644
index 000000000000..c26a27d1ee7d
--- /dev/null
+++ b/Documentation/zh_CN/stable_api_nonsense.txt
@@ -0,0 +1,157 @@
1Chinese translated version of Documentation/stable_api_nonsense.txt
2
3If you have any comment or update to the content, please contact the
4original document maintainer directly. However, if you have problem
5communicating in English you can also ask the Chinese maintainer for help.
6Contact the Chinese maintainer, if this translation is outdated or there
7is problem with translation.
8
9Maintainer: Greg Kroah-Hartman <greg@kroah.com>
10Chinese maintainer: TripleX Chung <zhongyu@18mail.cn>
11---------------------------------------------------------------------
12Documentation/stable_api_nonsense.txt 的中文翻译
13
14如果想评论或更新本文的内容,请直接联系原文档的维护者。如果你使用英文
15交流有困难的话,也可以向中文版维护者求助。如果本翻译更新不及时或者翻
16译存在问题,请联系中文版维护者。
17
18英文版维护者: Greg Kroah-Hartman <greg@kroah.com>
19中文版维护者: 钟宇 TripleX Chung <zhongyu@18mail.cn>
20中文版翻译者: 钟宇 TripleX Chung <zhongyu@18mail.cn>
21中文版校译者: 李阳 Li Yang <leoli@freescale.com>
22以下为正文
23---------------------------------------------------------------------
24
25写作本文档的目的,是为了解释为什么Linux既没有二进制内核接口,也没有稳定
26的内核接口。这里所说的内核接口,是指内核里的接口,而不是内核和用户空间
27的接口。内核到用户空间的接口,是提供给应用程序使用的系统调用,系统调用
28在历史上几乎没有过变化,将来也不会有变化。我有一些老应用程序是在0.9版本
29或者更早版本的内核上编译的,在使用2.6版本内核的Linux发布上依然用得很好
30。用户和应用程序作者可以将这个接口看成是稳定的。
31
32
33执行纲要
34--------
35
36你也许以为自己想要稳定的内核接口,但是你不清楚你要的实际上不是它。你需
37要的其实是稳定的驱动程序,而你只有将驱动程序放到公版内核的源代码树里,
38才有可能达到这个目的。而且这样做还有很多其它好处,正是因为这些好处使得
39Linux能成为强壮,稳定,成熟的操作系统,这也是你最开始选择Linux的原因。
40
41
42入门
43-----
44
45只有那些写驱动程序的“怪人”才会担心内核接口的改变,对广大用户来说,既
46看不到内核接口,也不需要去关心它。
47
48首先,我不打算讨论关于任何非GPL许可的内核驱动的法律问题,这些非GPL许可
49的驱动程序包括不公开源代码,隐藏源代码,二进制或者是用源代码包装,或者
50是其它任何形式的不能以GPL许可公开源代码的驱动程序。如果有法律问题,请咨
51询律师,我只是一个程序员,所以我只打算探讨技术问题(不是小看法律问题,
52法律问题很实际,并且需要一直关注)。
53
54既然只谈技术问题,我们就有了下面两个主题:二进制内核接口和稳定的内核源
55代码接口。这两个问题是互相关联的,让我们先解决掉二进制接口的问题。
56
57
58二进制内核接口
59--------------
60假如我们有一个稳定的内核源代码接口,那么自然而然的,我们就拥有了稳定的
61二进制接口,是这样的吗?错。让我们看看关于Linux内核的几点事实:
62 - 取决于所用的C编译器的版本,不同的内核数据结构里的结构体的对齐方
63式会有差别,代码中不同函数的表现形式也不一样(函数是不是被inline编译取
64决于编译器行为)。不同的函数的表现形式并不重要,但是数据结构内部的对齐
65方式很关键。
66 - 取决于内核的配置选项,不同的选项会让内核的很多东西发生改变:
67 - 同一个结构体可能包含不同的成员变量
68 - 有的函数可能根本不会被实现(比如编译的时候没有选择SMP支持
69,一些锁函数就会被定义成空函数)。
70 - 内核使用的内存会以不同的方式对齐,这取决于不同的内核配置选
71项。
72 - Linux可以在很多的不同体系结构的处理器上运行。在某个体系结构上编
73译好的二进制驱动程序,不可能在另外一个体系结构上正确的运行。
74
75对于一个特定的内核,满足这些条件并不难,使用同一个C编译器和同样的内核配
76置选项来编译驱动程序模块就可以了。这对于给一个特定Linux发布的特定版本提
77供驱动程序,是完全可以满足需求的。但是如果你要给不同发布的不同版本都发
78布一个驱动程序,就需要在每个发布上用不同的内核设置参数都编译一次内核,
79这简直跟噩梦一样。而且还要注意到,每个Linux发布还提供不同的Linux内核,
80这些内核都针对不同的硬件类型进行了优化(有很多种不同的处理器,还有不同
81的内核设置选项)。所以每发布一次驱动程序,都需要提供很多不同版本的内核
82模块。
83
84相信我,如果你真的要采取这种发布方式,一定会慢慢疯掉,我很久以前就有过
85深刻的教训...
86
87
88稳定的内核源代码接口
89--------------------
90
91如果有人不将他的内核驱动程序,放入公版内核的源代码树,而又想让驱动程序
92一直保持在最新的内核中可用,那么这个话题将会变得没完没了。
93 内核开发是持续而且快节奏的,从来都不会慢下来。内核开发人员在当前接口中
94找到bug,或者找到更好的实现方式。一旦发现这些,他们就很快会去修改当前的
95接口。修改接口意味着,函数名可能会改变,结构体可能被扩充或者删减,函数
96的参数也可能发生改变。一旦接口被修改,内核中使用这些接口的地方需要同时
97修正,这样才能保证所有的东西继续工作。
98
99举一个例子,内核的USB驱动程序接口在USB子系统的整个生命周期中,至少经历
100了三次重写。这些重写解决以下问题:
101 - 把数据流从同步模式改成非同步模式,这个改动减少了一些驱动程序的
102复杂度,提高了所有USB驱动程序的吞吐率,这样几乎所有的USB设备都能以最大
103速率工作了。
104 - 修改了USB核心代码中为USB驱动分配数据包内存的方式,所有的驱动都
105需要提供更多的参数给USB核心,以修正了很多已经被记录在案的死锁。
106
107这和一些封闭源代码的操作系统形成鲜明的对比,在那些操作系统上,不得不额
108外的维护旧的USB接口。这导致了一个可能性,新的开发者依然会不小心使用旧的
109接口,以不恰当的方式编写代码,进而影响到操作系统的稳定性。
110 在上面的例子中,所有的开发者都同意这些重要的改动,在这样的情况下修改代
111价很低。如果Linux保持一个稳定的内核源代码接口,那么就得创建一个新的接口
112;旧的,有问题的接口必须一直维护,给Linux USB开发者带来额外的工作。既然
113所有的Linux USB驱动的作者都是利用自己的时间工作,那么要求他们去做毫无意
114义的免费额外工作,是不可能的。
115 安全问题对Linux来说十分重要。一个安全问题被发现,就会在短时间内得到修
116正。在很多情况下,这将导致Linux内核中的一些接口被重写,以从根本上避免安
117全问题。一旦接口被重写,所有使用这些接口的驱动程序,必须同时得到修正,
118以确定安全问题已经得到修复并且不可能在未来还有同样的安全问题。如果内核
119内部接口不允许改变,那么就不可能修复这样的安全问题,也不可能确认这样的
120安全问题以后不会发生。
121开发者一直在清理内核接口。如果一个接口没有人在使用了,它就会被删除。这
122样可以确保内核尽可能的小,而且所有潜在的接口都会得到尽可能完整的测试
123(没有人使用的接口是不可能得到良好的测试的)。
124
125
126要做什么
127-------
128
129如果你写了一个Linux内核驱动,但是它还不在Linux源代码树里,作为一个开发
130者,你应该怎么做?为每个发布的每个版本提供一个二进制驱动,那简直是一个
131噩梦,要跟上永远处于变化之中的内核接口,也是一件辛苦活。
132很简单,让你的驱动进入内核源代码树(要记得我们在谈论的是以GPL许可发行
133的驱动,如果你的代码不符合GPL,那么祝你好运,你只能自己解决这个问题了,
134你这个吸血鬼<把Andrew和Linus对吸血鬼的定义链接到这里>)。当你的代码加入
135公版内核源代码树之后,如果一个内核接口改变,你的驱动会直接被修改接口的
136那个人修改。保证你的驱动永远都可以编译通过,并且一直工作,你几乎不需要
137做什么事情。
138
139把驱动放到内核源代码树里会有很多的好处:
140 - 驱动的质量会提升,而维护成本(对原始作者来说)会下降。
141 - 其他人会给驱动添加新特性。
142 - 其他人会找到驱动中的bug并修复。
143 - 其他人会在驱动中找到性能优化的机会。
144 - 当外部的接口的改变需要修改驱动程序的时候,其他人会修改驱动程序
145
146 - 不需要联系任何发行商,这个驱动会自动的随着所有的Linux发布一起发
147布。
148
149和别的操作系统相比,Linux为更多不同的设备提供现成的驱动,而且能在更多不
150同体系结构的处理器上支持这些设备。这个经过考验的开发模式,必然是错不了
151的 :)
152
153-------------
154感谢 Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder,
155Robert Love, and Nishanth Aravamudan 对于本文档早期版本的评审和建议。
156
157英文版维护者: Greg Kroah-Hartman <greg@kroah.com>