Codec Engine OSAL - Memory

Data Structures
struct	Memory_AllocParams
	Parameters for Memory_alloc() & Memory_free(). More...
Defines
#define	Memory_DEFAULTALIGNMENT   ((UInt)(-1))
#define	Memory_GTNAME   "OM"
#define	Memory_CACHED   0x00000000
#define	Memory_NONCACHED   0x00000001
#define	Memory_CACHEDMASK   0x00000001
Enumerations
enum	Memory_type {   Memory_MALLOC = 0,   Memory_SEG = 1,   Memory_CONTIGPOOL = 2,   Memory_CONTIGHEAP = 3 }
	Enum values for Memory_AllocParams.type. More...
Functions
Ptr	Memory_alloc (UInt size, Memory_AllocParams *params)
	General memory allocation.
Void	Memory_cacheInv (Ptr addr, Int sizeInBytes)
	Invalidate a range of cache.
Void	Memory_cacheWb (Ptr addr, Int sizeInBytes)
	Write back cache.
Void	Memory_cacheWbInv (Ptr addr, Int sizeInBytes)
	Write back and invalidate cache.
Ptr	Memory_contigAlloc (UInt size, UInt align)
	Allocate physically contiguous blocks of memory.
Bool	Memory_contigFree (Ptr addr, UInt size)
	Free memory allocated by Memory_contigAlloc().
Bool	Memory_free (Ptr addr, UInt size, Memory_AllocParams *params)
	Free memory allocated with Memory_alloc().
Void	Memory_dumpKnownContigBufsList (Void)
	Dumps the list of all translated/registered bufs.
UInt32	Memory_getBufferPhysicalAddress (Ptr virtualAddress, Int sizeInBytes, Bool *isContiguous)
	Converts application virtual address to a physical address.
Int	Memory_getHeapId (String name)
	Get the heap heap ID corresponding to a heap name. This number will be between 0 and the value returned by Memory_getNumHeaps(). The heap Id can be passed to Memory_redefine(), Memory_restoreHeap(), and Memory_segStat().
Int	Memory_getNumHeaps ()
	Get the number of memory heaps.
Ptr	Memory_getBufferVirtualAddress (UInt32 physicalAddress, Int sizeInBytes)
	Obtains the virtual address of a physically contiguous buffer.
Void	Memory_registerContigBuf (UInt32 virtualAddress, UInt32 sizeInBytes, UInt32 physicalAddress)
	Register a physical buffer allocated without Memory_contigAlloc().
Void	Memory_unregisterContigBuf (UInt32 virtualAddress, UInt32 sizeInBytes)
	Unregisters a physical buffer allocated without Memory_contigAlloc().
Variables
Memory_AllocParams	Memory_DEFAULTPARAMS
	Default parameters for Memory_alloc() & Memory_free().

---

Define Documentation

#define Memory_DEFAULTALIGNMENT   ((UInt)(-1))

#define Memory_GTNAME   "OM"

#define Memory_CACHED   0x00000000

Cached allocation.

See also:

Memory_AllocParams.flags

#define Memory_NONCACHED   0x00000001

Non-cached allocation.

See also:

Memory_AllocParams.flags

#define Memory_CACHEDMASK   0x00000001

Mask to isolate cache flag.

See also:

Memory_AllocParams.flags

---

Enumeration Type Documentation

enum Memory_type

Enum values for Memory_AllocParams.type.

See also:

Memory_AllocParams

Enumerator:

Memory_MALLOC	malloc()-based allocation
Memory_SEG	DSP/BIOS segment-based allocation
Memory_CONTIGPOOL	Contiguous, pool-based allocation
Memory_CONTIGHEAP	Contiguous, heap-based allocation

---

Function Documentation

Ptr Memory_alloc	(	UInt	size,
		Memory_AllocParams *	params
	)

General memory allocation.

Parameters:

[in]	size	Number of bytes to allocate.
[in]	params	Parameters controlling the allocation.

Return values:

	NULL	The memory request failed.
	non-NULL	The pointer to a buffer containing the requested memory.

See also:

Memory_free()

Memory_contigAlloc()

Void Memory_cacheInv	(	Ptr	addr,
		Int	sizeInBytes
	)

Invalidate a range of cache.

Parameters:

[in]	addr	Address of the beginning of the buffer to invalidate.
[in]	sizeInBytes	Size of the buffer to invalidate.

Remarks:

In addition to application usage, this is often called by a skeleton implementor after it has received a shared memory buffer from another processor, and before it invokes an algorithm's interface which will operate on that shared memory buffer.

See also:

Memory_cacheWb()

Memory_cacheWbInv()

Void Memory_cacheWb	(	Ptr	addr,
		Int	sizeInBytes
	)

Write back cache.

Parameters:

[in]	addr	Address of the beginning of the buffer to writeback.
[in]	sizeInBytes	Size of the buffer to writeback.

See also:

Memory_cacheInv()

Memory_cacheWbInv()

Void Memory_cacheWbInv	(	Ptr	addr,
		Int	sizeInBytes
	)

Write back and invalidate cache.

Parameters:

[in]	addr	Address of the beginning of the buffer to writeback and invalidate.
[in]	sizeInBytes	Size of the buffer to writeback invalidate.

See also:

Memory_cacheInv()

Memory_cacheWb()

Ptr Memory_contigAlloc	(	UInt	size,
		UInt	align
	)

Allocate physically contiguous blocks of memory.

Deprecated:

This function has been superceded by Memory_alloc() and will be removed in a future release. Users are recommended to modify their applications to use the new, more flexible Memory_alloc() instead.

Parameters:

[in]	size	Size of the buffer to allocate.
[in]	align	Alignment of the buffer; must be divisible by a power of two.

Precondition:

align must be divisible by a power of two.

Return values:

	non-NULL	Address of a physically contiguous buffer.
	NULL	Unable to obtain the requested buffer.

Remarks:

This is commonly called by an application wishing to obtain a physically contiguous buffer which it must share with another processor.

For portability reasons, applications commonly use this API even in environments which do not have virtual memory or an MMU (e.g. a single processor, DSP/BIOS based system). Doing so makes them portable to environments which do have to provide physically contiguous memory to remote processors.

See also:

Memory_alloc()

Memory_contigFree()

Bool Memory_contigFree	(	Ptr	addr,
		UInt	size
	)

Free memory allocated by Memory_contigAlloc().

Parameters:

[in]	addr	Address of a buffer allocated by Memory_contigAlloc()
[in]	size	Size of the buffer to free.

Return values:

	TRUE	The buffer was freed and the memory pointed to by addr is no longer valid.
	FALSE	The buffer couldn't be freed.

Precondition:

addr must be a valid address returned by Memory_contigAlloc()

size must be equivalent to the size passed in during the Memory_contigAlloc() allocation.

See also:

Memory_contigAlloc()

Bool Memory_free	(	Ptr	addr,
		UInt	size,
		Memory_AllocParams *	params
	)

Free memory allocated with Memory_alloc().

Parameters:

[in]	addr	Address of a buffer allocated by Memory_alloc().
[in]	size	Size of the buffer to free.
[in]	params	Parameters controlling the free operation.

Return values:

	TRUE	The buffer was freed and the memory pointed to by addr is no longer valid.
	FALSE	The buffer couldn't be freed.

Precondition:

addr must be a valid address returned by Memory_alloc().

size must be equivalent to the size passed in during the Memory_alloc() allocation.

See also:

Memory_alloc()

Void Memory_dumpKnownContigBufsList

(

Void

)

Dumps the list of all translated/registered bufs.

Remarks:

The list is printed using the tracing infrastructure at trace level 5 to tracemask Memory_GTNAME.

There are several mechanisms to enable this trace mask, one would be to do the following from your application:

    GT_set(Memory_GTNAME "+5");

See also:

Memory_registerContigBuf()

Memory_unregisterContigBuf()

UInt32 Memory_getBufferPhysicalAddress	(	Ptr	virtualAddress,
		Int	sizeInBytes,
		Bool *	isContiguous
	)

Converts application virtual address to a physical address.

This API also checks verifies that the buffer is really contiguous.

Parameters:

[in]	virtualAddress	Address of a buffer.
[in]	sizeInBytes	Size of the buffer.
[out]	isContiguous	Optional flag indicating whether the buffer was physically contiguous or not.

Return values:

	0	Failure, the physical address could not be obtained.
	non-zero	The physical address of the buffer.

Remarks:

sizeInBytes must be non-zero.

isContiguous is an optional parameter, and can be NULL if the caller doesn't want the results of this check. If isContiguous is NULL but the buffer is not contiguous, error trace will be generated.

If a physically discontiguous buffer is provided in virtualAddress, zero will be returned. And if isContiguous is non-null, it will be set to FALSE.

This is typically called by a stub implementation to translate an application-side virtual address into a physical address usable by a remote skeleton and algorithm.

To enable portable code, this is safe to call on systems without virtual memory. In those cases, the returned physical buffer will be the same as the provided "virtual" buffer.

See also:

Memory_getBufferVirtualAddress()

Int Memory_getHeapId

(

String

name

)

Get the heap heap ID corresponding to a heap name. This number will be between 0 and the value returned by Memory_getNumHeaps(). The heap Id can be passed to Memory_redefine(), Memory_restoreHeap(), and Memory_segStat().

Remarks:

This is an unsupported, private function. There is no contract to provide compatibility between releases, and it may be deleted at any time.

Return values:

	>=	0 The heap number.
	<	0 No heap with the given name was found.

See also:

Memory_getNumHeaps()

Int Memory_getNumHeaps

(

)

Get the number of memory heaps.

Remarks:

This is an unsupported, private function. There is no contract to provide compatibility between releases, and it may be deleted at any time.

Return values:

The

number of memroy heaps.

See also:

Memory_getHeapId()

Ptr Memory_getBufferVirtualAddress	(	UInt32	physicalAddress,
		Int	sizeInBytes
	)

Obtains the virtual address of a physically contiguous buffer.

Parameters:

[in]	physicalAddress	Physical address of a buffer.
[in]	sizeInBytes	Size of the buffer.

Return values:

	NULL	Failure, the virtual address could not be obtained.
	non-zero	The virtual address of the buffer.

Remarks:

sizeInBytes must be non-zero.

If virtualAddress, was not acquired by Memory_getBufferPhysicalAddress(), no attempt is made to map the physically contiguous buffer into a the application's virtual memory space.

This is typically called by a stub implementation to translate a buffer provided by a remote skeleton and/or algorithm into an application-usable, virtual address.

To enable portable code, this is safe to call on systems without virtual memory. In those cases, the returned "virtual" buffer will be the same as the provided physical buffer.

See also:

Memory_getBufferPhysicalAddress()

Void Memory_registerContigBuf	(	UInt32	virtualAddress,
		UInt32	sizeInBytes,
		UInt32	physicalAddress
	)

Register a physical buffer allocated without Memory_contigAlloc().

Parameters:

[in]	virtualAddress	Address of the buffer mapped into the process space
[in]	sizeInBytes	Size of the region
[in]	physicalAddress	Physical address of the buffer

Remarks:

A cache of "app-address to codec-address" mappings (e.g. virtual to physical address mappings in DM644x devices) is internally maintained in some environments (e.g. Linux). This is used, for example, by Memory_getBufferPhysicalAddress() and Memory_getBufferVirtualAddress(). This lookup map is automatically updated when using Memory_contigAlloc() and Memory_contigFree(). However, if the user acquires buffers independently, it must use Memory_registerContigBuf() and Memory_unregisterContigBuf() to ensure the lookup map is current.

Individual sub-blocks of a buffer need not be registered; registering the entire buffer once will suffice.

This API is typically only required for environments with virtual memory (e.g. Linux-based systems).

See also:

Memory_unregisterContigBuf()

Memory_dumpKnownContigBufsList()

Void Memory_unregisterContigBuf	(	UInt32	virtualAddress,
		UInt32	sizeInBytes
	)

Unregisters a physical buffer allocated without Memory_contigAlloc().

Parameters:

[in]	virtualAddress	beginning address of the buffer mapped into the process space
[in]	sizeInBytes	size of the region

Remarks:

This API must be used to unregister a buffer allocated outside of Memory_contigAlloc() if the buffer (or a portion of it) is passed on to VISA calls. Segments of the buffer need not be individually unregistered.

See also:

Memory_registerContigBuf()

Memory_dumpKnownContigBufsList()

---

Variable Documentation

Memory_AllocParams Memory_DEFAULTPARAMS

Default parameters for Memory_alloc() & Memory_free().

Remarks:

Memory_DEFAULTPARAMS will be used when NULL is passed in the Memory_AllocParams parameter for Memory_alloc() & Memory_free(). When passing a non-NULL Memory_AllocParams parameter, you should first copy Memory_DEFAULTPARAMS to your structure and then modify individual elements as needed:

      Memory_AllocParams  myParams;

      myParams = Memory_DEFAULTPARAMS;
      myParams.type = Memory_CONTIGHEAP;

See also:

Memory_alloc()

Memory_free()