/*---------------------------------------------------------------------------*
  Project:  NitroSDK - CARD - include
  File:     rom.h

  Copyright 2004-2004 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.

  $Log: rom.h,v $
  Revision 1.11  2004/11/02 10:07:30  yosizaki
  fix comment.

  Revision 1.10  2004/09/06 13:44:31  yosizaki
  move CARD_(Lock/Unlock)Backup

  Revision 1.9  2004/09/03 07:19:12  yosizaki
  fix include directives.

  Revision 1.8  2004/09/03 06:50:43  yosizaki
  add CARD_GetRomRegionOVT.

  Revision 1.7  2004/07/23 08:32:14  yosizaki
  small fix.

  Revision 1.6  2004/07/19 13:10:47  yosizaki
  change interface.

  Revision 1.5  2004/07/10 10:20:47  yosizaki
  add CARD_LockBackup()

  Revision 1.4  2004/07/09 08:40:13  yosizaki
  change implement of synchronous mode.

  Revision 1.3  2004/07/08 13:47:42  yosizaki
  change CARD_ReadRom (for fs_rom)

  Revision 1.2  2004/07/05 08:10:41  yosizaki
  add comment.
  include card/common.h

  Revision 1.1  2004/06/28 01:55:02  yosizaki
  (none)

  $NoKeywords: $
 *---------------------------------------------------------------------------*/


#if	!defined(NITRO_CARD_ROM_H_)
#define NITRO_CARD_ROM_H_


#if	defined(__cplusplus)
extern "C" {
#endif


#include <nitro/misc.h>
#include <nitro/types.h>
#include <nitro/memorymap.h>
#include <nitro/mi/dma.h>
#include <nitro/mi/exMemory.h>
#include <nitro/os.h>

#include <nitro/card/common.h>


/********************************************************************
 * constants
 ********************************************************************/

/* ROM Header Region Information Structure */
typedef	struct
{
	u32	offset;
	u32	length;
} CARDRomRegion;

/* ROM Area Size */
#define CARD_ROM_PAGE_SIZE	512


/********************************************************************
 * functions
 ********************************************************************/

/* rom-access *******************************************************/


/* Obtain FNT region information of ROM header. */
static inline const CARDRomRegion*	CARD_GetRomRegionFNT(void)
{
	return	(const CARDRomRegion*)((const u8*)HW_ROM_HEADER_BUF + 0x40);
}

/* Obtain FAT region information of ROM header. */
static inline const CARDRomRegion*	CARD_GetRomRegionFAT(void)
{
	return	(const CARDRomRegion*)((const u8*)HW_ROM_HEADER_BUF + 0x48);
}

/* Obtain OVT region information of ROM header */
static inline const CARDRomRegion*	CARD_GetRomRegionOVT(MIProcessor target)
{
	return	(target == MI_PROCESSOR_ARM9) ?
		(const CARDRomRegion*)((const u8*)HW_ROM_HEADER_BUF + 0x50) :
		(const CARDRomRegion*)((const u8*)HW_ROM_HEADER_BUF + 0x58);
}


/*
 *	The following functions provide low level access to the device 
 *      on the card. When using them, make sure you self-manage the 
 *	settings of the predefined bus.
 *
 *	The access target is changed to the cartridge internally 
 *	in the TEG and cartridge environment so the same processing is 
 *	possible excluding operating characteristics.
 *
 *	CARD_LockRom() / CARD_UnlockRom() /
 *	CARD_LockBackup() / CARD_UnlockBackup() determine dynamically if 
 *	OS_LockCard() or OS_LockCartridge() should be used and call the 
 *	appropriate function.
 *	To prevent access at same time to ROM and backup, exclusive access
 *	control is carried out internally.
 */

#if	!defined(SDK_TS)
static inline BOOL	CARDi_IsTrueRom(void)
{
	return	(OS_GetConsoleType() & OS_CONSOLE_DEV_CARD) != 0;
}
#endif

/*
 * Lock access target of CARD API.
 * ROM and backup device go under exclusive control.
 */
void	CARD_LockRom(u16 lock_id);
void	CARD_UnlockRom(u16 lock_id);

/*
 * CARD-ID read
 * CARD-ID is the value uniquely allocated to the NITRO-CARD media.
 */
u32	CARD_ReadRomID(void);


/*
 *	The following are the synchronized/asynchronized that read access ROM.
 *	Control of the hardware in the function is as follows:
 *
 *	- If DMA is specified, use after explicitly stopping with MI_StopDma().
 *	- Use CPU transfer if DMA is specified outside of range.
 *	- If previous access is not complete, block until done.
 *
 *	The card transfer speed is a maximum of 5.94[MB/s], but 
 *	with the actual API a certain amount of overhead is included.
 *	With synchronized transfer by the CPU, around 100% speed can be 
 *	realized. With asynchronized DMA, it drops to 90 - 95%, but for a   
 *	great deal of time during transfer the CPU can be run in parallel.
 *	This maximum value is limited to situations in which the transfer
 *      conditions are ideal.
 */

void	CARDi_ReadRom(u32 dma,
	const void *src, void *dst, u32 len,
	MIDmaCallback callback, void *arg, BOOL is_async);

/*
 * Verification of completion of CARD ROM asynchronized read
 * Return FALSE if continue to call CARD_ReadRomAsync and processing is incomplete.
 */
BOOL	CARD_TryWaitRomAsync(void);

/*
 * Wait for end of CARD ROM asynchronized read
 * Block if continue to call CARD_ReadRomAsync and processing is incomplete.
 */
void	CARD_WaitRomAsync(void);

/* CARD ROM read (asynchronized) */
static inline void	CARD_ReadRomAsync(u32 dma,
	const void *src, void *dst, u32 len,
	MIDmaCallback callback, void *arg)
{
	CARDi_ReadRom(dma, src, dst, len, callback, arg, TRUE);
}

/* CARD ROM read (synchronized) */
static inline void	CARD_ReadRom(u32 dma, const void *src, void *dst, u32 len)
{
	CARDi_ReadRom(dma, src, dst, len, NULL, NULL, FALSE);
}



/* I/O processror ***************************************************/

#if	defined(SDK_TEG) && defined(SDK_ARM7)

void	CARDi_CreatePxiRecvThread(u32 priority);

#endif	/* defined(SDK_TEG) && defined(SDK_ARM7) */


#if	defined(__cplusplus)
}	/* extern "C" */
#endif


/* NITRO_CARD_ROM_H_ */
#endif
