pm(7D) (SunOS リファレンスマニュアル (7) : デバイスとネットワークインタフェース)

SunOS リファレンスマニュアル (7) : デバイスとネットワークインタフェース

pm(7D)

名前 | 形式 | 機能説明 | 旧式の IOCTLS | 新しい IOCTLS | エラー | 属性 | 関連項目

名前

pm- 電源管理システムのドライバ

形式

/dev/pm

機能説明

電源管理システム (pm) のドライバは、アプリケーションが電源管理用にシステム内でデバイスを設定するインタフェースを提供します。インタフェースは、ioctl(2) コマンドを経由して提供されます。pm ドライバは、/dev/pm を使用してアクセスすることができます。

電源管理システムのフレームワーク

電源管理システムのフレームワークのモデルは、システムをデバイスの集合体として見ます。各デバイスは部品の集合体であり、部品は電源管理が可能な最小単位です。デバイス内の電源管理が可能な部品は、デバイスドライバの制御によって異なります。

電源管理可能な部品は、現在の電源レベルでは busy または idle のどちらかの状態となります。通常、電源管理フレームワークは、idle 状態にある部品を次に低い電源レベルにします。電源管理フレームワークは、部品がしきい値の時間以上アイドル状態にあることと、部品が属しているデバイスが依存条件を満たしていることの 2 つの要素によってこの遷移を判定します。依存関係は、あるデバイスが電源管理される前に別のデバイスが電源管理されている必要がある場合に発生します。依存関係はデバイス単位で発生します。依存関係が存在する場合、デバイスが依存するすべてのデバイスが最初に管理されないかぎり、そのデバイスの部品のいずれも管理することができません。

以下のコマンドを使用することによって、アプリケーションは電源管理フレームワークドライバからデバイスの電源管理の制御を受け取り、デバイスの電源レベルの遷移を直接管理することができます。

旧式の IOCTLS

このセクションで記述されているすべての ioctl コマンドは、現在のリリースでは旧式であり、将来のリリースで削除される予定です。新しいコマンドについては、このマニュアルページの「新しい IOCTLS」セクションを参照してください。

コマンドのこのセットについて、arg (ioctl(2) を参照) は <sys/pm.h>で定義された型 pm_request の構造体を指します。

typedef struct {
     char *who;          /* 設定するデバイス */
     int  select;        /* 部品またはデバイスの依存デバイスを選択 */
     int  level;         /* 電源レベルまたはしきい値 */
     char *dependent;    /* 依存デバイスの名前を格納 */
     int  size;          /* 依存デバイスのバッファーの大きさ */
} pm_request;

フィールドには、以下のデータが含まれている必要があります。

who: 設定されるデバイスの名前を指すポインタです。デバイスの専用のファイル名またはデバイスへの物理パスの部分文字列となることもあります。
select: 設定される部品または依存デバイスを指定する正の整数です。番号付けは 0 で始まります。
level: 秒単位のしきい値または目的の電源レベルを指定する正の整数です。
dependent: このデバイスが依存するデバイスの名前を格納しているバッファーを指すポインタです。who のフィールドと同じ形式を使用します。
size: 依存デバイスのバッファーの大きさです。

すべてのフィールドが、各コマンドで使用されるわけではありません。

PM_DISABLE_AUTOPM

who で指定されたデバイスに対しては、フレームワークによる電源管理が無効になっています。呼び出し元は、以下のコマンドを使用してこのデバイスの電源を管理します。このコマンドの実行が成功しなかった場合、それに続く PM_SET_CUR_PWR は失敗します。このコマンドは、現在のリリースでは旧式であり、将来のリリースで削除される予定です。代わりに PM_DIRECT_PM コマンドを使用してください。

以下にエラーコードを示します。

EBUSY: フレームワークにより、デバイスの電源管理はすでに無効になっています。
EPERM: 呼び出し元がスーパーユーザーまたはデバイスの所有者ではありません。

PM_GET_NORM_PWR

who で指定されたデバイスの部品 select の通常の電源レベルが返されました。この部品の通常の電力は、この部品が再び使用中になるときにこの部品に対して設定される電源レベルです。このコマンドは、現在のリリースでは旧式であり、将来のリリースで削除される予定です。代わりに PM_GET_FULL_POWER コマンドを使用してください。

以下にエラーコードを示します。

EINVAL: デバイスの部品が範囲外です。
EIO: デバイスには、電源管理が可能な部品がありません。

PM_GET_CUR_PWR

who で指定されたデバイスの部品 select の現在の電源レベルが返されました。このコマンドは、現在のリリースでは旧式であり、将来のリリースで削除される予定です。代わりに PM_GET_CURRENT_POWER コマンドを使用してください。

以下にエラーコードを示します。

EINVAL: デバイスの部品が範囲外です。
EAGAIN: デバイスの部品の電源レベルは、現在わかっていません。

PM_SET_CUR_PWR

who で指定されたデバイスの部品 select に対して電源レベルが level になりました。select が 0 でなく、デバイスの部品 0 が電源レベル 0 にある場合、部品 0 に対して電源レベルが通常のレベルになります。このデバイスに依存する各デバイスの各部品に対して、電源レベルは通常の電源レベルになります。影響を受ける各デバイスの各祖先の各部品に対して、電源レベルは通常の電源レベルになります。このコマンドは、現在のリリースでは旧式であり、将来のリリースで削除される予定です。代わりに PM_SET_CURRENT_POWER コマンドを使用してください。

以下にエラーコードを示します。

EINVAL: デバイスの部品が範囲外か、 0 より低い電源レベルです。
EIO: デバイスまたはその祖先、またはその依存先またはそれらの祖先に対して電源投入が失敗しました。
EPERM: 呼び出し元がスーパーユーザーまたはデバイスの所有者ではありません。

PM_REENABLE_AUTOPM

who で指定されたデバイスに対して、フレームワークによる電源管理が再び有効になりました。デフォルトでは、すべての構成されたデバイスはフレームワークによって電源管理されます。このコマンドは、現在のリリースでは旧式であり、将来のリリースで削除される予定です。代わりに PM_RELEASE_DIRECT_PM コマンドを使用してください。

以下にエラーコードを示します。

EINVAL: デバイスはすでにフレームワークによって電源管理されています。
EPERM: 呼び出し元がスーパーユーザーまたはデバイスの所有者ではありません。

新しい IOCTLS

このセクションの ioctl コマンドは、前述されているは旧式のコマンドに代わるものです。これらの新しいコマンドは、異なる構造へのポインタを取り、より完全な機能をサポートします。

ioctl コマンドのセットについて、arg (ioctl(2) を参照) は、<sys/pm.h> で定義された型 pm_req の構造体を指します。

typedef struct pm_req {
          char *physpath;     /* 設定するデバイスの物理パス */
                              /* libdevinfo(3) を参照 */
          int  component;     /* デバイスの部品 */
          int  value;         /* 電源レベル、しきい値、またはカウント */
          void *data;         /* コマンドに依存する可変サイズデータ */
          size_t  datasize;   /* データバッファーの大きさ */
     } pm_req_t;

このフィールドには以下のデータが含まれている必要があります。

physpath: デバイスの物理パスを指すポインタです。libdevinfo(3devinfo) を参照してください。たとえば、デバイス /devices/pseudo/pm@0:pm では、 physpath の値は /pseudo/pm@0 です。
component: 設定される部品または依存デバイスを指定する正の整数です。番号付けは 0 から始まります。
value: 秒単位のしきい値または目的の電源レベルを指定する正の整数、あるいは指定されているレベルの数値です。
data: このデバイスが依存するデバイスの名前などの可変サイズデータを格納しているか受け取るバッファーを指すポインタです。
size: データバッファーのサイズ。

すべてのフィールドが、各コマンドで使用されるわけではありません。

PM_DIRECT_PM

physpath で指定されたデバイスに対しては、フレームワークによって行われていた電源管理が無効になっています。呼び出し元は、PM_DIRECT_NOTIFY、PM_GET_TIME_IDLE、PM_GET_CURRENT_POWER、PM_GET_FULL_POWER および PM_SET_CURRENT_POWER コマンドを使用してこのデバイスの電源を管理します。「このドライバが、pm_raise_power(9F )、pm_lower_power(9F )、pm_power_has_changed(9F) のいずれかを呼び出す」、または「このデバイスが電源レベルが変化している別のデバイスの親であるか、このデバイスが依存しているデバイスの電源レベルが変化している」かのどちらかの理由により、このデバイスで電源レベルの変更が必要になる場合には、電源レベルの変更は行われず、呼び出し元は、以下に PM_DIRECT_NOTIFY コマンドについて記述されているように電源レベルの変化について通知されます。

以下にエラーコードを示します。

EBUSY: フレームワークにより、デバイスの電源管理はすでに無効になっています。
EPERM: 呼び出し元がスーパーユーザーでないか、または実効グループ ID が 0 ではありません。

PM_RELEASE_DIRECT_PM

physpath (PM_DIRECT_PM コマンドのターゲットである必要がある) で指定されたデバイスに対して、フレームワークによる電源管理が再び有効になりました。

以下にエラーコードを示します。

EINVAL: デバイスの部品が範囲外です。

PM_DIRECT_NOTIFY PM_DIRECT_NOTIFY_WAIT

これらのコマンドは、デバイスを直接電源管理しているプロセスに、このデバイスの電源レベルが変更されるかも知れないイベントについて通知します。このようなイベントが起こった場合は、このコマンドは該当イベントについての情報を返します。

arg ( ioctl(2) を参照) は、以下のように <sys/pm.h> で定義された型 pm_state_change の構造体を指します。

typedef struct  pm_state_change {
   char   *physpath;    /* 状態が変化したデバイス */
   int     component;   /* どの部品の状態が変化したか */
#if defined(_BIG_ENDIAN)
	ushort_t flags;      /* PSC_EVENT_LOST、PSC_ALL_LOWEST */   
	ushort_t event;      /* イベントの型 */
#else
	ushort_t event;      /* イベントの型 *
	ushort_t flags;      /* PSC_EVENT_LOST、PSC_ALL_LOWEST */
#endif
	time_t  timestamp;   /* 状態の変化した時刻 */+
	int     old_level;    /* 変更前の電源レベル */
	int    new_level;   /* 変更後の電源レベル */
	size_t  size;        /* physpath が指すバッファーの大きさ */
} pm_state_change_t;

イベントが起こった場合は、arg が指す構造体に挿入されます。このイベントの型が PSC_PENDING_CHANGE の場合は、構造体の残りの部分の情報には、このデバイスが呼び出し元により直接電源管理されない場合にフレームワークがとるアクションが記述されます。呼び出し元は、以下に示す PM_SET_CURRENT_POWER を使用して指定された電源レベルの変更を完全に行います。

PSC_HAS_CHANGED のイベントの型は、デバイスを直接電源管理するドライバがそのデバイスの電源の変化のために、pm_power_has_changed(9F) を呼んだことを示します。これにより呼び出し元は、デバイスの電源の状態を追跡することができます。

システムは、イベントを循環バッファーに入れます。バッファーがオーバーフローした場合、最も古いイベントが削除され、削除されたイベントの次に古いイベントが取り出された時に、PSC_EVENT_LOST フラグが設定されます。

保留中のイベントがない場合は、PM_DIRECT_NOTIFY は、EWOULDBLOCK を返します。また PM_DIRECT_NOTIFY_WAIT は、イベントが使用できるようになるまで実行されません。

pm は、poll(2) インタフェースもサポートします。イベントが保留中の場合、 /dev/pm のファイル記述子を含み、かつイベントマスクに設定された POLLIN または POLLRDNORM を持つ poll(2) 呼び出しが返されます。

PM_SET_CURRENT_POWER

physpath ( PM_DIRECT_PM コマンドを発行したプロセスに対するデバイスの物理パス) で指定されたデバイスの部品である component は、電源レベルが value に設定されています。physpath で指定されたデバイスのすべての部品の電源レベルが 0 で、value の値が 0 ではなく、しかも、このデバイスに依存するデバイスがある場合は、このコマンドが返される前に、デバイスのすべての部品がフルパワーになります。同様に、ターゲットデバイスの親の電源が切断されている場合、そのデバイスはこのコマンドが返される前に必要に応じて起動します。PM_SET_CURRENT_POWER がデバイスに対して発行されると、結果として発生する電源の変更が、PM_DIRECT_NOTIFY のイベントリストに追加されます。

以下にエラーコードを示します。

EINVAL: デバイスの部品が範囲外か、 0 より低い電源レベルです。
EIO: デバイスまたはその祖先、またはその依存先またはそれらの祖先に対して電源投入が失敗しました。部品が busy の状態になったためにデバイスドライバがコマンドを不適切なものとして拒否した可能性があるため、このことは障害を示しているとは限らないことに注意してください。
EPERM: 呼び出し元がこのデバイスに対して以前に行った PM_DIRECT_PM コマンドの実行が成功していません。

PM_GET_FULL_POWER

physpath で指定されたデバイスの部品 component の使用可能なもっとも高い電源レベルが返されました。

PM_GET_CURRENT_POWER

physpath で指定されたデバイスの部品 component の現在の電源レベルが返されました。

以下にエラーコードを示します。

EAGAIN: デバイス部品の電源レベルは、現在わかっていません。

PM_GET_TIME_IDLE

PM_GET_TIME_IDLE は、 physpath で指定されたデバイスの部品 component が idel 状態になっている秒数を返します。デバイスが idel 状態でない場合は、0 が返されます。

プロセスが PM_GET_TIME_IDLE コマンドと PM_SET_CURRENT_POWER コマンドを実行する間に idel 状態にある部品の電源レベルを小さくするために、デバイスの状態が変化することがあります。そのためにプロセスは、 PM_SET_CURRENT_POWER コマンドの実行が成功しなかったと返された場合に対処できる必要があります。これはデバイスの部品が busy の状態になったために、デバイスがコマンドを不適切であるとして拒否することがあるためです。PM_GET_TIME_IDLE コマンドを再び実行して、その部品が busy の状態であるがどうかを判断することで、ほかのタイプの障害と区別することができます。

エラー

エラーが起きると、コマンドは -1 を返し、errno を設定します。上記のコマンドごとのエラーコードに加えて、すべてのコマンドに共通するエラーコードを以下に示します。

EFAULT: 引数に指定したアドレスが間違っています。
ENODEV: デバイスは電源管理することができないか、構成されていません。
ENXIO: デバイスを開く試行回数が多すぎます。

属性

以下の属性については、attributes(5) を参照してください。

属性タイプ	属性値
インタフェースの安定性	不安定 (廃止された IOCTLS のインタフェースは使用できません。)