--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/kernel/eka/include/d32btrace.h Mon Oct 19 15:55:17 2009 +0100
@@ -0,0 +1,359 @@
+// Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of the License "Eclipse Public License v1.0"
+// which accompanies this distribution, and is available
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+//
+// WARNING: This file contains some APIs which are internal and are subject
+// to change without notice. Such APIs should therefore not be used
+// outside the Kernel and Hardware Services package.
+//
+
+#ifndef D32BTRACE_H
+#define D32BTRACE_H
+
+#include <e32cmn.h>
+#include <e32ver.h>
+#include <e32btrace.h>
+
+#ifndef __KERNEL_MODE__
+#include <e32std.h>
+#endif
+
+
+class TBTraceBuffer;
+
+/**
+Interface to the fast-trace memory buffer.
+
+@publishedPartner
+@released
+*/
+class RBTrace : public RBusLogicalChannel
+ {
+public:
+ /**
+ Bit flags indicating the operational mode of the fast-trace buffer.
+ */
+ enum TMode
+ {
+ /**
+ Flag set to enable trace to be stored in the buffer.
+ If this is not set, all trace records are discarded.
+ */
+ EEnable = 1<<0,
+
+ /**
+ This flag dictates the behaviour which occurs when the trace buffer is too full to
+ accomodate a new record.
+ When this flag is set, new trace records will overwrite the oldest ones.
+ When this flag is not set, new trace records are discard.
+ (This latter mode provides the best performance.)
+ */
+ EFreeRunning = 1<<1,
+ };
+
+#ifndef __KERNEL_MODE__
+ /**
+ Open channel to fast-trace driver.
+ Must be called before any other methods are used.
+ @return KErrNone or standard error code.
+ */
+ IMPORT_C TInt Open();
+
+ /**
+ Close channel to fast-trace driver.
+ */
+ IMPORT_C void Close();
+
+ /**
+ Get the current size of trace buffer.
+ @return Buffer size.
+ */
+ IMPORT_C TInt BufferSize();
+
+ /**
+ Change size of trace buffer.
+ This causes all current data in the trace buffer to be lost.
+ If this method fails then the trace buffer may no longer exist.
+ @param aSize The size in bytes for the trace buffer.
+ @return KErrNone or standard error code.
+ */
+ IMPORT_C TInt ResizeBuffer(TInt aSize);
+
+ /**
+ Discard all trace data.
+ */
+ IMPORT_C void Empty();
+
+ /**
+ The chunk in which trace data returned by GetData() resides.
+ @return The chunk.
+ */
+ inline RChunk DataChunk();
+
+ /**
+ The operational mode for fast-trace.
+ @return The current operational mode. This is bitmask of values from TMode.
+ */
+ IMPORT_C TUint Mode();
+
+ /**
+ Set the operational mode for fast-trace.
+ Calling this method, invalidates the trace data returned by the last call to GetData().
+ @param aMode A bitmask of values from TMode.
+ */
+ IMPORT_C void SetMode(TUint aMode);
+
+ /**
+ Set the trace filter bit for the specified category.
+ @param aCategory A category value from BTrace::TCategories.
+ @param aValue The new filter value for the category.
+ 1 means traces of this category are output, 0 means they are suppressed.
+ Any other value will be ignored, and this method will just return the current
+ value of the filter.
+ @return The previous value of the filter for the category, 0 or 1.
+ Or KErrNotSupported if this category is not supported by this build of the kernel.
+ */
+ IMPORT_C TInt SetFilter(TUint aCategory, TInt aValue);
+
+ /**
+ Get the trace filter bit for the specified category.
+ @param aCategory A category value from enum BTrace::TCategory,
+ @return The value of the filter for the category, 0 or 1,
+ or KErrNotSupported if this category is not supported by this build of the kernel.
+ (1 means traces of this category are output, 0 means they are suppressed.)
+ */
+ inline TInt Filter(TUint aCategory);
+
+ /**
+ Set the trace secondary trace filter for the specified UID.
+
+ This method can not be used to disable a UID key if SetFilter2(TInt aGlobalFilter)
+ has been used to set the filter to pass all traces. Such attempts result in a return
+ code of KErrNotSupported.
+
+ @param aUid The UID to filter.
+ @param aValue The new filter value for the UID.
+ 1 means traces with this UID are output, 0 means they are suppressed.
+ Other values must not be used.
+
+ @return The previous value of the filter for the UID, 0 or 1, if operation is successful.
+ Otherwise, a negative number representing a system wide error code.
+ (E.g. KErrNoMemory.)
+ */
+ IMPORT_C TInt SetFilter2(TUint32 aUid, TBool aValue);
+
+ /**
+ Set the secondary trace filter to include only the specified UIDs.
+
+ @param aUids Pointer to array of UIDs.
+ @param aNumUids Number of UID values pointer to by \a aUid.
+
+ @return KErrNone on success.
+ Otherwise, a negative number representing a system wide error code.
+ (E.g. KErrNoMemory.)
+ */
+ IMPORT_C TInt SetFilter2(const TUint32* aUids, TInt aNumUids);
+
+ /**
+ Set the secondary trace filter to pass or reject every trace.
+
+ @param aGlobalFilter If 0, the secondary filter will reject
+ all traces; if 1, all traces are passed
+ by the filter.
+ Other values have no effect.
+
+ @return The previous value of the global filter.
+ */
+ IMPORT_C TInt SetFilter2(TInt aGlobalFilter);
+
+ /**
+ Get the contents of the secondary trace filter.
+
+ @param [out] aUids Pointer to array of UIDs contained in the secondary filter.
+ Ownership of this array is passed to the caller of this
+ function, which is then responsible for deleting it.
+ If filter is empty, \a aUid equals zero.
+ @param [out] aGlobalFilter Set to 1 if the secondary filter passes all traces.
+ Set to 0 if the secondary filter rejects all traces.
+ Set to -1 if the secondary filter operates by UIDs contained in traces.
+
+ @return Number of UIDs in returned array, if operation is successful.
+ Otherwise, a negative number representing a system wide error code.
+ */
+ IMPORT_C TInt Filter2(TUint32*& aUids, TInt& aGlobalFilter);
+
+ /**
+ Get pointer to as much contiguous trace data as is available.
+ This data resides in the shared chunk DataChunk().
+ The data returned will always be a whole number of trace records, i.e. trace records
+ will not be split between successive calls to this method.
+ Once the data is no loger required, DataUsed() must be called.
+ This method can be called repeatedly to get more trace data. E.g.
+ @code
+ RBTrace trace;
+ TInt error = trace.Open();
+ if(error!=KErrNone)
+ return error;
+ const TInt KTraceDataBlockSize = 65536; // size of data we ideally want to process in one go
+ TUint8* data;
+ TInt size;
+ do
+ {
+ while((size=trace.GetData(data))!=0)
+ {
+ ProcessTheTraceData(data,size);
+ trace.DataUsed();
+ }
+ TRequestStatus waitStatus;
+ trace.RequestData(waitStatus,KTraceDataBlockSize);
+ User::WaitForRequest(waitStatus);
+ error = waitStatus.Int();
+ }
+ while(error==KErrNone);
+ trace.Close();
+ return error;
+ @endcode
+
+ @param aData Pointer to the first byte of trace data.
+ @return The number of bytes of trace data available at aData.
+ @see DataChunk();
+ */
+ IMPORT_C TInt GetData(TUint8*& aData);
+
+ /**
+ Remove from the trace buffer all of the data returned by the last call to GetData().
+ */
+ IMPORT_C void DataUsed();
+
+ /**
+ Request notification when trace data becomes available.
+ Only one outstanding request may be present at any one time.
+ @param aStatus Request status to be complete with KErrNone once data becomes available.
+ @param aSize The minimum number of bytes of trace data required.
+ This is intended to improve performance by only signalling the client once
+ a suitably large amount of trace data is available. However, this request
+ may complete before this amount of trace data is available, therefore a
+ client must be able to handle this situation.
+ If aSize is zero or negative, then the request completes as soon as any trace
+ data is available.
+ @panic BTRACE 0 if a previous request is still pending
+ */
+ IMPORT_C void RequestData(TRequestStatus& aStatus, TInt aSize);
+
+ /**
+ Cancel any previous RequestData(), completing it with KErrCancel.
+ */
+ IMPORT_C void CancelRequestData();
+
+ /**
+ @internalTechnology
+ */
+ TBool SetSerialPortOutput(TBool aEnable);
+
+ /**
+ Controls whether Timestamp2 field is added to trace record headers.
+ */
+ IMPORT_C TBool SetTimestamp2Enabled(TBool aEnable);
+
+#endif
+
+ /**
+ Enumeration of panic reasons for category 'BTRACE'.
+ */
+ enum TPanic
+ {
+ ERequestAlreadyPending, /**< A call to RequestData() was made whist a request was already pending. */
+ };
+private:
+ TInt OpenChunk();
+ void CloseChunk();
+ inline static const TDesC& Name();
+
+ enum TControl
+ {
+ EOpenBuffer,
+ EResizeBuffer,
+ ESetFilter,
+ ESetFilter2,
+ ESetFilter2Array,
+ ESetFilter2Global,
+ EGetFilter2Part1,
+ EGetFilter2Part2,
+ ERequestData,
+ ECancelRequestData,
+ ESetSerialPortOutput,
+ ESetTimestamp2Enabled,
+ };
+#ifndef __KERNEL_MODE__
+ RChunk iDataChunk;
+ TBTraceBuffer* iBuffer;
+ TInt iLastGetDataSize;
+ TUint32 iSpare[4];
+#endif
+ friend class DBTraceChannel;
+ friend class DBTraceFactory;
+ friend class RBTraceAdapter;
+ };
+
+#ifndef __KERNEL_MODE__
+
+inline RChunk RBTrace::DataChunk()
+ {
+ return iDataChunk;
+ }
+
+inline TInt RBTrace::Filter(TUint aCategory)
+ {
+ return SetFilter(aCategory,-1);
+ }
+
+#endif // !__KERNEL_MODE__
+
+inline const TDesC& RBTrace::Name()
+ {
+ _LIT(KBTraceName,"btrace");
+ return KBTraceName;
+ }
+
+
+/**
+@internalComponent
+*/
+class TBTraceBuffer
+ {
+private:
+ TUint iStart;
+ TUint iEnd;
+ volatile TUint iHead;
+ volatile TUint iTail;
+ volatile TUint iWrap;
+ volatile TUint iGeneration;
+ volatile TUint iMode;
+ TUint iRecordOffsets;
+ TUint iCopyBuffer;
+ TUint iCopyBufferSize;
+private:
+ TInt Data(TUint& aData, TUint& aTail);
+ TInt Adjust(TUint aTail, TInt aSize);
+ TInt CopyData(TUint aData, TUint aTail, TInt aSize);
+ TUint UpdateTail(TUint32 aOld, TUint32 aNew);
+ TInt GetData(TUint8*& aData);
+
+ friend class RBTrace;
+ friend class TBTraceBufferK;
+ friend class RBTraceAdapter;
+ };
+
+
+
+#endif