1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/include/d32btrace.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,359 @@
1.4 +// Copyright (c) 2005-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 +//
1.18 +// WARNING: This file contains some APIs which are internal and are subject
1.19 +// to change without notice. Such APIs should therefore not be used
1.20 +// outside the Kernel and Hardware Services package.
1.21 +//
1.22 +
1.23 +#ifndef D32BTRACE_H
1.24 +#define D32BTRACE_H
1.25 +
1.26 +#include <e32cmn.h>
1.27 +#include <e32ver.h>
1.28 +#include <e32btrace.h>
1.29 +
1.30 +#ifndef __KERNEL_MODE__
1.31 +#include <e32std.h>
1.32 +#endif
1.33 +
1.34 +
1.35 +class TBTraceBuffer;
1.36 +
1.37 +/**
1.38 +Interface to the fast-trace memory buffer.
1.39 +
1.40 +@publishedPartner
1.41 +@released
1.42 +*/
1.43 +class RBTrace : public RBusLogicalChannel
1.44 + {
1.45 +public:
1.46 + /**
1.47 + Bit flags indicating the operational mode of the fast-trace buffer.
1.48 + */
1.49 + enum TMode
1.50 + {
1.51 + /**
1.52 + Flag set to enable trace to be stored in the buffer.
1.53 + If this is not set, all trace records are discarded.
1.54 + */
1.55 + EEnable = 1<<0,
1.56 +
1.57 + /**
1.58 + This flag dictates the behaviour which occurs when the trace buffer is too full to
1.59 + accomodate a new record.
1.60 + When this flag is set, new trace records will overwrite the oldest ones.
1.61 + When this flag is not set, new trace records are discard.
1.62 + (This latter mode provides the best performance.)
1.63 + */
1.64 + EFreeRunning = 1<<1,
1.65 + };
1.66 +
1.67 +#ifndef __KERNEL_MODE__
1.68 + /**
1.69 + Open channel to fast-trace driver.
1.70 + Must be called before any other methods are used.
1.71 + @return KErrNone or standard error code.
1.72 + */
1.73 + IMPORT_C TInt Open();
1.74 +
1.75 + /**
1.76 + Close channel to fast-trace driver.
1.77 + */
1.78 + IMPORT_C void Close();
1.79 +
1.80 + /**
1.81 + Get the current size of trace buffer.
1.82 + @return Buffer size.
1.83 + */
1.84 + IMPORT_C TInt BufferSize();
1.85 +
1.86 + /**
1.87 + Change size of trace buffer.
1.88 + This causes all current data in the trace buffer to be lost.
1.89 + If this method fails then the trace buffer may no longer exist.
1.90 + @param aSize The size in bytes for the trace buffer.
1.91 + @return KErrNone or standard error code.
1.92 + */
1.93 + IMPORT_C TInt ResizeBuffer(TInt aSize);
1.94 +
1.95 + /**
1.96 + Discard all trace data.
1.97 + */
1.98 + IMPORT_C void Empty();
1.99 +
1.100 + /**
1.101 + The chunk in which trace data returned by GetData() resides.
1.102 + @return The chunk.
1.103 + */
1.104 + inline RChunk DataChunk();
1.105 +
1.106 + /**
1.107 + The operational mode for fast-trace.
1.108 + @return The current operational mode. This is bitmask of values from TMode.
1.109 + */
1.110 + IMPORT_C TUint Mode();
1.111 +
1.112 + /**
1.113 + Set the operational mode for fast-trace.
1.114 + Calling this method, invalidates the trace data returned by the last call to GetData().
1.115 + @param aMode A bitmask of values from TMode.
1.116 + */
1.117 + IMPORT_C void SetMode(TUint aMode);
1.118 +
1.119 + /**
1.120 + Set the trace filter bit for the specified category.
1.121 + @param aCategory A category value from BTrace::TCategories.
1.122 + @param aValue The new filter value for the category.
1.123 + 1 means traces of this category are output, 0 means they are suppressed.
1.124 + Any other value will be ignored, and this method will just return the current
1.125 + value of the filter.
1.126 + @return The previous value of the filter for the category, 0 or 1.
1.127 + Or KErrNotSupported if this category is not supported by this build of the kernel.
1.128 + */
1.129 + IMPORT_C TInt SetFilter(TUint aCategory, TInt aValue);
1.130 +
1.131 + /**
1.132 + Get the trace filter bit for the specified category.
1.133 + @param aCategory A category value from enum BTrace::TCategory,
1.134 + @return The value of the filter for the category, 0 or 1,
1.135 + or KErrNotSupported if this category is not supported by this build of the kernel.
1.136 + (1 means traces of this category are output, 0 means they are suppressed.)
1.137 + */
1.138 + inline TInt Filter(TUint aCategory);
1.139 +
1.140 + /**
1.141 + Set the trace secondary trace filter for the specified UID.
1.142 +
1.143 + This method can not be used to disable a UID key if SetFilter2(TInt aGlobalFilter)
1.144 + has been used to set the filter to pass all traces. Such attempts result in a return
1.145 + code of KErrNotSupported.
1.146 +
1.147 + @param aUid The UID to filter.
1.148 + @param aValue The new filter value for the UID.
1.149 + 1 means traces with this UID are output, 0 means they are suppressed.
1.150 + Other values must not be used.
1.151 +
1.152 + @return The previous value of the filter for the UID, 0 or 1, if operation is successful.
1.153 + Otherwise, a negative number representing a system wide error code.
1.154 + (E.g. KErrNoMemory.)
1.155 + */
1.156 + IMPORT_C TInt SetFilter2(TUint32 aUid, TBool aValue);
1.157 +
1.158 + /**
1.159 + Set the secondary trace filter to include only the specified UIDs.
1.160 +
1.161 + @param aUids Pointer to array of UIDs.
1.162 + @param aNumUids Number of UID values pointer to by \a aUid.
1.163 +
1.164 + @return KErrNone on success.
1.165 + Otherwise, a negative number representing a system wide error code.
1.166 + (E.g. KErrNoMemory.)
1.167 + */
1.168 + IMPORT_C TInt SetFilter2(const TUint32* aUids, TInt aNumUids);
1.169 +
1.170 + /**
1.171 + Set the secondary trace filter to pass or reject every trace.
1.172 +
1.173 + @param aGlobalFilter If 0, the secondary filter will reject
1.174 + all traces; if 1, all traces are passed
1.175 + by the filter.
1.176 + Other values have no effect.
1.177 +
1.178 + @return The previous value of the global filter.
1.179 + */
1.180 + IMPORT_C TInt SetFilter2(TInt aGlobalFilter);
1.181 +
1.182 + /**
1.183 + Get the contents of the secondary trace filter.
1.184 +
1.185 + @param [out] aUids Pointer to array of UIDs contained in the secondary filter.
1.186 + Ownership of this array is passed to the caller of this
1.187 + function, which is then responsible for deleting it.
1.188 + If filter is empty, \a aUid equals zero.
1.189 + @param [out] aGlobalFilter Set to 1 if the secondary filter passes all traces.
1.190 + Set to 0 if the secondary filter rejects all traces.
1.191 + Set to -1 if the secondary filter operates by UIDs contained in traces.
1.192 +
1.193 + @return Number of UIDs in returned array, if operation is successful.
1.194 + Otherwise, a negative number representing a system wide error code.
1.195 + */
1.196 + IMPORT_C TInt Filter2(TUint32*& aUids, TInt& aGlobalFilter);
1.197 +
1.198 + /**
1.199 + Get pointer to as much contiguous trace data as is available.
1.200 + This data resides in the shared chunk DataChunk().
1.201 + The data returned will always be a whole number of trace records, i.e. trace records
1.202 + will not be split between successive calls to this method.
1.203 + Once the data is no loger required, DataUsed() must be called.
1.204 + This method can be called repeatedly to get more trace data. E.g.
1.205 + @code
1.206 + RBTrace trace;
1.207 + TInt error = trace.Open();
1.208 + if(error!=KErrNone)
1.209 + return error;
1.210 + const TInt KTraceDataBlockSize = 65536; // size of data we ideally want to process in one go
1.211 + TUint8* data;
1.212 + TInt size;
1.213 + do
1.214 + {
1.215 + while((size=trace.GetData(data))!=0)
1.216 + {
1.217 + ProcessTheTraceData(data,size);
1.218 + trace.DataUsed();
1.219 + }
1.220 + TRequestStatus waitStatus;
1.221 + trace.RequestData(waitStatus,KTraceDataBlockSize);
1.222 + User::WaitForRequest(waitStatus);
1.223 + error = waitStatus.Int();
1.224 + }
1.225 + while(error==KErrNone);
1.226 + trace.Close();
1.227 + return error;
1.228 + @endcode
1.229 +
1.230 + @param aData Pointer to the first byte of trace data.
1.231 + @return The number of bytes of trace data available at aData.
1.232 + @see DataChunk();
1.233 + */
1.234 + IMPORT_C TInt GetData(TUint8*& aData);
1.235 +
1.236 + /**
1.237 + Remove from the trace buffer all of the data returned by the last call to GetData().
1.238 + */
1.239 + IMPORT_C void DataUsed();
1.240 +
1.241 + /**
1.242 + Request notification when trace data becomes available.
1.243 + Only one outstanding request may be present at any one time.
1.244 + @param aStatus Request status to be complete with KErrNone once data becomes available.
1.245 + @param aSize The minimum number of bytes of trace data required.
1.246 + This is intended to improve performance by only signalling the client once
1.247 + a suitably large amount of trace data is available. However, this request
1.248 + may complete before this amount of trace data is available, therefore a
1.249 + client must be able to handle this situation.
1.250 + If aSize is zero or negative, then the request completes as soon as any trace
1.251 + data is available.
1.252 + @panic BTRACE 0 if a previous request is still pending
1.253 + */
1.254 + IMPORT_C void RequestData(TRequestStatus& aStatus, TInt aSize);
1.255 +
1.256 + /**
1.257 + Cancel any previous RequestData(), completing it with KErrCancel.
1.258 + */
1.259 + IMPORT_C void CancelRequestData();
1.260 +
1.261 + /**
1.262 + @internalTechnology
1.263 + */
1.264 + TBool SetSerialPortOutput(TBool aEnable);
1.265 +
1.266 + /**
1.267 + Controls whether Timestamp2 field is added to trace record headers.
1.268 + */
1.269 + IMPORT_C TBool SetTimestamp2Enabled(TBool aEnable);
1.270 +
1.271 +#endif
1.272 +
1.273 + /**
1.274 + Enumeration of panic reasons for category 'BTRACE'.
1.275 + */
1.276 + enum TPanic
1.277 + {
1.278 + ERequestAlreadyPending, /**< A call to RequestData() was made whist a request was already pending. */
1.279 + };
1.280 +private:
1.281 + TInt OpenChunk();
1.282 + void CloseChunk();
1.283 + inline static const TDesC& Name();
1.284 +
1.285 + enum TControl
1.286 + {
1.287 + EOpenBuffer,
1.288 + EResizeBuffer,
1.289 + ESetFilter,
1.290 + ESetFilter2,
1.291 + ESetFilter2Array,
1.292 + ESetFilter2Global,
1.293 + EGetFilter2Part1,
1.294 + EGetFilter2Part2,
1.295 + ERequestData,
1.296 + ECancelRequestData,
1.297 + ESetSerialPortOutput,
1.298 + ESetTimestamp2Enabled,
1.299 + };
1.300 +#ifndef __KERNEL_MODE__
1.301 + RChunk iDataChunk;
1.302 + TBTraceBuffer* iBuffer;
1.303 + TInt iLastGetDataSize;
1.304 + TUint32 iSpare[4];
1.305 +#endif
1.306 + friend class DBTraceChannel;
1.307 + friend class DBTraceFactory;
1.308 + friend class RBTraceAdapter;
1.309 + };
1.310 +
1.311 +#ifndef __KERNEL_MODE__
1.312 +
1.313 +inline RChunk RBTrace::DataChunk()
1.314 + {
1.315 + return iDataChunk;
1.316 + }
1.317 +
1.318 +inline TInt RBTrace::Filter(TUint aCategory)
1.319 + {
1.320 + return SetFilter(aCategory,-1);
1.321 + }
1.322 +
1.323 +#endif // !__KERNEL_MODE__
1.324 +
1.325 +inline const TDesC& RBTrace::Name()
1.326 + {
1.327 + _LIT(KBTraceName,"btrace");
1.328 + return KBTraceName;
1.329 + }
1.330 +
1.331 +
1.332 +/**
1.333 +@internalComponent
1.334 +*/
1.335 +class TBTraceBuffer
1.336 + {
1.337 +private:
1.338 + TUint iStart;
1.339 + TUint iEnd;
1.340 + volatile TUint iHead;
1.341 + volatile TUint iTail;
1.342 + volatile TUint iWrap;
1.343 + volatile TUint iGeneration;
1.344 + volatile TUint iMode;
1.345 + TUint iRecordOffsets;
1.346 + TUint iCopyBuffer;
1.347 + TUint iCopyBufferSize;
1.348 +private:
1.349 + TInt Data(TUint& aData, TUint& aTail);
1.350 + TInt Adjust(TUint aTail, TInt aSize);
1.351 + TInt CopyData(TUint aData, TUint aTail, TInt aSize);
1.352 + TUint UpdateTail(TUint32 aOld, TUint32 aNew);
1.353 + TInt GetData(TUint8*& aData);
1.354 +
1.355 + friend class RBTrace;
1.356 + friend class TBTraceBufferK;
1.357 + friend class RBTraceAdapter;
1.358 + };
1.359 +
1.360 +
1.361 +
1.362 +#endif