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