|
1 // Copyright (c) 2005-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 // |
|
15 // WARNING: This file contains some APIs which are internal and are subject |
|
16 // to change without notice. Such APIs should therefore not be used |
|
17 // outside the Kernel and Hardware Services package. |
|
18 // |
|
19 |
|
20 #ifndef D32BTRACE_H |
|
21 #define D32BTRACE_H |
|
22 |
|
23 #include <e32cmn.h> |
|
24 #include <e32ver.h> |
|
25 #include <e32btrace.h> |
|
26 |
|
27 #ifndef __KERNEL_MODE__ |
|
28 #include <e32std.h> |
|
29 #endif |
|
30 |
|
31 |
|
32 class TBTraceBuffer; |
|
33 |
|
34 /** |
|
35 Interface to the fast-trace memory buffer. |
|
36 |
|
37 @publishedPartner |
|
38 @released |
|
39 */ |
|
40 class RBTrace : public RBusLogicalChannel |
|
41 { |
|
42 public: |
|
43 /** |
|
44 Bit flags indicating the operational mode of the fast-trace buffer. |
|
45 */ |
|
46 enum TMode |
|
47 { |
|
48 /** |
|
49 Flag set to enable trace to be stored in the buffer. |
|
50 If this is not set, all trace records are discarded. |
|
51 */ |
|
52 EEnable = 1<<0, |
|
53 |
|
54 /** |
|
55 This flag dictates the behaviour which occurs when the trace buffer is too full to |
|
56 accomodate a new record. |
|
57 When this flag is set, new trace records will overwrite the oldest ones. |
|
58 When this flag is not set, new trace records are discard. |
|
59 (This latter mode provides the best performance.) |
|
60 */ |
|
61 EFreeRunning = 1<<1, |
|
62 }; |
|
63 |
|
64 #ifndef __KERNEL_MODE__ |
|
65 /** |
|
66 Open channel to fast-trace driver. |
|
67 Must be called before any other methods are used. |
|
68 @return KErrNone or standard error code. |
|
69 */ |
|
70 IMPORT_C TInt Open(); |
|
71 |
|
72 /** |
|
73 Close channel to fast-trace driver. |
|
74 */ |
|
75 IMPORT_C void Close(); |
|
76 |
|
77 /** |
|
78 Get the current size of trace buffer. |
|
79 @return Buffer size. |
|
80 */ |
|
81 IMPORT_C TInt BufferSize(); |
|
82 |
|
83 /** |
|
84 Change size of trace buffer. |
|
85 This causes all current data in the trace buffer to be lost. |
|
86 If this method fails then the trace buffer may no longer exist. |
|
87 @param aSize The size in bytes for the trace buffer. |
|
88 @return KErrNone or standard error code. |
|
89 */ |
|
90 IMPORT_C TInt ResizeBuffer(TInt aSize); |
|
91 |
|
92 /** |
|
93 Discard all trace data. |
|
94 */ |
|
95 IMPORT_C void Empty(); |
|
96 |
|
97 /** |
|
98 The chunk in which trace data returned by GetData() resides. |
|
99 @return The chunk. |
|
100 */ |
|
101 inline RChunk DataChunk(); |
|
102 |
|
103 /** |
|
104 The operational mode for fast-trace. |
|
105 @return The current operational mode. This is bitmask of values from TMode. |
|
106 */ |
|
107 IMPORT_C TUint Mode(); |
|
108 |
|
109 /** |
|
110 Set the operational mode for fast-trace. |
|
111 Calling this method, invalidates the trace data returned by the last call to GetData(). |
|
112 @param aMode A bitmask of values from TMode. |
|
113 */ |
|
114 IMPORT_C void SetMode(TUint aMode); |
|
115 |
|
116 /** |
|
117 Set the trace filter bit for the specified category. |
|
118 @param aCategory A category value from BTrace::TCategories. |
|
119 @param aValue The new filter value for the category. |
|
120 1 means traces of this category are output, 0 means they are suppressed. |
|
121 Any other value will be ignored, and this method will just return the current |
|
122 value of the filter. |
|
123 @return The previous value of the filter for the category, 0 or 1. |
|
124 Or KErrNotSupported if this category is not supported by this build of the kernel. |
|
125 */ |
|
126 IMPORT_C TInt SetFilter(TUint aCategory, TInt aValue); |
|
127 |
|
128 /** |
|
129 Get the trace filter bit for the specified category. |
|
130 @param aCategory A category value from enum BTrace::TCategory, |
|
131 @return The value of the filter for the category, 0 or 1, |
|
132 or KErrNotSupported if this category is not supported by this build of the kernel. |
|
133 (1 means traces of this category are output, 0 means they are suppressed.) |
|
134 */ |
|
135 inline TInt Filter(TUint aCategory); |
|
136 |
|
137 /** |
|
138 Set the trace secondary trace filter for the specified UID. |
|
139 |
|
140 This method can not be used to disable a UID key if SetFilter2(TInt aGlobalFilter) |
|
141 has been used to set the filter to pass all traces. Such attempts result in a return |
|
142 code of KErrNotSupported. |
|
143 |
|
144 @param aUid The UID to filter. |
|
145 @param aValue The new filter value for the UID. |
|
146 1 means traces with this UID are output, 0 means they are suppressed. |
|
147 Other values must not be used. |
|
148 |
|
149 @return The previous value of the filter for the UID, 0 or 1, if operation is successful. |
|
150 Otherwise, a negative number representing a system wide error code. |
|
151 (E.g. KErrNoMemory.) |
|
152 */ |
|
153 IMPORT_C TInt SetFilter2(TUint32 aUid, TBool aValue); |
|
154 |
|
155 /** |
|
156 Set the secondary trace filter to include only the specified UIDs. |
|
157 |
|
158 @param aUids Pointer to array of UIDs. |
|
159 @param aNumUids Number of UID values pointer to by \a aUid. |
|
160 |
|
161 @return KErrNone on success. |
|
162 Otherwise, a negative number representing a system wide error code. |
|
163 (E.g. KErrNoMemory.) |
|
164 */ |
|
165 IMPORT_C TInt SetFilter2(const TUint32* aUids, TInt aNumUids); |
|
166 |
|
167 /** |
|
168 Set the secondary trace filter to pass or reject every trace. |
|
169 |
|
170 @param aGlobalFilter If 0, the secondary filter will reject |
|
171 all traces; if 1, all traces are passed |
|
172 by the filter. |
|
173 Other values have no effect. |
|
174 |
|
175 @return The previous value of the global filter. |
|
176 */ |
|
177 IMPORT_C TInt SetFilter2(TInt aGlobalFilter); |
|
178 |
|
179 /** |
|
180 Get the contents of the secondary trace filter. |
|
181 |
|
182 @param [out] aUids Pointer to array of UIDs contained in the secondary filter. |
|
183 Ownership of this array is passed to the caller of this |
|
184 function, which is then responsible for deleting it. |
|
185 If filter is empty, \a aUid equals zero. |
|
186 @param [out] aGlobalFilter Set to 1 if the secondary filter passes all traces. |
|
187 Set to 0 if the secondary filter rejects all traces. |
|
188 Set to -1 if the secondary filter operates by UIDs contained in traces. |
|
189 |
|
190 @return Number of UIDs in returned array, if operation is successful. |
|
191 Otherwise, a negative number representing a system wide error code. |
|
192 */ |
|
193 IMPORT_C TInt Filter2(TUint32*& aUids, TInt& aGlobalFilter); |
|
194 |
|
195 /** |
|
196 Get pointer to as much contiguous trace data as is available. |
|
197 This data resides in the shared chunk DataChunk(). |
|
198 The data returned will always be a whole number of trace records, i.e. trace records |
|
199 will not be split between successive calls to this method. |
|
200 Once the data is no loger required, DataUsed() must be called. |
|
201 This method can be called repeatedly to get more trace data. E.g. |
|
202 @code |
|
203 RBTrace trace; |
|
204 TInt error = trace.Open(); |
|
205 if(error!=KErrNone) |
|
206 return error; |
|
207 const TInt KTraceDataBlockSize = 65536; // size of data we ideally want to process in one go |
|
208 TUint8* data; |
|
209 TInt size; |
|
210 do |
|
211 { |
|
212 while((size=trace.GetData(data))!=0) |
|
213 { |
|
214 ProcessTheTraceData(data,size); |
|
215 trace.DataUsed(); |
|
216 } |
|
217 TRequestStatus waitStatus; |
|
218 trace.RequestData(waitStatus,KTraceDataBlockSize); |
|
219 User::WaitForRequest(waitStatus); |
|
220 error = waitStatus.Int(); |
|
221 } |
|
222 while(error==KErrNone); |
|
223 trace.Close(); |
|
224 return error; |
|
225 @endcode |
|
226 |
|
227 @param aData Pointer to the first byte of trace data. |
|
228 @return The number of bytes of trace data available at aData. |
|
229 @see DataChunk(); |
|
230 */ |
|
231 IMPORT_C TInt GetData(TUint8*& aData); |
|
232 |
|
233 /** |
|
234 Remove from the trace buffer all of the data returned by the last call to GetData(). |
|
235 */ |
|
236 IMPORT_C void DataUsed(); |
|
237 |
|
238 /** |
|
239 Request notification when trace data becomes available. |
|
240 Only one outstanding request may be present at any one time. |
|
241 @param aStatus Request status to be complete with KErrNone once data becomes available. |
|
242 @param aSize The minimum number of bytes of trace data required. |
|
243 This is intended to improve performance by only signalling the client once |
|
244 a suitably large amount of trace data is available. However, this request |
|
245 may complete before this amount of trace data is available, therefore a |
|
246 client must be able to handle this situation. |
|
247 If aSize is zero or negative, then the request completes as soon as any trace |
|
248 data is available. |
|
249 @panic BTRACE 0 if a previous request is still pending |
|
250 */ |
|
251 IMPORT_C void RequestData(TRequestStatus& aStatus, TInt aSize); |
|
252 |
|
253 /** |
|
254 Cancel any previous RequestData(), completing it with KErrCancel. |
|
255 */ |
|
256 IMPORT_C void CancelRequestData(); |
|
257 |
|
258 /** |
|
259 @internalTechnology |
|
260 */ |
|
261 TBool SetSerialPortOutput(TBool aEnable); |
|
262 |
|
263 /** |
|
264 Controls whether Timestamp2 field is added to trace record headers. |
|
265 */ |
|
266 IMPORT_C TBool SetTimestamp2Enabled(TBool aEnable); |
|
267 |
|
268 #endif |
|
269 |
|
270 /** |
|
271 Enumeration of panic reasons for category 'BTRACE'. |
|
272 */ |
|
273 enum TPanic |
|
274 { |
|
275 ERequestAlreadyPending, /**< A call to RequestData() was made whist a request was already pending. */ |
|
276 }; |
|
277 private: |
|
278 TInt OpenChunk(); |
|
279 void CloseChunk(); |
|
280 inline static const TDesC& Name(); |
|
281 |
|
282 enum TControl |
|
283 { |
|
284 EOpenBuffer, |
|
285 EResizeBuffer, |
|
286 ESetFilter, |
|
287 ESetFilter2, |
|
288 ESetFilter2Array, |
|
289 ESetFilter2Global, |
|
290 EGetFilter2Part1, |
|
291 EGetFilter2Part2, |
|
292 ERequestData, |
|
293 ECancelRequestData, |
|
294 ESetSerialPortOutput, |
|
295 ESetTimestamp2Enabled, |
|
296 }; |
|
297 #ifndef __KERNEL_MODE__ |
|
298 RChunk iDataChunk; |
|
299 TBTraceBuffer* iBuffer; |
|
300 TInt iLastGetDataSize; |
|
301 TUint32 iSpare[4]; |
|
302 #endif |
|
303 friend class DBTraceChannel; |
|
304 friend class DBTraceFactory; |
|
305 friend class RBTraceAdapter; |
|
306 }; |
|
307 |
|
308 #ifndef __KERNEL_MODE__ |
|
309 |
|
310 inline RChunk RBTrace::DataChunk() |
|
311 { |
|
312 return iDataChunk; |
|
313 } |
|
314 |
|
315 inline TInt RBTrace::Filter(TUint aCategory) |
|
316 { |
|
317 return SetFilter(aCategory,-1); |
|
318 } |
|
319 |
|
320 #endif // !__KERNEL_MODE__ |
|
321 |
|
322 inline const TDesC& RBTrace::Name() |
|
323 { |
|
324 _LIT(KBTraceName,"btrace"); |
|
325 return KBTraceName; |
|
326 } |
|
327 |
|
328 |
|
329 /** |
|
330 @internalComponent |
|
331 */ |
|
332 class TBTraceBuffer |
|
333 { |
|
334 private: |
|
335 TUint iStart; |
|
336 TUint iEnd; |
|
337 volatile TUint iHead; |
|
338 volatile TUint iTail; |
|
339 volatile TUint iWrap; |
|
340 volatile TUint iGeneration; |
|
341 volatile TUint iMode; |
|
342 TUint iRecordOffsets; |
|
343 TUint iCopyBuffer; |
|
344 TUint iCopyBufferSize; |
|
345 private: |
|
346 TInt Data(TUint& aData, TUint& aTail); |
|
347 TInt Adjust(TUint aTail, TInt aSize); |
|
348 TInt CopyData(TUint aData, TUint aTail, TInt aSize); |
|
349 TUint UpdateTail(TUint32 aOld, TUint32 aNew); |
|
350 TInt GetData(TUint8*& aData); |
|
351 |
|
352 friend class RBTrace; |
|
353 friend class TBTraceBufferK; |
|
354 friend class RBTraceAdapter; |
|
355 }; |
|
356 |
|
357 |
|
358 |
|
359 #endif |