EN JA
EVENTTIMERS(9)
EVENTTIMERS(9) FreeBSD Kernel Developer's Manual EVENTTIMERS(9)

名称

eventtimersカーネルイベントタイマサブシステム

書式

#include < sys/timeet.h>

struct eventtimer; 
 
typedef int et_start_t(struct eventtimer *et, 
    sbintime_t first, sbintime_t period); 
typedef int et_stop_t(struct eventtimer *et); 
typedef void et_event_cb_t(struct eventtimer *et, void *arg); 
typedef int et_deregister_cb_t(struct eventtimer *et, void *arg); 
 
struct eventtimer { 
 SLIST_ENTRY(eventtimer) et_all; 
 char   *et_name; 
 int   et_flags; 
#define ET_FLAGS_PERIODIC 1 
#define ET_FLAGS_ONESHOT 2 
#define ET_FLAGS_PERCPU  4 
#define ET_FLAGS_C3STOP  8 
#define ET_FLAGS_POW2DIV 16 
 int   et_quality; 
 int   et_active; 
 uint64_t  et_frequency; 
 sbintime_t  et_min_period; 
 sbintime_t  et_max_period; 
 et_start_t  *et_start; 
 et_stop_t  *et_stop; 
 et_event_cb_t  *et_event_cb; 
 et_deregister_cb_t *et_deregister_cb; 
 void    *et_arg; 
 void   *et_priv; 
 struct sysctl_oid *et_sysctl; 
};


int
et_register( struct eventtimer *et);

int
et_deregister( struct eventtimer *et);

ET_LOCK();

ET_UNLOCK();

struct eventtimer *
et_find( const char *name, int check, int want);

int
et_init( struct eventtimer *et, et_event_cb_t *event, et_deregister_cb_t *deregister, void *arg);

int
et_start( struct eventtimer *et, sbintime_t first, sbintime_t period);

int
et_stop( struct eventtimer *et);

int
et_ban( struct eventtimer *et);

int
et_free( struct eventtimer *et);

解説

イベントタイマは、異なる時間に基づいたイベントを実行するために、指定された時間または周期的に割り込みを生成することに対して責任があります。サブシステムは、次の 3 つの主要な部分から成ります:
Drivers
要求された時間のイベントを生成するためにハードウェアを管理します。
Consumers
sys/kern/kern_clocksource.c は、 hardclock(), statclock() と profclock() タイムイベントでカーネルに供給するイベントタイマを使用します。
Glue code
sys/sys/timeet.h, sys/kern/kern_et.c は、イベントタイマドライバと消費者 (consumer) に API を提供しています。

ドライバ API

ドライバ API は、eventtimer 構造体の周囲で構築されます。その機能性を登録するために、ドライバは、その構造体を割り付けて et_register() 呼び出します。ドライバは、次のフィールドに書き込むべきです:
et_name
管理的のためのイベントタイマのユニークな名前。
et_flags
タイマのケーパビリティを記述するフラグの組は、次の通りです:
ET_FLAGS_PERIODIC
周期的なモードをサポート。
ET_FLAGS_ONESHOT
1 回限りのモードをサポート。
ET_FLAGS_PERCPU
タイマは、CPU ごとです。
ET_FLAGS_C3STOP
タイマは、CPU のスリープ状態で停止するかもしれません。
ET_FLAGS_POW2DIV
タイマは、2^n 除数のみをサポートします。
et_quality
このタイムカウンタ (timecounter) が他のものよりよいかどうかを認証する抽象的な値。より高い値は、より良いことを意味します。
et_frequency
適用可能で、知られているなら、タイマ発信器の基本的な周波数。それを割ることによって取得することができた利用可能な周波数の組を予測するために消費者によって使用されます。適用可能でないか未知であるなら、0 であるべきです。
et_min_period, et_max_period
最小と最大の信頼できるプログラマブルな期間 (time period)。
et_start
ドライバのタイマ開始関数ポインタ。
et_stop
ドライバのタイマ停止関数ポインタ。
et_priv
ドライバのプライベートデータの記憶域。

イベントタイマの機能が登録された後、それは、 et_startet_stop メソッドを通して制御されます。 et_start メソッドは、指定されたイベントタイマを開始するために呼び出されます。最後の 2 つの引数は、イベントが生成されるべきであるとき、指定するために使用されます。 first 引数は、最初のイベントが生成される前に、期間 (time period) を指定します。周期的なモードで、NULL の値は、最初の期間が period 引数の値と等しいことを指定します。 period 引数は、周期的なモードのための次のイベントの間の期間 (time period) を指定します。 NULL の値は、1 回限りのモードを指定します。少なくとも、これらの 2 つの引数の 1 つは、NULL であってはいけません。イベントタイムに到着するとき、ドライバは、2 番目の引数として et_arg を渡す et_event_cb コールバック関数を呼び出すべきです。 et_stop メソッドは、指定されたイベントタイマを停止するために呼び出されます。 CPU ごとのイベントタイマについて、 et_startet_stop メソッドは、現在の CPU に関連したタイマを制御します。

ドライバは、 et_deregister() を呼び出すことによってその機能の登録を取り消します。

消費者 (consumer) API

et_find() によって消費者は、オプションで指定された名前および/またはケーパビリティフラグに一致する利用可能なイベントタイマを見つけることができます。消費者は、返された eventtimer 構造体を読み込みますが、それを修正するべきではありません。必要とされるイベントタイマが見つかるとき、 et_init() は、 event とオプションで deregister コールバック関数と不透明な引数 arg を提出して、呼び出されるべきです。その引数は、コールバックへの引数として渡されます。イベントコールバック関数は、スケジュールされたタイムイベントで呼び出されます。それは、ハードウェア割り込みコンテキストから呼び出されるので、スリープは、そこで許可されません。登録を取り消しコールバック関数は、イベントタイマの機能がもはや利用可能ではない、消費者に報告するために呼び出されます。この呼び出しにおいて、消費者は、返る前にイベントタイマを使用して停止するべきです。

タイマが見つかり初期化される後に、 et_start() と et_stop() によって、それを制御することができます。引数は、ドライバ API に記述されているもののと同じです。 CPU ごとのイベントタイマは、特定の CPU からのみ制御することができます。

et_ban() によって、消費者は、どういうわけか検知されたなら、1 回限りと周期的なケーパビリティフラグの両方をクリアすることによって、壊れているようなイベントタイマをマークすることができます。 et_free() は、 et_init() の反対です。それは、他の消費者の使用のためのイベントタイマを解放します。

ET_LOCK() と ET_UNLOCK() マクロは、 et_find() によって返された登記されたイベントタイマとポインタのリストへの連続したアクセスのために et_find(), et_init() と et_free() の周囲の mutex(9) ロックを管理するために使用されるべきです。 et_start() と et_stop() 呼び出しは、同時にタイマのハードウェアをアクセスすることを回避するために消費者の内部の方法で順番になされるべきです。

関連項目

eventtimers(4)

作者

Alexander Motin <mav@FreeBSD.org>
February 25, 2013 FreeBSD