# PM_GetBattery

## 構文

      #include <nitro/spi.h>

      u32 PM_GetBattery( PMBattery* batteryBuf );

## 引数

batteryBuf | バッテリパックの電池残量状態を書き込むバッファ

## 返り値

PM_RESULT_SUCCESS ならば、コマンドの実行が成功したことを表します。

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

コマンドの実行が成功した場合、 batteryBuf に電池残量に関する情報が入ります。`PM_BATTERY_HIGH` の場合、電池残量がある程度あることを示し、`PM_BATTERY_LOW` の場合、電池残量が少なくなっていることを示します。

## 説明

バッテリーパックの電池残量を調べます。

batteryBuf は `PMBattery` 型へのポインタで、ここに結果が格納されます。

この関数を ARM9 から呼び出すと、PXI 経由で ARM7 にコマンドが送られます。それを受け取ったARM7 が電池残量を調べ、ARM9 に返します。

NITROの場合、ARM7は PMIC から電池残量の情報を取得します。VDET端子の検出電圧が閾値よりも高いか低いかによって 2段階で結果を返します。

TWLの場合、ARM7は マイコンから電池残量の情報を取得します。具体的には ARM7 で`PM_GetBatteryLevel()` に相当する値を取得し、その結果が 0〜1 か 2〜5 かで2段階の結果を返します。

butteryBuf に格納される値 | 意味 | NITROハードでの取得方法 LEDの状態 | TWLハードでの取得方法 LEDの状態
--- | --- | --- | ---
`PM_BATTERY_HIGH` | 電池残量がある程度あります。 | VDET端子の検出電圧が閾値以上 ■ 緑点灯 | `PM_GetBatteryLevel()` が 2〜5 ■ 青点灯 または ■ 赤点灯
`PM_BATTERY_LOW ` | 電池残量が少なくなっています。 | VDET端子の検出電圧が閾値以下 ■ 赤点灯 | `PM_GetBatteryLevel()` が 0〜1 ■■ 赤点滅

LED の色や点灯/点滅状態をアプリケーション側で制御することは出来ません。

電池残量が閾値近くの場合、スリープに入ると一時的にパワーランプ LED の色が変わる場合があります。例えば NITROハードウェアで動作していて LED が赤点灯している状況でスリープをすると一時的に緑に戻ることがあります。

割込みハンドラからこの関数を使用することは可能です。割込みハンドラ以外の割込み禁止状態でこの関数を使用することは出来ません。

PM_RESULT_BUSY について

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

従って、確実に本関数を成功させようとすれば、次のように成功するまでループするようにしてください。(引数が間違っているというようなミスは考慮していません。)

> (例)
> `while( PM_GetBattery( ... ) != PM_RESULT_SUCCESS )
> {
> }`

## 内部動作

(NITROの場合)
PMIC のレジスタ PMIC_STAT の値を読み込みます。
これはPMICのVDET 端子の検出電圧が閾値よりも高いか低いかを検知しています。

(TWLの場合)
マイコンが取得した電池残量を元に2段階で結果を返します。

## 参照

`PM_Init, PM_GetBatteryLevel`

## 履歴

2009/06/03 `PM_Init()` についての記述を削除 (`OS_Init()` が必須となったため)
2008/08/23 PM_RESULT_ERROR をやめて PM_RESULT_BUSY について言及した
2008/06/12 TWL の取得方法について説明
2005/07/07 返り値 PM_RESULT_ERRORについて言及した
2004/08/09 初版