/* **********************************************************
 * Copyright (c) 2010-2016 Google, Inc.  All rights reserved.
 * Copyright (c) 2009-2010 VMware, Inc.  All rights reserved.
 * **********************************************************/

/* Dr. Memory: the memory debugger
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation;
 * version 2.1 of the License, and no later version.

 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Library General Public License for more details.

 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

/**
 ****************************************************************************
 ****************************************************************************
\page page_release_notes Release Notes for Version \TOOL_VERSION

This section is divided into the following subsections:

 - \ref sec_package
 - \ref sec_changes
 - \ref sec_limits

***************************************************************************
\htmlonly
<table width=100% bgcolor="#000000" cellspacing=0 cellpadding=2 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td></td></tr></table></td></tr></table></td></tr></table>
\endhtmlonly
\section sec_package Distribution Contents

The Dr. Memory distribution contains the following:

 - The front-end executable \p drmemory for launching Dr. Memory.
 - The back-end of Dr. Memory, contained in the \p bin and \p dynamorio
   subdirectories.  Dr. Memory runs on top of the DynamoRIO tool engine
   (see http://dynamorio.org for more information on DynamoRIO).
 - Documentation for Dr. Memory (you're looking at it).
 - \ref page_drstrace
 - \ref page_symquery

***************************************************************************
\htmlonly
<table width=100% bgcolor="#000000" cellspacing=0 cellpadding=2 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td></td></tr></table></td></tr></table></td></tr></table>
\endhtmlonly
\section sec_changes Changes Since Prior Releases

The current version is \TOOL_VERSION.
The changes between \TOOL_VERSION and version 1.10.1 include:
 - Added support for Windows 10 1607.
 - Added support for loading system call numbers from a file, to make
   it easier to update for future major Windows 10 updates.
 - Added an option -ignore_kernel to attempt to continue on even when
   running on a kernel with unknown system call numbers.
 - Added support for Mac OSX El Capitan.
 - Better international string support.

The changes between 1.10.1 and version 1.10.0 include:
 - Fixed problems with configuration directories on Android.
 - Fixed several bugs, including Windows false positives, ARM
   instrumentation issues, and VS2015 crashes.

The changes between 1.10.0 and version 1.9.0 include:
 - Added preliminary 64-bit Dr. Memory support for Windows and Linux (but
   not MacOS yet).  This does not yet include uninitialized read checking,
   so we still recommend compiling your application as 32-bit.
 - Added preliminary Linux/ARM and Android/ARM 32-bit Dr. Memory support.
   This does not yet include uninitialized read checking.
 - Added support for Windows 10 1511.
 - Fixed incremental error output to the console for graphical
   applications, which was missing in prior versions when using certain
   consoles such as cmd.
 - Removed the -fuzz_mutator option and replaced it with separate options
   for each component of the mutator.
 - Added custom mutator support to Dr. Fuzz.
 - Changed the mutator option passing scheme for Dr. Fuzz to take in
   an argv-style array of parameters, to better support custom mutators.
 - Added checking that the program counter points to valid memory,
   controlled by the on-by-default -check_pc option.
 - Added a new option -malloc_callstacks for recording malloc callstacks
   to include in alloc/free error reports when leaks are disabled.
   The option is off by default due to the additional overhead that
   it incurs.
 - Added code coverage measurement via a new option -coverage.
 - By default, without the \p -show_reachable option, reachable leak
   callstacks are no longer compared to suppressions, in order to reduce
   overhead.

The changes between version 1.9.0 and version 1.8.0 include:
 - Added support for Mac OSX Yosemite.
 - Added Dr. Fuzz, a fuzz testing framework that facilitates repeated
   execution of any program function while mutating the arguments.
 - Added a fuzz testing mode to Dr. Memory. Use new options -fuzz_target
   and -fuzz_mutator to fuzz test any C or C++ target function having a
   buffer argument and a corresponding buffer size argument.
 - Switched the Windows installer from an NSIS-based executable to
   a WIX-based .msi file.  The new installer automatically adds
   Dr. Memory to the PATH for the current user.
 - Added an unaddressable warning report on a write to read-only memory.
 - Added support for the VALGRIND_DO_LEAK_CHECK annotation.

The changes between version 1.8.0 and version 1.7.0 include:
 - Dropped official support for Windows 2000.
 - Enabled -delay_frees_stack by default.
 - The Windows installer now automatically adds Dr. Memory as an External
   Tool for every installation of Visual Studio on the machine.
 - Changed details of the callstack maximum frame options.
   Added two new options: -malloc_max_frames, used for leak reports (and
   mismatch aux info), and -free_max_frames, used for -delay_frees_stack.
   Changed the default -callstack_max_frames to 20.  -malloc_max_frames
   defaults to the original 12, and -free_max_frames is at 6.
 - Added a new option -check_uninit_blacklist to reduce overhead on modules
   where no uninitialized read error reporting is desired.
   Dr. Memory automatically adds to this list when it sees a whole-module
   suppression.
 - Disabled checks for mixing C library heap routines with Windows API heap
   routines (-check_heap_mismatch) for modules that contain static libc.
 - Changed the drsymcache_lookup() interface.
 - Added extra information to unaddressable error titles to make
   several common types of such errors easier to identify:
   "UNADDRESSABLE ACCESS of freed memory",
   "UNADDRESSABLE ACCESS beyond heap bounds", and
   "UNADDRESSABLE ACCESS beyond top of stack".
 - Renamed option -stderr to -use_stderr.

The changes between version 1.7.0 and version 1.6.1 include:
 - Added a Beta version of Dr. Memory for Mac.  Be aware that this
   is a work in progress, but is far enough along to use on small
   applications.
 - Changed Windows PDB symbols to collapse template parameters to "<>"
   to shrink and simplify callstacks and suppressions.  The old behavior
   can be requested by passing 0x1000 to the -callstack_style option.
 - Changed Linux and MinGW symbols to omit the "()" in C++ symbol names.
 - Added a new Dr. Memory Framework Extension, Dr. SymCache or drsymcache,
   which provides persistent caching of symbol lookup data to reduce
   startup time overhead on large applications.
 - Clarified the final parameter to umbra_get_shadow_memory_type() and
   umbra_shadow_memory_is_shared() to be umbra_shadow_memory_type_t
   rather than uint.
 - Clarified the 2nd parameter to umbra_create_shadow_memory() to be
   umbra_shadow_memory_flags_t rather than uint.
 - Clarified the umbra_shadow_memory_info_t shadow_type field to be
   umbra_shadow_memory_type_t rather than uint.
 - Clarified the umbra_map_options_t flags field to be
   umbra_map_flags_t rather than uint.
 - Added static library versions of drsyscall and umbra.
 - On Windows, handle leak detection (-check_handle_leaks) is now on by default
   in full mode.  However, it is still experimental and conservative,
   placing leaks it's not sure about in potential_errors.txt.
 - Added preliminary shadowing of xmm registers for better Visual Studio
   2013 support.
 - Added preliminary shadowing of mmx registers.
 - Augmented the Dr. Syscall API for MacOS support by adding
   drsys_cur_syscall_result(), drsys_arg_t.value64, and
   drsys_pre_syscall_arg64().
 - The pause in cmd on a frontend error is now bypassable by -batch.
 - Added an option -exit_code_if_errors to return a non-zero exit code
   when errors are detected.
 - Replaced the perl front-end \p drmemory.pl on Linux with an executable.
 - Various bug fixes.

The changes between version 1.6.1 and version 1.6.0 include:
 - Added Windows 8.1 support
 - Added -handle_leaks_only feature for low-overhead handle leak checking
 - Added the -crash_at_unaddressable and -crash_at_error options
 - Added the -no_callstack_use_fp and -callstack_conservative options
 - Various bug fixes

The changes between version 1.6.0 and version 1.5.1 include:
 - Added a separate category of error report, "potential errors", stored in
   potential_errors.txt.  These are errors that are suspected of being
   false positives or limited to system libraries.  It is possible that
   they are in fact true application errors, however.  This separation of
   errors can be disabled with the option -lib_blacklist_frames 0, and
   tuned via the options -lib_blacklist and -lib_blacklist_frames.
 - Added options -lib_whitelist and -lib_whitelist_frames to support
   only displaying errors whose top N frames reference a whitelisted
   module.  Any error that does not match the whitelist is separated
   as a "potential error" (see the prior blacklist entry).
 - Removed -srcfilter option and replaced with new options -src_whitelist
   and -src_whitelist_frames to support only displaying errors whose top N
   frames reference a whitelisted source file.  Any error that does not
   match the whitelist is separated as a "potential error" (see the earlier
   blacklist entry).
 - Added full support for applications linked with the debug Visual Studio
   C library.
 - Added checks for mixing of C library heap routines with Windows API heap
   routines on the same allocation, under a new on-by-default new option
   -check_heap_mismatch.
 - Switched to replacing the malloc implementation with Dr. Memory's own
   allocator, rather than wrapping the system allocator, for improved
   performance and stability and improved interoperability with
   the Visual Studio debug C library.
 - Improved still-reachable allocation reporting, adding suppression
   support, de-duplication, and hiding of system allocations.
 - Added option -check_prefetch to make it easier to turn off the warnings
   on prefetching unaddressable memory.
 - The GDI error on using a DC by more than one thread is now off by
   default.  It can be enabled with the -check_gdi_multithread option.
 - Added drsys_syscall_gateway() to the Dr. Syscall library.
 - Extended -soft_kills to handle the most common job termination sequences.
 - Further reduced false positives in Windows system libraries by
   continuing to make progress on Windows system call handling.
 - Added a source file package to the release process.
 - Improved Windows 8 support.
 - Improved Visual Studio 2012 support.
 - Added non-ASCII symbol support.
 - Added the total execution time to the logfile.
 - Added default suppressions for real bugs in the Visual Studio C
   and C++ libraries detected by Dr. Memory.
 - Various bug fixes.

The changes between version 1.5.1 and version 1.5.0 include:
 - Re-organized and improved the documentation.
 - Added Visual Studio External Tool support (-visual_studio option)
 - Added experimental support for Windows 8.  However, false positives
   may occur on graphical or networked applications on Windows 8.
   Future releases will add full support.
 - Added Dr. Syscall library and Dr. Memory Framework for building other
   tools from Dr. Memory's feature base.  Future releases will add other
   libraries and add further tool-building support.
 - Added \p drstrace, an initial version of a system call tracer.
   Future releases will expand its capabilities.
 - Added heuristics to distinguish substrings that look like pointers and
   thus reduce false negatives in leak reporting.  See
   the -strings_vs_pointers option.
 - Added a new, experimental lightweight mode: \p -unaddr_only.
 - Added non-ASCII application support.
 - Added option \p -show_duplicates to list details on duplicate errors.
 - Eliminated reliance on the WDK/DDK when building from sources.
 - Fixed PATH limit issue with the NSIS installer.
 - Reduced false positives from bitfields.
 - Fixed problems with debug C libraries on Windows.
 - Fixed some problems in callstack walking.
 - Various bug fixes.

The changes between version 1.5.0 and 1.4.6 include:
 - Compatibility change: GDI usage errors are no longer of type WARNING
   but have their own type GDI USAGE ERROR.  This affects any existing
   suppressions.
 - Added online symbols for Linux, which enables -results_to_stderr.  The
   -aggregate and -skip_results post-processing features are temporarily
   disabled until a future release adds them for both Windows and Linux.
 - Added support for the Microsoft Visual Studio dynamic debug C library
 - Added automated retrieval of certain system library debug files
   at the end of a run for better error reports in future runs.
 - Added -log_suppressed_errors option
 - Added -show_duplicates option
 - Support wildcards in instruction lines in suppressions
 - Improved callstack walking
 - Added -callstack_exe_hide
 - Eliminated most false positives with bitwise operations
 - Various bug fixes

The changes between version 1.4.6 and 1.4.5 include:
 - Added MinGW support
 - Added GDI API usage error reports
 - Added -light mode that does not detect uninitialized reads
   or leaks but is more performant
 - Added -pause_at_error option
 - Added mod!... suppression wildcard
 - Reduced false positives from graphical operations
 - Various performance improvements
 - Various bug fixes

The changes between version 1.4.5 and 1.4.4 include:
 - The tool now detects mismatched use of malloc/new/new[] vs
   free/delete/delete[]
 - Added a script to convert Memcheck suppression files to
   the Dr. Memory format.
 - Performance improvements on large applications via a symbol cache
 - Renamed the -check_cmps option to -check_uninit_cmps
 - Renamed the -check_non_moves option to -check_uninit_non_moves
 - Various bug fixes

The changes between version 1.4.4 and 1.4.3 include:
 - Fix for missing output in cmd on Win7 SP1
 - Check for /MDd and abort

The changes between version 1.4.3 and 1.4.2 include:
 - Changed the default callstack printing style and added control
   over the style via the -callstack_style runtime option
 - On Windows, printing errors to stderr is now on by default
 - On Windows, several options now control simplifying callstacks:
   -callstack_truncate_below, -callstack_srcfile_prefix,
   -callstack_modname_hide, -callstack_srcfile_hide.
   The -brief option sets these to common defaults and hides
   absolute addresses for simpler reports.
 - Callstack walking in presence of FPO is now supported.
 - Added a new mode that is several times faster but does not check
   for uninitialized reads: -no_check_uninitialized.
 - Thread creation stack traces are now available in the global.pid.log
   file for identifying threads.
 - Suppressions can take names, and the list of used suppressions is
   printed out in the results file.
 - Increased default -redzone_size to 16
 - Suppression can take instruction specifiers for narrower scope.
 - The Valgrind Memcheck suppression format is supported for legacy
   suppression files: however, C++ symbols must be de-mangled at this time.
 - Various bug fixes

The changes between version 1.4.2 and 1.4.1 include:
 - Initial graphical system call support to reduce false positives
 - Various bug fixes

The changes between version 1.4.1 and 1.4.0 include:
 - Full Windows 7 support
 - Various bug fixes

The changes between version 1.4.0 and 1.3.1 include:
 - Initial Windows 7 support
 - Performance improvements
 - Various bug fixes
 - Release build is used by default

The changes between version 1.3.1 and 1.3.0 include:
 - Performance improvements
 - Various bug fixes

The changes between version 1.3.0 and 1.2.1 include:
 - Enabled -check_leaks and -possible_leaks by default (Issue 8)
 - Improved suppression support: support for vertical wildcards "..."
 - Locate target app on path on Linux (Issue 33)
 - Various bug fixes

The changes between version 1.2.1 and 1.2.0 include:
 - Fix bug in symbol lookup causing debug build asserts

The changes between version 1.2.0 and 1.1.0 include:
 - Avoid false positives and false negatives when using debug versions of
   msvcrt, whose own debugging facilities conflicted with Dr. Memory's
 - Added -perturb feature that uses random delays to attempt to trigger
   data races such as use-after-free accesses, which Dr. Memory will
   immediately detect
 - Separate indirect leaks from direct leaks
 - Added -version option to front end
 - Generalized "invalid free" to "invalid heap argument"
 - Improved performance of many instruction types including string instructions
 - Improved performance of heap routines accessing heap headers
 - Improved performance of stack adjustments
 - Improved performance of shadow table accesses
 - Improved performance of hashtables via dynamic resizing
 - Display messages in cmd window, where DynamoRIO has trouble printing
 - Switch to online symbol processing on Windows, greatly simplifying the
   Windows design and making it more robust by eliminating perl entirely
 - Eliminate need for admin privileges to run on Windows
 - Added wildcard support to suppressions
 - Various bug fixes

The changes between version 1.1.0 and 1.0.1 include:

 - Eliminated common C++ cases of false positives in possible leaks
 - Report additional information on unaddressable errors: list the nearest
   malloc chunks above and below, and whether the access was to freed memory
 - Report timestamp and thread id of reported errors
 - Added -leaks_only feature for low-overhead leak checking
 - Improved support for heaps used as stacks when such stacks are small
   and are adjacent to non-stack data
 - Improved Linux system call parameter handling to reduce false positives
 - Added default suppression file
 - Added -aggregate option to combine error listings and eliminate
   duplicates among a set of processes
 - Report the total number of leaked bytes
 - Perform error duplication checks in the client
 - Reduce memory usage of callstacks stored on each malloc
 - Eliminate false positives from libc string routines by replacing them
 - Switch to true reachability-based leak detection, trigger-able from a
   nudge at any time during a run
 - Split possible leaks from certain leaks
 - Improved documentation
 - Improve performance of consecutive similar memory references
 - Improve performance of 64K-boundary-crossing stack adjustments
 - Many other performance improvements
 - Many bug fixes

***************************************************************************
\htmlonly
<table width=100% bgcolor="#000000" cellspacing=0 cellpadding=2 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td><table width=100% bgcolor="#0000C0" cellspacing=0 cellpadding=1 border=0>
  <tr><td></td></tr></table></td></tr></table></td></tr></table>
\endhtmlonly
\section sec_limits Limitations

Dr. Memory is still under development.  It has some missing features and undoubtedly
some bugs.  The missing features include:

 - Uninitialized read checking is not yet supported for 64-bit applications
   nor for ARM platforms.
 - Windows system call parameters are not all known, which can
   result in false positives and false negatives, especially on graphical
   applications on more recent versions of Windows.
   Often, these false positives are solely in system library code.
   Dr. Memory attempts to separate such errors into potential_errors.txt.
 - Definedness is tracked at the byte level, not at the bit level,
   which when bitfields are in use can lead to false positives.
 - Race corner cases:
   - Pathological races between mallocs and frees can result in Dr. Memory's
     shadow memory structures becoming mis-aligned with subsequent false
     positives.  However, such a scenario will always be preceded by
     an invalid free error.
   - General races between memory accesses and Dr. Memory's shadow memory
     can occur but errors will only occur with the presence of erroneous
     race conditions in the application.
   - This release can produce false positives if multiple threads write
     to adjacent bytes simultaneously.  Future releases will provide
     options to trade off performance, memory usage, and accuracy.

\subsection sec_interop Interoperability

Dr. Memory may have conflicts with security software or with other software
that injects into the same process as Dr. Memory.  There are known
interoperability problems with some anti-virus applications, including
Avast 8.0.

****************************************************************************
****************************************************************************
*/