diff options
Diffstat (limited to 'kernel/Documentation/ja_JP')
| -rw-r--r-- | kernel/Documentation/ja_JP/HOWTO | 644 | ||||
| -rw-r--r-- | kernel/Documentation/ja_JP/SubmitChecklist | 111 | ||||
| -rw-r--r-- | kernel/Documentation/ja_JP/SubmittingPatches | 719 | ||||
| -rw-r--r-- | kernel/Documentation/ja_JP/stable_api_nonsense.txt | 263 | ||||
| -rw-r--r-- | kernel/Documentation/ja_JP/stable_kernel_rules.txt | 84 |
5 files changed, 1821 insertions, 0 deletions
diff --git a/kernel/Documentation/ja_JP/HOWTO b/kernel/Documentation/ja_JP/HOWTO new file mode 100644 index 000000000..b61885c35 --- /dev/null +++ b/kernel/Documentation/ja_JP/HOWTO @@ -0,0 +1,644 @@ +NOTE: +This is a version of Documentation/HOWTO translated into Japanese. +This document is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com> +and the JF Project team <www.linux.or.jp/JF>. +If you find any difference between this document and the original file +or a problem with the translation, +please contact the maintainer of this file or JF project. + +Please also note that the purpose of this file is to be easier to read +for non English (read: Japanese) speakers and is not intended as a +fork. So if you have any comments or updates for this file, please try +to update the original English file first. + +Last Updated: 2013/07/19 +================================== +これは、 +linux-3.10/Documentation/HOWTO +の和訳です。 + +翻訳団体： JF プロジェクト < http://linuxjf.sourceforge.jp/ > +翻訳日： 2013/7/19 +翻訳者： Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com> +校正者： 松倉さん <nbh--mats at nifty dot com> + 小林 雅典さん (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp> + 武井伸光さん、<takei at webmasters dot gr dot jp> + かねこさん (Seiji Kaneko) <skaneko at a2 dot mbn dot or dot jp> + 野口さん (Kenji Noguchi) <tokyo246 at gmail dot com> + 河内さん (Takayoshi Kochi) <t-kochi at bq dot jp dot nec dot com> + 岩本さん (iwamoto) <iwamoto.kn at ncos dot nec dot co dot jp> + 内田さん (Satoshi Uchida) <s-uchida at ap dot jp dot nec dot com> +================================== + +Linux カーネル開発のやり方 +------------------------------- + +これは上のトピック( Linux カーネル開発のやり方)の重要な事柄を網羅した +ドキュメントです。ここには Linux カーネル開発者になるための方法と +Linux カーネル開発コミュニティと共に活動するやり方を学ぶ方法が含まれて +います。カーネルプログラミングに関する技術的な項目に関することは何も含 +めないようにしていますが、カーネル開発者となるための正しい方向に向かう +手助けになります。 + +もし、このドキュメントのどこかが古くなっていた場合には、このドキュメン +トの最後にリストしたメンテナにパッチを送ってください。 + +はじめに +--------- + +あなたは Linux カーネルの開発者になる方法を学びたいのでしょうか？ そ +れともあなたは上司から「このデバイスの Linux ドライバを書くように」と +言われているのでしょうか？ +この文書の目的は、あなたが踏むべき手順と、コミュニティと一緒にうまく働 +くヒントを書き下すことで、あなたが知るべき全てのことを教えることです。 +また、このコミュニティがなぜ今うまくまわっているのかという理由の一部も +説明しようと試みています。 + + +カーネルは 少量のアーキテクチャ依存部分がアセンブリ言語で書かれている +以外は大部分は C 言語で書かれています。C言語をよく理解していることはカー +ネル開発者には必要です。アーキテクチャ向けの低レベル部分の開発をするの +でなければ、(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要あり +ません。以下の本は、C 言語の十分な知識や何年もの経験に取って代わるもの +ではありませんが、少なくともリファレンスとしては良い本です。 + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] + -『プログラミング言語Ｃ第2版』(B.W. カーニハン/D.M. リッチー著 石田晴久訳) [共立出版] + - "Practical C Programming" by Steve Oualline [O'Reilly] + - 『C実践プログラミング第3版』(Steve Oualline著 望月康司監訳 谷口功訳) [オライリージャパン] + - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] + - 『新・詳説 C 言語 H&S リファレンス』 + (サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク] + +カーネルは GNU C と GNU ツールチェインを使って書かれています。カーネル +は ISO C89 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って +います。カーネルは標準 C ライブラリとは関係がないといった、C 言語フリー +スタンディング環境です。そのため、C の標準で使えないものもあります。任 +意の long long の除算や浮動小数点は使えません。 +ときどき、カーネルがツールチェインや C 言語拡張に置いている前提がどう +なっているのかわかりにくいことがあり、また、残念なことに決定的なリファ +レンスは存在しません。情報を得るには、gcc の info ページ( info gcc )を +見てください。 + +あなたは既存の開発コミュニティと一緒に作業する方法を学ぼうとしているこ +とに留意してください。そのコミュニティは、コーディング、スタイル、 +開発手順について高度な標準を持つ、多様な人の集まりです。 +地理的に分散した大規模なチームに対してもっともうまくいくとわかったこと +をベースにしながら、これらの標準は長い時間をかけて築かれてきました。 +これらはきちんと文書化されていますから、事前にこれらの標準についてでき +るだけたくさん学んでください。また皆があなたやあなたの会社のやり方に合わ +せてくれると思わないでください。 + +法的問題 +------------ + +Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま +す。ライセンスの詳細については、ソースツリーのメインディレクトリに存在 +する、COPYING のファイルを見てください。もしライセンスについてさらに質 +問があれば、Linux Kernel メーリングリストに質問するのではなく、どうぞ +法律家に相談してください。メーリングリストの人達は法律家ではなく、法的 +問題については彼らの声明はあてにするべきではありません。 + +GPL に関する共通の質問や回答については、以下を参照してください。 + http://www.gnu.org/licenses/gpl-faq.html + +ドキュメント +------------ + +Linux カーネルソースツリーは幅広い範囲のドキュメントを含んでおり、それ +らはカーネルコミュニティと会話する方法を学ぶのに非常に貴重なものです。 +新しい機能がカーネルに追加される場合、その機能の使い方について説明した +新しいドキュメントファイルも追加することを勧めます。 +カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの +変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報 +をマニュアルページのメンテナ mtk.manpages@gmail.com に送り、CC を +linux-api@ver.kernel.org に送ることを勧めます。 + +以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で +す- + + README + このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注 + configure )し、生成(訳注 build )するために必要なことは何かが書かれ + ています。カーネルに関して初めての人はここからスタートすると良いで + しょう。 + + Documentation/Changes + このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最 + 小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい + ます。 + + Documentation/CodingStyle + これは Linux カーネルのコーディングスタイルと背景にある理由を記述 + しています。全ての新しいコードはこのドキュメントにあるガイドライン + に従っていることを期待されています。大部分のメンテナはこれらのルー + ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード + だけをレビューします。 + + Documentation/SubmittingPatches + Documentation/SubmittingDrivers + これらのファイルには、どうやってうまくパッチを作って投稿するかに + ついて非常に詳しく書かれており、以下を含みます(これだけに限らない + けれども) + - Email に含むこと + - Email の形式 + - だれに送るか + これらのルールに従えばうまくいくことを保証することではありません + が (すべてのパッチは内容とスタイルについて精査を受けるので)、 + ルールに従わなければ間違いなくうまくいかないでしょう。 + + この他にパッチを作る方法についてのよくできた記述は- + + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html + + Documentation/stable_api_nonsense.txt + このファイルはカーネルの中に不変のAPIを持たないことにした意識的な + 決断の背景にある理由について書かれています。以下のようなことを含 + んでいます- + - サブシステムとの間に層を作ること(コンパチビリティのため?) + - オペレーティングシステム間のドライバの移植性 + - カーネルソースツリーの素早い変更を遅らせる(もしくは素早い変更 + を妨げる) + このドキュメントは Linux 開発の思想を理解するのに非常に重要です。 + そして、他のOSでの開発者が Linux に移る時にとても重要です。 + + Documentation/SecurityBugs + もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ + のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を + 支援してください。 + + Documentation/ManagementStyle + このドキュメントは Linux カーネルのメンテナ達がどう行動するか、 + 彼らの手法の背景にある共有されている精神について記述しています。こ + れはカーネル開発の初心者なら（もしくは、単に興味があるだけの人でも） + 重要です。なぜならこのドキュメントは、カーネルメンテナ達の独特な + 行動についての多くの誤解や混乱を解消するからです。 + + Documentation/stable_kernel_rules.txt + このファイルはどのように stable カーネルのリリースが行われるかのルー + ルが記述されています。そしてこれらのリリースの中のどこかで変更を取 + り入れてもらいたい場合に何をすれば良いかが示されています。 + + Documentation/kernel-docs.txt + カーネル開発に付随する外部ドキュメントのリストです。もしあなたが + 探しているものがカーネル内のドキュメントでみつからなかった場合、 + このリストをあたってみてください。 + + Documentation/applying-patches.txt + パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに + 適用するのかについて正確に記述した良い入門書です。 + +カーネルはソースコードから自動的に生成可能な多数のドキュメントを自分自 +身でもっています。これにはカーネル内 API のすべての記述や、どう正しく +ロックをかけるかの規則が含まれます。このドキュメントは +Documentation/DocBook/ ディレクトリに作られ、以下のように + make pdfdocs + make psdocs + make htmldocs + make mandocs +コマンドを実行するとメインカーネルのソースディレクトリから +それぞれ、PDF, Postscript, HTML, man page の形式で生成されます。 + +カーネル開発者になるには +--------------------------- + +もしあなたが、Linux カーネル開発について何も知らないならば、 +KernelNewbies プロジェクトを見るべきです + http://kernelnewbies.org + +このサイトには役に立つメーリングリストがあり、基本的なカーネル開発に関 +するほとんどどんな種類の質問もできます (既に回答されているようなことを +聞く前にまずはアーカイブを調べてください)。 +またここには、リアルタイムで質問を聞くことができる IRC チャネルや、Linux +カーネルの開発に関して学ぶのに便利なたくさんの役に立つドキュメントがあ +ります。 + +web サイトには、コードの構成、サブシステム、現在存在するプロジェクト(ツ +リーにあるもの無いものの両方)の基本的な管理情報があります。 +ここには、また、カーネルのコンパイルのやり方やパッチの当て方などの間接 +的な基本情報も記述されています。 + +あなたがどこからスタートして良いかわからないが、Linux カーネル開発コミュ +ニティに参加して何かすることをさがしている場合には、Linux kernel +Janitor's プロジェクトにいけば良いでしょう - + http://kernelnewbies.org/KernelJanitors +ここはそのようなスタートをするのにうってつけの場所です。ここには、 +Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな +らない、単純な問題のリストが記述されています。このプロジェクトに関わる +開発者と一緒に作業することで、あなたのパッチを Linuxカーネルツリーに入 +れるための基礎を学ぶことができ、そしてもしあなたがまだアイディアを持っ +ていない場合には、次にやる仕事の方向性が見えてくるかもしれません。 + +もしあなたが、すでにひとまとまりコードを書いていて、カーネルツリーに入 +れたいと思っていたり、それに関する適切な支援を求めたい場合、カーネル +メンターズプロジェクトはそのような皆さんを助けるためにできました。 +ここにはメーリングリストがあり、以下から参照できます + http://selenic.com/mailman/listinfo/kernel-mentors + +実際に Linux カーネルのコードについて修正を加える前に、どうやってその +コードが動作するのかを理解することが必要です。そのためには、特別なツー +ルの助けを借りてでも、それを直接よく読むことが最良の方法です(ほとんど +のトリッキーな部分は十分にコメントしてありますから)。そういうツールで +特におすすめなのは、Linux クロスリファレンスプロジェクトです。これは、 +自己参照方式で、索引がついた web 形式で、ソースコードを参照することが +できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり +ます- + http://lxr.linux.no/+trees + +開発プロセス +----------------------- + +Linux カーネルの開発プロセスは現在幾つかの異なるメインカーネル「ブラン +チ」と多数のサブシステム毎のカーネルブランチから構成されます。 +これらのブランチとは- + - メインの 3.x カーネルツリー + - 3.x.y -stable カーネルツリー + - 3.x -git カーネルパッチ + - サブシステム毎のカーネルツリーとパッチ + - 統合テストのための 3.x -next カーネルツリー + +3.x カーネルツリー +----------------- + +3.x カーネルは Linus Torvalds によってメンテナンスされ、kernel.org +の pub/linux/kernel/v3.x/ ディレクトリに存在します。この開発プロセスは +以下のとおり- + + - 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、 + この期間中に、メンテナ達は Linus に大きな差分を送ることができます。 + このような差分は通常 -next カーネルに数週間含まれてきたパッチです。 + 大きな変更は git(カーネルのソース管理ツール、詳細は + http://git-scm.com/ 参照) を使って送るのが好ましいやり方ですが、パッ + チファイルの形式のまま送るのでも十分です。 + + - 2週間後、-rc1 カーネルがリリースされ、この後にはカーネル全体の安定 + 性に影響をあたえるような新機能は含まない類のパッチしか取り込むこと + はできません。新しいドライバ(もしくはファイルシステム)のパッチは + -rc1 の後で受け付けられることもあることを覚えておいてください。な + ぜなら、変更が独立していて、追加されたコードの外の領域に影響を与え + ない限り、退行のリスクは無いからです。-rc1 がリリースされた後、 + Linus へパッチを送付するのに git を使うこともできますが、パッチは + レビューのために、パブリックなメーリングリストへも同時に送る必要が + あります。 + + - 新しい -rc は Linus が、最新の git ツリーがテスト目的であれば十分 + に安定した状態にあると判断したときにリリースされます。目標は毎週新 + しい -rc カーネルをリリースすることです。 + + - このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま + す。このプロセスはだいたい 6週間継続します。 + + - 各リリースでの既知の後戻り問題(regression: このリリースの中で新規 + に作り込まれた問題を指す) はその都度 Linux-kernel メーリングリスト + に投稿されます。ゴールとしては、カーネルが 「準備ができた」と宣言 + する前にこのリストの長さをゼロに減らすことですが、現実には、数個の + 後戻り問題がリリース時にたびたび残ってしまいます。 + +Andrew Morton が Linux-kernel メーリングリストにカーネルリリースについ +て書いたことをここで言っておくことは価値があります- + 「カーネルがいつリリースされるかは誰も知りません。なぜなら、これは現 + 実に認識されたバグの状況によりリリースされるのであり、前もって決めら + れた計画によってリリースされるものではないからです。」 + +3.x.y -stable カーネルツリー +--------------------------- + +バージョン番号が3つの数字に分かれているカーネルは -stable カーネルです。 +これには、3.x カーネルで見つかったセキュリティ問題や重大な後戻りに対 +する比較的小さい重要な修正が含まれます。 + +これは、開発/実験的バージョンのテストに協力することに興味が無く、 +最新の安定したカーネルを使いたいユーザに推奨するブランチです。 + +もし、3.x.y カーネルが存在しない場合には、番号が一番大きい 3.x が +最新の安定版カーネルです。 + +3.x.y は "stable" チーム <stable@vger.kernel.org> でメンテされており、必 +要に応じてリリースされます。通常のリリース期間は 2週間毎ですが、差し迫っ +た問題がなければもう少し長くなることもあります。セキュリティ関連の問題 +の場合はこれに対してだいたいの場合、すぐにリリースがされます。 + +カーネルツリーに入っている、Documentation/stable_kernel_rules.txt ファ +イルにはどのような種類の変更が -stable ツリーに受け入れ可能か、またリ +リースプロセスがどう動くかが記述されています。 + +3.x -git パッチ +------------------ + +git リポジトリで管理されているLinus のカーネルツリーの毎日のスナップ +ショットがあります。(だから -git という名前がついています)。これらのパッ +チはおおむね毎日リリースされており、Linus のツリーの現状を表します。こ +れは -rc カーネルと比べて、パッチが大丈夫かどうかも確認しないで自動的 +に生成されるので、より実験的です。 + +サブシステム毎のカーネルツリーとパッチ +------------------------------------------- + +それぞれのカーネルサブシステムのメンテナ達は --- そして多くのカーネル +サブシステムの開発者達も --- 各自の最新の開発状況をソースリポジトリに +公開しています。そのため、自分とは異なる領域のカーネルで何が起きている +かを他の人が見られるようになっています。開発が早く進んでいる領域では、 +開発者は自身の投稿がどのサブシステムカーネルツリーを元にしているか質問 +されるので、その投稿とすでに進行中の他の作業との衝突が避けられます。 + +大部分のこれらのリポジトリは git ツリーです。しかしその他の SCM や +quilt シリーズとして公開されているパッチキューも使われています。これら +のサブシステムリポジトリのアドレスは MAINTAINERS ファイルにリストされ +ています。これらの多くは http://git.kernel.org/ で参照することができま +す。 + +提案されたパッチがこのようなサブシステムツリーにコミットされる前に、メー +リングリストで事前にレビューにかけられます（以下の対応するセクションを +参照）。いくつかのカーネルサブシステムでは、このレビューは patchwork +というツールによって追跡されます。Patchwork は web インターフェイスに +よってパッチ投稿の表示、パッチへのコメント付けや改訂などができ、そして +メンテナはパッチに対して、レビュー中、受付済み、拒否というようなマーク +をつけることができます。大部分のこれらの patchwork のサイトは +http://patchwork.kernel.org/ でリストされています。 + +統合テストのための 3.x -next カーネルツリー +--------------------------------------------- + +サブシステムツリーの更新内容がメインラインの 3.x ツリーにマージされ +る前に、それらは統合テストされる必要があります。この目的のため、実質的 +に全サブシステムツリーからほぼ毎日プルされてできる特別なテスト用のリ +ポジトリが存在します- + http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git + http://linux.f-seidel.de/linux-next/pmwiki/ + +このやり方によって、-next カーネルは次のマージ機会でどんなものがメイン +ラインカーネルにマージされるか、おおまかなの展望を提供します。-next +カーネルの実行テストを行う冒険好きなテスターは大いに歓迎されます + +バグレポート +------------- + +bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを追跡する +場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。 +どう kernel bugzilla を使うかの詳細は、以下を参照してください- + http://bugzilla.kernel.org/page.cgi?id=faq.html +メインカーネルソースディレクトリにあるファイル REPORTING-BUGS はカーネ +ルバグらしいものについてどうレポートするかの良いテンプレートであり、問 +題の追跡を助けるためにカーネル開発者にとってどんな情報が必要なのかの詳 +細が書かれています。 + +バグレポートの管理 +------------------- + +あなたのハッキングのスキルを訓練する最高の方法のひとつに、他人がレポー +トしたバグを修正することがあります。あなたがカーネルをより安定化させる +こに寄与するということだけでなく、あなたは 現実の問題を修正することを +学び、自分のスキルも強化でき、また他の開発者があなたの存在に気がつき +ます。バグを修正することは、多くの開発者の中から自分が功績をあげる最善 +の道です、なぜなら多くの人は他人のバグの修正に時間を浪費することを好ま +ないからです。 + +すでにレポートされたバグのために仕事をするためには、 +http://bugzilla.kernel.org に行ってください。もし今後のバグレポートに +ついてアドバイスを受けたいのであれば、bugme-new メーリングリスト(新し +いバグレポートだけがここにメールされる) または bugme-janitor メーリン +グリスト(bugzilla の変更毎にここにメールされる)を購読できます。 + + http://lists.linux-foundation.org/mailman/listinfo/bugme-new + http://lists.linux-foundation.org/mailman/listinfo/bugme-janitors + +メーリングリスト +------------- + +上のいくつかのドキュメントで述べていますが、コアカーネル開発者の大部分 +は Linux kernel メーリングリストに参加しています。このリストの登録/脱 +退の方法については以下を参照してください- + http://vger.kernel.org/vger-lists.html#linux-kernel + +このメーリングリストのアーカイブは web 上の多数の場所に存在します。こ +れらのアーカイブを探すにはサーチエンジンを使いましょう。例えば- + http://dir.gmane.org/gmane.linux.kernel + +リストに投稿する前にすでにその話題がアーカイブに存在するかどうかを検索 +することを是非やってください。多数の事がすでに詳細に渡って議論されて +おり、アーカイブにのみ記録されています。 + +大部分のカーネルサブシステムも自分の個別の開発を実施するメーリングリス +トを持っています。個々のグループがどんなリストを持っているかは、 +MAINTAINERS ファイルにリストがありますので参照してください。 + +多くのリストは kernel.org でホストされています。これらの情報は以下にあ +ります- + http://vger.kernel.org/vger-lists.html + +メーリングリストを使う場合、良い行動習慣に従うようにしましょう。 +少し安っぽいが、以下の URL は上のリスト(や他のリスト)で会話する場合の +シンプルなガイドラインを示しています- + http://www.albion.com/netiquette/ + +もし複数の人があなたのメールに返事をした場合、CC: で受ける人のリストは +だいぶ多くなるでしょう。良い理由がない場合、CC: リストから誰かを削除を +しないように、また、メーリングリストのアドレスだけにリプライすることの +ないようにしましょう。1つは送信者から、もう1つはリストからのように、メー +ルを2回受けることになってもそれに慣れ、しゃれたメールヘッダーを追加し +てこの状態を変えようとしないように。人々はそのようなことは好みません。 + +今までのメールでのやりとりとその間のあなたの発言はそのまま残し、 +"John Kernlehacker wrote ...:" の行をあなたのリプライの先頭行にして、 +メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで +す。 + +もしパッチをメールに付ける場合は、Documentaion/SubmittingPatches に提 +示されているように、それは プレーンな可読テキストにすることを忘れない +ようにしましょう。カーネル開発者は 添付や圧縮したパッチを扱いたがりま +せん- +彼らはあなたのパッチの行毎にコメントを入れたいので、そのためにはそうす +るしかありません。あなたのメールプログラムが空白やタブを圧縮しないよう +に確認した方が良いです。最初の良いテストとしては、自分にメールを送って +みて、そのパッチを自分で当ててみることです。もしそれがうまく行かないな +ら、あなたのメールプログラムを直してもらうか、正しく動くように変えるべ +きです。 + +とりわけ、他の登録者に対する尊敬を表すようにすることを覚えておいてくだ +さい。 + +コミュニティと共に働くこと +-------------------------- + +カーネルコミュニティのゴールは可能なかぎり最高のカーネルを提供すること +です。あなたがパッチを受け入れてもらうために投稿した場合、それは、技術 +的メリットだけがレビューされます。その際、あなたは何を予想すべきでしょ +うか? + - 批判 + - コメント + - 変更の要求 + - パッチの正当性の証明要求 + - 沈黙 + +思い出してください、ここはあなたのパッチをカーネルに入れる話です。あ +なたは、あなたのパッチに対する批判とコメントを受け入れるべきで、それら +を技術的レベルで評価して、パッチを再作成するか、なぜそれらの変更をすべ +きでないかを明確で簡潔な理由の説明を提供してください。 +もし、あなたのパッチに何も反応がない場合、たまにはメールの山に埋もれて +見逃され、あなたの投稿が忘れられてしまうこともあるので、数日待って再度 +投稿してください。 + +あなたがやるべきでないものは? + - 質問なしにあなたのパッチが受け入れられると想像すること + - 守りに入ること + - コメントを無視すること + - 要求された変更を何もしないでパッチを出し直すこと + +可能な限り最高の技術的解決を求めているコミュニティでは、パッチがどのく +らい有益なのかについては常に異なる意見があります。あなたは協調的である +べきですし、また、あなたのアイディアをカーネルに対してうまく合わせるよ +うにすることが望まれています。もしくは、最低限あなたのアイディアがそれ +だけの価値があるとすすんで証明するようにしなければなりません。 +正しい解決に向かって進もうという意志がある限り、間違うことがあっても許 +容されることを忘れないでください。 + +あなたの最初のパッチに単に 1ダースもの修正を求めるリストの返答になるこ +とも普通のことです。これはあなたのパッチが受け入れられないということで +は *ありません*、そしてあなた自身に反対することを意味するのでも *ありま +せん*。単に自分のパッチに対して指摘された問題を全て修正して再送すれば +良いのです。 + + +カーネルコミュニティと企業組織のちがい +----------------------------------------------------------------- + +カーネルコミュニティは大部分の伝統的な会社の開発環境とは異ったやり方で +動いています。以下は問題を避けるためにできると良いことのリストです- + + あなたの提案する変更について言うときのうまい言い方： + + - "これは複数の問題を解決します" + - "これは2000行のコードを削除します" + - "以下のパッチは、私が言おうとしていることを説明するものです" + - "私はこれを5つの異なるアーキテクチャでテストしたのですが..." + - "以下は一連の小さなパッチ群ですが..." + - "これは典型的なマシンでの性能を向上させます.." + + やめた方が良い悪い言い方： + + - このやり方で AIX/ptx/Solaris ではできたので、できるはずだ + - 私はこれを20年もの間やってきた、だから + - これは、私の会社が金儲けをするために必要だ + - これは我々のエンタープライズ向け商品ラインのためである + - これは 私が自分のアイディアを記述した、1000ページの設計資料である + - 私はこれについて、6ケ月作業している。 + - 以下は ... に関する5000行のパッチです + - 私は現在のぐちゃぐちゃを全部書き直した、それが以下です... + - 私は〆切がある、そのためこのパッチは今すぐ適用される必要がある + +カーネルコミュニティが大部分の伝統的なソフトウェアエンジニアリングの労 +働環境と異なるもう一つの点は、やりとりに顔を合わせないということです。 +email と irc を第一のコミュニケーションの形とする一つの利点は、性別や +民族の差別がないことです。Linux カーネルの職場環境は女性や少数民族を受 +容します。なぜなら、email アドレスによってのみあなたが認識されるからで +す。 +国際的な側面からも活動領域を均等にするようにします。なぜならば、あなた +は人の名前で性別を想像できないからです。ある男性が アンドレアという名 +前で、女性の名前は パット かもしれません (訳注 Andrea は米国では女性、 +それ以外(欧州など)では男性名として使われることが多い。同様に、Pat は +Patricia (主に女性名)や Patrick (主に男性名)の略称)。 +Linux カーネルの活動をして、意見を表明したことがある大部分の女性は、前 +向きな経験をもっています。 + +言葉の壁は英語が得意でない一部の人には問題になります。 +メーリングリストの中できちんとアイディアを交換するには、相当うまく英語 +を操れる必要があることもあります。そのため、あなたは自分のメール +を送る前に英語で意味が通じているかをチェックすることをお薦めします。 + +変更を分割する +--------------------- + +Linux カーネルコミュニティは、一度に大量のコードの塊を喜んで受容するこ +とはありません。変更は正確に説明される必要があり、議論され、小さい、個 +別の部分に分割する必要があります。これはこれまで多くの会社がやり慣れて +きたことと全く正反対のことです。あなたのプロポーザルは、開発プロセスのと +ても早い段階から紹介されるべきです。そうすれば あなたは自分のやってい +ることにフィードバックを得られます。これは、コミュニティからみれば、あ +なたが彼らと一緒にやっているように感じられ、単にあなたの提案する機能の +ゴミ捨て場として使っているのではない、と感じられるでしょう。 +しかし、一度に 50 もの email をメーリングリストに送りつけるようなことは +やってはいけません、あなたのパッチ群はいつもどんな時でもそれよりは小さ +くなければなりません。 + +パッチを分割する理由は以下です- + +1) 小さいパッチはあなたのパッチが適用される見込みを大きくします、カー + ネルの人達はパッチが正しいかどうかを確認する時間や労力をかけないか + らです。5行のパッチはメンテナがたった1秒見るだけで適用できます。 + しかし、500行のパッチは、正しいことをレビューするのに数時間かかるか + もしれません(時間はパッチのサイズなどにより指数関数に比例してかかり + ます) + + 小さいパッチは何かあったときにデバッグもとても簡単になります。パッ + チを1個1個取り除くのは、とても大きなパッチを当てた後に(かつ、何かお + かしくなった後で)解剖するのに比べればとても簡単です。 + +2) 小さいパッチを送るだけでなく、送るまえに、書き直して、シンプルにす + る(もしくは、単に順番を変えるだけでも)ことも、とても重要です。 + +以下はカーネル開発者の Al Viro のたとえ話です： + + "生徒の数学の宿題を採点する先生のことを考えてみてください、先 + 生は生徒が解に到達するまでの試行錯誤を見たいとは思わないでしょ + う。先生は簡潔な最高の解を見たいのです。良い生徒はこれを知って + おり、そして最終解の前の中間作業を提出することは決してないので + す" + + カーネル開発でもこれは同じです。メンテナ達とレビューア達は、 + 問題を解決する解の背後になる思考プロセスを見たいとは思いません。 + 彼らは単純であざやかな解決方法を見たいのです。 + +あざやかな解を説明するのと、コミュニティと共に仕事をし、未解決の仕事を +議論することのバランスをキープするのは難しいかもしれません。 +ですから、開発プロセスの早期段階で改善のためのフィードバックをもらうよ +うにするのも良いですが、変更点を小さい部分に分割して全体ではまだ完成し +ていない仕事を(部分的に)取り込んでもらえるようにすることも良いことです。 + +また、でき上がっていないものや、"将来直す" ようなパッチを、本流に含め +てもらうように送っても、それは受け付けられないことを理解してください。 + +あなたの変更を正当化する +------------------- + +あなたのパッチを分割するのと同時に、なぜその変更を追加しなければならな +いかを Linux コミュニティに知らせることはとても重要です。新機能は必要 +性と有用性で正当化されなければなりません。 + +あなたの変更の説明 +-------------------- + +あなたのパッチを送付する場合には、メールの中のテキストで何を言うかにつ +いて、特別に注意を払ってください。この情報はパッチの ChangeLog に使わ +れ、いつも皆がみられるように保管されます。これは次のような項目を含め、 +パッチを完全に記述するべきです- + + - なぜ変更が必要か + - パッチ全体の設計アプローチ + - 実装の詳細 + - テスト結果 + +これについて全てがどのようにあるべきかについての詳細は、以下のドキュメ +ントの ChangeLog セクションを見てください- + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt + +これらのどれもが、時にはとても困難です。これらの慣例を完璧に実施するに +は数年かかるかもしれません。これは継続的な改善のプロセスであり、そのた +めには多数の忍耐と決意を必要とするものです。でも、諦めないで、これは可 +能なことです。多数の人がすでにできていますし、彼らも皆最初はあなたと同 +じところからスタートしたのですから。 + +Paolo Ciarrocchi に感謝、彼は彼の書いた "Development Process" +(http://lwn.net/Articles/94386/) セクションをこのテキストの原型にする +ことを許可してくれました。Rundy Dunlap と Gerrit Huizenga はメーリング +リストでやるべきこととやってはいけないことのリストを提供してくれました。 +以下の人々のレビュー、コメント、貢献に感謝。 +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, と Alex Shepard +彼らの支援なしでは、このドキュメントはできなかったでしょう。 + +Maintainer: Greg Kroah-Hartman <greg@kroah.com> diff --git a/kernel/Documentation/ja_JP/SubmitChecklist b/kernel/Documentation/ja_JP/SubmitChecklist new file mode 100644 index 000000000..cb5507b1a --- /dev/null +++ b/kernel/Documentation/ja_JP/SubmitChecklist @@ -0,0 +1,111 @@ +NOTE: +This is a version of Documentation/SubmitChecklist into Japanese. +This document is maintained by Takenori Nagano <t-nagano@ah.jp.nec.com> +and the JF Project team <http://www.linux.or.jp/JF/>. +If you find any difference between this document and the original file +or a problem with the translation, +please contact the maintainer of this file or JF project. + +Please also note that the purpose of this file is to be easier to read +for non English (read: Japanese) speakers and is not intended as a +fork. So if you have any comments or updates of this file, please try +to update the original English file first. + +Last Updated: 2008/07/14 +================================== +これは、 +linux-2.6.26/Documentation/SubmitChecklist の和訳です。 + +翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > +翻訳日： 2008/07/14 +翻訳者： Takenori Nagano <t-nagano at ah dot jp dot nec dot com> +校正者： Masanori Kobayashi さん <zap03216 at nifty dot ne dot jp> +================================== + + +Linux カーネルパッチ投稿者向けチェックリスト +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +本書では、パッチをより素早く取り込んでもらいたい開発者が実践すべき基本的な事柄 +をいくつか紹介します。ここにある全ての事柄は、Documentation/SubmittingPatches +などのLinuxカーネルパッチ投稿に際しての心得を補足するものです。 + + 1: 妥当なCONFIGオプションや変更されたCONFIGオプション、つまり =y, =m, =n + 全てで正しくビルドできることを確認してください。その際、gcc及びリンカが + warningやerrorを出していないことも確認してください。 + + 2: allnoconfig, allmodconfig オプションを用いて正しくビルドできることを + 確認してください。 + + 3: 手許のクロスコンパイルツールやOSDLのPLMのようなものを用いて、複数の + アーキテクチャにおいても正しくビルドできることを確認してください。 + + 4: 64bit長の'unsigned long'を使用しているppc64は、クロスコンパイルでの + チェックに適当なアーキテクチャです。 + + 5: カーネルコーディングスタイルに準拠しているかどうか確認してください(!) + + 6: CONFIGオプションの追加・変更をした場合には、CONFIGメニューが壊れていない + ことを確認してください。 + + 7: 新しくKconfigのオプションを追加する際には、必ずそのhelpも記述してください。 + + 8: 適切なKconfigの依存関係を考えながら慎重にチェックしてください。 + ただし、この作業はマシンを使ったテストできちんと行うのがとても困難です。 + うまくやるには、自分の頭で考えることです。 + + 9: sparseを利用してちゃんとしたコードチェックをしてください。 + +10: 'make checkstack' と 'make namespacecheck' を利用し、問題が発見されたら + 修正してください。'make checkstack' は明示的に問題を示しませんが、どれか + １つの関数が512バイトより大きいスタックを使っていれば、修正すべき候補と + なります。 + +11: グローバルなkernel API を説明する kernel-doc をソースの中に含めてください。 + ( staticな関数においては必須ではありませんが、含めてもらっても結構です ) + そして、'make htmldocs' もしくは 'make mandocs' を利用して追記した + ドキュメントのチェックを行い、問題が見つかった場合には修正を行ってください。 + +12: CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, CONFIG_DEBUG_SLAB, + CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, CONFIG_DEBUG_SPINLOCK, + CONFIG_DEBUG_ATOMIC_SLEEP これら全てを同時に有効にして動作確認を + 行ってください。 + +13: CONFIG_SMP, CONFIG_PREEMPT を有効にした場合と無効にした場合の両方で + ビルドした上、動作確認を行ってください。 + +14: もしパッチがディスクのI/O性能などに影響を与えるようであれば、 + 'CONFIG_LBDAF'オプションを有効にした場合と無効にした場合の両方で + テストを実施してみてください。 + +15: lockdepの機能を全て有効にした上で、全てのコードパスを評価してください。 + +16: /proc に新しいエントリを追加した場合には、Documentation/ 配下に + 必ずドキュメントを追加してください。 + +17: 新しいブートパラメータを追加した場合には、 + 必ずDocumentation/kernel-parameters.txt に説明を追加してください。 + +18: 新しくmoduleにパラメータを追加した場合には、MODULE_PARM_DESC()を + 利用して必ずその説明を記述してください。 + +19: 新しいuserspaceインタフェースを作成した場合には、Documentation/ABI/ に + Documentation/ABI/README を参考にして必ずドキュメントを追加してください。 + +20: 'make headers_check'を実行して全く問題がないことを確認してください。 + +21: 少なくともslabアロケーションとpageアロケーションに失敗した場合の + 挙動について、fault-injectionを利用して確認してください。 + Documentation/fault-injection/ を参照してください。 + + 追加したコードがかなりの量であったならば、サブシステム特有の + fault-injectionを追加したほうが良いかもしれません。 + +22: 新たに追加したコードは、`gcc -W'でコンパイルしてください。 + このオプションは大量の不要なメッセージを出力しますが、 + "warning: comparison between signed and unsigned" のようなメッセージは、 + バグを見つけるのに役に立ちます。 + +23: 投稿したパッチが -mm パッチセットにマージされた後、全ての既存のパッチや + VM, VFS およびその他のサブシステムに関する様々な変更と、現時点でも共存 + できることを確認するテストを行ってください。 diff --git a/kernel/Documentation/ja_JP/SubmittingPatches b/kernel/Documentation/ja_JP/SubmittingPatches new file mode 100644 index 000000000..5d6ae639b --- /dev/null +++ b/kernel/Documentation/ja_JP/SubmittingPatches @@ -0,0 +1,719 @@ +NOTE: +This is a version of Documentation/SubmittingPatches into Japanese. +This document is maintained by Keiichi KII <k-keiichi@bx.jp.nec.com> +and the JF Project team <http://www.linux.or.jp/JF/>. +If you find any difference between this document and the original file +or a problem with the translation, +please contact the maintainer of this file or JF project. + +Please also note that the purpose of this file is to be easier to read +for non English (read: Japanese) speakers and is not intended as a +fork. So if you have any comments or updates of this file, please try +to update the original English file first. + +Last Updated: 2011/06/09 + +================================== +これは、 +linux-2.6.39/Documentation/SubmittingPatches の和訳 +です。 +翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > +翻訳日： 2011/06/09 +翻訳者： Keiichi Kii <k-keiichi at bx dot jp dot nec dot com> +校正者： Masanari Kobayashi さん <zap03216 at nifty dot ne dot jp> + Matsukura さん <nbh--mats at nifty dot com> + Takeshi Hamasaki さん <hmatrjp at users dot sourceforge dot jp> +================================== + + Linux カーネルに変更を加えるための Howto + 又は + かの Linus Torvalds の取り扱い説明書 + +Linux カーネルに変更を加えたいと思っている個人又は会社にとって、パッ +チの投稿に関連した仕組みに慣れていなければ、その過程は時々みなさんを +おじけづかせることもあります。この文章はあなたの変更を大いに受け入れ +てもらえやすくする提案を集めたものです。 + +コードを投稿する前に、Documentation/SubmitChecklist の項目リストに目 +を通してチェックしてください。もしあなたがドライバーを投稿しようとし +ているなら、Documentation/SubmittingDrivers にも目を通してください。 + +-------------------------------------------- +セクション1 パッチの作り方と送り方 +-------------------------------------------- + +1) 「 diff -up 」 +------------ + +パッチの作成には「 diff -up 」又は「 diff -uprN 」を使ってください。 + +Linux カーネルに対する全ての変更は diff(1) コマンドによるパッチの形式で +生成してください。パッチを作成するときには、diff(1) コマンドに「 -u 」引 +数を指定して、unified 形式のパッチを作成することを確認してください。また、 +変更がどの C 関数で行われたのかを表示する「 -p 」引数を使ってください。 +この引数は生成した差分をずっと読みやすくしてくれます。パッチは Linux +カーネルソースの中のサブディレクトリではなく Linux カーネルソースのルート +ディレクトリを基準にしないといけません。 + +1個のファイルについてのパッチを作成するためには、ほとんどの場合、 +以下の作業を行えば十分です。 + + SRCTREE= linux-2.6 + MYFILE= drivers/net/mydriver.c + + cd $SRCTREE + cp $MYFILE $MYFILE.orig + vi $MYFILE # make your change + cd .. + diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch + +複数のファイルについてのパッチを作成するためには、素の( vanilla )、す +なわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネル +ソースとの差分を生成しないといけません。例えば、 + + MYSRC= /devel/linux-2.6 + + tar xvfz linux-2.6.12.tar.gz + mv linux-2.6.12 linux-2.6.12-vanilla + diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ + linux-2.6.12-vanilla $MYSRC > /tmp/patch + +dontdiff ファイルには Linux カーネルのビルドプロセスの過程で生成された +ファイルの一覧がのっています。そして、それらはパッチを生成する diff(1) +コマンドで無視されるべきです。dontdiff ファイルは 2.6.12 以後のバージョ +ンの Linux カーネルソースツリーに含まれています。それより前のバージョン +の Linux カーネルソースツリーに対する dontdiff ファイルは、 +<http://www.xenotime.net/linux/doc/dontdiff>から取得することができます。 + +投稿するパッチの中に関係のない余分なファイルが含まれていないことを確 +認してください。diff(1) コマンドで生成したパッチがあなたの意図したとお +りのものであることを確認してください。 + +もしあなたのパッチが多くの差分を生み出すのであれば、あなたはパッチ +を意味のあるひとまとまりごとに分けたいと思うかもしれません。 +これは他のカーネル開発者にとってレビューしやすくなるので、あなたの +パッチを受け入れてもらうためにはとても重要なことです。これを補助でき +る多くのスクリプトがあります。 + +Quilt: +http://savannah.nongnu.org/projects/quilt + +2) パッチに対する説明 + +パッチの中の変更点に対する技術的な詳細について説明してください。 + +説明はできる限り具体的に。もっとも悪い説明は「ドライバー X を更新」、 +「ドライバー X に対するバグフィックス」あるいは「このパッチはサブシス +テム X に対する更新を含んでいます。どうか取り入れてください。」などです。 + +パッチの説明を Linux カーネルのソースコードマネジメントシステム「 git 」の +コミットログとして簡単に引用できる形で書けば、メンテナから感謝されるでしょう。 +以下の #15 を見てください。 + +説明が長くなりだしたのであれば、おそらくそれはパッチを分ける必要がある +という兆候です。次の #3 を見てください。 + +パッチ(シリーズ)を(再)投稿する時、十分なパッチの説明とそのパッチが必要な理由を +パッチに含めてください。ただ「これはパッチ(シリーズ)のバージョン N」とだけ +書かないでください。そして、パッチをマージする人にパッチの説明を探させそれを +パッチに追記させるため、過去のバージョンのパッチやそのパッチの URL を参照する +手間をかけさせないでください。 +つまり、パッチシリーズとその説明は一緒にあるべきです。これはパッチをマージする +人、レビューする人、どちらのためにもなります。レビューする人の中には、おそらく +過去のバージョンのパッチを受け取ってもいない人がいます。 + +登録済みのバグエントリを修正するパッチであれば、そのバグエントリを示すバグ ID +や URL を明記してください。 + +3) パッチの分割 + +意味のあるひとまとまりごとに変更を個々のパッチファイルに分けてください。 + +例えば、もし1つのドライバーに対するバグフィックスとパフォーマンス強 +化の両方の変更を含んでいるのであれば、その変更を2つ以上のパッチに分 +けてください。もし変更箇所に API の更新と、その新しい API を使う新たな +ドライバーが含まれているなら、2つのパッチに分けてください。 + +一方で、もしあなたが多数のファイルに対して意味的に同じ1つの変更を加え +るのであれば、その変更を1つのパッチにまとめてください。言いかえると、 +意味的に同じ1つの変更は1つのパッチの中に含まれます。 + +あるパッチが変更を完結させるために他のパッチに依存していたとしても、 +それは問題ありません。パッチの説明の中で「このパッチはパッチ X に依存 +している」と簡単に注意書きをつけてください。 + +もしパッチをより小さなパッチの集合に凝縮することができないなら、まずは +15かそこらのパッチを送り、そのレビューと統合を待って下さい。 + +4) パッチのスタイルチェック + +あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し +ていないかをチェックして下さい。その詳細を Documentation/CodingStyle で +見つけることができます。コーディングスタイルの違反はレビューする人の +時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく +拒否されるでしょう。 + +あなたはパッチを投稿する前に最低限パッチスタイルチェッカー +( scripts/checkpatch.pl )を利用してパッチをチェックすべきです。 +もしパッチに違反がのこっているならば、それらの全てについてあなたは正当な +理由を示せるようにしておく必要があります。 + +5) 電子メールの宛先の選び方 + +MAINTAINERS ファイルとソースコードに目を通してください。そして、その変 +更がメンテナのいる特定のサブシステムに加えられるものであることが分か +れば、その人に電子メールを送ってください。 + +もし、メンテナが載っていなかったり、メンテナからの応答がないなら、 +LKML ( linux-kernel@vger.kernel.org )へパッチを送ってください。ほとんど +のカーネル開発者はこのメーリングリストに目を通しており、変更に対して +コメントを得ることができます。 + +15個より多くのパッチを同時に vger.kernel.org のメーリングリストへ送らな +いでください!!! + +Linus Torvalds は Linux カーネルに入る全ての変更に対する最終的な意思決定者 +です。電子メールアドレスは torvalds@linux-foundation.org になります。彼は +多くの電子メールを受け取っているため、できる限り彼に電子メールを送るのは +避けるべきです。 + +バグフィックスであったり、自明な変更であったり、話し合いをほとんど +必要としないパッチは Linus へ電子メールを送るか CC しなければなりません。 +話し合いを必要としたり、明確なアドバンテージがないパッチは、通常まず +は LKML へ送られるべきです。パッチが議論された後にだけ、そのパッチを +Linus へ送るべきです。 + +6) CC (カーボンコピー)先の選び方 + +特に理由がないなら、LKML にも CC してください。 + +Linus 以外のカーネル開発者は変更に気づく必要があり、その結果、彼らはそ +の変更に対してコメントをくれたり、コードに対してレビューや提案をくれ +るかもしれません。LKML とは Linux カーネル開発者にとって一番中心的なメー +リングリストです。USB やフレームバッファデバイスや VFS や SCSI サブシステ +ムなどの特定のサブシステムに関するメーリングリストもあります。あなた +の変更に、はっきりと関連のあるメーリングリストについて知りたければ +MAINTAINERS ファイルを参照してください。 + +VGER.KERNEL.ORG でホスティングされているメーリングリストの一覧が下記の +サイトに載っています。 +<http://vger.kernel.org/vger-lists.html> + +もし、変更がユーザランドのカーネルインタフェースに影響を与え +るのであれば、MAN-PAGES のメンテナ( MAINTAINERS ファイルに一覧 +があります)に man ページのパッチを送ってください。少なくとも +情報がマニュアルページの中に入ってくるように、変更が起きたという +通知を送ってください。 + +たとえ、メンテナが #5 で反応がなかったとしても、メンテナのコードに変更を +加えたときには、いつもメンテナに CC するのを忘れないようにしてください。 + +小さなパッチであれば、Trivial Patch Monkey(ちょっとしたパッチを集めている) +<trivial@kernel.org>に CC してもいいです。その現管理者については MAINTAINERS +ファイルを見てください。ちょっとしたパッチとは以下のルールのどれか1つを満たして +いなければなりません。 + ・ドキュメントのスペルミスの修正 + ・grep(1) コマンドによる検索を困難にしているスペルの修正 + ・コンパイル時の警告の修正(無駄な警告が散乱することは好ましくないた + めです) + ・コンパイル問題の修正(それらの修正が本当に正しい場合に限る) + ・実行時の問題の修正(それらの修正が本当に問題を修正している場合に限る) + ・廃止予定の関数やマクロを使用しているコードの除去(例 check_region ) + ・問い合わせ先やドキュメントの修正 + ・移植性のないコードから移植性のあるコードへの置き換え(小さい範囲で + あればアーキテクチャ特有のことでも他の人がコピーできます) + ・作者やメンテナによる修正(すなわち patch monkey の再転送モード) + +7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ + +Linus や他のカーネル開発者はあなたが投稿した変更を読んで、コメントでき +る必要があります。カーネル開発者にとって、あなたが書いたコードの特定の +部分にコメントをするために、標準的な電子メールクライアントで変更が引用 +できることは重要です。 + +上記の理由で、すべてのパッチは文中に含める形式の電子メールで投稿さ +れるべきです。警告：あなたがパッチをコピー&ペーストする際には、パッ +チを改悪するエディターの折り返し機能に注意してください。 + +パッチを圧縮の有無に関わらず MIME 形式で添付しないでください。多くのポ +ピュラーな電子メールクライアントは MIME 形式の添付ファイルをプレーンテ +キストとして送信するとは限らないでしょう。そうなると、電子メールクラ +イアントがコードに対するコメントを付けることをできなくします。また、 +MIME 形式の添付ファイルは Linus に手間を取らせることになり、その変更を +受け入れてもらう可能性が低くなってしまいます。 + +例外：お使いの電子メールクライアントがパッチをめちゃくちゃにするので +あれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。 + +余計な変更を加えずにあなたのパッチを送信するための電子メールクライアントの設定 +のヒントについては Documentation/email-clients.txt を参照してください。 + +8) 電子メールのサイズ + +パッチを Linus へ送るときは常に #7 の手順に従ってください。 + +大きなパッチはメーリングリストやメンテナにとって不親切です。パッチが +未圧縮で 300KB を超えるようであるなら、インターネット上のアクセス可能な +サーバに保存し、保存場所を示す URL を伝えるほうが適切です。 + +9) カーネルバージョンの明記 + +パッチが対象とするカーネルのバージョンをパッチの概要か電子メールの +サブジェクトに付けることが重要です。 + +パッチが最新バージョンのカーネルに正しく適用できなければ、Linus は +そのパッチを採用しないでしょう。 + +10) がっかりせず再投稿 + +パッチを投稿した後は、辛抱強く待っていてください。Linus があなたのパッ +チを気に入って採用すれば、Linus がリリースする次のバージョンのカーネル +の中で姿を見せるでしょう。 + +しかし、パッチが次のバージョンのカーネルに入っていないなら、いくつもの +理由があるのでしょう。その原因を絞り込み、間違っているものを正し、更新 +したパッチを投稿するのはあなたの仕事です。 + +Linus があなたのパッチに対して何のコメントもなく不採用にすることは極め +て普通のことです。それは自然な姿です。もし、Linus があなたのパッチを受 +け取っていないのであれば、以下の理由が考えられます。 +* パッチが最新バージョンの Linux カーネルにきちんと適用できなかった +* パッチが LKML で十分に議論されていなかった +* スタイルの問題(セクション2を参照) +* 電子メールフォーマットの問題(このセクションを参照) +* パッチに対する技術的な問題 +* Linus はたくさんの電子メールを受け取っているので、どさくさに紛れて見 + 失った +* 不愉快にさせている + +判断できない場合は、LKML にコメントを頼んでください。 + +11) サブジェクトに「 PATCH 」 + +Linus や LKML への大量の電子メールのために、サブジェクトのプレフィックスに +「 [PATCH] 」を付けることが慣習となっています。これによって Linus や他の +カーネル開発者がパッチであるのか、又は、他の議論に関する電子メールであるの +かをより簡単に識別できます。 + +12) パッチへの署名 + +誰が何をしたのかを追いかけやすくするために (特に、パッチが何人かの +メンテナを経て最終的に Linux カーネルに取り込まれる場合のために)、電子 +メールでやり取りされるパッチに対して「 sign-off 」という手続きを導入し +ました。 + +「 sign-off 」とは、パッチがあなたの書いたものであるか、あるいは、 +あなたがそのパッチをオープンソースとして提供する権利を保持している、 +という証明をパッチの説明の末尾に一行記載するというものです。 +ルールはとても単純です。以下の項目を確認して下さい。 + + 原作者の証明書( DCO ) 1.1 + + このプロジェクトに寄与するものとして、以下のことを証明する。 + + (a) 本寄与は私が全体又は一部作成したものであり、私がそのファイ + ル中に明示されたオープンソースライセンスの下で公開する権利 + を持っている。もしくは、 + + (b) 本寄与は、私が知る限り、適切なオープンソースライセンスでカバ + ーされている既存の作品を元にしている。同時に、私はそのライセ + ンスの下で、私が全体又は一部作成した修正物を、ファイル中で示 + される同一のオープンソースライセンスで(異なるライセンスの下で + 投稿することが許可されている場合を除いて)投稿する権利を持って + いる。もしくは、 + + (c) 本寄与は(a)、(b)、(c)を証明する第3者から私へ直接提供された + ものであり、私はそれに変更を加えていない。 + + (d) 私はこのプロジェクトと本寄与が公のものであることに理解及び同意す + る。同時に、関与した記録(投稿の際の全ての個人情報と sign-off を + 含む)が無期限に保全されることと、当該プロジェクト又は関連する + オープンソースライセンスに沿った形で再配布されることに理解及び + 同意する。 + +もしこれに同意できるなら、以下のような1行を追加してください。 + + Signed-off-by: Random J Developer <random@developer.example.org> + +実名を使ってください。(残念ですが、偽名や匿名による寄与はできません。) + +人によっては sign-off の近くに追加のタグを付加しています。それらは今のところ +無視されますが、あなたはそのタグを社内の手続きに利用したり、sign-off に特別 +な情報を示したりすることができます。 + +あなたがサブシステムまたはブランチのメンテナであれば、受け取ったパッチを自身の +ツリーにマージするために、わずかに変更が必要となる場合があります。なぜなら +あなたのツリーの中のコードと投稿者のツリーの中のコードは同一ではないためです。 +もし、あなたが厳密に上記ルール(c)にこだわるのであれば、投稿者に再度差分を +とるよう依頼すべきです。しかし、これは時間とエネルギーを非生産的に浪費する +ことになります。ルール(b)はあなたにコードを修正する権利を与えてくれます。 +しかし、投稿者のコードを修正し、その修正によるバグを投稿者に押し付けてしまう +ことはとても失礼なことです。この問題を解決するために、末尾の投稿者の +Signed-off-by とあなたがその末尾に追加する Signed-off-by の間に、修正を +加えたことを示す1行を追加することが推奨されています。 +(その1行の書き方に)決まりはありませんが、大括弧の中に電子メールアドレスや氏名 +と修正内容を記載するやり方は目につきやすく、最終段階での変更の責任があなたに +あることを明確にするのに十分な方法のようです。例えば、 + + Signed-off-by: Random J Developer <random@developer.example.org> + [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] + Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> + +あなたが安定版のブランチを管理しており、作成者のクレジット、変更の追跡、 +修正のマージ、と同時に苦情からの投稿者の保護を行いたい場合、この慣習は特に +有用となります。いかなる事情があってもチェンジログに出てくる作成者の +アイデンティティ情報(From ヘッダ)は変更できないことに注意してください。 + +バックポートする人のための特別な注意事項。追跡を容易に行うために、コミット +メッセージのトップ(サブジェクト行のすぐ後)にパッチの起源を示す情報を記述する +ことは一般的で有用な慣習です。例えば、これは 2.6-stable ツリーでの一例です。 + + Date: Tue May 13 19:10:30 2008 +0000 + + SCSI: libiscsi regression in 2.6.25: fix nop timer handling + + commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream + +そして、これは 2.4 ツリーでの一例です。 + + Date: Tue May 13 22:12:27 2008 +0200 + + wireless, airo: waitbusy() won't delay + + [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] + +どんな形式であれ、この情報はあなたのツリーを追跡する人やあなたのツリーのバグを +解決しようとしている人にとって価値のある支援となります。 + +13) いつ Acked-by: と Cc: を使うのか + +「 Signed-off-by: 」タグはその署名者がパッチの開発に関わっていたことやパッチ +の伝播パスにいたことを示しています。 + +ある人が直接パッチの準備や作成に関わっていないけれど、その人のパッチに対す +る承認を記録し、示したいとします。その場合、その人を示すのに Acked-by: が使 +えます。Acked-by: はパッチのチェンジログにも追加されます。 + +パッチの影響を受けるコードのメンテナがパッチに関わっていなかったり、パッチ +の伝播パスにいなかった時にも、メンテナは Acked-by: をしばしば利用します。 + +Acked-by: は Signed-off-by: のように公式なタグではありません。それはメンテナが +少なくともパッチをレビューし、同意を示しているという記録です。そのような +ことからパッチをマージする人がメンテナの「うん、良いと思うよ」という発言を +Acked-by: へ置き換えることがあります。 + +Acked-by: が必ずしもパッチ全体の承認を示しているわけではありません。例えば、 +あるパッチが複数のサブシステムへ影響を与えており、その中の1つのサブシステム +のメンテナからの Acked-by: を持っているとします。その場合、Acked-by: は通常 +そのメンテナのコードに影響を与える一部分だけに対する承認を示しています。 +この点は、ご自分で判断してください。(その Acked-by: が)疑わしい場合は、 +メーリングリストアーカイブの中の大元の議論を参照すべきです。 + +パッチにコメントする機会を持っていたが、その時にコメントしなかった人がいれば、 +その人を指す「Cc:」タグを任意で追加してもかまいません。これは指定された人からの +明確なアクションなしに付与できる唯一のタグです。 +このタグはパッチに関心があると思われる人達がそのパッチの議論に含まれていたこと +を明文化します。 + +14) Reported-by と Tested-by: と Reviewed-by: の利用 + +他の誰かによって報告された問題を修正するパッチであれば、問題報告者という寄与を +クレジットするために、Reported-by: タグを追加することを検討してください。 +こまめにバグ報告者をクレジットしていくことで、うまくいけばその人たちが将来再び +コミュニティの力となってくれるでしょう。 +ただし、報告者の許可無くこのタグを追加しないように注意してください。特に、 +問題が公の場で報告されていなかったのであれば。 + +Tested-by: タグはタグで指定された人によって(ある環境下で)パッチのテストに成功 +していることを示します。このタグはメンテナにテストが実施済みであることを +知らせ、将来の関連パッチのテスト協力者を見つける方法を提供し、テスト実施者に +対するクレジットを保証します。 + +Reviewed-by: タグは、それとは異なり、下記のレビューア宣言の下にレビューされ、 +受け入れ可能とみなされたパッチであることを示します。 + + レビューアによる監督宣言 + + 私は Reviewed-by: タグを提示することによって、以下のことを明言する。 + + (a) 私はメインラインカーネルへの統合に向け、その妥当性及び「即応性 + (訳注)」を検証し、技術的側面からパッチをレビュー済みである。 + + 訳注: + 「即応性」の原文は "readiness"。 + パッチが十分な品質を持っており、メインラインカーネルへの統合を即座に + 行うことができる状態であるかどうかを "readiness" という単語で表現 + している。 + + (b) パッチに関するあらゆる問題、懸念、あるいは、疑問は投稿者へ伝達済み + である。私はそれらのコメントに対する投稿者の返答に満足している。 + + (c) 投稿に伴い改良されるコードがある一方で、現時点で、私は(1)それが + カーネルにとって価値のある変更であること、そして、(2)統合に際して + 議論になり得るような問題はないものと確信している。 + + (d) 私はパッチをレビューし適切であると確信している一方で、あらゆる + 状況においてその宣言した目的や機能が正しく実現することに関して、 + いかなる保証もしない(特にどこかで明示しない限り)。 + +Reviewd-by タグはそのパッチがカーネルに対して適切な修正であって、深刻な技術的 +問題を残していないという意見の宣言です。興味のあるレビューアは誰でも(レビュー +作業を終えたら)パッチに対して Reviewed-by タグを提示できます。このタグは +レビューアの寄与をクレジットする働き、レビューの進捗の度合いをメンテナに +知らせる働きを持ちます。そのパッチの領域に詳しく、そして、しっかりとした +レビューを実施したレビューアによって提供される時、Reviewed-by: タグがあなたの +パッチをカーネルにマージする可能性を高めるでしょう。 + +15) 標準的なパッチのフォーマット + +標準的なパッチのサブジェクトは以下のとおりです。 + + Subject: [PATCH 001/123] subsystem: summary phrase + +標準的なパッチの、電子メールのボディは以下の項目を含んでいます。 + + - パッチの作成者を明記する「 from 」行 + + - 空行 + + - 説明本体。これはこのパッチを説明するために無期限のチェンジログ + (変更履歴)にコピーされます。 + + - 上述した「 Signed-off-by: 」行。これも説明本体と同じくチェン + ジログ内にコピーされます。 + + - マーカー行は単純に「 --- 」です。 + + - 余計なコメントは、チェンジログには不適切です。 + + - 実際のパッチ(差分出力) + +サブジェクト行のフォーマットは、アルファベット順で電子メールをとても +ソートしやすいものになっています。(ほとんどの電子メールクライアント +はソートをサポートしています)パッチのサブジェクトの連番は0詰めであ +るため、数字でのソートとアルファベットでのソートは同じ結果になります。 + +電子メールのサブジェクト内のサブシステム表記は、パッチが適用される +分野またはサブシステムを識別できるようにすべきです。 + +電子メールのサブジェクトの「summary phrase」はそのパッチの概要を正確 +に表現しなければなりません。「summary phrase」をファイル名にしてはい +けません。パッチシリーズ中でそれぞれのパッチは同じ「summary phrase」を +使ってはいけません(「パッチシリーズ」とは順序付けられた関連のある複数の +パッチ群です)。 + +あなたの電子メールの「summary phrase」がそのパッチにとって世界で唯一の識別子に +なるように心がけてください。「summary phrase」は git のチェンジログの中へ +ずっと伝播していきます。「summary phrase」は、開発者が後でパッチを参照する +ために議論の中で利用するかもしれません。 +人々はそのパッチに関連した議論を読むために「summary phrase」を使って google で +検索したがるでしょう。それはまた2、3ヶ月あとで、人々が「gitk」や +「git log --oneline」のようなツールを使用して何千ものパッチに目を通す時、 +唯一目にとまる情報となるでしょう。 + +これらの理由のため、「summary phrase」はなぜパッチが必要であるか、パッチが何を +変更するかの2つの情報をせいぜい70〜75文字で表現していなければなりません。 +「summary phrase」は簡潔であり説明的である表現を目指しつつ、うまく +まとめられている概要となるべきです。 + +「summary phrase」は「Subject: [PATCH tag] <summary phrase>」のように、 +大括弧で閉じられたタグを接頭辞として付加してもかまいません。このタグは +「summary phrase」の一部とは考えませんが、パッチをどのように取り扱うべきかを +表現します。 +一般的には「v1, v2, v3」のようなバージョン情報を表すタグ(過去のパッチに対する +コメントを反映するために複数のバージョンのパッチが投稿されているのであれば)、 +「RFC」のようなコメントを要求するタグが挙げられます。パッチシリーズとして4つの +パッチがあれば、個々のパッチに「1/4, 2/4, 3/4, 4/4」のように番号を付けても +かまいません。これは開発者がパッチを適用する順番を確実に把握するためです。 +そして、開発者がパッチシリーズの中のすべてのパッチをもらさずレビュー或いは +適用するのを保証するためです。 + +サブジェクトの例を二つ + + Subject: [patch 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCHv2 001/207] x86: fix eflags tracking + +「 from 」行は電子メールのボディの一番最初の行でなければなりません。 +その形式は以下のとおりです。 + + From: Original Author <author@example.com> + +「 from 」行はチェンジログの中で、そのパッチの作成者としてクレジットされ +ている人を特定するものです。「 from 」行がかけていると、電子メールのヘッ +ダーの「 From: 」が、チェンジログの中でパッチの作成者を決定するために使わ +れるでしょう。 + +説明本体は無期限のソースのチェンジログにコミットされます。なので、説明 +本体はそのパッチに至った議論の詳細を忘れているある程度の技量を持っている人 +がその詳細を思い出すことができるものでなければなりません。パッチが対処する +障害の症状(カーネルログメッセージや oops メッセージ等)を記載することは問題に +対処可能なパッチを求めてコミットログを検索する人々にとって特に有用です。 +パッチがコンパイル問題を解決するのであれば、そのパッチを探している人が見つける +ことができる情報だけで十分であり、コンパイル時の全てのエラーを含める必要は +ありません。「summary phrase」と同様に、簡潔であり説明的であることが重要です。 + +「 --- 」マーカー行はパッチ処理ツールに対して、チェンジログメッセージの終端 +部分を認識させるという重要な役目を果たします。 + +「 --- 」マーカー行の後の追加コメントの良い使用方法の1つに diffstat コマンド +があります。diffstat コマンドとは何のファイルが変更され、1ファイル当たり何行 +追加され何行消されたかを示すものです。diffstat コマンドは特に大きなパッチに +おいて役立ちます。その時点でだけ又はメンテナにとってのみ関係のあるコメント +は無期限に保存されるチェンジログにとって適切ではありません。そのため、この +ようなコメントもマーカー行の後に書かれるべきです。 +このようなコメントの良い例として、v1 と v2 のバージョン間で何が変更されたかを +表す「パッチの変更履歴」が挙げられます。 + +「 --- 」マーカー行の後に diffstat コマンドの結果を含めるのであれば、ファイル +名はカーネルソースツリーのトップディレクトリからの表記で列記されるため、横方向 +のスペースをとり過ぎないように、diffstat コマンドにオプション「 -p 1 -w 70 」 +を指定してください(インデントを含めてちょうど80列に合うでしょう)。 + +適切なパッチのフォーマットの詳細についてはセクション3の参考文献を参照して +ください。 + +16) 「git pull」要求の送り方(Linus の電子メールから) + +間違ったブランチから引っ張るのを防ぐために、git リポジトリのアドレスと +ブランチ名を同じ行に1行で記載してください。そうすることで、3回の連続クリック +で全て選択できます。 + +正しい形式は下記の通りです。 + + "Please pull from + + git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus + + to get these changes:" + +その結果、アドレスを自分自身でタイピングして間違えることはなくなります(実際に、 +何度か間違ったブランチから引っ張ってきてしまい、その時に diffstat の結果を +検証して間違っていることに気づいたことがあります。どこから何を引っ張るべきかを +「探したり」、正しいブランチ名かどうかを重ねてチェックしたりする必要が +なくなればより快適になるでしょう)。 + +diffstat の結果を生成するために「 git diff -M --stat --summary 」を使って +ください。-M オプションはファイル名の変更を検知でき、--summary オプションは +新規ファイル、削除されたファイル、名前が変更されたファイルの概要を生成します。 + +-M オプション(ファイル名の変更検知)を指定すると、diffstat の結果はかなり +異なってきます。git は大規模な変更(追加と削除のペア)をファイル名の変更と +判断するためです。 + +------------------------------------ +セクション2 - ヒントとTIPSと小技 +------------------------------------ + +このセクションは Linux カーネルに変更を適用することに関係のある一般的な +「お約束」の多くを載せています。物事には例外というものがあります。しか +し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの +セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。 + +1) Documentation/CodingStyleを参照 + +言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに +も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし +れません。 + +特筆すべき例外は、コードをあるファイルから別のファイルに移動 +するときです。この場合、コードを移動するパッチでは、移動されるコード +に関して移動以外の変更を一切加えるべきではありません。これにより、 +コードの移動とあなたが行ったコードの修正を明確に区別できるようにな +ります。これは実際に何が変更されたかをレビューする際の大きな助けに +なるとともに、ツールにコードの履歴を追跡させることも容易になります。 + +投稿するより前にパッチのスタイルチェッカー( scripts/checkpatch.pl )で +あなたのパッチをチェックしてください。このスタイルチェッカーは最終結 +論としてではなく、指標としてみるべきです。もし、あなたのコードが違反 +はしているが修正するより良く見えるのであれば、おそらくそのままにする +のがベストです。 + +スタイルチェッカーによる3段階のレポート: + - エラー: 間違っている可能性が高い + - 警告：注意してレビューする必要がある + - チェック：考慮する必要がある + +あなたはパッチに残っている全ての違反について、それがなぜ必要なのか正当な +理由を示せるようにしておく必要があります。 + +2) #ifdefは見苦しい + +ifdef が散乱したコードは、読むのもメンテナンスするのも面倒です。コードの中 +で ifdef を使わないでください。代わりに、ヘッダファイルの中に ifdef を入れて、 +条件付きで、コードの中で使われる関数を「 static inline 」関数かマクロで定義し +てください。後はコンパイラが、何もしない箇所を最適化して取り去ってくれるで +しょう。 + +まずいコードの簡単な例 + + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + #ifdef CONFIG_NET_FUNKINESS + init_funky_net(dev); + #endif + +クリーンアップしたコードの例 + +(in header) + #ifndef CONFIG_NET_FUNKINESS + static inline void init_funky_net (struct net_device *d) {} + #endif + +(in the code itself) + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + init_funky_net(dev); + +3) マクロより「 static inline 」を推奨 + +「 static inline 」関数はマクロよりもずっと推奨されています。それらは、 +型安全性があり、長さにも制限が無く、フォーマットの制限もありません。 +gcc においては、マクロと同じくらい軽いです。 + +マクロは「 static inline 」が明らかに不適切であると分かる場所(高速化パスの +いくつかの特定のケース)や「 static inline 」関数を使うことができないような +場所(マクロの引数の文字列連結のような)にだけ使われるべきです。 + +「 static inline 」は「 static __inline__ 」や「 extern inline 」や +「 extern __inline__ 」よりも適切です。 + +4) 設計に凝りすぎるな + +それが有用になるかどうか分からないような不明瞭な将来を見越した設計 +をしないでください。「できる限り簡単に、そして、それ以上簡単になら +ないような設計をしてください。」 + +---------------------- +セクション3 参考文献 +---------------------- + +Andrew Morton, "The perfect patch" (tpp). + <http://www.ozlabs.org/~akpm/stuff/tpp.txt> + +Jeff Garzik, "Linux kernel patch submission format". + <http://linux.yyz.us/patch-format.html> + +Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + <http://www.kroah.com/log/2005/03/31/> + <http://www.kroah.com/log/2005/07/08/> + <http://www.kroah.com/log/2005/10/19/> + <http://www.kroah.com/log/2006/01/11/> + +NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! + <https://lkml.org/lkml/2005/7/11/336> + +Kernel Documentation/CodingStyle: + <http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle> + +Linus Torvalds's mail on the canonical patch format: + <http://lkml.org/lkml/2005/4/7/183> + +Andi Kleen, "On submitting kernel patches" + Some strategies to get difficult or controversial changes in. + http://halobates.de/on-submitting-patches.pdf + +-- + + diff --git a/kernel/Documentation/ja_JP/stable_api_nonsense.txt b/kernel/Documentation/ja_JP/stable_api_nonsense.txt new file mode 100644 index 000000000..7653b5cbf --- /dev/null +++ b/kernel/Documentation/ja_JP/stable_api_nonsense.txt @@ -0,0 +1,263 @@ +NOTE: +This is a version of Documentation/stable_api_nonsense.txt into Japanese. +This document is maintained by IKEDA, Munehiro <m-ikeda@ds.jp.nec.com> +and the JF Project team <http://www.linux.or.jp/JF/>. +If you find any difference between this document and the original file +or a problem with the translation, +please contact the maintainer of this file or JF project. + +Please also note that the purpose of this file is to be easier to read +for non English (read: Japanese) speakers and is not intended as a +fork. So if you have any comments or updates of this file, please try +to update the original English file first. + +Last Updated: 2007/07/18 +================================== +これは、 +linux-2.6.22-rc4/Documentation/stable_api_nonsense.txt の和訳 +です。 +翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > +翻訳日 ： 2007/06/11 +原著作者: Greg Kroah-Hartman < greg at kroah dot com > +翻訳者 ： 池田 宗広 < m-ikeda at ds dot jp dot nec dot com > +校正者 ： Masanori Kobayashi さん < zap03216 at nifty dot ne dot jp > + Seiji Kaneko さん < skaneko at a2 dot mbn dot or dot jp > +================================== + + + +Linux カーネルのドライバインターフェース +（あなたの質問すべてに対する回答とその他諸々） + +Greg Kroah-Hartman <greg at kroah dot com> + + +この文書は、なぜ Linux ではバイナリカーネルインターフェースが定義 +されていないのか、またはなぜ不変のカーネルインターフェースを持たな +いのか、ということを説明するために書かれた。ここでの話題は「カーネ +ル内部の」インターフェースについてであり、ユーザー空間とのインター +フェースではないことを理解してほしい。カーネルとユーザー空間とのイ +ンターフェースとはアプリケーションプログラムが使用するものであり、 +つまりシステムコールのインターフェースがこれに当たる。これは今まで +長きに渡り、かつ今後も「まさしく」不変である。私は確か 0.9 か何か +より前のカーネルを使ってビルドした古いプログラムを持っているが、そ +れは最新の 2.6 カーネルでもきちんと動作する。ユーザー空間とのイン +ターフェースは、ユーザーとアプリケーションプログラマが不変性を信頼 +してよいものの一つである。 + + +要旨 +---- + +あなたは不変のカーネルインターフェースが必要だと考えているかもしれ +ないが、実際のところはそうではない。あなたは必要としているものが分 +かっていない。あなたが必要としているものは安定して動作するドライバ +であり、それはドライバがメインのカーネルツリーに含まれる場合のみ得 +ることができる。ドライバがメインのカーネルツリーに含まれていると、 +他にも多くの良いことがある。それは、Linux をより強固で、安定な、成 +熟したオペレーティングシステムにすることができるということだ。これ +こそ、そもそもあなたが Linux を使う理由のはずだ。 + + +はじめに +-------- + +カーネル内部のインターフェース変更を心配しなければならないドライバ +を書きたいなどというのは、変わり者だけだ。この世界のほとんどの人は、 +そのようなドライバがどんなインターフェースを使っているかなど知らな +いし、そんなドライバのことなど全く気にもかけていない。 + + +まず初めに、クローズソースとか、ソースコードの隠蔽とか、バイナリの +みが配布される使い物にならない代物[訳注(1)]とか、実体はバイナリ +コードでそれを読み込むためのラッパー部分のみソースコードが公開され +ているとか、その他用語は何であれ GPL の下にソースコードがリリース +されていないカーネルドライバに関する法的な問題について、私は「いか +なる議論も」行うつもりがない。法的な疑問があるのならば、プログラマ +である私ではなく、弁護士に相談して欲しい。ここでは単に、技術的な問 +題について述べることにする。（法的な問題を軽視しているわけではない。 +それらは実際に存在するし、あなたはそれをいつも気にかけておく必要が +ある） + +訳注(1) +「使い物にならない代物」の原文は "blob" + + +さてここでは、バイナリカーネルインターフェースについてと、ソースレ +ベルでのインターフェースの不変性について、という二つの話題を取り上 +げる。この二つは互いに依存する関係にあるが、まずはバイナリインター +フェースについて議論を行いやっつけてしまおう。 + + +バイナリカーネルインターフェース +-------------------------------- + +もしソースレベルでのインターフェースが不変ならば、バイナリインター +フェースも当然のように不変である、というのは正しいだろうか？正しく +ない。Linux カーネルに関する以下の事実を考えてみてほしい。 + - あなたが使用するＣコンパイラのバージョンによって、カーネル内部 + の構造体の配置構造は異なったものになる。また、関数は異なった方 + 法でカーネルに含まれることになるかもしれない（例えばインライン + 関数として扱われたり、扱われなかったりする）。個々の関数がどの + ようにコンパイルされるかはそれほど重要ではないが、構造体のパデ + ィングが異なるというのは非常に重要である。 + - あなたがカーネルのビルドオプションをどのように設定するかによっ + て、カーネルには広い範囲で異なった事態が起こり得る。 + - データ構造は異なるデータフィールドを持つかもしれない + - いくつかの関数は全く実装されていない状態になり得る + （例：SMP向けではないビルドでは、いくつかのロックは中身が + カラにコンパイルされる） + - カーネル内のメモリは、異なった方法で配置され得る。これはビ + ルドオプションに依存している。 + - Linux は様々な異なるプロセッサアーキテクチャ上で動作する。 + あるアーキテクチャ用のバイナリドライバを、他のアーキテクチャで + 正常に動作させる方法はない。 + + +ある特定のカーネル設定を使用し、カーネルをビルドしたのと正確に同じ +Ｃコンパイラを使用して単にカーネルモジュールをコンパイルするだけで +も、あなたはこれらいくつもの問題に直面することになる。ある特定の +Linux ディストリビューションの、ある特定のリリースバージョン用にモ +ジュールを提供しようと思っただけでも、これらの問題を引き起こすには +十分である。にも関わらず Linux ディストリビューションの数と、サ +ポートするディストリビューションのリリース数を掛け算し、それら一つ +一つについてビルドを行ったとしたら、今度はリリースごとのビルドオプ +ションの違いという悪夢にすぐさま悩まされることになる。また、ディス +トリビューションの各リリースバージョンには、異なるハードウェア（プ +ロセッサタイプや種々のオプション）に対応するため、何種類かのカーネ +ルが含まれているということも理解して欲しい。従って、ある一つのリ +リースバージョンだけのためにモジュールを作成する場合でも、あなたは +何バージョンものモジュールを用意しなければならない。 + + +信じて欲しい。このような方法でサポートを続けようとするなら、あなた +はいずれ正気を失うだろう。遠い昔、私はそれがいかに困難なことか、身 +をもって学んだのだ・・・ + + +不変のカーネルソースレベルインターフェース +------------------------------------------ + +メインカーネルツリーに含まれていない Linux カーネルドライバを継続 +してサポートしていこうとしている人たちとの議論においては、これは極 +めて「引火性の高い」話題である。[訳注(2)] + +訳注(2) +「引火性の高い」の原文は "volatile"。 +volatile には「揮発性の」「爆発しやすい」という意味の他、「変わり +やすい」「移り気な」という意味がある。 +「（この話題は）爆発的に激しい論争を巻き起こしかねない」ということ +を、「（カーネルのソースレベルインターフェースは）移ろい行くもので +ある」ということを連想させる "volatile" という単語で表現している。 + + +Linux カーネルの開発は継続的に速いペースで行われ、決して歩みを緩め +ることがない。その中でカーネル開発者達は、現状のインターフェースに +あるバグを見つけ、より良い方法を考え出す。彼らはやがて、現状のイン +ターフェースがより正しく動作するように修正を行う。その過程で関数の +名前は変更されるかもしれず、構造体は大きく、または小さくなるかもし +れず、関数の引数は検討しなおされるかもしれない。そのような場合、引 +き続き全てが正常に動作するよう、カーネル内でこれらのインターフェー +スを使用している個所も全て同時に修正される。 + + +具体的な例として、カーネル内の USB インターフェースを挙げる。USB +サブシステムはこれまでに少なくとも３回の書き直しが行われ、その結果 +インターフェースが変更された。これらの書き直しはいくつかの異なった +問題を修正するために行われた。 + - 同期的データストリームが非同期に変更された。これにより多数のド + ライバを単純化でき、全てのドライバのスループットが向上した。今 + やほとんど全ての USB デバイスは、考えられる最高の速度で動作し + ている。 + - USB ドライバが USB サブシステムのコアから行う、データパケット + 用のメモリ確保方法が変更された。これに伴い、いくつもの文書化さ + れたデッドロック条件を回避するため、全ての USB ドライバはより + 多くの情報を USB コアに提供しなければならないようになっている。 + + +このできごとは、数多く存在するクローズソースのオペレーティングシス +テムとは全く対照的だ。それらは長期に渡り古い USB インターフェース +をメンテナンスしなければならない。古いインターフェースが残ることで、 +新たな開発者が偶然古いインターフェースを使い、正しくない方法で開発 +を行ってしまう可能性が生じる。これによりシステムの安定性は危険にさ +らされることになる。 + + +上に挙げたどちらの例においても、開発者達はその変更が重要かつ必要で +あることに合意し、比較的楽にそれを実行した。もし Linux がソースレ +ベルでインターフェースの不変性を保証しなければならないとしたら、新 +しいインターフェースを作ると同時に、古い、問題のある方を今後ともメ +ンテナンスするという余計な仕事を USB の開発者にさせなければならな +い。Linux の USB 開発者は、自分の時間を使って仕事をしている。よっ +て、価値のない余計な仕事を報酬もなしに実行しろと言うことはできない。 + + +セキュリティ問題も、Linux にとっては非常に重要である。ひとたびセキ +ュリティに関する問題が発見されれば、それは極めて短期間のうちに修正 +される。セキュリティ問題の発生を防ぐための修正は、カーネルの内部イ +ンターフェースの変更を何度も引き起こしてきた。その際同時に、変更さ +れたインターフェースを使用する全てのドライバもまた変更された。これ +により問題が解消し、将来偶然に問題が再発してしまわないことが保証さ +れる。もし内部インターフェースの変更が許されないとしたら、このよう +にセキュリティ問題を修正し、将来再発しないことを保証することなど不 +可能なのだ。 + + +カーネルのインターフェースは時が経つにつれクリーンナップを受ける。 +誰も使っていないインターフェースは削除される。これにより、可能な限 +りカーネルが小さく保たれ、現役の全てのインターフェースが可能な限り +テストされることを保証しているのだ。（使われていないインターフェー +スの妥当性をテストすることは不可能と言っていいだろう） + + + +これから何をすべきか +----------------------- + +では、もしメインのカーネルツリーに含まれない Linux カーネルドライ +バがあったとして、あなたは、つまり開発者は何をするべきだろうか？全 +てのディストリビューションの全てのカーネルバージョン向けにバイナリ +のドライバを供給することは悪夢であり、カーネルインターフェースの変 +更を追いかけ続けることもまた過酷な仕事だ。 + + +答えは簡単。そのドライバをメインのカーネルツリーに入れてしまえばよ +い。（ここで言及しているのは、GPL に従って公開されるドライバのこと +だということに注意してほしい。あなたのコードがそれに該当しないなら +ば、さよなら。幸運を祈ります。ご自分で何とかしてください。Andrew +と Linus からのコメント＜Andrew と Linus のコメントへのリンクをこ +こに置く＞をどうぞ）ドライバがメインツリーに入れば、カーネルのイン +ターフェースが変更された場合、変更を行った開発者によってドライバも +修正されることになるだろう。あなたはほとんど労力を払うことなしに、 +常にビルド可能できちんと動作するドライバを手に入れることができる。 + + +ドライバをメインのカーネルツリーに入れると、非常に好ましい以下の効 +果がある。 + - ドライバの品質が向上する一方で、（元の開発者にとっての）メンテ + ナンスコストは下がる。 + - あなたのドライバに他の開発者が機能を追加してくれる。 + - 誰かがあなたのドライバにあるバグを見つけ、修正してくれる。 + - 誰かがあなたのドライバにある改善点を見つけてくれる。 + - 外部インターフェースが変更されドライバの更新が必要になった場合、 + 誰かがあなたの代わりに更新してくれる。 + - ドライバを入れてくれとディストロに頼まなくても、そのドライバは + 全ての Linux ディストリビューションに自動的に含まれてリリース + される。 + + +Linux では、他のどのオペレーティングシステムよりも数多くのデバイス +が「そのまま」使用できるようになった。また Linux は、どのオペレー +ティングシステムよりも数多くのプロセッサアーキテクチャ上でそれらの +デバイスを使用することができるようにもなった。このように、Linux の +開発モデルは実証されており、今後も間違いなく正しい方向へと進んでい +くだろう。:) + + + +------ + +この文書の初期の草稿に対し、Randy Dunlap, Andrew Morton, David +Brownell, Hanna Linder, Robert Love, Nishanth Aravamudan から査読 +と助言を頂きました。感謝申し上げます。 + diff --git a/kernel/Documentation/ja_JP/stable_kernel_rules.txt b/kernel/Documentation/ja_JP/stable_kernel_rules.txt new file mode 100644 index 000000000..9dbda9b5d --- /dev/null +++ b/kernel/Documentation/ja_JP/stable_kernel_rules.txt @@ -0,0 +1,84 @@ +NOTE: +This is Japanese translated version of "Documentation/stable_kernel_rules.txt". +This one is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com> +and JF Project team <www.linux.or.jp/JF>. +If you find difference with original file or problem in translation, +please contact maintainer of this file or JF project. + +Please also note that purpose of this file is easier to read for non +English natives and do no intended to fork. So, if you have any +comment or update of this file, please try to update Original(English) +file at first. + +================================== +これは、 +linux-2.6.29/Documentation/stable_kernel_rules.txt +の和訳です。 + +翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > +翻訳日： 2009/1/14 +翻訳者： Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com> +校正者： 武井伸光さん、<takei at webmasters dot gr dot jp> + かねこさん (Seiji Kaneko) <skaneko at a2 dot mbn dot or dot jp> + 小林 雅典さん (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp> + 野口さん (Kenji Noguchi) <tokyo246 at gmail dot com> + 神宮信太郎さん <jin at libjingu dot jp> +================================== + +ずっと知りたかった Linux 2.6 -stable リリースの全て + +"-stable" ツリーにどのような種類のパッチが受け入れられるか、どのような +ものが受け入れられないか、についての規則- + + - 明らかに正しく、テストされているものでなければならない。 + - 文脈(変更行の前後)を含めて 100 行より大きくてはいけない。 + - ただ一個のことだけを修正しているべき。 + - 皆を悩ませている本物のバグを修正しなければならない。("これはバグで + あるかもしれないが..." のようなものではない) + - ビルドエラー(CONFIG_BROKENになっているものを除く), oops, ハング、デー + タ破壊、現実のセキュリティ問題、その他 "ああ、これはダメだね"という + ようなものを修正しなければならない。短く言えば、重大な問題。 + - 新しい device ID とクオークも受け入れられる。 + - どのように競合状態が発生するかの説明も一緒に書かれていない限り、 + "理論的には競合状態になる"ようなものは不可。 + - いかなる些細な修正も含めることはできない。(スペルの修正、空白のクリー + ンアップなど) + - Documentation/SubmittingPatches の規則に従ったものでなければならない。 + - パッチ自体か同等の修正が Linus のツリーに既に存在しなければならない。 + Linus のツリーでのコミットID を -stable へのパッチ投稿の際に引用す + ること。 + +-stable ツリーにパッチを送付する手続き- + + - 上記の規則に従っているかを確認した後に、stable@vger.kernel.org にパッチ + を送る。 + - 送信者はパッチがキューに受け付けられた際には ACK を、却下された場合 + には NAK を受け取る。この反応は開発者たちのスケジュールによって、数 + 日かかる場合がある。 + - もし受け取られたら、パッチは他の開発者たちと関連するサブシステムの + メンテナーによるレビューのために -stable キューに追加される。 + - パッチに stable@vger.kernel.org のアドレスが付加されているときには、それ + が Linus のツリーに入る時に自動的に stable チームに email される。 + - セキュリティパッチはこのエイリアス (stable@vger.kernel.org) に送られるべ + きではなく、代わりに security@kernel.org のアドレスに送られる。 + +レビューサイクル- + + - -stable メンテナがレビューサイクルを決めるとき、パッチはレビュー委 + 員会とパッチが影響する領域のメンテナ(提供者がその領域のメンテナで無 + い限り)に送られ、linux-kernel メーリングリストにCCされる。 + - レビュー委員会は 48時間の間に ACK か NAK を出す。 + - もしパッチが委員会のメンバから却下されるか、メンテナ達やメンバが気付 + かなかった問題が持ちあがり、linux-kernel メンバがパッチに異議を唱え + た場合には、パッチはキューから削除される。 + - レビューサイクルの最後に、ACK を受けたパッチは最新の -stable リリー + スに追加され、その後に新しい -stable リリースが行われる。 + - セキュリティパッチは、通常のレビューサイクルを通らず、セキュリティ + カーネルチームから直接 -stable ツリーに受け付けられる。 + この手続きの詳細については kernel security チームに問い合わせること。 + +レビュー委員会- + + - この委員会は、このタスクについて活動する多くのボランティアと、少数の + 非ボランティアのカーネル開発者達で構成されている。 + |