1 // Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of the License "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // Definition of the stop-mode debug interface.
23 #ifndef D_STOP_MODE_API_H
24 #define D_STOP_MODE_API_H
26 #include <rm_debug_api.h>
27 #include <plat_priv.h>
32 * The stop-mode debug interface is a stateless interface which may be called at any point
33 * except user mode, provided the rest of the OS is not going to run or pre-empt it.
34 * For example, for stop-mode debugging, the ICE may run the stop_mode_api routine to
35 * collect information about the system so long as no exceptions are enabled, and all
36 * registers/stack are preserved and restored after the call completes. Note that in an SMP environment
37 * it is expected that ALL the CPU's have been stopped
40 /** Stop Mode Debug API Version Numbers */
41 const TUint KStopModeMajorVersionNumber=0;
42 const TUint KStopModeMinorVersionNumber=0;
43 const TUint KStopModePatchVersionNumber=2;
46 * Enumerators used to identify the buffers created for use with the Stop-Mode Debug API.
50 EBuffersFunctionality = 0, /**< Enumerator corresponding to the buffer created to store the debug functionality block. */
51 EBuffersRequest = 1, /**< Enumerator corresponding to the request buffer. */
52 EBuffersResponse = 2, /**< Enumerator corresponding to the response buffer. */
56 * A user should find the number of buffer tags from the DFBlock rather than this enumerator.
62 * Enumerators used to identify the functions for use with the Stop-Mode Debug API.
64 enum TFunctionalityStopModeFunctions
66 EStopModeFunctionsExitPoint = 0, /**< Enumerator corresponding to the Debug::GetList() function. */
67 EStopModeFunctionsGetList = 1, /**< Enumerator corresponding to the Debug::ExitPoint() function. */
68 EStopModeFunctionsTestAPI = 2, /**< Enumerator corresponding to the Debug::TestAPI() function. */
72 * A user should find the number of supported functions from the DFBlock rather than this enumerator.
74 EStopModeFunctionsLast
78 * This structure defines the start elements of a stop-mode debug functionality block.
79 * It is assumed that the rest of the functionality block will extend past the end of
80 * the structure and will be accessed according to the documented format of the
81 * stop-mode functionality block.
83 struct DFunctionalityBlock
85 TUint32 iSize; /**< Size of the functionality block in bytes. */
86 TVersion iStopModeVersion; /** Version of the stop-mode debug API. */
87 TTagHeader iFirstHeader; /** The header for the first sub-block in the functionality block. */
91 * This structure used for extracting static data using the Stop Mode Extension API
92 * StopModeDebug::GetList using TListId::EStaticInfo
93 * as the first argument.
95 class TStaticListEntry
99 /** Build time of ROM in microseconds */
102 /** Number of CPUs */
105 /** ROM build number */
106 TUint16 iBuildNumber;
108 /** Major Version of ROM build */
109 TUint8 iMajorVersion;
111 /** Minor Version of ROM build */
112 TUint8 iMinorVersion;
114 /** Currently unused element. May be used in future to aid maintaining compatibility. */
119 * This structure represents a request to return a list via the SM API
123 /** Size of this TListItem */
126 /** The type of list to return */
129 /** The scope of the list to return */
130 TListScope iListScope;
133 * Data corresponding to the list scope, for example if iListScope specifies a thread
134 * specific listing then iScopeData should contain the thread ID to return the list for.
135 * If iListScope = EGlobalScope then iScopeData is ignored.
140 * The first element in the target list to return data for. For example if a thread list is being
141 * requested then specifying iStartElement = 100 indicates that the first thread to be returned should
142 * be the first thread with thread ID >= 100.
144 TUint64 iStartElement;
146 /** Memory address of where the data should be written */
147 TAny* iBufferAddress;
149 /** Size of the buffer available for writing the data into */
154 * Structure that describes a list being returned
158 /** List that is being returned */
161 /** Number of items in the returned list */
162 TUint32 iNumberItems;
164 /** Size occupied by data */
169 * Class used to add extended functionality to DDebuggerInfo class.
174 class DStopModeExtension
178 :iFunctionalityBlock(NULL),
188 static void Install(DStopModeExtension* aExt);
191 Debug::DFunctionalityBlock* iFunctionalityBlock;
202 * This is the interface to the stop mode debug API. The ROM resident address of these functions can be found
203 * from the Debug Functionality block via the superpage. It may be assumed that all of these functions
204 * will exit via the function ExitPoint and thus setting a breakpoint there will capture the end of execution.
205 * For more detailed information, see the stop mode guide.
211 * Stop mode debug API. Call this to action any request for information, or to manipulate
214 * This is a stateless interface - it does not record information about previous invocations. It
215 * does not take any OS locks, wait on any synchronisation objects, allocate/deallocate heap memory or call
216 * ANY OS routines (unless documented as doing so). It will not cause any exceptions due to page faults,
217 * but will report that it encountered such problems where appropriate.
219 * @pre This must be called with a valid stack in supervisor mode. There are no exceptions/interrupts
220 * enabled which will cause the OS state to change during the execution of this routine.
221 * @args aItem Structure describing the list we want to retrieve
222 * @args aCheckConsistent If true, this will honour any locks the system holds and return KErrNotReady
223 * @return KErrNone on success or one of the other system wide error codes.
225 IMPORT_C static TInt GetList(const TListItem* aItem, TBool aCheckConsistent);
228 * Stop mode debug API
230 * This is a test function that allows us to test our communications with the hardware debugger
232 * @pre This must be called with a valid stack in supervisor mode. There are no exceptions/interrupts
233 * enabled which will cause the OS state to change during the execution of this routine.
234 * @args aItem Structure describing the list we want to retrieve
235 * @return KErrNone on success or one of the other system wide error codes.
237 IMPORT_C static TInt TestAPI(const TListItem* aItem);
240 static TInt ExitPoint(const TInt aReturnValue);
243 /** Code segment list routines */
244 static TInt ProcessCodeSeg(TUint8*& aBuffer, TUint32& aBufferSize, DEpocCodeSeg* aCodeSeg);
246 //TODO: Horrible signature. Structify it
247 static TInt AppendCodeSegData(TUint8*& aBuffer, TUint32& aBufferSize, const TModuleMemoryInfo& aMemoryInfo, const TBool aIsXip, const TCodeSegType aCodeSegType, const TDesC8& aFileName, DEpocCodeSeg* aCodeSeg);
248 static TInt GetCodeSegList(const TListItem* aItem, bool aCheckConsistent);
249 static DEpocCodeSeg* GetNextCodeSeg(const TUint32 aStart, const Debug::TListScope aListScope, const TUint64 aScopeData);
250 static DEpocCodeSeg* GetNextGlobalCodeSeg(const TUint32 aStart);
251 static DEpocCodeSeg* GetNextThreadSpecificCodeSeg(const TUint32 aStart, const TUint64 aThreadId);
253 /** Process list routines */
254 static TInt GetProcessList(const TListItem* aItem, bool aCheckConsistent);
255 static TInt AppendProcessToBuffer(DProcess* aProc, TUint8* aBuffer, TUint8* aBufferEnd, TUint32& aProcSize);
257 /** Static Info Retrieval routines */
258 static TInt GetStaticInfo(const TListItem* aItem, bool aCheckConsistent);
260 static void GetObjectFullName(const DObject* aObj, TFullName& aName);
262 /** Utility functions */
263 static TInt CopyAndExpandDes(const TDesC& aSrc, TDes& aDest);
268 #endif // D_STOP_MODE_API_H
270 // End of file sm_debug_api.h