tmmanapi.h

wince host 和 target PCI驱动程序

		a adapter physical address.
	Flase
		If the address tranaltion failed.
*/
Bool    tmmanTranslateAdapterAddress ( 
	UInt32 MappedAddress,
	UInt32 Length,
	UInt32 *PhysicalAddressPtr );


/* 
	Message Interfces 
*/

/* 

tmmanMessageCreate


	Creates a bi-directional message channel between the host and 
	the target processor. This message channel can be used to 
	send fixed size packets of type tmmanPacket from one processor
	to another. The message packets are copied across the PCI bus
	via shared mailboxes. Every message channel has its own private 
	queue where incoming packets from the other processor are 
	temporarily buffered.
	When a packet arrives from the other processor the caller supplied
	OS synchronization object will be signaled. The caller can use 
	native OS primitives to block on this object or on multiple 
	objects as required. Note however that due to the relative speed
	of the two processors there may not be a one to one correspondence
	between the number of times the object is actually signaled and the
	number of packets in the incoming queue.


Paremters :

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

	SynchronizationHandle
		Pointer to OS specific synchronization object. See NOTES on
		Synchronization Handle.

	SynchronizationFlags
		This parameter describes how TMMan should interpret the 
		SynchronizationHandle parameter. See NOTES on Synchronization
		Flags. It can have one of the following values.

			constTMManModuleHostKernel
			constTMManModuleHostUser
			constTMManModuleTargetKernel
			constTMManModuleTargetUser

	MessageHandlePointer
		Address of the location where the pointer to the message channel 
		will be stored.

Returns :

	statusInvalidHandle	
		Handle to the DSP is corrupted.

	statusObjectAllocFail
		Object memory allocation failed.

	statusObjectListAllocFail
		No more message channels free.

	statusNameSpaceNoMoreSlots
		Out of name space slots - internal error

	statusNameSpaceLengthExceeded
		Name is more than 12 characters long.

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

	statusSynchronizationObjectCreateFail
		The synchronization flags were invalid or memory could not 
		be allocated for the Synchronization object.

	statusQueueObjectCreateFail
		Creation of the queue to buffer incoming packets failed.


*/
TMStatus  tmmanMessageCreate ( 
	UInt32	DSPHandle,
	Int8*	Name,
	UInt32	SynchronizationHandle,
	UInt32	SynchronizationFlags,
	UInt32* MessageHandlePointer );
/*

tmmanMessageDestroy

	Closes the message channel handle returned by tmmanMessageCreate().
	Only the message channel and the queue are freed. The caller is 
	responsible for freeing the OS synchronization object that was 
	supplied to tmmanMessageCreate().


Parametrers :

	MessageHandle
		Handle to the message channel returned by 
		tmmanMessageCreate().

Returns :

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

*/

TMStatus  tmmanMessageDestroy ( 
	UInt32 MessageHandle );

/*
tmmanMessageSend

	This function sends a fixed size data packet of type tmmanPacket
	to the peer processor.	This functions returns an error if 
	there is no space in the interprocessor mailbox to send packets.
	However this may be a temporary condition and caller should retry 
	sending the packet after a timeout. Packets on a certain message
	channel are guaranteed to arrive, in the order sent, on peer 
	processor.
	

Parameters :

	MessageHandle
		Handle to the message channel returned by 
		tmmanMessageCreate().

	DataPointer 
		Pointer to the tmmanPacket data structure. Once this call
		returns successfully the data structure can be reused.

Returns :

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

	statusChannelMailboxFullError
		The interprocessor mailbox is temporarily full, this is
		a temporary condition. The user us permitted to supposed
		to retry the call only when this error code is returned.
		i.e the caller should not do the following
		while ( tmmanMessageSend ( Handle, &Packet ) != statusSuccess );
		it should rather do the following
		while ( tmmanMessageSend ( Handle, &Packet ) 
			== statusChannelMailboxFullError );

*/

TMStatus  tmmanMessageSend ( 
	UInt32 MessageHandle, 
	void *DataPointer );


/*
tmmanMessageReceive

	This function retrieves a packet from the incoming packet
	queue. This is a non-blocking function, so if there are no 
	packets	in the queue this function returns immediately with
	an error code. A synchronization object may be signaled 
	once for multiple packets. The caller should call this 
	function repeatedly, until it fails, to retrieve all packets 
	that have arrived.
	
Parametrers :

	MessageHandle
		Handle to the message channel returned by 
		tmmanMessageCreate().

	DataPointer 
		Pointer to the tmmanPacket data structure. If this call succeeds
		the tmmanPacket structure contains a valid packet.


Returns :

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

	statusMessageQueueEmptyError
		There are no pending packets in the incoming message queue 
		for this message channel.


*/
TMStatus  tmmanMessageReceive ( 
	UInt32 MessageHandle, 
	void *DataPointer );


/* 
	Event Functions 
*/

/*

tmmanEventCreate

	Events provide an interprocessor signaling mechanism. It enables
	one processor to signal an event that will cause another processor
	to unblock if it is waiting on that event. The caller of this function 
	should use the native OS dependent Synchronization primitives to
	create a OS synchronization object and pass the handle to this 
	function. Due to the relative speeds of the two processors there 
	may not be a one to one correspondence between	the number of 
	times one processors signals the event and the number of times 
	the event actually gets signaled on the peer processor.

Paremters :

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

	SynchronizationHandle
		Pointer to OS specific synchronization object. See NOTES on
		Synchroniztoin Handle.

	SynchronizationFlags
		This parameter describes how TMMan should interpret the 
		SynchronizationHandle parameter. See NOTES on Synchronization
		Flags. It can have one of the following values.

			constTMManModuleHostKernel
			constTMManModuleHostUser
			constTMManModuleTargetKernel
			constTMManModuleTargetUser

	EventHandlePointer
		Address of the location where the pointer to the event	will be 
		stored.

Returns :

	statusInvalidHandle	
		Handle to the DSP is corrupted.

	statusObjectAllocFail
		Object memory allocation failed.

	statusObjectListAllocFail
		No more events 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.

	statusSynchronizationObjectCreateFail
		The synchronization flags were invalid or memory could not 
		be allocated for the Synchronization object.

*/

TMStatus	tmmanEventCreate (
	UInt32	DSPHandle,						
	Int8*	Name,
	UInt32	SynchronizationHandle,
	UInt32	SynchronizationFlags,
	UInt32* EventHandlePointer );

/*
tmmanEventSignal

	This function causes the OS specific synchronization object 
	on the peer processor to be signaled.


Parameters :

	EventHandle
		Handle to the event returned by tmmanEventCreate().

Returns :

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

*/

TMStatus	tmmanEventSignal (
	UInt32 EventHandle );

/*
tmmanEventDestroy

	Closes the Event Handle and frees up the resources
	allocated by TMMan for this object. It is the callers
	responsibility to free the OS synchronization object
	that was passed to the tmmanEventCreate() function.	

Parametrers :

	EventHandle
		Handle to the event returned by tmmanEventCreate().

Returns :

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

*/

TMStatus	tmmanEventDestroy (
	UInt32 EventHandle );

/*
	Shared Memory
*/

/*

tmmanSharedMemoryCreate


	Allocates a block of shared memory and returns a pointer to the 
	memory block. This memory is allocated out of contiguous, page 
	locked memory on the host processor. Shared memory can only be 
	allocated on the host but can be accessed from the target. Note
	that this is a very expensive system resource and should be used
	sparingly. The memory block returned is always aligned on a 32
	bit boundary. TMMan allocates a region of shared memory for every
	board present in the system ( at startup ) and then suballocates 
	blocks from this region when this function is called.

Parametrers :

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

	Length
		Length of the required shared memory block in bytes.

	AddressPointer

		Address of the memory location where the pointer to
		the shared memory will be stored. This pointer can 
		be used by the host directly to access the allocated
		memory.

	SharedMemoryHandlePointer
		Address of the location where the handle to the shared memory
		will be stored. This handle is required to free this resource.
		

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.

	statusUnsupportedOnThisPlatform
		If this function is called on the target.

*/
TMStatus  tmmanSharedMemoryCreate ( 
	UInt32	DSPHandle, 
	Int8*	Name,
	UInt32	Length,
	UInt32*	AddressPointer,
	UInt32* SharedMemoryHandlePointer );


/*
tmmanSharedMemoryDestroy


	Closes the Shared Memory handle and frees up the shared 
	memory that was allocated via the call to 
	tmmanSharedMemoryCreate(). This fucntion should be called
	by the host processor only.

Parametrers :

	SharedMemoryHandle
		Handle to the shared memory block returned by 
		tmmanSharedMemoryCreate().

Returns :

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

	statusUnsupportedOnThisPlatform
		If this function is called on the target.

*/
TMStatus  tmmanSharedMemoryDestroy ( 
	UInt32	SharedMemoryHandle );


/*
tmmanSharedMemoryOpen

	This function opens a handle to a shared memory resource 
	created on the host. This function does not actually 
	allocate any memory, it returns a handle to an existing
	shared memory block, that has been already allocated on
	the host. This function should be called on 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.

	LengthPointer
		Address of the memory location where the Length of the 
		shared memory block identified by name will be stored.

	AddressPointer

		Address of the memory location where the pointer to
		the shared memory will be stored. This pointer can 
		be used by the target directly to access the allocated
		memory.

	SharedMemoryHandlePointer
		Address of the location where the handle to the shared memory
		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  tmmanSharedMemoryOpen ( 
	UInt32 DSPHandle, 
	Int8*	Name,
	UInt32* LengthPointer,
	UInt32*	AddressPointer,
	UInt32*	SharedMemoryHandlePointer );

/*

tmmanSharedMemoryClose

	Closes the shared memory Handle and frees up the resources
	allocated by TMMan for this object. This function does not
	free the shared memory. The shared memory has to be freed 
	by the host. This function should be called from the target
	processor only.

Parametrers :

	SharedMemoryHandle
		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 host.

*/

TMStatus  tmmanSharedMemoryClose (
	UInt32	SharedMemoryHandle );

								 
/* 
	Buffer Locking 
*/

/*

tmmanSGBufferCreate

	This function page locks the specified memory and generates a page frame
	table that can be used by the target to access the page locked memory.
	This function is only supported on hosts that have virtual memory. This
	function can only be called by the host processor. 
	
Parametrers :

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