Debugging Tools for Windows

AttachKernel

The AttachKernel and AttachKernelWide methods connect the debugger engine to a kernel target.

HRESULT
  IDebugClient::AttachKernel(
    IN ULONG  Flags,
    IN OPTIONAL PCSTR  ConnectOptions
    );

HRESULT
  IDebugClient5::AttachKernelWide(
    IN ULONG  Flags,
    IN OPTIONAL PCWSTR  ConnectOptions
    );

#ifdef UNICODE
#define AttachKernelT AttachKernelWide
#else
#define AttachKernelT AttachKernel
#endif

Parameters

Flags

Specifies the flags that control how the debugger attaches to the kernel target. The possible values are:

Value	Description
DEBUG_ATTACH_KERNEL_CONNECTION	Attach to the kernel on the target computer.
DEBUG_ATTACH_LOCAL_KERNEL	Attach to the local kernel. To check whether this option is available, use IsKernelDebuggerEnabled.
DEBUG_ATTACH_EXDI_DRIVER	Attach to a kernel by using an eXDI driver.

ConnectOptions

Specifies the connection settings for communicating with the computer running the kernel target. The interpretation of ConnectOptions depends on the value of Flags.

DEBUG_ATTACH_KERNEL_CONNECTION: ConnectOptions will be interpreted the same way as the options that follow the -k switch on the WinDbg and KD command lines. Environment variables affect ConnectOptions in the same way they affect the -k switch. For details on the syntax of this string, see Choosing Kernel Debugging Settings.
DEBUG_ATTACH_LOCAL_KERNEL: Set to NULL.
DEBUG_ATTACH_EXDI_DRIVER: eXDI drivers are not described in this documentation. If you have an eXDI interface to your hardware probe or hardware simulator, please contact Microsoft for debugging information.

Return Value

S_OK: The method was successful.

This method may also return error values. See Return Values for more details.

Interface Version

AttachKernel is available in all versions of IDebugClient. AttachKernelWide is available in IDebugClient5 and later versions.

Comments

Local debugging and debugging over an IEEE 1394 cable are supported only on Windows XP and later versions of Windows. Both the target computer and the host computer must be running one of these Windows versions, but not necessarily the same one.

Note The engine doesn't completely attach to the kernel until the WaitForEvent method has been called. Only after the kernel has generated an event — for example, the initial breakpoint — does it become available in the debugger session.

For more information about connecting to live kernel-mode targets, see Live Kernel-Mode Targets.

Requirements