2012年4月5日 星期四

什是module 以及如何寫一個module

本文出自:http://os.silversand.net 作者: 莊榮城 (2001-08-31 08:00:00)
不知道在什時候,Linux 出現了 module 這種東西,的確,它是 Linux 的一大革新。有了 module 之,寫 device driver 不再是一項惡夢,修改 kernel 也不再是一件痛苦的事了。因為你不需要每次要測試 driver 就重新 compile kernel 一次。那簡直是會累死人。Module 可以允許我們動態的改變 kernel,加載 device driver,而且它也能縮短我們 driver development 的時間。在這篇文章裡,我將要跟各位介紹一下 module 的原理,以及如何寫一個 module。

module 翻譯成中文就是模塊,不過,事實上去翻譯這個字一點都沒意義。在講模塊之前,我先舉一個例子。相信很多人都用過 RedHat。在 RedHat 裡,我們可以執行 sndconfig,它可以幫我們 config 聲卡。config 完之如果捉得到你的聲卡,那你的聲卡馬上就可以動了,而且還不用重新激活計算機。這是怎做的呢 ? 就是靠module。module 其實是一般的程序。但是它可以被動態載到 kernel 裡成為 kernel的一部分。載到 kernel 裡的 module 它具有跟 kernel 一樣的權力。可以 access 任何 kernel 的 data structure。你聽過 kdebug 嗎 ? 它是用來 debug kernel 的。它就是先將它本身的一個 module 載到 kernel 裡,而在 user space 的 gdb 就可以經由跟這個 module 溝通,得知 kernel 裡的 data structure 的值,除此之外,還可以經由載到 kernel 的 module 去更改 kernel 裡 data structure。

我們知道,在寫 C 程序的時候,一個程序只能有一個 main。Kernel 本身其實也是一個程序,它本身也有個 main,叫 start_kernel()。當我們把一個 module 載到 kernel 裡的時候,它會跟 kernel 整合在一起,成為 kernel 的一部分。請各位想想,那 module 可以有 main 嗎 ? 答案很明顯的,是 No。理由很簡單。一個程序只能有一個 main。在使用 module 時,有一點要記住的是 module 是處被動的角色。它是提供某些功能讓別人去使用的。

Kernel 裡有一個變量叫 module_list,每當 user 將一個 module 載到 kernel 裡的時候,這個 module 就會被記錄在 module_list 裡面。當 kernel 要使用到這個 module 提供的 function 時,它就會去 search 這個 list,找到 module,然再使用其提供的 function 或 variable。每一個 module 都可以 export 一些 function 或變量來讓別人使用。除此之外,module 也可以使用已經載到 kernel 裡的 module 提供的 function。這種情形叫做 module stack。比方說,module A 用到 module B 的東西,那在加載 module A 之前必須要先加載 module B。否則 module A 會無法加載。除了 module 會 export 東西之外,kernel 本身也會 export 一些 function 或 variable。同樣的,module 也可以使用 kernel 所 export 出來的東西。由大家平時都是撰寫 user space 的程序,所以,當突然去寫 module 的時候,會把平時寫程序用的 function 拿到 module 裡使用。像是 printf 之類的東西。我要告訴各位的是,module 所使用的 function 或 variable,要嘛就是自己寫在 module 裡,要嘛就是別的 module 提供的,再不就是 kernel 所提供的。你不能使用一般 libc 或 glibc所提供的 function。像 printf 之類的東西。這一點可能是各位要多小心的地方。(也許你可以先 link 好,再載到 kernel,我好象試過,但是忘了)

剛才我們說到 kernel 本身會 export 出一些 function 或 variable 來讓 module 使用,但是,我們不是萬能的,我們怎知道 kernel 有開放那裡東西讓我們使用呢 ? Linux 提供一個 command,叫 ksyms,你只要執行 ksyms -a 就可以知道 kernel 或目前載到 kernel 裡的 module 提供了那些 function 或 variable。底下是我的系統的情形:

c0216ba0 drive_info_R744aa133
c01e4a44 boot_cpu_data_R660bd466
c01e4ac0 EISA_bus_R7413793a
c01e4ac4 MCA_bus_Rf48a2c4c
c010cc34 __verify_write_R203afbeb
. . . . .

在 kernel 裡,有一個 symbol table 是用來記錄 export 出去的 function 或 variable。除此之外,也會記錄著那個 module export 那些 function。上面幾行中,表示 kernel 提供了 drive_info 這個 function/variable。所以,我們可以在 kernel 裡直接使用它,等載到 kernel 裡時,會自動做好 link 的動作。由此,我們可以知道,module 本身其實是還沒做 link 的一些 object code。一切都要等到 module 被加載 kernel 之,link 才會完成。各位應該可以看到 drive_info 面還接著一些奇怪的字符串。_R744aa133,這個字符串是根據目前 kernel 的版本再做些 encode 得出來的結果。為什額外需要這一個字符串呢 ?

Linux 不知道從那個版本以來,就多了一個 config 的選項,叫做 Set version number in symbols of module。這是為了避免對系統造成不穩定。我們知道 Linux 的 kernel 更新的很快。在 kernel 更新的過程,有時為了效率起見,會對某些舊有的 data structure 或 function 做些改變,而且一變可能有的 variable 被拿掉,有的 function 的 prototype 跟原來的都不太一樣。如果這種情形發生的時候,那可能以前 2.0.33 版本的 module 拿到 2.2.1 版本的 kernel 使用,假設原來 module 使用了 2.0.33 kernel 提供的變量叫 A,但是到了 2.2.1 由某些原因必須把 A 都設成 NULL。那當此 module 用在 2.2.1 kernel 上時,如果它沒去檢查 A 的值就直接使用的話,就會造成系統的錯誤。也許不會整個系統都死掉,但是這個 module 肯定是很難發揮它的功能。為了這個原因,Linux 就在 compile module 時,把 kernel 版本的號碼 encode 到各個 exported function 和 variable 裡。

所以,剛才也許我們不應該講 kernel 提供了 drive_info,而應該說 kernel 提供了 driver_info_R744aa133 來讓我們使用。這樣也許各位會比較明白。也就是說,kernel 認為它提供的 driver_info_R744aa133 這個東西,而不是 driver_info。所以,我們可以發現有的人在加載 module 時,系統都一直告訴你某個 function 無法 resolved。這就是因為 kernel 裡沒有你要的 function,要不然就是你的 module 裡使用的 function 跟 kernel encode 的結果不一樣。所以無法 resolve。解決方式,要嘛就是將 kernel 裡的 set version 選項關掉,要嘛就是將 module compile 成 kernel 有辦法接受的型式。

那有人就會想說,如果 kernel 認定它提供的 function 名字叫做 driver_info_R744aa133 的話,那我們寫程序時,是不是用到這個 funnction 的地方都改成 driver_info_R744aa133 就可以了。答案是 Yes。但是,如果每個 function 都要你這樣寫,你不會覺得很煩嗎 ? 比方說,我們在寫 driver 時,很多人都會用到 printk 這個 function。這是 kernel 所提供的 function。它的功能跟 printf 很像。用法也幾乎都一樣。是 debug 時很好用的東西。如果我們 module 裡用了一百次 printk,那是不是我們也要打一百次的 printk_Rdd132261 呢 ? 當然不是,聰明的人馬上會想到用 #define printk printk_Rdd132261 就好了嘛。所以,Linux 很體貼的幫我們做了這件事。

如果各位的系統有將 set version 的選項打開的話,那大家可以到 /usr/src/linux/include/linux/modules 這個目錄底下。這個目錄底下有所多的 ..ver檔案。這些檔案其實就是用來做 #define 用的。我們來看看 ksyms.ver 這個檔案裡,裡面有一行是這樣子的 :

#define printk _set_ver(printk)

set_ver 是一個 macro,就是用來在 printk 面加上 version number 的。有興趣的朋友可以自行去觀看這個 macro 的寫法。用了這些 ver ,我們就可以在 module 裡直接使用 printk 這樣的名字了。而這些 ver 檔會自動幫我們做好 #define 的動作。可是,我們可以發現這個目錄有很多很多的 ver 。有時候,我們怎知道我們要呼叫的 function 是在那個 ver 檔裡有定義呢 ? Linux 又幫我們做了一件事。/usr/src/linux/include/linux/modversions.h 這個檔案已經將全部的 ver 檔都加進來了。所以在我們的 module 裡只要 include 這個檔,那名字的問題都解決了。但是,在此,我們奉勸各位一件事,不要將 modversions.h 這個檔在 module 裡 include 進來,如果真的要,那也要加上以下數行:

#ifdef MODVERSIONS
#include
#endif

加入這三行的原因是,避免這個 module 在沒有設定 kernel version 的系統上,將 modversions.h 這個檔案 include 進來。各位可以去試試看,當你把 set version 的選項關掉時,modversions.h 和 modules 這個目錄都會不見。如果沒有上面三行,那 compile 就不會過關。所以一般來講,modversions.h 我們會選擇在 compile 時傳給 gcc 使用。就像下面這個樣子。

gcc -c -D__KERNEL__ -DMODULE -DMODVERSIONS main.c \
-include usr/src/linux/include/linux/modversions.h

在這個 command line 裡,我們看到了 -D__KERNEL__,這是說要定義 __KERNEL__ 這個 constant。很多跟 kernel 有關的 header file,都必須要定義這個 constant 才能 include 的。所以建議你最好將它定義起來。另外還有一個 -DMODVERSIONS。這個 constant 我剛才忘了講。剛才我們說要解決 fucntion 或 variable 名字 encode 的方式就是要 include modversions.h,其實除此之外,你還必須定義 MODVERSIONS 這個 constant。再來就是 MODULE 這個 constant。其實,只要是你要寫 module 就一定要定義這個變量。而且你還要 include module.h 這個檔案,因為 _set_ver 就是定義在這裡的。

講到這裡,相信各位應該對 module 有一些認識了,以遇到 module unresolved 應該不會感到困惑了,應該也有辦法解決了。

剛才講的都是使用別人的 function 上遇到的名字 encode 問題。但是,如果我們自己的 module 想要 export 一些東西讓別的 module 使用呢。很簡單。在 default 上,在你的 module 裡所有的 global variable 和 function 都會被認定為你要 export 出去的。所以,如果你的 module 裡有 10 個 global variable,經由 ksyms,你可以發現這十個 variable 都會被 export 出去。這當然是個很方便的事啦,但是,你知道,有時候我們根本不想把所有的 variable 都 export 出去,萬一有個 module 沒事亂改我們的 variable 怎辦呢 ? 所以,在很多時候,我們都只會限定幾個必要的東西 export 出去。在 2.2.1 之前的 kernel (不是很確定) 可以利用 register_symtab 來幫我們。但是,現在更新的版本早就出來了。所以,在此,我會介紹 kernel 2.2.1 裡所提供的。kernel 2.2.1 裡提供了一個 macro,叫做 EXPORT_SYMBOL,這是用來幫我們選擇要 export 的 variable 或 function。比方說,我要 export 一個叫 full 的 variable,那我只要在 module 裡寫:

EXPORT_SYMBOL(full);

就會自動將 full export 出去,你馬上就可以從 ksyms 裡發現有 full 這個變量被 export 出去。在使用 EXPORT_SYMBOL 之前,要小心一件事,就是必須在 gcc 裡定義 EXPORT_SYMTAB 這個 constant,否則在 compile 時會發生 parser error。所以,要使用 EXPORT_SYMBOL 的話,那 gcc 應該要下:

gcc -c -D__KERNEL__ -DMODULE -DMODVERSIONS -DEXPORT_SYMTAB \
main.c -include /usr/src/linux/include/linux/modversions.h

如果我們不想 export 任何的東西,那我們只要在 module 裡下

EXPORT_NO_SYMBOLS;

就可以了。使用 EXPORT_NO_SYMBOLS 用不著定義任何的 constant。其實,如果各位使用過舊版的 register_symbol 的話,一定會覺得新版的方式比較好用。至少我是這樣覺得啦。因為使用 register_symbol 還要先定義出自己的 symbol_table,感覺有點麻煩。

當我們使用 EXPORT_SYMBOL 把一些 function 或 variable export 出來之,我們使用 ksyma -a 去看一些結果。我們發現 EXPORT_SYMBOL(full) 的確是把 full export出來了 :

c8822200 full [my_module]
c01b8e08 pci_find_slot_R454463b5
. . .

但是,結果怎跟我們想象中的不太一樣,照理說,應該是 full_Rxxxxxx 之類的東西才對啊,怎才出現 full 而已呢 ? 奇怪,問題在那裡呢 ?

其實,問題就在我們沒有對本身的 module 所 export 出來的 function 或 variable 的名字做 encode。想想,如果在 module 的開頭。我們加入一行

#define full full_Rxxxxxx

之,我們再重新 compile module 一次,載到 kernel 之,就可以發現 ksyms -a 顯示的是

c8822200 full_Rxxxxxx [my_module]
c01b8e08 pci_find_slot_R454463b5
. . . . .

了。那是不是說,我們要去對每一個 export 出來的 variable 和 function 做 define 的動作呢 ? 當然不是。記得嗎,前頭我們講去使用 kernel export 的 function 時,由 include 了一些 .ver 的檔案,以致我們不用再做 define 的動作。現在,我們也要利用 .ver 的檔案來幫我們,使我們 module export 出來的 function 也可以自動加入 kernel version 的 information。也就是變成 full_Rxxxxxx 之類的東西。

Linux 裡提供了一個 command,叫 genksyms,就是用來幫我們產生這種 .ver 的檔案的。它會從 stdin 裡讀取 source code,然檢查 source code 裡是否有 export 的 variable 或 function。如果有,它就會自動為每個 export 出來的東西產生一些 define。這些 define 就是我們之前說的。等我們有了這些 define 之,只要在我們的 module 裡加入這些 define,那 export 出來的 function 或 variable 就會變成上面那個樣子。

假設我們的程序都放在一個叫 main.c 的檔案裡,我們可以使用下列的方式產生這些 define。

gcc -E -D__GENKSYMS__ main.c | genksyms -k 2.2.1 > main.ver

gcc 的 -E 參數是指將 preprocessing 的結果 show 出來。也就是說將它 include 的檔案,一些 define 的結果都展開。-D__GENKSYMS__ 是一定要的。如果沒有定義這個 constant,你將不會看到任何的結果。用一個管線是因為 genksyms 是從 stdin 讀資料的,所以,經由管線將 gcc 的結果傳給 genksyms。-k 2.2.1 是指目前使用的 kernel 版本是 2.2.1,如果你的 kernel 版本不一樣,必須指定你的 kernel 的版本。產生的 define 將會被放到 main.ver 裡。產生完 main.ver 檔之,在 main.c 裡將它 include 進來,那一切就 OK 了。有件事要告訴各位的是,使用這個方式產生的 module,其 export 出來的東西會經由 main.ver 的 define 改頭換面。所以如果你要讓別人使用,那你必須將 main.ver 公開,不然,別人就沒辦法使用你 export 出來的東西了。

講了這多,相信各位應該都已經比較清楚 module 在 kernel 中是怎樣一回事,也應該知道為什有時候 module 會無法加載了。除此之外,各位應該還知道如何使自己 module export 出來的東西也具有 kernel version 的 information。

接下來,要跟各位講的就是,如何寫一個 module 了。其實,寫一個 module 很簡單的。如果你了解我上面所說的東西。那我再講一次,再用個例子,相信大家就都會了。要寫一個 module,必須要提供兩個 function。這兩個 function 是給 insmod 和 rmmod 使用的。它們分別是 init_module(),以及 cleanup_module()。

int init_module();
void cleanup_module();

相信大家都知道在 Linux 裡可以使用 insmod 這個 command 來將某個 module 加載。比方說,我有一個 module 叫 hello.o,那使用 insmod hello.o 就可以將 hello 這個 module 載到 kernel 裡。觀察 /etc/modules 應該就可以看到 hello 這個 module 的名字。如果要將 hello 這個 module 移除,則只要使用 rmmod hello 就可以了。insmod 在加載 module 之,就會去呼叫 module 所提供的 init_module()。如果傳回 0 表示成功,那 module 就會被加載。如果失敗,那加載的動作就會失敗。一般來講,我們在 init_module() 做的事都是一些初始化的工作。比方說,你的 module 需要一塊內存,那你就可以在 init_module() 做 kmalloc 的動作。想當然爾。cleanup_module() 就是在 module 要移除的時候做的事。做的事一般來講就是一些善的工作,比方像把之前 kmalloc 的內存 free 掉。

由 module 是載到 kernel 使用的,所以,可能別的 module 會使用你的 module,甚至某些 process 也會使用到你的 module,為了避免 module 還有人使用時就被移除,每個 module 都有一個 use count。用來記錄目前有多少個 process 或 module 正在使用這個 module。當 module 的 use count 不等 0 時,module 是不會被移除掉的。也就是說,當 module 的 use count 不等 0 時,cleanup_module() 是不會被呼叫的。

在此,我要介紹三個 macro,是跟 module 的 use count 有關的。

MOD_INC_USE_COUNT
MOD_DEC_USE_COUNT
MOD_IN_USE

MOD_INC_USE_COUNT 是用來增加 module 的 use count,而 MOD_DEC_USE_COUNT 是用來減少 module 的 use count。至 MOD_IN_USE 則是用來檢查目前這個 module 是不是被使用中。也就是檢查 use count 是否為 0。module 的 use count 必須由寫 module 的人自己來 maintain。系統並不會自動為你把 use count 加一或減一。一切都得由自己控制。下面有一個例子,但是,並不會介紹這三個 macro 的使用方法。將來如果有機會,我再來介紹這三個 macro 的用法。

這個例子很簡單。其實只是示范如何使用 init_module() 以及 cleanup_module() 來寫一個 module。當然,這兩個 function 只是構成 module 的基本條件罷了。至 module 裡要提供的功能則是看各人的需要。

main.c
#define MODULE
#include
#include
int full;
EXPORT_SYMBOL(full); /* 將 full export 出去 */
int init_module( void )
{
printk( "<5> Module is loaded\n" );
return 0;
}
void cleanup_module( void )
{
printk( "<5> Module is unloaded\n" );
}

關 printk 是這樣子的,它是 kernel 所提供的一個打印訊息的 function。kernel 有 export 這個 function。所以你可以自由的使用它。它的用法跟 printf 幾乎一模一樣。唯獨訊息的開頭是 <5>,其實,不見得這三個字符啦。也可以是 <4>,<3>,<7> 等等的東西。這是代表這個訊息的 prioirty 或 level。<5> 表示的是跟 KERNEL 有關的訊息。

main.ver:

利用 genksyms 產生出來的。

gcc -E -D__GENKSYMS__ main.c | genksyms -k 2.2.1 > main.ver

接下來,就是要把 main.c compile 成 main.o

gcc -D__KERNEL__ -DMODVERSIONS -DEXPORT_SYMTAB -c \
-I/usr/src/linux/include/linux -include \
/usr/src/linux/include/linux/modversions.h \
-include ./main.ver main.c

好了。main.o 已經成功的 compile 出來了,現在下一個 command,

insmod main.o

檢查看 /proc/modules 裡是否有 main 這個 module。如果有,表示 main 這個 module 已經載到 kernel 了。再下一個指令,看看 full export 出去的結果。

ksyms

結果顯示

Address Symbol Defined by
c40220e0 full_R355b84b2 [main]
c401d04c ne_probe [ne]
c401a04c ei_open [8390]
c401a094 ei_close [8390]
c401a504 ei_interrupt [8390]
c401af1c ethdev_init [8390]
c401af80 NS8390_init [8390]

可以看到 full_R355b84b2,表示,我們已經成功的將 full 的名字加上 kernel version 的 information 了。當我們不需要這個 module 時,我們就可以下一個 command,

rmmod main

這樣 main 就會被移除掉了。再檢查看看 /proc/modules 就可以發現 main 那一行不見了。各位現在可以看一下 /var/log/message 這個檔案,應該可以發現以兩行

Apr 12 14:19:05 host kernel: Module is loaded
Apr 12 14:39:29 host kernel: Module is unloaded

這兩行就是 printk 印出來的。

關 module 的介紹已經到此告一段落了。其實,使用 module 實在是很簡單的一件事。對要發展 driver 或是增加 kernel 某些新功能的人來講,用 module 不啻為一個方便的方式。希望這篇文章對各位能有所幫助。


莊榮城 (J.C. Chuang), cjc86@cs.ccu.edu.tw

How to use simple speedtest in RaspberryPi CLI

  pi@ChunchaiRPI2:/tmp $  wget -O speedtest-cli https://raw.githubusercontent.com/sivel/speedtest-cli/master/speedtest.py --2023-06-26 10:4...