1 // Copyright (c) 2007-2010 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 "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 // Trace Core

    15 //

    16 

    17 #ifndef __TRACECOREWRITER_H__

    18 #define __TRACECOREWRITER_H__

    19 

    20 

    21 // Include files

    22 #include <kernel/kernel.h>

    23 

    24 

    25 /**

    26  * Types for WriteStart

    27  */

    28 enum TWriterEntryType

    29     {

    30 	

    31 	/**

    32 	 * Ascii printf trace

    33 	 */

    34     EWriterEntryAscii       = 1,

    35     

    36     /**

    37      * Binary trace

    38      */

    39     EWriterEntryTrace       = 2

    40     };

    41 

    42 /**

    43  * Writer types for constructor

    44  */

    45 enum TWriterType

    46     {

    47 	/**

    48 	 * No writer, can be used to remove writer

    49 	 */

    50     EWriterTypeNone    		= 0,

    51     

    52 	/**

    53 	 * XTI writer

    54 	 */

    55     EWriterTypeXTI          = 1,

    56     

    57     /**

    58      * USB phonet writer

    59      */

    60     EWriterTypeUSBPhonet    = 2,

    61   

    62     /**

    63      * Wins writer

    64      */

    65     EWriterTypeWins    = 3,

    66     

    67     /**

    68      * Custom writer 1

    69      */

    70     EWriterTypeCustom1 = 4,

    71     

    72     /**

    73      * Custom writer 2

    74      */

    75     EWriterTypeCustom2 = 5,

    76 

    77 	/**

    78      * test writer

    79      */

    80     EWriterTypeTest    = 6,

    81     

    82     /**

    83      * Ost Buffer writer

    84      */

    85     EWriterTypeOstBuffer = 7

    86     

    87     

    88     };

    89 

    90 /**

    91  * Write parameters for WriteEnd functions.

    92  * This structure can contain some output channel specific information.

    93  */

    94 class TWriteEndParams

    95 {

    96     public:

    97     TWriteEndParams(TUint32  aEntryId, TBool aWriteZero){ iEntryId = aEntryId; iWriteZero = aWriteZero; };

    98 	TUint32 iEntryId;

    99 	TBool iWriteZero;    

   100 };

   101 

   102 

   103 

   104 /**

   105  * Base class for trace core writers

   106  */

   107 class DTraceCoreWriter : public DBase

   108     {

   109 public:

   110 

   111     /**

   112      * Constructor

   113      *

   114      * @param aWriterType Type of writer 

   115      */

   116     IMPORT_C DTraceCoreWriter( TWriterType aWriterType );

   117 

   118     /**

   119      * Destructor

   120      */    

   121     IMPORT_C virtual ~DTraceCoreWriter();

   122 

   123     /**

   124      * Registers this writer to TraceCore. The first writer to register becomes the active writer.

   125      */

   126     IMPORT_C virtual TInt Register();

   127 

   128     /**

   129      * Outputs a TraceCore frame. This calls WriteStart, writes the component and trace ID's,

   130      * calls WriteBTraceFrame and calls WriteEnd

   131      *

   132      * @param aComponentId the component ID

   133      * @param aTraceWord The trace word containing the group ID and the Trace ID for the frame

   134      * @param aHeader BTrace header

   135      * @param aHeader2 Extra header data

   136      * @param aContext The thread context in which this function was called

   137      * @param a1 The first trace parameter

   138      * @param a2 The second trace parameter

   139      * @param a3 The third trace parameter

   140      * @param aExtra Extra trace data

   141      * @param aPc The program counter value

   142      * @param aRecordSize The record size

   143      */

   144     IMPORT_C virtual void WriteTraceCoreFrame( const TUint32 aComponentId, const TUint32 aTraceId, 

   145     		TUint32 aHeader, TUint32 aHeader2, const TUint32 aContext, const TUint32 a1, 

   146     		const TUint32 a2, const TUint32 a3, const TUint32 aExtra, const TUint32 aPc, TUint32 aRecordSize );

   147 

   148     /**

   149      * Ends an entry. 

   150 	 * This function should be overwritten in writers that derive from DTraceCoreWriter 

   151 	 * and require non standard implementation.

   152      *

   153      * @param aWriteEndParams structure containing 'end of message' information. @see TWriteEndParams

   154      */

   155     IMPORT_C virtual void WriteEnd( const TWriteEndParams& aWriteEndParams );

   156     

   157     

   158     //TODO: assert that BtraceLock is held in Write Start!!!!

   159     //TODO: Write WritePreStart() or something

   160     

   161     /**

   162      * Starts an entry

   163      *

   164      * @return the entry ID that is passed to other Write-functions

   165      */

   166     virtual TUint32 WriteStart( TWriterEntryType aType ) = 0;

   167 

   168     /**

   169      * Ends an entry

   170      *

   171      * @param aEntryId the entry ID returned by WriteStart

   172      */

   173     virtual void WriteEnd( TUint32 aEntryId ) = 0;

   174 

   175 

   176 

   177     /**

   178      * Writes 8-bit data to given entry

   179      * 

   180      * @param aEntryId the entry ID returned by WriteStart

   181      * @param aData the trace data

   182      */

   183 	virtual void WriteData( TUint32 aEntryId, TUint8 aData ) = 0;

   184 

   185     /**

   186      * Writes 16-bit data to given entry

   187      * 

   188      * @param aEntryId the entry ID returned by WriteStart

   189      * @param aData the trace data

   190      */

   191     virtual void WriteData( TUint32 aEntryId, TUint16 aData ) = 0;

   192 

   193     /**

   194      * Writes 32-bit data to given entry

   195      * 

   196      * @param aEntryId the entry ID returned by WriteStart

   197      * @param aData the trace data

   198      */

   199 	virtual void WriteData( TUint32 aEntryId, TUint32 aData ) = 0;

   200 	

   201 	/**

   202 	 * Gets the type of this writer

   203 	 */

   204 	TWriterType GetWriterType();

   205 	

   206 

   207 	/**

   208 	 * Signal to TraceCore if there has been a dropped trace

   209 	 * 

   210      * @param aDropped ETrue if the writer dropped the trace - otherwise EFalse

   211      * 

   212 	 */

   213     IMPORT_C void TraceDropped(TBool aDropped);

   214 

   215 

   216 

   217 

   218     /**

   219       * Interrogates tracecore if the last trace was dropped

   220       * 

   221       * @return  returns ETrue if the trace was dropped otherwise EFalse

   222       * 

   223     */

   224 

   225     IMPORT_C TBool WasLastTraceDropped() const ;

   226 

   227     

   228     /**

   229      * Checks whether writer can handle incoming trace data with specific size.

   230      * This method is useful in case where Trace Core must report dropped traces.

   231      * Currently it is used only in printf-handler and only in case where 

   232      * the "dropped trace" flag is set.

   233      * Typical implementation of this method should check writer internal state and answer

   234      * whether trace with specific size and type can be sent.

   235      * Default implementation of this method assumes writer is able to handle incoming 

   236      * trace (ETrue is returned).

   237      * 

   238      * @param aTraceSize Size of incomming trace.

   239      * @return ETrue if writer state is correct and it is able to send incomming data; EFalse otherwise.

   240      */

   241     IMPORT_C virtual TBool AbleToWrite(TUint aTraceSize); 

   242 

   243 private:

   244     

   245     /**

   246      * Outputs a BTrace frame

   247      *

   248      * @param aEntryId the entry ID returned by WriteStart

   249      * @param aHeader BTrace header

   250      * @param aHeader2 Extra header data

   251      * @param aContext The thread context in which this function was called

   252      * @param a1 The first trace parameter

   253      * @param a2 The second trace parameter

   254      * @param a3 The third trace parameter

   255      * @param aExtra Extra trace data

   256      * @param aPc The program counter value

   257      * @param aRecordSize The record size

   258      */

   259     void WriteBTraceFrame( const TUint32 aEntryId, TUint32 aHeader, TUint32 aHeader2, 

   260     		const TUint32 aContext, const TUint32 a1, const TUint32 a2, const TUint32 a3, 

   261     		const TUint32 aExtra, const TUint32 aPc, TUint32 aRecordSize );

   262 

   263     /**

   264      * Unregisters this writer from TraceCore. Called from destructor

   265      */

   266     void Unregister();

   267 

   268     /**

   269      * Writes the remaining bytes if data is not 32-bit aligned

   270      */

   271     void WriteRemainingBytes( TUint32 aEntryId, TUint32 aSize, TUint32 a3 );

   272 

   273     /**

   274      * Writer type

   275      */

   276     TWriterType iWriterType;

   277     };

   278 

   279 #endif

   280 

   281 // End of File