CodeWarrior Kernel-Aware Debug API Revised: 17 October 2006
Freescale and the Freescale logo are trademarks of Freescale Semiconductor, Inc. CodeWarrior is a trademark or registered trademark of Freescale Semiconductor, Inc. in the United States and/or other countries. All other product or service names are the property of their respective owners. Copyright 2003-2006 by Freescale Semiconductor, Inc. All rights reserved. Information in this document is provided solely to enable system and software implementers to use Freescale Semiconductor products. There are no express or implied copyright licenses granted hereunder to design or fabricate any integrated circuits or integrated circuits based on the information in this document. Freescale Semiconductor reserves the right to make changes without further notice to any products herein. Freescale Semiconductor makes no warranty, representation or guarantee regarding the suitability of its products for any particular purpose, nor does Freescale Semiconductor assume any liability arising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation consequential or incidental damages. Typical parameters that may be provided in Freescale Semiconductor data sheets and/or specifications can and do vary in different applications and actual performance may vary over time. All operating parameters, including Typicals, must be validated for each customer application by customer's technical experts. Freescale Semiconductor does not convey any license under its patent rights nor the rights of others. Freescale Semiconductor products are not designed, intended, or authorized for use as components in systems intended for surgical implant into the body, or other applications intended to support or sustain life, or for any other application in which the failure of the Freescale Semiconductor product could create a situation where personal injury or death may occur. Should Buyer purchase or use Freescale Semiconductor products for any such unintended or unauthorized application, Buyer shall indemnify and hold Freescale Semiconductor and its officers, employees, subsidiaries, affiliates, and distributors harmless against all claims, costs, damages, and expenses, and reasonable attorney fees arising out of, directly or indirectly, any claim of personal injury or death associated with such unintended or unauthorized use, even if such claim alleges that Freescale Semiconductor was negligent regarding the design or manufacture of the part. How to Contact Us Corporate Headquarters World Wide Web Technical Support Freescale Semiconductor, Inc. 7700 West Parmer Lane Austin, TX 78729 U.S.A. http://www.freescale.com/codewarrior http://www.freescale.com/support
Table of Contents 1 5 Overview.................................. 5 Using the................................... 5................................ 6 GetCurrentThread.............................................. 7 GetProcesses.................................................. 7 GetProcessInformation.......................................... 8 GetProcessThreads............................................. 8 GetThreadInformation........................................... 9 HasFeature................................................... 10 InstallNubMenu............................................... 11 NotifyAboutToRun............................................ 11 NotifyReturnFromRun......................................... 12 NotifyShutDown.............................................. 12 ProcessExists................................................. 13 ReadThreadRegisters.......................................... 13 WriteThreadRegisters.......................................... 14 IMWKernelAware2 Interface Reference.............................. 15 ThreadHasCurrentRegisterSet.................................... 15 Index 17 CodeWarrior 3
Table of Contents 4 CodeWarrior
1 This chapter shows how to use the Microsoft Component Object Model (COM) API for kernel-aware debugging plug-ins for the CodeWarrior IDE. This document is intended for third party RTOS (Real-Time Operating System) vendors interested in developing kernel-aware debugging support for the CodeWarrior IDE s debugger. This chapter contains the following sections: Overview Using the IMWKernelAware2 Interface Reference Overview The IDE s debugger uses a kernel-aware debugger plug-in to retrieve information about and control a remote embedded system (typically a development board). A kernel-aware debugging plug-in is implemented as a COM object running under the Microsoft Win32/ x86 runtime environment. The methods in a kernel-aware plug-in are called directly from a debugger plug-in; a kernel-aware plug-in is never called directly by the IDE s debugger. A kernel-aware plugin does not (typically) communicate directly to the target board's debug monitor (or hardware debug device). Instead, it uses the IMWPluginNub interface to get information from a development board. The kernel-aware plug-in then formats this information into the form expected by the IDE s debugger plug-in. Using the There are two interfaces: IMWKernelAware and IMWKernelAware2. The IMWKernelAware interface is derived from the interface for the IMWDebuggerPlugin class, so kernel-aware plug-ins must implement the same RegisterServices() function as the debugger plug-ins. IMWKernelAware2 is a separate interface containing only one method. CodeWarrior 5
Also, the IMWKernelAware interface uses COM (Component Object Model), so kernel-aware plug-ins must implement AddRef(), Release(), and QueryInterface(). A kernel-aware plug-in should export the same function as the debugger plug-ins: DebuggerPluginEntryName. Finally, a kernel-aware plug-in should also export: GetIMWKernelAwareName(char* registedname) GetIMWKernelAwareName() should return the plug-in s unique registered name. TIP For related information on implementing a kernel-aware debugging plug-in, refer to the DebuggerInterface.h head file. This section lists the methods you implement to create a kernel-aware debugging plug-in. Each method s topic has a short description, a prototype to show you its arguments, additional remarks about the method, and a list of related topics. The topics in this section are: GetCurrentThread GetProcesses GetProcessInformation GetProcessThreads GetThreadInformation HasFeature InstallNubMenu NotifyAboutToRun NotifyReturnFromRun NotifyShutDown ProcessExists ReadThreadRegisters WriteThreadRegisters 6 CodeWarrior
GetCurrentThread Retrieves the ID of the thread that is currently running. STDMETHOD_(IMWDebugError*, GetCurrentThread)( IMWProcess* processptr, MWThreadID &threadid ) = 0; This method retrieves the ID of the thread that is currently running on the target machine. When called, processptr, a pointer to an object of type IMWProcess, refers to the process for which GetCurrentThread() must retrieve the currently running thread. On return, GetCurrentThread() stores the ID of the currently running thread in threadid. GetProcesses on page 7 GetProcessThreads on page 8 GetThreadInformation on page 9 GetProcesses Returns the processes running on a target machine. STDMETHOD_(IMWDebugError*, GetProcesses)( IMWMachine* machineptr, ProcessID* processidbuffer, long& count, long next) = 0; This method retrieves the IDs of processes running on a target machine. When called, machineptr argument points to the target machine for which GetProcess() must return process IDs. The processidbuffer argument is an array of type ProcessID in which GetProcess() must store process IDs. The debugger allocates 1000 elements for this array. The next argument refers to the element at which to begin storing process IDs in the processidbuffer array. CodeWarrior 7
On return, GetProcess() stores the number of process IDs stored in processidbuffer and returns an error result. GetProcessInformation on page 8 GetProcessThreads on page 8 GetCurrentThread on page 7 GetProcessInformation Retrieves information about a process running on a target machine. struct NubProcessInformation { char name[256]; }; STDMETHOD_(IMWDebugError*, GetProcessInformation)( IMWMachine* machineptr, ProcessID processid, NubProcessInformation& info) = 0; This method retrieves information about a process running on a target machine. When called, machineptr argument points to the machine for which GetProcessInformation() must return information. The processid argument refers to the process to retrieve information about. On return, GetProcessInformation() fills out the fields in the info argument about the specified process and returns an error result. GetProcessThreads Retrieves the threads in a process running on a target machine. struct NubThreadPair { MWThreadID threadid; MWThreadKind threadkind; 8 CodeWarrior
}; #define kembeddedrtosthread 6 STDMETHOD_(IMWDebugError*, GetProcessThreads)( IMWProcess* processptr, NubThreadPair* buffer, long& count) = 0; This method retrieves a list of threads running under a process on a target machine. When called, processptr, a pointer to an object of type IMWProcess, refers to the process for which GetProcessThreads() must retrieve threads for. The buffer argument is a pointer to an array of type NubThreadPair. GetProcessThreads() fills out this array. The threadkind field for each element in this array should be set to kembeddedrtosthread for kernel-aware plug-ins. On return, GetProcessThreads() fills out the fields in the buffer array, stores the number of threads in the count argument and returns an error result. GetProcesses on page 7 GetThreadInformation on page 9 GetCurrentThread on page 7 GetThreadInformation Retrieves information about a thread running on a target machine. struct NubThreadInformation { charname[256]; shortsuspended; }; STDMETHOD_(IMWDebugError*, GetThreadInformation)( NubThreadInformation& threadinfo, MWThreadID threadid, IMWProcess* processptr) = 0; CodeWarrior 9
This method retrieves information about a thread running under a process on a target machine. When called, the threadid argument specifies the thread to retrieve information for and the processptr argument points to an object of type IMWProcess for the process under which the thread is running. On return, GetThreadInformation() fills out the fields in the threadinfo argument about the specified thread and returns an error result. If the thread specified in threadid is running, then threadinfo s suspended field should be set to a positive value. If the thread is suspended then the suspended field should be set to zero. GetProcessThreads on page 8 GetCurrentThread on page 7 HasFeature Returns information about the kernel-aware plug-in s capabilities. enum KernelAwareNubFeatures { firstkernelnubfeature, nubwritesregisters }; STDMETHOD_(bool, HasFeature)( KernelAwareNubFeature feature) = 0; This function will be used by the debugger plug-ins to allow for future expansion of the kernel-aware interface. The plug-in should return false by default, only returning true if the specific feature is supported by this plug-in. WriteThreadRegisters on page 14 10 CodeWarrior
InstallNubMenu Allows the kernel-aware plug-in to set up a menu. STDMETHOD_(IMWDebugError*, InstallNubMenu) () = 0; The debugger calls this method immediately after a successful call to ProcessExists(). The kernel-aware plug-in should use this notification to use plug-in menu interface to install a plug-in specific menu. NotifyShutDown on page 12 NotifyAboutToRun Tells the kernel-aware plug-in that a thread on the target machine is about to continue execution. STDMETHOD_(void, NotifyAboutToRun)( ProcessID processid, MWThreadID threadid) = 0; The debugger calls this method when the debugger is about to resume a thread s execution. When called, the processid argument contains the ID of the process that is resumed. The threadid argument contain the ID of the thread that is resumed. The kernel-aware plug-in should use this notification to update any user interface items created by the plug-in. NotifyReturnFromRun on page 12 NotifyShutDown on page 12 InstallNubMenu on page 11 CodeWarrior 11
NotifyReturnFromRun Tells the kernel-aware plug-in that a thread on the target machine has been stopped. STDMETHOD_(void, NotifyReturnFromRun)( ProcessID processid, MWThreadID threadid) = 0; The debugger calls this method when a thread has stopped because of a breakpoint, exception, or other debugging task. When called, the processid argument contains the ID of the process who s thread has stopped. The threadid argument contain the ID of the thread that has stopped. The kernel-aware plug-in should use this notification to update any user interface items created by the plug-in. NotifyAboutToRun on page 11 NotifyShutDown on page 12 NotifyShutDown Tells the kernel-aware plug-in that the debug session is about to end. STDMETHOD_(void, NotifyShutDown)( ProcessID processid) = 0; The debugger calls this method when it is about to end a debug session. When called, the processid argument contains the ID of the process that is being shut down. The kernel-aware plug-in should use this notification to clean up any user interface items created by the kernel-aware plug-in (including menus). If any COM interface pointers (IMWTarget, IMWProcess, IMWSymbolics, for example) have been referenced, they should be released at this time. 12 CodeWarrior
NotifyAboutToRun on page 11 InstallNubMenu on page 11 ProcessExists Determines if the kernel-aware plug-in can be used with a program. STDMETHOD_(bool, ProcessExists)( IMWTarget* targetptr, ProcessID* outprocessid) = 0; This is the first function called by the debugger. Debuggers call this method to determine whether this kernel-aware plug-in should be used to debug a program running on a target machine. When called, the targetptr argument points to an object of type IMWTarget. A kernel-aware plug-in s ProcessExists() method uses the methods provided by targetptr to determine if the kernel-aware plug-in is able to work with the target. For example, using the IMWTarget class s GetSymbolics() method to retrieve symbolic information for the machine. From the symbolic information the kernel-aware plug-in might look for a unique identifier. If the kernel-aware plug-in determines that it is able to work with the application referred to by targetptr, it must store a process ID in outprocessid, logically-or d with EMBEDDED_RTOS_TYPE: processid EMBEDDED_RTOS_TYPE The debugger will use this value on subsequent calls to the kernel-aware plug-in. On return, ProcessExists() returns true and stores the process s ID logically- OR d with EMBEDDED_RTOS_TYPE if the kernel-aware plug-in recognizes the application. ReadThreadRegisters Retrieves the states of a thread s processor registers at the time that a thread was suspended. STDMETHOD_(IMWDebugError*, ReadThreadRegisters)( CodeWarrior 13
IMWProcess* processptr, MWThreadID threadid, IMWRegisterInfo* reginfoptr) = 0; This method retrieves information about a thread s registers running under a process on a target machine at the time the thread was suspended by the operating system. The actual processor registers will be retrieved by the debugger for the current thread using a separate mechanism. When called, the processptr argument points to an object of type IMWProcess for the process under which the thread is running and the threadid argument specifies the thread to retrieve register information for. The reginfoptr argument points to an object of type IMWRegisterInfo. On return, ReadThreadRegisters() uses the methods provided by the reginfoptr object to record information about the thread s general purpose registers. WriteThreadRegisters on page 14, HasFeature on page 10 WriteThreadRegisters Sets the states of a thread s processor registers when a thread is suspended. STDMETHOD_(IMWDebugError*, WriteThreadRegisters)( IMWProcess* processptr, MWThreadID threadid, IMWRegisterInfo* reginfoptr) = 0; This method is used to modify the values of this threads saved register state. The actual processor registers will be set by the debugger for the current thread using a separate mechanism. When called, the processptr argument points to an object of type IMWProcess for the process under which the thread is running and the threadid argument specifies the thread to set register information for. The reginfoptr argument points to an object of type IMWRegisterInfo. If the kernel-aware plug-in does not allow registers to be set, it should make sure to return false when its HasFeature() method is called with numwritesregisters. 14 CodeWarrior
IMWKernelAware2 Interface Reference On return, WriteThreadRegisters() uses the methods provided by the reginfoptr object to set the thread s general purpose registers. ReadThreadRegisters on page 13 HasFeature on page 10 IMWKernelAware2 Interface Reference This section describes the IMWKernelAware2 Interface and its one method. You do not need to implement this interface in your kernel aware plug-in, but if your operating system manages thread state in such a way that the current chip registers do not necessarily correspond to the current thread, then this interface may be useful. Consider the following scenario, as it is an example of how this interface may be used. When a thread is switched out of context, the General Purpose registers and Floating Point registers are stored on its stack. When the thread is switched back into context, the General Purpose registers from the threads stack will be pushed into the chip registers, but restoration of the Floating Point registers will be delayed until the thread actually executes a floating point instruction that affects those registers. In this type of scenario, the debugger needs to be able to determine when to read the chip s floating point registers through the standard debug protocol and when to read the floating point registers from a thread's stack through the kernel aware plug-in s ReadThreadRegisters() function. IMWKernelAware2::ThreadHasCurrentRegisterSet gives the debugger this ability. ThreadHasCurrentRegisterSet Checks wether a thread is using the current registers for this register set. STDMETHOD_(bool, ThreadHasCurrentRegisterSet)( IMWProcess* inprocessptr, MWThreadID inthreadid, IMWRegisterInfo* reginfoptr) = 0; It is possible that the current thread does not use the chip registers for a given set. For example, a background thread may be using the chip registers. CodeWarrior 15
IMWKernelAware2 Interface Reference If the method returns true, the thread is using the chip registers. If the method returns false, the thread has registers stored in memory (or nowhere). 16 CodeWarrior
Index A AddRef() 6 C CodeWarrior IDE 5 COM. See Component Object Model. Component Object Model AddRef() 6 API for kernel-aware plug-ins 5 implementation as 5 implementation requirements 6 QueryInterface() 6 Release() 6 D debugger 5 DebuggerInterface.h 6 DebuggerPluginEntryName() 6 E exporting DebuggerPluginEntryName() 6 GetIMWKernelAwareName() 6 F features checking available 10 G GetCurrentThread() 7 GetIMWKernelAwareName() 6 GetProcesses() 7 GetProcessInformation() 8 GetProcessThreads() 8 GetThreadInformation() 9 H HasFeature() 10 host platform 5 I implementation requirements 6 IMWDebuggerPlugin class 5 IMWKernelAware class 5 IMWKernelAware2 class 5 IMWPluginNub 5 InstallNubMenu() 11 Intel x86 5 M menu when to set up 11 Microsoft 5 Microsoft Win32 5 N NotifyReturnFromRun() 12 NotifyShutDown() 12 P plug-in features 10 installing menu 11 stopping 12 using with processes 13 process available 13 information about 8 running 7 threads in a 8 ProcessExists() 13 Q QueryInterface() 6 R ReadThreadRegisters() 13 Real-Time Operating System vendors 5 registers reading 13 CodeWarrior 17
writing 14 RegisterServices() 5 Release() 6 RTOS. See Real-Time Operating System. runtime environment 5 S shutting down 12 stopping 12 T thread ID 7 information about 9 registers, reading 13 registers, writing 14 running 7, 11 stopped 12 suspended 12 ThreadHasCurrentRegisterSet() 15 W Win32 5 WriteThreadRegisters() 14 X x86 5 18 CodeWarrior