further top level edits

JimRadigan · JimRadigan · commit e5c87555eb31 · 2021-02-15T14:45:11.000-08:00
diff --git a/docs/cpp/ASAN/asan-jims-bone-yard.md b/docs/cpp/ASAN/asan-jims-bone-yard.md
@@ -0,0 +1,76 @@
+
+## STUFF TO KEEP -- remove later!!!!!
+
+## Viewing Address Saniziter Errors ##
+
+There are three ways your code can generate error reports:
+
+- [Command line](#Command-line)
+- [IDE](#IDE)
+- [Snapshot files](#Snapshot-file)
+
+These types of reports can be generated for many types of [errors found at runtime](#Error-types). 
+
+### Example 
+
+!!! Jim, I think we need a simpler example here. !!!
+The following source code is **safe by coincidence**. It will **not** fail at runtime. The Windows 10, 16.9 version of the C runtime, will pad the 13 bytes requested, in order to facilitate alignment for subsequent calls to alloca. 
+
+```cpp
+    int x = 13;
+
+    void main()
+    {
+        int *cc; 
+        int i;
+        int k = 17;
+
+         __try{
+
+            cc = (int*)_alloca(x);  // Cast pointer to 1-byte to pointer to 4-bytes
+            if (((int)cc) & 0x3)
+                fail = 1;
+
+            cc[0] = 1;
+            cc[1] = 1;
+            cc[2] = 2;
+            cc[3] = 3;  //Boom! Only caught with -fsanitize=address
+```
+
+Padding and alignment is platform dependent. It's a function of the CRT used on a particular operating system and whether the target is 32-bits, or 64-bits. The above example, or a slightly modified version, could produce different runtime results on Linux macOS or Android.
+
+### Command line ###
+
+If you run from the command line then your binary will emit formatted text reports to the screen. Consider the over layed, red boxes which high light four (4) key pieces of information from the error in the _alloca example.
+
+![Command line: alloca](media\CommandLine-alloca.png)
+
+From top to bottom
+
+1.) A write of 4 bytes (32-bits) went beyond the stack allocation the program explicitly requested.
+
+2.) That store was produced from line 47 in the function "main"
+
+3.) The type of error was a dynamic stack buffer overflow for the 13 bytes explicitly requested.
+
+4.) The [**shadow bytes**](.\asan-shadowbytes.md) that correspond to the address used in the overflowing store, indicate 13 bytes (8 + 5) were explicitly allocated for the alloca.
+
+**Note:**  The call stack is converted to function names through the [LLVM symbolizer](https://llvm.org/docs/CommandGuide/llvm-symbolizer.html). The Address Sanitizer creates the rest of of the report based on its context, the shadow bytes, and meta-data the compiler produces.
+
+### IDE
+
+By simply recompiling with -fsanitze=address and invoking Visual Studio from the command line, the IDE will automatically map a pop up to the line and column causing the error.
+
+                                     devenv /debugexe MyApp.exe arg1 arg2 ... argn
+
+Consider the following error found in our cached version of spec2k6\povray where the program allocates 24-bytes but only frees 8-bytes. The details for where the allocation and free took place are in the **output pane** of the Visual Studio screen shot immediately below:
+
+![IDE: povray](media\povray.png)
+
+
+### VCASan library
+
+The flag -fsanitize=address automatically links a new static library to your .EXE or .DLL. This static library will automatically produce:
+
+- In memory meta-data for directly interfacing with the VS IDE, [while debugging](#Error-types).
+- An optional [snap shot file](#Snapshot-files) with the same IDE meta-data.
diff --git a/docs/cpp/ASAN/asan-offline-address-sanitizer-crash-dumps.md b/docs/cpp/ASAN/asan-offline-address-sanitizer-crash-dumps.md
@@ -0,0 +1,22 @@
+# Offline Address Sanitizer crash dumps
+
+## Enable Cloud and Distributed testing
+
+We've made it very simple to store an Address Sanitizer runtime error in a new type of crash dump file.This functionality is simply enabled with an environment variable.
+
+  `set ASAN_SAVE_DUMPS="MyFileName.dmpx"`
+
+## How it works
+
+Address Sanitizer exceptions are thrown from inside the runtime, due to many [error types](#errors) detected at runtime. When run from the command line the Address Sanitizer runtime produces text output with error information. When run from the Visual Studio IDE the debugger displays the error information.
+
+Upon error, your application will produce MyFileName.dmpx which is a [dump file](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/proc_snap/export-a-process-snapshot-to-a-file) that can be opened and debugged using Visual Studio.
+
+**Note** that like all other dump files, [debugging symbols](https://docs.microsoft.com/en-us/windows/win32/dxtecharts/debugging-with-symbols) must be available and must match the version of the source compiled.
+
+## Example
+
+## Command line build and run
+
+## Viewing in Visual Studio
+
diff --git a/docs/cpp/ASAN/asan-top-level.md b/docs/cpp/ASAN/asan-top-level.md
@@ -24,9 +24,9 @@ The Address Sanitizer is a compiler and runtime runtime [introduced by Google](h
 
 Compiling with `-fsanitize=address` is a powerful alternative to both [/RTC](https://docs.microsoft.com/en-us/cpp/build/reference/rtc-run-time-error-checks?view=msvc-160), and [/analyze](https://docs.microsoft.com/en-us/cpp/code-quality/code-analysis-for-c-cpp-overview?view=msvc-160). It provides run-time bug-finding technologies which leverage your existing build systems and existing test assets.
 
-We've also extended the basic Windows executable file. By setting a new environment variable via **`set ASAN_SAVE_DUMPS=”MyFileName.dmpx”`** your program will create a new type of crash dump file that will contain extra meta-data for post-mortem debugging. These dump files can be displayed off-line, with Visual Studio's new debugger IDE. These dump files can be an enabler for work flows requiring:
+We also link a new library to your executable. By setting a new environment variable via **`set ASAN_SAVE_DUMPS=”MyFileName.dmpx”`** your program will create a new type of crash dump file that will contain extra meta-data for post-mortem debugging. These dump files can be displayed off-line, with Visual Studio's new debugger IDE. These dump files are an enabler for:
 
-- On-premises testing
+- On-premise single machine or distributed testing
 - Cloud based workflows for testing
 
 These test systems can store the dump files, with **precisely diagnosed bugs**, for later viewing super imposed on your source code in the IDE.
@@ -37,7 +37,7 @@ Simply  [**install the Address Sanitizer functionality**]().
 
 After installing you can build your executables with the `-fsanitize=address`compiler switch using any of the following:
 
-   - a command line
+   - Command line
    - Visual Studio project system 
    - Visual Studio Cmake make integration
 
@@ -53,7 +53,6 @@ Microsoft recommends using the Address Sanitizer in these **three standard workf
     - Visual Studio - [Project system](#Using-the-Address-Sanitizer-from-Visual-Studio)
     - Visual Studio - [CMake]([CMake](#Using-the-Address-Sanitizer-from-Visual-Studio:-CMake))
 
-    
 - **CI/CD** - continuous integration / continuous development
     - Error reporting - [New Address Sanitizer dump files]()
 
@@ -67,9 +66,9 @@ This article will cover the information needed to enable the three workflows lis
 
 ## Using the Address Sanitizer from a Developer Command Prompt
 
-Compile with `-fsanitize=address` to enable Address Sanitizer. The compiler flag `-fsanitize=address` is compatible with all existing C++ or C optimization levels (e.g., /Od, /O1, /O2, /O2 /GL and PGO), works with static and dynamic CRTs (e.g. /MD, /MDd, /MT, /MTd) and can be used to create a .EXE or .DLL. Debug information is required for the Address Sanitizer runtime to print correct call stacks on errors; In this example we pass `-/Zi`.
+Compile with `-fsanitize=address` to enable Address Sanitizer. The compiler flag `-fsanitize=address` is compatible with all existing C++ or C optimization levels (e.g., /Od, /O1, /O2, /O2 /GL and PGO), works with static and dynamic CRTs (e.g. /MD, /MDd, /MT, /MTd) and can be used to create an .EXE or .DLL. Debug information is required for optimal formatting of call stacks. In this example we explicitly pass `-/Zi`.
 
-The Address Sanitizer libraries (.lib files) will be linked in for you. For more detail, and for guidelines on partitioned build systems, see [building to target the Address Sanitizer runtime.](.\ASan-building.md).
+The Address Sanitizer libraries (.lib files) will be linked for you. For more detail, and for guidelines on partitioned build systems, see [building to target the Address Sanitizer runtime.](.\ASan-building.md).
 
 ### Example - basic global buffer overflow:
 
@@ -157,17 +156,15 @@ The following screen shot captures the error from the CMake build.
 
 ![cmake-F5-runt](.\MEDIA\asan-cmake-F5-error.PNG) 
 
-## Offline Address Sanitizer crash dumps
+## Address Sanitizer crash dumps - cloud and distributed workflows
 
-Address Sanitizer exceptions are triggered one of the many [errors](#errors) are detected at runtime. When run from the command line the Address Sanitizer runtime produces text output with error information. When run from the Visual Studio IDE the debugger displays the error information.
+To produce a new type of dump file which can be viewed in Visual Studio on another machine at a later date:
 
-To produce a dump file of the error which can be debugged offline, set an environment variable which is consumed by the Address Sanitizer runtime. 
+                                `set ASAN_SAVE_DUMPS="MyFileName.dmpx"`
 
-`set ASAN_SAVE_DUMPS="MyFileName.dmpx"`
+As of Visual Studio 16.9 will be able to display the **precisely diagnosed error**, stored in MyFileName.dmpx, with your source code.
 
-Upon error, your application will produce MyFileName.dmpx which is a [dump file](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/proc_snap/export-a-process-snapshot-to-a-file) that can be opened and debugged using Visual Studio.
-
-**Note** that like all other dump files, [debugging symbols](https://docs.microsoft.com/en-us/windows/win32/dxtecharts/debugging-with-symbols) must be available and must match the version of the source compiled.
+[This new crash dump functionality](.\asan-offline-address-sanitizer-crash-dumps.md) is an enabler for cloud based workflows and distributed testing.
 
 ## Error types
 
@@ -191,14 +188,23 @@ The following list of runtime errors can be exposed when you run your binaries c
 - [use-after-poison](.\examples-use-after-poison.md)
 - [alloc-dealloc-mismatch](.\examples-alloc-dealloc-mismatch.md)
 
-## Differences with Clang
+## Differences with Clang 12.0
 
 We differ in two functional areas:
 
 - **stack-use-after-scope** - this is on by default and can't be turned off.
 - **stack-use-after-return** - this is not available by just setting ASAN_OPTIONS
 
-See [Building for the Address Sanitizer with MSVC](.\asan-building.md).These decisions were made to reduce the test matrix used to ship this first version.
+These decisions were made to reduce the test matrix used to ship this first version.
+
+We did NOT ship features that could lead to false positives in this first release. That discipline enforced an effective testing integrity necessary when considering inter-op with years of exiting code. The following functionalities will be shipped later:
+
+ - [Initialization Order Fiasco](https://github.com/google/sanitizers/wiki/AddressSanitizerInitializationOrderFiasco)
+ - [Intra Object Overflow](https://github.com/google/sanitizers/wiki/AddressSanitizerIntraObjectOverflow)
+ - [Container Overflow](https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow)
+ - [Pointer Subtraction/Comparison](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html)
+
+See [Building for the Address Sanitizer with MSVC](.\asan-building.md) for further details.
 
 ## Existing industry documentation
 
@@ -210,90 +216,14 @@ Extensive documentation already exists for these language and platform dependent
 
 This seminal paper on the [Address Sanitizer](https://www.usenix.org/system/files/conference/atc12/atc12-final39.pdf) describes the implementation.
 
-!!! is this where we should mention that we don't implement the entire complete feature set? !!!
-
 ## See also
 
-- [Building for the Address Sanitizer with MSVC](.\asan-building.md)
+- [Building for the Address Sanitizer with Visual Studio](.\asan-building.md)
 
 - [Address Sanitizer runtime](.\address-sanitizer-runtime.md)
 
 These structure all further details into the tools and the run times they target.
 
 ----
-
-## STUFF TO KEEP -- remove later!!!!!
-
-## Viewing Address Saniziter Errors ##
-
-There are three ways your code can generate error reports:
-
-- [Command line](#Command-line)
-- [IDE](#IDE)
-- [Snapshot files](#Snapshot-file)
-
-These types of reports can be generated for many types of [errors found at runtime](#Error-types). 
-
-### Example 
-
-!!! Jim, I think we need a simpler example here. !!!
-The following source code is **safe by coincidence**. It will **not** fail at runtime. The Windows 10, 16.9 version of the C runtime, will pad the 13 bytes requested, in order to facilitate alignment for subsequent calls to alloca. 
-
-```cpp
-    int x = 13;
-
-    void main()
-    {
-        int *cc; 
-        int i;
-        int k = 17;
-
-         __try{
-
-            cc = (int*)_alloca(x);  // Cast pointer to 1-byte to pointer to 4-bytes
-            if (((int)cc) & 0x3)
-                fail = 1;
-
-            cc[0] = 1;
-            cc[1] = 1;
-            cc[2] = 2;
-            cc[3] = 3;  //Boom! Only caught with -fsanitize=address
-```
-
-Padding and alignment is platform dependent. It's a function of the CRT used on a particular operating system and whether the target is 32-bits, or 64-bits. The above example, or a slightly modified version, could produce different runtime results on Linux macOS or Android.
-
-### Command line ###
-
-If you run from the command line then your binary will emit formatted text reports to the screen. Consider the over layed, red boxes which high light four (4) key pieces of information from the error in the _alloca example.
-
-![Command line: alloca](media\CommandLine-alloca.png)
-
-From top to bottom
-
-1.) A write of 4 bytes (32-bits) went beyond the stack allocation the program explicitly requested.
-
-2.) That store was produced from line 47 in the function "main"
-
-3.) The type of error was a dynamic stack buffer overflow for the 13 bytes explicitly requested.
-
-4.) The [**shadow bytes**](.\asan-shadowbytes.md) that correspond to the address used in the overflowing store, indicate 13 bytes (8 + 5) were explicitly allocated for the alloca.
-
-**Note:**  The call stack is converted to function names through the [LLVM symbolizer](https://llvm.org/docs/CommandGuide/llvm-symbolizer.html). The Address Sanitizer creates the rest of of the report based on its context, the shadow bytes, and meta-data the compiler produces.
-
-### IDE
-
-By simply recompiling with -fsanitze=address and invoking Visual Studio from the command line, the IDE will automatically map a pop up to the line and column causing the error.
-
-                                     devenv /debugexe MyApp.exe arg1 arg2 ... argn
-
-Consider the following error found in our cached version of spec2k6\povray where the program allocates 24-bytes but only frees 8-bytes. The details for where the allocation and free took place are in the **output pane** of the Visual Studio screen shot immediately below:
-
-![IDE: povray](media\povray.png)
-
-
-### VCASan library
-
-The flag -fsanitize=address automatically links a new static library to your .EXE or .DLL. This static library will automatically produce:
-
-- In memory meta-data for directly interfacing with the VS IDE, [while debugging](#Error-types).
-- An optional [snap shot file](#Snapshot-files) with the same IDE meta-data.
+----
+----
