--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/kernel/eka/include/e32utrace_basic_types.h Mon Oct 19 15:55:17 2009 +0100
@@ -0,0 +1,543 @@
+/**
+* Copyright (c) 2007-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:
+* Trace API
+*
+* 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.
+*/
+
+
+
+/**
+ @file
+ @publishedPartner
+ @prototype
+*/
+
+
+#ifndef E32UTRACE_BASIC_TYPES_H
+#define E32UTRACE_BASIC_TYPES_H
+
+#ifdef __KERNEL_MODE__
+#include <kernel/kernel.h>
+#else //__KERNEL_MODE__
+#include <e32std.h>
+#endif //__KERNEL_MODE__
+
+
+/**
+@file
+@publishedPartner
+@prototype
+*/
+
+namespace UTF
+{
+
+/**
+ * Every trace point must be statically assigned a classification. This is
+ * essentially a “label” that allows identification of the intended use of
+ * the trace packets generated by the trace point. The classification either
+ * reflects a system-wide Tracing use-case, such as highlighting reasons why
+ * a Panic occurred, or is assigned to trace points in performance critical
+ * software such as the kernel or other key services.
+ * @see TClassificationRange for more information.
+ */
+typedef TUint8 TClassification;
+
+/**
+ * The maximum possible value for TClassification
+ */
+const static TClassification KMaxClassification = 255; // 2^8 - 1
+
+/**
+ * Each trace point must be statically assigned a ModuleUid to indicate the
+ * module in which the trace point is defined. It is recommended that this
+ * value is the UID3 of the associated binary file.
+ *
+ * The ModuleUid and Classification attributes of a trace point are independent.
+ */
+typedef TUint32 TModuleUid;
+
+/**
+ * The maximum possible value for TModuleUid
+ */
+const static TModuleUid KMaxModuleUid = 0xFFFFFFFF; // 2^32 - 1, or 4294967295 - 1
+
+/**
+ * The EXECUTABLE_DEFAULT_MODULEUID can be used to define your own default
+ * specific ModuleUid. This is done by defining the macro to be your new
+ * default value.
+ */
+#ifdef EXECUTABLE_DEFAULT_MODULEUID
+#define FW_DEFAULT_MODULEUID EXECUTABLE_DEFAULT_MODULEUID
+#else
+#define FW_DEFAULT_MODULEUID TTraceContext::DefaultModuleUid()
+#endif
+
+/**
+ * This is a numerical value statically assigned to a trace point which will be used
+ * on the host to look-up the format of the associated trace packets.
+ *
+ * The meaning of a FormatId is specific to the ModuleUid and Category of the
+ * associated trace point.
+ */
+typedef TUint16 TFormatId;
+
+/**
+ * The maximum possible value for TFormatId
+ */
+const static TFormatId KMaxFormatId = 65535; // 2^16 - 1
+
+/**
+ * TFormatId used in packets produced by the Print and Printf
+ * functions.
+ *
+ * Note that this format should not be used on the
+ * device by clients of UTrace. This symbol is only marked
+ * as published to partners to give host side tools access to
+ * it.
+ *
+ * @see TFormatId
+ */
+const static TFormatId KFormatPrintf = 0;
+
+/**
+ * TFormatId used in packets produced by the Print and Printf
+ * functions for unicode descriptors.
+ *
+ * Note that this format should not be used on the
+ * device by clients of UTrace. This symbol is only marked
+ * as published to partners to give host side tools access to
+ * it.
+ *
+ * @see TFormatId
+ */
+const static TFormatId KFormatPrintfUnicode = 1;
+
+/**
+ * This value is intended to be used by clients to specify the
+ * start of the range of enums used to define their format ids.
+ *
+ * Any values between 0 up to this should not be used directly
+ * by clients of UTrace on the device.
+ *
+ * @see TFormatId
+ */
+const static TFormatId KInitialClientFormat = 512;
+
+/**
+ * Include the thread identification into the trace packet at run-time.
+ * The thread identification is used as an identifier to resolve
+ * thread and process names in conjunction with
+ * classificiation EThreadIdentification = 3.
+ */
+enum THasThreadIdentification
+ {
+ /**Do add the thread identification to the trace packet*/
+ EAddThreadIdentification = ETrue,
+ /**Don't add the thread identification*/
+ ENoThreadIdentification = EFalse
+ };
+
+
+/**
+ * The EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION can be used to
+ * define the default setting for adding or not adding the thread
+ * identification in a trace packet. This is done by defining
+ * the macro to be your new default value.
+ */
+#ifdef EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION
+#define FW_DEFAULT_HAS_THREAD_IDENTIFICATION EXECUTABLE_DEFAULT_HAS_THREAD_IDENTIFICATION
+#else
+#define FW_DEFAULT_HAS_THREAD_IDENTIFICATION EAddThreadIdentification
+#endif
+
+
+/**
+ * Add the program counter into the trace packet at run-time.
+ * The program counter is used to indicate where the CPU is in the
+ * instruction sequence. This can be used to locate the line of code
+ * or routine the trace was sent from.
+ */
+enum THasProgramCounter
+ {
+ /**Do add the program counter to the trace packet.*/
+ EAddProgramCounter = ETrue,
+ /**Don't add the program counter*/
+ ENoProgramCounter = EFalse
+ };
+
+
+/**
+ * The EXECUTABLE_DEFAULT_HAS_PC can be used to
+ * define the default setting for adding or not adding the
+ * program counter in a trace packet. This is done by defining
+ * the macro to be your new default value.
+ */
+#ifdef EXECUTABLE_DEFAULT_HAS_PC
+#define FW_DEFAULT_HAS_PC EXECUTABLE_DEFAULT_HAS_PC
+#else
+#define FW_DEFAULT_HAS_PC ENoProgramCounter
+#endif
+
+
+/**
+ * The Classifications in the All range should be used by the majority of
+ * trace points. This range of Classifications are intended to identify which
+ * of the most common trace use-cases a trace point is contributing to.
+ * The Classifications in this series are defined solely by Symbian but are
+ * intended for use by any software on a device.
+ *
+ * @see TClassification
+ * @see TClassificationRange
+ * @see EAllRangeFirst
+ */
+enum TClassificationAll
+ {
+ /**
+ * Used when a panic has occurred or when providing information on the execution
+ * state that lead to the decision to panic.
+ *
+ * A trace point with this Classification indicates a fatal condition is about to
+ * occur which will halt the flow of program execution in the current thread.
+ *
+ * This Classification also provides information describing where a panic has been
+ * dealt with.
+ *
+ * EPanic = EAllRangeFirst
+ */
+ EPanic = 192,
+
+ /**
+ * Used when an error has occurred that means the current operation cannot continue
+ * but isn’t sufficiently serious to cause a Panic. The trace points could contain
+ * not just the error code but any relevant information about the execution state
+ * when the error occurred.
+ *
+ * To be used for all types of error and includes situations where the errors are
+ * returned from a function or in a Leave.
+ *
+ * This Classification also provides information describing where an error has been
+ * dealt with.
+ */
+ EError = 193,
+
+ /**
+ * Used when something unexpected or unusual has occurred that does not stop the
+ * current operation from happening but may result in unintended side effects or
+ * actual errors later on.
+ */
+ EWarning = 194,
+
+ /**
+ * Used to detail normal activity at the edges of a module. Does not include errors
+ * or warnings as these are covered in other Classifications.
+ *
+ * Includes data about exported or published functions defined by module as well as
+ * calls out of the module to get significant information. Exactly what is significant
+ * is for the module owner to decide. For example, getting the contents of an .ini file to
+ * determine which configuration to use might be significant but calling RArray::Count()
+ * would not be.
+ *
+ * The information in this Classification should be enough to allow someone unfamiliar
+ * with the trace module to get a high level understanding of what functionality it has
+ * executed.
+ */
+ EBorder = 195,
+
+ /**
+ * Intended for tracing the state transitions of an application or service such as those
+ * performed by a machine.
+ *
+ * Trace packet’s using this Classification should contain the name of the
+ * changed state variable and the new value.
+ */
+ EState = 196,
+
+ /**
+ * Used to provide detailed information about the normal activity of a module
+ * to help a developer, who is familiar with the module, to understand what it is doing.
+ *
+ * Does not include errors or warnings as those are covered in other Classifications.
+ */
+ EInternals = 197,
+
+ /**
+ * Used when there is a need to output large amounts of data through individual trace
+ * points that would likely cause significant intrusion if included under one of the
+ * other Classifications.
+ *
+ * This Classification in intended to be used in conjunction with the Internals
+ * Classification to provide more details when debugging a specific module.
+ */
+ EDump = 198,
+
+ /**
+ * Used to provide comprehensive information on what paths the execution takes within
+ * functions.
+ *
+ * This Classification is intended only to be assigned by tools that add temporary
+ * instrumentation points specifically to output this data.
+ */
+ EFlow = 199,
+
+ /**
+ * Used to output data about the execution time, memory usage, disk usage, power
+ * utilisation and other system characteristics of the trace module.
+ *
+ * This data may need to be processed before it can provide affective metrics. E.g.
+ * the time between two timestamps might need to be computed.
+ *
+ * Intended only to be used to output system characteristic data that requires the
+ * smallest possible intrusion.
+ */
+ ESystemCharacteristicMetrics = 200,
+
+ /**
+ * Can be used when adding ad-hoc / temporary trace points if there’s a need to
+ * distinguish it from existing trace.
+ */
+ EAdhoc = 201,
+
+ /**
+ * Provided to allow the following compile time assert:
+ * EClassificationAllHighWaterMark <= EAllRangeLast + 1
+ *
+ * @internalComponent
+ */
+ EClassificationAllHighWaterMark,
+ };
+
+
+/**
+ * The division of the Classifications into different ranges aims to manage the
+ * contention for the namespace.
+ * The stakeholders considered for the namespace are:
+ * - Software vendors who own trace points in a base-port, whether a hardware
+ * manufacturer or their suppliers.
+ * - Software vendors who own trace points in the UI layer, whether a phone
+ * manufacturer or their suppliers.
+ * - ISVs who own trace points in source code installed on a device after it has been
+ * released.
+ * - Symbian as the owner of all trace points in Symbian OS.
+ *
+ * It is recommended that all stakeholders use the All range as far as possible.
+ * It is also strongly recommended that software provided by one stakeholder does
+ * not use any Classifications from a range provided specifically for another
+ * stakeholder.
+ *
+ * @see TClassification
+ */
+enum TClassificationRange
+ {
+ /**
+ * The Symbian One range is only for use on the device by Symbian.
+ *
+ * @see epoc32\include\e32btrace.h
+ *
+ * This range is defined and used by Symbian only.
+ */
+ ESymbianOneRangeFirst = 0,
+
+ /**
+ * @see ESymbianOneRangeFirst
+ */
+ ESymbianOneRangeLast = 127,
+
+ /**
+ * The Base Port range is only for use on the device by code provided solely as
+ * part of a base-port.
+ *
+ * It is expected that the owner of each base-port will manage the use of trace
+ * points by all the software vendors contributing to their base-port to prevent
+ * conflicts.
+ *
+ * This range may only be defined and used by device manufacturers.
+ */
+ EBasePortRangeFirst = 128,
+
+ /**
+ * @see EBasePortRangeFirst
+ */
+ EBasePortRangeLast = 159,
+
+ /**
+ * The UI Layer range is only for use on the device by code provided as part of
+ * the UI Layer. This includes all software needed to create a device
+ * that is not part of Symbian OS or the base-port.
+ *
+ * It is expected that the owner of each UI layer will prevent collisions between
+ * trace points provided by all the software vendors contributing software to the
+ * UI layer.
+ *
+ * This range may only be defined and used by device manufacturers.
+ */
+ EUiLayerRangeFirst = 160,
+
+ /**
+ * @see EUiLayerRangeFirst
+ */
+ EUiLayerRangeLast = 191,
+
+ /**
+ * The Classifications in the All range should be used by the majority of trace
+ * points. This range of Classifications are intended to identify which of the
+ * most common trace use-cases a trace point is contributing to.
+ *
+ * The Classifications in this series are defined solely by Symbian but are
+ * intended for use by any software on a device. No software vendor other than
+ * Symbian should define Classifications in this range.
+ *
+ * When assigning one of these Classifications to a trace point you should
+ * also assign a ModuleUid to allow your trace points to be differentiated from
+ * other uses of the Classification in the system.
+ *
+ * These Classifications should only be enabled at run-time if the filtering on
+ * ModuleUids functionality is also enabled. This is to avoid accidentally causing
+ * trace live-locks from occurring when the Classification is enabled. This could
+ * happen because trace points in components involved in the current trace output
+ * path might also be assigned these Classifications. Filtering on ModuleUids means
+ * that those trace points can be activated only when it’s known to be safe to do
+ * so and not accidentally enabled with a Classification.
+ *
+ * This range is definded by Symbian and may be used by anyone.
+ *
+ * @see TAllClassification
+ */
+ EAllRangeFirst = 192,
+
+ /**
+ * @see EAllRangeFirst
+ */
+ EAllRangeLast = 221,
+
+ /**
+ * This range may only be used and defined by Symbian.
+ */
+ ESymbianTwoRangeFirst = 222,
+
+ /**
+ * @see ESymbianTwoRangeFirst
+ */
+ ESymbianTwoRangeLast = 245,
+
+ /**
+ * The ISV range is only for use on the device by ISVs providing software that is
+ * installed on a device after it has been released and is not part of the base-port,
+ * Symbian OS or the UI Layer.
+ *
+ * This range is only intended to provide enough Classifications for a single ISV
+ * application. Clashes that occur between different applications should be
+ * resolved by uninstalling one or other of them.
+ *
+ * This range is defined and used by 3rd party developers.
+ */
+ EIsvRangeFirst = 246,
+
+ /**
+ * @see EIsvRangeFirst
+ */
+ EIsvRangeLast = 253,
+
+ /**
+ * Only for use on the device by test code.
+ *
+ * Trace points with these Classifications should not be released as part of a
+ * production device.
+ */
+ ETestingRangeFirst = 254,
+
+ /**
+ * @see ETestingRangeFirst
+ */
+ ETestingRangeLast = KMaxClassification,
+ };
+
+// Check high water mark for classification ranges for TClassificationAll
+__ASSERT_COMPILE(EClassificationAllHighWaterMark <= EAllRangeLast + 1);
+
+
+
+/**
+ * @see TClassification
+ * @see ESymbianTwoRangeFirst
+ * @internalComponent
+ */
+enum TClassificationSymbianTwo
+ {
+ /**
+ * This classification is reserved for future use to allow the classification range
+ * to be expanded to cover more than current 256 different values.
+ *
+ * If trace is output on this Classification at some point in the future then this
+ * indicates another mechanism (to be decided) will be used to indicate the actual
+ * Classification for the trace.
+ *
+ * EClassificationExtension = 222
+ */
+ EClassificationExtension = ESymbianTwoRangeFirst,
+
+ /**
+ * Provided to allow the following compile time assert:
+ * EClassificationSymbianTwoHighWaterMark <= ESymbianTwoRangeLast + 1
+ *
+ * @internalComponent
+ */
+ EClassificationSymbianTwoHighWaterMark,
+ };
+// Check high water marks for classification ranges
+__ASSERT_COMPILE(EClassificationSymbianTwoHighWaterMark <= ESymbianTwoRangeLast + 1);
+
+/**
+ * @see TClassification
+ * @see ETestingRangeFirst
+ * @test
+ */
+enum TClassificationTesting
+ {
+ /**
+ * Only for use on the device by test code.
+ *
+ * Trace points with this Classification should not be released as part of a
+ * production device.
+ *
+ * ETesting1 = 254
+ */
+ ETesting1 = ETestingRangeFirst,
+
+ /**
+ * @see ETesting1
+ */
+ ETesting2 = 255,
+
+ /**
+ * Provided to allow the following compile time assert:
+ * EClassificationTestingHighWaterMark <= ETestingRangeLast + 1
+ *
+ * @internalComponent
+ */
+ EClassificationTestingHighWaterMark,
+ };
+
+// Check high water marks for classification ranges
+__ASSERT_COMPILE(EClassificationTestingHighWaterMark <= ETestingRangeLast + 1);
+
+
+} //end of UTF namespace
+
+#endif //E32UTRACE_BASIC_TYPES_H
+