1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/include/sm_debug_api.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,270 @@
1.4 +// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// Definition of the stop-mode debug interface.
1.18 +//
1.19 +
1.20 +/**
1.21 +@file
1.22 +@publishedPartner
1.23 +@prototype
1.24 +*/
1.25 +
1.26 +#ifndef D_STOP_MODE_API_H
1.27 +#define D_STOP_MODE_API_H
1.28 +
1.29 +#include <rm_debug_api.h>
1.30 +#include <plat_priv.h>
1.31 +
1.32 +namespace Debug
1.33 + {
1.34 + /**
1.35 + * The stop-mode debug interface is a stateless interface which may be called at any point
1.36 + * except user mode, provided the rest of the OS is not going to run or pre-empt it.
1.37 + * For example, for stop-mode debugging, the ICE may run the stop_mode_api routine to
1.38 + * collect information about the system so long as no exceptions are enabled, and all
1.39 + * registers/stack are preserved and restored after the call completes. Note that in an SMP environment
1.40 + * it is expected that ALL the CPU's have been stopped
1.41 + */
1.42 +
1.43 + /** Stop Mode Debug API Version Numbers */
1.44 + const TUint KStopModeMajorVersionNumber=0;
1.45 + const TUint KStopModeMinorVersionNumber=0;
1.46 + const TUint KStopModePatchVersionNumber=2;
1.47 +
1.48 + /**
1.49 + * Enumerators used to identify the buffers created for use with the Stop-Mode Debug API.
1.50 + */
1.51 + enum TBufferType
1.52 + {
1.53 + EBuffersFunctionality = 0, /**< Enumerator corresponding to the buffer created to store the debug functionality block. */
1.54 + EBuffersRequest = 1, /**< Enumerator corresponding to the request buffer. */
1.55 + EBuffersResponse = 2, /**< Enumerator corresponding to the response buffer. */
1.56 +
1.57 + /**
1.58 + * @internalTechnology
1.59 + * A user should find the number of buffer tags from the DFBlock rather than this enumerator.
1.60 + */
1.61 + EBuffersLast
1.62 + };
1.63 +
1.64 + /**
1.65 + * Enumerators used to identify the functions for use with the Stop-Mode Debug API.
1.66 + */
1.67 + enum TFunctionalityStopModeFunctions
1.68 + {
1.69 + EStopModeFunctionsExitPoint = 0, /**< Enumerator corresponding to the Debug::GetList() function. */
1.70 + EStopModeFunctionsGetList = 1, /**< Enumerator corresponding to the Debug::ExitPoint() function. */
1.71 + EStopModeFunctionsTestAPI = 2, /**< Enumerator corresponding to the Debug::TestAPI() function. */
1.72 +
1.73 + /**
1.74 + * @internalTechnology
1.75 + * A user should find the number of supported functions from the DFBlock rather than this enumerator.
1.76 + */
1.77 + EStopModeFunctionsLast
1.78 + };
1.79 +
1.80 + /**
1.81 + * This structure defines the start elements of a stop-mode debug functionality block.
1.82 + * It is assumed that the rest of the functionality block will extend past the end of
1.83 + * the structure and will be accessed according to the documented format of the
1.84 + * stop-mode functionality block.
1.85 + */
1.86 + struct DFunctionalityBlock
1.87 + {
1.88 + TUint32 iSize; /**< Size of the functionality block in bytes. */
1.89 + TVersion iStopModeVersion; /** Version of the stop-mode debug API. */
1.90 + TTagHeader iFirstHeader; /** The header for the first sub-block in the functionality block. */
1.91 + };
1.92 +
1.93 + /**
1.94 + * This structure used for extracting static data using the Stop Mode Extension API
1.95 + * StopModeDebug::GetList using TListId::EStaticInfo
1.96 + * as the first argument.
1.97 + */
1.98 + class TStaticListEntry
1.99 + {
1.100 + public:
1.101 +
1.102 + /** Build time of ROM in microseconds */
1.103 + TUint64 iTime;
1.104 +
1.105 + /** Number of CPUs */
1.106 + TInt iCpuNumbers;
1.107 +
1.108 + /** ROM build number */
1.109 + TUint16 iBuildNumber;
1.110 +
1.111 + /** Major Version of ROM build */
1.112 + TUint8 iMajorVersion;
1.113 +
1.114 + /** Minor Version of ROM build */
1.115 + TUint8 iMinorVersion;
1.116 +
1.117 + /** Currently unused element. May be used in future to aid maintaining compatibility. */
1.118 + TUint32 iSpare[10];
1.119 + };
1.120 +
1.121 + /**
1.122 + * This structure represents a request to return a list via the SM API
1.123 + */
1.124 + struct TListItem
1.125 + {
1.126 + /** Size of this TListItem */
1.127 + TUint32 iSize;
1.128 +
1.129 + /** The type of list to return */
1.130 + TListId iListId;
1.131 +
1.132 + /** The scope of the list to return */
1.133 + TListScope iListScope;
1.134 +
1.135 + /**
1.136 + * Data corresponding to the list scope, for example if iListScope specifies a thread
1.137 + * specific listing then iScopeData should contain the thread ID to return the list for.
1.138 + * If iListScope = EGlobalScope then iScopeData is ignored.
1.139 + */
1.140 + TUint64 iScopeData;
1.141 +
1.142 + /**
1.143 + * The first element in the target list to return data for. For example if a thread list is being
1.144 + * requested then specifying iStartElement = 100 indicates that the first thread to be returned should
1.145 + * be the first thread with thread ID >= 100.
1.146 + */
1.147 + TUint64 iStartElement;
1.148 +
1.149 + /** Memory address of where the data should be written */
1.150 + TAny* iBufferAddress;
1.151 +
1.152 + /** Size of the buffer available for writing the data into */
1.153 + TUint32 iBufferSize;
1.154 + };
1.155 +
1.156 + /**
1.157 + * Structure that describes a list being returned
1.158 + */
1.159 + struct TListReturn
1.160 + {
1.161 + /** List that is being returned */
1.162 + TUint32 iReqNo;
1.163 +
1.164 + /** Number of items in the returned list */
1.165 + TUint32 iNumberItems;
1.166 +
1.167 + /** Size occupied by data */
1.168 + TUint32 iDataSize;
1.169 + };
1.170 +
1.171 + /**
1.172 + * Class used to add extended functionality to DDebuggerInfo class.
1.173 + *
1.174 + * @publishedPartner
1.175 + * @prototype
1.176 + */
1.177 + class DStopModeExtension
1.178 + {
1.179 + public:
1.180 + DStopModeExtension()
1.181 + :iFunctionalityBlock(NULL),
1.182 + iSpare1(0),
1.183 + iSpare2(0),
1.184 + iSpare3(0),
1.185 + iSpare4(0),
1.186 + iSpare5(0),
1.187 + iSpare6(0),
1.188 + iSpare7(0)
1.189 + {};
1.190 +
1.191 + static void Install(DStopModeExtension* aExt);
1.192 +
1.193 + public:
1.194 + Debug::DFunctionalityBlock* iFunctionalityBlock;
1.195 + TUint32 iSpare1;
1.196 + TUint32 iSpare2;
1.197 + TUint32 iSpare3;
1.198 + TUint32 iSpare4;
1.199 + TUint32 iSpare5;
1.200 + TUint32 iSpare6;
1.201 + TUint32 iSpare7;
1.202 + };
1.203 +
1.204 + /**
1.205 + * This is the interface to the stop mode debug API. The ROM resident address of these functions can be found
1.206 + * from the Debug Functionality block via the superpage. It may be assumed that all of these functions
1.207 + * will exit via the function ExitPoint and thus setting a breakpoint there will capture the end of execution.
1.208 + * For more detailed information, see the stop mode guide.
1.209 + */
1.210 + class StopModeDebug
1.211 + {
1.212 + public:
1.213 + /**
1.214 + * Stop mode debug API. Call this to action any request for information, or to manipulate
1.215 + * debug data.
1.216 + *
1.217 + * This is a stateless interface - it does not record information about previous invocations. It
1.218 + * does not take any OS locks, wait on any synchronisation objects, allocate/deallocate heap memory or call
1.219 + * ANY OS routines (unless documented as doing so). It will not cause any exceptions due to page faults,
1.220 + * but will report that it encountered such problems where appropriate.
1.221 + *
1.222 + * @pre This must be called with a valid stack in supervisor mode. There are no exceptions/interrupts
1.223 + * enabled which will cause the OS state to change during the execution of this routine.
1.224 + * @args aItem Structure describing the list we want to retrieve
1.225 + * @args aCheckConsistent If true, this will honour any locks the system holds and return KErrNotReady
1.226 + * @return KErrNone on success or one of the other system wide error codes.
1.227 + */
1.228 + IMPORT_C static TInt GetList(const TListItem* aItem, TBool aCheckConsistent);
1.229 +
1.230 + /**
1.231 + * Stop mode debug API
1.232 + *
1.233 + * This is a test function that allows us to test our communications with the hardware debugger
1.234 + *
1.235 + * @pre This must be called with a valid stack in supervisor mode. There are no exceptions/interrupts
1.236 + * enabled which will cause the OS state to change during the execution of this routine.
1.237 + * @args aItem Structure describing the list we want to retrieve
1.238 + * @return KErrNone on success or one of the other system wide error codes.
1.239 + */
1.240 + IMPORT_C static TInt TestAPI(const TListItem* aItem);
1.241 +
1.242 + public:
1.243 + static TInt ExitPoint(const TInt aReturnValue);
1.244 +
1.245 + private:
1.246 + /** Code segment list routines */
1.247 + static TInt ProcessCodeSeg(TUint8*& aBuffer, TUint32& aBufferSize, DEpocCodeSeg* aCodeSeg);
1.248 +
1.249 + //TODO: Horrible signature. Structify it
1.250 + static TInt AppendCodeSegData(TUint8*& aBuffer, TUint32& aBufferSize, const TModuleMemoryInfo& aMemoryInfo, const TBool aIsXip, const TCodeSegType aCodeSegType, const TDesC8& aFileName, DEpocCodeSeg* aCodeSeg);
1.251 + static TInt GetCodeSegList(const TListItem* aItem, bool aCheckConsistent);
1.252 + static DEpocCodeSeg* GetNextCodeSeg(const TUint32 aStart, const Debug::TListScope aListScope, const TUint64 aScopeData);
1.253 + static DEpocCodeSeg* GetNextGlobalCodeSeg(const TUint32 aStart);
1.254 + static DEpocCodeSeg* GetNextThreadSpecificCodeSeg(const TUint32 aStart, const TUint64 aThreadId);
1.255 +
1.256 + /** Process list routines */
1.257 + static TInt GetProcessList(const TListItem* aItem, bool aCheckConsistent);
1.258 + static TInt AppendProcessToBuffer(DProcess* aProc, TUint8* aBuffer, TUint8* aBufferEnd, TUint32& aProcSize);
1.259 +
1.260 + /** Static Info Retrieval routines */
1.261 + static TInt GetStaticInfo(const TListItem* aItem, bool aCheckConsistent);
1.262 +
1.263 + static void GetObjectFullName(const DObject* aObj, TFullName& aName);
1.264 +
1.265 + /** Utility functions */
1.266 + static TInt CopyAndExpandDes(const TDesC& aSrc, TDes& aDest);
1.267 +
1.268 + };
1.269 +
1.270 + };
1.271 +#endif // D_STOP_MODE_API_H
1.272 +
1.273 +// End of file sm_debug_api.h