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

NOTE:

This is Japanese translated version of "Documentation/HOWTO".

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 not to be intended to fork. So, if you have any

comments or updates of this file, please try to update Original(English)

file at first.

Last Updated: 2007/06/04

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: 2007/07/18

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

これは、

linux-2.6.21/Documentation/HOWTO

linux-2.6.22/Documentation/HOWTO

の和訳です。

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

翻訳日： 2007/06/04

翻訳日： 2007/07/16

翻訳者： 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>

また、このコミュニティがなぜ今うまくまわっているのかという理由の一部も

説明しようと試みています。

カーネルは 少量のアーキテクチャ依存部分がアセンブリ言語で書かれている

以外は大部分は C 言語で書かれています。C言語をよく理解していることはカー

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

     これらのルールに従えばうまくいくことを保証することではありません

     が (すべてのパッチは内容とスタイルについて精査を受けるので)、

     ルールに従わなければ間違いなくうまくいかないでしょう。

     この他にパッチを作る方法についてのよくできた記述は-

	"The Perfect Patch"

  git ツリー-

    - Kbuild の開発ツリー、Sam Ravnborg <sam@ravnborg.org>

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

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

    - ACPI の開発ツリー、 Len Brown <len.brown@intel.com>

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

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

    - Block の開発ツリー、Jens Axboe <axboe@suse.de>

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

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

    - DRM の開発ツリー、Dave Airlie <airlied@linux.ie>

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

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

    - ia64 の開発ツリー、Tony Luck <tony.luck@intel.com>

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

    - ieee1394 の開発ツリー、Jody McIntyre <scjody@modernduck.com>

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

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

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

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

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

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

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

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

    - ネットワークドライバ, Jeff Garzik <jgarzik@pobox.com>

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

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

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

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

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

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

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

  その他の git カーネルツリーは http://kernel.org/git に一覧表がありま

  す。

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

  quilt ツリー-

    - USB, PCI ドライバコアと I2C, Greg Kroah-Hartman <gregkh@suse.de>

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

    - x86-64 と i386 の仲間 Andi Kleen <ak@suse.de>

  その他のカーネルツリーは http://git.kernel.org/ と MAINTAINERS ファ

  イルに一覧表があります。

バグレポート

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

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

いいのです。

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

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

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

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

   す)

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

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

   かしくなった後で)解剖するのに比べればとても簡単です。

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

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

        す"

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

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

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

NOTE:

This is a Japanese translated version of

"Documentation/stable_api_nonsense.txt".

This one is maintained by

IKEDA, Munehiro <m-ikeda@ds.jp.nec.com>

and JF Project team <http://www.linux.or.jp/JF/>.

If you find difference with original file or problem in translation,

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 purpose of this file is easier to read for non

English natives and not to be intended to fork. So, if you have any

comments or updates of this file, please try to update

Original(English) file at first.

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 の和訳

- kobjects	a simple object.

- kset		a set of objects of a certain type.

- ktype		a set of helpers for objects of a common type. 

- subsystem	a controlling object for a number of ksets.

The kobject infrastructure maintains a close relationship with the

1.2 Definition

struct kobject {

	const char		* k_name;

	char			name[KOBJ_NAME_LEN];

	atomic_t		refcount;

	struct kref		kref;

	struct list_head	entry;

	struct kobject		* parent;

	struct kset		* kset;

	struct kobj_type	* ktype;

	struct dentry		* dentry;

	struct sysfs_dirent	* sd;

	wait_queue_head_t	poll;

};

void kobject_init(struct kobject *);

becomes its dominant kset. 

If a kobject does not have a parent nor a dominant kset, its directory

is created at the top-level of the sysfs partition. This should only

happen for kobjects that are embedded in a struct subsystem. 

is created at the top-level of the sysfs partition.

struct kset {

	struct subsystem	* subsys;

	struct kobj_type	* ktype;

	struct list_head	list;

	struct kobject		kobj;

	struct kset_uevent_ops	* uevent_ops;

};

The type that the kobjects are embedded in is described by the ktype

pointer. The subsystem that the kobject belongs to is pointed to by the

subsys pointer. 

pointer.

A kset contains a kobject itself, meaning that it may be registered in

the kobject hierarchy and exported via sysfs. More importantly, the

kset_find_obj() may be used to locate a kobject with a particular

name. The kobject, if found, is returned. 

There are also some helper functions which names point to the formerly

existing "struct subsystem", whose functions have been taken over by

ksets.

decl_subsys(name,type,uevent_ops)

Declares a kset named '<name>_subsys' of type <type> with

uevent_ops <uevent_ops>. For example,

decl_subsys(devices, &ktype_device, &device_uevent_ops);

is equivalent to doing:

struct kset devices_subsys = {

     .kobj = {

	   .name = "devices",

     },

     .ktype = &ktype_devices,

     .uevent_ops = &device_uevent_ops,

};

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:

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.

2.3 sysfs

the kset. A kobj_type may be referenced by an arbitrary number of

ksets, as there may be disparate sets of identical objects. 

4. subsystems

4.1 Description

A subsystem represents a significant entity of code that maintains an

arbitrary number of sets of objects of various types. Since the number

of ksets and the type of objects they contain are variable, a

generic representation of a subsystem is minimal. 

struct subsystem {

	struct kset		kset;

	struct rw_semaphore	rwsem;

};

int subsystem_register(struct subsystem *);

void subsystem_unregister(struct subsystem *);

struct subsystem * subsys_get(struct subsystem * s);

void subsys_put(struct subsystem * s);

A subsystem contains an embedded kset so:

- It can be represented in the object hierarchy via the kset's

  embedded kobject. 

- It can maintain a default list of objects of one type. 

Additional ksets may attach to the subsystem simply by referencing the

subsystem before they are registered. (This one-way reference means

that there is no way to determine the ksets that are attached to the

subsystem.) 

All ksets that are attached to a subsystem share the subsystem's R/W

semaphore. 

4.2 subsystem Programming Interface.

The subsystem programming interface is simple and does not offer the

flexibility that the kset and kobject programming interfaces do. They

may be registered and unregistered, as well as reference counted. Each

call forwards the calls to their embedded ksets (which forward the

calls to their embedded kobjects).

4.3 Helpers

A number of macros are available to make dealing with subsystems and

their embedded objects easier. 

decl_subsys(name,type)

Declares a subsystem named '<name>_subsys', with an embedded kset of

type <type>. For example, 

decl_subsys(devices,&ktype_devices);

is equivalent to doing:

struct subsystem device_subsys = {

       .kset = {

	     .kobj = {

		   .name = "devices",

	     },

	     .ktype = &ktype_devices,

	}

}; 

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, ksets, or other subsystems. The

following helpers make 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 subsystem's embedded kset.

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 subsystem's 

  embedded kset. 

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.

4.4 sysfs

subsystems are represented in sysfs via their embedded kobjects. They

follow the same rules as previously mentioned with no exceptions. They

typically receive a top-level directory in sysfs, except when their

embedded kobject is part of another kset, or the parent of the

embedded kobject is explicitly set. 

Note that the subsystem's embedded kset must be 'attached' to the

subsystem itself in order to use its rwsem. This is done after

kset_add() has been called. (Not before, because kset_add() uses its

subsystem for a default parent if it doesn't already have one).

the one that application programs use, the syscall interface.  That

interface is _very_ stable over time, and will not break.  I have old

programs that were built on a pre 0.9something kernel that still work

just fine on the latest 2.6 kernel release.  This interface is the one

just fine on the latest 2.6 kernel release.  That interface is the one

that users and application programmers can count on being stable.

Rules on how to access information in the Linux kernel sysfs

The kernel exported sysfs exports internal kernel implementation-details

The kernel-exported sysfs exports internal kernel implementation details

and depends on internal kernel structures and layout. It is agreed upon

by the kernel developers that the Linux kernel does not provide a stable

internal API. As sysfs is a direct export of kernel internal

structures, the sysfs interface can not provide a stable interface eighter,

structures, the sysfs interface cannot provide a stable interface either;

it may always change along with internal kernel changes.

To minimize the risk of breaking users of sysfs, which are in most cases

low-level userspace applications, with a new kernel release, the users

of sysfs must follow some rules to use an as abstract-as-possible way to

of sysfs must follow some rules to use an as-abstract-as-possible way to

access this filesystem. The current udev and HAL programs already

implement this and users are encouraged to plug, if possible, into the

abstractions these programs provide instead of accessing sysfs

directly.

abstractions these programs provide instead of accessing sysfs directly.

But if you really do want or need to access sysfs directly, please follow

the following rules and then your programs should work with future

  implementation details in its own API. Therefore it is not better than

  reading directories and opening the files yourself.

  Also, it is not actively maintained, in the sense of reflecting the

  current kernel-development. The goal of providing a stable interface

  to sysfs has failed, it causes more problems, than it solves. It

  current kernel development. The goal of providing a stable interface

  to sysfs has failed; it causes more problems than it solves. It

  violates many of the rules in this document.

- sysfs is always at /sys

  Parsing /proc/mounts is a waste of time. Other mount points are a

  system configuration bug you should not try to solve. For test cases,

  possibly support a SYSFS_PATH environment variable to overwrite the

  applications behavior, but never try to search for sysfs. Never try

  application's behavior, but never try to search for sysfs. Never try

  to mount it, if you are not an early boot script.

- devices are only "devices"

  There is no such thing like class-, bus-, physical devices,

  interfaces, and such that you can rely on in userspace. Everything is

  just simply a "device". Class-, bus-, physical, ... types are just

  kernel implementation details, which should not be expected by

  kernel implementation details which should not be expected by

  applications that look for devices in sysfs.

  The properties of a device are:

      - identical to the DEVPATH value in the event sent from the kernel

        at device creation and removal

      - the unique key to the device at that point in time

      - the kernels path to the device-directory without the leading

      - the kernel's path to the device directory without the leading

        /sys, and always starting with with a slash

      - all elements of a devpath must be real directories. Symlinks

        pointing to /sys/devices must always be resolved to their real

        target, and the target path must be used to access the device.

        target and the target path must be used to access the device.

        That way the devpath to the device matches the devpath of the

        kernel used at event time.

      - using or exposing symlink values as elements in a devpath string

        link

      - it is retrieved by reading the "driver"-link and using only the

        last element of the target path

      - devices which do not have "driver"-link, just do not have a

        driver; copying the driver value in a child device context, is a

      - devices which do not have "driver"-link just do not have a

        driver; copying the driver value in a child device context is a

        bug in the application

    o attributes

      - the files in the device directory or files below a subdirectories

      - the files in the device directory or files below subdirectories

        of the same device directory

      - accessing attributes reached by a symlink pointing to another device,

        like the "device"-link, is a bug in the application

  Everything else is just a kernel driver-core implementation detail,

  Everything else is just a kernel driver-core implementation detail

  that should not be assumed to be stable across kernel releases.

- Properties of parent devices never belong into a child device.

  context properties. If the device 'eth0' or 'sda' does not have a

  "driver"-link, then this device does not have a driver. Its value is empty.

  Never copy any property of the parent-device into a child-device. Parent

  device-properties may change dynamically without any notice to the

  device properties may change dynamically without any notice to the

  child device.

- Hierarchy in a single device-tree

- Hierarchy in a single device tree

  There is only one valid place in sysfs where hierarchy can be examined

  and this is below: /sys/devices.

  It is planned, that all device directories will end up in the tree

  It is planned that all device directories will end up in the tree

  below this directory.

- Classification by subsystem

  There are currently three places for classification of devices:

  /sys/block, /sys/class and /sys/bus. It is planned that these will

  not contain any device-directories themselves, but only flat lists of

  not contain any device directories themselves, but only flat lists of

  symlinks pointing to the unified /sys/devices tree.

  All three places have completely different rules on how to access

  device information. It is planned to merge all three

  classification-directories into one place at /sys/subsystem,

  following the layout of the bus-directories. All buses and

  classes, including the converted block-subsystem, will show up

  classification directories into one place at /sys/subsystem,

  following the layout of the bus directories. All buses and

  classes, including the converted block subsystem, will show up

  there.

  The devices belonging to a subsystem will create a symlink in the

  "devices" directory at /sys/subsystem/<name>/devices.

  subsystem name.

  Assuming /sys/class/<subsystem> and /sys/bus/<subsystem>, or

  /sys/block and /sys/class/block are not interchangeable, is a bug in

  /sys/block and /sys/class/block are not interchangeable is a bug in

  the application.

- Block

  The converted block-subsystem at /sys/class/block, or

  The converted block subsystem at /sys/class/block or

  /sys/subsystem/block will contain the links for disks and partitions

  at the same level, never in a hierarchy. Assuming the block-subsytem to

  contain only disks and not partition-devices in the same flat list is

  at the same level, never in a hierarchy. Assuming the block subsytem to

  contain only disks and not partition devices in the same flat list is

  a bug in the application.

- "device"-link and <subsystem>:<kernel name>-links

  Never depend on the "device"-link. The "device"-link is a workaround

  for the old layout, where class-devices are not created in

  /sys/devices/ like the bus-devices. If the link-resolving of a

  device-directory does not end in /sys/devices/, you can use the

  for the old layout, where class devices are not created in

  /sys/devices/ like the bus devices. If the link-resolving of a

  device directory does not end in /sys/devices/, you can use the

  "device"-link to find the parent devices in /sys/devices/. That is the

  single valid use of the "device"-link, it must never appear in any

  single valid use of the "device"-link; it must never appear in any

  path as an element. Assuming the existence of the "device"-link for

  a device in /sys/devices/ is a bug in the application.

  Accessing /sys/class/net/eth0/device is a bug in the application.

  Never depend on the class-specific links back to the /sys/class

  directory.  These links are also a workaround for the design mistake

  that class-devices are not created in /sys/devices. If a device

  that class devices are not created in /sys/devices. If a device

  directory does not contain directories for child devices, these links

  may be used to find the child devices in /sys/class. That is the single

  valid use of these links, they must never appear in any path as an

  valid use of these links; they must never appear in any path as an

  element. Assuming the existence of these links for devices which are

  real child device directories in the /sys/devices tree, is a bug in

  real child device directories in the /sys/devices tree is a bug in

  the application.

  It is planned to remove all these links when when all class-device

  It is planned to remove all these links when all class device

  directories live in /sys/devices.

- Position of devices along device chain can change.

  the chain. You must always request the parent device you are looking for

  by its subsystem value. You need to walk up the chain until you find

  the device that matches the expected subsystem. Depending on a specific

  position of a parent device, or exposing relative paths, using "../" to

  access the chain of parents, is a bug in the application.

  position of a parent device or exposing relative paths using "../" to

  access the chain of parents is a bug in the application.