JF Linux Kernel 3.x/2.6 Documentation: /usr/src/linux/Documentation/usb/hotplug.txt

usb/hotplug.txt

USB ホットプラグの説明 [プレインテキスト版]


==================================
これは、
linux-2.6.13-rc3/Documentation/usb/hotplug.txt の和訳
です。
翻訳団体: JF プロジェクト < http://www.linux.or.jp/JF/ >
翻訳日 : 2005/8/2
翻訳者 : Hiroshi.Suzuki < setter at reset dot jp >
校正者 : Chie Nakatani さん <jeanne at mbox dot kyoto-inet dot or dot jp>
==================================
LINUX HOTPLUGGING

LINUX ホットプラグ

In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices
into the bus with power on.  In most cases, users expect the devices to become
immediately usable.  That means the system must do many things, including:

USB(および、カードバス PCI) のような、ホットプラグ可能なバスでは、エンドユーザは
電源が入った状態でデバイスをバスに接続します。ほとんどの場合、ユーザはすぐにデバイス
が使えるようになって欲しいと思っています。これは、システムが次に示すことを含めて、
多くの事をしなければならないことを意味します:

    - Find a driver that can handle the device.  That may involve
      loading a kernel module; newer drivers can use module-init-tools
      to publish their device (and class) support to user utilities.

    - デバイスを扱えるドライバを探す。カーネルモジュールをロードするかもしれません;
      より新しいドライバは、ユーザユーティリティにデバイス(および、クラス)サポート
      を公開するために、module-init-tools を使えます。

    - Bind a driver to that device.  Bus frameworks do that using a
      device driver's probe() routine.

    - デバイスにドライバをバインドする。バスフレームワークがデバイスドライバの 
      probe() ルーチンを使って行います。

    - Tell other subsystems to configure the new device.  Print
      queues may need to be enabled, networks brought up, disk
      partitions mounted, and so on.  In some cases these will
      be driver-specific actions.

     - 新しいデバイスを設定するため、別のサブシステムを呼びます。プリントキュー
       を有効にする、ネットワークを起動する、ディスクパーティションをマウントする
       などが必要かもしれません。これらが、ドライバ特有の動作になる場合もあります。

This involves a mix of kernel mode and user mode actions.  Making devices
be immediately usable means that any user mode actions can't wait for an
administrator to do them:  the kernel must trigger them, either passively
(triggering some monitoring daemon to invoke a helper program) or
actively (calling such a user mode helper program directly).

これには、カーネルモードとユーザモードを混合した動作が必要です。
デバイスをすぐに使えるようにするということは、どのようなユーザモード動作も、
それらを動かすために管理者を待っていられないということです:
カーネルは、受動的(ヘルパープログラムを起動するために、何かのモニターデーモン
を起動する)または、能動的(ユーザモードヘルパープログラムのようなものを直接呼び出す)
どちらかによって、それらを起動しなければなりません。

Those triggered actions must support a system's administrative policies;
such programs are called "policy agents" here.  Typically they involve
shell scripts that dispatch to more familiar administration tools.

このように起動された動作は、システムの管理ポリシーをサポートしなければなりません;
ここでは、そのようなプログラム(たいていの場合、よく知られている管理ツールにディスパッチ
するシェルスクリプトを含みます)を、"ポリシーエージェント"と呼びます。

Because some of those actions rely on information about drivers (metadata)
that is currently available only when the drivers are dynamically linked,
you get the best hotplugging when you configure a highly modular system.

これら動作のいくつかは、ドライバに関する情報(メタデータ)(現在ドライバが直接リンク
しているときだけ利用できます)に依存するものもあるので、高度にモジュール化された
システムを構成すると、最高のホットプラグ環境を得られます。

KERNEL HOTPLUG HELPER (/sbin/hotplug)

カーネルホットプラグヘルパー (/sbin/hotplug)

When you compile with CONFIG_HOTPLUG, you get a new kernel parameter:
/proc/sys/kernel/hotplug, which normally holds the pathname "/sbin/hotplug".
That parameter names a program which the kernel may invoke at various times.

CONFIG_HOTPLUG を組み込むと、新しいカーネルパラメータが使えます
/proc/sys/kernel/hotplug  (この内容は通常、パス名 "/sbin/hotplug" になります)
そのパラメータには、カーネルが頻繁に起動するプログラムを指定します。

The /sbin/hotplug program can be invoked by any subsystem as part of its
reaction to a configuration change, from a thread in that subsystem.
Only one parameter is required: the name of a subsystem being notified of
some kernel event.  That name is used as the first key for further event
dispatch; any other argument and environment parameters are specified by
the subsystem making that invocation.

/sbin/hotplug プログラムは設定を変更するため、そのサブシステムにあるス
レッドから、その反応の一部分のようなどんなサブシステムによっても起動で
きます。パラメータはひとつだけ必要です:
あるカーネルイベントについて通知を受けているサブシステム名になります。
その名前は、さらなるイベントディスパッチで、最初のキーとして使用されます;
他の引数、および、環境変数は、サブシステム起動時に設定されます。

Hotplug software and other resources is available at:

ホットプラグソフトウェアと、他の資源は、次の場所にあります:

	http://linux-hotplug.sourceforge.net

Mailing list information is also available at that site.

メーリングリスト情報もそのサイトにあります。

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


USB POLICY AGENT

USB ポリシーエージェント

The USB subsystem currently invokes /sbin/hotplug when USB devices
are added or removed from system.  The invocation is done by the kernel
hub daemon thread [khubd], or else as part of root hub initialization
(done by init, modprobe, kapmd, etc).  Its single command line parameter
is the string "usb", and it passes these environment variables:

現在、USB サブシステムは、USB デバイスが付け外しされたときに、/sbin/hotplug を起動します。
起動は、カーネルハブデーモンスレッド [khubd] や、ルートハブ初期化の一部
(init, modprobe, kapmd, など) により実行されます。その一つのコマンドラインパラメータは、
文字列 "usb" で、次に示すような環境変数も渡します:

    ACTION ... "add", "remove"
    PRODUCT ... USB vendor, product, and version codes (hex)
    TYPE ... device class codes (decimal)
    INTERFACE ... interface 0 class codes (decimal)

    ACTION ... "add", "remove"
    PRODUCT ... USB ベンダ, プロダクト, バージョンコード(16進数)
    TYPE ... デバイスクラスコード (10進数)
    INTERFACE ... インタフェース 0 クラスコード (10進数)

If "usbdevfs" is configured, DEVICE and DEVFS are also passed.  DEVICE is
the pathname of the device, and is useful for devices with multiple and/or
alternate interfaces that complicate driver selection.  By design, USB
hotplugging is independent of "usbdevfs":  you can do most essential parts
of USB device setup without using that filesystem, and without running a
user mode daemon to detect changes in system configuration.

"usbdevfs" が組み込まれている場合、 DEVICE と DEVFS も渡します。
DEVICE は、デバイスのパス名で、ドライバ選択を困難にする、複数 および/または 
代理インタフェースを持つデバイスに有効です。仕様で、USB ホットプラグ は、
"usbdevfs" とは、無関係です: USB デバイスのほとんどの基本的設定は、
そのファイルシステムを使う必要がありません。さらに、システム設定の変更を検出する
ユーザモードデーモンも実行する必要はありません。

Currently available policy agent implementations can load drivers for
modules, and can invoke driver-specific setup scripts.  The newest ones
leverage USB module-init-tools support.  Later agents might unload drivers.

現時点で利用できるポリシーエージェントの実装では、モジュールのためにドライバを
ロードできるのと、ドライバ特有の設定スクリプトを呼び出すことができます。最新のものは 
USB module-init-tools のサポートを導入しています。あとで、エージェントはモジュールを
アンロードできます。

USB MODUTILS SUPPORT

USB MODUTILS サポート

Current versions of module-init-tools will create a "modules.usbmap" file
which contains the entries from each driver's MODULE_DEVICE_TABLE.  Such
files can be used by various user mode policy agents to make sure all the
right driver modules get loaded, either at boot time or later. 

現行バージョンの module-init-tools は、それぞれのドライバの、MODULE_DEVICE_TABLE 
からのエントリを含む、"modules.usbmap" ファイルを作成します。
このようなファイルは、ブート時や、それ以後に、正しいドライバモジュールがロードされたのを
確認するために、任意のユーザモードポリシーエージェントで使えます。

See <linux/usb.h> for full information about such table entries; or look
at existing drivers.  Each table entry describes one or more criteria to
be used when matching a driver to a device or class of devices.  The
specific criteria are identified by bits set in "match_flags", paired
with field values.  You can construct the criteria directly, or with
macros such as these, and use driver_info to store more information.

このようなテーブルエントリについての全情報は、<linux/usb.h> を見てください;
または、存在するドライバを見てください。それぞれのテーブルエントリは、
ドライバがデバイスあるいはデバイスのクラスに合っているなら使われるはずの、
ひとつあるいはそれ以上の基準を記述しています。
特定の基準は、"match_flags" 内のビットセットと、フィールド値の対で、
識別されます。基準は直接、または、そのようなマクロで作ることができます。また、
詳細情報を保存するために、driver_info を使ってください。

    USB_DEVICE (vendorId, productId)
	... matching devices with specified vendor and product ids
    USB_DEVICE_VER (vendorId, productId, lo, hi)
	... like USB_DEVICE with lo <= productversion <= hi
    USB_INTERFACE_INFO (class, subclass, protocol)
	... matching specified interface class info
    USB_DEVICE_INFO (class, subclass, protocol)
	... matching specified device class info

    USB_DEVICE (vendorId, productId)
	... 指定したベンダとプロダクトIDで、デバイスと照合する
    USB_DEVICE_VER (vendorId, productId, lo, hi)
	... USB_DEVICE と同様で、 lo <= productversion <= hi がともなう
    USB_INTERFACE_INFO (class, subclass, protocol)
	... 指定したインタフェースクラス情報で照合する
    USB_DEVICE_INFO (class, subclass, protocol)
	... 指定したデバイスクラス情報で照合する。

A short example, for a driver that supports several specific USB devices
and their quirks, might have a MODULE_DEVICE_TABLE like this:

数種の特徴的な USB デバイスをサポートするドライバと、ちょっとくせのある
デバイスをサポートするドライバには、次に示すような MODULE_DEVICE_TABLE 
があるかもしれません。:

    static const struct usb_device_id mydriver_id_table = {
	{ USB_DEVICE (0x9999, 0xaaaa), driver_info: QUIRK_X },
	{ USB_DEVICE (0xbbbb, 0x8888), driver_info: QUIRK_Y|QUIRK_Z },
	...
	{ } /* end with an all-zeroes entry */

	{ } /* すべて ゼロ のエントリで終了 */

    }
    MODULE_DEVICE_TABLE (usb, mydriver_id_table);

Most USB device drivers should pass these tables to the USB subsystem as
well as to the module management subsystem.  Not all, though: some driver
frameworks connect using interfaces layered over USB, and so they won't
need such a "struct usb_driver".

ほとんどの USB デバイスドライバは、これらテーブルをモジュール管理サブシステム、
および、 USB サブシステムに渡さなければなりません。すべてとは限りませんが、いくつかのドライバ
フレームワークには USB 上に重ねられたインタフェースを使用して接続するものもあり、
それらはこのような、"struct usb_driver" を不要とします。

Drivers that connect directly to the USB subsystem should be declared
something like this:

USB サブシステムに直接接続するドライバは、このように定義しなければなりません:

    static struct usb_driver mydriver = {
	.name		= "mydriver",
	.id_table	= mydriver_id_table,
	.probe		= my_probe,
	.disconnect	= my_disconnect,

	/*
	if using the usb chardev framework:
	    .minor		= MY_USB_MINOR_START,
	    .fops		= my_file_ops,
	if exposing any operations through usbdevfs:
	    .ioctl		= my_ioctl,
	*/

	/*
	usb chardev フレームワークをつかうなら:
	    .minor		= MY_USB_MINOR_START,
	    .fops		= my_file_ops,
	usbdevfs 経由ですべての動作を公開するなら:
	    .ioctl		= my_ioctl,
	*/

    }

When the USB subsystem knows about a driver's device ID table, it's used when
choosing drivers to probe().  The thread doing new device processing checks
drivers' device ID entries from the MODULE_DEVICE_TABLE against interface and
device descriptors for the device.  It will only call probe() if there is a
match, and the third argument to probe() will be the entry that matched.

USB サブシステムがドライバのデバイス ID テーブルを理解すると、それは、probe() へ渡すドライバを
選択するのに使われます。新しいデバイス処理を行うスレッドは、デバイスのためのインタフェースと、
デバイスディスクリプタに対して、MODULE_DEVICE_TABLE からのドライバのデバイス ID エントリを
照合します。一致した場合、それは、probe() を呼び出すだけです。また、probe() に渡す3番目の引数は、
一致したエントリになります。

If you don't provide an id_table for your driver, then your driver may get
probed for each new device; the third parameter to probe() will be null.

ドライバのための id_table がないなら、ドライバはそれぞれの新しいデバイスのために調査された物を得ます;
probe() に渡す3番目のパラメータは無効になります。

Linux カーネル 3.x/2.6 付属文書一覧へ戻る