/*---------------------------------------------------------------------------*
  Project:  Horizon
  File:     dsp_Api.h

  Copyright (C)2009 Nintendo Co., Ltd.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

  $Rev: 29251 $
 *---------------------------------------------------------------------------*/

/*! @file
    @brief      DSP ライブラリの初期化、終了を行う API です。
 */
#ifndef NN_DSP_CTR_DSP_API_H_
#define NN_DSP_CTR_DSP_API_H_

#include <nn/Handle.h>

namespace nn {
namespace dsp {
namespace CTR {

namespace detail
{
    nn::Result InitializeBase(Handle* pSession, const char* name);
    nn::Result FinalizeBase  (Handle* pSession);
}

namespace
{
    const char PORT_NAME_DSP[]    = "dsp::DSP";
}

inline nn::Result InitializeIpc(Handle* pSession)    { return detail::InitializeBase(pSession, PORT_NAME_DSP); }
inline nn::Result FinalizeIpc  (Handle* pSession)    { return detail::FinalizeBase  (pSession); }

/*!
    @name     Initialize/Finalize
    @{
 */

/*!
    @brief      DSP ライブラリの初期化を行い、DSP プロセスとのセッションを確立します。
    @return     処理の結果が返ります。
 */
nn::Result    Initialize( void );

/*!
    @brief      DSP ライブラリを終了します。
    @return     なし。
 */
void          Finalize( void );

/*!
    @brief      DSP コンポーネントファイルをロードし、DSP を起動します。
    @param[in]  pComponent  コンポーネントファイルのアドレス。
    @param[in]  size        コンポーネントファイルのサイズ。
    @param[in]  maskPram    使用する DSP-Pram ブロックを指定します。LSB からMSB 方向にブロック0、1、...、7 を表します。8〜15 ビットは無効です。
    @param[in]  maskDram    使用する DSP-Dram ブロックを指定します。maskDram を参照。
    @return     処理の結果が返ります。
 */
nn::Result    LoadComponent( const u8 pComponent[], size_t size, bit16 maskPram = 0xff, bit16 maskDram = 0xff ) ;
nn::Result    LoadComponentCore( const u8 pComponent[], size_t size, bit16 maskPram = 0xff, bit16 maskDram = 0xff ) ;

/*!
    @brief      デフォルトの DSP コンポーネントファイル（サウンド）をロードし、DSP を起動します。
    @return     処理の結果が返ります。
 */
nn::Result    LoadDefaultComponent( void );

/*!
    @brief      DSP を停止します。
    @return     処理の結果が返ります。
 */
nn::Result    UnloadComponent( void );
nn::Result    UnloadComponentCore( void );

/*!
    @}
 */

/*!
    @name       CPU-DSP 間通信
    @{
 */

/*!
    @brief      DSP 割り込みを受信するためのイベントハンドルを DSP プロセスに登録します。
    @param[in]  handle      イベントオブジェクトのハンドル。
    @param[in]  type        割り込みタイプ。
    @param[in]  port        PIPE のポート番号（type が PIPE の場合のみ有効）。
    @return     処理の結果が返ります。
 */
nn::Result RegisterInterruptEvents(nn::Handle handle, s32 type, s32 port = 0);

/*!
    @brief      リプライレジスタの値を取得します。
    @param[in]  regNo       リプライレジスタ番号。
    @param[out] pValue      値を格納するアドレス。
    @return     処理の結果が返ります。
 */
nn::Result RecvData( u16 regNo, u16 *pValue );

/*!
    @brief      コマンドレジスタに値を設定します。
    @param[in]  regNo       コマンドレジスタ番号。
    @param[in]  value       設定する値。
    @return     処理の結果が返ります。
 */
nn::Result SendData( u16 regNo, u16 value );

/*!
    @brief      リプライレジスタに値が書き込まれているかどうかを確認します。
    @param[in]  regNo       リプライレジスタ番号。
    @param[out] pStatus     状態を格納するアドレス。
    @return     処理の結果が返ります。
 */
nn::Result RecvDataIsReady( u16 regNo, bool* pStatus );

/*!
    @brief      コマンドレジスタが読み込まれたかどうかを確認します。
    @param[in]  regNo       コマンドレジスタ番号。
    @param[out] pStatus     状態を格納するアドレス。
    @return     処理の結果が返ります。
 */
nn::Result SendDataIsEmpty( u16 regNo, bool * pStatus );

/*! :private
    @brief      DSP-Wram アドレスおよび連続領域アドレスの仮想アドレスを取得します。
    @param[in]  physicalAddress     物理アドレス。
    @param[out] pVirtualAddress     仮想アドレスの格納先。
    @return     処理の結果が返ります。
 */
nn::Result GetVirtualAddress(uptr physicalAddress, uptr * pVirtualAddress);

/*! :private
    @brief      DSP-Wram アドレスおよび連続領域アドレスの物理アドレスを取得します。
    @param[in]  virtualAddress      仮想アドレス。
    @param[out] pPhysicalAddress    物理アドレスの格納先。
    @return     処理の結果が返ります。
 */
nn::Result GetPhysicalAddress(uptr address, uptr * pPhysicalAddress);

/*! :private
    @brief      DSP 環境におけるアドレスを、CPU 環境におけるアドレスに変換します。
    @param[in]  addressOnDsp        DSP 環境におけるアドレス。
    @param[out] pAddressOnHost      CPU 環境におけるアドレスの格納先。
    @return     処理の結果が返ります。
 */
nn::Result ConvertProcessAddressFromDspDram(uptr addressOnDsp, uptr * pAddressOnHost);

/*!
    @brief      DSP pipe からデータを読みます。
    @param[in]  port        ポート番号。
    @param[in]  buffer      データを読み込むバッファのアドレス。
    @param[in]  length      読み込みデータ長。
    @param[out] pLengthRead 実際に読み込まれたデータ長の格納先。
    @return     処理の結果が返ります。
 */
nn::Result ReadPipeIfPossible( int port, void* buffer, u16 length, u16* pLengthRead );

/*!
    @brief      DSP pipe へデータを書きます。
    @param[in]  port        ポート番号。
    @param[in]  buffer      データを書き込むバッファのアドレス。
    @param[in]  length      書き込みデータ長。
    @return     処理の結果が返ります。
 */
nn::Result WriteProcessPipe( int port, const void *buffer, u32 length );

/*!
    @brief      セマフォのリクエストを取得します。
    @param[in]  pIsRequested        リクエストの有無。
    @return     処理の結果が返ります。
 */
nn::Result CheckSemaphoreRequest( bool* pIsRequested );

/*!
    @brief      セマフォをクリアします。
    @param[in]  mask        マスク。
    @return     処理の結果が返ります。
 */
nn::Result ClearSemaphore( u16 mask );

/*!
    @brief      セマフォのマスクを設定します。
    @param[in]  mask        マスク。
    @return     処理の結果が返ります。
 */
nn::Result MaskSemaphore( u16 mask );

/*!
    @brief      セマフォの値を取得します。
    @param[in]  pMask       値の格納先。
    @return     処理の結果が返ります。
 */
nn::Result GetSemaphore( u16* pMask );

/*!
    @brief      セマフォの値を設定します。
    @param[in]  mask        マスク。
    @return     処理の結果が返ります。
 */
nn::Result SetSemaphore( u16 mask );

/*!
    :private
    @brief      セマフォイベントのハンドルを取得します。
    @param[out] pHandle     値の格納先。
    @return     処理の結果が返ります。
 */
nn::Result GetSemaphoreEventHandle ( nn::Handle *);

/*!
    :private
    @brief      セマフォイベントで設定するマスクの値を設定します。
    @param[in]  mask        設定するマスクの値。
    @return     処理の結果が返ります。
 */
nn::Result SetSemaphoreEventMask ( bit16 );

/*!
    @}
 */

/*!
    @brief      指定された範囲のデータをキャッシュからメモリに書き戻し、キャッシュを無効にします。
    @param[in]  addr        先頭アドレス。
    @param[in]  size        サイズ。
    @return     処理の結果が返ります。
 */
nn::Result FlushDataCache( uptr addr, size_t size );

/*! :private
    @brief      指定された範囲のキャッシュを無効にします。
    @param[in]  addr        先頭アドレス。
    @param[in]  size        サイズ。
    @return     処理の結果が返ります。
 */
nn::Result InvalidateDataCache( uptr addr, size_t size );

/*! :private
    @brief      DSP にコンポーネントがロードされているかどうかを確認します。
    @return     ロードされていれば true を、されていなければ false を返します。
 */
bool IsComponentLoaded(void);

/*!
    @brief      DSP で行っている処理を一時中断し、終了処理を行います。
    @return     実際にスリープ処理が行われば場合は true を、何もしなかった場合は false を返します。
 */
bool Sleep(void);

/*!
    @brief      一時中断した DSP の処理を復元します。
    @brief      なし。
 */
void WakeUp(void);

/*! :private
    @brief      システムのスリープから復帰します。
 */
void Awake();

/*! :private
    @brief      終了処理のための準備を行います。
 */
void OrderToWaitForFinalize();

/*! :private
    @brief      Sleep, WakeUp, OrderToWaitForFinalize 時に呼ばれるコールバックを設定します。
    @param[in]  sleepCallback                   Sleep 時のコールバック
    @param[in]  wakeUpCallback                  WakeUp 時のコールバック
    @param[in]  orderToWaitForFinalizeCallback  OrderToWaitForFinalize 時のコールバック
    @return     コールバックの設定に成功したら true を、失敗したら false を返します。
 */
bool RegisterSleepWakeUpCallback(
    void (*sleepCallback)(),
    void (*wakeUpCallback)(),
    void (*orderToWaitForFinalizeCallback)() = NULL
);

/*! :private
    @brief      Sleep, WakeUp, OrderToWaitForFinalize 時に呼ばれるコールバックを無効にします。
    @param[in]  sleepCallback                   Sleep 時のコールバック
    @param[in]  wakeUpCallback                  WakeUp 時のコールバック
    @param[in]  orderToWaitForFinalizeCallback  OrderToWaitForFinalize 時のコールバック
    @return     コールバックの無効化に成功したら true を、失敗したら false を返します。
 */
bool ClearSleepWakeUpCallback(
    void (*sleepCallback)(),
    void (*wakeUpCallback)(),
    void (*orderToWaitForFinalizeCallback)() = NULL
);

/*!
    @brief      ヘッドホンの挿入状態を取得します。
    @param[out] isConnected     挿入されていれば true が返ってきます。
    @return     処理の結果が返ります。
 */
nn::Result GetHeadphoneStatus(bool* isConnected);

/*! :private
    @brief      蓋閉じ時に強制的にヘッドフォン出力にするかどうかを設定します。
    @param[in]  forceout        true なら強制ヘッドフォン出力とします。
    @return     処理の結果が返ります。
 */
Result ForceHeadphoneOut(bool forceout);

/*!
    :private
    @brief      DSP が占有状態を取得します。
    @return     占有されていれば true を、そうでなければ false を返します。
 */
bool IsDspOccupied(void);

} // namespace CTR {
} // namespace dsp {
} // namespace nn  {

#endif  // ifndef NN_DSP_CTR_DSP_API_H_