libOGC  1.0
 All Data Structures Files Functions Variables Typedefs Macros Modules Pages
Macros | Typedefs | Functions
aram.h File Reference

ARAM subsystem. More...

#include <gctypes.h>

Macros

#define AR_ARAMINTALL   0
 
#define AR_ARAMINTUSER   1
 
#define AR_ARAMTOMRAM   1
 
#define AR_MRAMTOARAM   0
 
#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 More...
 

Functions

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

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]lenlength 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]flagspecifies the region of ARAM to clear
Returns
none
u32 AR_Free ( u32 len)

Free a block from ARAM.

Parameters
[out]lenpointer 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:

  • Disables ARAM DMA
  • Sets DMA callback to NULL
  • Initializes ARAM controller
  • Determines size of ARAM memory
  • Initializes the ARAM stack based memory allocation system

    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:

    1 #define MAX_NUM_BLOCKS 10
    2 
    3 u32 aram_blocks[MAX_NUM_BLOCKS];
    4 ...
    5 void func(void)
    6 {
    7  AR_Init(aram_blocks, MAX_NUM_BLOCKS);
    8 }
       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.<br>
       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:<br>
    
              AR_Init(NULL, 0);<br>
    
       The AR_Init() function also calculates the total size of the ARAM aggregate. Note that this procedure is <b><i>destructive</i></b> - i.e., any data stored in ARAM will be corrupted.<br>
       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_arraypointer to an array of u32 integer
[in]num_entriesnumber 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]callbackto 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:

  • Does not perform boundery-checking on addresses and lengths.
  • Will assert failure if a DMA is allready in progress.
  • Is provided for debugging purpose. Application programmers must use the ARQ API in order to access ARAM.
Parameters
[in]dirspecifies the direction of transfer.
[in]memaddrspecifies main memory address for the transfer
[in]aramaddrspecifies the ARAM address for the transfer. NOTE: Addresses are 27bits wide and refer to bytes
[in]lenspecifies the length of the block to transfer. NOTE: Must be in bytes and a multiple of 32
Returns
none