draft/man4/rtc.4

   1 .\" rtc.4
   2 .\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de)
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" $Id: rtc.4,v 1.4 2005/12/05 17:19:49 urs Exp $
  26 .\"
  27 .\" 2006-02-08 Various additions by mtk
  28 .\" 2006-11-26 cleanup, cover the generic rtc framework; David Brownell
  29 .\"
  30 .\"*******************************************************************
  31 .\"
  32 .\" This file was generated with po4a. Translate the source file.
  33 .\"
  34 .\"*******************************************************************
  35 .\"
  36 .\" Japanese Version Copyright (c) 2006-2007 Yuichi SATO
  37 .\"         all rights reserved.
  38 .\" Translated 2006-07-12 by Yuichi SATO <ysato444@yahoo.co.jp>. LDP v2.29
  39 .\" Updated & Modified 2007-01-08 by Yuichi SATO. LDP v2.43
  40 .\"
  41 .TH RTC 4 2010\-02\-25 Linux "Linux Programmer's Manual"
  42 .SH 名前
  43 rtc \- リアルタイムクロック
  44 .SH 書式
  45 #include <linux/rtc.h>
  46 .sp
  47 \fBint ioctl(\fP\fIfd\fP\fB, RTC_\fP\fIrequest\fP\fB, \fP\fIparam\fP\fB);\fP
  48 .SH 説明
  49 これはリアルタイムクロック (RTC) のドライバのインタフェースである。
  50
  51 多くのコンピュータは、現在の「壁時計」時刻 ("wall clock" time) を記録する、 ハードウェアクロックを 1 個以上持っている。
  52 これらは「リアルタイムクロック」(RTC) と呼ばれる。 これらの時計のうち 1 つは、通常は電池でバックアップして駆動されるので、
  53 コンピュータのスイッチを切っても、時刻を保持できる。 多くの場合、RTC はアラームやその他の割り込みの機能を提供する。
  54
  55 全ての i386 PC と ACPI ベースのシステムには RTC がある。 この RTC は、元々の PC/AT に存在した Motorola
  56 MC146818 チップと互換性がある。 このような RTC は、今日ではマザーボードの チップセット (サウスブリッジ)
  57 内で実装されていることが多く、 交換可能な硬貨くらいの大きさのバックアップ電池を使っている。
  58
  59 システムオンチップ (system\-on\-chip) プロセッサを使って作られた 組み込みシステムといった、PC
  60 以外のシステムでは、別な実装を用いている。 このようなシステムでは、PC/AT の RTC と同じ機能を提供していない場合が多い。
  61 .SS "RTC とシステムクロックの違い"
  62 RTC をシステムクロックと混同すべきではない。 システムクロックは、カーネルに管理されるソフトウェアクロックであり、
  63 ファイルによるタイムスタンプ設定などとともに、 \fBgettimeofday\fP(2)  や \fBtime\fP(2)  を実装するのに使用されている。
  64 システムクロックは、POSIX における紀元 (Epoch; 1970\-01\-01 00:00:00 +0000 (UTC)) からの秒とミリ秒を表す。
  65 1 つの一般的な実装ではタイマー割り込みを、"jiffy" 毎に 1 回、 100, 250, 1000 Hz という周波数でカウントする。
  66
  67 RTC とシステムクロックの重要な違いは、 RTC はシステムが低電力状態 (「オフ」の場合も含む) でも動作するのに対し、
  68 システムクロックは動作しない点である。 システムクロックは、初期化が行われるまでは、 POSIX
  69 紀元からではなくシステムのブート時からの時刻しか返せない。 そのため、ブート時やシステムの低電力状態からの復帰 (resume) 後には、
  70 システムクロックは RTC を使って現在の壁時計時刻に設定される場合が多い。 RTC を持たないシステムでは、
  71 他の時計を使ってシステムクロックを設定する必要があり、 ネットワークにアクセスしたり、(時刻) データを手動で入力したりするだろう。
  72 .SS "RTC の機能"
  73 RTC は \fBhwclock\fP(8)  または下記の ioctl リクエストで読み書きができる。
  74
  75 日付と時間をカウントするのに加えて、 多くの RTC は以下のように割り込みを発生できる。
  76 .IP * 3
  77 クロックの更新毎 (つまり 1 秒毎)。
  78 .IP *
  79 2 Hz から 8192 Hz までの 2 の乗数の周波数で、定期的な間隔。
  80 .IP *
  81 前もって指定したアラーム時刻に達した時。
  82 .PP
  83 これらの割り込み元は、個別に有効にしたり無効にしたりできる。 多くのシステムでは、アラーム割り込みをシステムの ウェイクアップイベントとして設定できる。
  84 このイベントは、RAM へのサスペンド (STR, ACPI システムで S3 と呼ばれる) や ハイバーネーション (ACPI システムで S4
  85 と呼ばれる) といった低電力状態や、 「オフ」(ACPI システムで S5 と呼ばれる) からでも、システムを復帰できる。 電池でバックアップされた
  86 RTC が割り込みを発生できるシステムと、 できないシステムがある。
  87
  88 \fI/dev/rtc\fP (または \fI/dev/rtc0\fP, \fI/dev/rtc1\fP などの)  デバイスは (クローズされるまで) 1
  89 回しかオープンすることができず、 読み込み専用である。 \fBread\fP(2)  と \fBselect\fP(2)  を呼び出したプロセスは、 RTC
  90 からの割り込みを受け取るまで停止 (block) される。 割り込みの後、プロセスは long 型整数を読み出すことができる。
  91 この整数の最下位バイトは発生した割り込みの種別を コード化したビットマスクであり、 残りの 3 バイトは最後の \fBread\fP(2)
  92 以降に発生した割り込みの回数である。
  93 .SS "ioctl(2) インタフェース"
  94 以下の \fBioctl\fP(2)  リクエストが RTC デバイスの接続された ファイルディスクリプタに対して定義されている:
  95 .TP
  96 \fBRTC_RD_TIME\fP
  97 RTC の時刻を以下の構造体で返す:
  98 .IP
  99 .in +4n
 100 .nf
 101 struct rtc_time {
 102     int tm_sec;
 103     int tm_min;
 104     int tm_hour;
 105     int tm_mday;
 106     int tm_mon;
 107     int tm_year;
 108     int tm_wday;     /* 未使用 */
 109     int tm_yday;     /* 未使用 */
 110     int tm_isdst;    /* 未使用 */
 111 };
 112 .fi
 113 .in
 114 .IP
 115 この構造体のフィールドは \fBgmtime\fP(3)  で説明されている \fItm\fP 構造体のフィールドと同じ意味で同じ範囲である。
 116 この構造体へのポインタを \fBioctl\fP(2)  の第 3 引き数として渡す。
 117 .TP
 118 \fBRTC_SET_TIME\fP
 119 \fBioctl\fP(2)  の第 3 引き数が指す \fIrtc_time\fP 構造体の値を RTC 時刻に設定する。 RTC
 120 時刻の設定する場合、プロセスは特権 (つまり \fBCAP_SYS_TIME\fP ケーパビリティ) を持たなければならない。
 121 .TP
 122 \fBRTC_ALM_READ\fP, \fBRTC_ALM_SET\fP
 123 アラームがサポートされている RTC に対して、 アラーム時刻の読み込みと設定を行う。 アラーム割り込みは、 \fBRTC_AIE_ON\fP,
 124 \fBRTC_AIE_OFF\fP を使って、これとは別に有効または無効にしなければならない。 \fBioctl\fP(2) の第 3 引き数は、
 125 \fIrtc_time\fP 構造体へのポインタでなければならない。 この構造体の \fItm_sec\fP, \fItm_min\fP, \fItm_hour\fP
 126 フィールドのみが使用される。
 127 .TP
 128 \fBRTC_IRQP_READ\fP, \fBRTC_IRQP_SET\fP
 129 周期的な割り込みがサポートされている RTC に対して、 周期的な割り込みの周波数の読み込みと設定を行う。 周期的な割り込みは、
 130 \fBRTC_PIE_ON\fP, \fBRTC_PIE_OFF\fP を使って、これとは別に有効または無効にしなければならない。 \fBioctl\fP(2) の第 3
 131 引き数は、それぞれ \fIunsigned long\ *\fP と \fIunsigned long\fP である。 この値は 1
 132 秒当たりの割り込みの回数である。 指定可能な周波数は、2 の乗数で 2 から 8192 の範囲である。 特権プロセス (つまり
 133 \fBCAP_SYS_RESOURCE\fP ケーパビリティを持つプロセス) のみが、 \fI/proc/sys/dev/rtc/max\-user\-freq\fP
 134 に書かれた上記の周波数を設定できる。 (このファイルにはデフォルトで 64 という値が書かれている)。
 135 .TP
 136 \fBRTC_AIE_ON\fP, \fBRTC_AIE_OFF\fP
 137 アラームがサポートされている RTC に対して、 アラーム割り込みを有効または無効にする。 \fBioctl\fP(2) の第 3 引き数は無視される。
 138 .TP
 139 \fBRTC_UIE_ON\fP, \fBRTC_UIE_OFF\fP
 140 1 秒毎の割り込みがサポートされている RTC に対して、 クロック更新毎の割り込みを有効または無効にする。 \fBioctl\fP(2) の第 3
 141 引き数は無視される。
 142 .TP
 143 \fBRTC_PIE_ON\fP, \fBRTC_PIE_OFF\fP
 144 周期的な割り込みがサポートされている RTC に対して、 周期的な割り込みを有効または無効にする。 \fBioctl\fP(2) の第 3
 145 引き数は無視される。 特権プロセス (つまり \fBCAP_SYS_RESOURCE\fP ケーパビリティを持つプロセス) のみが、 その時点で
 146 \fI/proc/sys/dev/rtc/max\-user\-freq\fP に周期が上記の値に指定されている場合に、 周期的な割り込みを有効にできる。
 147 .TP
 148 \fBRTC_EPOCH_READ\fP, \fBRTC_EPOCH_SET\fP
 149 多くの RTC は年を 8 ビットのレジスタにコード化する。 年は 8 ビットのバイナリ数または BCD 数に変換される。 どちらの場合でも、その数値は
 150 RTC の紀元から相対値に変換される。 多くのシステムでは RTC の紀元は 1900 に初期化されるが、 Alpha と MIPS では、RTC
 151 レジスタの年の値に応じて、 1952, 1980, 2000 の何れかに初期化される。 これらの操作でそれぞれ RTC の紀元の読み込みと設定が可能な
 152 RTC もある。 \fBioctl\fP(2) の第 3 引き数は、それぞれ \fIunsigned long\ *\fP と \fIunsigned long\fP
 153 である。 返される値 (または指定される値) は紀元である。 RTC の紀元を設定する場合、プロセスは特権 (つまり \fBCAP_SYS_TIME\fP
 154 ケーパビリティ) を持たなければならない。
 155 .TP
 156 \fBRTC_WKALM_RD\fP, \fBRTC_WKALM_SET\fP
 157 RTC の中にはより強力なアラームインタフェースをサポートするものもあり、 これらの ioctl を使うことで、以下のような構造体で RTC
 158 のアラーム時刻を (それぞれ) 読み書きできる:
 159 .PP
 160 .RS
 161 .in +4n
 162 .nf
 163 struct rtc_wkalrm {
 164     unsigned char enabled;
 165     unsigned char pending;
 166     struct rtc_time time;
 167 };
 168 .fi
 169 .in
 170 .RE
 171 .IP
 172 \fIenabled\fP フラグはアラーム割り込みを有効または無効したり、 現在の状態を読み込むのに使用される。 これらのフラグを使う場合、
 173 \fBRTC_AIE_ON\fP と \fBRTC_AIE_OFF\fP は使用されない。 \fIpending\fP フラグは \fBRTC_WKALM_RD\fP
 174 で使用され、処理待ちの割り込みを表示する (EFI ファームウェアで管理される RTC と通信するとき以外、 Linux ではほとんど役に立たない)。
 175 \fItime\fP フィールドは \fBRTC_ALM_READ\fP や \fBRTC_ALM_SET\fP の場合と同じように使用されるが、 \fItm_mday\fP,
 176 \fItm_mon\fP, \fItm_year\fP フィールドも有効であるという点が異なる。 この構造体へのポインタを \fBioctl\fP(2)  の第 3
 177 引き数として渡さなければならない。
 178 .SH ファイル
 179 \fI/dev/rtc\fP, \fI/dev/rtc0\fP, \fI/dev/rtc1\fP など: RTC 特殊キャラクターデバイスファイル
 180
 181 \fI/proc/driver/rtc\fP: (1 つ目の) RTC の状態
 182 .SH 注意
 183 カーネルのシステムクロックを \fBadjtimex\fP(2)  を使って外部参照で同期させる場合、 \fBadjtimex\fP(2)  は指定された RTC
 184 を 11 分毎に定期的に更新する。 これを行うためカーネルは周期的な割り込みを短期間無効にする必要がある。 これは RTC
 185 を使うプログラムに影響を与える。
 186
 187 RTC の紀元は、システムクロックでのみ使用される POSIX の紀元とは何の関係もない。
 188
 189 RTC の紀元と年のレジスタに基づく年が 1970 未満である場合、 100 年後、つまり 2000 から 2069 であると仮定される。
 190
 191 RTC の中にはアラームフィールドに 「ワイルドカード」の値をサポートするものもあり、 毎時 15
 192 分や各月の初日など、定期的なアラームを行うシナリオをサポートする。 このような使い方は移植性がない。
 193 移植性の高いユーザ空間コードでは、単独のアラーム割り込みだけを想定し、 割り込みの受信後にアラームを無効または再初期化すべきである。
 194
 195 以下の機能をサポートする RTC もある。 1 秒の分数ではなく、1 秒の倍数を周期とする周期的な割り込み。 複数のアラーム。
 196 プログラム可能な出力クロックシグナル。 不揮発性 (nonvolatile) メモリ。 この API で現在提供していない、その他のハードウェア機能。
 197 .SH 関連項目
 198 \fBdate\fP(1), \fBadjtimex\fP(2), \fBgettimeofday\fP(2), \fBsettimeofday\fP(2),
 199 \fBstime\fP(2), \fBtime\fP(2), \fBgmtime\fP(3), \fBtime\fP(7), \fBhwclock\fP(8)
 200
 201 Linux カーネルソース内の \fIDocumentation/rtc.txt\fP
 202 .SH この文書について
 203 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
 204 である。プロジェクトの説明とバグ報告に関する情報は
 205 http://www.kernel.org/doc/man\-pages/ に書かれている。