Merge master.kernel.org:/pub/scm/linux/kernel/git/gregkh/driver-2.6

NOTE:

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>.

fork. So if you have any comments or updates for this file, please try

to update the original English file first.

Last Updated: 2007/07/18

Last Updated: 2007/09/23

==================================

これは、

linux-2.6.22/Documentation/HOWTO

linux-2.6.23/Documentation/HOWTO

の和訳です。

翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >

翻訳日： 2007/07/16

翻訳日： 2007/09/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>

         野口さん (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 カーネル開発のやり方

手助けになります。

もし、このドキュメントのどこかが古くなっていた場合には、このドキュメン

トの最後にリストしたメンテナーにパッチを送ってください。

トの最後にリストしたメンテナにパッチを送ってください。

はじめに

---------

ネル開発者には必要です。アーキテクチャ向けの低レベル部分の開発をするの

でなければ、(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要あり

ません。以下の本は、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 言語拡張に置いている前提がどう

なっているのかわかりにくいことがあり、また、残念なことに決定的なリファ

レンスは存在しません。情報を得るには、gcc の info ページ( info gcc )を

みてください。

見てください。

あなたは既存の開発コミュニティと一緒に作業する方法を学ぼうとしているこ

とに留意してください。そのコミュニティは、コーディング、スタイル、

Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま

す。ライセンスの詳細については、ソースツリーのメインディレクトリに存在

する、COPYING のファイルをみてください。もしライセンスについてさらに質

する、COPYING のファイルを見てください。もしライセンスについてさらに質

問があれば、Linux Kernel メーリングリストに質問するのではなく、どうぞ

法律家に相談してください。メーリングリストの人達は法律家ではなく、法的

問題については彼らの声明はあてにするべきではありません。

新しいドキュメントファイルも追加することを勧めます。

カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの

変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報

をマニュアルページのメンテナ mtk-manpages@gmx.net に送ることを勧めます。

をマニュアルページのメンテナ mtk-manpages@gmx.net に送ることを勧めま

す。

以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で

す-

  README

    このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注

    configure )し、生成(訳注 build )するために必要なことは何かが書かれ

    ています。カーネルに関して初めての人はここからスタートするとよいで

    ています。カーネルに関して初めての人はここからスタートすると良いで

    しょう。

  Documentation/Changes

  Documentation/CodingStyle

    これは Linux カーネルのコーディングスタイルと背景にある理由を記述

    しています。全ての新しいコードはこのドキュメントにあるガイドライン

    に従っていることを期待されています。大部分のメンテナーはこれらのルー

    に従っていることを期待されています。大部分のメンテナはこれらのルー

    ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード

    だけをレビューします。

    支援してください。

  Documentation/ManagementStyle

    このドキュメントは Linux カーネルのメンテナー達がどう行動するか、

    このドキュメントは Linux カーネルのメンテナ達がどう行動するか、

    彼らの手法の背景にある共有されている精神について記述しています。こ

    れはカーネル開発の初心者なら（もしくは、単に興味があるだけの人でも）

    重要です。なぜならこのドキュメントは、カーネルメンテナー達の独特な

    重要です。なぜならこのドキュメントは、カーネルメンテナ達の独特な

    行動についての多くの誤解や混乱を解消するからです。

  Documentation/stable_kernel_rules.txt

    このファイルはどのように stable カーネルのリリースが行われるかのルー

    ルが記述されています。そしてこれらのリリースの中のどこかで変更を取

    り入れてもらいたい場合に何をすればいいかが示されています。

    り入れてもらいたい場合に何をすれば良いかが示されています。

  Documentation/kernel-docs.txt

  カーネル開発に付随する外部ドキュメントのリストです。もしあなたが

ここには、また、カーネルのコンパイルのやり方やパッチの当て方などの間接

的な基本情報も記述されています。

あなたがどこからスタートしてよいかわからないが、Linux カーネル開発コミュ

あなたがどこからスタートして良いかわからないが、Linux カーネル開発コミュ

ニティに参加して何かすることをさがしている場合には、Linux kernel

Janitor's プロジェクトにいけばよいでしょう -

Janitor's プロジェクトにいけば良いでしょう -

	http://janitor.kernelnewbies.org/

ここはそのようなスタートをするのにうってつけの場所です。ここには、

Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな

自己参照方式で、索引がついた web 形式で、ソースコードを参照することが

できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり

ます-

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

	http://sosdg.org/~qiyong/lxr/

開発プロセス

-----------------------

以下のとおり-

  - 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、

    この期間中に、メンテナー達は Linus に大きな差分を送ることができま

    す。このような差分は通常 -mm カーネルに数週間含まれてきたパッチで

    す。 大きな変更は git(カーネルのソース管理ツール、詳細は

    この期間中に、メンテナ達は Linus に大きな差分を送ることができます。

    このような差分は通常 -mm カーネルに数週間含まれてきたパッチです。

    大きな変更は git(カーネルのソース管理ツール、詳細は

    http://git.or.cz/  参照) を使って送るのが好ましいやり方ですが、パッ

    チファイルの形式のまま送るのでも十分です。

    に安定した状態にあると判断したときにリリースされます。目標は毎週新

    しい -rc カーネルをリリースすることです。

   - 以下の URL で各 -rc リリースに存在する既知の後戻り問題のリスト

     が追跡されます-

     http://kernelnewbies.org/known_regressions

  - このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま

    す。このプロセスはだいたい 6週間継続します。

linux-kernel メーリングリストで収集された多数のパッチと同時に一つにま

とめます。

このツリーは新機能とパッチが検証される場となります。ある期間の間パッチ

が -mm に入って価値を証明されたら、Andrew やサブシステムメンテナが、メ

インラインへ入れるように Linus にプッシュします。

が -mm に入って価値を証明されたら、Andrew やサブシステムメンテナが、

メインラインへ入れるように Linus にプッシュします。

メインカーネルツリーに含めるために Linus に送る前に、すべての新しいパッ

チが -mm ツリーでテストされることが強く推奨されます。

せん-

彼らはあなたのパッチの行毎にコメントを入れたいので、そのためにはそうす

るしかありません。あなたのメールプログラムが空白やタブを圧縮しないよう

に確認した方がいいです。最初の良いテストとしては、自分にメールを送って

に確認した方が良いです。最初の良いテストとしては、自分にメールを送って

みて、そのパッチを自分で当ててみることです。もしそれがうまく行かないな

ら、あなたのメールプログラムを直してもらうか、正しく動くように変えるべ

きです。

とも普通のことです。これはあなたのパッチが受け入れられないということで

は *ありません*、そしてあなた自身に反対することを意味するのでも *ありま

せん*。単に自分のパッチに対して指摘された問題を全て修正して再送すれば

いいのです。

良いのです。

カーネルコミュニティと企業組織のちがい

-----------------------------------------------------------------

カーネルコミュニティは大部分の伝統的な会社の開発環境とは異ったやり方で

動いています。以下は問題を避けるためにできるとよいことののリストです-

動いています。以下は問題を避けるためにできると良いことのリストです-

  あなたの提案する変更について言うときのうまい言い方：

    - "以下は一連の小さなパッチ群ですが..."

    - "これは典型的なマシンでの性能を向上させます.."

  やめた方がいい悪い言い方：

  やめた方が良い悪い言い方：

    - このやり方で AIX/ptx/Solaris ではできたので、できるはずだ

    - 私はこれを20年もの間やってきた、だから

1) 小さいパッチはあなたのパッチが適用される見込みを大きくします、カー

   ネルの人達はパッチが正しいかどうかを確認する時間や労力をかけないか

   らです。5行のパッチはメンテナがたった1秒見るだけで適用できます。し

   かし、500行のパッチは、正しいことをレビューするのに数時間かかるかも

   しれません(時間はパッチのサイズなどにより指数関数に比例してかかりま

   す)

   らです。5行のパッチはメンテナがたった1秒見るだけで適用できます。

   しかし、500行のパッチは、正しいことをレビューするのに数時間かかるか

   もしれません(時間はパッチのサイズなどにより指数関数に比例してかかり

   ます)

   小さいパッチは何かあったときにデバッグもとても簡単になります。パッ

   チを1個1個取り除くのは、とても大きなパッチを当てた後に(かつ、何かお

2) 小さいパッチを送るだけでなく、送るまえに、書き直して、シンプルにす

   る(もしくは、単に順番を変えるだけでも)ことも、とても重要です。

以下はカーネル開発者の Al Viro のたとえ話しです：

以下はカーネル開発者の Al Viro のたとえ話です：

        "生徒の数学の宿題を採点する先生のことを考えてみてください、先

        生は生徒が解に到達するまでの試行錯誤をみたいとは思わないでしょ

        う。先生は簡潔な最高の解をみたいのです。良い生徒はこれを知って

        生は生徒が解に到達するまでの試行錯誤を見たいとは思わないでしょ

        う。先生は簡潔な最高の解を見たいのです。良い生徒はこれを知って

        おり、そして最終解の前の中間作業を提出することは決してないので

        す"

        カーネル開発でもこれは同じです。メンテナー達とレビューア達は、

        問題を解決する解の背後になる思考プロセスをみたいとは思いません。

        彼らは単純であざやかな解決方法をみたいのです。

        カーネル開発でもこれは同じです。メンテナ達とレビューア達は、

        問題を解決する解の背後になる思考プロセスを見たいとは思いません。

        彼らは単純であざやかな解決方法を見たいのです。

あざやかな解を説明するのと、コミュニティと共に仕事をし、未解決の仕事を

議論することのバランスをキープするのは難しいかもしれません。

ですから、開発プロセスの早期段階で改善のためのフィードバックをもらうよ

うにするのもいいですが、変更点を小さい部分に分割して全体ではまだ完成し

ていない仕事を(部分的に)取り込んでもらえるようにすることもいいことです。

うにするのも良いですが、変更点を小さい部分に分割して全体ではまだ完成し

ていない仕事を(部分的に)取り込んでもらえるようにすることも良いことです。

また、でき上がっていないものや、"将来直す" ようなパッチを、本流に含め

てもらうように送っても、それは受け付けられないことを理解してください。

  - テスト結果

これについて全てがどのようにあるべきかについての詳細は、以下のドキュメ

ントの ChangeLog セクションをみてください-

ントの ChangeLog セクションを見てください-

  "The Perfect Patch"

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

	pt.		[PARIDE]

			See Documentation/paride.txt.

	pty.legacy_count=

			[KNL] Number of legacy pty's. Overwrites compiled-in

			default number.

	quiet		[KNL] Disable most log messages

	r128=		[HW,DRM]

struct kobject {

	const char		* k_name;

	char			name[KOBJ_NAME_LEN];

	struct kref		kref;

	struct list_head	entry;

	struct kobject		* parent;

is equivalent to doing:

struct kset devices_subsys = {

     .kobj = {

	   .name = "devices",

     },

     .ktype = &ktype_devices,

     .uevent_ops = &device_uevent_ops,

};

kobject_set_name(&devices_subsys, name);

The objects that are registered with a subsystem that use the

subsystem's default list must have their kset ptr set properly. These

objects may have embedded kobjects or ksets. The

following helpers make setting the kset easier:

following helper makes setting the kset easier:

kobj_set_kset_s(obj,subsys)

- Assumes that obj->kobj exists, and is a struct kobject.

- Sets the kset of that kobject to the kset <subsys>.

kset_set_kset_s(obj,subsys)

- Assumes that obj->kset exists, and is a struct kset.

- Sets the kset of the embedded kobject to the kset <subsys>.

subsys_set_kset(obj,subsys)

- Assumes obj->subsys exists, and is a struct subsystem.

- Sets obj->subsys.kset.kobj.kset to the subsystem's embedded kset.

void subsystem_init(struct kset *s);

int subsystem_register(struct kset *s);

void subsystem_unregister(struct kset *s);

struct kset *subsys_get(struct kset *s);

void kset_put(struct kset *s);

These are just wrappers around the respective kset_* functions.

}

static int tiocx_uevent(struct device *dev, char **envp, int num_envp,

			 char *buffer, int buffer_size)

static int tiocx_uevent(struct device *dev, struct kobj_uevent_env *env)

{

	return -ENODEV;

}

	return tsize;

}

int of_device_uevent(struct device *dev,

		char **envp, int num_envp, char *buffer, int buffer_size)

int of_device_uevent(struct device *dev, struct kobj_uevent_env *env)

{

	struct of_device *ofdev;

	const char *compat;

	int i = 0, length = 0, seen = 0, cplen, sl;

	int seen = 0, cplen, sl;

	if (!dev)

		return -ENODEV;

	ofdev = to_of_device(dev);

	if (add_uevent_var(envp, num_envp, &i,

			   buffer, buffer_size, &length,

			   "OF_NAME=%s", ofdev->node->name))

	if (add_uevent_var(env, "OF_NAME=%s", ofdev->node->name))

		return -ENOMEM;

	if (add_uevent_var(envp, num_envp, &i,

			   buffer, buffer_size, &length,

			   "OF_TYPE=%s", ofdev->node->type))

	if (add_uevent_var(env, "OF_TYPE=%s", ofdev->node->type))

		return -ENOMEM;

        /* Since the compatible field can contain pretty much anything

	compat = of_get_property(ofdev->node, "compatible", &cplen);

	while (compat && *compat && cplen > 0) {

		if (add_uevent_var(envp, num_envp, &i,

				   buffer, buffer_size, &length,

				   "OF_COMPATIBLE_%d=%s", seen, compat))

		if (add_uevent_var(env, "OF_COMPATIBLE_%d=%s", seen, compat))

			return -ENOMEM;

		sl = strlen (compat) + 1;

		seen++;

	}

	if (add_uevent_var(envp, num_envp, &i,

			   buffer, buffer_size, &length,

			   "OF_COMPATIBLE_N=%d", seen))

	if (add_uevent_var(env, "OF_COMPATIBLE_N=%d", seen))

		return -ENOMEM;

	/* modalias is trickier, we add it in 2 steps */

	if (add_uevent_var(envp, num_envp, &i,

			   buffer, buffer_size, &length,

			   "MODALIAS="))

	if (add_uevent_var(env, "MODALIAS="))

		return -ENOMEM;

	sl = of_device_get_modalias(ofdev, &buffer[length-1],

					buffer_size-length);

	if (sl >= (buffer_size-length))

	sl = of_device_get_modalias(ofdev, &env->buf[env->buflen-1],

				    sizeof(env->buf) - env->buflen);

	if (sl >= (sizeof(env->buf) - env->buflen))

		return -ENOMEM;

	length += sl;

	envp[i] = NULL;

	env->buflen += sl;

	return 0;

}