tmman32.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	: tmman32.h    1.12
 *
 *  Last update	: 13:38:21 - 98/05/18
 *
 *  Description	: 
 *
 *	Contains the ptototypes for the Windows User mode clients.
 *	This header files is also use by Kernel mode clients to call the Ring0
 *	services provided by vtmman.vxd.
 *	
 *	THIS FILE SHOULD BE USED ONLY ON  THE HOST (WIN95)
 *
 *	Revision	:
 *	960530	TR	Updated to reflect the actual ASR 1.1 inerface
 *	961218	TR	Modified for ASR 2.0 release.
 *	970108	TR	Cleaned up for ASR 2.1 release
 *
 */
 

#ifndef  TMMAN32_INCLUDED
#define  TMMAN32_INCLUDED
	
/*-----------------------------includes-------------------------------------*/

#include "tmwincom.h"


#ifdef __cplusplus
extern "C" {
#endif

/*-----------------------------defines---------------------------------------*/

/* ADDRESS TRANSLATION MACROS */
/* Converts a SDRAM or MMIO linear address to a physical address */
#define tmLinToPhys(Address,MemType) \
	(((Address) - (MemType)->dwLinear) + (MemType)->dwPhysical)

/* conversts a SDRAM or MMIO physical address to a linear address */
#define tmPhysToLin(Address,MemType) \
	(((Address) - (MemType)->dwPhysical) + (MemType)->dwLinear)

/*	CONSTANTS */


#define TMMAN_DEFAULT		0xffffffff

#define TMMAN_MODULE_HOST_TMMAN32	1
#define TMMAN_MODULE_HOST_VTMMAN	2
#define	TMMAN_MODULE_DSP_TMMAN		5

#define TMMAN_DEFAULT_VERSION_MAJ	TMSTD_MAJOR_VERSION
#define TMMAN_DEFAULT_VERSION_MIN	TMSTD_MINOR_VERSION

#define TMMAN_ADVISE_MSG_RECV		(1)
#define TMMAN_ADVISE_TASK_CREATE	(2)
#define TMMAN_ADVISE_TASK_START		(3)
#define TMMAN_ADVISE_TASK_STOP		(4)
#define TMMAN_ADVISE_TASK_DESTROY	(5)
#define TMMAN_ADVISE_TASK_SIGNAL	(6)
#define TMMAN_ADVISE_TASK_FAIL		(7)

/* DSP is currently out of reset and running code */
#define	TMMAN_DSPSTATUS_EXECUTABLE_LOADED		0x01
/* DSP is currently out of reset and running code */
#define	TMMAN_DSPSTATUS_EXECUTABLE_RUNNING		0x02
/* DSP is currently in a reset state */
#define	TMMAN_DSPSTATUS_EXECUTABLE_STOPPED		0x03
/* Interrupts from TriMedia to Host are not functioning */
#define	TMMAN_DSPSTATUS_INTERRUPT_NONFUNCTIONAL	0x04

/* ERROR CODES */

/* TMCons.exe could not be started */
#define		TMMAN32_ERR_CREATEPROCESSTMCONSFAIL	TMERR(TM_STATUS_HCOMP_TMMAN32,0x12)
/* Image Buffer Memory Allocation failure */
#define		TMMAN32_ERR_MEMALLOCFAIL		TMERR(TM_STATUS_HCOMP_TMMAN32,0x13)
/* Minor Version of calling application is lower than that expected by tmman32 */
#define		TMMAN32_ERR_MINVERSIONERROR		TMERR(TM_STATUS_HCOMP_TMMAN32,0x14)
/* Major Version of calling application is lower than that expected by tmman32 */
#define		TMMAN32_ERR_MAJVERSIONERROR		TMERR(TM_STATUS_HCOMP_TMMAN32,0x15)
/* Component code is not recognized by tmman32 */
#define		TMMAN32_ERR_UNKNOWNCOMPONENT	TMERR(TM_STATUS_HCOMP_TMMAN32,0x16)
/* Internal Error - Win32 DeviceIoctl() call fail */
#define		TMMAN32_ERR_DEVIOCTLFAIL		TMERR(TM_STATUS_HCOMP_TMMAN32,0x17)
/* Unable to create the TMCons start event */
#define		TMMAN32_ERR_CREATEEVENTFAIL		TMERR(TM_STATUS_HCOMP_TMMAN32,0x20)
/* Unable to open TMCons Exit event */
#define		TMMAN32_ERR_OPENEVENTFAIL		TMERR(TM_STATUS_HCOMP_TMMAN32,0x21)
/* Target Image endianness is incorrect - link execution host using -host Win95 option */
#define		TMMAN32_ERR_IMAGENOTLITTLEENDIAN		TMERR(TM_STATUS_HCOMP_TMMAN32,0x22)


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

/* CALLBACK DEFINITION */

typedef STATUS	(* TMMAN_ADVISORY_NOTIFICATION) (
	DWORD dwMessage, DWORD	dwObjHandle, PVOID pvObjContext, 
	PTMSTD_PACKET pPacket  );

typedef       DWORD   ( * VXD_CALLBACK ) ( PVOID pvAdvisoryObject,
	PVOID pvPacket );
/* DATA STRUCTURES */
/*
TMMAN_TMCONS_PARAMS
This structure controls the behaviour of TMCons. 
*/
typedef struct	_TMMAN_TMCONS_PARAMS
{
	BOOL	fIgnoreTMCons;
	
	BOOL	fUseWindowSize;
	DWORD	dwWindowSize;

	DWORD	fUseTMMonWindow;

	BOOL	fRedirectedStdin;
	CHAR	szFilenameStdin[TMSTD_PATH_LENGTH];

	BOOL	fRedirectedStdout;
	CHAR	szFilenameStdout[TMSTD_PATH_LENGTH];

	BOOL	fRedirectedStderr;
	CHAR	szFilenameStderr[TMSTD_PATH_LENGTH];
}	TMMAN_TMCONS_PARAMS, *PTMMAN_TMCONS_PARAMS;


typedef struct	_TMMAN_DSP_INFO
{
	DWORD	ArgCount;
	DWORD	ArgVector;
	DWORD	TMMANSharedPhys;
	PVOID	pDBGSharedData;
	DWORD	Flags;
}	TMMAN_DSP_INFO, *PTMMAN_DSP_INFO;


typedef struct	_TMMAN_DSP_CAPS
{
	CHAR			szPCIName[TMSTD_NAME_LENGTH];
	DWORD			dwHWVersion;
	DWORD			dwCPUVersion;
	DWORD			dwROMVersion;
	TMSTD_MEMORY_BLOCK	SDRAM;
	TMSTD_MEMORY_BLOCK	MMIO;
	TMSTD_MEMORY_BLOCK	User;
	DWORD			DSPNumber;
}	TMMAN_DSP_CAPS, *PTMMAN_DSP_CAPS;


typedef struct _TMMAN_MESSAGE_DESC
{
	DWORD	dwMessageSlots;
	DWORD	dwCallback;
	PVOID	pvContext;
	DWORD	dwID;
	DWORD	dwHandle;
}	TMMAN_MESSAGE_DESC, *PTMMAN_MESSAGE_DESC;


typedef struct  _TMMAN_TASK_CREATE
{
	DWORD				dwFlags;
	DWORD				dwCallback;
	PVOID				pvContext;
	DWORD				dwPriority;
	DWORD				dwStackSize;
	CHAR				szTaskFile[TMSTD_PATH_LENGTH];
	DWORD				dwArgumentCount;
	PCHAR				*ppbArgumentVector;
}	TMMAN_TASK_CREATE, *PTMMAN_TASK_CREATE;


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

/*
tmNegotiateVersion 

Parameters
	dwModuleID
		If the version of the default module is desired use TMMAN_DEAFULT.
		 The default module is tmman32 or tmman16 as the case may be. 
		 Module IDs currently supported are :
	TMMAN_MODULE_HOST_TMMAN32
		Refers to tmman32.dll
	TMMAN_MODULE_HOST_TMMAN16
		Refers to tmman16.dll
	TMMAN_MODULE_HOST_VTMMAN
		Refers to vtmman.vxd
	TMMAN_MODULE_DSP_TMMAN
		Refers to tmman.td

	pVersion
		Address of the version structure. This structure is used both 
		for input and output. Before making the call this structure
		should be filled with the version of the module that the  
		calling program requires. If the module does not agree with 
		the version then an error code is returned and the current 
		version information of the module is returned in pVersion, 
		otherwise the function returns success. 
		If dwModuleID is specified as TMMAN_DEAFULT then initialize :
		pVersion->dwMajor = TMMAN_DEFAULT_VERSION_MAJ;
		pVersion->dwMinor = TMMAN_DEFAULT_VERSION_MIN;
		pVersion->dwBuild = 0;

Comments
	The TriMedia manager is made up of a lot of modules. 
	Any one of them may be out of date due to interface changes. 
	This function attempts to avoid these synchronization problems. 
	It provides a mechanism for the Windows application / driver to 
	query the version information of any component of the TriMedia Manager. 
*/
STATUS  tmNegotiateVersion ( DWORD dwModuleID, PTMSTD_VERSION_INFO pVersion );

/*
tmVxDOpen

Parameters
	NONE
Comments
	This function should be called before calling any of the tmman API 
	calls available in Ring 0. This function registers the calling VxD
	as  a client with TMMan. Callers should check the return status to
	determine whether the VxD could be successfully registered or not.
*/
STATUS	tmVxDOpen ( VOID );

/*
tmVxDClose

Parameters
	NONE
Comments
	This function should be called after the calling VxD has finished
	using TMMan services. This call frees all the resources that TMMan
	has allocated for this client. After this any attempt to call
	TMMan serviecs from Ring 0 will lead to unpredictable results.
*/
STATUS	tmVxDClose ( VOID );

/*
tmDSPGetNum

Parameters
	pdwDSPCount
	Address of the location where the information will be copied.

Comments
	Enumerate the number of DSP boards present in the system.
*/
STATUS	tmDSPGetNum ( PDWORD pdwDSPCount );

/*
tmDSPGetCaps

Parameters
	dwDSPNumber
		Handle to the DSP board returned by tmDSPOpen.
	pDSPCaps
		Address of the structure where the information will be copied.

Comments
	Retrieve the capabilities of the given DSP board.
*/
STATUS	tmDSPGetCaps ( DWORD dwDSPHandle, PTMMAN_DSP_CAPS pDSPCaps );

/*
tmDSPOpen

Parameters
	dwDSPNumber
		Board Number of the DSP that has to be opened.
	pdwHandle
		Address of the location where the handle to the opened DSP 
		board will be stored.

Comments
	This function returns a handle for accessing a particular DSP 
	board in the system. The board can be opened multiple times by 
	the different applications. The DSP object handle returned by 
	this call is used for all future accesses to this board. 
	
*/
STATUS	tmDSPOpen ( DWORD dwDSPNumber, PDWORD pdwHandle );

/*
tmDSPExecutableLoad

Parameters
	dwDSPHandle
		Handle to the DSP board returned by tmDSPOpen.
	dwLoadAddress
		Load address for downloading the executable file.
		Use TMMAN_DEFAULT for default value.
	pszImagePath
		Full path to the executable image that has to be downloaded.
	dwArgCount
		Number of arguments pointed to by pArgVector. 
	pArgVector[]
		Pointer to an array of pointers pointing to arguments 
		that are passed to the target executable抯 main(). 
		This function does not pre-pend the executable path 
		name to the argument list. Hence it is the responsibility 
		of the caller to set pArgVector[0] to the executable path 
		name. The total number of characters in all the argument 
		lists have to less than 1024.

Comments
	Downloads a TriMedia boot executable into SDRAM. Boot executable 
	are files that have been linked with the -btype boot option. 
*/

STATUS	tmDSPExecutableLoad ( DWORD dwDSPHandle, DWORD dwLoadAddress,
	PCHAR pszImagePath, DWORD dwArgCount, PCHAR pArgVector[] );
/*
tmDSPExecutableRun

Parameters
	dwHandle
		Handle to the DSP returned by tmDSPOpen.
	dwStartingAddress
		Address of the first instruction. 
	pTMConsParams
		Pointer to the TMMAN_TMCONS_PARAMS structure. 

Comments
	Runs the executable boot image that is downloaded into the 
	TriMedia processor. It pulls the TriMedia processor out of 
	reset as a result of which it starts running the code present 
	at SDRAM Base.

*/
STATUS	tmDSPExecutableRun ( DWORD dwDSPHandle, DWORD dwStartingAddress,