// Copyright (c) 2006-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:

// Definitions for the run mode debug agent client side sessions.

// 

// 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 RM_DEBUG_API_H

#define RM_DEBUG_API_H

/**

@file

@publishedPartner

@released

*/

#include <e32cmn.h>

#include <e32def_private.h>

/**

  The Debug namespace contains all API definitions used for on-target debugging.

  */

namespace Debug {

/** This is the maximum size in bytes a user trace can be */

const TInt TUserTraceSize = 256;

/**

  Information in the debug functionality block is represented as a concatenation

  of pairs of TTagHeader structures and arrays of TTag objects.

  @see TTagHeader

  @see RSecuritySvrSession::GetDebugFunctionality

  */

struct TTag

{

	/** Tag ID, value identifying this tag. */

	TUint32	iTagId;

	/**

	  Values correspond to TTagType enumerators.

	  @see TTagType

	  */

	TUint16	iType;

	/** Size of external data associated with this tag. */

	TUint16 iSize;

	/** Data associated with this tag. */

	TUint32 iValue;

};

/**

  Enumeration defining the supported tag types. These enumerators are used in TTag.iTagId.

  @see TTag

  */

enum TTagType

{

	/** Indicates that the iValue field of a TTag structure will contain either ETrue or EFalse. */

	ETagTypeBoolean = 0,

	/** Indicates that the iValue field of a TTag structure will contain a value in the TUint32 range. */

	ETagTypeTUint32 = 1,

	/** Indicates that the iValue field of a TTag structure will contain values from an enumeration. */

	ETagTypeEnum = 2,

	/** Indicates that the iValue field of a TTag structure should be interpreted as a bit field. */

	ETagTypeBitField = 3,

	/** Indicates that the type of the iValue field of a TTag structure is unknown. */

	ETagTypeUnknown = 4,

	/** Indicates that the iValue field of a TTag structure will contain a pointer. */

	ETagTypePointer = 5

};

/**

  Information in the debug functionality block is represented as a concatenation

  of pairs of TTagHeader structures and arrays of TTag objects.

  @see TTag

  @see RSecuritySvrSession::GetDebugFunctionality

  */

struct TTagHeader

{

	/** Value identifying the contents of this TTagHeader, should be interpreted as an enumerator from TTagHeaderId.

	  @see TTagHeaderId

	  */

	TUint16	iTagHdrId;

	/** The number of TTag elements in the array associated with this TTagHeader. */

	TUint16 iNumTags;

};

/**

  Enumeration used to identify TTagHeader structures, TTagHeader::iTagHdrId elements take these enumerators as values.

  @see TTagHeader

  */

enum TTagHeaderId

{

	ETagHeaderIdCore = 0,            /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityCore. */

	ETagHeaderIdMemory = 1,          /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityMemory. */

	/**

	  Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityRegister.

	  These values are defined as in the document Symbian Core Dump File Format Appendix C

	  (see SGL.TS0028.027 - Symbian Core Dump File Format v1.0.doc).

	  The TTag objects in the associated array have an iSize value corresponding to the size of the register's data in bytes.

	  */

	ETagHeaderIdRegistersCore = 2,

	/**

	  Identifies a TTagHeader with associated TTag elements with iTagId values corresponding to coprocessor register identifiers.

	  Coprocessor registers are defined as in the document Symbian Core Dump File Format Appendix C as follows

	  (see SGL.TS0028.027 - Symbian Core Dump File Format v1.0.doc):

	  For each 32-bit data word defining a co-pro register, the definition of the meaning of the bits follows

	  the ARM Architecture Reference manual instruction coding

	  Upper Halfword	Lower Halfword

	  Opcode 2			CRm

	  For example: The Domain Access Control Register is Register 3 of co-processor 15. The encoding is therefore

	  CRm = 3

	  Opcode2 = 0

	  Therefore the functionality tag would be:

	  TagID:  15			// co-processor number

	  Type: ETagTypeTUint32

	  Data: 0x00000003		// Opcode2 = 0, CRm = 3

	  */

	ETagHeaderIdCoProRegisters = 3,  /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityRegister. */

	ETagHeaderIdBreakpoints = 4,     /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityBreakpoint. */

	ETagHeaderIdStepping = 5,        /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityStep. */

	ETagHeaderIdExecution = 6,       /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityExec. */

	ETagHeaderIdEvents = 7,          /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TEventType. */

	ETagHeaderIdApiConstants = 8,    /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityApiConstants.*/

	ETagHeaderList = 9,              /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TListId. */

	ETagHeaderIdKillObjects = 10,    /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityKillObject. */

	ETagHeaderIdSecurity = 11,		 /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalitySecurity */

	ETagHeaderIdBuffers = 12,        /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TBufferType. */

	ETagHeaderIdStopModeFunctions = 13, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityStopModeFunctions. */	

};

/**

  This structure is not used in the run-mode debug API.

  @deprecated

  */

struct TSubBlock

{

	/** Header to identify the TSubBlock. */

	TTagHeader iHeader;

	/** Pointer to array of TTag values associated with this TSubBlock. */

	TTag* iTagArray;

};

/**

  These tags define what kinds of core functionality are supported by the run-mode debug subsystem.

  TTag structures associated with the ETagHeaderIdCore sub-block will have iTagId values from this enumeration.

  See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.

  */

enum TFunctionalityCore

{

	ECoreEvents = 0,        /**< Indicates whether events processing is supported. */

	ECoreStartStop = 1,     /**< Indicates whether suspending and resuming threads is supported. */

	ECoreMemory = 2,        /**< Indicates whether reading and writing memory is supported. */

	ECoreRegister = 3,      /**< Indicates whether reading and writing register values is supported. */

	ECoreBreakpoint = 4,    /**< Indicates whether breakpoints are supported. */

	ECoreStepping = 5,      /**< Indicates whether stepping is supported. */

	ECoreLists = 6,         /**< Indicates whether listings are supported. */

	ECoreLogging = 7,       /**< Indicates whether logging is supported. */

	ECoreHardware = 8,      /**< Indicates whether hardware support is supported. */

	ECoreApiConstants = 9,  /**< Indicates whether the information in the ETagHeaderIdApiConstants sub-block is relevant. */

	ECoreKillObjects = 10,  /**< Indicates whether killing objects (i.e. threads and processes) is supported. */

	ECoreSecurity = 11,		/**< Indicates whether OEM Debug token support or other security info is supported. */

	ECoreStopModeFunctions = 12, /**< Indicates whether Stop Mode function calling is supported. */

	ECoreStopModeBuffers = 13, /**< Indicates whether Stop Mode buffers are supported. */

	/**

	  @internalTechnology

	  A debug agent should find the number of core tags from the DFBlock rather than this enumerator.

	  */

	ECoreLast

};

/**

  These tags define what kind of memory operations can be performed.

  TTag structures associated with the ETagHeaderIdMemory sub-block will have iTagId values from this enumeration.

  See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.

 */

enum TFunctionalityMemory

{

	EMemoryRead = 0,          /**< Indicates whether reading memory is supported. */

	EMemoryWrite = 1,         /**< Indicates whether writing memory is supported. */

	EMemoryAccess64 = 2,      /**< Indicates whether 64 bit memory access is supported. */

	EMemoryAccess32 = 3,      /**< Indicates whether 32 bit memory access is supported. */

	EMemoryAccess16 = 4,      /**< Indicates whether 16 bit memory access is supported. */

	EMemoryAccess8 = 5,       /**< Indicates whether 8 bit memory access is supported. */

	EMemoryBE8 = 6,           /**< Indicates whether reading memory as 8 bit big-endian values is supported. */

	EMemoryBE32 = 7,          /**< Indicates whether reading memory as 32 bit big-endian values is supported. */

	EMemoryLE8 = 8,           /**< Indicates whether reading memory as 8 bit little-endian values is supported. */

	EMemoryMaxBlockSize = 9,  /**< Corresponds to the maximum size of a block of memory which can be requested. */

	/**

	  @internalTechnology

	  A debug agent should find the number of memory tags from the DFBlock rather than this enumerator.

	  */

	EMemoryLast

};

/**

  These tags define which objects can be killed by the device driver.

  TTag structures associated with the ETagHeaderIdKillObjects sub-block will have iTagId values from this enumeration.

  See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.

 */

enum TFunctionalityKillObject

{

	EFunctionalityKillThread = 0,          /**< Indicates whether killing threads is supported. */

	EFunctionalityKillProcess = 1,         /**< Indicates whether killing processes is supported. */

	/**

	  @internalTechnology

	  A debug agent should find the number of kill object tags from the DFBlock rather than this enumerator.

	  */

	EFunctionalityKillObjectLast

};

/**

  A TTag with an id from the TFunctionalityRegister enum will have a value from this enumeration.

  The values define how a register can be accessed, if at all.

 */

enum TFunctionalityAccess

{

	EAccessNone = 0,       /**< Indicates that a register cannot be accessed. */

	EAccessReadOnly = 1,   /**< Indicates that a register can be read, but not written to. */

	EAccessWriteOnly = 2,  /**< Indicates that a register can be written to, but not read. */

	EAccessReadWrite = 3,  /**< Indicates that a register can be both read and written to. */

	EAccessUnknown = 4,    /**< Indicates that it is unspecified whether reading or writing to a register is possible. */

};

/**

  These enumerators act as core register identifiers.

  TTag structures associated with the ETagHeaderIdRegistersCore sub-block will have iTagId values from this enumeration.

  The numeric value of each enumerator identifies the register according to the definitions in the Symbian Core Dump File Format Appendix B

  (see SGL.TS0028.027 - Symbian Core Dump File Format v1.0.doc).

  */

enum TFunctionalityRegister

{

	ERegisterR0 = 0x00000000,      /**< Identifier for user mode register R0. */

	ERegisterR1 = 0x00000100,      /**< Identifier for user mode register R1. */

	ERegisterR2 = 0x00000200,      /**< Identifier for user mode register R2. */

	ERegisterR3 = 0x00000300,      /**< Identifier for user mode register R3. */

	ERegisterR4 = 0x00000400,      /**< Identifier for user mode register R4. */

	ERegisterR5 = 0x00000500,      /**< Identifier for user mode register R5. */

	ERegisterR6 = 0x00000600,      /**< Identifier for user mode register R6. */

	ERegisterR7 = 0x00000700,      /**< Identifier for user mode register R7. */

	ERegisterR8 = 0x00000800,      /**< Identifier for user mode register R8. */

	ERegisterR9 = 0x00000900,      /**< Identifier for user mode register R9. */

	ERegisterR10 = 0x00000a00,     /**< Identifier for user mode register R10. */

	ERegisterR11 = 0x00000b00,     /**< Identifier for user mode register R11. */

	ERegisterR12 = 0x00000c00,     /**< Identifier for user mode register R12. */

	ERegisterR13 = 0x00000d00,     /**< Identifier for user mode register R13. */

	ERegisterR14 = 0x00000e00,     /**< Identifier for user mode register R14. */

	ERegisterR15 = 0x00000f00,     /**< Identifier for user mode register R15. */

	ERegisterCpsr = 0x00001000,    /**< Identifier for CPSR. */

	ERegisterR13Svc = 0x00001100,  /**< Identifier for R13 supervisor mode banked register. */

	ERegisterR14Svc = 0x00001200,  /**< Identifier for R14 supervisor mode banked register. */

	ERegisterSpsrSvc = 0x00001300, /**< Identifier for SPSR supervisor mode banked register. */

	ERegisterR13Abt = 0x00001400,  /**< Identifier for R13 Abort mode banked register. */

	ERegisterR14Abt = 0x00001500,  /**< Identifier for R14 Abort mode banked register. */

	ERegisterSpsrAbt = 0x00001600, /**< Identifier for SPSR Abort mode banked register. */

	ERegisterR13Und = 0x00001700,  /**< Identifier for R13 Undefined mode banked register. */

	ERegisterR14Und = 0x00001800,  /**< Identifier for R14 Undefined mode banked register. */

	ERegisterSpsrUnd = 0x00001900, /**< Identifier for SPSR Undefined mode banked register. */

	ERegisterR13Irq = 0x00001a00,  /**< Identifier for R13 Interrupt mode banked register. */

	ERegisterR14Irq = 0x00001b00,  /**< Identifier for R14 Interrupt mode banked register. */

	ERegisterSpsrIrq = 0x00001c00, /**< Identifier for SPSR Interrupt mode banked register. */

	ERegisterR8Fiq = 0x00001d00,   /**< Identifier for R8 Fast Interrupt mode banked register. */

	ERegisterR9Fiq = 0x00001e00,   /**< Identifier for R9 Fast Interrupt mode banked register. */

	ERegisterR10Fiq = 0x00001f00,  /**< Identifier for R10 Fast Interrupt mode banked register. */

	ERegisterR11Fiq = 0x00002000,  /**< Identifier for R11 Fast Interrupt mode banked register. */

	ERegisterR12Fiq = 0x00002100,  /**< Identifier for R12 Fast Interrupt mode banked register. */

	ERegisterR13Fiq = 0x00002200,  /**< Identifier for R13 Fast Interrupt mode banked register. */

	ERegisterR14Fiq = 0x00002300,  /**< Identifier for R14 Fast Interrupt mode banked register. */

	ERegisterSpsrFiq = 0x00002400, /**< Identifier for SPSR Fast Interrupt mode banked register. */

	/**

	  @internalTechnology

	  A debug agent should find the number of core registers from the DFBlock rather than this enumerator.

	  */

	ERegisterLast = 37

};

/**

  These tags define the kind of breakpoints that are supported.

  TTag structures associated with the ETagHeaderIdBreakpoints sub-block will have iTagId values from this enumeration.

  See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.

 */

enum TFunctionalityBreakpoint

{

	EBreakpointThread = 0,         /**< Indicates whether thread specific breakpoints are supported. */

	EBreakpointProcess = 1,        /**< Indicates whether process specific breakpoints are supported. */

	EBreakpointSystem = 2,         /**< Indicates whether system wide breakpoints are supported. */

	EBreakpointArm = 3,            /**< Indicates whether ARM mode breakpoints are supported. */

	EBreakpointThumb = 4,          /**< Indicates whether Thumb mode breakpoints are supported. */

	EBreakpointT2EE = 5,           /**< Indicates whether Thumb2 mode breakpoints are supported. */

	EBreakpointArmInst = 6,        /**< Reserved for future use. */

	EBreakpointThumbInst = 7,      /**< Reserved for future use. */

	EBreakpointT2EEInst = 8,       /**< Reserved for future use. */

	EBreakpointSetArmInst = 9,     /**< Reserved for future use. */

	EBreakpointSetThumbInst = 10,  /**< Reserved for future use. */

	EBreakpointSetT2EEInst = 11,   /**< Reserved for future use. */

	/**

	  @internalTechnology

	  A debug agent should find the number of breakpoint tags from the DFBlock rather than this enumerator.

	  */

	EBreakpointLast

};

/**

  These enumerators provide information about the stepping capabilities of the debug sub-system.

  TTag structures associated with the ETagHeaderIdStepping sub-block will have iTagId values from this enumeration.

  See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.

 */

enum TFunctionalityStep

{

	EStep = 0, /**< Indicates whether instruction stepping is supported. */

	/**

	  @internalTechnology

	  A debug agent should find the number of stepping tags from the DFBlock rather than this enumerator.

	  */

	EStepLast

};

/**

  These enumerators provide information about the execution control capabilities of the debug sub-system.

  TTag structures associated with the ETagHeaderIdExecution sub-block will have iTagId values from this enumeration.

  See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.

 */

enum TFunctionalityExec

{

	EExecThreadSuspendResume = 0,  /**< Indicates whether suspending and resuming threads is supported. */

	EExecProcessSuspendResume = 1, /**< Indicates whether suspending and resuming processes is supported. */

	EExecSystemSuspendResume = 2,  /**< Indicates whether suspending and resuming the entire system is supported. */

	/**

	  @internalTechnology

	  A debug agent should find the number of execution control tags from the DFBlock rather than this enumerator.

	  */

	EExecLast

};

/**

  This enumeration defines the event types supported by the debug sub-system.

  TTag structures associated with the ETagHeaderIdEvents sub-block will have

  iTagId values from this enumeration, and iValue values from the TKernelEventAction enumeration.

  These enumerators are also used by the RSecuritySvrSession API to identify events.

  @see RSecuritySvrSession

  @see TKernelEventAction

 */

enum TEventType

{

	EEventsBreakPoint = 0,    /**< Identifies a breakpoint event. */

	EEventsSwExc = 1,         /**< Identifies a software exception event. */

	EEventsHwExc = 2,         /**< Identifies a hardware exception event. */

	EEventsKillThread = 3,    /**< Identifies a kill thread event. */

	EEventsAddLibrary = 4,    /**< Identifies an add library event. */

	EEventsRemoveLibrary = 5, /**< Identifies a remove library event. */

	/**

	 If an event is generated and there is only a single space remaining in the events queue then

	 an event of type EEventsBufferFull will be stored in the queue and the generated event will

	 be discarded. If further events occur while the buffer is full the events will be discarded.

	 As such an event of type EEventsBufferFull being returned signifies that one or more events

	 were discarded. An event of this type has no valid data associated with it.

	 */

	EEventsBufferFull = 6,

	EEventsUnknown = 7,       /**< Identifies an event of unknown type. */

	EEventsUserTrace = 8,     /**< Identifies a user trace. */

	EEventsProcessBreakPoint = 9, /**< Identifies a process breakpoint event. */

	EEventsStartThread = 10, /**< Identifies a start thread event. */

	EEventsUserTracesLost = 11, /**< Identifies user traces being lost. */

	EEventsAddProcess = 12, /**< Identifies an AddProcess event */

	EEventsRemoveProcess = 13, /**< Identifies a RemoveProcess event */

	/**

	  @internalTechnology

	  A debug agent should find the number of event types from the DFBlock rather than this enumerator.

	  */

	EEventsLast

};

/**

  These enumerators provide information about constants which are used in the RSecuritySvrSession API.

  TTag structures associated with the ETagHeaderIdApiConstants sub-block will have iTagId values from this enumeration.

  See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.

 */

enum TFunctionalityApiConstants

	{

	/**

	  Corresponds to the size of a buffer required to store a TEventInfo.

	  @see TEventInfo

	  */

	EApiConstantsTEventInfoSize = 0,

	/**

	  @internalTechnology

	  A debug agent should find the number of API constants tags from the DFBlock rather than this enumerator.

	  */

	EApiConstantsLast,

	};

/**

  The set of possible actions which could be taken when a kernel event occurs.

  Not all actions are possible for all events. The debug functionality sub-block with header id ETagHeaderIdEvents

  indicates which values are permitted for each event. The value given for that event should be

  considered as the most intrusive action the debugger may set: with the definition that EActionSuspend is more

  intrusive than EActionContinue, which is more intrusive than EActionIgnore.

  @see RSecuritySvrSession

  */

enum TKernelEventAction

{

	/** If an event action is set to this value then events of that type will be

	  ignored, and not reported to the debugger. */

	EActionIgnore = 0,

	/** If an event action is set to this value then events of that type will be

	  reported to the debugger and the thread which generated the event will be

	  allowed to continue executing. */

	EActionContinue = 1,

	/** If an event action is set to this value then events of that type will be

	  reported to the debugger and the thread which generated the event will be

	  suspended. */

	EActionSuspend = 2,

	/**

	  @internalTechnology

	  Count of event actions.

	  */

	EActionLast

};

/**

  These enumerators provide information about the ability of the debug subsystem to support OEM Debug tokens.

  TTag structures associated with the ETagHeaderIdSecurity sub-block will have iTagId values from this enumeration.

  See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.

 */

enum TFunctionalitySecurity

{

	ESecurityOEMDebugToken = 0,  /**< Indicates whether the DSS supports the use of OEM Debug Tokens. */

	/**

	  @internalTechnology

	  A debug agent should find the number of tags from the DFBlock rather than this enumerator.

	  */

	ESecurityLast

};

/**

  Used for storing the contents of a 32 bit register

  */

typedef TUint32 TRegisterValue32;

/**

 * Processor mode

 */

enum TArmProcessorModes

{

	EUserMode=0x10,    	//!< EUserMode

    EFiqMode=0x11,  	//!< EFiqMode

    EIrqMode=0x12,  	//!< EIrqMode

    ESvcMode=0x13,  	//!< ESvcMode

    EAbortMode=0x17,	//!< EAbortMode

    EUndefMode=0x1b,	//!< EUndefMode

    EMaskMode=0x1f  	//!< EMaskMode

};

/**

  Structure containing information about the state of the registers when a

  hardware exception occurred

  */

class TRmdArmExcInfo

	{

public:

	/** Enumeration detailing the types of exception which may occur. */

	enum TExceptionType

		{

		/** Enumerator signifying that a prefetch abort error has occurred. */

		EPrefetchAbort = 0,

		/** Enumerator signifying that a data abort error has occurred. */

		EDataAbort = 1,

		/** Enumerator signifying that an undefined instruction error has occurred. */

		EUndef =2

		};

	/** Value of CPSR. */

	TRegisterValue32 iCpsr;

	/** Type of exception which has occurred. */

	TExceptionType iExcCode;

	/** Value of R13 supervisor mode banked register. */

	TRegisterValue32 iR13Svc;

	/** Value of user mode register R4. */

	TRegisterValue32 iR4;

	/** Value of user mode register R5. */

	TRegisterValue32 iR5;

	/** Value of user mode register R6. */

	TRegisterValue32 iR6;

	/** Value of user mode register R7. */

	TRegisterValue32 iR7;

	/** Value of user mode register R8. */

	TRegisterValue32 iR8;

	/** Value of user mode register R9. */

	TRegisterValue32 iR9;

	/** Value of user mode register R10. */

	TRegisterValue32 iR10;

	/** Value of user mode register R11. */

	TRegisterValue32 iR11;

	/** Value of R14 supervisor mode banked register. */

	TRegisterValue32 iR14Svc;

	/** Address which caused exception (System Control Coprocessor Fault Address Register) */

	TRegisterValue32 iFaultAddress;

	/** Value of System Control Coprocessor Fault Status Register. */

	TRegisterValue32 iFaultStatus;

	/** Value of SPSR supervisor mode banked register. */

	TRegisterValue32 iSpsrSvc;

	/** Value of user mode register R13. */

	TRegisterValue32 iR13;

	/** Value of user mode register R14. */

	TRegisterValue32 iR14;

	/** Value of user mode register R0. */

	TRegisterValue32 iR0;