tmmanapi.h

PNX系列设备驱动 PNX系列设备驱动

	
	Name
		Unique caller supplied name for this object. See NOTES on
		Object Names.

	MappedAddress
		Host address of the block of memory that needs to be page locked.
		This parameter is typically the return value of malloc().
		
	Size
		Size of the memory in bytes.

	Flags
		Flags can have one or more the following values.
		constTMManSGBufferRead
			Buffer is going to read into ( Incoming Data )
		constTMManSGBufferWrite
			Buffer is going to be written from ( Outgoing Data ).
		
	BufferHandlePointer
		Address of the location where the handle to the page locked
		memory will be stored. This handle is required to unlock the
		page locked memory.

Returns :

	statusInvalidHandle	
		Handle to the DSP is corrupted.

	statusObjectAllocFail
		Object memory allocation failed.

	statusObjectListAllocFail
		No more shared memory slots free.

	statusDeviceIoCtlFail
		internal Error

	statusNameSpaceNoMoreSlots
		Out of name space slots - internal error

	statusNameSpaceLengthExceeded
		Name is more than 12 characters

	statusNameSpaceNameConflict
		The user assigned name already exists in TMMan name space.

	statusMemoryUnavailable
		No more shared memory available to copy the page frame table.

	statusUnsupportedOnThisPlatform
		If this function is called on the target.
*/

TMStatus  tmmanSGBufferCreate ( 
	UInt32	DSPHandle, 
	Int8*	Name,
	UInt32	MappedAddress,
	UInt32	Size,
	UInt32	Flags,
	UInt32* BufferHandlePointer );

/*
tmmanSGBufferDestroy

	Closes the handle tp the page locked memory and unlocks
	the memory and frees up the page frame tables. This function
	should be called by the host processor only.

Parametrers :

	BufferHandle
		Handle to the event returned by tmmanSharedMemoryOpen ().

Returns :

	statusInvalidHandle
		Handle to the object is corrupted or has already 
		been closed.

	statusUnsupportedOnThisPlatform
		If this function is called on the target.

*/
TMStatus  tmmanSGBufferDestroy ( 
	UInt32	BufferHandle );


/*

tmmanSGBufferOpen

	Opens a handle to the block of memory that was page locked on the
	host. This function should be called by the target processor only.

	DSPHandle
		Handle to the TriMedia processor returned by tmmanDSPOpen().
	
	Name
		Unique caller supplied name for this object. See NOTES on
		Object Names.

	EntryCountPointer
		Address of the memory location where the count of the PTE 
		entries is stored by this function.

	SizePointer
		Address of the memory location where the size of the buffer 
		is stored.

	BufferHandlePointer
		Address of the location where the handle to the scatter
		gather buffer will be stored. This handle is required to 
		free references	to this resource.
		
Returns :

	statusInvalidHandle	
		Handle to the DSP is corrupted.

	statusObjectAllocFail
		Object memory allocation failed.

	statusObjectListAllocFail
		No more shared memory slots free.

	statusNameSpaceLengthExceeded
		Name is more than 12 characters

	statusNameSpaceNameNonExistent
		The user provided name does not exists in TMMan name space.

	statusUnsupportedOnThisPlatform
		If this function is called on the host.

*/
TMStatus  tmmanSGBufferOpen ( 
	UInt32	DSPHandle, 
	Int8*	Name,
	UInt32*	EntryCountPointer,
	UInt32* SizePointer,
	UInt32* BufferHandlePointer );


/*
tmmanSGBufferClose

	Closes the reference to the scatter gather page locked 
	memory. This function does not unlock the memory pages.
	This function should be called from the target processor only.

Parametrers :

	BufferHandle
		Handle to the buffer returned by tmmanSGBufferOpen().

Returns :

	statusInvalidHandle
		Handle to the object is corrupted or has already 
		been closed.

	statusUnsupportedOnThisPlatform
		If this function is called on the host.

*/

TMStatus  tmmanSGBufferClose ( 
	UInt32	BufferHandle );

/*

tmmanSGBufferFirstBlock


	Returns the description of the first contiguous run of the 
	page locked memory on the host. The description consists
	of the offset of the block from the beginning of the memory,
	pointer of the block that the target processor can use to 
	access the memory, size of the block. Calls have to be made
	to the tmmmanSGBufferNextBlock to get description of 
	subsequent blocks.

Parametrers :

	BufferHandle
		Handle to the buffer returned by tmmanSGBufferOpen().
		
	OffsetPointer 
		Address of the memory location, where the offset of the
		block from the beginning of the memory that was page locked 
		on the host, will be stored.

	AddressPointer
		Address of the memory location, where the pointer to the
		memory block will be stored.

	SizePointer
		Address of the memory location where the size of the block
		will be stored.

Returns :

	statusInvalidHandle
		Handle to the object is corrupted or has already 
		been closed.

	statusUnsupportedOnThisPlatform
		If this function is called on the host.

*/

TMStatus	tmmanSGBufferFirstBlock ( 
	UInt32	BufferHandle,
	UInt32* OffsetPointer, 
	UInt32* AddressPointer, 
	UInt32* SizePointer );

/*

tmmanSGBufferNextBlock

	Returns the description of consecutive runs of contiguous memory
	from the page frame table referred to by BufferHandle. Note that
	tmmanSGBufferFirstBlock functions should be called at least once
	prior to calling this function.


Parametrers :

	BufferHandle
		Handle to the buffer returned by tmmanSGBufferOpen().
		
	OffsetPointer 
		Address of the memory location, where the offset of the
		block from the beginning of the memory that was page locked 
		on the host, will be stored.

	AddressPointer
		Address of the memory location, where the pointer to the
		memory block will be stored.

	SizePointer
		Address of the memory location where the size of the block
		will be stored.

Returns :

	statusInvalidHandle
		Handle to the object is corrupted or has already 
		been closed.

	statusSGBufferNoMoreEntries
		There are no more entries in the page frame table. To 
		restart parsing of the page frame table, call 
		tmmanSGBufferFirstBlock() followed by calls to 
		tmmanSGBufferBextBlock().

	statusUnsupportedOnThisPlatform
		If this function is called on the host.

*/

TMStatus	tmmanSGBufferNextBlock ( 
	UInt32	BufferHandle,
	UInt32* OffsetPointer, 
	UInt32* AddressPointer, 
	UInt32* SizePointer );

/*
tmmanSGBufferCopy

	The function copies the contents of the page locked memory 
	on the host to/from another block of memory on the target.
	It uses the c run time routine memcpy() to perform the actual
	copying operation. If the caller needs the copying to be 
	done via DMA transfer, then the tmmanSGBufferFirstBlock()
	and tmmanSGBufferNextBlock should be used instead.


Parametrers :

	BufferHandle
		Handle to the buffer returned by tmmanSGBufferOpen().

	Offset 
		Offset from the beginning of memory where the copying has to start.

	Address
		Pointer to the buffer on the target processor from/to where will be
		copied.

	Size
		Number of bytes to copy.

	Direction
		Direction of copy.
		
		True 
			Copy from host memory to target memory.

		False
			Copy from target to host memory. 
		

Returns :

	statusInvalidHandle
		Handle to the object is corrupted or has already been closed.

	statusSGBufferOffsetOutOfRange
		The Offset supplied to this function is out of range of the
		page locked host buffer.
			

	statusSGBufferSizeOutOfRange
		The size passed to this function is greater than the amount of
		page locked memory available from the given offset.

	statusUnsupportedOnThisPlatform
		If this function is called on the host.

*/

TMStatus	tmmanSGBufferCopy ( 
	UInt32	BufferHandle,
	UInt32	Offset,
	UInt32	Address, 
	UInt32	Size, 
	UInt32	Direction );

/* DEBUG SUPPORT */

/*
tmmanDebugDPBuffers

	This function retrieves pointer to the circular wrap around buffers,
	where the TriMedia processor dumps debug messages.  
	This function is current callable only from the host and it retrieves
	debug information generated by the TriMedia processor. 
	Debug information printed via the DP macros are retrieved via this 
	function. 	See NOTES on Debug Buffer Pointers.

Parametrers :

	DSPHandle
		Handle to the DSP returned by tmmanDSPOpen. 

	FirstHalfPtr
		Address of the memory location where the pointer to the first half
		of the buffer will be stored.


	FirstHalfSizePtr
		Address of the memory location where the size of the first half 
		buffer will be stored.

	SecondHalfPtr
		Address of the memory location where the pointer to the second half
		of the buffer will be stored.

	SecondHalfSizePtr
		Address of the memory location where the size of the second half 
		buffer will be stored.

Returns :

	statusInvalidHandle
		Handle to the DSP is corrupted.

	statusDebugNoPeerDebugInformation
		This function scans through the entire SDRAM to search for a magic 
		header that identifies valid debug information. This error code
		denotes that the magic header does not exist or had been corrupted.

	statusUnsupportedOnThisPlatform
		If this function is called on the target. 
*/

TMStatus	tmmanDebugDPBuffers (
	UInt32	DSPHandle, 
	UInt8*	*FirstHalfPtr, 
	UInt32*	FirstHalfSizePtr, 
	UInt8*	*SecondHalfPtr, 
	UInt32*	SecondHalfSizePtr );

/*
tmmanDebugHostBuffers

	This function retrieves pointer to the circular wrap around buffers,
	where the host processor dumps debug messages.  
	This function is current callable only from the host and it retrieves
	debug information generated by the host component of TMMan. The are no
	application callable functions that can dump data into these buffers.
	TMMan(host) uses this buffer to print internal debug information.
	See NOTES on Debug Buffer Pointers.

Parameters :

	FirstHalfPtr
		Address of the memory location where the pointer to the first half
		of the buffer will be stored.


	FirstHalfSizePtr
		Address of the memory location where the size of the first half 
		buffer will be stored.

	SecondHalfPtr
		Address of the memory location where the pointer to the second half
		of the buffer will be stored.

	SecondHalfSizePtr
		Address of the memory location where the size of the second half 
		buffer will be stored.

Returns :

	statusNotImplemented	
		This function will be implemented in a future release.
		Currently all TMMan (host) debug messages are printed to the host
		debugger(WinDBG or NTIce).

  	statusUnsupportedOnThisPlatform
		If this function is called on the target. 

*/

TMStatus	tmmanDebugHostBuffers (
	UInt8*	*FirstHalfPtr, 
	UInt32*	FirstHalfSizePtr, 
	UInt8*	*SecondHalfPtr, 
	UInt32*	SecondHalfSizePtr );


/*
tmmanDebugTargetBuffers

	This function retrieves pointer to the circular wrap around buffers,
	where the target processor dumps debug messages.  
	This function is current callable only from the host and it retrieves
	debug information generated by the target component of TMMan. 
	Applications running on the target can call the tmmanDebugPrintf 
	fucntion to print information into these buffers.
	TMMan(target) uses this buffer to print internal debug information.
	See NOTES on Debug Buffer Pointers.

  DSPHandle
		Handle to the DSP returned by tmmanDSPOpen. 

	FirstHalfPtr
		Address of the memory location where the pointer to the first half
		of the buffer will be stored.


	FirstHalfSizePtr
		Address of the memory location where the size of the first half 
		buffer will be stored.

	SecondHalfPtr
		Address of the memory location where the pointer to the second half
		of the buffer will be stored.

	SecondHalfSizePtr
		Address of the memory location where the size of the second half 
		buffer will be stored.

Returns :

	statusInvalidHandle
		Handle to the DSP is corrupted.

	statusDebugNoPeerDebugInformation
		This function scans through the entire SDRAM to search for a magic 
		header that identifies valid debug information. This error code
		denotes that the magic header do not exist or has been corrupted.

   	statusUnsupportedOnThisPlatform
		If this function is called on the target. 

*/

TMStatus	tmmanDebugTargetBuffers (
	UInt32	DSPHandle, 
	UInt8*	*FirstHalfPtr, 
	UInt32*	FirstHalfSizePtr, 
	UInt8*	*SecondHalfPtr, 
	UInt32*	SecondHalfSizePtr );


/*
tmmanDebugPrintf

	This function is used to print formatted strings via the debugging
	subsystem of TMMan. The implementation of this function is platform
	specific. On the host this functions prints out strings to the debug
	windows. On the target this function prints strings to the debug
	trace buffers. The maximum length of the string can be 1024 bytes.
	Applications on the TriMedia processor should use the DP macros to
	print debugging information.

Parametrers :

	Format
		printf style format specifier
	...
		printf style arguments.

Returns :

	Number of items printed.
*/

UInt32 tmmanDebugPrintf ( Int8 *Format, ... );


/* TMMan Internal Functions - should not be called by applications */

Bool	tmmanGetImageInfo (
	Int8*	ImagePath,
	UInt32*	TypePtr,
	UInt32*	EndianPtr );

Bool	tmmanGetTCSPath ( 
	Int8*	TCSPathBuffer,
	UInt32	TCSPathBufferLength );

TMStatus  tmmanDSPGetInternalInfo ( 
	UInt32 DSPHandle, 
	tmmanDSPInternalInfo* pDSPCaps );

TMStatus  tmmanDSPSetInternalInfo ( 
	UInt32 DSPHandle, 
	tmmanDSPInternalInfo* pDSPCaps );

void	tmmanExit (  
	UInt32 DSPNumber );

Pointer	tmmanInit ( 
	UInt32 DSPNumber, 
	Pointer Configuration );

#ifdef __cplusplus
};
#endif	/* __cplusplus */

#endif /* _TMMANAPI_H_ */