================================== これは、 linux-2.6.13/Documentation/i2c/writing-clients の和訳（ドラフト） です。 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > 更新日 ： 2005/9/2 翻訳者 ： Hiroshi.Suzuki < setter at reset dot jp > 校正者 ： ================================== This is a small guide for those who want to write kernel drivers for I2C or SMBus devices. この小さい手引きは、I2C や、SMBus デバイス用のカーネルドライバを作りたい人たち のためのものです。 To set up a driver, you need to do several things. Some are optional, and some things can be done slightly or completely different. Use this as a guide, not as a rule book! ドライバを構築するには、いくつかやらなければならないことがあります。 いくつかは任意で、また、いくつかのものは、少し、またはまったく違うようにできます。 これは、手引きとして使ってください。ルールブック (規定書) としては使わないでください。 General remarks 全般的な注意事項 =============== Try to keep the kernel namespace as clean as possible. The best way to do this is to use a unique prefix for all global symbols. This is especially important for exported symbols, but it is a good idea to do it for non-exported symbols too. We will use the prefix `foo_' in this tutorial, and `FOO_' for preprocessor variables. カーネル名前空間をできるだけきれいに保つようにしてください。もっとも良い方法 は、すべてのグローバルシンボルの前に、他と重複しないような物をつけることです。 これは、エクスポートされたシンボルでは特に重要なことですが、エクスポートしない シンボルにつけるのも、お薦めです。この指導書では、'foo_' をシンボルの前に、 'FOO_' をプリプロセッサ変数の前につけます。 The driver structure ドライバ構造体 ==================== Usually, you will implement a single driver structure, and instantiate all clients from it. Remember, a driver structure contains general access routines, a client structure specific information like the actual I2C address. 通常、単一のドライバ構造体を実装し、そこからのクライアントすべてのインスタンス を作成するでしょう。ドライバ構造体が、一般的なアクセスルーチンを持つこと、クラ イアント構造体が、実際の I2C アドレスのような、固有情報であることを思い出してく ださい。 static struct i2c_driver foo_driver = { .owner = THIS_MODULE, .name = "Foo version 2.3 driver", .flags = I2C_DF_NOTIFY, .attach_adapter = &foo_attach_adapter, .detach_client = &foo_detach_client, .command = &foo_command /* may be NULL */ } The name can be chosen freely, and may be upto 40 characters long. Please use something descriptive here. name の内容は自由ですが、40文字以内に制限されるかもしれません。ここに、説明など を書いてください。 Don't worry about the flags field; just put I2C_DF_NOTIFY into it. This means that your driver will be notified when new adapters are found. This is almost always what you want. flags フィールドについては考える必要はありません; I2C_DF_NOTIFY とだけ書いてください。 これは、新しいアダプタが見つかったら、ドライバが通知するということです。 これは、ほとんどの場合、必要なことです。 All other fields are for call-back functions which will be explained below. 他のフィールドは、コールバック関数のためのもので、下で説明されます。 There use to be two additional fields in this structure, inc_use et dec_use, for module usage count, but these fields were obsoleted and removed. この構造体には、さらに2つのフィールド (モジュール処理回数用の inc_use と dec_use) がありましたが、それらフィールドは、古くなり、削除されました。 Extra client data 特別なクライアントデータ ================= The client structure has a special `data' field that can point to any structure at all. You can use this to keep client-specific data. You do not always need this, but especially for `sensors' drivers, it can be very useful. クライアント構造体は、常にどんな構造体も指し示せる、特別な 'data' フィールドを 持ちます。これは、クライアント固有のデータを保持するのに使えます。 必ずしも必要ではないですが、特に、'sensors' ドライバでは、非常に便利です。 An example structure is below. 次に、構造体の例を示します。 struct foo_data { struct semaphore lock; /* For ISA access in `sensors' drivers. */ int sysctl_id; /* To keep the /proc directory entry for `sensors' drivers. */ enum chips type; /* To keep the chips type for `sensors' drivers. */ /* Because the i2c bus is slow, it is often useful to cache the read information of a chip for some time (for example, 1 or 2 seconds). It depends of course on the device whether this is really worthwhile or even sensible. */ struct semaphore update_lock; /* When we are reading lots of information, another process should not update the below information */ char valid; /* != 0 if the following fields are valid. */ unsigned long last_updated; /* In jiffies */ /* Add the read information here too */ }; struct foo_data { struct semaphore lock; /* `sensors' ドライバの ISA アクセス用。 */ int sysctl_id; /* 'sensors' ドライバ用に、/proc ディレクトリの内容 を 保持する。 */ enum chips type; /* 'sensors' ドライバ用にチップの種類を保持する。 */ /* i2c バスは低速なので、時々 (例えば 1,2秒)、 チップの情報を読み込んで キャッシュしておくことは、とても便利です。 もちろん、これは、デバイスで、実際に必要か、とか、実用的かどうかにより ます。*/ struct semaphore update_lock; /* たくさんの情報を読み込んでいるとき、 他のプロセスは、次に示す情報を書換えては いけません。 */ char valid; /* != 0 続くフィールドが有効なら != 0 です*/ unsigned long last_updated; /* jiffies で */ /* 読み込み情報の追加もここで行います */ }; (訳者追記 : jiffies(jiffy) = Linux カーネルにおける時間の計測方法 http://www.kernelnewbies.org/glossary/#J 参照) Accessing the client クライアントへのアクセス ==================== Let's say we have a valid client structure. At some time, we will need to gather information from the client, or write new information to the client. How we will export this information to user-space is less important at this moment (perhaps we do not need to do this at all for some obscure clients). But we need generic reading and writing routines. 有効なクライアント構造体ができました。時々、クライアントからの情報を収集した り、クライアントに新しい情報を書き込んだりする必要があります。ユーザ空間にどの ように、情報を開示するかは、この時点では重要ではありません (たぶん、良くわから ないクライアントに対しては、常に不要です)。ですが、一般的な、読み書きルーチンを 必要とします。 I have found it useful to define foo_read and foo_write function for this. For some cases, it will be easier to call the i2c functions directly, but many chips have some kind of register-value idea that can easily be encapsulated. Also, some chips have both ISA and I2C interfaces, and it useful to abstract from this (only for `sensors' drivers). このために foo_read と、foo_write 関数を定義するのが良いとわかります。 時として、それは、i2c 機能を直接呼び出しやすくするかもしれませんが、 多くのチップが、ある種のレジスタ値を簡単にカプセル化する良い方法を持っています。 同様に、いくつかのチップは、ISA と I2C 両方のインタフェースを持っていて、 チップから (情報を) 取り出すのに使えます ('sensors' ドライバ専用)。 The below functions are simple examples, and should not be copied literally. 関数の簡単な例を次に示します。ですが、そのままコピーしてはいけません。 int foo_read_value(struct i2c_client *client, u8 reg) { if (reg < 0x10) /* byte-sized register */ /* バイトサイズのレジスタ */ return i2c_smbus_read_byte_data(client,reg); else /* word-sized register */ /* ワードサイズのレジスタ */ return i2c_smbus_read_word_data(client,reg); } int foo_write_value(struct i2c_client *client, u8 reg, u16 value) { if (reg == 0x10) /* Impossible to write - driver error! */ { /* 書き込みできない - ドライバエラー！ */ return -1; else if (reg < 0x10) /* byte-sized register */ /* バイトサイズのレジスタ */ return i2c_smbus_write_byte_data(client,reg,value); else /* word-sized register */ /* ワードサイズのレジスタ */ return i2c_smbus_write_word_data(client,reg,value); } For sensors code, you may have to cope with ISA registers too. Something like the below often works. Note the locking! sensors 用コード、ISA レジスタでもうまく動かせるかもしれません。 次に示すものも、通常動きます。ロックに注意してください！ int foo_read_value(struct i2c_client *client, u8 reg) { int res; if (i2c_is_isa_client(client)) { down(&(((struct foo_data *) (client->data)) -> lock)); outb_p(reg,client->addr + FOO_ADDR_REG_OFFSET); res = inb_p(client->addr + FOO_DATA_REG_OFFSET); up(&(((struct foo_data *) (client->data)) -> lock)); return res; } else return i2c_smbus_read_byte_data(client,reg); } Writing is done the same way. 同じ方法で書き込みもできます。 Probing and attaching 探査と接続 ===================== Most i2c devices can be present on several i2c addresses; for some this is determined in hardware (by soldering some chip pins to Vcc or Ground), for others this can be changed in software (by writing to specific client registers). Some devices are usually on a specific address, but not always; and some are even more tricky. So you will probably need to scan several i2c addresses for your clients, and do some sort of detection to see whether it is actually a device supported by your driver. ほとんどの i2c デバイスは、いくつかの i2c アドレス上に存在できます; アドレスは、ハードウェア的 (チップのいくつかのピンを、Vcc や グラウンドに半田付 して) に決まるか、ソフトウェアで (指定のクライアントレジスタに書き込み) 変更で きます。 いくつかのデバイスは、通常、特定のアドレスにありますが、常にではありません; いくつかのものは、さらに、扱い難くなっています。おそらく、クライアントのため に、さまざまな i2c アドレスの走査と、実際にドライバがサポートするデバイスか確認 するための、いくつかの検出作業をしなければならないでしょう。 To give the user a maximum of possibilities, some default module parameters are defined to help determine what addresses are scanned. Several macros are defined in i2c.h to help you support them, as well as a generic detection algorithm. ユーザに最大限の可能性を持たせるため、いくつかのモジュールパラメータの初期値を 設定し、どんなアドレスが走査されるかを決定する手助けをします。いくつかのマクロ が i2c.h で定義され、包括的な検出アルゴリズムと同様に、その手助けをします。 You do not have to use this parameter interface; but don't try to use function i2c_probe() (or i2c_detect()) if you don't. このパラメータインタフェースを使う必要はありませんが、使わないなら、i2c_probe() (または i2c_detect()) 関数を使おうとしてはいけません。 NOTE: If you want to write a `sensors' driver, the interface is slightly different! See below. 注記: `sensors' ドライバを作りたいなら、このインタフェースは少し異なっていま す。下述を見てください。 Probing classes (i2c) 探査クラス (i2c) --------------------- All parameters are given as lists of unsigned 16-bit integers. Lists are terminated by I2C_CLIENT_END. The following lists are used internally: すべてのパラメータは、符号無し16ビット整数の一覧で与えられます。一覧は、 I2C_CLIENT_END で終端されます。 次に示す一覧は、内部的に使われます。 normal_i2c: filled in by the module writer. A list of I2C addresses which should normally be examined. probe: insmod parameter. A list of pairs. The first value is a bus number (-1 for any I2C bus), the second is the address. These addresses are also probed, as if they were in the 'normal' list. ignore: insmod parameter. A list of pairs. The first value is a bus number (-1 for any I2C bus), the second is the I2C address. These addresses are never probed. This parameter overrules 'normal' and 'probe', but not the 'force' lists. force: insmod parameter. A list of pairs. The first value is a bus number (-1 for any I2C bus), the second is the I2C address. A device is blindly assumed to be on the given address, no probing is done. normal_i2c: モジュール作者によって埋められます。 通常、I2C アドレス一覧を調査しなければなりません。 probe: insmod パラメータ。 2個一組の一覧。最初の値は、バス番号 (-1 は、すべての I2C バス) で、2番目 は、I2C アドレスです。それらアドレスは 'normal' 一覧にあるものとして、探査 されます。 ignore: insmod パラメータ。 2個一組の一覧。最初の値は、バス番号 (-1 は、すべての I2C バス) で、2番目 は、I2C アドレスです。それらアドレスは探査されません。 このパラメータは 'normal' と 'probe' 一覧を却下します ('force' 一覧を除く)。 force: insmod パラメータ。 2個一組の一覧。最初の値は、バス番号 (-1 は、すべての I2C バス) で、2番目 は、I2C アドレスです。デバイスは、何も見ないで、与えられたアドレスにある と仮定されます。 探査は終わっていません。 Fortunately, as a module writer, you just have to define the `normal_i2c' parameter. The complete declaration could look like this: 幸運にも、モジュール作者として、単に、`normal_i2c' を定義することができます。 完全な宣言 (ソースコード) は、次のようになります。 /* Scan 0x37, and 0x48 to 0x4f */ /* 0x37 と 0x48 から 0x4f までを走査 */ static unsigned short normal_i2c[] = { 0x37, 0x48, 0x49, 0x4a, 0x4b, 0x4c, 0x4d, 0x4e, 0x4f, I2C_CLIENT_END }; /* Magic definition of all other variables and things */ /* 他の変数などの 魔法の定義 */ I2C_CLIENT_INSMOD; Note that you *have* to call the defined variable `normal_i2c', without any prefix! 定義された変数 'normal_i2c' を、頭に何もつけないで呼ばなければならないことに注 意してください！ Probing classes (sensors) クラス (sensors) を探査する ------------------------- If you write a `sensors' driver, you use a slightly different interface. As well as I2C addresses, we have to cope with ISA addresses. Also, we use a enum of chip types. Don't forget to include `sensors.h'. 'sensors' ドライバを作るなら、少し異なるインタフェースを使います。 I2C アドレスと同様に、ISA アドレスに対応しなければなりません。さらに、チップ種 類を列挙したものも使います。`sensors.h' を含める (#include) のを忘れないでくだ さい。 The following lists are used internally. They are all lists of integers. 次に示す一覧は内部的に使われます。すべて、整数の一覧です。 normal_i2c: filled in by the module writer. Terminated by SENSORS_I2C_END. A list of I2C addresses which should normally be examined. normal_isa: filled in by the module writer. Terminated by SENSORS_ISA_END. A list of ISA addresses which should normally be examined. probe: insmod parameter. Initialize this list with SENSORS_I2C_END values. A list of pairs. The first value is a bus number (SENSORS_ISA_BUS for the ISA bus, -1 for any I2C bus), the second is the address. These addresses are also probed, as if they were in the 'normal' list. ignore: insmod parameter. Initialize this list with SENSORS_I2C_END values. A list of pairs. The first value is a bus number (SENSORS_ISA_BUS for the ISA bus, -1 for any I2C bus), the second is the I2C address. These addresses are never probed. This parameter overrules 'normal' and 'probe', but not the 'force' lists. normal_i2c: モジュール作者によって埋められます。SENSORS_I2C_END で終端されます。 通常、I2C アドレス一覧を調査しなければなりません。 normal_isa: モジュール作者によって埋められます。SENSORS_ISA_END で終端されます。 通常、ISA アドレス一覧を調査しなければなりません。 probe: insmod パラメータ。SENSORS_I2C_END の値によってこの一覧を初期化します。 2個一組の一覧。最初の値は、バス番号 (ISA バスでは SENSORS_ISA_BUS、-1 ですべて の I2C バスになります) で、2番目はアドレスです。 それらアドレスも 'normal' 一覧にあるものとして、探査されます。 ignore: insmod パラメータ。SENSORS_I2C_END の値によってこの一覧を初期化します。 A2個一組の一覧。最初の値は、バス番号 (ISA バスでは SENSORS_ISA_BUS、-1 で すべての I2C バスになります) で、2番目は I2C アドレスです。 それらアドレスは探査されません。 このパラメータは 'normal' と 'probe' 一覧を却下します ('force' 一覧を除く)。 Also used is a list of pointers to sensors_force_data structures: force_data: insmod parameters. A list, ending with an element of which the force field is NULL. Each element contains the type of chip and a list of pairs. The first value is a bus number (SENSORS_ISA_BUS for the ISA bus, -1 for any I2C bus), the second is the address. These are automatically translated to insmod variables of the form force_foo. sensors_force_data 構造体へのポインタ一覧も使われます: force_data: insmod パラメータ。ひとつの一覧は、force フィールドが NULL に なっている要素で終わります。 それぞれの要素は、チップの種類と、2つ一組の一覧を含みます。 最初の値は、バス番号 (ISA バスでは SENSORS_ISA_BUS、-1 で、すべての I2C バス になります) で、2番目はアドレスです。 それらは、force_foo 形式の insmod 変数に自動的に変換されます。 So we have a generic insmod variabled `force', and chip-specific variables `force_CHIPNAME'. したがって、包括的な insmod 変数となった 'force' と、チップ独自の変数 `force_CHIPNAME' を持ちます。 Fortunately, as a module writer, you just have to define the `normal_i2c' and `normal_isa' parameters, and define what chip names are used. The complete declaration could look like this: 幸運にも、モジュール作者として、単に、`normal_i2c' と `normal_isa' パラメータ、 および、使うチップの名前を定義できます。 /* Scan i2c addresses 0x37, and 0x48 to 0x4f */ /* 0x37 と 0x48 から 0x4f までの i2c アドレスを走査 */ static unsigned short normal_i2c[] = { 0x37, 0x48, 0x49, 0x4a, 0x4b, 0x4c, 0x4d, 0x4e, 0x4f, I2C_CLIENT_END }; /* Scan ISA address 0x290 */ /* ISA アドレス 0x290 を走査*/ static unsigned int normal_isa[] = {0x0290,SENSORS_ISA_END}; /* Define chips foo and bar, as well as all module parameters and things */ /* チップ foo と bar をモジュールパラメータと同様に定義する */ SENSORS_INSMOD_2(foo,bar); If you have one chip, you use macro SENSORS_INSMOD_1(chip), if you have 2 you use macro SENSORS_INSMOD_2(chip1,chip2), etc. If you do not want to bother with chip types, you can use SENSORS_INSMOD_0. 単一のチップを使うなら、マクロ SENSORS_INSMOD_1(chip) を使います。2つなら、 マクロ SENSORS_INSMOD_2(chip1,chip2) を使います。その他にもあります。 チップの種類で手を煩わせたくないなら、SENSORS_INSMOD_0 が使えます。 A enum is automatically defined as follows: enum は、自動的に、次のように定義されます: enum chips { any_chip, chip1, chip2, ... } Attaching to an adapter 単一のアダプタに接続する ----------------------- Whenever a new adapter is inserted, or for all adapters if the driver is being registered, the callback attach_adapter() is called. Now is the time to determine what devices are present on the adapter, and to register a client for each of them. 新しいアダプタが挿入されるたびに、または、ドライバが登録されているならすべての ドライバのために、コールバック attach_adapter() が呼び出されます。そして、アダ プタに接続されているデバイスが何かが決定し、それぞれのデバイスのクライアントが 登録されます。 The attach_adapter callback is really easy: we just call the generic detection function. This function will scan the bus for us, using the information as defined in the lists explained above. If a device is detected at a specific address, another callback is called. attach_adapter コールバックは実に簡単です: 包括的検出関数を呼び出すだけです。 関数は、上述した一覧内に登録された情報を使い、バスを走査してくれるでしょう。 デバイスが、特定のアドレスで検出されたなら、他のコールバックが呼び出されます。 int foo_attach_adapter(struct i2c_adapter *adapter) { return i2c_probe(adapter,&addr_data,&foo_detect_client); } For `sensors' drivers, use the i2c_detect function instead: 'sensors' ドライバでは、代わりに、i2c_detect 関数が使われます: int foo_attach_adapter(struct i2c_adapter *adapter) { return i2c_detect(adapter,&addr_data,&foo_detect_client); } Remember, structure `addr_data' is defined by the macros explained above, so you do not have to define it yourself. `addr_data' 構造体は、上で述べたマクロにより定義されるので、あなたが定義する必 要はないことを思い出してください。 The i2c_probe or i2c_detect function will call the foo_detect_client function only for those i2c addresses that actually have a device on them (unless a `force' parameter was used). In addition, addresses that are already in use (by some other registered client) are skipped. i2c_probe や i2c_detect 関数は、実際にデバイスを持つ、それら i2c アドレスためだ けに、foo_detect_client 関数を呼び出すでしょう ('force' パラメータが使われない なら)。さらに、(他の登録されたクライアントにより) すでに使われているアドレス は、飛ばされます。 The detect client function クライアント検出関数 -------------------------- The detect client function is called by i2c_probe or i2c_detect. The `kind' parameter contains 0 if this call is due to a `force' parameter, and -1 otherwise (for i2c_detect, it contains 0 if this call is due to the generic `force' parameter, and the chip type number if it is due to a specific `force' parameter). クライアント検出関数は、i2c_probe や i2c_detect により、呼び出されます。 'force' で呼び出された場合、'kind' パラメータは 0 になり、それ以外では -1 にな ります (i2c_detect で、包括的 'force' パラメータで呼び出されると 0 になり、特定 の 'force' パラメータで呼び出されると、チップ種類番号になります)。 Below, some things are only needed if this is a `sensors' driver. Those parts are between /* SENSORS ONLY START */ and /* SENSORS ONLY END */ markers. 下に示すように、'sensors' ドライバなら、いくつかのものだけが必要です。 その部分は、/* SENSORS ONLY START */ と /* SENSORS ONLY END */ の間にあります。 This function should only return an error (any value != 0) if there is some reason why no more detection should be done anymore. If the detection just fails for this address, return 0. この関数は、検出作業をこれ以上行う必要がないなら、常にエラー (値は常に、!= 0) を返さなければいけません。このアドレスの検出が失敗したなら、0 を返します。 For now, you can ignore the `flags' parameter. It is there for future use. 今のところ、'flags' パラメータは無視できます。それは、将来使うためにあります。 int foo_detect_client(struct i2c_adapter *adapter, int address, unsigned short flags, int kind) { int err = 0; int i; struct i2c_client *new_client; struct foo_data *data; const char *client_name = ""; /* For non-`sensors' drivers, put the real name here! */ /* 'sensors' 以外のドライバ用、ここに実際の名前を 書きます！ */ /* Let's see whether this adapter can support what we need. Please substitute the things you need here! For `sensors' drivers, add `! is_isa &&' to the if statement */ /* アダプタが必要な機能をサポートできるかを見ましょう。 ここを必要なものに置き換えてください！ `sensors' ドライバでは、`! is_isa &&' を if ステートメントに追加します。*/ if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA | I2C_FUNC_SMBUS_WRITE_BYTE)) goto ERROR0; /* SENSORS ONLY START */ const char *type_name = ""; int is_isa = i2c_is_isa_adapter(adapter); if (is_isa) { /* If this client can't be on the ISA bus at all, we can stop now (call `goto ERROR0'). But for kicks, we will assume it is all right. */ /* このクライアントが、常に ISA バス上に存在できないなら、止めることがで きます( 'goto ERROR0' を呼び出す )。物言いがなければ、それを良しと考え るでしょう。 */ /* Discard immediately if this ISA range is already used */ /* ISA 範囲がすでに使われているなら、ただちに破棄します */ if (check_region(address,FOO_EXTENT)) goto ERROR0; /* Probe whether there is anything on this address. Some example code is below, but you will have to adapt this for your own driver */ /* このアドレス上に何かないかを探査します。 コードの例を下に示しますが、あなたのドライバにあわせる必要があるでしょう。*/ if (kind < 0) /* Only if no force parameter was used */ { /* force パラメータが使われないときのみ */ /* We may need long timeouts at least for some chips. */ /* いくつかのチップで長い待ち時間を必要とするかもしれません。*/ #define REALLY_SLOW_IO i = inb_p(address + 1); if (inb_p(address + 2) != i) goto ERROR0; if (inb_p(address + 3) != i) goto ERROR0; if (inb_p(address + 7) != i) goto ERROR0; #undef REALLY_SLOW_IO /* Let's just hope nothing breaks here */ /* ここで何も壊れないことを期待しましょう */ i = inb_p(address + 5) & 0x7f; outb_p(~i & 0x7f,address+5); if ((inb_p(address + 5) & 0x7f) != (~i & 0x7f)) { outb_p(i,address+5); return 0; } } } /* SENSORS ONLY END */ /* OK. For now, we presume we have a valid client. We now create the client structure, even though we cannot fill it completely yet. But it allows us to access several i2c functions safely */ /* OK。今のところ、有効なクライアントがあると思われます。完全に中身を埋める ことができなくても、client 構造体を作ります。それにより、安全に、いくつ かの i2c 関数にアクセスできるようになります */ /* Note that we reserve some space for foo_data too. If you don't need it, remove it. We do it here to help to lessen memory fragmentation. */ /* foo_data のためにもいくらかの空間を予約することに注意してください。必要 ないなら、削除してください。メモリのフラグメントを減らすのを手助けするた め、ここで、それを行います。 */ if (! (new_client = kmalloc(sizeof(struct i2c_client) + sizeof(struct foo_data), GFP_KERNEL))) { err = -ENOMEM; goto ERROR0; } /* This is tricky, but it will set the data to the right value. */ /* これは扱い難いですが、データを正しい値にするでしょう。*/ client->data = new_client + 1; data = (struct foo_data *) (client->data); new_client->addr = address; new_client->data = data; new_client->adapter = adapter; new_client->driver = &foo_driver; new_client->flags = 0; /* Now, we do the remaining detection. If no `force' parameter is used. */ /* 検出を続けます。'force' パラメータが使われないなら。 */ /* First, the generic detection (if any), that is skipped if any force parameter was used. */ /* はじめに、'force' パラメータが使われると、包括的検出 (もしあれば) は、 飛ばされます。*/ if (kind < 0) { /* The below is of course bogus */ /* 下に示すものは、もちろん偽りです。*/ if (foo_read(new_client,FOO_REG_GENERIC) != FOO_GENERIC_VALUE) goto ERROR1; } /* SENSORS ONLY START */ /* Next, specific detection. This is especially important for `sensors' devices. */ /* 次に、詳細検出。これは、'sensors' デバイスで特に重要です。*/ /* Determine the chip type. Not needed if a `force_CHIPTYPE' parameter was used. */ /* チップの種類を確定します。`force_CHIPTYPE' が使われるなら不要です。*/ if (kind <= 0) { i = foo_read(new_client,FOO_REG_CHIPTYPE); if (i == FOO_TYPE_1) kind = chip1; /* As defined in the enum */ /* enum 内で定義されたもの */ else if (i == FOO_TYPE_2) kind = chip2; else { printk("foo: Ignoring 'force' parameter for unknown chip at " "adapter %d, address 0x%02x\n",i2c_adapter_id(adapter),address); goto ERROR1; } } /* Now set the type and chip names */ /* 種類とチップ名を設定します */ if (kind == chip1) { type_name = "chip1"; /* For /proc entry */ client_name = "CHIP 1"; } else if (kind == chip2) { type_name = "chip2"; /* For /proc entry */ client_name = "CHIP 2"; } /* Reserve the ISA region */ /* ISA 領域を予約 */ if (is_isa) request_region(address,FOO_EXTENT,type_name); /* SENSORS ONLY END */ /* Fill in the remaining client fields. */ /* 留まっているクライアントフィールドを埋める。*/ strcpy(new_client->name,client_name); /* SENSORS ONLY BEGIN */ data->type = kind; /* SENSORS ONLY END */ data->valid = 0; /* Only if you use this field */ /* このフィールドを使うときだけ */ init_MUTEX(&data->update_lock); /* Only if you use this field */ /* このフィールドを使うときだけ */ /* Any other initializations in data must be done here too. */ /* 他のデータ初期化もここで行わなければいけません。*/ /* Tell the i2c layer a new client has arrived */ /* 新しいクライアントが現れたことを、i2c 階層に教えます */ if ((err = i2c_attach_client(new_client))) goto ERROR3; /* SENSORS ONLY BEGIN */ /* Register a new directory entry with module sensors. See below for the `template' structure. */ /* sensors モジュールの新しいディレクトリエントリを登録します。 'template' 構造体は、下述を見てください。*/ if ((i = i2c_register_entry(new_client, type_name, foo_dir_table_template,THIS_MODULE)) < 0) { err = i; goto ERROR4; } data->sysctl_id = i; /* SENSORS ONLY END */ /* This function can write default values to the client registers, if needed. */ /* この関数は、必要なら、クライアントレジスタに初期値を書き込みます。*/ foo_init_client(new_client); return 0; /* OK, this is not exactly good programming practice, usually. But it is very code-efficient in this case. */ /* OK、これは、通常、真に良いプログラミングの練習ではありません。しかし、 この場合では、とても能率的なコードです。*/ ERROR4: i2c_detach_client(new_client); ERROR3: ERROR2: /* SENSORS ONLY START */ if (is_isa) release_region(address,FOO_EXTENT); /* SENSORS ONLY END */ ERROR1: kfree(new_client); ERROR0: return err; } Removing the client クライアントの削除 =================== The detach_client call back function is called when a client should be removed. It may actually fail, but only when panicking. This code is much simpler than the attachment code, fortunately! detach_client コールバック関数は、クライアントを削除しなければならないときに呼 び出されます。実際には失敗するかもしれませんが、パニックするときだけです。 このコードは、幸運にも付属コードよりはるかに単純です！ int foo_detach_client(struct i2c_client *client) { int err,i; /* SENSORS ONLY START */ /* Deregister with the `i2c-proc' module. */ /* `i2c-proc' モジュールで、登録を解除します。*/ i2c_deregister_entry(((struct lm78_data *)(client->data))->sysctl_id); /* SENSORS ONLY END */ /* Try to detach the client from i2c space */ /* i2c 空間からクライアントを外そうと試みます */ if ((err = i2c_detach_client(client))) { printk("foo.o: Client deregistration failed, client not detached.\n"); return err; } /* SENSORS ONLY START */ if i2c_is_isa_client(client) release_region(client->addr,LM78_EXTENT); /* SENSORS ONLY END */ kfree(client); /* Frees client data too, if allocated at the same time */ /* 同時に割り当てられたなら、クライアントデータも開放します */ return 0; } Initializing the module or kernel モジュールまたはカーネルを初期化する。 ================================= When the kernel is booted, or when your foo driver module is inserted, you have to do some initializing. Fortunately, just attaching (registering) the driver module is usually enough. カーネルが起動したら、または、あなたの foo ドライバモジュールが組み込まれたら、 いくつかの初期化をしなければなりません。幸運にも、通常、ドライバモジュールを 接続 (登録) するだけで十分です。 /* Keep track of how far we got in the initialization process. If several things have to initialized, and we fail halfway, only those things have to be cleaned up! */ /* 初期化処理がどこまで進んだか追跡してください。いくつかの物が初期化され、 途中で失敗したとき、それらだけを掃除すれば済みます！ */ static int __initdata foo_initialized = 0; static int __init foo_init(void) { int res; printk("foo version %s (%s)\n",FOO_VERSION,FOO_DATE); if ((res = i2c_add_driver(&foo_driver))) { printk("foo: Driver registration failed, module not inserted.\n"); foo_cleanup(); return res; } foo_initialized ++; return 0; } void foo_cleanup(void) { if (foo_initialized == 1) { if ((res = i2c_del_driver(&foo_driver))) { printk("foo: Driver registration failed, module not removed.\n"); return; } foo_initialized --; } } /* Substitute your own name and email address */ /* あなたの名前と email アドレスに置き換えてください */ MODULE_AUTHOR("Frodo Looijaard " MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); module_init(foo_init); module_exit(foo_cleanup); Note that some functions are marked by `__init', and some data structures by `__init_data'. Hose functions and structures can be removed after kernel booting (or module loading) is completed. いくつかの関数は、`__init' で、いくつかの データ構造体は、`__init_data'で区別さ れることに注意してください。それら関数と構造体はカーネルの起動 (または、モジュ ールのロード) が完了した後で削除できます。 Command function command 関数 ================ A generic ioctl-like function call back is supported. You will seldom need this. You may even set it to NULL. 包括的な ioctl 類似の関数コールバックがサポートされます。まれに、必要になるかも しれません。さらに、それを NULL にすることができます。 /* No commands defined */ /* コマンドは定義されていません */ int foo_command(struct i2c_client *client, unsigned int cmd, void *arg) { return 0; } Sending and receiving 送信と受信 ===================== If you want to communicate with your device, there are several functions to do this. You can find all of them in i2c.h. デバイスと通信したいなら、それを行ういくつかの関数があります。 すべては、i2c.h にあります。 If you can choose between plain i2c communication and SMBus level communication, please use the last. All adapters understand SMBus level commands, but only some of them understand plain i2c! 素の i2c 通信と、SMBus 水準の通信を選択できるなら、後者を選択してください。 すべてのアダプタは、SMBus 水準のコマンドを理解しますが、いくつかの物だけしか、 素の i2c を理解できません！ Plain i2c communication 素の i2c 通信 ----------------------- extern int i2c_master_send(struct i2c_client *,const char* ,int); extern int i2c_master_recv(struct i2c_client *,char* ,int); These routines read and write some bytes from/to a client. The client contains the i2c address, so you do not have to include it. The second parameter contains the bytes the read/write, the third the length of the buffer. Returned is the actual number of bytes read/written. これらルーチンは、クライアントへ、いくつかのバイトを読み書きします。クライアン トが i2c アドレスを持っているので、それを含む必要はありません。2番目のパラメー タは、読み書きするバイトを格納します。3番目のパラメータは、バッファ長です。戻り 値は、実際に読み書きされたバイト数です。 extern int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, int num); This sends a series of messages. Each message can be a read or write, and they can be mixed in any way. The transactions are combined: no stop bit is sent between transaction. The i2c_msg structure contains for each message the client address, the number of bytes of the message and the message data itself. これは、一連のメッセージを送ります。それぞれのメッセージは読み書きでき、また、 任意の方法で、混合できます。処理が連続するなら: 処理間で停止ビットは送られませ ん。i2c_msg 構造体は、各メッセージのために、クライアントアドレス, メッセージの バイト数, 自身のメッセージデータを格納します。 You can read the file `i2c-protocol' for more information about the actual i2c protocol. 実際の i2c プロトコルの詳細は、`i2c-protocol' を見てください。 SMBus communication SMBus 通信 ------------------- extern s32 i2c_smbus_xfer (struct i2c_adapter * adapter, u16 addr, unsigned short flags, char read_write, u8 command, int size, union i2c_smbus_data * data); This is the generic SMBus function. All functions below are implemented in terms of it. Never use this function directly! これは、包括的 SMBus 関数です。次に示す関数は、その関連性で、実装されています。 この関数を直接使わないでください！ extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value); extern s32 i2c_smbus_read_byte(struct i2c_client * client); extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value); extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command); extern s32 i2c_smbus_write_byte_data(struct i2c_client * client, u8 command, u8 value); extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command); extern s32 i2c_smbus_write_word_data(struct i2c_client * client, u8 command, u16 value); extern s32 i2c_smbus_write_block_data(struct i2c_client * client, u8 command, u8 length, u8 *values); These ones were removed in Linux 2.6.10 because they had no users, but could be added back later if needed: これらのものは、ユーザがいないので、Linux 2.6.10 で削除されました。しかし、必要 になれば、後でまた追加されます。 extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client, u8 command, u8 *values); extern s32 i2c_smbus_read_block_data(struct i2c_client * client, u8 command, u8 *values); extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client, u8 command, u8 length, u8 *values); extern s32 i2c_smbus_process_call(struct i2c_client * client, u8 command, u16 value); extern s32 i2c_smbus_block_process_call(struct i2c_client *client, u8 command, u8 length, u8 *values) All these transactions return -1 on failure. The 'write' transactions return 0 on success; the 'read' transactions return the read value, except for read_block, which returns the number of values read. The block buffers need not be longer than 32 bytes. これら処理は、すべて、失敗したときに -1 を返します。'write' 処理は、成功時に 0 を返し、'read' 処理は、read_block を除き、読み込んだ値を返します。read_block は、読み込んだ値の数を返します。ブロックバッファは、32バイトより多くはいりません。 You can read the file `smbus-protocol' for more information about the actual SMBus protocol. 実際の SMBus プロトコルの詳細は、`smbus-protocol' を見てください。 General purpose routines 汎用ルーチン ======================== Below all general purpose routines are listed, that were not mentioned before. 以下にすべての汎用ルーチンの一覧を示します。これについてはまだ述べられていません。 /* This call returns a unique low identifier for each registered adapter, * or -1 if the adapter was not registered. */ /* この呼び出しは、登録されたアダプタそれぞれに、唯一のもっとも低い値の識別子 * を返し、また、アダプターが登録されなかった場合、-1 を返します。 */ extern int i2c_adapter_id(struct i2c_adapter *adap); The sensors sysctl/proc interface sensors sysctl/proc インタフェース ================================= This section only applies if you write `sensors' drivers. 本節は、`sensors' ドライバを作る場合にのみ適用されます。 Each sensors driver creates a directory in /proc/sys/dev/sensors for each registered client. The directory is called something like foo-i2c-4-65. The sensors module helps you to do this as easily as possible. それぞれの sensors ドライバは、登録されたクライアントそれぞれのためのディレクト リを、/proc/sys/dev/sensors 以下に作成します。ディレクトリは、foo-i2c-4-65 のよ うになります。sensors モジュールは、これを簡単にできるようにする手助けをします。 The template テンプレート (定型書式) ------------ You will need to define a ctl_table template. This template will automatically be copied to a newly allocated structure and filled in where necessary when you call sensors_register_entry. ctl_table テンプレートを定義する必要があるでしょう。テンプレートは、 sensors_register_entry を呼び出すとき、自動的にコピーされ、新しく割り当てられた 構造体の必要な場所に埋め込まれます。 First, I will give an example definition. はじめに、定義例を示しましょう。 static ctl_table foo_dir_table_template[] = { { FOO_SYSCTL_FUNC1, "func1", NULL, 0, 0644, NULL, &i2c_proc_real, &i2c_sysctl_real,NULL,&foo_func }, { FOO_SYSCTL_FUNC2, "func2", NULL, 0, 0644, NULL, &i2c_proc_real, &i2c_sysctl_real,NULL,&foo_func }, { FOO_SYSCTL_DATA, "data", NULL, 0, 0644, NULL, &i2c_proc_real, &i2c_sysctl_real,NULL,&foo_data }, { 0 } }; In the above example, three entries are defined. They can either be accessed through the /proc interface, in the /proc/sys/dev/sensors/* directories, as files named func1, func2 and data, or alternatively through the sysctl interface, in the appropriate table, with identifiers FOO_SYSCTL_FUNC1, FOO_SYSCTL_FUNC2 and FOO_SYSCTL_DATA. 上の例で、3つのエントリが定義されます。それらは、次に示すどちらかでアクセスでき ます。ひとつは、/proc インタフェース経由、もうひとつは、/proc/sys/dev/sensors/* ディレクトリ内の ファイル名 func1, func2, data として、または、代わりに、 FOO_SYSCTL_FUNC1, FOO_SYSCTL_FUNC2, FOO_SYSCTL_DATA 識別子を持つ適当な表中の sysctl インタフェース経由です。 The third, sixth and ninth parameters should always be NULL, and the fourth should always be 0. The fifth is the mode of the /proc file; 0644 is safe, as the file will be owned by root:root. 3番目と 6番目と 9番目のパラメータは常に NULL でなければならず、4番目は、常に 0 でなければなりません。5番目は、/proc ファイルのモードで、ファイルは、root:root に所有され、モードは 0644 が安全です。 The seventh and eighth parameters should be &i2c_proc_real and &i2c_sysctl_real if you want to export lists of reals (scaled integers). You can also use your own function for them, as usual. Finally, the last parameter is the call-back to gather the data (see below) if you use the *_proc_real functions. 7番目と 8番目のパラメータは、real (整数の定数) の 一覧を開示したいなら、 &i2c_proc_real と &i2c_sysctl_real にしなければなりません。 通常、そのためにあなたの関数も使えます。 最後に、最後のパラメータは、*_proc_real 関数を使うなら、データを収集するための コールバックです。 Gathering the data データを収集する ------------------ The call back functions (foo_func and foo_data in the above example) can be called in several ways; the operation parameter determines what should be done: コールバック関数 (上述の例の foo_func と foo_data) は、いくつかの方法で呼び出す ことができます; 処理パラメータは、何が行われるかを決定します。 * If operation == SENSORS_PROC_REAL_INFO, you must return the magnitude (scaling) in nrels_mag; * If operation == SENSORS_PROC_REAL_READ, you must read information from the chip and return it in results. The number of integers to display should be put in nrels_mag; * If operation == SENSORS_PROC_REAL_WRITE, you must write the supplied information to the chip. nrels_mag will contain the number of integers, results the integers themselves. * operation == SENSORS_PROC_REAL_INFO なら、nrels_mag に、倍率 (縮尺) を返さ なければなりません; * operation == SENSORS_PROC_REAL_READ なら、チップから情報を読み込み、results に返さなければなりません。表示する整数の数は nrels_mag に格納しなければなり ません; * operation == SENSORS_PROC_REAL_WRITE なら、提供された情報をチップに書き込ま なければなりません。nrels_mag は、整数の数を格納し、resolts は、それ自身の 整数になるでしょう。 The *_proc_real functions will display the elements as reals for the /proc interface. If you set the magnitude to 2, and supply 345 for SENSORS_PROC_REAL_READ, it would display 3.45; and if the user would write 45.6 to the /proc file, it would be returned as 4560 for SENSORS_PROC_REAL_WRITE. A magnitude may even be negative! *_proc_real 関数は、/proc インタフェースのために、reals として、要素を表示する でしょう。magnitude を 2 に設定し、345 を SENSORS_PROC_REAL_READ に提供するな ら、3.45 を表示します; また、ユーザが、/proc ファイルに 45.6 を書き込むなら、 SENSORS_PROC_REAL_WRITE で、4560 が返されます。magnitude は、負の数かもしれません！ An example function: 関数の例: /* FOO_FROM_REG and FOO_TO_REG translate between scaled values and register values. Note the use of the read cache. */ /* FOO_FROM_REG と FOO_TO_REG は、レジスタ値と縮尺値の間を変換します。 読み込みキャッシュの仕様に注意してください。*/ void foo_in(struct i2c_client *client, int operation, int ctl_name, int *nrels_mag, long *results) { struct foo_data *data = client->data; int nr = ctl_name - FOO_SYSCTL_FUNC1; /* reduce to 0 upwards */ /* 0 まで減算されます */ if (operation == SENSORS_PROC_REAL_INFO) *nrels_mag = 2; else if (operation == SENSORS_PROC_REAL_READ) { /* Update the readings cache (if necessary) */ /* 読み込みキャッシュを更新する (必要なら) */ foo_update_client(client); /* Get the readings from the cache */ /* キャッシュから読み込み値を得る */ results[0] = FOO_FROM_REG(data->foo_func_base[nr]); results[1] = FOO_FROM_REG(data->foo_func_more[nr]); results[2] = FOO_FROM_REG(data->foo_func_readonly[nr]); *nrels_mag = 2; } else if (operation == SENSORS_PROC_REAL_WRITE) { if (*nrels_mag >= 1) { /* Update the cache */ /* キャッシュを更新する */ data->foo_base[nr] = FOO_TO_REG(results[0]); /* Update the chip */ /* チップを更新する */ foo_write_value(client,FOO_REG_FUNC_BASE(nr),data->foo_base[nr]); } if (*nrels_mag >= 2) { /* Update the cache */ /* キャッシュを更新する */ data->foo_more[nr] = FOO_TO_REG(results[1]); /* Update the chip */ /* チップを更新する */ foo_write_value(client,FOO_REG_FUNC_MORE(nr),data->foo_more[nr]); } } }