February 8, 1999
Microsoft NT Tools Project

Windows NT OEM Support Tools version 2.01 release note

Release History
---------------

03/20/98 first milestone release
04/03/98 second milestone release
04/24/98 third milestone release 
05/22/98 4th milestone release 
06/02/98 5th milestone release 
06/10/98 version 1.0 final release 

09/11/98 version 1.1
10/23/98 Phase2 second milestone release (User Dump only)
11/20/98 Phase2 third milestone release
12/25/98 Phase2 fourth milestone release
01/19/99 Phase2 RC release
02/03/99 version 2.0 release 
02/08/99 version 2.01 release (This release)
-----------------------------


Support Platform
----------------
This release supports Windows NT Server and Workstation versions
3.51 and 4.0 on x86 platform and Windows NT version 4.0 on Alpha 
platform. 


Debugger Requirements
---------------------
Windbg version tested and recommended with this release is 5.00.1867.1.
It is available either from MSDN Platform SDK September 1998 CD-ROM or 
http://msdn.microsoft.com/developer/sdk/windbg.htm. This version of
Windbg runs on Windows NT 4.0 and can debug crash dumps and user dumps
from both 3.51 and 4.0 systems, as well as live Windows NT 4.0 systems. 
If you want to debug live x86 3.51 systems, you need to use i386kd.exe.


Documentation
-------------
Please refer to updated ph2spec.doc included in this release to find
new and changed features in Phase 2.
User Documentation will be released at the end of February.


Kernel Debugger Extensions
--------------------------
!stack command provides improved stack traces.
The command is only supported on x86 platform.
The command can be used to debug a crash dump file but cannot be used
to debug a live system.

Below is a sample output from !stack command.

  T. Address  RetAddr  Called Procedure
  *0 FDF62D70 8013FE5C _KeBugCheckEx@20(0000000A, 0003C408, 00000002,...);
  *0 FDF62D88 FE1FACAD _IoSetThreadHardErrorMode@4(00000000, 83E16020, 824A2020,...);
  *1 FDF62E00 801251EA _MiInitializePfn@12(0000223E, C01DFE58, 00000001,...);
  *1 FDF62E24 801256AE _MiResolveDemandZeroFault@16(77F96190, C01DFE58, 82F7B340,...);
  *1 FDF62E54 80124E58 _MiResolveProtoPteFault@24(00000001, 77F96190, C01DFE58,...);
  *0 FDF62E94 8012D6FA @MiLocateAddressInTree@8(FDF62EF0, 8012B2DE, 00000001,...);
  *1 FDF62E9C 8012B2DE _MiDispatchFault@20(00000001, 77F96190, C01DFE58,...);
  *1 FDF62EF4 8013FCBA _MmAccessFault@12(00000001, 77F96190, 00000001,...);

In the above example, numbers at the T. column indicates the trust level.
More detail information will be provided in the upcoming user document.


Pool Enhancements
-----------------
If you installed poolext driver from milestone or RC releases, you must
reinstall the final version and reboot your system.

Support for Alpha platform is added in this release.


Kernel Memory Space Analyzer
----------------------------
Below are the list of director plug-ins supplied with this release.
They are all supported on both x86 and Alpha platform.
You can customize template kanalyze.ini to enable/disable these
plug-ins.

  RESULT   - Displays all anomaly items and their related items.
  DISP     - Displays all items in sorted order by type name.
  VIEWCMD  - Allows users to interactively view stored items.
  DRIVERS  - Displays a list of loaded drivers.
  DUMPINFO - Displays StopCode, registers, etc.
  IOVIEW   - Displays IRPs, device queues.
  OBJVIEW  - Displays object trees, per process handle tables.
  POOLVIEW - Displays usage of pool pages, pool blocks.
  PSVIEW   - Displays a list of processes, threads.
  STVIEW   - Displays stack traces per thread.
  VMVIEW   - Displays virtual memory layout, usage of memory.

For plug-in developers, \kanalyze\inc directory includes header files
required for developing director plug-ins.


User Mode Process Dump
----------------------
You must use Windbg 5.0 as stated in the Debugger Requirements
section. Windbg 4.0 cannot open a user dump file generated by
the tool.


Known issues and restrictions
-----------------------------
1) Kernel Debugger Extensions

  - There are cases where output from Extensions commands includes wrong 
    symbol information if symbol files are located on a network drive or 
    path to symbol files is specified by UNC name. 
    This is a bug of Windbg version 5.00.1867.1 and should be corrected 
    in the future release of Windbg. As a workaround, locating symbol 
    files on a local hard disk should solve the problem.

  - When address to interrupt routine displayed by !idt command is lower than 
    0x80000000, symbol information associated with the address is not valid
    and should be ignored.

  - The offset of following structure members displayed by !strct command is 
    wrong.

    + "Queue" in "DEVICE_OBJECT"
    + "u"     in "MCA_EXCEPTION"

  - Below are the restrictions regarding !strct user-defined structure ini file.

    + The maximum number of structures which can be defined in one ini file is 
      limited to 256. If there are more than 256 structures defined in
      [struct] section, only first 256 structures will be loaded and the rest
      will be ignored. If you want to define more than 256 structures, the ini
      file should be separated into multiple files. 
    
    + The maximum number of structure definition files which can be defined in 
      structdb.ini file is limited to 256. If there are more than 256 ini 
      files defined in the [StructDbList] section, only first 256 files will be
      loaded and the rest will be ignored.

    + In ini file, if the type of structure's member is defined as enum or 
      bitfield, "count" item must be 1. That means array of enum/bitfield is
      not supported. If array of enum/bitfield is defined, only first entry in
      the array is displayed with corresponding name.

    + !strct command sometimes displays a wrong size of loaded struct loaded 
      from ini file. Currently kernel debugger extension calculates the size of 
      loaded struct by the sum of the offset of last member and the size of last
      member. However if alignment rule is adapted by compiler, the calculated 
      size is wrong.

    + If anonymous struct/union member is defined in ini file and loaded,
      !strct command displays a data type like

        " <parent structure name>CHILD<3 figures hex numbers>"

      when such struct/union member is specified by the command. 
      This is a temporary name named by kernel debugger extension.
      This is by design and not a bug. Such temporary name cannot be 
      specified by !strct or !list command directly.

      e.g.)
      +000a    Flags
      +000c    Block( RTL_HEAP_WALK_ENTRY_CHILD000 struct)
      +000c      Settable
      +0010      TagIndex
      +0012      AllocatorBackTraceIndex
      +0014      Reserved
      +000c    Segment( RTL_HEAP_WALK_ENTRY_CHILD001 struct)
      +000c      CommittedSize

      Also note that the maximum number of anonymous struct union type in one 
      structure is 4096. 

    + If anonymous member like struct union is defined in ini file and loaded, 
      !strct command displays a member name like 

        " anonymous<3 figures hex numbers>"

      when such members is specified by the command.
      This is a temporary name named by kernel debugger extension.
      This is by design and not a bug. Such temporary name cannot be specified
      by !strct, !list, or !singlelist command directly. 
 
      e.g.)
      +00d8    array =                0073 005c 0041
      +00dc     anonymous000( X3452_CHILD000 struct)
      +00dc      a =                    A                   41
      +00e0      b =                    0070

      Also note that the maximum number of anonymous struct union members in one 
      structure is 4096. 

    + "!strct load" and "!strct unload" commands don't work with i386kd.exe and 
      alphakd.exe. To use user-defined structure feature with 
      i386kd.exe/alphakd.exe, structdb.ini is required to be placed in the same 
      directory as kdex2x86.dll/kdex2alp.dll is placed. Then user-defined 
      structures must be defined in the ini file listed in structdb.ini. 


2) Kernel Memory Space Analyzer

  - Depending on the versions of Windows NT, module plug-in may identify
    anomalies in the following functions of ntoskrnel.exe and hal.dll. 
    They are expected behavior of these modules at runtime and you can ignore
    them.

    + KeFlushCurrentTb function in ntoskrnel.exe
    + HalpRealModeStart and HalSetTimeIncrement functions in hal.dll

  - Module plug-in identifies anomalies in the following functions in
    ntoskrnl.exe if Poolext.sys was installed on the system which dump file was
    taken. They are expected results because Poolext.sys hooks into these
    functions in the kernel at runtime. You should ignore them.

    + ExAllocatePool+0
    + ExAllocatePoolWithTag+0
    + ExAllocatePoolWithQuota+0 
    + ExAllocatePoolWithQuotaTag+0 
    + ExFreePool+0 
    + ExFreePoolWithTag+0 
    + FsRtlAllocatePool+0 
    + FsRtlAllocatePoolWithQuota+0 
    + FsRtlAllocatePoolWithTag+0 
    + FsRtlAllocatePoolWithQuotaTag+0 
    + MmUnloadSystemImage+0
    + MmLoadSystemImage+0
     
  - There are following known issues in STRACE plug-in if NMI(KiTrap02) or 
    Double-fault(KiTrap08) found in a dump file.

    + Cannot locate switched stack.
    + Cannot locate stack frame for the stack before switched.
    + Can locate stack frame for the switched stack but includes some wrong
      data.

    Due to above problems, output from STVIEW, DUMPINFO, and stack item 
    descriptions sometimes include wrong information.

  - STRACE plug-in for Alpha does not locate TRAP frames.

  - EXECUTIVEOBJECT plug-in reports the following anomaly if a process is
    attached by debugger. This is a bug of EXECUTIVEOBJECT plug-in and can be
    ignored.

      EPROCESS @f9cc24c0
      CreateProcessReported is anomalous.
      This value must be false

  - Following are notes for plug-in developers who uses helper routines and
    method interfaces.

    + New line codes for a string returned by GetDataItemDescription are
      CR+LF. If you use stream output functions like printf to print this string,
      new line codes might get converted to CR+CR+LF.
      If you want to output a string returned by GetDataItemDescription,
      use binary mode or output without using stream output functions.

    + If data item specified by GetDataItemDescription or CallMethodRoutine
      is located in paged out area, these functions may return ERROR_READ_FAULT.

    + When analyzing Windows NT 3.51 crash dump file, method code 
      M_EOTHREAD_GET_IMPERSONATION_INFO returns ERROR_INVALID_FUNCTION error.
      This is by design.


3) User Mode Process Dump

  - On Windows NT 3.51, if "All Exceptions" is applied to csrss.exe by the
    Exception Monitoring, User Dump will try to dump csrss.exe every time 
    when certain type of application is started or terminated on the system. 
    This will cause frequent system freeze for a short period while csrss.exe
    is being dumped. This occurs because csrss.exe always raises 
    STATUS_PORT_DISCONNECTED (c0000037) exception when certain type of application
    is started or terminated. To avoid this problem, it is suggested that when 
    csrss.exe is monitored configure default or custom rules so that it does not 
    include above exception.

  - Attempt to dump smss.exe and open a dump file by Windbg will fail 
    as smss.exe is not a standard Win32 executable. This is by design. 


[End of Text]