1 // Copyright (c) 2006-2009 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 the License "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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // Definitions for the run mode debug agent client side sessions.
16 // WARNING: This file contains some APIs which are internal and are subject
17 // to change without notice. Such APIs should therefore not be used
18 // outside the Kernel and Hardware Services package.
21 #ifndef RM_DEBUG_API_H
22 #define RM_DEBUG_API_H
31 #include <e32def_private.h>
34 The Debug namespace contains all API definitions used for on-target debugging.
38 /** This is the maximum size in bytes a user trace can be */
39 const TInt TUserTraceSize = 256;
42 Information in the debug functionality block is represented as a concatenation
43 of pairs of TTagHeader structures and arrays of TTag objects.
45 @see RSecuritySvrSession::GetDebugFunctionality
49 /** Tag ID, value identifying this tag. */
52 Values correspond to TTagType enumerators.
56 /** Size of external data associated with this tag. */
58 /** Data associated with this tag. */
63 Enumeration defining the supported tag types. These enumerators are used in TTag.iTagId.
68 /** Indicates that the iValue field of a TTag structure will contain either ETrue or EFalse. */
70 /** Indicates that the iValue field of a TTag structure will contain a value in the TUint32 range. */
72 /** Indicates that the iValue field of a TTag structure will contain values from an enumeration. */
74 /** Indicates that the iValue field of a TTag structure should be interpreted as a bit field. */
76 /** Indicates that the type of the iValue field of a TTag structure is unknown. */
78 /** Indicates that the iValue field of a TTag structure will contain a pointer. */
83 Information in the debug functionality block is represented as a concatenation
84 of pairs of TTagHeader structures and arrays of TTag objects.
86 @see RSecuritySvrSession::GetDebugFunctionality
90 /** Value identifying the contents of this TTagHeader, should be interpreted as an enumerator from TTagHeaderId.
94 /** The number of TTag elements in the array associated with this TTagHeader. */
99 Enumeration used to identify TTagHeader structures, TTagHeader::iTagHdrId elements take these enumerators as values.
104 ETagHeaderIdCore = 0, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityCore. */
105 ETagHeaderIdMemory = 1, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityMemory. */
107 Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityRegister.
108 These values are defined as in the document Symbian Core Dump File Format Appendix C
109 (see SGL.TS0028.027 - Symbian Core Dump File Format v1.0.doc).
110 The TTag objects in the associated array have an iSize value corresponding to the size of the register's data in bytes.
112 ETagHeaderIdRegistersCore = 2,
114 Identifies a TTagHeader with associated TTag elements with iTagId values corresponding to coprocessor register identifiers.
115 Coprocessor registers are defined as in the document Symbian Core Dump File Format Appendix C as follows
116 (see SGL.TS0028.027 - Symbian Core Dump File Format v1.0.doc):
118 For each 32-bit data word defining a co-pro register, the definition of the meaning of the bits follows
119 the ARM Architecture Reference manual instruction coding
121 Upper Halfword Lower Halfword
124 For example: The Domain Access Control Register is Register 3 of co-processor 15. The encoding is therefore
128 Therefore the functionality tag would be:
129 TagID: 15 // co-processor number
130 Type: ETagTypeTUint32
131 Data: 0x00000003 // Opcode2 = 0, CRm = 3
133 ETagHeaderIdCoProRegisters = 3, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityRegister. */
134 ETagHeaderIdBreakpoints = 4, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityBreakpoint. */
135 ETagHeaderIdStepping = 5, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityStep. */
136 ETagHeaderIdExecution = 6, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityExec. */
137 ETagHeaderIdEvents = 7, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TEventType. */
138 ETagHeaderIdApiConstants = 8, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityApiConstants.*/
139 ETagHeaderList = 9, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TListId. */
140 ETagHeaderIdKillObjects = 10, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityKillObject. */
141 ETagHeaderIdSecurity = 11, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalitySecurity */
142 ETagHeaderIdBuffers = 12, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TBufferType. */
143 ETagHeaderIdStopModeFunctions = 13, /**< Identifies a TTagHeader with associated TTag elements with iTagId values from TFunctionalityStopModeFunctions. */
147 This structure is not used in the run-mode debug API.
152 /** Header to identify the TSubBlock. */
154 /** Pointer to array of TTag values associated with this TSubBlock. */
159 These tags define what kinds of core functionality are supported by the run-mode debug subsystem.
160 TTag structures associated with the ETagHeaderIdCore sub-block will have iTagId values from this enumeration.
161 See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.
163 enum TFunctionalityCore
165 ECoreEvents = 0, /**< Indicates whether events processing is supported. */
166 ECoreStartStop = 1, /**< Indicates whether suspending and resuming threads is supported. */
167 ECoreMemory = 2, /**< Indicates whether reading and writing memory is supported. */
168 ECoreRegister = 3, /**< Indicates whether reading and writing register values is supported. */
169 ECoreBreakpoint = 4, /**< Indicates whether breakpoints are supported. */
170 ECoreStepping = 5, /**< Indicates whether stepping is supported. */
171 ECoreLists = 6, /**< Indicates whether listings are supported. */
172 ECoreLogging = 7, /**< Indicates whether logging is supported. */
173 ECoreHardware = 8, /**< Indicates whether hardware support is supported. */
174 ECoreApiConstants = 9, /**< Indicates whether the information in the ETagHeaderIdApiConstants sub-block is relevant. */
175 ECoreKillObjects = 10, /**< Indicates whether killing objects (i.e. threads and processes) is supported. */
176 ECoreSecurity = 11, /**< Indicates whether OEM Debug token support or other security info is supported. */
177 ECoreStopModeFunctions = 12, /**< Indicates whether Stop Mode function calling is supported. */
178 ECoreStopModeBuffers = 13, /**< Indicates whether Stop Mode buffers are supported. */
182 A debug agent should find the number of core tags from the DFBlock rather than this enumerator.
188 These tags define what kind of memory operations can be performed.
189 TTag structures associated with the ETagHeaderIdMemory sub-block will have iTagId values from this enumeration.
190 See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.
192 enum TFunctionalityMemory
194 EMemoryRead = 0, /**< Indicates whether reading memory is supported. */
195 EMemoryWrite = 1, /**< Indicates whether writing memory is supported. */
196 EMemoryAccess64 = 2, /**< Indicates whether 64 bit memory access is supported. */
197 EMemoryAccess32 = 3, /**< Indicates whether 32 bit memory access is supported. */
198 EMemoryAccess16 = 4, /**< Indicates whether 16 bit memory access is supported. */
199 EMemoryAccess8 = 5, /**< Indicates whether 8 bit memory access is supported. */
200 EMemoryBE8 = 6, /**< Indicates whether reading memory as 8 bit big-endian values is supported. */
201 EMemoryBE32 = 7, /**< Indicates whether reading memory as 32 bit big-endian values is supported. */
202 EMemoryLE8 = 8, /**< Indicates whether reading memory as 8 bit little-endian values is supported. */
203 EMemoryMaxBlockSize = 9, /**< Corresponds to the maximum size of a block of memory which can be requested. */
206 A debug agent should find the number of memory tags from the DFBlock rather than this enumerator.
212 These tags define which objects can be killed by the device driver.
213 TTag structures associated with the ETagHeaderIdKillObjects sub-block will have iTagId values from this enumeration.
214 See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.
216 enum TFunctionalityKillObject
218 EFunctionalityKillThread = 0, /**< Indicates whether killing threads is supported. */
219 EFunctionalityKillProcess = 1, /**< Indicates whether killing processes is supported. */
222 A debug agent should find the number of kill object tags from the DFBlock rather than this enumerator.
224 EFunctionalityKillObjectLast
228 A TTag with an id from the TFunctionalityRegister enum will have a value from this enumeration.
229 The values define how a register can be accessed, if at all.
231 enum TFunctionalityAccess
233 EAccessNone = 0, /**< Indicates that a register cannot be accessed. */
234 EAccessReadOnly = 1, /**< Indicates that a register can be read, but not written to. */
235 EAccessWriteOnly = 2, /**< Indicates that a register can be written to, but not read. */
236 EAccessReadWrite = 3, /**< Indicates that a register can be both read and written to. */
237 EAccessUnknown = 4, /**< Indicates that it is unspecified whether reading or writing to a register is possible. */
241 These enumerators act as core register identifiers.
242 TTag structures associated with the ETagHeaderIdRegistersCore sub-block will have iTagId values from this enumeration.
243 The numeric value of each enumerator identifies the register according to the definitions in the Symbian Core Dump File Format Appendix B
244 (see SGL.TS0028.027 - Symbian Core Dump File Format v1.0.doc).
246 enum TFunctionalityRegister
248 ERegisterR0 = 0x00000000, /**< Identifier for user mode register R0. */
249 ERegisterR1 = 0x00000100, /**< Identifier for user mode register R1. */
250 ERegisterR2 = 0x00000200, /**< Identifier for user mode register R2. */
251 ERegisterR3 = 0x00000300, /**< Identifier for user mode register R3. */
252 ERegisterR4 = 0x00000400, /**< Identifier for user mode register R4. */
253 ERegisterR5 = 0x00000500, /**< Identifier for user mode register R5. */
254 ERegisterR6 = 0x00000600, /**< Identifier for user mode register R6. */
255 ERegisterR7 = 0x00000700, /**< Identifier for user mode register R7. */
256 ERegisterR8 = 0x00000800, /**< Identifier for user mode register R8. */
257 ERegisterR9 = 0x00000900, /**< Identifier for user mode register R9. */
258 ERegisterR10 = 0x00000a00, /**< Identifier for user mode register R10. */
259 ERegisterR11 = 0x00000b00, /**< Identifier for user mode register R11. */
260 ERegisterR12 = 0x00000c00, /**< Identifier for user mode register R12. */
261 ERegisterR13 = 0x00000d00, /**< Identifier for user mode register R13. */
262 ERegisterR14 = 0x00000e00, /**< Identifier for user mode register R14. */
263 ERegisterR15 = 0x00000f00, /**< Identifier for user mode register R15. */
264 ERegisterCpsr = 0x00001000, /**< Identifier for CPSR. */
265 ERegisterR13Svc = 0x00001100, /**< Identifier for R13 supervisor mode banked register. */
266 ERegisterR14Svc = 0x00001200, /**< Identifier for R14 supervisor mode banked register. */
267 ERegisterSpsrSvc = 0x00001300, /**< Identifier for SPSR supervisor mode banked register. */
268 ERegisterR13Abt = 0x00001400, /**< Identifier for R13 Abort mode banked register. */
269 ERegisterR14Abt = 0x00001500, /**< Identifier for R14 Abort mode banked register. */
270 ERegisterSpsrAbt = 0x00001600, /**< Identifier for SPSR Abort mode banked register. */
271 ERegisterR13Und = 0x00001700, /**< Identifier for R13 Undefined mode banked register. */
272 ERegisterR14Und = 0x00001800, /**< Identifier for R14 Undefined mode banked register. */
273 ERegisterSpsrUnd = 0x00001900, /**< Identifier for SPSR Undefined mode banked register. */
274 ERegisterR13Irq = 0x00001a00, /**< Identifier for R13 Interrupt mode banked register. */
275 ERegisterR14Irq = 0x00001b00, /**< Identifier for R14 Interrupt mode banked register. */
276 ERegisterSpsrIrq = 0x00001c00, /**< Identifier for SPSR Interrupt mode banked register. */
277 ERegisterR8Fiq = 0x00001d00, /**< Identifier for R8 Fast Interrupt mode banked register. */
278 ERegisterR9Fiq = 0x00001e00, /**< Identifier for R9 Fast Interrupt mode banked register. */
279 ERegisterR10Fiq = 0x00001f00, /**< Identifier for R10 Fast Interrupt mode banked register. */
280 ERegisterR11Fiq = 0x00002000, /**< Identifier for R11 Fast Interrupt mode banked register. */
281 ERegisterR12Fiq = 0x00002100, /**< Identifier for R12 Fast Interrupt mode banked register. */
282 ERegisterR13Fiq = 0x00002200, /**< Identifier for R13 Fast Interrupt mode banked register. */
283 ERegisterR14Fiq = 0x00002300, /**< Identifier for R14 Fast Interrupt mode banked register. */
284 ERegisterSpsrFiq = 0x00002400, /**< Identifier for SPSR Fast Interrupt mode banked register. */
287 A debug agent should find the number of core registers from the DFBlock rather than this enumerator.
294 These tags define the kind of breakpoints that are supported.
295 TTag structures associated with the ETagHeaderIdBreakpoints sub-block will have iTagId values from this enumeration.
296 See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.
298 enum TFunctionalityBreakpoint
300 EBreakpointThread = 0, /**< Indicates whether thread specific breakpoints are supported. */
301 EBreakpointProcess = 1, /**< Indicates whether process specific breakpoints are supported. */
302 EBreakpointSystem = 2, /**< Indicates whether system wide breakpoints are supported. */
303 EBreakpointArm = 3, /**< Indicates whether ARM mode breakpoints are supported. */
304 EBreakpointThumb = 4, /**< Indicates whether Thumb mode breakpoints are supported. */
305 EBreakpointT2EE = 5, /**< Indicates whether Thumb2 mode breakpoints are supported. */
306 EBreakpointArmInst = 6, /**< Reserved for future use. */
307 EBreakpointThumbInst = 7, /**< Reserved for future use. */
308 EBreakpointT2EEInst = 8, /**< Reserved for future use. */
309 EBreakpointSetArmInst = 9, /**< Reserved for future use. */
310 EBreakpointSetThumbInst = 10, /**< Reserved for future use. */
311 EBreakpointSetT2EEInst = 11, /**< Reserved for future use. */
314 A debug agent should find the number of breakpoint tags from the DFBlock rather than this enumerator.
320 These enumerators provide information about the stepping capabilities of the debug sub-system.
321 TTag structures associated with the ETagHeaderIdStepping sub-block will have iTagId values from this enumeration.
322 See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.
324 enum TFunctionalityStep
326 EStep = 0, /**< Indicates whether instruction stepping is supported. */
329 A debug agent should find the number of stepping tags from the DFBlock rather than this enumerator.
335 These enumerators provide information about the execution control capabilities of the debug sub-system.
336 TTag structures associated with the ETagHeaderIdExecution sub-block will have iTagId values from this enumeration.
337 See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.
339 enum TFunctionalityExec
341 EExecThreadSuspendResume = 0, /**< Indicates whether suspending and resuming threads is supported. */
342 EExecProcessSuspendResume = 1, /**< Indicates whether suspending and resuming processes is supported. */
343 EExecSystemSuspendResume = 2, /**< Indicates whether suspending and resuming the entire system is supported. */
346 A debug agent should find the number of execution control tags from the DFBlock rather than this enumerator.
352 This enumeration defines the event types supported by the debug sub-system.
353 TTag structures associated with the ETagHeaderIdEvents sub-block will have
354 iTagId values from this enumeration, and iValue values from the TKernelEventAction enumeration.
356 These enumerators are also used by the RSecuritySvrSession API to identify events.
357 @see RSecuritySvrSession
358 @see TKernelEventAction
362 EEventsBreakPoint = 0, /**< Identifies a breakpoint event. */
363 EEventsSwExc = 1, /**< Identifies a software exception event. */
364 EEventsHwExc = 2, /**< Identifies a hardware exception event. */
365 EEventsKillThread = 3, /**< Identifies a kill thread event. */
366 EEventsAddLibrary = 4, /**< Identifies an add library event. */
367 EEventsRemoveLibrary = 5, /**< Identifies a remove library event. */
369 If an event is generated and there is only a single space remaining in the events queue then
370 an event of type EEventsBufferFull will be stored in the queue and the generated event will
371 be discarded. If further events occur while the buffer is full the events will be discarded.
372 As such an event of type EEventsBufferFull being returned signifies that one or more events
373 were discarded. An event of this type has no valid data associated with it.
375 EEventsBufferFull = 6,
376 EEventsUnknown = 7, /**< Identifies an event of unknown type. */
377 EEventsUserTrace = 8, /**< Identifies a user trace. */
378 EEventsProcessBreakPoint = 9, /**< Identifies a process breakpoint event. */
379 EEventsStartThread = 10, /**< Identifies a start thread event. */
380 EEventsUserTracesLost = 11, /**< Identifies user traces being lost. */
381 EEventsAddProcess = 12, /**< Identifies an AddProcess event */
382 EEventsRemoveProcess = 13, /**< Identifies a RemoveProcess event */
385 A debug agent should find the number of event types from the DFBlock rather than this enumerator.
391 These enumerators provide information about constants which are used in the RSecuritySvrSession API.
392 TTag structures associated with the ETagHeaderIdApiConstants sub-block will have iTagId values from this enumeration.
393 See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.
395 enum TFunctionalityApiConstants
398 Corresponds to the size of a buffer required to store a TEventInfo.
401 EApiConstantsTEventInfoSize = 0,
404 A debug agent should find the number of API constants tags from the DFBlock rather than this enumerator.
410 The set of possible actions which could be taken when a kernel event occurs.
411 Not all actions are possible for all events. The debug functionality sub-block with header id ETagHeaderIdEvents
412 indicates which values are permitted for each event. The value given for that event should be
413 considered as the most intrusive action the debugger may set: with the definition that EActionSuspend is more
414 intrusive than EActionContinue, which is more intrusive than EActionIgnore.
415 @see RSecuritySvrSession
417 enum TKernelEventAction
419 /** If an event action is set to this value then events of that type will be
420 ignored, and not reported to the debugger. */
422 /** If an event action is set to this value then events of that type will be
423 reported to the debugger and the thread which generated the event will be
424 allowed to continue executing. */
426 /** If an event action is set to this value then events of that type will be
427 reported to the debugger and the thread which generated the event will be
432 Count of event actions.
438 These enumerators provide information about the ability of the debug subsystem to support OEM Debug tokens.
439 TTag structures associated with the ETagHeaderIdSecurity sub-block will have iTagId values from this enumeration.
440 See each enumerator for an explanation of how a TTag with that iTagId should be interpreted.
442 enum TFunctionalitySecurity
444 ESecurityOEMDebugToken = 0, /**< Indicates whether the DSS supports the use of OEM Debug Tokens. */
448 A debug agent should find the number of tags from the DFBlock rather than this enumerator.
454 Used for storing the contents of a 32 bit register
456 typedef TUint32 TRegisterValue32;
462 enum TArmProcessorModes
464 EUserMode=0x10, //!< EUserMode
465 EFiqMode=0x11, //!< EFiqMode
466 EIrqMode=0x12, //!< EIrqMode
467 ESvcMode=0x13, //!< ESvcMode
468 EAbortMode=0x17, //!< EAbortMode
469 EUndefMode=0x1b, //!< EUndefMode
470 EMaskMode=0x1f //!< EMaskMode
476 Structure containing information about the state of the registers when a
477 hardware exception occurred
482 /** Enumeration detailing the types of exception which may occur. */
485 /** Enumerator signifying that a prefetch abort error has occurred. */
487 /** Enumerator signifying that a data abort error has occurred. */
489 /** Enumerator signifying that an undefined instruction error has occurred. */
493 /** Value of CPSR. */
494 TRegisterValue32 iCpsr;
495 /** Type of exception which has occurred. */
496 TExceptionType iExcCode;
497 /** Value of R13 supervisor mode banked register. */
498 TRegisterValue32 iR13Svc;
499 /** Value of user mode register R4. */
500 TRegisterValue32 iR4;
501 /** Value of user mode register R5. */
502 TRegisterValue32 iR5;
503 /** Value of user mode register R6. */
504 TRegisterValue32 iR6;
505 /** Value of user mode register R7. */
506 TRegisterValue32 iR7;
507 /** Value of user mode register R8. */
508 TRegisterValue32 iR8;
509 /** Value of user mode register R9. */
510 TRegisterValue32 iR9;
511 /** Value of user mode register R10. */
512 TRegisterValue32 iR10;
513 /** Value of user mode register R11. */
514 TRegisterValue32 iR11;
515 /** Value of R14 supervisor mode banked register. */
516 TRegisterValue32 iR14Svc;
517 /** Address which caused exception (System Control Coprocessor Fault Address Register) */
518 TRegisterValue32 iFaultAddress;
519 /** Value of System Control Coprocessor Fault Status Register. */
520 TRegisterValue32 iFaultStatus;
521 /** Value of SPSR supervisor mode banked register. */
522 TRegisterValue32 iSpsrSvc;
523 /** Value of user mode register R13. */
524 TRegisterValue32 iR13;
525 /** Value of user mode register R14. */
526 TRegisterValue32 iR14;
527 /** Value of user mode register R0. */
528 TRegisterValue32 iR0;
529 /** Value of user mode register R1. */
530 TRegisterValue32 iR1;
531 /** Value of user mode register R2. */
532 TRegisterValue32 iR2;
533 /** Value of user mode register R3. */
534 TRegisterValue32 iR3;
535 /** Value of user mode register R12. */
536 TRegisterValue32 iR12;
537 /** Value of user mode register R15, points to instruction which caused exception. */
538 TRegisterValue32 iR15;
542 The maximum size, in bytes, of the panic category string returned as part of a
548 const TInt KPanicCategoryMaxName = KMaxName;
551 Event specific information returned as part of a TEventInfo object when
552 an agent set breakpoint is hit.
554 class TThreadBreakPointInfo
557 /** Identifies the type of exception. */
558 TExcType iExceptionNumber;
559 /** Structure containing information about the ARM register values. */
560 TRmdArmExcInfo iRmdArmExcInfo;
564 Event specific information returned as part of a TEventInfo object when
565 a software exception occurs.
567 class TThreadSwExceptionInfo
570 /** The value of the program counter. */
572 /** Identifies the type of exception. */
573 TExcType iExceptionNumber;
577 Event specific information returned as part of a TEventInfo object when
578 a hardware exception occurs.
580 class TThreadHwExceptionInfo
583 /** Identifies the type of exception. */
584 TExcType iExceptionNumber;
585 /** Structure containing information about the ARM register values. */
586 TRmdArmExcInfo iRmdArmExcInfo;
590 Event specific information returned as part of a TEventInfo object when
591 a thread kill event occurs.
593 class TThreadKillInfo
596 /** The value of the program counter. */
598 /** Specifies the reason for the kill thread event, this value is specific to the killed thread and does not correspond to a standard Symbian enumeration. */
600 /** Specifies the type of the thread kill event, values correspond to elements of TExitType. */
602 /** The panic category of the killed thread. */
603 TUint8 iPanicCategory[KPanicCategoryMaxName];
604 /** Contains the length in bytes of the initialised data in iPanicCategory. */
605 TInt iPanicCategoryLength;
609 Event specific information returned as part of a TEventInfo object when
610 a library load event occurs.
612 class TLibraryLoadedInfo
615 /** The name of the file that the library was loaded from. */
616 TUint8 iFileName[KMaxName];
617 /** Contains the length in bytes of the initialised data in iFileName. */
618 TInt iFileNameLength;
619 /** The code base address (.text). */
620 TUint32 iCodeAddress;
621 /** The base address of the initialised data section (.data). */
622 TUint32 iDataAddress;
626 Event specific information returned as part of a TEventInfo object when
629 class TStartThreadInfo
632 /** The name of the file that the process owning the thread was created from. */
633 TUint8 iFileName[KMaxName];
634 /** Contains the length in bytes of the initialised data in iFileName. */
635 TInt iFileNameLength;
639 Event specific information returned as part of a TEventInfo object when
640 a process is added. Note that the Process may not be fully constructed,
643 class TAddProcessInfo
646 /** The name of the file that the process was created from. */
647 TUint8 iFileName[KMaxName];
648 /** Contains the length in bytes of the initialised data in iFileName. */
649 TInt iFileNameLength;
650 /** The UID3 of this process */
652 /** Contains the CreatorThread ID if available: May be 0 */
653 TUint64 iCreatorThreadId;
657 Event specific information returned as part of a TEventInfo object when
658 a process is removed. Note that the Process may not be fully destroyed,
659 so its resources should only be accessed if you already have a handle to it.
661 class TRemoveProcessInfo
664 /** The name of the file that the process was created from. */
665 TUint8 iFileName[KMaxName];
666 /** Contains the length in bytes of the initialised data in iFileName. */
667 TInt iFileNameLength;
668 TUint32 iSpare1; // Unused
672 Event specific information returned as part of a TEventInfo object when
673 a library unload event occurs.
675 class TLibraryUnloadedInfo
678 /** The name of the file that the library was loaded from. */
679 TUint8 iFileName[KMaxName];
680 /** Contains the length in bytes of the initialised data in iFileName. */
681 TInt iFileNameLength;
685 * Enum to represent the context of a user trace message
687 enum TUserTraceMessageContext
689 ESingleMessage = 0x1, /** Indicates this message is the only one corresponding to a given user trace */
690 EMultiStart = 0x2, /** Indicates this message is the start of a user trace which consists of multiple messages */
691 EMultiMid = 0x3, /** Indicates this message is one in a series of user trace messages */
692 EMultiEnd = 0x4, /** Indicates this message is the last in a series of user trace messages */
695 A debug agent should find the number of core tags from the DFBlock rather than this enumerator.
701 * Event specific information returned as part of a TEventInfo object
702 * when a user trace event occurs.
707 /** The user trace text */
708 TUint8 iUserTraceText[TUserTraceSize];
710 /** User trace text length */
711 TInt iUserTraceLength;
713 /** The context of the message */
714 TUserTraceMessageContext iMessageStatus;
719 Structure used to store information about an event. An object of this type
720 is passed as an argument to the RSecuritySvrSession::GetEvent function,
721 and is filled in by the debug driver, and returned to the agent, when a
722 relevant event occurs.
724 The debug functionality block contains the size in bytes of the data that
725 the driver will return when a GetEvent call is issued. A debug agent should
726 ensure that this value equals the size of this TEventInfo object to ensure
727 that a compatible debug driver is being used. The value is stored as
728 EApiConstantsTEventInfoSize in the TFunctionalityApiConstants block.
730 @see RSecuritySvrSession::GetDebugFunctionality
731 @see RSecuritySvrSession::GetEvent
737 /** Constructor sets all elements to default values. */
738 inline TEventInfo() { Reset(); };
740 /** Resets all values to default values. */
744 iProcessIdValid = EFalse;
746 iThreadIdValid = EFalse;
747 iEventType = (TEventType)NULL;
752 /** The process ID of the process which the event occurred in. */
754 /** The thread ID of the thread which the event occurred in. */
756 /** Has value ETrue if iProcessId is valid, EFalse otherwise. */
757 TUint8 iProcessIdValid;
758 /** Has value ETrue if iThreadId is valid, EFalse otherwise. */
759 TUint8 iThreadIdValid;
760 /** Indicates the type of the event. This type should be used to determine
761 the type of the information stored in the union which is part of this class. */
762 TEventType iEventType;
765 /** Information which is specific to the break point event. */
766 TThreadBreakPointInfo iThreadBreakPointInfo;
767 /** Information which is specific to the software exception event. */
768 TThreadSwExceptionInfo iThreadSwExceptionInfo;
769 /** Information which is specific to the hardware exception event. */
770 TThreadHwExceptionInfo iThreadHwExceptionInfo;
771 /** Information which is specific to the thread kill event. */
772 TThreadKillInfo iThreadKillInfo;
773 /** Information which is specific to the library loaded event. */
774 TLibraryLoadedInfo iLibraryLoadedInfo;
775 /** Information which is specific to the library unloaded event. */
776 TLibraryUnloadedInfo iLibraryUnloadedInfo;
777 /** Information which is specific to the user trace event. */
778 TUserTraceInfo iUserTraceInfo;
779 /** Information which is specific to the start thread event. */
780 TStartThreadInfo iStartThreadInfo;
781 /** Information which is specific to the Add Process event. */
782 TAddProcessInfo iAddProcessInfo;
783 /** Information which is specific to the Remove Process event. */
784 TRemoveProcessInfo iRemoveProcessInfo;
795 inline TProcessInfo() { Reset(); }
797 inline TProcessInfo(TUint32 aId, TUint32 aCodeAddress, TUint32 aCodeSize, TUint32 aDataAddress)
799 iCodeAddress(aCodeAddress),
800 iCodeSize(aCodeSize),
801 iDataAddress(aDataAddress) { }
814 TUint32 iCodeAddress;
816 TUint32 iDataAddress;
819 /* Other functionality may be defined here later */
822 Represents a register id value, in the terms of the Symbian ELF format:
823 - bits 0-7 define the class
824 - bits 8-15 define the rd_id
825 - bits 16-31 define the rd_sub_id
827 Both the core registers (TFunctionalityRegister type) and the coprocessor registers
828 follow this identifier scheme.
830 typedef TUint32 TRegisterInfo;
833 Enum representing the status flags which could be returned from a register
839 Default value, a register access call will never return this value
843 Would be returned if the register is supported by the debug driver but the kernel cannot access the register
847 Would be returned if the register could be accessed correctly
851 Would be returned if the register is not supported by the debug driver
855 Would be returned if a non-4 byte register value was requested
861 Enum representing the different ARM CPU instruction set architectures.
863 enum TArchitectureMode
865 /** Represents the ARM CPU architecture. */
867 /** Represents the Thumb CPU architecture. */
870 Represents the Thumb2 CPU architecture.
877 Used as an identifier for breakpoints set by the RSecuritySvrSession::SetBreak function.
878 @see RSecuritySvrSession
880 typedef TInt32 TBreakId;
883 Specifies the type of a code segment.
884 @see TCodeSegListEntry
888 EUnknownCodeSegType = 0, /**< Signifies an unknown code segment type. */
889 EExeCodeSegType = 1, /**< Signifies a code segment belonging to an executable. */
890 EDllCodeSegType = 2 /**< Signifies a code segment belonging to a library. */
894 Structure used for extracting data from a descriptor returned by a call to
895 RSecuritySvrSession::GetList() when GetList() is called with TListId::ECodeSegs
896 as the first argument.
898 @see RSecuritySvrSession::GetList()
901 //buffer is a TDesC8 containing 4-byte aligned TCodeSegListEntry objects
902 //create a pointer to the start of the data
903 TUint8* ptr = (TUint8*)buffer.Ptr();
904 //create a pointer to the end of the data
905 const TUint8* ptrEnd = ptr + buffer.Length();
908 //cast the pointer to be a TCodeSegListEntry object
909 TCodeSegListEntry& entry = *(TCodeSegListEntry*)ptr;
910 //use the TCodeSegListEntry pointer, i.e.
911 TUint16 nameLength = entry.iNameLength;
912 TPtr name(&(entry.iName[0]), nameLength, nameLength);
913 // move ptr on to point to the next TCodeSegListEntry object
914 ptr += Align4(entry.GetSize());
918 class TCodeSegListEntry
921 TInt GetSize() const;
924 Address of the start of the code segment.
928 Size of the code segment.
932 Size of the const data segment
934 TUint32 iConstDataSize;
936 Address of the initialised data
938 TUint32 iInitialisedDataBase;
940 Size of the initialised data
942 TUint32 iInitialisedDataSize;
944 Size of the uninitialised data
946 TUint32 iUninitialisedDataSize;
948 Boolean indicating whether the code segment is execute in place
952 Indicates whether the code segment is from an executable or a dll, or neither
954 TCodeSegType iCodeSegType;
955 /** Uid3 of this segment. */
957 /** Currently unused element. May be used in future to aid maintaining compatibility. */
960 Length of the code segment's name
964 First two bytes of the code segment's name, the name should be considered to
965 extend past the end of the TCodeSegListEntry structure to a length
966 corresponding to iNameLength
972 Returns the size of the TCodeSegListEntry, including the file name length
974 @return the size, in bytes, of the TCodeSegListEntry and the code segment's
977 inline TInt TCodeSegListEntry::GetSize() const
979 return sizeof(TCodeSegListEntry) - sizeof(iName) + (2 * iNameLength);
983 Structure used for extracting data from a descriptor returned by a call to
984 RSecuritySvrSession::GetList() when GetList() is called with TListId::EXipLibraries
985 as the first argument.
987 @see RSecuritySvrSession::GetList()
990 //buffer is a TDesC8 containing 4-byte aligned TXipLibraryListEntry objects
991 //create a pointer to the start of the data
992 TUint8* ptr = (TUint8*)buffer.Ptr();
993 //create a pointer to the end of the data
994 const TUint8* ptrEnd = ptr + buffer.Length();
997 //cast the pointer to be a TXipLibraryListEntry object
998 TXipLibraryListEntry& entry = *(TXipLibraryListEntry*)ptr;
999 //use the TXipLibraryListEntry pointer, i.e.
1000 TUint16 nameLength = entry.iNameLength;
1001 TPtr name(&(entry.iName[0]), nameLength, nameLength);
1002 // move ptr on to point to the next TXipLibraryListEntry object
1003 ptr += Align4(entry.GetSize());
1007 class TXipLibraryListEntry
1010 TInt GetSize() const;
1013 Address of the start of the library's code segment.
1017 Size of the code segment.
1021 Size of the const data segment
1023 TUint32 iConstDataSize;
1025 Address of the initialised data
1027 TUint32 iInitialisedDataBase;
1029 Size of the initialised data
1031 TUint32 iInitialisedDataSize;
1033 Size of the uninitialised data
1035 TUint32 iUninitialisedDataSize;
1036 /** Currently unused element. May be used in future to aid maintaining compatibility. */
1038 /** Currently unused element. May be used in future to aid maintaining compatibility. */
1041 Length of the library's name
1043 TUint16 iNameLength;
1045 First two bytes of the code segment's name, the name should be considered to
1046 extend past the end of the TXipLibraryListEntry structure to a length
1047 corresponding to iNameLength
1053 Returns the size of the TXipLibraryListEntry, including the file name length
1055 @return the size, in bytes, of the TXipLibraryListEntry and the library's
1058 inline TInt TXipLibraryListEntry::GetSize() const
1060 return sizeof(TXipLibraryListEntry) - sizeof(iName) + (2 * iNameLength);
1064 Structure used for extracting data from a descriptor returned by a call to
1065 RSecuritySvrSession::GetList() when GetList() is called with TListId::EExecutables
1066 as the first argument.
1068 @see RSecuritySvrSession::GetList()
1071 //buffer is a TDesC8 containing 4-byte aligned TExecutablesListEntry objects
1072 //create a pointer to the start of the data
1073 TUint8* ptr = (TUint8*)buffer.Ptr();
1074 //create a pointer to the end of the data
1075 const TUint8* ptrEnd = ptr + buffer.Length();
1078 //cast the pointer to be a TExecutablesListEntry object
1079 TExecutablesListEntry& entry = *(TExecutablesListEntry*)ptr;
1080 //use the TExecutablesListEntry pointer, i.e.
1081 TUint16 nameLength = entry.iNameLength;
1082 TPtr name(&(entry.iName[0]), nameLength, nameLength);
1083 // move ptr on to point to the next TExecutablesListEntry object
1084 ptr += Align4(entry.GetSize());
1088 class TExecutablesListEntry
1091 TInt GetSize() const;
1094 Indicates whether an agent has registered to actively debug the executable,
1095 a non-zero value indicates that an agent has attached.
1097 TUint8 iIsActivelyDebugged;
1099 Indicates whether any agents have registered to passively debug the executable,
1100 a non-zero value indicates that at least one agent is attached passively
1102 TUint8 iIsPassivelyDebugged;
1103 /** Currently unused element. May be used in future to aid maintaining compatibility. */
1105 /** Currently unused element. May be used in future to aid maintaining compatibility. */
1108 Length of the executable's name
1110 TUint16 iNameLength;
1112 First two bytes of the executable's name, the name should be considered to
1113 extend past the end of the TExecutablesListEntry structure to a length
1114 corresponding to iNameLength
1120 Returns the size of the TExecutablesListEntry, including the file name length
1122 @return the size, in bytes, of the TExecutablesListEntry and the executable's
1125 inline TInt TExecutablesListEntry::GetSize() const
1127 return sizeof(TExecutablesListEntry) - sizeof(iName) + (2*iNameLength);
1131 Structure used for extracting data from a descriptor returned by a call to
1132 RSecuritySvrSession::GetList() when GetList() is called with TListId::EProcesses
1133 as the first argument.
1135 @see RSecuritySvrSession::GetList()
1138 //buffer is a TDesC8 containing 4-byte aligned TProcessListEntry objects
1139 //create a pointer to the start of the data
1140 TUint8* ptr = (TUint8*)buffer.Ptr();
1141 //create a pointer to the end of the data
1142 const TUint8* ptrEnd = ptr + buffer.Length();
1145 //cast the pointer to be a TProcessListEntry object
1146 TProcessListEntry& entry = *(TProcessListEntry*)ptr;
1147 //use the TProcessListEntry pointer, i.e.
1148 TUint16 fileNameLength = entry.iFileNameLength;
1149 TPtr name(&(entry.iNames[0]), fileNameLength, fileNameLength);
1150 // move ptr on to point to the next TProcessListEntry object
1151 ptr += Align4(entry.GetSize());
1155 class TProcessListEntry
1158 TInt GetSize() const;
1164 /** The Uid3 of the process */
1168 * Process Attributes
1169 * @see DProcess::TProcessAttributes
1174 * Length of fully qualified file name of the process in bytes. Note that this
1175 * entry may be 0 if the process is in the process of shutting down.
1177 TUint16 iFileNameLength;
1180 * Length of current dynamic name of the process in bytes
1182 TUint16 iDynamicNameLength;
1185 * First two bytes of the process' file name, the name should be considered to
1186 * extend past the end of the TProcessListEntry structure to a length
1187 * corresponding to iFileNameLength. Directly after the data corresponding to the
1188 * file name, the dynamic name is stored with a length of iDynamicNameLength characters.
1189 * Note that these names are not null terminated and are concatenated directly after each other.
1192 * TProcessListEntry& entry; // entry is a reference to a TProcessListEntry
1194 * //get the file name..
1195 * TPtr fileName(&(entry.iNames[0]), iFileNameLength, iFileNameLength);
1197 * //get the dynamic name length..
1198 * TPtr dynamicName(&(entry.iNames[0]) + iFileNameLength, iDynamicNameLength, iDynamicNameLength);
1205 Returns the size of the TProcessListEntry, including the file name length and the
1208 @return the size, in bytes, of the TProcessListEntry and the executable's
1209 file name file name and dynamic name
1211 inline TInt TProcessListEntry::GetSize() const
1213 return sizeof(TProcessListEntry) - sizeof(iNames) + (2 * (iFileNameLength + iDynamicNameLength));
1217 Structure used for extracting data from a descriptor returned by a call to
1218 RSecuritySvrSession::GetList() when GetList() is called with TListId::EThreads
1219 as the first argument.
1221 @see RSecuritySvrSession::GetList()
1224 //buffer is a TDesC8 containing 4-byte aligned TThreadListEntry objects
1225 //create a pointer to the start of the data
1226 TUint8* ptr = (TUint8*)buffer.Ptr();
1227 //create a pointer to the end of the data
1228 const TUint8* ptrEnd = ptr + buffer.Length();
1231 //cast the pointer to be a TThreadListEntry object
1232 TThreadListEntry& entry = *(TThreadListEntry*)ptr;
1233 //use the TThreadListEntry pointer, i.e.
1234 TUint16 nameLength = entry.iNameLength;
1235 TPtr name(&(entry.iName[0]), nameLength, nameLength);
1236 // move ptr on to point to the next TThreadListEntry object
1237 ptr += Align4(entry.GetSize());
1241 class TThreadListEntry
1244 TInt GetSize() const;
1255 Address of the base of the supervisor stack
1257 TUint32 iSupervisorStackBase;
1259 Size of the supervisor stack
1261 TUint32 iSupervisorStackSize;
1263 Non-zero if iSupervisorStackBase has been set correctly
1265 TUint8 iSupervisorStackBaseValid;
1267 Non-zero if iSupervisorStackSize has been set correctly
1269 TUint8 iSupervisorStackSizeValid;
1271 Address of the thread's supervisor stack pointer
1273 TUint32 iSupervisorStackPtr;
1275 Indicator of whether the value returned as iSupervisorStackPtr is valid.
1276 It is necessary, but not necessarily sufficient, that the thread be suspended
1277 for a valid value to be returned. This may be removed from the final API and
1278 the value would be extracted instead via the ReadRegisters type calls.
1280 TRegisterFlag iSupervisorStackPtrValid;
1281 /** Currently unused element. May be used in future to aid maintaining compatibility. */
1283 /** Currently unused element. May be used in future to aid maintaining compatibility. */
1286 The length of the thread's name
1288 TUint16 iNameLength;
1290 First two bytes of the thread's name, the name should be considered to
1291 extend past the end of the TThreadListEntry structure to a length
1292 corresponding to iNameLength
1298 Returns the size of the TThreadListEntry, including the name length
1300 @return the size, in bytes, of the TExecutablesListEntry and the thread's name
1302 inline TInt TThreadListEntry::GetSize() const
1304 return sizeof(TThreadListEntry) - sizeof(iName) + (2 * iNameLength);
1308 Denotes which list type to return from a RSecuritySvrSession::GetList() call
1310 @see RSecuritySvrSession::GetList()
1315 Indicates that the GetList() call should return a list of the processes in
1316 the system. The returned buffer will contain an array of 4-byte aligned
1317 TProcessListEntry objects.
1319 @see TProcessListEntry
1323 Indicates that the GetList() call should return a list of the threads in
1324 the system. The returned buffer will contain an array of 4-byte aligned
1325 TThreadListEntry objects.
1327 @see TThreadListEntry
1331 Indicates that the GetList() call should return a list of the code segments in
1332 the system. The returned buffer will contain an array of 4-byte aligned
1333 TCodeSegListEntry objects.
1335 @see TCodeSegListEntry
1339 Indicates that the GetList() call should return a list of the XIP libraries in
1340 the system. The returned buffer will contain an array of 4-byte aligned
1341 EXipLibraries objects.
1347 Indicates that the GetList() call should return a list of the executables in
1348 the system. The returned buffer will contain an array of 4-byte aligned
1349 EExecutables objects.
1355 Indicates that the GetList() call should return a list of the logical devices in the system.
1357 ELogicalDevices = 5,
1359 Indicates that the GetList() call should return a list of the mutexes in the system.
1363 Indicates that the GetList() call should return a list of the servers in the system.
1367 Indicates that the GetList() call should return a list of the sessions in the system.
1371 Indicates that the GetList() call should return a list of the semaphores in the system.
1375 Indicates that the GetList() call should return a list of the chunks in the system.
1380 Provides a complete list of all the breakpoints in the system and their
1388 The following are for the possible use of kernel-side debug and SMP breakpoint
1396 * Provides static information of the system
1400 /** Last listing enum. */
1405 Bit field values denoting the scope of a listing.
1407 In the debug functionality block, the TTag::iValue element which is returned for a listing tag
1408 should be considered as a union of the supported values from this enumeration for that listing.
1412 EScopeNone = 0x0, /**< Corresponds to no scope for a listing. equivalent to not supported */
1413 EScopeGlobal= 0x1, /**< Corresponds to a global scope for a listing. */
1414 EScopeProcessSpecific = 0x2, /**< Corresponds to a process specific scope for a listing. */
1415 EScopeThreadSpecific = 0x4 /**< Corresponds to a thread specific scope for a listing. */
1421 Interface constructor for passing IPC data for the GetList call.
1426 TListDetails(const TListId aListId, const TListScope aListScope, TUint64 aTargetId=0)
1428 iListScope(aListScope),
1429 iTargetId(aTargetId) {}
1432 TListScope iListScope;
1436 /** Debug Security Server Secure ID */
1437 const TUid KUidDebugSecurityServer = { 0x102834E2 };
1439 } // end of Debug namespace declaration
1441 // the remaining functionality in this file is intended for use on user side only
1442 #ifndef __KERNEL_MODE__
1446 // API definition for Debug namespace appears elsewhere in this file.
1449 /** The name of the Debug Security Server. */
1450 _LIT(KSecurityServerName,"DebugSecurityServer");
1452 // A version must be specified when creating a session with the server
1453 /** The Debug Security Server's major version number. */
1454 const TUint KDebugServMajorVersionNumber=2;
1455 /** The Debug Security Server's minor version number. */
1456 const TUint KDebugServMinorVersionNumber=4;
1457 /** The Debug Security Server's patch version number. */
1458 const TUint KDebugServPatchVersionNumber=0;
1461 Denotes how memory should be accessed
1465 EAccess8 = 1, /**< Currently unsupported, signifies 8 bit access. */
1466 EAccess16 = 2, /**< Currently unsupported, signifies 16 bit access. */
1467 EAccess32 = 4 /**< Signifies 32 bit access. */
1471 Denotes how data should be interpreted
1475 EEndLE8 = 0, /**< Signifies 8 bit little-endian. */
1476 EEndBE8 = 1, /**< Currently unsupported, signifies 8 bit big-endian. */
1477 EEndBE32 = 2 /**< Currently unsupported, signifies 32 bit big-endian. */
1481 Structure used to store information about a memory operation
1489 TMemoryInfo(TUint32 aAddress=0, TUint32 aLength=0, TAccess aAccess=EAccess32, TEndianess aEndianess=EEndLE8)
1490 : iAddress(aAddress),
1493 iEndianess(aEndianess)
1499 Address to start reading/writing memory
1503 Number of bytes of memory to read/write
1507 Access size for read/write
1512 Endianess to interpret data as
1515 TEndianess iEndianess;
1525 TArchitectureMode iArchitectureMode;
1531 Function codes (opcodes) used in message passing between client and server
1532 in this header file and what arguments should be passed with each of these
1537 EDebugServClose = 2,
1538 EDebugServSuspendThread = 3,
1539 EDebugServResumeThread = 4,
1540 EDebugServReadMemory = 5,
1541 EDebugServWriteMemory = 6,
1542 EDebugServSetBreak = 7,
1543 EDebugServClearBreak = 8,
1544 EDebugServModifyBreak = 9,
1545 EDebugServGetEvent = 10,
1546 EDebugServCancelGetEvent = 11,
1547 EDebugServAttachExecutable = 12,
1548 EDebugServDetachExecutable = 13,
1549 EDebugServGetDebugFunctionalityBufSize = 14,
1550 EDebugServGetDebugFunctionality = 15,
1551 EDebugServReadRegisters = 16,
1552 EDebugServWriteRegisters = 17,
1553 EDebugServSetEventAction = 18,
1554 EDebugServBreakInfo = 19,
1555 EDebugServGetList = 20,
1556 EDebugServStep = 21,
1557 EDebugServSetProcessBreak = 22,
1558 EDebugServProcessBreakInfo = 23,
1559 EDebugServKillProcess = 24,
1560 EDebugServModifyProcessBreak = 25,
1561 EDebugServReadCrashFlash = 26,
1562 EDebugServWriteCrashFlash = 27,
1563 EDebugServEraseCrashFlash = 28,
1564 EDebugServEraseEntireCrashFlash = 29,
1568 Client side API to debug security server (DSS). Interaction with the DSS should
1569 be conducted through this class only.
1571 class RSecuritySvrSession : public RSessionBase
1574 RSecuritySvrSession();
1575 TVersion Version() const;
1579 TInt AttachExecutable(const TDesC& aProcessName, TBool aPassive);
1580 TInt DetachExecutable(const TDesC& aProcessName);
1582 TInt GetDebugFunctionalityBufSize(TUint32* aBufSize);
1583 TInt GetDebugFunctionality(TDes8& aBuffer);
1585 TInt SuspendThread(const TThreadId aThreadId);
1586 TInt ResumeThread(const TThreadId aThreadId);
1588 TInt ReadMemory(const TThreadId aThreadId, const TUint32 aAddress, const TUint32 aLength, TDes8 &aData, const TAccess aAccessSize, const TEndianess aEndianess);
1589 TInt WriteMemory(const TThreadId aThreadId, const TUint32 aAddress, const TUint32 aLength, const TDesC8 &aData, const TAccess aAccessSize, const TEndianess aEndianess);
1591 TInt ReadRegisters(const TThreadId aThreadId, const TDesC8& aRegisterIds, TDes8& aRegisterValues, TDes8& aRegisterFlags);
1592 TInt WriteRegisters(const TThreadId aThreadId, const TDesC8& aRegisterIds, const TDesC8& aRegisterValues, TDes8& aRegisterFlags);
1594 void GetEvent(const TDesC& aExecutableName, TRequestStatus &aStatus, TDes8& aEventInfo);
1595 TInt CancelGetEvent(const TDesC& aExecutableName);
1597 TInt SetEventAction(const TDesC& aExecutableName, TEventType aEvent, TKernelEventAction aEventAction);
1599 TInt SetBreak( TBreakId &aId, const TThreadId aThreadId, const TUint32 aAddress, const TArchitectureMode aArchitectureMode);
1600 TInt ClearBreak(const TBreakId aBreakId);
1601 TInt ModifyBreak(const TBreakId aBreakId, const TThreadId aThreadId, const TUint32 aAddress, const TArchitectureMode aArchitectureMode);
1602 TInt BreakInfo(const TBreakId aBreakId, TThreadId& aThreadId, TUint32& aAddress, TArchitectureMode& aMode);
1603 TInt SetProcessBreak( TBreakId &aId, const TProcessId aProcessId, const TUint32 aAddress, const TArchitectureMode aArchitectureMode);
1604 TInt ProcessBreakInfo(const TBreakId aBreakId, TProcessId& aProcessId, TUint32& aAddress, TArchitectureMode& aMode);
1605 TInt ModifyProcessBreak(const TBreakId aBreakId, const TProcessId aProcessId, const TUint32 aAddress, const TArchitectureMode aArchitectureMode);
1607 TInt GetList(const TListId aListId, TDes8& aListData, TUint32& aDataSize);
1608 TInt GetList(const TThreadId aThreadId, const TListId aListId, TDes8& aListData, TUint32& aDataSize);
1609 TInt GetList(const TProcessId aProcessId, const TListId aListId, TDes8& aListData, TUint32& aDataSize);
1610 TInt Step(const TThreadId aThreadId, TUint32 aNumSteps);
1611 TInt KillProcess(const TProcessId aProcessId, const TInt aReason);
1612 TInt ReadCrashLog(const TUint32 aPos, TDes8& aData, const TUint32 aDataSize);
1613 TInt WriteCrashConfig(const TUint32 aPos, const TDesC8& aBuffer, TUint32& aSize);
1614 TInt EraseCrashLog(const TUint32 aPos, const TUint32 aBlockNumber);
1615 TInt EraseCrashFlashPartition();
1617 TInt Connect(const TVersion aVersion);
1619 TInt StartServer(void);
1622 Server session constructor
1624 inline RSecuritySvrSession::RSecuritySvrSession()
1630 Called by a client to create a session with the DSS. This method starts the
1631 DSS if it is not running, or connects to it if it already exists.
1633 @param aVersion version of the DSS to connect to
1635 @return KErrNone if a connection was successfully created, or one of the other
1636 system wide error codes
1638 inline TInt RSecuritySvrSession::Connect(const TVersion aVersion)
1640 // default message slots for the server
1641 const TUint KDefaultMessageSlots = 4;
1645 TInt r=CreateSession(KSecurityServerName, aVersion, KDefaultMessageSlots);
1646 if (r!=KErrNotFound && r!=KErrServerTerminated)
1655 if (r!=KErrNone && r!=KErrAlreadyExists)
1665 @return KErrNone on success, or one of the other system wide error codes
1667 inline TInt RSecuritySvrSession::StartServer()
1669 // constants for the server
1670 _LIT(KSecurityServerProcessName, "rm_debug_svr");
1671 const TUidType serverUid(KNullUid, KNullUid, KUidDebugSecurityServer);
1674 TInt err = server.Create(KSecurityServerProcessName, KNullDesC, serverUid);
1681 // Synchronise with the process to make sure it hasn't died straight away
1682 TRequestStatus stat;
1683 server.Rendezvous(stat);
1684 if (stat != KRequestPending)
1686 // logon failed - server is not yet running, so cannot have terminated
1687 server.Kill(0); // Abort startup
1691 // logon OK - start the server
1695 // Wait to synchronise with server - if it dies in the meantime, it
1696 // also gets completed
1697 User::WaitForRequest(stat);
1699 // We can't use the 'exit reason' if the server panicked as this
1700 // is the panic 'reason' and may be '0' which cannot be distinguished
1702 err = (server.ExitType()==EExitPanic) ? KErrGeneral : stat.Int();
1708 Get version of RSecuritySvrSession
1710 @return a TVersion object specifying the version
1712 inline TVersion RSecuritySvrSession::Version(void) const
1714 return (TVersion(KDebugServMajorVersionNumber, KDebugServMinorVersionNumber, KDebugServPatchVersionNumber));
1718 Suspends execution of the specified thread.
1720 @param aThreadId thread ID of the thread to suspend
1722 @return KErrNone if there were no problems, KErrPermissionDenied if security
1723 check fails or KErrArgument if the thread does not exist
1725 inline TInt RSecuritySvrSession::SuspendThread(const TThreadId aThreadId)
1727 TPckgBuf<TThreadId> threadIdPckg(aThreadId);
1728 TIpcArgs args(&threadIdPckg);
1730 return SendReceive(EDebugServSuspendThread, args);
1734 Resumes execution of the specified thread.
1736 @param aThreadId thread ID of the thread to resume
1738 @return KErrNone if there were no problems, KErrPermissionDenied if security
1739 check fails or KErrArgument if the thread does not exist
1741 inline TInt RSecuritySvrSession::ResumeThread(const TThreadId aThreadId)
1743 TPckgBuf<TThreadId> threadIdPckg(aThreadId);
1744 TIpcArgs args(&threadIdPckg);
1746 return SendReceive(EDebugServResumeThread, args);
1751 Set a thread-specific breakpoint in an attached process.
1753 @pre Debug Agent must be connected to the debug security server
1754 @pre Debug Agent must be attached to a process.
1756 @param aThreadId The thread id to which the breakpoint will apply.
1757 @param aAddress The virtual memory address at which to place the breakpoint.
1758 @param aArchitectureMode The kind of breakpoint which is to be set (e.g. ARM/Thumb/Thumb2EE)
1759 @param aBreakId The address to which the assigned breakpoint ID will be written by this function
1760 @return Any error which may be returned by RSessionBase::SendReceive()
1762 inline TInt RSecuritySvrSession::SetBreak( TBreakId &aBreakId,const TThreadId aThreadId, const TUint32 aAddress, const TArchitectureMode aArchitectureMode)
1764 TPtr8 breakIdPtr((TUint8*)&aBreakId, sizeof(aBreakId));
1766 TPckgBuf<TThreadId> threadIdPckg(aThreadId);
1768 TBreakInfo breakInfo;
1769 breakInfo.iAddress = aAddress;
1770 breakInfo.iArchitectureMode = aArchitectureMode;
1771 TPckgBuf<TBreakInfo> breakInfoPckg(breakInfo);
1773 //call driver to attempt to set break
1774 TIpcArgs args(&threadIdPckg, &breakInfoPckg, &breakIdPtr);
1775 return SendReceive(EDebugServSetBreak, args);
1780 Clears a previously set thread-specific or process-specific breakpoint.
1782 @pre Debug Agent must be connected to the debug security server
1783 @pre Debug Agent must be attached to a process.
1785 @param aBreakId The TBreakId returned by a prior SetBreak call. Must have been set by the same Debug Agent.
1786 @return Any error which may be returned by RSessionBase::SendReceive()
1788 inline TInt RSecuritySvrSession::ClearBreak(const TBreakId aBreakId)
1790 TIpcArgs args(aBreakId);
1791 return SendReceive(EDebugServClearBreak, args);
1796 Modifies the properties of a previously set breakpoint.
1798 @pre Debug Agent must be connected to the debug security server
1799 @pre Debug Agent must be attached to a process.
1801 @param aBreakId the TBreakId returned by a prior SetBreak() call. Must have been set by the same Debug Agent.
1802 @param aThreadId the thread id of the thread to move the breakpoint to
1803 @param aAddress the virtual memory address at which to place the breakpoint.
1804 @param aArchitectureMode the kind of breakpoint which is to be set (e.g. ARM/Thumb/Thumb2EE)
1805 @return Any error which may be returned by RSessionBase::SendReceive()
1807 inline TInt RSecuritySvrSession::ModifyBreak(const TBreakId aBreakId, const TThreadId aThreadId, const TUint32 aAddress, const TArchitectureMode aArchitectureMode)
1810 TPckgBuf<TThreadId> threadIdPckg(aThreadId);
1811 TIpcArgs args(aBreakId,&threadIdPckg,aAddress,aArchitectureMode);
1812 return SendReceive(EDebugServModifyBreak, args);
1817 Modifies the properties of a previously set process breakpoint.
1819 @pre Debug Agent must be connected to the debug security server
1820 @pre Debug Agent must be attached to a process.
1822 @param aBreakId the TBreakId returned by a prior SetBreak() call. Must have been set by the same Debug Agent.
1823 @param aProcessId the process id of the process to move the breakpoint to
1824 @param aAddress the virtual memory address at which to place the breakpoint.
1825 @param aArchitectureMode the kind of breakpoint which is to be set (e.g. ARM/Thumb/Thumb2EE)
1826 @return Any error which may be returned by RSessionBase::SendReceive()
1828 inline TInt RSecuritySvrSession::ModifyProcessBreak(const TBreakId aBreakId, const TProcessId aProcessId, const TUint32 aAddress, const TArchitectureMode aArchitectureMode)
1831 TPckgBuf<TProcessId> processIdPckg(aProcessId);
1832 TIpcArgs args(aBreakId,&processIdPckg,aAddress,aArchitectureMode);
1833 return SendReceive(EDebugServModifyProcessBreak, args);
1838 Returns the properties associated with a given TBreakId. The supplied break id must previously have been allocated
1839 to the debug agent by a SetBreak() call.
1841 @pre Debug Agent must be connected to the debug security server
1842 @pre Debug Agent must be attached to a process.
1843 @pre The aBreakId must have been previously returned by a SetBreak() call and not subsequently cleared by ClearBreak().
1845 @param aBreakId the TBreakId returned by a prior SetBreak() call. Must have been set by the same Debug Agent.
1846 @param aAddress on return contains the virtual memory address of the breakpoint
1847 @param aThreadId on return contains the thread id of the thread that the breakpoint is set in
1848 @param aMode on return contains the type of this breakpoint (e.g. ARM/Thumb/Thumb2EE)
1849 @return Any error which may be returned by RSessionBase::SendReceive()
1851 inline TInt RSecuritySvrSession::BreakInfo(const TBreakId aBreakId, TThreadId& aThreadId, TUint32& aAddress, TArchitectureMode& aMode)
1853 // temporary descriptors
1854 TPtr8 threadId((TUint8*)&aThreadId,0,sizeof(TThreadId));
1855 TPtr8 address((TUint8*)&aAddress,0,sizeof(TUint32));
1856 TPtr8 mode((TUint8*)&aMode,0,sizeof(TArchitectureMode));
1858 TIpcArgs args(aBreakId,&threadId,&address,&mode);
1859 return SendReceive(EDebugServBreakInfo, args);
1864 Set a process-specific breakpoint in an attached process.
1866 @pre Debug Agent must be connected to the debug security server
1867 @pre Debug Agent must be attached to a process.
1869 @param aProcessId The process id to which the breakpoint will apply.
1870 @param aAddress The virtual memory address at which to place the breakpoint.
1871 @param aArchitectureMode The kind of breakpoint which is to be set (e.g. ARM/Thumb/Thumb2EE)
1872 @param aBreakId The address to which the assigned breakpoint ID will be written by this function
1873 @return Any error which may be returned by RSessionBase::SendReceive()
1875 inline TInt RSecuritySvrSession::SetProcessBreak( TBreakId &aBreakId, const TProcessId aProcessId, const TUint32 aAddress, const TArchitectureMode aArchitectureMode)
1877 TPtr8 breakIdPtr((TUint8*)&aBreakId, sizeof(aBreakId));
1879 TPckgBuf<TProcessId> threadIdPckg(aProcessId);
1881 TBreakInfo breakInfo;
1882 breakInfo.iAddress = aAddress;
1883 breakInfo.iArchitectureMode = aArchitectureMode;
1884 TPckgBuf<TBreakInfo> breakInfoPckg(breakInfo);
1886 //call driver to attempt to set break
1887 TIpcArgs args(&threadIdPckg, &breakInfoPckg, &breakIdPtr);
1888 return SendReceive(EDebugServSetProcessBreak, args);
1893 Returns the properties associated with a given TBreakId. The supplied break id must previously have been allocated
1894 to the debug agent by a SetProcessBreak() call.
1896 @pre Debug Agent must be connected to the debug security server
1897 @pre Debug Agent must be attached to a process.
1898 @pre The aBreakId must have been previously returned by a SetProcessBreak() call and not subsequently cleared by ClearBreak().
1900 @param aBreakId the TBreakId returned by a prior SetBreak() call. Must have been set by the same Debug Agent.
1901 @param aAddress on return contains the virtual memory address of the breakpoint
1902 @param aThreadId on return contains the thread id of the thread that the breakpoint is set in
1903 @param aMode on return contains the type of this breakpoint (e.g. ARM/Thumb/Thumb2EE)
1904 @return Any error which may be returned by RSessionBase::SendReceive()
1906 inline TInt RSecuritySvrSession::ProcessBreakInfo(const TBreakId aBreakId, TProcessId& aProcessId, TUint32& aAddress, TArchitectureMode& aMode)
1908 // temporary descriptors
1909 TPtr8 processId((TUint8*)&aProcessId,0,sizeof(TProcessId));
1910 TPtr8 address((TUint8*)&aAddress,0,sizeof(TUint32));
1911 TPtr8 mode((TUint8*)&aMode,0,sizeof(TArchitectureMode));
1913 TIpcArgs args(aBreakId,&processId,&address,&mode);
1914 return SendReceive(EDebugServProcessBreakInfo, args);
1919 Wait for an event to occur to the target executable being debugged. When an event
1920 occurs, the TRequestStatus is changed from KRequestPending.
1922 @pre Debug Agent must be connected to the debug security server
1923 @pre Debug Agent must be attached to a process.
1925 Note 1: Events are reported on a per-executable basis, not per-thread.
1927 Note 2: All the parameters must remain in scope until either CancelGetEvent is called, or
1928 until TRequestStatus is changed from KRequestPending. In practice, this generally
1929 means these parameters should not be based on the stack, as they may go out of
1930 scope before the call completes.
1932 Note 3: TIpcArgs args is allocated on the stack within this function, however,
1933 all the data containing in args is transferred in the SendReceive() so it can safely
1934 go out of scope after the call has been made.
1936 @param aExecutableName The name of any executable to which the Debug Agent is attached.
1937 @param aStatus Debug Agent request status variable.
1938 @param aEventInfo Descriptor containing a buffer sufficient for Event information.
1939 @return Any error which may be returned by RSessionBase::SendReceive()
1941 inline void RSecuritySvrSession::GetEvent(const TDesC& aExecutableName, TRequestStatus &aStatus, TDes8& aEventInfo)
1943 TIpcArgs args(&aExecutableName, &aEventInfo);
1945 SendReceive(EDebugServGetEvent, args, aStatus );
1951 Cancel a previously issued asynchronous RSecuritySvrSession::GetEvent call. The previously
1952 issued call will immediately complete with the TRequestStatus = KErrCancel
1954 @pre Debug Agent must be connected to the debug security server
1955 @pre Debug Agent must be attached to the process specified by aProcessName
1956 @pre Debug Agent must have previously issued an RSecuritySvrSession::GetEvent() call.
1958 @param aExecutableName The name of the executable being debugged.
1959 @return Any error which may be returned by RSessionBase::SendReceive()
1961 inline TInt RSecuritySvrSession::CancelGetEvent(const TDesC& aExecutableName)
1963 TIpcArgs args(&aExecutableName);
1965 return SendReceive(EDebugServCancelGetEvent,args);
1969 Called by a debug agent to request debug privileges for the executable with
1970 file name aExecutableName.
1972 @param aExecutableName a fully qualified file name of the executable to attach to
1973 @param aPassive if true then the agent has reduced debug rights.
1975 @return KErrNone if attached successfully, one of the other system wide error
1978 inline TInt RSecuritySvrSession::AttachExecutable(const TDesC& aExecutableName, TBool aPassive)
1980 TIpcArgs args((TInt)aPassive, &aExecutableName);
1981 return SendReceive(EDebugServAttachExecutable, args);
1985 Called by a debug agent to detach from the executable with file
1986 name aExecutableName.
1988 @param aExecutableName the fully qualified file name of the executable to detach from
1990 @return KErrNone if detached successfully, one of the other system wide error
1993 inline TInt RSecuritySvrSession::DetachExecutable(const TDesC& aExecutableName)
1995 TIpcArgs args(&aExecutableName);
1996 return SendReceive(EDebugServDetachExecutable, args);
2000 Close the session and thread
2002 @return KErrNone if the session is closed successfully, otherwise one of the system wide errors.
2004 inline TInt RSecuritySvrSession::Close()
2006 RSessionBase::Close();
2011 Get buffer size required to contain Functionality text block.
2013 @see in-source documentation in rm_debug_api.h
2015 @param aBufSize function will fill this with the required buffer size
2017 @return KErrNone if the call succeeded, or one of the other system wide error
2018 codes if the call failed
2020 inline TInt RSecuritySvrSession::GetDebugFunctionalityBufSize(TUint32 *aBufSize)
2022 TInt res = KErrNone;
2024 TPtr8 stuff((TUint8*)aBufSize,4, 4);
2026 TIpcArgs args(&stuff);
2028 res = SendReceive(EDebugServGetDebugFunctionalityBufSize, args);
2034 Get debug functionality text block and place it into aBuffer.
2036 The debug functionality block (DFBlock) is used to provide information about the functionality
2037 (i.e. features) which are supported by the rm_debug.ldd device driver.
2039 Calling this function with a suitably sized buffer aBuffer will result in the debug
2040 functionality information being stored in aBuffer. The necessary size of aBuffer can
2041 be determined by calling DebugFunctionalityBufSize().
2043 The format of the DFBlock is:
2052 The data which will be returned by a call to GetDebugFunctionality() is constant so is
2053 guaranteed to fit exactly into the aBuffer allocated, assuming that the size of aBuffer
2054 corresponds to the value returned from GetDebugFunctionalityBufSize().
2056 Each sub-block is composed of a TTagHeader object followed by a C-style array of TTag objects.
2057 The sub-block contains information about a particular aspect of the debug sub-system, for example
2058 information about the manner in which memory can be accessed.
2059 The TTagHeader is comprised of an identifier which determines the type of data
2060 it contains, together with the number of TTag elements in the array following the TTagHeader.
2061 Each TTag in a sub-block has a unique ID, stored in the TTag::iTagId member variable.
2063 The only sub-block that is guaranteed to exist has TTagHeader::iTagHdrId = ETagHeaderIdCore, all other
2064 sub-blocks are optional. The ETagHeaderIdCore sub-block is the first sub-block within the DFBlock.
2065 Other sub-blocks may appear in any order after the ETagHeaderIdCore sub-block.
2067 The following is a diagrammatic representation of a sub-block the DFBlock:
2070 The HHHH represents the tag header ID of a sub-block (TTagHeader::iTagHdrId)
2071 The NNNN represents the number of TTag elements in the sub-block (TTagHeader::iNumTags)
2072 The IIIIIIII represents the ID of the TTag (TTag::iTagId)
2073 The TTTT represents the type of the TTag (TTag::iType)
2074 The SSSS represents the size of the TTag's associated data (TTag::iSize)
2075 The VVVVVVVV represents the TTag's value (TTag::iValue)
2077 0xNNNNHHHH TTagHeader element for first sub-block (has N1 TTag elements)
2079 0xSSSSTTTT -- TTag 0
2082 0xSSSSTTTT -- TTag 1
2086 0xSSSSTTTT -- TTag N1 - 1
2088 0xNNNNHHHH TTagHeader element for second sub-block (has N2 TTag elements)
2090 0xSSSSTTTT -- TTag 0
2094 0xSSSSTTTT -- TTag N2 - 1
2097 0xNNNNHHHH TTagHeader element for last sub-block (has NX TTag elements)
2099 0xSSSSTTTT -- TTag 0
2103 0xSSSSTTTT -- TTag NX - 1
2107 The following example DFBlock contains two sub-blocks (values taken from enums below):
2109 - ETagHeaderIdMemory
2112 Binary Meaning Value
2114 0x000A0000 iTagHdrId, iNumTags ETagHeaderIdCore, ECoreLast
2115 0x00000000 iTagId ECoreEvents
2116 0x00000000 iType, iSize ETagTypeBoolean, 0
2117 0x00000001 iValue ETrue
2118 0x00000001 iTagId ECoreStartStop
2119 0x00000000 iType, iSize ETagTypeBoolean, 0
2120 0x00000001 iValue ETrue
2122 0x00000008 iTagId ECoreHardware
2123 0x00000000 iType, iSize ETagTypeBoolean, 0
2124 0x00000000 iValue EFalse
2125 0x00000009 iTagId ECoreApiConstants
2126 0x00000000 iType, iSize ETagTypeBoolean, 0
2127 0x00000001 iValue ETrue
2129 0x000A0001 iTagHdrId, iNumTags ETagHeaderIdMemory, EMemoryLast
2130 0x00000000 iTagId EMemoryRead
2131 0x00000000 iType, iSize ETagTypeBoolean, 0
2132 0x00000001 iValue ETrue
2133 0x00000001 iTagId EMemoryWrite
2134 0x00000000 iType, iSize ETagTypeBoolean, 0
2135 0x00000001 iValue ETrue
2137 0x00000008 iTagId EMemoryLE8
2138 0x00000000 iType, iSize ETagTypeBoolean, 0
2139 0x00000001 iValue ETrue
2140 0x00000009 iTagId EMemoryMaxBlockSize
2141 0x00000001 iType, iSize ETagTypeTUint32, 0
2142 0x00004000 iValue 0x4000
2145 - Debug Agent DFBlock Processing:
2147 Debug Agents MUST understand and process the ETagHeaderIdCore block. The other
2148 blocks may be ignored if not recognised. Tags within each block may be ignored if
2151 @pre aBuffer.MaxLength() >= *aBufSize where aBufSize is set by a call to:
2152 RSecuritySvrSession::GetDebugFunctionalityBufSize(TUint32 *aBufSize)
2154 @param aBuffer buffer to store functionality block in
2156 @return KErrNone if call succeeded,
2157 KErrNoMemory if temporary memory could not be allocated,
2158 KErrGeneral if debug functionality block could not be accessed
2160 inline TInt RSecuritySvrSession::GetDebugFunctionality(TDes8& aBuffer)
2162 TIpcArgs args(&aBuffer);
2164 TInt res = KErrNone;
2166 res = SendReceive(EDebugServGetDebugFunctionality, args);
2172 Read a block of memory from the target debug thread defined by aThreadId.
2174 @pre the client should attach to the process containing the target thread
2175 @pre aData.MaxLength() >= aLength
2177 @param aThreadId thread ID of the thread to read memory from
2178 @param aAddress address to start reading memory from
2179 @param aLength number of bytes of memory to read
2180 @param aData descriptor to read memory into
2181 @param aAccessSize access size for memory reads, default is TAccess::EAccess32
2182 @param aEndianess interpretation of endianess of target data, default is
2185 @return KErrNone if memory read successfully, or one of the other system wide error codes
2187 inline TInt RSecuritySvrSession::ReadMemory(const TThreadId aThreadId, const TUint32 aAddress, const TUint32 aLength, TDes8 &aData, const TAccess aAccessSize, const TEndianess aEndianess)
2189 TPckgBuf<TThreadId> threadIdPckg(aThreadId);
2190 //set up memory info object
2191 TMemoryInfo memoryInfo;
2192 memoryInfo.iAddress = aAddress;
2193 memoryInfo.iSize = aLength;
2194 memoryInfo.iAccess = aAccessSize;
2195 memoryInfo.iEndianess = aEndianess;
2197 TPckgBuf<TMemoryInfo> pckg(memoryInfo);
2199 TIpcArgs args(&threadIdPckg, &pckg, &aData);
2201 return SendReceive(EDebugServReadMemory, args);
2205 Write a block of memory to the target debug thread defined by aThreadId.
2207 @pre the client should attach non-passively to the process containing the
2210 @param aThreadId thread ID of the thread to write memory to
2211 @param aAddress address to start writing memory at
2212 @param aLength number of bytes of memory to write
2213 @param aData descriptor to read memory from
2214 @param aAccessSize access size for memory writes, default is TAccess::EAccess32
2215 @param aEndianess interpretation of endianess of target data, default is
2218 @return KErrNone if memory written successfully, or one of the other system wide error codes
2220 inline TInt RSecuritySvrSession::WriteMemory(const TThreadId aThreadId, const TUint32 aAddress, const TUint32 aLength, const TDesC8 &aData, const TAccess aAccessSize, const TEndianess aEndianess)
2222 TPckgBuf<TThreadId> threadIdPckg(aThreadId);
2223 //create memory info object
2224 TMemoryInfo memoryInfo;
2225 memoryInfo.iAddress = aAddress;
2226 memoryInfo.iSize = aLength;
2227 memoryInfo.iAccess = aAccessSize;
2228 memoryInfo.iEndianess = aEndianess;
2230 TPckgBuf<TMemoryInfo> pckg(memoryInfo);
2232 TIpcArgs args(&threadIdPckg, &pckg, &aData);
2234 return SendReceive(EDebugServWriteMemory, args);
2238 Read register values from the thread with thread ID aThreadId. The IDs of the
2239 registers to read are stored as an array of TRegisterInfo objects in
2240 aRegisterIds. If the nth register requested could be read then the value of the
2241 register will be appended to aRegisterValues and EValid stored at
2242 offset n in aRegisterFlags. If the register is supported but could not be read
2243 then EInValid will be stored at offset n in aRegisterFlags and arbitrary data
2244 appended in aRegisterValues. If reading the specified register is not
2245 supported by the kernel then ENotSupported will be stored at offset n in
2246 aRegisterFlags and arbitrary data appended to aRegisterValues. If an unknown
2247 register is specified then EUnknown will be put in aRegisterFlags and
2248 arbitrary data placed in aRegisterValues.
2250 @pre the client should attach to the process containing the target thread
2252 @see the register ID format is defined in:
2253 SGL.TS0028.027 - Symbian Core Dump File Format v1.0.doc
2255 @param aThreadId thread ID of the thread to read register values from
2256 @param aRegisterIds descriptor containing array of TFunctionalityRegister defined
2258 @param aRegisterValues descriptor to contain register values
2259 @param aRegisterFlags descriptor containing array of TUint8 flags, with values
2260 taken from TRegisterFlag
2262 @return KErrNone if registers were read successfully, or one of the other system wide error codes
2264 inline TInt RSecuritySvrSession::ReadRegisters(const TThreadId aThreadId, const TDesC8& aRegisterIds, TDes8& aRegisterValues, TDes8& aRegisterFlags)
2266 TPckgBuf<TThreadId> threadIdPckg(aThreadId);
2267 TIpcArgs args(&threadIdPckg, &aRegisterIds, &aRegisterValues, &aRegisterFlags);
2269 return SendReceive(EDebugServReadRegisters, args);
2273 Write register values to the thread with thread ID aThreadId. The IDs of the
2274 registers to write are stored as an array of TRegisterInfo objects in
2275 aRegisterIds. The values to put in the registers are stored as an array of
2276 objects in aRegisterValues. If the nth register to write could be
2277 written then EValid stored at offset n in aRegisterFlags. If the register is
2278 supported but could not be written then EInValid will be stored at offset n in
2279 aRegisterFlags. If writing to the specified register is not supported by the
2280 kernel then ENotSupported will be stored at offset n in aRegisterFlags. If an
2281 unknown register is specified then EUnknown will be put in aRegisterFlags.
2283 @pre the client should attach non-passively to the process containing the
2286 @see the register ID format is defined in:
2287 SGL.TS0028.027 - Symbian Core Dump File Format v1.0.doc
2289 @param aThreadId thread ID of the thread to write register values to
2290 @param aRegisterIds descriptor containing array of TFunctionalityRegister defined
2292 @param aRegisterValues descriptor containing array of register values
2293 @param aRegisterFlags descriptor containing array of TUint8 flags, with values
2294 taken from TRegisterFlag
2296 @return KErrNone if registers were written successfully, or one of the other system wide error codes
2298 inline TInt RSecuritySvrSession::WriteRegisters(const TThreadId aThreadId, const TDesC8& aRegisterIds, const TDesC8& aRegisterValues, TDes8& aRegisterFlags)
2300 TPckgBuf<TThreadId> threadIdPckg(aThreadId);
2301 TIpcArgs args(&threadIdPckg, &aRegisterIds, &aRegisterValues, &aRegisterFlags);
2303 return SendReceive(EDebugServWriteRegisters, args);
2308 Set the requisite actions to be taken when a particular event occurs.
2309 The events are defined in Debug::TEventType and the
2310 actions are defined in Debug::TKernelEventAction.
2312 The default action for all events is EActionIgnore.
2314 @pre Debug Agent must be connected to the debug security server
2315 @pre Debug Agent must be attached to the executable specified by aExecutableName.
2317 Note: Event actions are on a per-executable basis. This is
2318 to ensure that events such as EEventStartThread are notified to the Debug
2319 Agent, even though the debug agent cannot be aware of the existence
2320 of a new thread at the time the event occurs.
2322 @param aExecutableName The name of the executable to which the Debug Agent is attached.
2323 @param aEvent A TEventType enum defined in rm_debug_api.h:Debug::TEventType
2324 @param aEventAction Any TKernelEventAction permitted by the DFBlock.
2325 @return Any error which may be returned by RSessionBase::SendReceive()
2327 inline TInt RSecuritySvrSession::SetEventAction(const TDesC& aExecutableName, TEventType aEvent, TKernelEventAction aEventAction)
2329 TInt res = KErrNone;
2331 TIpcArgs args(&aExecutableName,aEvent,aEventAction);
2333 res = SendReceive(EDebugServSetEventAction, args);
2339 Returns a global listing corresponding to the type specified as aListId. The structure
2340 of the returned data depends on the value of aListId, see TListId for details.
2341 If aListData is not large enough to contain the listings data then
2342 the necessary buffer size is stored in aDataSize and the function returns
2343 KErrTooBig. In this case the contents of aListData will not contain useful data.
2345 Note that if the aListData buffer was too small to hold the data then the value
2346 returned as aDataSize corresponds to the size of the data at that particular
2347 instance. The size of the data will vary over time, for example the thread list
2348 will increase and decrease in size as threads are created and destroyed, so
2349 re-requesting data with a buffer with max length aDataSize will not necessarily
2350 succeed if a list has increased in size between the two calls.
2354 @param aListId enum from TListId signifying which type of listing to return
2355 @param aListData buffer provided by the debug agent in which data can be returned by the debug system
2356 @param aDataSize if aListData was not large enough to contain the requested
2357 data then the necessary buffer size is stored in aDataSize. If aListData
2358 was large enough then the value of aDataSize is the length of aListData
2360 @return KErrNone if data was returned successfully,
2361 KErrTooBig if aListData is too small to hold the data,
2362 one of the other system-wide error codes
2364 inline TInt RSecuritySvrSession::GetList(const TListId aListId, TDes8& aListData, TUint32& aDataSize)
2366 //second argument of ETrue implies a global listing
2367 TListDetails info(aListId, EScopeGlobal);
2368 TPtr8 infoBuf((TUint8*)&info, sizeof(TListDetails), sizeof(TListDetails));
2369 TPtr8 dataSizeBuf((TUint8*)&aDataSize, sizeof(TUint32), sizeof(TUint32));
2370 TIpcArgs args(&infoBuf, &aListData, &dataSizeBuf);
2371 return SendReceive(EDebugServGetList, args);
2375 Returns a thread-specific listing corresponding to the type specified as aListId. The structure
2376 of the returned data depends on the value of aListId, see TListId for details.
2377 If aListData is not large enough to contain the listings data then
2378 the necessary buffer size is stored in aDataSize and the function returns
2379 KErrTooBig. In this case the contents of aListData will not contain useful data.
2381 Note that if the aListData buffer is too small to hold the data then the value
2382 returned as aDataSize corresponds to the size of the data at that particular
2383 instant. The size of the data will vary over time, for example the thread list
2384 will increase and decrease in size as threads are created and destroyed, so
2385 re-requesting data with a buffer with max length aDataSize will not necessarily
2386 succeed if a list has increased in size between the two calls.
2390 @param aThreadId thread to return the listing for
2391 @param aListId member of TListId signifying which type of listing to return
2392 @param aListData buffer provided by the debug agent in which data can be returned by the debug system.
2393 @param aDataSize if aListData was not large enough to contain the requested
2394 data then the necessary buffer size is stored in aDataSize. If aListData
2395 was large enough then the value of aDataSize is the length of aListData
2397 @return KErrNone if data was returned successfully,
2398 KErrTooBig if aListData is too small to hold the data,
2399 one of the other system-wide error codes
2401 inline TInt RSecuritySvrSession::GetList(const TThreadId aThreadId, const TListId aListId, TDes8& aListData, TUint32& aDataSize)
2403 TListDetails info(aListId, EScopeThreadSpecific, aThreadId.Id());
2404 TPtr8 infoBuf((TUint8*)&info, sizeof(TListDetails), sizeof(TListDetails));
2405 TPtr8 dataSizeBuf((TUint8*)&aDataSize, sizeof(TUint32), sizeof(TUint32));
2406 TIpcArgs args(&infoBuf, &aListData, &dataSizeBuf);
2407 return SendReceive(EDebugServGetList, args);
2411 Returns a process-specific listing corresponding to the type specified as aListId. The structure
2412 of the returned data depends on the value of aListId, see TListId for details.
2413 If aListData is not large enough to contain the listings data then
2414 the necessary buffer size is stored in aDataSize and the function returns
2415 KErrTooBig. In this case the contents of aListData will not contain useful data.
2417 Note that if the aListData buffer is too small to hold the data then the value
2418 returned as aDataSize corresponds to the size of the data at that particular
2419 instant. The size of the data will vary over time, for example the thread list
2420 will increase and decrease in size as threads are created and destroyed, so
2421 re-requesting data with a buffer with max length aDataSize will not necessarily
2422 succeed if a list has increased in size between the two calls.
2426 @param aProcessId process to return the listing for
2427 @param aListId member of TListId signifying which type of listing to return
2428 @param aListData buffer provided by the debug agent in which data can be returned by the debug system.
2429 @param aDataSize if aListData was not large enough to contain the requested
2430 data then the necessary buffer size is stored in aDataSize. If aListData
2431 was large enough then the value of aDataSize is the length of aListData
2433 @return KErrNone if data was returned successfully,
2434 KErrTooBig if aListData is too small to hold the data,
2435 one of the other system-wide error codes
2437 inline TInt RSecuritySvrSession::GetList(const TProcessId aProcessId, const TListId aListId, TDes8& aListData, TUint32& aDataSize)
2439 TListDetails info(aListId, EScopeProcessSpecific, aProcessId.Id());
2440 TPtr8 infoBuf((TUint8*)&info, sizeof(TListDetails), sizeof(TListDetails));
2441 TPtr8 dataSizeBuf((TUint8*)&aDataSize, sizeof(TUint32), sizeof(TUint32));
2442 TIpcArgs args(&infoBuf, &aListData, &dataSizeBuf);
2443 return SendReceive(EDebugServGetList, args);
2448 Step one or more CPU instructions in the specified thread from the current PC.
2450 @pre Debug Agent must be connected to the debug security server
2451 @pre Debug Agent must be attached to a process.
2452 @pre The thread being stepped must be suspended by the Debug Agent.
2454 @param aThreadId the id of the thread which is to be stepped
2455 @param aNumSteps how many machine-level instructions are to be stepped.
2456 @return Any error which may be returned by RSessionBase::SendReceive()
2458 inline TInt RSecuritySvrSession::Step(const TThreadId aThreadId, const TUint32 aNumSteps)
2460 TPckgBuf<TThreadId> threadIdPckg(aThreadId);
2461 TInt res = KErrNone;
2463 TIpcArgs args(&threadIdPckg,aNumSteps);
2465 res = SendReceive(EDebugServStep,args);
2472 Kill the specified process with the supplied reason. Reason codes are equivalent
2473 to those in RProcess.Kill().
2475 @pre Debug Agent must be connected to the debug security server
2476 @pre Debug Agent must be attached to a process.
2478 @param aProcessId the id of the process which is to be killed
2479 @param aReason The reason to be associated with the ending of this process
2480 @return Any error which may be returned by RSessionBase::SendReceive()
2482 inline TInt RSecuritySvrSession::KillProcess(const TProcessId aProcessId, const TInt aReason)
2484 TPckgBuf<TProcessId> processIdPckg(aProcessId);
2485 TInt res = KErrNone;
2487 TIpcArgs args(&processIdPckg,aReason);
2489 res = SendReceive(EDebugServKillProcess,args);
2496 Method to read data from the crash flash
2498 @pre aData buffer to retrieve the data from the crash flash
2499 @pre aDataSize Size of the data
2501 @return Any error which may be returned by RSessionBase::SendReceive()
2503 inline TInt RSecuritySvrSession::ReadCrashLog(const TUint32 aPos, TDes8& aData, const TUint32 aDataSize)
2505 TIpcArgs args(aPos, &aData, aDataSize);
2506 TInt res = SendReceive(EDebugServReadCrashFlash,args);
2511 * @internalTechnology
2515 Method to write the crash flash config
2517 @return Any error which may be returned by RSessionBase::SendReceive()
2519 inline TInt RSecuritySvrSession::WriteCrashConfig(const TUint32 aPos, const TDesC8& aBuffer, TUint32& aSize)
2521 TPtr8 sizePtr((TUint8*)&aSize,4, 4);
2522 TIpcArgs args(aPos, &aBuffer, &sizePtr);
2523 TInt res = SendReceive(EDebugServWriteCrashFlash, args);
2528 Method to erase a block in the crash flash
2530 @return Any error which may be returned by RSessionBase::SendReceive()
2532 inline TInt RSecuritySvrSession::EraseCrashLog(const TUint32 aPos, const TUint32 aBlockNumber)
2534 TIpcArgs args(aPos, aBlockNumber);
2535 TInt res = SendReceive(EDebugServEraseCrashFlash, args);
2541 Method to erase entire flash partition
2543 @return Any error which may be returned by RSessionBase::SendReceive()
2545 inline TInt RSecuritySvrSession::EraseCrashFlashPartition()
2547 TInt res = SendReceive(EDebugServEraseEntireCrashFlash);
2551 } // end of Debug namespace declaration
2553 #endif // #ifndef __KERNEL_MODE__
2555 #endif // RM_DEBUG_API_H