tmmanapi.h

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

	UInt32	PeerMajorVersion;
	UInt32	PeerMinorVersion;

	/* required for symbol patching */
	UInt32	TMManSharedPhysicalAddress;

	tmmanMemoryBlock	Memory;

}	tmmanDSPInternalInfo;




/*
		FUNCTION PROTOTYPES
*/



/*

tmmanNegotiateVersion

	Called by the application to perform a version negotiation with 
	the different components of TMMan. The application should fill 
	up the fields of the version structure with the 
	constTMManDefaultVersionXXXX constants defined in this file, before 
	calling the function. If TMMan cannot handle the version passed in 
	this structure it will return an error. Otherwise it will return 
	a success status. Note that both in case of a failure or success
	TMMan will write its current version information in the structure
	pointed to by the version parameter.

	An application can restrict it self to run with a SPECIFIC VERSION
	of TMMan by doing either on the following.
	Not Proceeding of this function returns a failure
	OR
	Not proceeding based on the TMMan version returned by this function.

Paremters :

	ModuleID
		Module Identification of the TMMan component whose version needs to be
		verified.
		constTMManModuleHostKernel
		constTMManModuleHostUser
		constTMManModuleTargetKernel
		constTMManModuleTargetUser

	Version
		Pointer to the tmmanVersion  structure with its Major and Minor fields 
		filled up.

Return :
	statusMajorVersionError
		Caller provided major version was less than the major version of the
		given module.

	statusMinorVersionError
  		Caller provided minor version was less than the minor version of the
		given module.

	statusUnknownComponent
		Caller provided ModuleID was outside the range suported on this 
		platform. i.e. if this function is called on the host with 
		constTMManModuleTargetKernel or constTMManModuleTargetUser.


*/
TMStatus  tmmanNegotiateVersion ( 
	UInt32	ModuleID, 
	tmmanVersion* Version );

/*
tmmanGetErrorString

	Returns the string corresponding to the specified error code.
	
Parametrers :

	StatusCode
		Status Code that needs to be converted to a string.

Returns :

	Pointer
		Pointer to a Null terminated string describing the error.

	Null
		If the error code is invalid.
*/
Int8*	tmmanGetErrorString (
	TMStatus	StatusCode );




/*

tmmanDSPGetNum

	Returns the number of TriMedia processors installed in the system.
	
Parameters :
	
	None

Return :

	Number of TriMedia processors installed in the system.

*/
UInt32		tmmanDSPGetNum ( 
	void );




/* DSP Interfaces */
/*
tmmanDSPGetInfo
	
	Retrieves the properties of the specified TriMedia processor.

Parameters :
	
	DSPHandle
		Handle to the DSP returned by tmmanDSPOpen. 

	DSPInfo
		Pointer to the structure where the TriMedia processor related 
		information will be returned.
	
Return:

	statusInvalidHandle
			Handle to the DSP is corrupted.

*/
TMStatus  tmmanDSPGetInfo ( 
	UInt32 DSPHandle, 
	tmmanDSPInfo* DSPInfo );


/*
tmmanDSPGetStatus

	Get the current state of the specified TriMedia Processor

Parameters :
	
	DSPHandle
		Handle to the DSP returned by tmmanDSPOpen. 

	StatusFlags
		Pointer to the location where the status flags will be stored.
		The status flags can be one of the following.

		constTMManDSPStatusUnknown
		constTMManDSPStatusReset
		constTMManDSPStatusRunning

Return :

	statusInvalidHandle
		Handle to the DSP is corrupted.

	statusUnsupportedOnThisPlatform
		If this function is called on the target.
*/
TMStatus  tmmanDSPGetStatus ( 
	UInt32 DSPHandle, 
	UInt32* StatusFlags );


/*
tmmanDSPMapSDRAM

	Maps SDRAM into Operating System and Process virtual address space
	See NOTES on SDRAM Mapping.

Parameters :
	
	DSPHandle
		Handle to the DSP returned by tmmanDSPOpen. 

Return :

	statusInvalidHandle
		Handle to the DSP is corrupted.

	statusOutOfVirtualAddresses
		There are no more free Page Table Entries to map this memory.

	statusUnsupportedOnThisPlatform
		If this function is called on the target.
*/
TMStatus  tmmanDSPMapSDRAM ( 
	UInt32 DSPHandle );



/*
tmmanDSPUnmapSDRAM

	Unmaps SDRAM from Process virtual address space. If all instances 
	of  SDRAM for this processor have been unmapped then the OS 
	mapping is also undone.	See NOTES on SDRAM Mapping. Note that
	tmmanDSPMapSDRAM and tmmanDSPUnmapSDRAM have to be called in pairs.

Parameters :
	
	DSPHandle
		Handle to the DSP returned by tmmanDSPOpen. 
Return :

	statusInvalidHandle
		Handle to the DSP is corrupted.

	statusUnsupportedOnThisPlatform
		If this function is called on the target.
*/
TMStatus  tmmanDSPUnmapSDRAM ( 
	UInt32 DSPHandle );


/*
tmmanDSPGetEndianess

	Get the current endianess of the specified TriMedia Processor

Parameters :
	
	DSPHandle
		Handle to the DSP returned by tmmanDSPOpen. 

	EndianessFlags
		Pointer to the location where the endianness flags will be stored.
		The endianness flags can be one of the following.

		constTMManEndianessUnknown
		constTMManEndianessLittle
		constTMManEndianessBig

Return :

	statusInvalidHandle
		Handle to the DSP is corrupted.

	statusUnsupportedOnThisPlatform
		If this function is called on the target.
*/
TMStatus  tmmanDSPGetEndianess ( 
	UInt32 DSPHandle, 
	UInt32* EndianessFlags );


/*
tmmanDSPOpen

	Opens the given TriMedia Processor. This call simply increments an 
	internal reference count. It does not perform physical detection 
	of the processor. All TriMedia processors are detected when TMMan 
	is loaded.

Parameters :

	DSPNumber 
		Number of the TriMedia processor that needs to be opened. Note 
		that this count reflects the order in which the TriMedia processor
		was detected by TMMan. This is generally dependent on the PCI
		slot in which the TriMedia board is sitting.

	DSPHandlePointer
		Address of the memory location where the handle to the DSP will
		be stored. All future references to the board have to be made via
		the handle.

Returns :

	statusDSPNumberOutofRange
		The DSPNumber parameter does not lie within 0 and 
		tmmanDSPGetNum() - 1.

*/
TMStatus  tmmanDSPOpen ( 
	UInt32 DSPNumber, 
	UInt32* DSPHandlePointer );


/*
tmmanDSPClose

	Closes the given handle to the TriMedia processor. This call simply 
	decrements an internal  reference count. The caller	will be able 
	to use the handle even after closing it. The handle to the DSP 
	remains valid as long as the TriMedia processor, the handle refers 
	to, exists in the system.


Parametrs :
	DSPHandle
		Handle to the TriMedia processor returned by tmmanDSPOpen().

Returns :
	statusInvalidHandle	
		Handle to the DSP is corrupted.

*/
TMStatus  tmmanDSPClose ( 
	UInt32 DSPHandle );


/*
tmmanDSPLoad

	Load a boot image onto the DSP. This image has to be compiled with
	the -btype boot flag.

Parametrs :
	DSPHandle
		Handle to the TriMedia processor returned by tmmanDSPOpen().
	
	LoadAddress
		Address of SDRAM where the executable should be downloaded.
		To use the default values use constTMManDefault.

	ImagePath
		Path to the executable file image. This image should have 
		a boot image not a task.

Returns :

	statusInvalidHandle	
		Handle to the DSP is corrupted.

	statusUnsupportedOnThisPlatform
		If this function is called on the target.

	statusOutOfVirtualAddresses
		There are no more free Page Table Entries to map SDRAM for
		image download.

	statusExecutableFileWrongEndianness
		The endianness of the excutable file is not the same as that
		specified in the INI file or registry.

	statusDownloaderXXX
		Range of TMDownloader error codes. For explanation of these error
		codes refer to TMDownloader.h

*/
TMStatus  tmmanDSPLoad ( 
	UInt32 DSPHandle, 
	UInt32 LoadAddress,
	Int8* ImagePath );


/*
tmmanDSPStart

	This function just unresets the DSP. The DSP starts executing 
	code at SDRAM base. See NOTES on C Run Time.

Parametrs :

	DSPHandle
		Handle to the TriMedia processor returned by tmmanDSPOpen().

Returns :

	statusInvalidHandle	
		Handle to the DSP is corrupted.

	statusUnsupportedOnThisPlatform
		If this function is called on the target.

*/
TMStatus  tmmanDSPStart ( 
	UInt32 DSPHandle );

/*
tmmanDSPStop

	Puts the CPU into a reset state. 
	Resets all the peripherals via MMIO registers.
	Resets shared data structures TMMan uses across the bus.

Parameters :

	DSPHandle
		Handle to the TriMedia processor returned by tmmanDSPOpen().

Returns :

	statusInvalidHandle	
		Handle to the DSP is corrupted.

	statusUnsupportedOnThisPlatform
		If this function is called on the target.

*/
TMStatus  tmmanDSPStop ( 
	UInt32 DSPHandle );

/*
tmmanDSPReset

	Initializes the TriMedia Processor after it has been manually reset 
	via the reset button or	other means. 
	This function can additionally preform a hardware reset of the TriMedia
	processor provided the necessary hardware modifications have been made
	to the IREF board.

Parameters :

	DSPHandle
		Handle to the TriMedia processor returned by tmmanDSPOpen().

Returns :

	statusInvalidHandle	
		Handle to the DSP is corrupted.

	statusUnsupportedOnThisPlatform
		If this function is called on the target.

*/
TMStatus  tmmanDSPReset ( 
	UInt32 DSPHandle );


/* ADDRESS TRANSLATION MACROS */

/*
tmmanMappedToPhysical

	Translates a Operating System Mapped SDRAM or MMIO address to a 
	physical address. This function can translate SDRAM and MMIO address
	only.

Parameters :

	MemoryBlock
		Pointer to a SDRAM or MMIO memory block structure, that will be used 
		for translating the address. The contents of this structure can be 
		retrieved by calling tmmanDSPGetInfo.

	MappedAddress
		The platform specific translated ( mapped ) address.

Return :

	Returns the physical address corresponding to the given mapped address.

*/
UInt32	tmmanMappedToPhysical ( 
	tmmanMemoryBlock* MemoryBlock, 
	UInt32 MappedAddress );


/*
tmmanPhysicalToMapped

	Translates a SDRAM or MMIO physical address to an operating system 
	mapped address. This function can translate SDRAM and MMIO addresses
	only.

Parameters :

	MemoryBlock
		Pointer to a SDRAM or MMIO memory block structure, that will be used 
		for translating the address. The contents of this structure can be 
		retrieved by calling tmmanDSPGetInfo.

	PhysicalAddress
		The platform specific MMIO or SDRAM physical address.

Return :

	Returns the mapped address corresponding to the given physical address.
*/
UInt32	tmmanPhysicalToMapped ( 
	tmmanMemoryBlock* MemoryBlock, 
	UInt32 PhysicalAddress );


/*
tmmanValidateAddressAndLength

	Checks if the given physical address and length lies between bound of the 
	given memory block. This function works for SDRAM and MMIO addresses only.

Parameters :

	MemoryBlock
		Pointer to a SDRAM or MMIO memory block structure, that will be 
		used for translating the address. The contents of this structure 
		can be retrieved by calling tmmanDSPGetInfo.
	
	Address
			Physical address that needs to be checked.
			
	Length
			Length of the block that needs to be checked.

Return :

	True 
		If the address and length describes a block lying within the range 
		specified by MemoryBlock.
	Flase
		if the address and length describes a block lying outside the 
		range specified by MemoryBlock.
*/
Bool    tmmanValidateAddressAndLength ( 
	tmmanMemoryBlock* MemoryBlock, 
	UInt32 Address, 
	UInt32 Length );



/*
tmmanTranslateAdapterAddress

	This function call uses the TMMan Kernel Mode Driver to translatea a
	adapter mapped address to a physical address that can be used by the 
	TM processor to access that address. 
	NOTE : This call can only be used to translate PHYSICAL ADAPTER MEMORY
	addresses(physical memory that is guaranteed to be page locked and 
	contiguous). 
	As the address range is assumed to be contiguous the length
	of memory range passed to this function does not need to be the entire
	memory range that needs to be accessed.
	
Parameters :

	
	MappedAddress
			OS Mapped memory address that needs to be translated.
			
	Length
			Length of the block that needs to be translated. This 
			parameter does not need to encompass the entire
			memory range.

	PhysicalAddressPtr
			Address of the memory loction where the tranalated physical 
			address will be stored.

Return :

	True 
		If the address and length could be tranalated successfully to