sl@0: // Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // Definition of the stop-mode debug interface.
sl@0: // 
sl@0: 
sl@0: /**
sl@0: @file
sl@0: @publishedPartner
sl@0: @prototype
sl@0: */
sl@0: 
sl@0: #ifndef D_STOP_MODE_API_H
sl@0: #define D_STOP_MODE_API_H
sl@0: 
sl@0: #include <rm_debug_api.h>
sl@0: #include <plat_priv.h>
sl@0: 
sl@0: namespace Debug
sl@0: 	{
sl@0: 	/**
sl@0: 	 * The stop-mode debug interface is a stateless interface which may be called at any point
sl@0: 	 * except user mode, provided the rest of the OS is not going to run or pre-empt it.
sl@0: 	 * For example, for stop-mode debugging, the ICE may run the stop_mode_api routine to
sl@0: 	 * collect information about the system so long as no exceptions are enabled, and all 
sl@0: 	 * registers/stack are preserved and restored after the call completes. Note that in an SMP environment
sl@0: 	 * it is expected that ALL the CPU's have been stopped
sl@0: 	 */
sl@0: 
sl@0: 	/** Stop Mode Debug API Version Numbers */
sl@0: 	const TUint KStopModeMajorVersionNumber=0;
sl@0: 	const TUint KStopModeMinorVersionNumber=0;
sl@0: 	const TUint KStopModePatchVersionNumber=2;
sl@0: 
sl@0: 	/**
sl@0: 	 * Enumerators used to identify the buffers created for use with the Stop-Mode Debug API.
sl@0: 	 */
sl@0: 	enum TBufferType
sl@0: 		{
sl@0: 		EBuffersFunctionality = 0,   /**< Enumerator corresponding to the buffer created to store the debug functionality block. */
sl@0: 		EBuffersRequest = 1,         /**< Enumerator corresponding to the request buffer. */
sl@0: 		EBuffersResponse = 2,        /**< Enumerator corresponding to the response buffer. */
sl@0: 		
sl@0: 		/**
sl@0: 		 * @internalTechnology
sl@0: 		 * A user should find the number of buffer tags from the DFBlock rather than this enumerator.
sl@0: 		 */
sl@0: 		EBuffersLast
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	 * Enumerators used to identify the functions for use with the Stop-Mode Debug API.
sl@0: 	 */
sl@0: 	enum TFunctionalityStopModeFunctions
sl@0: 		{
sl@0: 		EStopModeFunctionsExitPoint = 0,  /**< Enumerator corresponding to the Debug::GetList() function. */
sl@0: 		EStopModeFunctionsGetList = 1,    /**< Enumerator corresponding to the Debug::ExitPoint() function. */
sl@0: 		EStopModeFunctionsTestAPI = 2,	  /**< Enumerator corresponding to the Debug::TestAPI() function. */
sl@0: 		
sl@0: 		/**
sl@0: 		 * @internalTechnology
sl@0: 		 * A user should find the number of supported functions from the DFBlock rather than this enumerator.
sl@0: 		 */
sl@0: 		EStopModeFunctionsLast
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	 * This structure defines the start elements of a stop-mode debug functionality block.
sl@0: 	 * It is assumed that the rest of the functionality block will extend past the end of
sl@0: 	 * the structure and will be accessed according to the documented format of the
sl@0: 	 * stop-mode functionality block.
sl@0: 	 */
sl@0: 	struct DFunctionalityBlock
sl@0: 		{
sl@0: 		TUint32 iSize;				/**< Size of the functionality block in bytes. */
sl@0: 		TVersion iStopModeVersion;	/** Version of the stop-mode debug API. */
sl@0: 		TTagHeader iFirstHeader;	/** The header for the first sub-block in the functionality block. */
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	 * This structure used for extracting static data using the Stop Mode Extension API
sl@0: 	 * StopModeDebug::GetList using TListId::EStaticInfo
sl@0: 	 * as the first argument.
sl@0: 	 */
sl@0: 	class TStaticListEntry
sl@0: 		{
sl@0: 	public:
sl@0:     
sl@0: 		/** Build time of ROM in microseconds */
sl@0: 	    TUint64 iTime;    
sl@0:     
sl@0: 		/** Number of CPUs */
sl@0: 	    TInt iCpuNumbers;
sl@0:     
sl@0: 		/** ROM build number */
sl@0: 	    TUint16 iBuildNumber;    
sl@0:         
sl@0: 		/** Major Version of ROM build */
sl@0: 	    TUint8 iMajorVersion;                   
sl@0: 
sl@0: 		/** Minor Version of ROM build */
sl@0: 	    TUint8 iMinorVersion;
sl@0:     
sl@0: 		/** Currently unused element. May be used in future to aid maintaining compatibility. */
sl@0: 	    TUint32 iSpare[10];    
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	 * This structure represents a request to return a list via the SM API
sl@0: 	 */
sl@0: 	struct TListItem
sl@0: 		{
sl@0: 		/** Size of this TListItem */
sl@0: 		TUint32 iSize;
sl@0: 	
sl@0: 		/** The type of list to return */
sl@0: 		TListId iListId;
sl@0: 	
sl@0: 		/** The scope of the list to return  */
sl@0: 		TListScope iListScope;
sl@0: 	
sl@0: 		/**
sl@0: 		 * Data corresponding to the list scope, for example if iListScope specifies a thread
sl@0: 		 * specific listing then iScopeData should contain the thread ID to return the list for.
sl@0: 		 * If iListScope = EGlobalScope then iScopeData is ignored.
sl@0: 		 */
sl@0: 		TUint64 iScopeData;
sl@0: 	
sl@0: 		/**
sl@0: 		 * The first element in the target list to return data for. For example if a thread list is being
sl@0: 		 * requested then specifying iStartElement = 100 indicates that the first thread to be returned should
sl@0: 		 * be the first thread with thread ID >= 100.
sl@0: 		 */
sl@0: 		TUint64 iStartElement;
sl@0: 	
sl@0: 		/** Memory address of where the data should be written */
sl@0: 		TAny* iBufferAddress;
sl@0: 	
sl@0: 		/** Size of the buffer available for writing the data into */
sl@0: 		TUint32 iBufferSize;
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	 * Structure that describes a list being returned
sl@0: 	 */
sl@0: 	struct TListReturn
sl@0: 		{
sl@0: 		/** List that is being returned */
sl@0: 		TUint32 iReqNo;
sl@0: 
sl@0: 		/** Number of items in the returned list */
sl@0: 		TUint32 iNumberItems;
sl@0: 
sl@0: 		/** Size occupied by data */
sl@0: 		TUint32 iDataSize;
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	 * Class used to add extended functionality to DDebuggerInfo class.
sl@0: 	 * 
sl@0: 	 * @publishedPartner
sl@0: 	 * @prototype
sl@0: 	 */
sl@0: 	class DStopModeExtension
sl@0: 		{
sl@0: 		public:
sl@0: 			DStopModeExtension()
sl@0: 				:iFunctionalityBlock(NULL),
sl@0: 				iSpare1(0),
sl@0: 				iSpare2(0),
sl@0: 				iSpare3(0),
sl@0: 				iSpare4(0),
sl@0: 				iSpare5(0),
sl@0: 				iSpare6(0),
sl@0: 				iSpare7(0)
sl@0: 				{};        
sl@0: 		   
sl@0: 			static void Install(DStopModeExtension* aExt);
sl@0: 			
sl@0: 		public:
sl@0: 			Debug::DFunctionalityBlock* iFunctionalityBlock;
sl@0: 			TUint32 iSpare1;
sl@0: 			TUint32 iSpare2;
sl@0: 			TUint32 iSpare3;
sl@0: 			TUint32 iSpare4;
sl@0: 			TUint32 iSpare5;
sl@0: 			TUint32 iSpare6;
sl@0: 			TUint32 iSpare7;
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	 * This is the interface to the stop mode debug API. The ROM resident address of these functions can be found 
sl@0: 	 * from the Debug Functionality block via the superpage. It may be assumed that all of these functions
sl@0: 	 * will exit via the function ExitPoint and thus setting a breakpoint there will capture the end of execution.
sl@0: 	 * For more detailed information, see the stop mode guide.
sl@0: 	 */
sl@0: 	class StopModeDebug
sl@0: 			{
sl@0: 			public:
sl@0: 				/**
sl@0: 				 * Stop mode debug API. Call this to action any request for information, or to manipulate
sl@0: 				 * debug data.
sl@0: 				 * 
sl@0: 				 * This is a stateless interface - it does not record information about previous invocations. It
sl@0: 				 * does not take any OS locks, wait on any synchronisation objects, allocate/deallocate heap memory or call
sl@0: 				 * ANY OS routines (unless documented as doing so). It will not cause any exceptions due to page faults,
sl@0: 				 * but will report that it encountered such problems where appropriate.
sl@0: 				 *
sl@0: 				 * @pre This must be called with a valid stack in supervisor mode. There are no exceptions/interrupts
sl@0: 				 * enabled which will cause the OS state to change during the execution of this routine.
sl@0: 				 * @args aItem Structure describing the list we want to retrieve
sl@0: 				 * @args aCheckConsistent If true, this will honour any locks the system holds and return KErrNotReady
sl@0: 				 * @return KErrNone on success or one of the other system wide error codes.
sl@0: 				 */
sl@0: 				IMPORT_C static TInt GetList(const TListItem* aItem, TBool aCheckConsistent);
sl@0: 
sl@0: 				/**
sl@0: 				 * Stop mode debug API
sl@0: 				 * 
sl@0: 				 * This is a test function that allows us to test our communications with the hardware debugger
sl@0: 				 * 
sl@0: 				 * @pre This must be called with a valid stack in supervisor mode. There are no exceptions/interrupts
sl@0: 				 * enabled which will cause the OS state to change during the execution of this routine.
sl@0: 				 * @args aItem Structure describing the list we want to retrieve
sl@0: 				 * @return KErrNone on success or one of the other system wide error codes.
sl@0: 				 */
sl@0: 				IMPORT_C static TInt TestAPI(const TListItem* aItem);
sl@0: 
sl@0: 			public:	
sl@0: 				static TInt ExitPoint(const TInt aReturnValue);
sl@0: 
sl@0: 			private:
sl@0: 				/** Code segment list routines */
sl@0: 				static TInt ProcessCodeSeg(TUint8*& aBuffer, TUint32& aBufferSize, DEpocCodeSeg* aCodeSeg);
sl@0: 			
sl@0: 				//TODO: Horrible signature. Structify it
sl@0: 				static TInt AppendCodeSegData(TUint8*& aBuffer, TUint32& aBufferSize, const TModuleMemoryInfo& aMemoryInfo, const TBool aIsXip, const TCodeSegType aCodeSegType, const TDesC8& aFileName, DEpocCodeSeg* aCodeSeg);
sl@0: 				static TInt GetCodeSegList(const TListItem* aItem, bool aCheckConsistent);
sl@0: 				static DEpocCodeSeg* GetNextCodeSeg(const TUint32 aStart, const Debug::TListScope aListScope, const TUint64 aScopeData);
sl@0: 				static DEpocCodeSeg* GetNextGlobalCodeSeg(const TUint32 aStart);
sl@0: 				static DEpocCodeSeg* GetNextThreadSpecificCodeSeg(const TUint32 aStart, const TUint64 aThreadId);
sl@0: 
sl@0: 				/** Process list routines */
sl@0: 				static TInt GetProcessList(const TListItem* aItem, bool aCheckConsistent);	
sl@0: 				static TInt AppendProcessToBuffer(DProcess* aProc, TUint8* aBuffer, TUint8* aBufferEnd, TUint32& aProcSize);
sl@0: 				
sl@0: 				/** Static Info Retrieval routines */
sl@0: 				static TInt GetStaticInfo(const TListItem* aItem, bool aCheckConsistent);
sl@0: 				
sl@0: 				static void GetObjectFullName(const DObject* aObj, TFullName& aName);
sl@0: 		
sl@0: 				/** Utility functions */
sl@0: 				static TInt CopyAndExpandDes(const TDesC& aSrc, TDes& aDest);
sl@0: 				
sl@0: 			};
sl@0: 
sl@0: 	};
sl@0: #endif // D_STOP_MODE_API_H
sl@0: 
sl@0: // End of file sm_debug_api.h