diff -r 000000000000 -r a41df078684a kernel/eka/include/e32utrace_basic_types.h --- /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 +#else //__KERNEL_MODE__ +#include +#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 +