                   Microsoft(R) Debugging Tools for Windows(R)
                            Version 6.5 Release Notes
                                    July 2005

-----------------------------------------------------------------------------

Contents

    Overview
    What's New
    Known Issues
    Programs
    Debugger Extensions
    Software Development Samples
    Documentation
    Redistributables
    More Information
    Feedback

-----------------------------------------------------------------------------

Overview

Debugging Tools for Windows(R) contains tools to analyze and debug Windows,
Windows drivers, and applications.   It can analyze memory dump files or
perform live debugging.

The kernel debugger is KD.exe.  It can be installed and run on all
the platforms listed below. It can debug all the platforms listed below.

The user-mode debugger is CDB.exe.  It can be installed and used on all the
platforms listed below.

WinDbg.exe is the GUI version of the debugger.  It supports both user-mode
and kernel-mode debugging.  It can be installed and run on all the platforms
listed below. It can debug all the platforms listed below.

Supported platforms:

Windows NT 4.0 (x86)
Windows 2000 (x86)
Windows XP  (All CPU architectures)
Windows Server 2003 (All CPU architectures)
Windows codename "Longhorn" (All CPU architectures)

-----------------------------------------------------------------------------

What's New

This release of Debugging Tools for Windows contains many bug fixes and new
enhancements. The debuggers are stable and more reliable than previous releases
and we recommend that you upgrade to this version.

Here's a list of the key changes in WinDbg 6.5:

    * Compatibility updates for Windows codename "Longhorn".
    * New EngExtCpp C++ extension framework:
         * This is a Developer Preview, and APIs are subject to change.
         * Headers and sample can be installed by choosing the SDK component
             during installation of Debugging Tools for Windows.
    * Win9x user-mode compatibility fixes:
         * Requires MSLU.  See debugger documentation for details.
         * Win9x debugging is still not a supported scenario.
    * USB 2.0 kernel debugging support.  Requires a Windows "Longhorn" target
        computer and some additional software.  See debugger documentation for
        details.
    * New tool available:  DBH.
    * New commands available: .allow_image_mapping, .apply_dbp, .prompt_allow, 
        .step_filter, and .suspend_ui.
    * New options available for the lm, uf, .attach, .cxr, .foreach, .opendump, 
        and .printf commands.
    * All debuggers now support .wtitle.
    * New pseudo-register: $ea2.
    * New automatic aliases:  $CurrentDumpArchiveFile, $CurrentDumpArchivePath, 
        $CurrentDumpFile, $CurrentDumpPath, $ntsym, $ntnsym, and $ntwsym.
    * New extensions available:
         * in exts.dll: !bitcount.
         * in kdexts.dll: !sysinfo.
         * in wmitrace.dll: !buffer, !ckcl, !regtable, and !setprefix.
         * in wdfkd.dll: !wdfdevice, !wdfdevicequeues, !wdfdriverinfo, 
             !wdfextendwatchdog, !wdfgetdriver, !wdfldr, !wdfqueue, !wdfrequest,
             !wdfsetdriver, and !wdftraceprtdebug.
    * New extension module fltkd.dll.  This contains !cbd, !contextlist, !ctx, 
        !filter, !filters, !fltobj, !frame, !frames, !instance, !irpctrl, !msgq,
        !namecachelist, !port, !portlist, !relobjs, !stats, !streamlist, 
        !traceflags, !tracelevel, !tree, !volume, and !volumes.
    * New options available for the !search extension.
    * New symbol quoting syntax.
    * WinDbg UI changes, including:
         * "Edit->Clear Command Output" allows clearing partial text from 
             command window.
         * "File->Open Executable" remembers process arguments and start 
             directory.
         * Cascading and tiling of undocked windows.
         * Watch window and Locals window context option to invoke 'dt' command.
    * Source Server support for Subversion version control system.
    * Updated 1394 kernel debugging drivers.
    * Updates to many sections of the debugger documentation (debugger.chm).
    * New documentation file, Kernel_Debugging_Tutorial.doc, aimed at customers
        who are familiar with other debugging tools and want to learn how to use
        WinDbg for kernel debugging.
    * Many improvements to the !analyze extension.
    * Numerous fixes to bugs in various commands and extensions reported by
        customers.

    Complete details on all these features can be found in the debugger
    documentation (debugger.chm).  To open this documentation, use 
    Start --> Debugging Tools for Windows --> Debugging Help.

    ***  Please report any bug you find to windbgfb@microsoft.com  ***


-----------------------------------------------------------------------------

Known Issues


VC4 \ NT 4 DDK support:
-----------------------
The NT 4 DDK shipped with VC4 compatible tools.

This version of the debuggers does not support local variables generated by 
this default build-environment.  The debuggers only support local variables 
if a .pdb file is generated by the compiler and linker.

To enable .pdb files in the NT 4 DDK, set the following environment variable.

    set USE_PDB=1
    set NTDEBUGTYPE=windbg



Other issues:
-------------

If you need to find source that was compiled at a different location than
the current location to the source, use the ".srcpath" command. 

If you are using Windows NT 4.0, you need to have Microsoft Internet Explorer
5.0 or later installed for all of the features to work correctly.


-----------------------------------------------------------------------------

Programs

This distribution includes the following debuggers:

    KD        - Command-line kernel debugger
    NTSD      - Command-line user-mode debugger
    CDB       - Command-line user-mode debugger (variant of NTSD)
    WinDbg    - GUI kernel debugger

I386KD is also provided in the package to support backwards compatibility. 
It has the same code-base as KD.

There are several debugger-related tools included with the package.  They
are identified as a subcategory under Tools in the custom menu during install.
This subcategory is called "Helpful Tools" and it is installed by default.

The Helpful Tools option is installed by default and includes these
debugger-related tools:

    AgeStore  - Removes old or unwanted files from the downstream store used by
                a symbol server or source server
    DBH       - DbgHelp shell
    GFlags    - Global Flags Editor
    Breakin   - Utility to force a breakin in another process being debugged
    Remote    - Remote Command Line
    Kill      - Task Killing Utility
    List      - File List Utility
    LogViewer - Display API logs created with the .logext extension from
                the debugger
    RTList    - Remote Task List Viewer
    SymChk    - utility to check validity of symbol files, or download symbols
                from a symbol server prior to a debugging session
    SymProxy  - ISAPI filter acting as an HTTP proxy for one or more symbol servers
    SymStore  - Creates a symbol server for automatic symbol lookup
    TList     - Task List Viewer
    UMDH      - Heap Analysis Tool

The following tools have been incorporated into KD.exe and WinDbg.exe.  They
are also provided with Helpful Tools as small stubs that point you to use the 
debugger.

    DumpChk   - Dump Checking Utility
    DumpExam  - Dump Examining Utility

-----------------------------------------------------------------------------

Debugger Extensions

Debugger Extensions are DLLs which WinDbg, CDB, NTSD, and KD can use to provide
additional debugger commands.

The extensions that work for all versions of Windows reside in the "winext"
subdirectory, and include:

    uext.dll
    kext.dll
    ext.dll
    logexts.dll


The newest version-specific debugger extensions (which work on Windows XP,
Windows Server 2003, and Windows codename "Longhorn") reside in the "winxp"
subdirectory, and include:

    exts.dll
    kdexts.dll

The debugger extension DLLs for Windows NT 4.0 and Windows 2000 are operating 
system version, debug/retail specific.  However, these extensions should
properly support all service packs based on that build.  Multiple versions of
each DLL are included, to provide the necessary files for each variant. All DLLs
are provided in both debug and retail versions.  The debug and retail versions 
of these DLLs for Windows NT 4.0 and Windows 2000 are installed 
into four subdirectories, under the target subdirectory:

    nt4chk
    nt4fre
    w2kchk
    w2kfre
    
The debugger has awareness of these subdirectories, and will not be able
to find them if these subdirectories are renamed or moved.

If a custom extension DLL is to be used, it should be placed in its own
directory.  The user can then set the debugger extension path variable so the
debugger can find the extension.  Debugger extensions can also be loaded in
the debugger using fully qualified path names.

All of the debuggers search for debugger extension DLLs in a series of 
directories.  For a list of these directories and the sequence in which they
are searched, open the documentation, choose the Index tab, type "extension",
and click on "default search order" in the listing under "extension".


-----------------------------------------------------------------------------

Software Development Samples


Header files, libs and samples for debugger extensions are provided in this
package.  They are not installed by default.  The "SDK" component of the package
must be selected during the install to get the samples installed.

Use the Build utility to compile and build these samples.  You must use the
version of the Build utility supplied by the latest version of the Windows DDK
or the Platform SDK.  These kits include several different build environment
windows; it is important that you use the "Windows Server 2003 Build Environment"
windows -- even if you are building samples or extensions for use on a different
version of Windows.

Attempting to build the samples and headers in a "Windows 2000 Build Environment"
will cause compilation errors.  Building them in a "Windows XP Build Environment"
may succeed in some cases, but it is not recommended.  The "Windows 2003 Server
Build Environment" is the one that should be used in all cases.

The header files and libs in this package should replace any existing version
of the header files or libs that are shipped with the Windows DDK or the
Platform SDK.  If you follow the instructions for using the Build utility which
appear in the Windows DDK documentation, you can set your include paths so that
this is done automatically.

The samples will not compile if they are located in a directory path containing
spaces.  If you have installed Debugging Tools for Windows into a path with
spaces, you can work around this limitation by moving or copying the "sdk"
subdirectory to a directory path without spaces.


-----------------------------------------------------------------------------

Documentation

For documentation on how to use these debuggers and related tools, see the
help file debugger.chm that is included with the tools.  This documentation
has been improved and expanded since the last release.

When Debugging Tools for Windows is installed, a shortcut to this documentation
can be found under Start --> Programs --> Debugging Tools for Windows -->
Debugging Help.

Information on how to write debugger extensions is included in this same
documentation file.  If you plan to write debugger extensions, you should
perform a custom install of Debugging Tools for Windows and select all
available features.  This will ensure that you have all the necessary
extension headers, libraries, and samples.

The DbgHelp interface is documented in a separate documentation file
(dbghelp.chm).

A tutorial on kernel debugging, Kernel_Debugging_Tutorial.doc, is also included
in this installation.  This file is helpful if you are familiar with other
debugging tools and want to learn how to use WinDbg for kernel debugging.

You need to have Internet Explorer 5.0 or greater installed in order to use
the documentation properly.

-----------------------------------------------------------------------------

Redistributables

Please read the license agreement during setup for legal information regarding
redistributable files.  If this is a retail release, the license agreement 
mentions that redist.txt gives a list of the files that are redistributable.  

-----------------------------------------------------------------------------

More Information

For more information on debugging, see the Debugging Tools for Windows
web page, <http://www.microsoft.com/whdc/DevTools/Debugging>.

We encourage people to get the new debugger off the web "often", as
we do many updates, while keeping compatibility with Windows NT 4.0, 
Windows 2000 and Windows XP.

-----------------------------------------------------------------------------

Feedback

We are interested in your feedback on the tools.  Please mail suggestions or 
bug reports to WinDbgfb@microsoft.com.  This is not a support alias, but your 
feedback will help us to plan future changes for these tools and will make 
them more useful to you in the future.

-----------------------------------------------------------------------------
