/*---------------------------------------------------------------------------*
  Project:  CtrBrom - OS - include
  File:     spinLock.h

  Copyright 2009 Nintendo.  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.

  $Date::            $
  $Rev$
  $Author$
 *---------------------------------------------------------------------------*/
#ifndef BROM_OS_SPINLOCK_H_
#define BROM_OS_SPINLOCK_H_

#include <brom/types.h>
#include <brom/memorymap.h>

#ifdef __cplusplus
extern "C" {
#endif

//======================================================================
//                      ロック変数
//
//・カード／カートリッジ／ＣＰＵ間共有内部ワークＲＡＭ／ＶＲＡＭ−Ｃ／Ｄ
//  などのＣＰＵ間での共有リスースや、ＣＰＵ間送信ＦＩＦＯ 等の専有リソース
//  の排他制御ためにこの関数をご使用下さい。
//======================================================================

// ロックＩＤ

#define OS_UNLOCK_ID            0      // ロック変数がロックされていない場合のＩＤ
#define OS_MAINP_LOCKED_FLAG    0x40   // メインプロセッサによるロック確認フラグ
#define OS_MAINP_LOCK_ID_START  0x40   // メインプロセッサ用ロックＩＤの割り当て開始番号
#define OS_MAINP_LOCK_ID_END    0x6f   //                               割り当て終了番号
#define OS_MAINP_DBG_LOCK_ID    0x70   //                               デバッガ予約番号
#define OS_MAINP_SYSTEM_LOCK_ID 0x7f   //                               システム予約番号
#define OS_SUBP_LOCKED_FLAG     0x80   //   サブプロセッサによるロック確認フラグ
#define OS_SUBP_LOCK_ID_START   0x80   //   サブプロセッサ用ロックＩＤの割り当て開始番号
#define OS_SUBP_LOCK_ID_END     0xaf   //                               割り当て終了番号
#define OS_SUBP_DBG_LOCK_ID     0xb0   //                               デバッガ予約番号
#define OS_SUBP_SYSTEM_LOCK_ID  0xbf   //                               システム予約番号

#define OS_LOCK_SUCCESS         0      // ロック成功
#define OS_LOCK_ERROR           (-1)   // ロックエラー

#define OS_UNLOCK_SUCCESS       0      // ロック解除成功
#define OS_UNLOCK_ERROR         (-2)   // ロック解除エラー

#define OS_LOCK_FREE            0      // ロック解除中

#define OS_LOCK_ID_ERROR        (-3)   // ロックＩＤエラー


//---- structure of lock variable 
typedef volatile struct OSLockByte
{
    u8      lockFlag;
    u8      ownerID;
}
OSLockByte;

/*---------------------------------------------------------------------------*
  Name:         osInitLock

  Description:  initialize system lock variable 
                and privilege to access shared resources

                * cartridge exclusive control area is not cleared 
                  because debugger uses.

  Arguments:    None.

  Returns:      None.
 *---------------------------------------------------------------------------*/
void    osInitLock(void);

//----------------------------------------------------------------------
//          スピンロック
//
//・プロセッサ間やモジュール間で共有リソースを排他制御するための
//  ロック変数のスピンロックを行います。
//・ロックが成功するまで試行し続けます。
//・プロセッサ間の共有リソースは必ずロック後に使用して下さい。
//・プロセッサ専有のリソースはタイミング的に調整できるのであれば
//  ロックしなくても構いません。
//  専有リソースはデバッグ時に限定してロックすることもできます。
//
//・引数：
//  lockID              ロックID
//  lockp               ロック変数のポインタ
//
//・戻り値：
//  OS_LOCK_SUCCESS     ロック成功
//----------------------------------------------------------------------
s32     osLockByByte(u8 lockID, OSLockByte *lockp, void (*ctrlFuncp) (void));
s32     osLockCard(u8 lockID);

//----------------------------------------------------------------------
//          ロックの解除
//
//・ロックを解除し、共有リソースのアクセス権をサブプロセッサに渡します。
//・ロックしていないモジュールが実行した場合には解除されず、
//  OS_UNLOCK_ERROR が返されます。
//
//・引数：
//  lockID              ロックID
//  lockp               ロック変数のポインタ
//
//・戻り値：
//  OS_UNLOCK_SUCCESS   ロック解除成功
//  OS_UNLOCK_ERROR     ロック解除エラー
//----------------------------------------------------------------------
s32     osUnlockByByte(u8 lockID, OSLockByte *lockp, void (*ctrlFuncp) (void));
s32     osUnlockCard(u8 lockID);

//----------------------------------------------------------------------
//          ロックの試行
//
//・１回だけスピンロックを試行します。
//・プロセッサ間の共有リソースは必ずロック後に使用して下さい。
//・プロセッサ専有のリソースはタイミング的に調整できるのであれば
//  ロックしなくても構いません。
//  専有リソースはデバッグ時に限定してロックすることもできます。
//
//・引数：
//  lockID              ロックID
//  lockp               ロック変数のポインタ
//  CtrlFuncp           リソース制御関数のポインタ
//
//・戻り値：
//  正                  ロック中（直前に格納されていたID）
//  OS_LOCK_SUCCESS     ロック成功
//----------------------------------------------------------------------
s32     osTryLockByByte(u8 lockID, OSLockByte *lockp, void (*crtlFuncp) (void));
s32     osTryLockCard(u8 lockID);

//----------------------------------------------------------------------
//          ロック変数の所有モジュールIDの読み込み
//
//・ロック変数の所有モジュールID を読み込みます。
//・モジュールID が非0 の場合はその時点でどちらのプロセッサ側が
//  所有権を持っているのかを確認できます。
//・共有リソースの場合は「メインプロセッサ側が所有権を持っている状態」
//  のみを割り込みを禁止することによって維持することができます。
//  その他の状態はサブプロセッサが変化させてしまう可能性があります。
//・所有モジュールID が 0 であってもロック変数が解除されているとは限りません。
//
//・引数：
//  lockp       ロック変数のポインタ
//
//・戻り値：    所有モジュールID
//
//※但し、メインメモリに対してはキャッシュ経由でなければ
//  バイトアクセスはできないことに注意して下さい。
//  ですので、メインメモリ上では基本的に osReadOwnerOfLockWord() を使用して下さい。
//----------------------------------------------------------------------
u8     osReadOwnerOfLockWord(OSLockByte *lockp);
#define osReadOwnerOfLockCard()       osReadOwnerOfLockWord( (OSLockByte *)HW_CARD_LOCK_BUF  )



/*---------------------------------------------------------------------------*
  Name:         osGetLockID

  Description:  get lock ID

  Arguments:    None.

  Returns:      OS_LOCK_ID_ERROR, if fail to get ID

                if ARM9
                   0x40〜0x6f       lockID
                else if ARM7
                   0x80〜0xaf       lockID
                endif

                *Notice:  ID is allocated only 48 pattern at a highest.

 *---------------------------------------------------------------------------*/
s32     osGetLockID(void);


/*---------------------------------------------------------------------------*
  Name:         osReleaseLockID

  Description:  release lock ID

  Arguments:    lockID : id to tend to release

  Returns:      None.
 *---------------------------------------------------------------------------*/
void    osReleaseLockID(u8 lockID);



//================================================================
//   private function.
//   This function is for internal use. Never call from application.
#define OSi_SYNCTYPE_SENDER 0
#define OSi_SYNCTYPE_RECVER 1

#define OSi_SYNCVAL_NOT_READY 0
#define OSi_SYNCVAL_READY     1

void OSi_SyncWithOtherProc( int type, void* syncBuf );

static inline void OSi_SetSyncValue( u8 n )
{
	*(vu8*)(HW_INIT_LOCK_BUF+4) = n;
}
static inline u8 OSi_GetSyncValue( void )
{
	return *(vu8*)(HW_INIT_LOCK_BUF+4);
}



//--------------------------------------------------------------------------------
#ifdef __cplusplus
} /* extern "C" */
#endif

/* BROM_OS_SPINLOCK_H_ */
#endif