# PM_ForceToPowerOff*

## 構文

      #include <nitro/spi.h>

      u32 PM_ForceToPowerOff( void );

      u32 PM_ForceToPowerOffAsync( PMCallback callback, void* arg );

## 引数

`PM_ForceToPowerOff()`
引数はありません。

`PM_ForceToPowerOffAsync()`

callback | コマンドが終了したときに呼ばれるコールバック
arg | コールバックを呼ぶ際の引数

## 返り値

`PM_ForceToPowerOff()
` 以前との互換性のために u32 型の返り値を持つ関数となっていますが、内部で成功するまでリトライし、その後ループしますので実際はこの関数から戻ることはありません。従って返り値を取得したり何かと比較したりすることに意味はありません。

`PM_ForceToPowerOffAsync()
` 非同期関数の場合、PM_RESULT_SUCCESS ならば、コマンドをARM7に送信することに成功したことを表します。ただし、電源がオフとなりますので実質的にはPM_RESULT_SUCCESS の後に何かをすることは出来ないでしょう。

PM_RESULT_BUSY を返した場合は、SPI が他の処理に占有されており処理できなかったことを示します。

## 説明

電源を強制的にオフにします。

この関数は ARM7 に該当動作を行うコマンドを PXI で送り、それを受け取った ARM7 側が PMIC を操作することで実行されます。従って関数を呼び出して即時に動作されるわけではありません。動作の終了まで待つ同期型の関数と、コマンドを ARM7 に送るだけの非同期型の関数が用意されていますので動作目的に合わせて使用してください。(関数名に Async がついているものが非同期関数です。)

同期関数では、成功するまで内部でリトライを繰り返します。そして成功した後はその場でループしますので、関数から戻ることはありません。戻らないのに関数の戻り値の型が u32 であるのは以前との互換性のためだけで、その値には意味はありませんし、関数から戻らないのでそもそも取得は出来ません。

非同期関数を呼び出した場合、ARM7側での処理が終了したときに指定のコールバック callback が呼び出されます。コールバックの型 `PMCallback` は

> `typedef void ( *PMCallback )( u32 result, void* arg );`

で定義されます。このコールバックは PXI 割り込みハンドラから呼び出されます。

コールバックの引数は、第一引数 result がコマンドの結果を表します。これは `PM_RESULT_SUCCESS` または `PM_RESULT_BUSY` となります。第二引数は arg を返します。

ただし、ARM7側で電源オフの処理が成功するとそれ以上の処理は行えませんので、実際には処理が失敗したときのみコールバック関数が実行されることになります。

この関数は割込みハンドラから呼び出すことが可能です。割り込みハンドラ以外の割込み禁止状態から呼び出すことも可能です。

PM_RESULT_BUSY について

SPI はPM以外にも様々な処理で使用されています。そのようなときに本関数を呼び出すと、ARM7 までコマンドを送り、そこで BUSY という判定が行われ、処理は行われずに ARM9 へ `PM_RESULT_BUSY` が通知されます。また他の PM 処理を行っている最中に本関数を呼び出すと、ARM9 側でそれを判断し `PM_RESULT_BUSY` を返します。(この場合は ARM7 への通知を行う前に判断します。)

同期関数では、それを考慮して成功するまで内部でリトライしますが、非同期関数では PM_RESULT_BUSY を返します。従って、非同期関数で確実に本関数を成功させようとすれば、BUSY だったときを考慮してリトライするようにしてください。

## 内部動作

PMIC のレジスタ PMIC_CTL を操作しています。

## 参照

`PM_Init
`

## 履歴

2009/06/03 `PM_Init()` についての記述を削除 (`OS_Init()` が必須となったため)
2008/08/23 PM_RESULT_BUSY について言及
2005/07/07 返り値 PM_RESULT_ERRORについて言及した
2005/06/02 コールバックの呼び元を明記した
2004/07/31 初版