aram.h File Reference

ARAM subsystem. More...

#include <gctypes.h>
#include <gcbool.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 (void)
	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 (void)
	Get the baseaddress of ARAM memory. More...
u32	AR_GetDMAStatus (void)
	Get current status of DMA. More...
u32	AR_GetInternalSize (void)
	Get the size of the internal ARAM memory. More...
u32	AR_GetSize (void)
	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 (void)
	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

ARCallback

void(* ARCallback)(void)

function pointer typedef for the user's ARAM interrupt callback

Parameters

none

Function Documentation

AR_Alloc()

u32 AR_Alloc

(

u32

len

)

Allocate a block of memory from ARAM having len bytes.

   The <i>len</i> parameter <b><i>must</i></b> 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

AR_CheckInit()

BOOL AR_CheckInit

(

void

)

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())

AR_Clear()

void AR_Clear

(

u32

flag

)

Clear ARAM memory.

Parameters

[in]

flag

specifies the region of ARAM to clear

Returns

none

AR_Free()

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

AR_GetBaseAddress()

u32 AR_GetBaseAddress

(

void

)

Get the baseaddress of ARAM memory.

Returns

ARAM memory baseaddress

AR_GetDMAStatus()

u32 AR_GetDMAStatus

(

void

)

Get current status of DMA.

Returns

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

AR_GetInternalSize()

u32 AR_GetInternalSize

(

void

)

Get the size of the internal ARAM memory.

Returns

ARAM internal memory size

AR_GetSize()

u32 AR_GetSize

(

void

)

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

Returns

size of the specified ARAM block

AR_Init()

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<br>

   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.<br>
   The user application is responsible for determining how many ARAM blocks the device driver can allocate.<br>

   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.<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_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.

AR_RegisterCallback()

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

AR_Reset()

void AR_Reset

(

void

)

Clears the ARAM subsystem initialization flag.

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

Returns

none

AR_StartDMA()

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

Initiates a DMA between main memory and ARAM.

   This function:

 - Does <b><i>not</i></b> 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]	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