[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Documentation/kernel/pseudo/index.list: 1.17 -> 1.19
以下のページの更新をしました。ツッコミをお願いします。
Documentation/kernel/pseudo/index.list: 1.17 -> 1.19
> revision 1.19
> date: 2006/12/29 03:41:31; author: kano; state: Exp; lines: +4 -3
> - add newline to terminate heading
> - fix typo
> ----------------------------
> revision 1.18
> date: 2006/12/28 09:37:08; author: blymn; state: Exp; lines: +89 -80
> Update the documentation and examples to the new way of doing devices.
1 月 4 日までに異議がなければ、 commit します。
以下、訳と原文それぞれの新旧の差分です。
--- Documentation/kernel/pseudo/index.list.orig 2006-12-30 13:14:54.000000000 +0900
+++ Documentation/kernel/pseudo/index.list 2006-12-30 13:14:54.000000000 +0900
@@ -262,7 +262,23 @@
読みこみ専用、書きこみ専用、読み書き可能かのいずれかです。
デバイスドライバーは全てをサポートする必要はありません。
</DL></OL><P>
-
+
+ このデバイスドライバーがサポートする関数を、
+ キャラクター型デバイス用の <TT>struct cdevsw</TT> と
+ <TT>struct bdevsw</TT> のいずれかまたは両方に含める必要があります。
+ この構造体の名前は、モジュール名の後に <TT>_cdevsw</TT> または <TT>_bdevsw</TT>
+ を付けたものです。
+ ここで例示する疑似デバイスは、キャラクター型デバイスとしてのみふるまうので、
+ 構造体の名前は <TT>skeleton_cdevsw</TT> とします。
+ なお、この構造体には、すべてのデバイスインターフェース関数のエントリーがありますが、
+ デバイス側で実装するのは、この関数の一部分だけでかまいません。
+ 使われないスタブ関数をすべてのデバイスに実装させるのではなく、
+ 頭に <TT>no</TT> がついた (たとえば noread, nowrite など)、
+ あらかじめ宣言されたスタブが用意されており、これらは呼ばれた時に <TT>ENODEV</TT>
+ または、何の操作もせずに成功を返す <TT>null</TT> (たとえば nullread,
+ nullwrite など) を返します。
+ cdevsw や bdevsw にある関数でドライバーがサポートしていないものに対しては、
+ あらかじめ宣言されたスタブのものを使うだけです。
<ENTRY>newdevice カーネルに新しいデバイスを知らせる
@@ -280,101 +296,78 @@
これらのファイルを変更する必要があって:
<P>
<OL TYPE=i>
-<LI><h4>/usr/src/sys/sys/conf.h</h4>
-
- このファイルには
- cdevsw (character device switch) と bdevsw (block device switch) テーブルエントリー
- を設定する 定義マクロが入ってます。
- あなたが書いているデバイスのタイプがわかっている必要があります。
-
- 我々の例において、 skeleton ドライバーはキャラクター型デバイスなので、
- エントリーを作る必要があります。
- また、 skeleton ドライバーは open, close と ioctl のコールだけをサポートしています。
-
- <I>conf.h</I> ファイルに目を通してみると
- called <TT>cdev__oci_init</TT> と、まさに私が欲しい(方法で)
- 定義されている一般デバイスが見つかります。
- これは、 <I>conf.h</I> に定義を追加するのにたくさん打ちこむことを省かせてくれて:
-<PRE>
- #define cdev_skeleton_init(c,n) cdev__oci_init(c,n)
-</PRE>
- これは、ほかのファイルが cdevsw エントリー を定義できるように、マクロを定義します。
- もっと複雑なドライバー では、単にほかの定義の1つをコピーして、
- 必要に応じ変更を加えればよいです。
-<P>
-<LI><h4>/usr/src/sys/arch/i386/i386/conf.c</h4>
- <!-- ほかのアーキテクチャーではどこ? -->
-
- <I>conf.h</I> に cdevsw 初期化エントリー を作れば、
- 次のステップの設定をします。
-
- 最初にすることはインクルードファイルに 入れ、
- エントリーのプロトタイプを設定することです。
- これをするには次のコードを置けば良く:
-
-<PRE>
- #include "skeleton.h"
- cdev_decl(skeleton)
-</PRE>
-
- ちょっと待った! skeleton.h は作ってないよ!
- その通りです。そのファイルは作っていません。
- それは、 config(8) でつくられ、後ほど、どうやる(なる)のか出てくるでしょう。
- 2行目は skeleton ドライバーの関数プロトタイプの設定で -
- skeleton は あなたの擬似デバイスの名前に置き換えます。
- それは 宣言を処理します。
-
- bdevsw/cdevsw テーブルの中にデバイスを追加することが必要です
- skeleton は cdev なので、 cdevsw 配列 を見つけ、
- エントリーを追加する必要があります。
- その配列の最後にエントリーを追加するべきで
- - cdevsw テーブルの途中に追加すると、ほかのデバイスドライバーを妨害します。
- それで cdevsw テーブルの最後にこういうエントリーを追加します:
+<LI><h4>/usr/src/sys/conf/majors or /usr/src/sys/<I>arch</I>/conf/majors.<I>arch</I></h4>
+ この各ファイルには、NetBSD におけるデバイスメジャー番号のリストが含まれます。
+ <I>/usr/src/sys/conf/majors</I> にあるのは、機種独立なデバイス、すなわち
+ NetBSD が対応しているすべてのアーキテクチャーで利用可能なデバイスのメジャー番号です。
+ デバイスが特定のアーキテクチャーにのみ関連するものである場合は、
+ <I>/usr/src/sys/<B>arch</B>/conf/majors.<B>arch</B></I>
+ (<B>arch</B> は、関連するアーキテクチャーに置き換えます)
+ ファイルを使う必要があります。
+ この各ファイルに含まれるエントリーは、以下の形式をとります。
+<PRE>
+device-major prefix type number condition
+</PRE>
+ この行の正確な文法は、config(5) マニュアルページで説明されていますが、
+ ここで例示するドライバーのためにその内容を説明しておきます。
+<P><DL>
+ <DT>device-major
+ <DD> このエントリーが、
+ デバイスメジャー番号のエントリーであることを示すキーワードです。
+
+ <DT>prefix
+ <DD> すべてのドライバーの関数に対して、
+ 関数名が自動生成される時に与えられる接頭辞です。
+ ここでの例においては、
+ <TT>skeleton</TT> とします。
+
+ <DT>type
+ <DD> メジャーデバイスの型で、
+ <TT>char</TT> または <TT>block</TT> のいずれかです。
+ char と block それぞれの type と number の組を繰り返し書くことで、
+ 両方の型のデバイスを指定することができます。
+
+ <DT>number
+ <DD> デバイスのメジャー番号です。次の空いている番号を選びます。
+ なお、<TT>/dev</TT> にデバイスノードを作る必要があるので、
+ 選んだ番号を控えておきます。
+
+ <DT>condition
+ <DD> このデバイスがカーネルに含まれる条件です。
+ これは、conf ファイル (後述)
+ に含めた疑似デバイスのエントリーと一致させるようにします。
+</DL><P>
+ ここで例示する skeleton 疑似デバイスは、キャラクター型デバイスとし、
+ ドライバーは <TT>i386</TT> アーキテクチャーに依存するものとします。
+ このような仮定をしたので、<TT>/usr/src/sys/arch/i386/conf/majors.i386</TT>
+ ファイルを編集すればよいことになります。すると、
+ メジャー番号 140 が使えることがわかるので、以下のような行を追加します。
<PRE>
- cdev_skeleton_init(NSKELETON,
- skeleton), /* 71: Skeleton pseudo-device */
+device-major skeleton char 140 skeleton
</PRE>
-
- 繰り返しますが、 NSKELETON は私達はどこにも定義していません。
- config(8) を実行すると、中に、 NSKELETON が定義された
- <I>skeleton.h</I> ファイルができ、
- シンボルは作られたデバイスの数だけ定義され - その数は config ファイルに由来します。
-
- 注として <TT>cdev_skeleton_init</TT> は
- <I>conf.h</I> で定義したマクロで、
- 2番目のパラメーター ("skeleton") は擬似ドライバーの名前です。
-
- このマクロは我々のコードで定義した関数名を作るために
- 擬似デバイス名と関数コール名(open, close, ioctl, etc)を連結します。
-
- これは、カーネルがあなたのコードを走らせることを知る方法です。
- パズルの最後のかけらは、そこにあるエントリーのコメントにあるその次の番号です。
- ほかのエントリーの形式をそのままコピーして、
- コメント内の番号を増やしデバイスの関数を書きこむことが必要です。
- この番号は重要です。この番号はデバイスの major number で、
- 後のために、書きとめておく必要があります。
</OL>
-<ENTRY>config config<b></b>(8) に新しいデバイスを知らせる
-
- config(8) に新しい擬似デバイスを知らせるには、
- <TT>/usr/src/sys/conf/files</TT> ファイルを編集します。
-
+<ENTRY>config config<b></b>(1) に新しいデバイスを知らせる
+ config(1) に新しい擬似デバイスを知らせるには、
+ <TT>/usr/src/sys/conf/files</TT> (アーキテクチャー独立なデバイスの場合) または
+ <TT>/usr/src/sys/arch/<I>arch</I>/conf/files.<I>arch</I></TT>
+ (<I>arch</I> は関連するアーキテクチャー) のいずれかのファイルを編集します。
このファイルは 有効な デバイスの名前 と
これらのデバイスと関連するファイルを config に教えます。
最初に擬似デバイスを定義するセクションを捜します。
この セクションは <TT>defpseudo</TT> で始まる行を持っています。
+ ここでは、ドライバーはアーキテクチャー依存であることを仮定しているので、
+ <TT>/usr/src/sys/arch/i386/conf/files.i386</TT> を編集します。
正しいセクションを見つけると、こういう行を加えることができ:
<PRE>
defpseudo skeleton
</PRE>
- config(8)に skeleton という擬似デバイスがあることを教えます。
- つぎに、 config(8) に skeleton 擬似デバイスに関連するファイルを教えてあげる必要があります。
- この場合
- on (訳注 one ???)ファイル
+ config(1)に skeleton という擬似デバイスがあることを教えます。
+ つぎに、 config(1) に skeleton 擬似デバイスに関連するファイルを教えてあげる必要があります。
+ この場合はひとつのファイル
があるだけですが、より複雑な擬似デバイスでは より多くのファイルがあるかもしれず、
同じ方法で必要とされるファイルごとに行を単純に追加していきます。
@@ -390,7 +383,7 @@
カーネルソースツリールートからの相対位置 (通常、 <TT>/usr/src/sys</TT>) です。
3番目のフィールドはドライバー名でこのファイルが関連しているもので、
この場合 skeleton - サンプル擬似デバイスです。
- 4番目 で 最後の フィールド は config(8) に
+ 4番目 で 最後の フィールド は config(1) に
skeleton.h インクルードファイルを書かせるための制御フラグです。
ここでファイル名が skeleton.c になっていますが、例示したファイルを使った場合、
ファイル pseudo_dev_skel.c を skeleton.c にリネームするか、このエントリーを
@@ -399,7 +392,7 @@
としたほうがおそらく素直でしょう。
<ENTRY>kernelconfig カーネルコンフィグファイルに新しいデバイスを追加する
- config(8) にデバイスのことを教えてやったあと、
+ config(1) にデバイスのことを教えてやったあと、
そのデバイスをカーネルコンフィグファイルに追加することは簡単です。
skeleton デバイスを追加するには、このような行を加え:
@@ -428,10 +421,10 @@
慣習によって、 デバイスノードは <I>/dev</I> に作られます。
デバイスノード をつくるために mknod(8)を使う必要があり、
- 4.ii 節で書きとめた major 番号で デバイスノード を作ります。
+ 4.i 節で書きとめた major 番号で デバイスノード を作ります。
この場合、 mknod(8) コマンドでこのようにでき:
<PRE>
- mknod /dev/skel c 71 0
+ mknod /dev/skel c 140 0
</PRE>
これで、新しいデバイスをオープンして試すことができます。
@@ -469,9 +462,9 @@
(連絡先 - <a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">英語</a>,
<a href="mailto:www@jp.NetBSD.org">日本語:
www@jp.NetBSD.org</a>)<br>
- $NetBSD: index.list,v 1.17 2006/02/23 17:18:02 kano Exp $<br>
+ $NetBSD: index.list,v 1.19 2006/12/29 03:41:31 kano Exp $<br>
<!-- Based on english version: -->
- <!-- NetBSD: index.list,v 1.17 2006/02/23 17:18:02 kano Exp -->
+ <!-- NetBSD: index.list,v 1.19 2006/12/29 03:41:31 kano Exp -->
<a href="../../../Misc/disclaimer.html">Copyright © 1994-2005
The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.</a><br>
<a href="../../../Misc/disclaimer.html">NetBSD<sup>®</sup> は
Index: Documentation/kernel/pseudo/index.list
===================================================================
RCS file: /cvsroot/htdocs/Documentation/kernel/pseudo/index.list,v
retrieving revision 1.17
retrieving revision 1.19
diff -u -r1.17 -r1.19
--- Documentation/kernel/pseudo/index.list 23 Feb 2006 17:18:02 -0000 1.17
+++ Documentation/kernel/pseudo/index.list 29 Dec 2006 03:41:31 -0000 1.19
@@ -249,7 +249,24 @@
only or read write. The device driver need not
support all modes.
</DL></OL><P>
-
+
+ The function names your device driver supports must be inserted
+ into a <TT>struct cdevsw</TT> for a character device and/or a
+ <TT>struct bdevsw</TT> that has the name of your module appended
+ with either <TT>_cdevsw</TT> or <TT>_bdevsw</TT>. For our sample
+ pseudo-device this structure would be called
+ <TT>skeleton_cdevsw</TT> since we decided that our pseudo-device
+ would be a character device only. Note that these structures have
+ entries in them for all the device interface functions but your
+ device may only implement a subset of these functions. Instead of
+ forcing everyone to implement stub functions for the unused ones
+ there are a set of pre-declared stubs prefixed with either
+ <TT>no</TT> (e.g. noread, nowrite and so on) which will return
+ <TT>ENODEV</TT> when called or <TT>null</TT> (e.g. nullread,
+ nullwrite and so on) which will return success, effectively
+ providing a null operation. For the functions in the cdevsw and/or
+ bdevsw that your driver does not support simply use one of the
+ predeclared stubs.
<ENTRY>newdevice Making the kernel aware of the new device
@@ -263,89 +280,82 @@
have to modify these files:
<P>
<OL TYPE=i>
-<LI><h4>/usr/src/sys/sys/conf.h</h4>
-
- This file contains some macro defines to set up the cdevsw
- (character device switch) and bdevsw (block device switch) table
- entries. You should, by now, know what type of device you are
- writing. In our example the skeleton driver is a character device
- so we want to create an entry. Also, our skeleton driver only
- supports the open, close and ioctl calls. Looking through the
- <I>conf.h</I> file we find there is a generic device defined called
- <TT>cdev__oci_init</TT> which does exactly what we
- want. This saves us a bit of typing by adding this define into
- <I>conf.h</I>:
-
-<PRE>
- #define cdev_skeleton_init(c,n) cdev__oci_init(c,n)
-</PRE>
- This defines a macro we can use to define the cdevsw entry in
- another file. For a more complex driver you can just copy one of
- the other defines and modify as required.
-<P>
-<LI><h4>/usr/src/sys/arch/i386/i386/conf.c</h4>
- <!-- where is it on other architectures? -->
+<LI><h4>/usr/src/sys/conf/majors or /usr/src/sys/<I>arch</I>/conf/majors.<I>arch</I></h4>
- Once we have the cdevsw initialisation entry in <I>conf.h</I> we are set
- to do the next step. The first thing to do is to include an
- include file and set up the prototype for the devsw entry. We do
- this by putting this code in:
-
-<PRE>
- #include "skeleton.h"
- cdev_decl(skeleton)
-</PRE>
-
- Wait a minute! We haven't created a skeleton.h! That is correct,
- we don't create that file. It will be created by config(8), we
- shall see later how this is done. The second line there sets up
- the function prototypes for the skeleton driver - you should
- replace skeleton with the name of your pseudo-device. That takes
- care of the declarations. Now we need to add the device into the
- bdevsw/cdevsw table. Since skeleton is a cdev we need to find the
- cdevsw array and add an entry to it. You should add an entry to
- the end of the array - trying to add an entry in the middle of the
- cdevsw table will mess up all the other device drivers. So, at the
- end of the cdevsw table we add an entry like this:
-
-<PRE>
- cdev_skeleton_init(NSKELETON,
- skeleton), /* 71: Skeleton pseudo-device */
-</PRE>
-
- Again, NSKELETON is not defined by us anywhere. When
- config(8) is run it will generate a <I>skeleton.h</I> file
- with NSKELETON defined in it, the symbol defines the number of
- these devices to create - the number comes from the config file.
- Note that <TT>cdev_skeleton_init</TT> is the macro we
- defined in <I>conf.h</I> and that the second parameter ("skeleton") is the
- name of our pseudo-driver. This macro concatenates the name of
- the pseudo-driver with the function call names (open, close, ioctl,
- etc) to produce the function names that we have defined in our
- code. This is how the kernel knows to run your code. The last bit
- of the puzzle is the number in the comment next to the entry. You
- must copy the format of the other entries, increment the number and
- put the function of your device into the comment. The number is
- important. This number is the major number of your device. You
- need to make a note of this number for later.
+ These files contain lists of device major numbers for NetBSD. The
+ file <I>/usr/src/sys/conf/majors</I> contains the major numbers for
+ devices that are machine independent, that is, available on all
+ architectures that NetBSD supports. If the device is only relevant
+ to a particular architecture then the file
+ <I>/usr/src/sys/<B>arch</B>/conf/majors.<B>arch</B></I> must be used
+ where <B>arch</B> is replaced with the architecture in question.
+ These files contain entries of the form
+<PRE>
+device-major prefix type number condition
+</PRE>
+ The exact syntax for these lines is described in the config(5)
+ man page but for the purposes of our example the components of the
+ line are:
+<P><DL>
+ <DT>device-major
+ <DD> A keyword indicating this is a device major
+ number entry.
+
+ <DT>prefix
+ <DD> The prefix that will be applied to all the
+ driver functions when their names are automatically
+ generated. In our example this would be
+ <TT>skeleton</TT>.
+
+ <DT>type
+ <DD> The type of major device this is, it may be
+ either <TT>char</TT> or <TT>block</TT>. You may
+ specify both a char and block device by repeating the
+ type/number pair for both.
+
+ <DT>number
+ <DD> The major number for the device, choose the next
+ available number. Make a note of this number as you
+ will need it to make the device node in <TT>/dev</TT>.
+
+ <DT>condition
+ <DD> The condition on which this device will be
+ included in the kernel. This should match the
+ pseudo-device entry you put in the conf file
+ (described below).
+</DL><P>
+ For our example skeleton pseudo device we want a character device,
+ and have decided that the driver is machine specific to the
+ <TT>i386</TT> architecture. After making these decisions we can
+ edit the <TT>/usr/src/sys/arch/i386/conf/majors.i386</TT> file, we find
+ that major number 140 is available so we add the line:
+<PRE>
+device-major skeleton char 140 skeleton
+</PRE>
</OL>
-<ENTRY>config Making config<b></b>(8) aware of the new device
- To make config(8) aware of our new pseudo device we need to
- edit the file in <TT>/usr/src/sys/conf/files</TT>.
- This file tells config what valid device names there are and which
- files are associated with these devices. Firstly we look for the
- section that defines the pseudo-devices. This section has lines
- that start with <TT>defpseudo</TT>. Once we have found
- the correct section we can add a line like this:
+<ENTRY>config Making config<b></b>(1) aware of the new device
+ To make
+ config(1) aware of our new pseudo device we need to edit the file
+ in either <TT>/usr/src/sys/conf/files</TT> (for architecture
+ independent devices) or
+ <TT>/usr/src/sys/arch/<I>arch</I>/conf/files.<I>arch</I></TT> where
+ <I>arch</I> is the relevant architecture. This file tells config
+ what valid device names there are and which files are associated
+ with these devices. Firstly we look for the section that defines
+ the pseudo-devices. This section has lines that start with
+ <TT>defpseudo</TT>. Since we have decided that our driver is to be
+ an architecture specific one we edit the
+ <TT>/usr/src/sys/arch/i386/conf/files.i386</TT> file and once we
+ have found the correct section we can add a line like this:
<PRE>
defpseudo skeleton
</PRE>
- Which tells config(8) we have a pseudo-device called skeleton.
- Next we need to tell config(8) which files are associated with the
- skeleton pseudo-device. In this case we only have on file but a
+ Which tells config(1) we have a pseudo-device called skeleton.
+ Next we need to tell config(1) which files are associated with the
+ skeleton pseudo-device. In this case we only have one file but a
more complex pseudo-device may have more files, simply add each
file required on a line in the same manner. For our example we
only need one line that looks like this:
@@ -360,7 +370,7 @@
source tree (normally, <TT>/usr/src/sys</TT>). The
third field is the name of the driver that this file is associated
with, in our case this is skeleton - our sample pseudo-device. The
- fourth and last field is a control flag that tells config(8) to
+ fourth and last field is a control flag that tells config(1) to
write the skeleton.h include file. Note that here the file is called
skeleton.c, if we were using the example files here, we would have to
either rename pseudo_dev_skel.c to skeleton.c or change this entry.
@@ -368,7 +378,7 @@
be more suitable to call it skeleton.c.
<ENTRY>kernelconfig Adding the new device to the kernel config file
- Once config(8) has been told about the device, adding it to
+ Once config(1) has been told about the device, adding it to
the kernel config file is simple. To add our skeleton device we
add the line:
@@ -391,10 +401,10 @@
from it but, by convention, device nodes are created in
<I>/dev</I>. To make the device node you will need to use
mknod(8) to create a device node with the major number you
- noted in section 4.ii. In our case the mknod(8) command would look
+ noted in section 4.i. In our case the mknod(8) command would look
like this:
<PRE>
- mknod /dev/skel c 71 0
+ mknod /dev/skel c 140 0
</PRE>
Once this has been done you should be able to open your new device
and test it out. The file <A HREF="sample.c">sample.c</A> shows
@@ -429,7 +439,7 @@
<address>
<small>
<a href="http://www.NetBSD.org/cgi-bin/feedback.cgi">(Contact us)</a>
- $NetBSD: index.list,v 1.17 2006/02/23 17:18:02 kano Exp $<br>
+ $NetBSD: index.list,v 1.19 2006/12/29 03:41:31 kano Exp $<br>
<a href="../../../Misc/disclaimer.html">Copyright © 1994-2005
The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.</a><br>
<a href="../../../Misc/disclaimer.html">NetBSD<sup>®</sup> is a