aram.h File Reference

ARAM subsystem. More...

#include <gctypes.h>

Defines

#define AR_MRAMTOARAM   0
#define AR_ARAMTOMRAM   1
#define AR_ARAMINTALL   0
#define AR_ARAMINTUSER   1
#define AR_StartDMARead(maddr, araddr, tlen)   AR_StartDMA(AR_ARAMTOMRAM,maddr,araddr,tlen);
 Wraps the DMA read operation done by AR_StartDMA().
#define AR_StartDMAWrite(maddr, araddr, tlen)   AR_StartDMA(AR_MRAMTOARAM,maddr,araddr,tlen);
 Wraps the DMA write operation done by AR_StartDMA().

Typedefs

typedef void(*) ARCallback (void)
 function pointer typedef for the user's ARAM interrupt callback

Functions

ARCallback AR_RegisterCallback (ARCallback callback)
 Register the given function as a DMA callback.
u32 AR_GetDMAStatus ()
 Get current status of DMA.
u32 AR_Init (u32 *stack_idx_array, u32 num_entries)
 Initializes ARAM subsystem.
void AR_StartDMA (u32 dir, u32 memaddr, u32 aramaddr, u32 len)
 Initiates a DMA between main memory and ARAM.
u32 AR_Alloc (u32 len)
 Allocate a block of memory from ARAM having len bytes.
u32 AR_Free (u32 *len)
 Free a block from ARAM.
void AR_Clear (u32 flag)
 Clear ARAM memory.
BOOL AR_CheckInit ()
 Get the ARAM subsystem initialization flag.
void AR_Reset ()
 Clears the ARAM subsystem initialization flag.
u32 AR_GetSize ()
 Get the total size - in bytes - of ARAM as calculated during AR_Init().
u32 AR_GetBaseAddress ()
 Get the baseaddress of ARAM memory.
u32 AR_GetInternalSize ()
 Get the size of the internal ARAM memory.


Detailed Description

ARAM subsystem.


Typedef Documentation

void(* ARCallback)(void)

function pointer typedef for the user's ARAM interrupt callback

Parameters:
none 


Function Documentation

u32 AR_Alloc ( u32  len  ) 

Allocate a block of memory from ARAM having len bytes.

The len parameter must be a multiple of 32

Parameters:
[in] len length of the specified block of memory in ARAM
Returns:
address of the block if successful, otherwise NULL

BOOL AR_CheckInit (  ) 

Get the ARAM subsystem initialization flag.

Returns:
TRUE if the ARAM subsystem has been initialized(via AR_Init())
FALSE if the ARAM subsystem has not been initialized, or has been reset(via AR_Reset())

void AR_Clear ( u32  flag  ) 

Clear ARAM memory.

Parameters:
[in] flag specifies the region of ARAM to clear
Returns:
none

u32 AR_Free ( u32 len  ) 

Free a block from ARAM.

Parameters:
[out] len pointer to receive the length of the free'd ARAM block. This is optional and can be NULL.
Returns:
ARAM current baseaddress after free'ing the block

u32 AR_GetBaseAddress (  ) 

Get the baseaddress of ARAM memory.

Returns:
ARAM memory baseaddress

u32 AR_GetDMAStatus (  ) 

Get current status of DMA.

Returns:
zero if DMA is idle, non-zero if a DMA is in progress

u32 AR_GetInternalSize (  ) 

Get the size of the internal ARAM memory.

Returns:
ARAM internal memory size

u32 AR_GetSize (  ) 

Get the total size - in bytes - of ARAM as calculated during AR_Init().

Returns:
size of the specified ARAM block

u32 AR_Init ( u32 stack_idx_array,
u32  num_entries 
)

Initializes ARAM subsystem.

Following tasks are performed:

The parameter u32 *stack_idx_array points to an array of u32 integers. The parameter u32 num_entries specifies the number of entries in this array.
The user application is responsible for determining how many ARAM blocks the device driver can allocate.

As an example, consider:

        #define MAX_NUM_BLOCKS 10

        u32 aram_blocks[MAX_NUM_BLOCKS];
        ...
        void func(void)
        {
           AR_Init(aram_blocks, MAX_NUM_BLOCKS);
        }

Here, we are telling AR that the application will allocate, at most, 10 blocks (of arbitrary size), and that AR should store addresses for those blocks in the array aram_blocks. Note that the array is simply storage supplied by the application so that AR can track the number and size of memory blocks allocated by AR_Alloc(). AR_Free()also uses this array to release blocks.
If you do not wish to use AR_Alloc() and AR_Free() and would rather manage ARAM usage within your application, then call AR_Init() like so:

AR_Init(NULL, 0);

The AR_Init() function also calculates the total size of the ARAM aggregate. Note that this procedure is destructive - i.e., any data stored in ARAM will be corrupted.
AR_Init()may be invoked multiple times. This function checks the state of an initialization flag; if asserted, this function will simply exit on subsequent calls. To perform another initialization of the ARAM driver, call AR_Reset() before invoking AR_Init() again.

Parameters:
[in] stack_idx_array pointer to an array of u32 integer
[in] num_entries number of entries in the specified array
Returns:
base address of the "user" ARAM area. As of this writing, the operating system reserves the bottom 16 KB of ARAM. Therefore, AR_Init() returns 0x04000 to indicate the starting location of the ARAM user area.

ARCallback AR_RegisterCallback ( ARCallback  callback  ) 

Register the given function as a DMA callback.

Any existing callback is replaced unconditionally

Parameters:
[in] callback to be invoked upon completion of DMA transaction
Returns:
pointer to the previously registered callback and NULL respectively

void AR_Reset (  ) 

Clears the ARAM subsystem initialization flag.

Calling AR_Init() after this function will cause a "real" initialization of ARAM

Returns:
none

void AR_StartDMA ( u32  dir,
u32  memaddr,
u32  aramaddr,
u32  len 
)

Initiates a DMA between main memory and ARAM.

This function:

Parameters:
[in] dir specifies the direction of transfer.
[in] memaddr specifies main memory address for the transfer
[in] aramaddr specifies the ARAM address for the transfer. NOTE: Addresses are 27bits wide and refer to bytes
[in] len specifies the length of the block to transfer. NOTE: Must be in bytes and a multiple of 32
Returns:
none


Generated on Sun Feb 4 18:14:34 2007 for libOGC by  doxygen 1.4.7