# PM_GetAmpGainLevel

## 構文

      #include <twl/spi.h>

      u32 PM_GetAmpGainLevel( u8* levelBuf );

## 引数

levelBuf | アンプのゲインを決定する設定値の取得結果を格納するバッファ

## 返り値

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

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

## 説明

プログラマブルゲインアンプのゲインの、現在の設定を取得します。

levelBuf には `u8` 型の値が格納されます。値は 0 〜 119 の120段階で取得できます。

`levelBuf に格納される値` | ゲイン
--- | ---
0 | 10.5dB
1 | 11.0dB
2 | 11.5dB
： | ：
n | 10.5 + ( n x 0.5 ) dB
： | ：
119 | 70.0 dB

この関数はARM7に該当動作を行うコマンドをPXIで送り、それを受け取ったARM7側がPMICを操作することで実行されます。

PM_RESULT_BUSY について

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

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

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

`PM_GetAmpGain()` と `PM_GetAmpGainLevel()` の違い

ゲインの設定取得関数は、`PM_GetAmpGain()` と 本関数である `PM_GetAmpGainLevel()` の２種類が存在します。前者は 旧DS から存在している関数で、取得できるゲインは4段階です。 (設定できるゲインも4段階です。) 後者はこのリファレンスページで説明している TWL で新設された関数で、ゲインを 120 段階で取得することができます。

4 段階で取得する `PM_GetAmpGain()` はどのモードでも使用することが出来ます。

120 段階で取得する `PM_GetAmpGainLevel()` は TWL HYBRID か TWL LIMITED のときにしか使用することが出来ません。そして実際に内部で 120 段階で設定されているかどうかは、CODEC のモードによります。CODEC が TWL モードで動作している場合 (この場合の動作モードは必ず TWL モードのはずです。) は 120 段階で設定されています。

もし内部で 4段階で設定されている場合は、本関数で設定値を取得したときには、120段階に対応した値が返ることになっています。逆に 内部で 120 段階で設定されていて、`PM_GetAmpGain()` で 4段階で取得しようとした場合は、120 段階を 4つの区間に区切り、そのどこに含まれるかで 4 段階に落として値を返します。

以下は、内部で 4段階で設定されていて `PM_GetAmpGainLevel()` で 120 段階で値取得した場合の対応表です。

設定されていた値 | ゲイン(120段階)
--- | ---
`PM_AMPGAIN_20` | 31 (26.0 dB)
`PM_AMPGAIN_40` | 43 (32.0 dB)
`PM_AMPGAIN_80` | 55 (38.0 dB)
`PM_AMPGAIN_160` | 67 (44.0 dB)

値 31, 43, 55, 67 は順に、`PM_AMPGAIN_LEVEL_DS0`、`PM_AMPGAIN_LEVEL_DS1`、`PM_AMPGAIN_LEVEL_DS2`、`PM_AMPGAIN_LEVEL_DS3` と定数定義されています。

## 内部動作

NITRO ハードウェアでは PMIC のレジスタ PGA_GAIN の値を読み込みます。 TWL ハードウェアでは CODEC の値を読み込みます。

## 参照

`PM_Init, PM_SetAmpGainLevel*, PM_GetAmpGain
`

## 履歴

2009/06/03 `PM_Init()` についての記述を削除 (`OS_Init()` が必須となったため)
2008/08/23 PM_RESULT_BUSY について言及
2008/05/01 `PM_GetAmpGain()` から分岐