|
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". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // Definition of the stop-mode debug interface. |
|
15 // |
|
16 |
|
17 /** |
|
18 @file |
|
19 @publishedPartner |
|
20 @prototype |
|
21 */ |
|
22 |
|
23 #ifndef D_STOP_MODE_API_H |
|
24 #define D_STOP_MODE_API_H |
|
25 |
|
26 #include <rm_debug_api.h> |
|
27 #include <plat_priv.h> |
|
28 |
|
29 namespace Debug |
|
30 { |
|
31 /** |
|
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 |
|
38 */ |
|
39 |
|
40 /** Stop Mode Debug API Version Numbers */ |
|
41 const TUint KStopModeMajorVersionNumber=0; |
|
42 const TUint KStopModeMinorVersionNumber=0; |
|
43 const TUint KStopModePatchVersionNumber=2; |
|
44 |
|
45 /** |
|
46 * Enumerators used to identify the buffers created for use with the Stop-Mode Debug API. |
|
47 */ |
|
48 enum TBufferType |
|
49 { |
|
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. */ |
|
53 |
|
54 /** |
|
55 * @internalTechnology |
|
56 * A user should find the number of buffer tags from the DFBlock rather than this enumerator. |
|
57 */ |
|
58 EBuffersLast |
|
59 }; |
|
60 |
|
61 /** |
|
62 * Enumerators used to identify the functions for use with the Stop-Mode Debug API. |
|
63 */ |
|
64 enum TFunctionalityStopModeFunctions |
|
65 { |
|
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. */ |
|
69 |
|
70 /** |
|
71 * @internalTechnology |
|
72 * A user should find the number of supported functions from the DFBlock rather than this enumerator. |
|
73 */ |
|
74 EStopModeFunctionsLast |
|
75 }; |
|
76 |
|
77 /** |
|
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. |
|
82 */ |
|
83 struct DFunctionalityBlock |
|
84 { |
|
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. */ |
|
88 }; |
|
89 |
|
90 /** |
|
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. |
|
94 */ |
|
95 class TStaticListEntry |
|
96 { |
|
97 public: |
|
98 |
|
99 /** Build time of ROM in microseconds */ |
|
100 TUint64 iTime; |
|
101 |
|
102 /** Number of CPUs */ |
|
103 TInt iCpuNumbers; |
|
104 |
|
105 /** ROM build number */ |
|
106 TUint16 iBuildNumber; |
|
107 |
|
108 /** Major Version of ROM build */ |
|
109 TUint8 iMajorVersion; |
|
110 |
|
111 /** Minor Version of ROM build */ |
|
112 TUint8 iMinorVersion; |
|
113 |
|
114 /** Currently unused element. May be used in future to aid maintaining compatibility. */ |
|
115 TUint32 iSpare[10]; |
|
116 }; |
|
117 |
|
118 /** |
|
119 * This structure represents a request to return a list via the SM API |
|
120 */ |
|
121 struct TListItem |
|
122 { |
|
123 /** Size of this TListItem */ |
|
124 TUint32 iSize; |
|
125 |
|
126 /** The type of list to return */ |
|
127 TListId iListId; |
|
128 |
|
129 /** The scope of the list to return */ |
|
130 TListScope iListScope; |
|
131 |
|
132 /** |
|
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. |
|
136 */ |
|
137 TUint64 iScopeData; |
|
138 |
|
139 /** |
|
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. |
|
143 */ |
|
144 TUint64 iStartElement; |
|
145 |
|
146 /** Memory address of where the data should be written */ |
|
147 TAny* iBufferAddress; |
|
148 |
|
149 /** Size of the buffer available for writing the data into */ |
|
150 TUint32 iBufferSize; |
|
151 }; |
|
152 |
|
153 /** |
|
154 * Structure that describes a list being returned |
|
155 */ |
|
156 struct TListReturn |
|
157 { |
|
158 /** List that is being returned */ |
|
159 TUint32 iReqNo; |
|
160 |
|
161 /** Number of items in the returned list */ |
|
162 TUint32 iNumberItems; |
|
163 |
|
164 /** Size occupied by data */ |
|
165 TUint32 iDataSize; |
|
166 }; |
|
167 |
|
168 /** |
|
169 * Class used to add extended functionality to DDebuggerInfo class. |
|
170 * |
|
171 * @publishedPartner |
|
172 * @prototype |
|
173 */ |
|
174 class DStopModeExtension |
|
175 { |
|
176 public: |
|
177 DStopModeExtension() |
|
178 :iFunctionalityBlock(NULL), |
|
179 iSpare1(0), |
|
180 iSpare2(0), |
|
181 iSpare3(0), |
|
182 iSpare4(0), |
|
183 iSpare5(0), |
|
184 iSpare6(0), |
|
185 iSpare7(0) |
|
186 {}; |
|
187 |
|
188 static void Install(DStopModeExtension* aExt); |
|
189 |
|
190 public: |
|
191 Debug::DFunctionalityBlock* iFunctionalityBlock; |
|
192 TUint32 iSpare1; |
|
193 TUint32 iSpare2; |
|
194 TUint32 iSpare3; |
|
195 TUint32 iSpare4; |
|
196 TUint32 iSpare5; |
|
197 TUint32 iSpare6; |
|
198 TUint32 iSpare7; |
|
199 }; |
|
200 |
|
201 /** |
|
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. |
|
206 */ |
|
207 class StopModeDebug |
|
208 { |
|
209 public: |
|
210 /** |
|
211 * Stop mode debug API. Call this to action any request for information, or to manipulate |
|
212 * debug data. |
|
213 * |
|
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. |
|
218 * |
|
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. |
|
224 */ |
|
225 IMPORT_C static TInt GetList(const TListItem* aItem, TBool aCheckConsistent); |
|
226 |
|
227 /** |
|
228 * Stop mode debug API |
|
229 * |
|
230 * This is a test function that allows us to test our communications with the hardware debugger |
|
231 * |
|
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. |
|
236 */ |
|
237 IMPORT_C static TInt TestAPI(const TListItem* aItem); |
|
238 |
|
239 public: |
|
240 static TInt ExitPoint(const TInt aReturnValue); |
|
241 |
|
242 private: |
|
243 /** Code segment list routines */ |
|
244 static TInt ProcessCodeSeg(TUint8*& aBuffer, TUint32& aBufferSize, DEpocCodeSeg* aCodeSeg); |
|
245 |
|
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); |
|
252 |
|
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); |
|
256 |
|
257 /** Static Info Retrieval routines */ |
|
258 static TInt GetStaticInfo(const TListItem* aItem, bool aCheckConsistent); |
|
259 |
|
260 static void GetObjectFullName(const DObject* aObj, TFullName& aName); |
|
261 |
|
262 /** Utility functions */ |
|
263 static TInt CopyAndExpandDes(const TDesC& aSrc, TDes& aDest); |
|
264 |
|
265 }; |
|
266 |
|
267 }; |
|
268 #endif // D_STOP_MODE_API_H |
|
269 |
|
270 // End of file sm_debug_api.h |