HelloWorld

Hello World †

ほぼ何もしない "Hello World" プログラムを作って Linux kernel に組み込む単純なモジュールの作り方を見ていきます。まだ、デバイスドライバには遠いです。

ソースコード †

添付ファイル に一式をまとめておきます。C 言語で実行部を、Makefile で構築手順を書きます。Makefile を書かずにコンパイルできるかというと、自分では試したことがないです。煩雑なコマンドライン操作をした割には利点は殆ど無いでしょう。

実行部 †

hello_world.c

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

- | | | ! - | ! - | | ! - !

#include <linux/kernel.h> #include <linux/module.h> /* * Tutorial hello world module init. * @return int == 0: Success. * < 0: Fail, negative errno number. */ static int __init hello_world_init(void) { printk(KERN_INFO "%s: Hello world.\n", __func__); return 0; } /* * Tutorial hello world module exit. * @return void */ static void __exit hello_world_exit(void) { printk(KERN_INFO "%s: Goodbye world.\n", __func__); } module_init(hello_world_init); module_exit(hello_world_exit); MODULE_LICENSE("GPL"); MODULE_DESCRIPTION("Tutorial hello world."); MODULE_AUTHOR("Your name or email address.");

Makefile †

Makefile

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25

# Build Tutorial hello world module.
# To try this tutorial.
# make
# sudo insmod hello_world.ko
# dmesg
# lsmod
# sudo rmmod hello_world.ko
# dmesg
# lsmod
 
KERNEL_SOURCE_TREE:=/lib/modules/$(shell uname -r)/build
PWD:=$(shell pwd)
 
# specify object.
obj-m:=hello_world.o
 
.PHONY: modules clean # install
modules:
        make -C $(KERNEL_SOURCE_TREE) M=$(PWD) modules
 
clean:
        make -C $(KERNEL_SOURCE_TREE) M=$(PWD) clean
 
#install:
#       make -C $(KERNEL_SOURCE_TREE) M=$(PWD) install

hello_world.c が user space アプリケーションと違うところ †

C 言語で Linux application の hello world プログラムを書いた場合と違うところを見て行きます。おそらく「知っている」C 言語のプログラムと違う点は「これで動くのだろうか？」と思えてくるでしょう。

module_init, module_exit †

main() はありません。モジュールが kernel に組み込まれる時 module_init() で指定した関数を実行します。モジュールが kernel から外されるとき module_exit() で指定した関数を実行します。

OpenGrok(linux-4.1.27/include/linux/init.h:296)

296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316

- | | | | | | ! - | | | | | | | | !

/** * module_init() - driver initialization entry point * @x: function to be run at kernel boot time or module insertion * * module_init() will either be called during do_initcalls() (if * builtin) or at module insertion time (if a module). There can only * be one per module. */ #define module_init(x) __initcall(x); /** * module_exit() - driver exit entry point * @x: function to be run when driver is removed * * module_exit() will wrap the driver clean-up code * with cleanup_module() when used with rmmod when * the driver is a module. If the driver is statically * compiled into the kernel, module_exit() has no effect. * There can only be one per module. */ #define module_exit(x) __exitcall(x);

モジュールが「組み込まれた」、「外された」時に呼ばれる仕掛けを作ることができるのは分りました。しかし、デバイス・ドライバを構成するにはまだ足りません。「ハードウエアにドライバが対応するデバイスが追加されたら」、あるいは、「モジュールが組み込まれた時点で既にドライバが対応するハードウエアが存在したら」、呼び出される様な仕掛けをまだ作っていません。i8253 PIT をアクセスするデバイスドライバで probe, remove と呼ばれるデバイスとドライバを関係づける「メソッドのような関数」を見ていきます。

__init, __exit †

関数に __init と __exit 修飾子がついています。 include/linux/init.h を読んでみると、広域変数に対して似たようなマクロ定義があることが判ります。__init と __exit 修飾子の目的は 次のようになります。

• __init: モジュールをロードするときだけ呼び出す関数を修飾します。より厳密に言えば module_init() で指定した関数から呼び出し関係を辿れて、辿った経路以外からの呼び出しが無い関数を修飾します。__init が付いた関数はモジュール・ロード(組み込み)が終了し module_init() からの呼び出しが完了した時点でメモリから削除されます。
• __exit: モジュールをアンロードする時だけ呼び出す関数を修飾します。より厳密に言えば module_exit() で指定した関数から呼び出し関係を辿れて、辿った経路以外からの呼び出しが無い関数を修飾します。(このページでは取り上げないのですが)モジュールを kernel に静的に結合した場合、モジュール・アンロードは起きません。__exit を付けた関数は kernel のオブジェクトコードから除去されます。

__init と __exit は kernel のメモリ使用量をなるべく減らすために使われる修飾子です。

OpenGrok(linux-4.1.27/include/linux/init.h:42)

42 43 44

#define __init __section(.init.text) __cold notrace #define __initdata __section(.init.data) #define __initconst __constsection(.init.rodata)

OpenGrok(linux-4.1.27/include/linux/init.h:92)

92

#define __exit __section(.exit.text) __exitused __cold notrace

printk †

printk は printf に相当する関数です。デバッグをするのに非常に有用な関数です。書式文字列を指定して書式文字列に続く引数の内容を表示します。書式文字列は printf とよく似ています。興味深く注意が必要な拡張は %p とその派生書式です。ここでは printk のヘッダファイル読み込みに linux/kernel.h を使用しました。もちろん、linux/printk.h を直接インクルードするのも良いでしょう。

KERN_INFO †

KERN_INFO は kernel message の表示レベルを意味します。include/linux/kern_levels.h には次のレベルが定義されています。おそらく普通に使うのは KERN_ERR より大きい Level 番号のメッセージでしょう。下の表の alternate function pr_xxx は printk に KERN_XXX マクロを組み合わせて定義したマクロです。デバイス・ドライバ向けに dev_xxx 関数も用意されています。dev_xxx はデバイスの場所や関連するコンテキストが格納された struct device を指すポインタを引数に渡します。

/proc/sys/kernel/printk リンク先の printk 節を参照 にログレベルを書き込むことで console と ログファイル(厳密にはログ出力ノード /proc/kmsg (/proc/kmsg を実装している fs/proc/kmsg.c) に出力するレベルを制御できます。説明の中で順位に "Higher" とあるのは上記表 Level においてより小さい値です。

別のページで各種のデバッグ手法について集中的に説明する予定です。

MODULE_LICENSE †

MODULE_LICENSE はモジュールのライセンスを指定します。このライセンスは シンボルの結合規則に関係しています。モジュールが結合可能な kernel symbol は EXPORT_SYMBOL または EXPORT_SYMBOL_GPL によって kernel から export されています。MODULE_LICENSE マクロの引数に指定する license 文字列と結合可能なシンボルは次の通りです。

ライセンスの宣言通り、ソースコードを配布できるようにする必要が有ります。

モジュールのソースを公開したくなければ "Proprietary" を指定します。このようにすると、結合可能なシンボルは限られます。開発段階で "GPL"を指定し、リリース直前に "Proprietary" を指定すると結合できないシンボルが出てきて、実装し直しあるいはライセンス変更と言った混乱が発生します。

MODULE_DESCRIPTION, MODULE_AUTHOR †

MODULE_DESCRIPTION, MODULE_AUTHOR はそれぞれモジュールの説明、モジュールの作者を設定します。 MODULE_AUTHOR は、フルネーム、メールアドレス、会社名などを入れます。ソース・コードに現れる例を参考に設定して下さい。これらの設定はモジュールの動作に影響を与えません。設定内容は次のコマンドで確かめることができます。

$  /sbin/modinfo module_name_or_module_path

Makefile †

module を構築するための Makefile の書き方 modules.txt に詳細が書かれています。ここでは、1 個のソース・ファイルから構築しているのでより簡単な Makefile にしました。Linux kernel のソース・コードからバイナリを構築する Makefile の仕組みの上でビルドします。make の -C オプションでディレクトリを Linux kernel のソース・コード・ツリーに移して M マクロにビルドするディレクトリのパスを設定します。

Linux kernel に動的に組み込むモジュールとして作成する †

添付ファイルを展開したディレクトリに移って、make します。

$ cd extracted_directory_base/hello_world
$ make

特に驚くような警告やエラーは出ないはずです。最終的なターゲットは hello_world.ko です。Linux ドライバを提供しているハードウエアの中には、すべて Makefile で書くのではなく、shell script で make を呼び出すものもあります。shell scripit の中で次の様なコマンドラインを実行する様に書かれています。

make -C /lib/modules/4.1.27-local/build M=/home/furuta/git/lkdq1stmodule modules

Linux kernel に組み込む †

make コマンドに続けて次のようにしてモジュールを組み込みます。何か起きましたか？

$ sudo insmod hello_world.ko
[sudo] password for user_name:password

何も起きない？ dmesg で確かめよう †

コンソールには insmod コマンドに反応した表示は何も出ないはずです(組み込み Linux 環境ならば kernel message がコンソールに流れるように設定されている場合もあります)。プログラムに書かれた "Hello world." が出力されたのかは dmesg コマンドで確かめることができます。

$ dmesg
...省略...
[  910.921955] hello_world: module verification failed: signature and/or required key missing - tainting kernel
[  910.921955] hello_world_init: Hello world.

左側に表れている数値は printk timestamp または printk time と呼ばれているものです。正式な名称は Documentation、ソース・コードの中に書かれていないようです。nano second 単位の local_clock() 関数から得ている時刻です。

OpenGrok(linux-4.1.27/kernel/printk/printk.c:1000)

1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014

- | | | | | | | | | | | | !

static size_t print_time(u64 ts, char *buf) { unsigned long rem_nsec; if (!printk_time) return 0; rem_nsec = do_div(ts, 1000000000); if (!buf) return snprintf(NULL, 0, "[%5lu.000000] ", (unsigned long)ts); return sprintf(buf, "[%5lu.%06lu] ", (unsigned long)ts, rem_nsec / 1000); }

Linux kernel に組み込まれたことを確認する †

モジュールが kernel に組み込まれていることを lsmod コマンドで確認します。下線を付けて示した行が見つかると思います。

$ lsmod
Module                  Size  Used by
hello_world            16384  0
rfcomm                 69632  0
bnep                   24576  2
bluetooth             516096  10 bnep,rfcomm
nfsd                  299008  13
autofs4                40960  4
auth_rpcgss            61440  1 nfsd
nfs_acl                16384  1 nfsd
nfs                   249856  0
lockd                  94208  2 nfs,nfsd
grace                  16384  2 nfsd,lockd
sunrpc                327680  19 nfs,nfsd,auth_rpcgss,lockd,nfs_acl
fscache                65536  1 nfs
snd_intel8x0           40960  2
snd_ac97_codec        135168  1 snd_intel8x0
ac97_bus               16384  1 snd_ac97_codec
snd_pcm               106496  2 snd_ac97_codec,snd_intel8x0
snd_seq_midi           16384  0
snd_seq_midi_event     16384  1 snd_seq_midi
snd_rawmidi            32768  1 snd_seq_midi
snd_seq                69632  2 snd_seq_midi_event,snd_seq_midi
joydev                 20480  0
snd_seq_device         16384  3 snd_seq,snd_rawmidi,snd_seq_midi
snd_timer              32768  2 snd_pcm,snd_seq
snd                    86016  11 snd_ac97_codec,snd_intel8x0,snd_timer,snd_pcm,snd_seq,snd_rawmidi,snd_seq_device
serio_raw              16384  0
soundcore              16384  1 snd
8250_fintek            16384  0
i2c_piix4              24576  0
mac_hid                16384  0
parport_pc             32768  0
ppdev                  20480  0
lp                     20480  0
parport                45056  3 lp,ppdev,parport_pc
hid_generic            16384  0
usbhid                 53248  0
hid                   118784  2 hid_generic,usbhid
psmouse               122880  0
ahci                   36864  5
libahci                32768  1 ahci
e1000                 139264  0
pata_acpi              16384  0

Linux kernel から外す †

rmmod コマンドでモジュールをアンロードしない限り、Linux kernel 内にモジュールは留まります。hello_world.c に留まった状態を確認できるような機能を実装したいところですが、まだ先になりそうです。rmmod コマンドを実行します。rmmod コマンドの引数はモジュール名です。.ko を付けていません(付けてもエラーになりません)。

$ sudo rmmod hello_world

続けて、dmesg で確かめてみましょう。module_exit() で指定した関数 hello_world_exit() が実行されているのが分かります。

$ dmesg
...省略...
[  910.921955] hello_world: module verification failed: signature and/or required key missing - tainting kernel
[  910.922372] hello_world_init: Hello world.
[  933.824630] hello_world_exit: Goodbye world.

lsmod コマンドをもう一度し hello_world モジュールが外されているのを確かめてみてください。

モジュールは一つだけ組み込める †

同じモジュールは 1 つだけ kernel に組み込めます。2 つ組み込めないか試してみましょう。2 回目は "File exists" (EEXIST, 発生源は add_unformed_module() 辺りかな) というエラーになります。

$ sudo insmod hello_world.ko
$ sudo insmod hello_world.ko
insmod: ERROR: could not insert module hello_world.ko: File exists

この結果から分ることは何でしょうか？

複数の同一デバイスを N 個接続した場合、1 個のモジュールは N 個のデバイスを扱う構造になります。モジュールのインスタンスがデバイスの数に合わせて作られることは有りません。アプリケーション・プログラムがシステム上に同時に複数存在できるのとは大きな違いです。同一デバイスが追加されるたびにモジュールはそれに対応するインスタンス(状態保持情報)を自ら作り「ユーザー・ランドからの要求を処理する」、「デバイスの変化を処理する」などの事象に応じてインスタンスの情報を更新します。

module verification failed: signature and/or required key missing - tainting kernel †

「kernel を汚した」というメッセージが気になります。このメッセージは 1 回だけ出ます。load_module() 関数で表示しています。「1 回だけ」と言う挙動は pr_notice_once() で実現しています。気になるのであれば、モジュールに署名を付けましょう。自前で構築したカーネルですのでソース・ツリーに秘密キーが有ります。署名を付けることができます。詳細は Documentation/module-signing.txt を参照して下さい。

$ keydir=/lib/modules/`uname -r`/build
$ $keydir/scripts/sign-file sha512 $keydir/signing_key.priv $keydir/signing_key.x509 hello_world.ko

いくつかの疑問と希望 †

hello_world モジュールは何もしないプログラムでした。ここで、こちらから疑問と希望を出しておきましょう。

printk は何処と結合しているの？ †

hello_world モジュールは printk 関数を使用しました。この関数のリンク先はまさに稼働している kernel の中のコードです。アプリケーション・プログラムの様に glibc ライブラリが(論理的には)プロセスそれぞれに独立してリンクされるのとは違います。リンクした関数や変数を通して kernel の中の状態を変更すれば、モジュールが外された後もその変更は残り続けます。

引数は受け取れないのか †

module_init() で指定した関数の引数は void でした。何も引数らしき値は受け取れないのでしょうか？ module_param() という特別なマクロと共に変数を使うと引数(そしてより柔軟なパラメータ)を扱うことができます。

エラーは返せないのか？ †

module_init() で指定した関数は int 型の値を返す関数です。0 以外の値を返せます。errno-base.h, errno.h にあるシステム・コール・エラー番号を負の値にして返すことができます。これで、ユーザー・ランドにエラーが起きたことを伝えることができます。

module_exit() で指定した関数は void 型でした。モジュールを外すときエラーは許されないのでしょうか？答えは「許されない」です。しかし、どうしても無理がある場合は、後で悪いことが起きない程度に後始末します。外す段になって「エラー」だと状況を伝えたところで、大抵は巻き戻して「無かったこと」にするのは無理な場合が多いです。あらかじめモジュールを外せない状況に在ると判っているならば、モジュールの参照カウンタを加減する try_module_get(), module_put() を使って下さい。

HelloWorld を修正する †

いくつかの疑問と希望を確かめ、叶えるために hello_world モジュールを修正します。長くなったので別ページに移ります。