/*
	(c) Philips Semiconductors - TriMedia Product Group 1999

	TriMedia Manager Application Programming Interface

	FILE	TMManAPI.h

	Author : T.Roy (Tilakraj.Roychoudhury@sv.sc.philips.com)

	Histroy
		970613	T.Roy		Second Revision
		980601	T.Roy		Documentation Updates
		981207	T.Roy		Added WinCE & Speculative Load stuff.
		990201	T.Roy		Added section on SDRAM Mapping and Synch Flags.
		990609	T.Roy		Added section on BIU->INT_CTL register update.
*/
/*
	IMPLEMENTATION NOTES 

	Throughout this header file function descriptions refer to these
	NOTES.

	Synchronization Handle

		The caller creates these handles via calls to the operating system
		specific functions like CreateEvent() or AppSem_create() etc. The
		caller is also responsible for freeing these handles. The following
		section lists the operating systems supported by TMMan, the 
		functions used by the caller to allocate these handles 
		and the functions TMMan uses to signal these handles. 

		Win95 Kernel Mode
			Creation - CreateEvent()
			Signaling - VWIN32_SetWin32Event()
			Closing - CloseHandle()

		WinNT KernelMode
			Creation - CreateEvent()
			Signaling - KeSignalEvent()
			Closing - CloseHandle()

		pSOS
			Creation - AppSem_create() + AppSem_p()
			Signaling - AppSem_v
			Closing - AppSem_delete()

		Standalone ( no oprating system )
			Creation - AppSem_create() + AppSem_p()
			Signaling - AppSem_v
			Closing - AppSem_delete()

		
		Note that under Windows operating systems 
		(WinNT, Win95, Win98, WinCE) this event 
		has to be created as an Auto Reset Event.


	Synchronization Flags

		constTMManModuleHostKernel
			Indicates that the Host module calling the required function is 
			running in Kernel Mode. If this flag is specified TMMan 
			interprets the SynchronizationHandle parameter as a handle
			to a Win32 Synchroniztion Object. Typically WinNT/Win9X Device 
			Drivers.
			
		constTMManModuleHostUser
			Indicates that the Host module calling the required function 
			running in User Mode. Typically WinNT/Win9X/WinCE DLLs or Applications.

	
		constTMManModuleTargetKernel
			On the target there is no distinction between user and kernel mode.
			If this flag is specified TMMan interprets SynchronizationHandle as
			an AppSem type of synchronization object. 
	
	
		constTMManModuleTargetUser
			On the target there is no distinction between user and kernel mode.
			If this flag is specified TMMan interprets SynchronizationHandle as
			an AppSem type of synchronization object. 


	Object Names

		Every TMMan object has a name associated with it. This name is used
		to form a binding between the host and target counterparts of the 
		objects. This object name is a unique user supplied name that can 
		be 12 characters long (maximum). The names are case sensitive.
		The host has to create the named object before the target can find 
		it otherwise the named object creation on the target will fail.
		These names do not have to be unique across objects. i.e. an
		event and a message channel can use the same name.


	Scatter Gather Buffer Locking 

		The tmmanSGBufferXXX functions are applicable to systems in which the
		host processor supports virtual memory.	If an application running on 
		the host allocates a buffer which the target processor needs to access
		(read from or write to ), scatter gather locking has to be performed.
		Scatter Gather locking a buffer ensures that the memory allocated to 
		that buffer does not get paged out. This locking operation also 
		generates a scatter gather list that is used by the target to access
		the memory allocated to the buffer which is fragmented in physical 
		address space. 

	Debug Buffer Pointers

  		The tmmanDebugXXXBuffers functions return 2 sets of pointers and sizes.
		These pointers point to a circular buffer on in SDRAM or in PC memory.
		These pointers that track the current state of the debug buffers are 
		constantly changing. This function returns a snapshot of these pointers.
		The contents of the circular wrap around buffer has to be accessed in
		two parts via the FirstHalfPtr and the  SecondHalfPtr. If the buffer
		has not wrapped around at the instance this call is made the 
		FirstHalfPtr will we Null. And only the SecondHalfPtr will point to 
		valid contents. To print the contents of the buffer the code should 
		look like this.

		if ( FirstHalfPtr )
		{
			Print ( FirstHalfPtr, FirstHalfBufferSize );
		}

		Print ( SecondHalfPtr, SecondHalfBufferSize );

	Speculatvie Load Fix

		The TriMedia compiler supports speculative loading i.e. values in 
		registers are used as pointers and are dereferenced to load data 
		from memory in advance. 

		Speculative load can lead to loads from SDRAM MMIO or over the PCI bus. 
		On certain Pentium II machines having the Intel 440LX and the 440BX 
		chipsets load access across the PCI bus cause the machine to lock up. 
		These PCI accesses could be targeted at PC memory, adapter memory 
		(like VGA frame buffer), or unclaimed PCI physical address space.

		The TriMedia processor has a hardware feature that allows all PCI 
		access (expect SDRAM and MMIO accesses) to be disabled. This feature 
		can be enabled and disabled at run time. 

		The TriMedia Manager disables PCI accesses at startup. However when 
		it needs to access PC memory for host communication functions, 
		it enables PCI accesses, performs the accesses and then disables 
		PCI accesses.

		Similarly User programs that allocate and use shared memory should 
		use the pciMemoryReadUIntXX() & pciMemoryWriteUIntXX() functions 
		to access shared memory on the host, instead of reading and writing
		memory by de-referencing pointers directly. These functions are
		documented in TCS\include\tm1\tmPCI.h.

		
		The option (Speculative Load Fix) is turned off by default, it can 
		be turned on by the following registry entry.

		[HKEY_LOCAL_MACHINE\\SOFTWARE\\PhilipsSemiconductors\\TriMedia\\TMMan]
		"SpeculativeLoadFix"=dword:00000001

		Existing application that use shared memory will break when this 
		fix is turned on.


	Big Endian Execution
		The TriMedia processor can execute in both big endian mode and little 
		endian mode. TMMan supports execution of little endian as well as big 
		endian executables on the TriMedia processor. 

		The host processor on the PC always executes in little endian mode 
		however the TriMedia processor can execute in big endian mode. 
		In such a case every access made to shared memory have to be swapped 
		to maintain data consistency. 

		The TriMedia processor always accesses data in native endianess i.e. 
		in either big endian or little endian mode. It is the host 
		applications responsibility to swap data types if the target is 
		running is an endianess different than the host. The example 
		programs i.e. memory, message, tmapi, sgbuffer take care of 
		endianess issues using macros for SWAPPING. Other user applicaitons 
		should do the same.

		To Execute Big Endian Examples set the following flag in 
		%windir%\\tmman.ini
		
		[TMMan]
		Endian=1 ; LITTLE Endian - This is the default
		Endian=0 ; BIG Endian

		The machine need not be rebooted after this change.

	WinCE Issues

		Under other Win32 platforms like WinNT, Win95 & Win98, Kernel Mode 
		Drivers can signal user mode event via handles. Under WinCE the 
		TMMan Drivers run in user mode within the driver.exe process. 
		The only way it can set an event in user mode is by obtaining a 
		handle to the event via a same name, that the user application, used
		to create the event. Hence applicaitons that, use TMMan Event and 
		Messaging Interfaces, and run under Win CE have to take care of the
		following :

		All Win32 events have to be named events.
		All event names have to be unique, even across applications. As 
		events are created in the global Win32 namespace.

		Note that these restrictions do NOT apply to other Win32 platforms.


	StatusCodes

		All the TMManAPI functions return statusSuccess on successful 
		completion.	Callers can retrieve a textual description of the 
		failure codes by calling tmmanGetErrorString. All error codes are 
		documented in the file TMManErr.h.


	SDRAM Mapping

		Due to limited amount of virtual address space on some Windows 
		Platforms, simultaneous mapping of SDRAM and MMIO spaces of 
		multiple TM processors may fail. A solution to this problem
		is to defer the mapping of SDRAM till the time when it will be 
		actually used and then unmapping it immediately so as to free
		Virtual Address Space for mapping other SDRAMs of the other
		TriMedia processors in that machine. For this purpose, two
		API calls have been added tmmanDSPMapSDRAM, tmmanDSPUnmapSDRAM.
		To disable SDRAM mapping at initialization ( default is to map
		all of SDRAM ) the following registry key has to be set :
		HKLM\SOFTWARE\PhilipsSemiconductors\TriMedia\TMMan
		MapSDRAM=0
		When SDRAM MApping is disabled, calls to tmmanDSPDSPInfo will 
		return invalid values in the tmmanMemoryBlock.SDRAM.MappedAddress 
		field. Other calls that make use of this field will also fail, i.e.
		tmmanMappedToPhysical
		tmmanPhysicalToMapped
		tmmanValidateAddressAndLength
		tmmanTranslateAdapterAddress
		tmmanDebugDPBuffers
		tmmanDebugTargetBuffers	
		Hence calls to these functions have to be wrapped with calls to 
		tmmanDSPMapSDRAM and tmmanDSPUnmapSDRAM.
		Also note the c Run Time library server DLL ( tmcrt.dll ) will not
		work anymore since it depends on the entire SDRAM to be accessible 
		all the times. So target executables have to be compiled with -host
		nohost or a dummy version of the host_comm.o have to be linked in
		if -host Windows is used. Also note that TriMedia DLLs  will not 
		work since loading DLLs require file I/O.

	Writing to BIU->INT_CTL register on TriMedia

		The TMMan host driver performs writes to the INT_CTL pins to 
		acknowledge the level trigerred interrupt that TriMedia 
		generates via PCI INT#A. Having the host and the target
		write to the same register causes atomicity problems.
		To circumvent this problem the host and the target uses
		a simple handshaking protocol to perform atomic updates of 
		the INT_CTL register.


		If any other component running on the TriMedia processor needs
		to write to the INT_CTL register it should use a similar
		handshaking protocol to guarantee atomicity of the writes.

		The following code runs on the TriMedia processor and shows how
		to use the two semaphores to perform a safe update of hte INT_CTL
		registers in a hosted mode.

		These variables are initialized by the TMMan initialization code.


		extern UInt32* Host2TargetIntPtr;
		extern UInt32* Target2HostIntPtr;


		while ( 1 )
		{
			UInt32 Data;

			// is the lock already claimed 
			pciMemoryReadUInt32 ( *Host2TargetIntPtr, &Data  );

			if ( Data  == False )
			{
				// claim the lock 
				pciMemoryWriteUInt32 ( *Target2HostIntPtr, True  );

				// has the host claimed in the mean time 
				pciMemoryReadUInt32 ( *Host2TargetIntPtr, &Data  );

				if ( Data == True )
				{
					// yes so we release it 
					pciMemoryWriteUInt32 ( *Target2HostIntPtr, False  );
				}
				else
				{

					// perform update of INT_CTL here
					MMIO(INT_CTL) = 0x0;

					// release the lock and get out 
					pciMemoryWriteUInt32 ( *Target2HostIntPtr, False  );

					break;
				}

			}
		}


*/

#ifndef  _TMMANAPI_H_
#define  _TMMANAPI_H_
	
/*-----------------------------includes-------------------------------------*/

#ifdef	__TCS__
#include <tmlib/tmtypes.h>
#include <WinNT/tmmanerr.h>
#else
#include "tmtypes.h"
#include "tmmanerr.h"
#endif


#ifdef __cplusplus
extern "C" {
#endif

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

#ifndef	constTMManDefault
#define constTMManDefault			(0xffffffff)
#endif

/* 
	maximum boards in one system 
*/
#define	constTMMANMaximumDeviceCount	10 


/* 
	maximum number of processes that can access tmman simultaneously 
*/
#define	constTMMANMaximumClientCount	20 


#define constTMManModuleHostKernel		(0x1)

#define constTMManModuleHostUser		(0x2)

/*
	Applications should not use this flag, 
	it is for internal use of TMMan only.
*/
#define constTMManModuleHostCallabck	(0x3)

#define constTMManModuleTargetKernel	(0x4)

#define constTMManModuleTargetUser		(0x5)

/*
	Applicaitons should not use this flag, 
	it is for internal use of TMMan only.
*/
#define constTMManModuleTargetCallback	(0x6)


/* TMMan Major  Version - compatible modules have the same version */
#define constTMManDefaultVersionMajor				5
/* TMMan Minor  Version - compatible modules have the same version */
#define constTMManDefaultVersionMinor				2


/* Status of the TriMedia Processor cannot be determined */ 
#define constTMManDSPStatusUnknown			0
/* TriMedia processor is in reset state - not executing any code */
#define constTMManDSPStatusReset			1
/* TriMedia processor is out of reset - executing code */
#define constTMManDSPStatusRunning			2

/* Target Executable Endianess unknown */
#define	constTMManEndianessUnknown		0x0
/* Target Executable - Little Endianess - Intel Comaptible */
#define	constTMManEndianessLittle		0x1
/* Target Executable - Big Endianess */
#define	constTMManEndianessBig			0x2

/*
	compile time tunable parameters

	IMPORTANT : if any of the following parameters are changed
	tmman and all applications that use tmman including the 
	C Run Time Library Server has to be recompiled 
*/

/* number of arguments that can be passed via the tmmanPacket structure */
#define	constTMManPacketArgumentCount		0x5	

/* internal space allocated for storing names and paths */
#define	constTMManPathLength				256
#define	constTMManStringLength				256
#define	constTMManDebugStringLength			1024

/* maximum number of cmd line args */
#define	constTMManMaximumArgumentCount		128		

/* maximum total cmd line arg buffer size */
#define constTMManMaximumArgumentBuffer		1024	

/* maximum number of TriMedia processors supported */
#define	constTMManBoardCount				constTMMANMaximumDeviceCount

#define constTMManNameSpaceNameLength		16

/* scatter gather buffer transfer direction constants */
#define	constTMManSGBufferRead				0
#define	constTMManSGBufferWrite				1

/* 
	run time tunable parameters

	These parameters will be read by TMMan at the time of starting up.
	values shown here are default values.
	On a Windows machine these parameters will be read form the registry.
*/

/* default shared memory size */
#define	constTMManMemorySize				0x10000	
/* default maximum number of interprocessor mailboxes */
#define	constTMManMailboxCount				0x40
/* default maximum number of interprocessor channels */
#define	constTMManChannelCount				0x10
/* default maximum number of virtual (multiplexed) interrupt lines */
#define	constTMManVIntrCount				0x04
/* default maximum number of message queues <=  constTMManChannelCount */
#define	constTMManMessageCount				0x10
/* default maximum number of interprocessor events */
#define	constTMManEventCount				0x10
/* default maximum number of streams - not yet supported */
#define	constTMManStreamCount				0x10
/* default maximum number is namespace slots that can be used */
#define	constTMManNameSpaceCount			0x40
/* default maximum number of shared memory blocks that can be allocaed */
#define	constTMManMemoryCount				0x40
/* default maximum number of buffer that can scatter gather locked */
#define	constTMManSGBufferCount				0x20


#define constTMManRegistryPath				TEXT("SOFTWARE\\PhilipsSemiconductors\\TriMedia\\TMMan")

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

/*
		DATA STRUCTURES
*/
typedef struct	tagtmmanPacket
{
	/* application specific arguments - TMMan does not modify or interpret these */
	UInt32	Argument[constTMManPacketArgumentCount];

	/* DO NOT USE THIS FIELD - TMMan overwrites it */
	UInt32	Reserved; 

}	tmmanPacket;

#define	constTMManPacketSize				sizeof(tmmanPacket) 

typedef struct	tagtmmanVersion
{
	/* Major Version number of the specified TMMan component */
	UInt32	Major;
	
	/* Minor Version Number of the specified TMMan component */
	UInt32	Minor;
	
	/* Build version number of the specified TMMan component */
	UInt32	Build;

}	tmmanVersion;

typedef struct	tagtmmanMemoryBlock
{

	/* Operating System Mapped Address corresponding to PhysicalAddress */
	UInt32	MappedAddress;

	/* Physical Address of the SDRAM or MMIO Window */
	UInt32	PhysicalAddress;

	/* Size of the SDRAM or MMIO Window */
	UInt32	Size;

}	tmmanMemoryBlock;

typedef struct	tagtmmanDSPInfo
{

	/* Address information about SDRAM */
	tmmanMemoryBlock	SDRAM;
	
	/* Address information about MMIO */
	tmmanMemoryBlock	MMIO;

	/* Version of the CPU - PCIConfig->RevisionID field */
	/*UInt32			CPUVersion; - old fields don't use */

	/* TriMedia PCI Class and Revision ID - for CPU version*/
	UInt32				TMClassRevisionID;

	/* Version of the board - PCIConfig->SubSystemVendor ID */
	/*UInt32			BoardVersion; - old fields don't use*/

	/* TriMedia PCI Subsystem & Subsystem Vendor ID - same as Board Revision */
	UInt32				TMSubSystemID;

	/* DSP Number - depends on the order this device was found on the PCI bus */
	UInt32				DSPNumber;


	/* TriMedia PCI Device and Vendor ID - TM1000 / TM2000 support */
	UInt32				TMDeviceVendorID;

	/* Bridge PCI Device and Vendor ID - non-transparent bridge support */
	UInt32				BridgeDeviceVendorID;

	/* Dridge PCI Class and Revision ID - for CPU version*/
	UInt32				BridgeClassRevisionID;

	/* Bridge PCI Subsystem & Subsystem Vendor ID - non-transparent bridge support */
	UInt32				BridgeSubsystemID;

	/* Reserved for future use */
	UInt32				Reserved[8];

}	tmmanDSPInfo;


/* this structure is used internally by tmman - not for applications use */
typedef struct	tagtmmanDSPInternalInfo
{
	/* only this field can be set from user mode */
	UInt32	Flags; 
	UInt32	CRunTimeHandle;
	UInt32	DebugOptionBitmap;

	/* all the fields below are read only */

	/* debugging */

	/* peer version information */