tmman.h

wince host 和 target PCI驱动程序

/*
 * Copyright (c) 1995,1996,1997 by Philips Semiconductors.
 *
 * +------------------------------------------------------------------+
 * | This software is furnished under a license and may only be used  |
 * | and copied in accordance with the terms and conditions of  such  |
 * | a license and with the inclusion of this copyright notice. This  |
 * | software or any other copies of this software may not be provided|
 * | or otherwise made available to any other person.  The ownership  |
 * | and title of this software is not transferred.                   |
 * |                                                                  |
 * | The information in this software is subject  to change without   |
 * | any  prior notice and should not be construed as a commitment by |
 * | Philips Semiconductors.                                          |
 * |                                                                  |
 * | this code and information is provided "as is" without any        |
 * | warranty of any kind, either expressed or implied, including but |
 * | not limited to the implied warranties of merchantability and/or  |
 * | fitness for any particular purpose.                              |
 * +------------------------------------------------------------------+
 *
 *  Module name	: tmman.h    1.8
 *
 *  Last update	: 14:27:20 - 98/02/27
 *
 *  Description	: 
 *
 *	Contains the public exports of tmman - dsp component.
 *	These functions are exported by libtmman.a
 *	
 *	THIS FILE SHOULD BE USED ONLY ON  THE TARGET (TM-1)
 *
 *	Revision	:
 *	960531	Tilakraj Roy	Created
 *	960913	Tilakraj Roy	Changed the interfaces to support tmman v4.0
 *
 */
 

#ifndef  TMMAN_INCLUDED
#define  TMMAN_INCLUDED

/*-----------------------------includes-------------------------------------*/

#include "tmwindef.h"
#include "tmwincom.h"

#if	defined(__cplusplus)
extern	"C"	{
#endif	/* defined(__cplusplus) */

/*-----------------------------defines---------------------------------------*/
/* Error codes */
#define	TMMAN_ERR_INVALIDHANDLE		TMERR(TM_STATUS_TCOMP_TMMAN,1)
#define	TMMAN_ERR_NOMORECHANNELS	TMERR(TM_STATUS_TCOMP_TMMAN,2)
#define	TMMAN_ERR_ALREADYINIT		TMERR(TM_STATUS_TCOMP_TMMAN,3)
#define	TMMAN_ERR_MSGSENDFAIL		TMERR(TM_STATUS_TCOMP_TMMAN,4)
#define	TMMAN_ERR_IDOUTOFRANGE		TMERR(TM_STATUS_TCOMP_TMMAN,5)
#define	TMMAN_ERR_INVALIDOBJECT		TMERR(TM_STATUS_TCOMP_TMMAN,6)
#define	TMMAN_ERR_INVALIDPTEHEADER	TMERR(TM_STATUS_TCOMP_TMMAN,7)
#define	TMMAN_ERR_INVALIDHOSTADDR	TMERR(TM_STATUS_TCOMP_TMMAN,8)
#define	TMMAN_ERR_INVALIDCOPYSIZE	TMERR(TM_STATUS_TCOMP_TMMAN,9)
#define	TMMAN_ERR_ENDOFPTELIST		TMERR(TM_STATUS_TCOMP_TMMAN,0xa)
#define	TMMAN_ERR_INCOMPATIBLEVERSION	TMERR(TM_STATUS_TCOMP_TMMAN,0xb)


#define	TMMAN_DEFAULT		0xffffffff

#define TMMAN_DEFAULT_VERSION_MAJ	TMSTD_MAJOR_VERSION
#define TMMAN_DEFAULT_VERSION_MIN	TMSTD_MINOR_VERSION

/* #define DT( _l_, _x_ ) if ( tmDGBTMMANGetLevel ( 1 << (_l_) ) ) tmDBGTMMANPrintf _x_ */

#define DT( _l_, _x_ ) 

/*-------------------------------types----------------------------------------*/

/* DSP Interface */
typedef struct _TMMAN_DSP_CAPS
{
	DWORD	CPUVersion;
	TMSTD_MEMORY_BLOCK	SDRAM;
	TMSTD_MEMORY_BLOCK	MMIO;
	TMSTD_MEMORY_BLOCK	User;
	DWORD	ClockFreq;
}	TMMAN_DSP_CAPS, *PTMMAN_DSP_CAPS;



typedef struct _TMMAN_MESSAGE_DESC
{
	DWORD	Slots;			/* number of message slots to allocate */
	DWORD	Callback;		/* message receive function callback */
	PVOID	pContext;		/* callback context */
	DWORD	ID;	/* id of the msg chnl - should match host msg chnl id */
}	TMMAN_MESSAGE_DESC, *PTMMAN_MESSAGE_DESC;

/*
	TMMAN_MSGONRECV
	prorotype of advise notification registered 
*/
typedef STATUS    ( * TMMAN_MSGONRECV )( 
	PVOID pvContext,	/* callback context registered during tmMsgCreate */
	PVOID pvPacket );	/* packet that was received from the host */


/*------------------------------functions------------------------------------*/

STATUS	tmNegotiateVersion ( PTMSTD_VERSION_INFO Version );
/*
tmDSPOpen

Parameters
	dwDSPNumber
		Always zero in this release.  Allows for expansion to multi-DSP systems.
	pDSPHandle
		Address of the buffer where the handle to the DSP object will be stored..

Comments
	Initializes the TMMan DSP interface.  Returns a handle to the DSP 
	object that should be used in all subsequent calls to functions on this DSP. 


*/
STATUS	tmDSPOpen  ( DWORD DSPNumer, PDWORD pDSPHandle );

/*
tmDSPGetCaps

Parameters
	dwDSPHandle
		Handle to the DSP returned by tmDSPOpen. 
	pDSPCaps
		Address of the buffer where the capabilities information will be stored.

Comments
	Returns information about processor version and resources allocated 
	to the processor. 

*/
STATUS	tmDSPGetCaps  ( DWORD DSPHandle, PTMMAN_DSP_CAPS pDSPCaps );

/*
tmDSPClose

Parameters
	dwDSPHandle
	Handle to the DSP returned by tmDSPOpen.

Comments
	Closes the DSP interface and invalidates the DSP handle. 

*/
STATUS	tmDSPClose  ( DWORD DSPHandle );

/*
tmMsgCreate


Parameters
	pMsgCreate
		Attributes for creating he message queue.
	ppMsg 
		Address of  buffer where the handle to the newly created 
		message queue will be stored.

Comments
	Create a message queue for communicating with the host.  The host 
	should not send any packet to this queue until this function 
	completes successfully.
*/
STATUS  tmMsgCreate ( 
	PTMMAN_MESSAGE_DESC pMsgCreate, /* message channel attributes */
	PVOID *ppMsg );					/* address of mem to store msg obj ptr */

/*
tmMsgDestroy

Parameters
	pMsg 
	Handle to the message queue returned by the call to tmMsgCreate.

Comments
	Destroys the message queue created with tmMsgCreate. After this 
	call any more calls to tmMsgSend with this handle will fail. Even 
	if the host continues to send packets to this message queue the 
	notification function on the target will not be called and 
	eventually the message queue will overflow.

*/
STATUS    tmMsgDestroy ( 
	PVOID pMsg );	/* ptr to msg obj to destroy */

/*
tmMsgSend

Parameters
	pMsg 
		Handle to the message queue returned by the call to tmMsgCreate.
	pPacket 
		Pointer to message packet that has to be delivered to the host..

Comments
	Send the packet to the host via this message queue. When this 
	packet is delivered to the host, the hosts message queue 
	notification function will be called. This function should not 
	be called until the host has called the tmMsgOpen function for 
	the corresponding message queue. If the host side fails to 
	retrieve packets from the queue as fast as the target sends 
	them, the queue will overflow and packets will be dropped. 

*/
STATUS  tmMsgSend ( 
	PVOID pMsg,			/* ptr to the msg obj */
	PVOID pPacket );	/* packet ptr to send to host */



/*
tmParameterDWORDSet


*/
STATUS	tmParameterDWORDSet ( DWORD ID, DWORD Value );

/*
tmParameterDWORDGet

Parameters
	dwID
		ID of the slot where the parameter will be retrieved from. 
		IDs below 0x10 are reserved for TMMan抯 internal use. User 
		programs should use ID greater than 0x10.
	pdwValue
		Address of the memory location where the retrieved value 
		will  be stored.

Comments
	This function is used by the target to retrieve parameters 
	that are set by the host. Before this function is called, the 
	host should have set the parameter via tmParameterDWORDSet 
	using the same ID that is used in this call. 

*/
STATUS	tmParameterDWORDGet ( DWORD ID, PDWORD pValue );


/*
tmSGMemCopy

Parameters
	pObject
		The dwPhysicalAddress returned by a call to the function 
		tmBufferPrepare on the host. This is actually the physical 
		address of the Page Frame Table Header object.
	dwHostAddress
		The Linear Address of the scatter gather locked buffer 
		on the host.  Note that this field has to contains the 
		linear address of the host buffer, not the physical 
		address of the buffer.
	dwTargetAddress
		Physical  address of the target buffer.
	dwSize
		Number of bytes to copy. 
	fHostToTarget
		Flag indicating the direction of copy.
		TRUE
			Copy from host memory to target memory.
		FALSE
			Copy from target memory to the host memory. 

Comments
	This function copies a scatter gather locked buffer in host 
	memory to the target memory or vice versa. This function need 
	not be called to copy the entire scatter gather locked buffer. 
	It can copy parts to the buffer. This function will fail if the 
	pObject parameter is invalid or if the dwHostAddress and dwSize 
	parameters are out of the range of the scatter gather locked buffer.

*/
STATUS	tmSGMemCopy ( PVOID pObject, DWORD dwHostAddress,
	DWORD dwTargetAddress, DWORD dwSize, BOOL fHostToTarget );

/*
tmSGGetNextBlock

Parameters
	pObject
		The dwPhysicalAddress returned by a call to the function 
		tmBufferPrepare on the host. This is actually the physical 
		address of the Page Frame Table Header object
	pdwLinearAddress
		Address of the buffer where the linear address of the 
		next block of contiguous memory will be placed. 
	pdwPhysicalAddress
		Address of the buffer where the physical address of 
		the next block of contiguous memory will be placed. 
	pdwSize
		Address of the buffer where the size of the next 
		block of contiguous memory will be placed. 

Comments
	This function returns the description of the next block of 
	page locked and contiguous host memory. Every time this 
	function is called the next block of memory is returned. 
	When the last block is reached this function returns an 
	error.  To start parsing the page frame table from the 
	beginning, call tmSGGetFirstBlock, this will reset the 
	next block to be the second block in he page frame table.

*/
STATUS	tmSGGetNextBlock ( PVOID pObject, PDWORD pdwLinearAddress, 
	PDWORD pdwPhysicalAddress, PDWORD pdwSize);

/*
tmSGGetFirstBlock

Parameters
	pObject
		The dwPhysicalAddress returned by a call to the function 
		tmBufferPrepare on the host. This is actually the physical 
		address of the Page Frame Table Header object.
	pdwLinearAddress
		Address of the buffer where the linear address of the first 
		block of contiguous memory will be placed. 
	pdwPhysicalAddress
		Address of the buffer where the physical address of the 
		first block of contiguous memory will be placed. 
	pdwSize
		Address of the buffer where the size of the first block 
		of contiguous memory will be placed. 

Comments
	This function returns the description of the first block of page 
	locked and contiguous host memory. Every time this function is 
	called, an internal pointer is reset to point to the first memory 
	block in the Page Frame Table. Call the function tmSGGetNextBlock 
	to get the description of subsequent blocks of memory. 


*/
STATUS	tmSGGetFirstBlock ( PVOID pObject, PDWORD pdwLinearAddress, 
	PDWORD pdwPhysicalAddress, PDWORD pdwSize);



/*
tmDBGPrintf

Parameters
	szFormat
		Address of the NULL terminated string containing the 
		formatting information. 

Comments
	Called by target applicaitons to print debug messages to the debug,
	trace buffer. This buffer can be examined from the PC using tmmon 
	or tmgmon.This function does not accept width or precision arguments
	neither does it accept the %f parameter.
*/

DWORD	tmDBGPrintf ( PCHAR szFormat, ...);

/*
tmDBGString

Parameters
	szString
		Address of the NULL terminated string. 

Comments
	This function prints a NULL terminated string, it does not 
	take printf style formatting. To use this function just call 
	the macro DS. The output of this function can be viewed off-line 
	via TMMon. This function is reentrant and can be called from 
	interrupt handlers.

*/
VOID	tmDBGString ( PCHAR szString );

/*
tmDBGOptions

Parameters
	Options
		Bitmap denoting which debug output sources to enable.. 
		TMSTD_DBG_OPTIONMONO
			Output to monochrome monitor
		TMSTD_DBG_OPTIONPERSIST
			Output to persistent buffer (SDRAM)
		TMSTD_DBG_OPTIONVOLATILE
			Output to volatile memory (PC-MEM)

Comments
	This function sets the debug output destinations. The return 
	value of this function is the previous value of options. Note 
	that the old value of options is overwritten by this function. 
*/
DWORD	tmDBGOptions ( DWORD Options );

/*
tmDBGBufferSize

Parameters
	dwSize
		Size of the buffer that has to be allocated for debugging. 

Comments
	This functions sets the persistent buffer ( sdram ) buffer size 
	to the given buffer. Note that the old buffer is freed and all 
	the contents are lost.  This function may fail due to lack of 
	memory. When TMMan starts the default buffer size is 2K bytes.
*/
STATUS	tmDBGBufferSize ( DWORD Size );

/*
tmDBGNULL

Parameters
	pDummy
		Pointer to a dummy buffer.

Comments
	Since tmDBgPrintf uses variable number of parameters, tmDBGNULL is
	provided to be a placeholder when debugging is not required.
*/
DWORD	tmDBGNULL(PVOID pDummy, ...);

/*
tmDBGTMMANPrintf

Comment
	Internally used by tmman. This function should not be called by 
	applications.
*/
DWORD	tmDBGTMMANPrintf( char * pFormat, ...);


/*
tmDGBTMMANGetLevel

Comment
	Internally used by tmman. This function should not be called by 
	applications.
*/
DWORD	tmDGBTMMANGetLevel(DWORD dwLevel);


/* 
tmTMMANCreate

Comments
	Internally used by the host call interface. Should not be called by
	target applications.
*/
BOOL	tmTMMANCreate( VOID);

/*
tmTMMANDestroy

Comments
	Internally used by the host call interface. Should not be called by
	target applications.
*/
BOOL 	tmTMMANDestroy( VOID);


#if	defined(__cplusplus)
}
#endif	/* defined(__cplusplus) */

#endif /* TMMAN_INCLUDED */