# PM_SetBackLight*

## 構文

      #include <nitro/spi.h>

      u32 PM_SetBackLight( PMLCDTarget target, PMBackLightSwitch sw );

      u32 PM_SetBackLightAsync( PMLCDTarget target, PMBackLightSwitch sw, PMCallback callback, void* arg );

## 引数

target | 操作対象となる画面
sw | バックライトスイッチ
callback | コマンドが終了したときに呼ばれるコールバック
arg | コールバックを呼ぶ際の引数

## 返り値

PM_RESULT_SUCCESS ならば、コマンドの実行が成功した(同期関数の場合)か、コマンドをARM7に送信することに成功した(非同期関数の場合)ことを表します。

PM_INVALID_COMMAND ならば、与えた引数が指定可能なものではないことを示します。

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

## 説明

指定の画面のバックライトスイッチを切り替えます。

target は `PMLCDTarget` 列挙型の値で、以下のいずれかを指定してください。

`target の値` | 対象の LCD
--- | ---
`PM_LCD_TOP` | 上画面
`PM_LCD_BOTTOM` | 下画面
`PM_LCD_ALL` | 上画面と下画面

sw は `PMBackLightSwitch` 列挙型の値で、以下のいずれかを指定してください。

`sw の値` | バックライト処理
--- | ---
`PM_BACKLIGHT_OFF` | バックライトを消灯します。
`PM_BACKLIGHT_ON` | バックライトを点灯します。

target で指定される画面に対して sw で指定される操作を行います。

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

非同期関数について

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

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

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

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

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

PM_RESULT_BUSY について

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

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

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

Async 関数を用いる場合は例えば以下のように記述できます。

> (例)`
> void setResult( u32 result, void* arg )
> {
> if ( arg )
> {
> *(u32*)arg = result;
> }
> }
> while(1)
> {
> volatile u32 result = PM_RESULT_NONE; //結果としては返らない値
> while ( PM_SetBackLightAsync(..., setResult, (void*)&result ) != PM_RESULT_SUCCESS )
> {
> }
> // 別の処理など
> otherProcess();
> // 処理終了待ち
> while( result == PM_RESULT_NONE )
> {
> }
> // 成功したならループから抜ける
> if ( result == PM_RESULT_SUCCESS )
> {
> break;
> }
> }`

## 内部動作

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

## 参照

`PM_Init, PM_GetBackLight`

## 履歴

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