Various document updates

documentation/building/linux-instructions.md

@@ -78,11 +78,11 @@ Install the required packages:
 
 See the section below on how to clone, build and test the repo.
 
-#### Alpine 3.6 ####
+#### Alpine 3.8/3.9 ####
 
-Currently there is no lldb that works on Alpine.
+Install the required packages:
 
-Issue https://github.com/dotnet/diagnostics/issues/73
+    sudo apk add autoconf bash clang clang-dev cmake coreutils curl gcc gettext-dev git icu-dev krb5-dev libunwind-dev llvm make openssl openssl-dev python which
 
 #### CentOS 6 ####
 

documentation/building/official-build-instructions.md

@@ -3,6 +3,15 @@ Official Build Instructions
 
 WARNING: These instructions will only work internally at Microsoft.
 
-To kick off an official build, go to this build definition: https://devdiv.visualstudio.com/DevDiv/_build?definitionId=9462 and queue build leaving all the build variables as their defaults.
+To kick off an official build, go to this build definition: https://dev.azure.com/dnceng/internal/_build?definitionId=528.
 
 This signs and publishes dotnet-dump, dotnet-sos, dotnet-trace, dotnet-counters and Microsoft.Diagnostic.TestHepers packages to https://dotnetfeed.blob.core.windows.net/dotnet-core feed.
+
+To release the latest tools:
+
+1) Merge all the commits for this release from the master branch to the release/3.0 branch.
+2) Kick off an official build from the release/3.0 branch.
+3) Change all the package version references in the documentation folder to this official build's package version. Commit/merge to master and release/3.0.
+4) Download the above packages from the successful official build under "Artifacts" -> "packages".
+5) Upload these packages to nuget.org.
+6) Create a new "release" in the [releases](https://github.com/dotnet/diagnostics/releases) diagnostics repo release tab with the package version (not the official build id) as the "tag". Add any release notes about known issues, issues fixed and new features.

documentation/debugging-coredump.md

@@ -7,6 +7,8 @@ Dumps created with gdb or gcore do not have all the managed state so various SOS
 
 ### Getting symbols ###
 
+Because SOS now has symbol download support, this step can be skipped if the matching version of the "host" program is available on the machine loading the dump. Usually the host program is "dotnet" but each .NET Core SDK has a different version.
+
 First install the dotnet CLI symbol tool. This only needs to be down once. See this [link](https://github.com/dotnet/symstore/tree/master/src/dotnet-symbol#install) for more details.
 
     ~$ dotnet tool install -g dotnet-symbol
@@ -30,15 +32,24 @@ See the instructions on the main [README.md](../README.md) under "Installing SOS
 
 ### Launch lldb under Linux ###
 
-    ~$ lldb
+    ~$ lldb --core /tmp/dump/coredump.32232 <host-program>
-    (lldb) target create --core /tmp/dump/coredump.32232
+    Core file '/tmp/dump/coredump.32232' (x86_64) was loaded.
+    (lldb)
+
+The `<host-program>` is the native program that started the .NET Core application. It is usually `dotnet` unless the application is self contained and then it is the name of application without the .dll.
+
+Add the directory with the core dump and symbols to the symbol search path:
+
+     (lldb) setsymbolserver -directory /tmp/dump
+     Added symbol directory path: /tmp/dump
+     (lldb)
 
 Even if the core dump was not generated on this machine, the native and managed .NET Core symbols should be available along with all the SOS commands.
 
 ### Launch lldb under MacOS ###
 
-    ~$ lldb
+    ~$ lldb --core /cores/core.32232 <host-program>
-    (lldb) target create --core /cores/core.32232
+    (lldb)
 
 The MacOS lldb has a bug that prevents SOS clrstack from properly working. Because of this bug SOS can't properly match the lldb native with with the managed thread OSID displayed by `clrthreads`. The `setsostid` command is a work around for this lldb bug. This command maps the OSID from this command:
 

documentation/sos-debugging-extension.md

@@ -110,7 +110,7 @@ importance. Shortcut names for popular functions are listed in parenthesis. Type
 |**PrintException** [**-nested**] [**-lines**] [\<*Exception object address*>]<br /><br /> -or-<br /><br /> **PE** [**-nested**] [\<*Exception object address*>]|Displays and formats fields of any object derived from the <xref:System.Exception> class at the specified address. If you do not specify an address, the **PrintException** command displays the last exception thrown on the current thread.<br /><br /> The **-nested** option displays details about nested exception objects.<br /><br /> The **-lines** option displays source information, if available.<br /><br /> You can use this command to format and view the `_stackTrace` field, which is a binary array.|
 |**SyncBlk** [**-all** &#124; \<*syncblk number*>]|Displays the specified `SyncBlock` structure or all `SyncBlock` structures.  If you do not pass any arguments, the **SyncBlk** command displays the `SyncBlock` structure corresponding to objects that are owned by a thread.<br /><br /> A `SyncBlock` structure is a container for extra information that does not need to be created for every object. It can hold COM interop data, hash codes, and locking information for thread-safe operations.|
 |**SOSFlush**|Flushes an internal SOS cache.|
-|**SetSymbolServer** [**-ms**] [**-disable**] [**-log**] [**-cache** \<cache-path>] [**-loadsymbols**] [\<symbol-server-URL>]|Enables the symbol server downloading support.<br/><br/>The **-ms** option enables downloading from the public Microsoft symbol server.<br/><br/>The **-disable** option turns on the symbol download support.<br/><br/>The **-cache** \<cache-path> option specifies a symbol cache directory. The default is $HOME/.dotnet/symbolcache if not specified.<br/><br/>The **-log** option enables symbol download logging.<br/><br/>The **-loadsymbols** option attempts to download the native .NET Core symbols for the runtime.|
+|**SetSymbolServer** [**-ms**] [**-disable**] [**-log**] [**-loadsymbols**] [**-cache** \<cache-path>] [**-directory** \<search-directory>] [**-sympath** \<windows-symbol-path>] [\<symbol-server-URL>]|Enables the symbol server downloading support.<br/><br/>The **-ms** option enables downloading from the public Microsoft symbol server.<br/><br/>The **-disable** option turns on the symbol download support.<br/><br/>The **-cache** \<cache-path> option specifies a symbol cache directory. The default is $HOME/.dotnet/symbolcache if not specified.<br/><br/>The **-directory** option add a path to search for symbols. Can be more than one.<br/><br/>The **-sympath** option adds server, cache and directory paths in the Windows symbol path format.<br/><br/>The **-log** option enables symbol download logging.<br/><br/>The **-loadsymbols** option attempts to download the native .NET Core symbols for the runtime.|
 |**Token2EE** \<*module name*> \<*token*>|Turns the specified metadata token in the specified module into a `MethodTable` structure or `MethodDesc` structure.<br /><br /> You can pass `*` for the module name parameter to find what that token maps to in every loaded managed module. You can also pass the debugger's name for a module, such as `mscorlib` or `image00400000`.|
 |**Threads** (**clrthreads**) [**-live**] [**-special**]|Displays all managed threads in the process.<br /><br /> The **Threads** command displays the debugger shorthand ID, the CLR thread ID, and the operating system thread ID.  Additionally, the **Threads** command displays a Domain column that indicates the application domain in which a thread is executing, an APT column that displays the COM apartment mode, and an Exception column that displays the last exception thrown in the thread.<br /><br /> The **-live** option displays threads associated with a live thread.<br /><br /> The **-special** option displays all special threads created by the CLR. Special threads include garbage collection threads (in concurrent and server garbage collection), debugger helper threads, finalizer threads, <xref:System.AppDomain> unload threads, and thread pool timer threads.|
 |**ThreadState \<** *State value field* **>**|Displays the state of the thread. The `value` parameter is the value of the `State` field in the **Threads** report output.|

src/SOS/Strike/sosdocs.txt

@@ -411,7 +411,7 @@ followed by a report listing all the types found, their size and number:
 	...
 
 "Free" objects are simply regions of space the garbage collector can use later.
-If 30% or more of the heap contains "Free" objects, the process may suffer from
+If 30%% or more of the heap contains "Free" objects, the process may suffer from
 heap fragmentation. This is usually caused by pinning objects for a long time 
 combined with a high rate of allocation. Here is example output where !DumpHeap
 provides a warning about fragmentation:
@@ -815,6 +815,8 @@ COMMAND: threads.
            output. Example of special threads include: GC threads (in 
            concurrent GC and server GC), Debugger helper threads, Finalizer 
            threads, AppDomain Unload threads, and Threadpool timer threads.
+-managedexception: optional. Sets the current thread to first thread with 
+                   an managed exception for the "printexception" command.
 
 Each thread has many attributes, many of which can be ignored. The important 
 ones are discussed below:
@@ -846,7 +848,7 @@ exceptions by switching to the thread in question, and running
 \\
 
 COMMAND: clrstack.
-!CLRStack [-a] [-l] [-p] [-n] [-f]
+!CLRStack [-a] [-l] [-p] [-n] [-f] [-r] [-all]
 !CLRStack [-a] [-l] [-p] [-i] [variable name] [frame]
 
 CLRStack attempts to provide a true stack trace for managed code only. It is
@@ -861,6 +863,10 @@ The -f option (full mode) displays the native frames intermixing them with
 the managed frames and the assembly name and function offset for the managed
 frames.
 
+The -r option dumps the registers for each stack frame.
+
+The -all option dumps all the managed threads' stacks.
+
 If the debugger has the option SYMOPT_LOAD_LINES specified (either by the
 .lines or .symopt commands), SOS will look up the symbols for every managed 
 frame and if successful will display the corresponding source file name and 
@@ -1992,8 +1998,8 @@ Sample output:
 	Total    337556       24           306968       8800        
 
 	Free space:                                                 Percentage
-	Heap0    28           12           12           64          SOH:  0% LOH:  0%
+	Heap0    28           12           12           64          SOH:  0%% LOH:  0%%
-	Heap1    104          12           12           16          SOH:  0% LOH:100%
+	Heap1    104          12           12           16          SOH:  0%% LOH:100%%
 	Total    132          24           24           80          
 
 	0:002> !heapstat -inclUnrooted
@@ -2003,13 +2009,13 @@ Sample output:
 	Total    337556       24           306968       8800        
 
 	Free space:                                                 Percentage
-	Heap0    28           12           12           64          SOH:  0% LOH:  0%
+	Heap0    28           12           12           64          SOH:  0%% LOH:  0%%
-	Heap1    104          12           12           16          SOH:  0% LOH:100%
+	Heap1    104          12           12           16          SOH:  0%% LOH:100%%
 	Total    132          24           24           80          
 
 	Unrooted objects:                                           Percentage
-	Heap0    152212       0            306196       0           SOH: 94% LOH:  0%
+	Heap0    152212       0            306196       0           SOH: 94%% LOH:  0%%
-	Heap1    155704       0            0            0           SOH: 97% LOH:  0%
+	Heap1    155704       0            0            0           SOH: 97%% LOH:  0%%
 	Total    307916       0            306196       0           
 
 The percentage column contains a breakout of free or unrooted bytes to total bytes.
@@ -2051,7 +2057,7 @@ is if the system is running out physical memory (+ page file if you have one) so
 GC can not commit memory it needs. You can look at these scenarios by using performance
 counters or debugger commands. For example for the former scenario the "!address 
 -summary" debugger command will show you the largest free region in the VM. For
-the latter scenario you can look at the "Memory\% Committed Bytes In Use" see
+the latter scenario you can look at the "Memory%% Committed Bytes In Use" see
 if you are running low on commit space. One important thing to keep in mind is
 when you do this kind of memory analysis it could an aftereffect and doesn't 
 completely agree with what this command tells you, in which case the command should
@@ -2605,14 +2611,19 @@ You can use the "dotnet --info" in a command shell to find the path of an instal
 \\
 
 COMMAND: setsymbolserver.
-SetSymbolServer [-ms] [-mi] [-disable] [-log] [-cache <cache-path>] [<symbol-server-URL>]
+SetSymbolServer [-ms] [-mi] [-disable] [-log] [-cache <cache-path>] [-directory <search-directory>] [<symbol-server-URL>]
 
 -ms - Use the public Microsoft symbol server.
 -mi - Use the internal symweb symbol server.
 -disable - Disable symbol download support.
--cache - Specific a symbol cache directory. The default is %TEMP%\SymbolCache if not specified.
+-directory - Directory to search for symbols. Can be more than one.
+-cache - Specific a symbol cache directory. The default is %%TEMP%%\SymbolCache if not specified.
 -log - Enable symbol download logging.
 <symbol-server-URL> - Symbol server URL.
 
 This commands enables symbol server support for portable PDBs in SOS. If the .sympath is set, this
-symbol server support is automatically enabled.
+symbol server support is automatically enabled.
+
+To disable downloading or clear the current SOS symbol settings allowing new symbol paths to be set:
+
+    0:000> !setsymbolserver -disable

src/SOS/Strike/sosdocsunix.txt

@@ -577,6 +577,8 @@ Threads (clrthreads) lists all the mananaged threads in the process.
            output. Example of special threads include: GC threads (in 
            concurrent GC and server GC), Debugger helper threads, Finalizer 
            threads, AppDomain Unload threads, and Threadpool timer threads.
+-managedexception: optional. Sets the current thread to first thread with 
+                   an managed exception for the "printexception" command.
 
 Each thread has many attributes, many of which can be ignored. The important 
 ones are discussed below:
@@ -623,6 +625,10 @@ The -f option (full mode) displays the native frames intermixing them with
 the managed frames and the assembly name and function offset for the managed
 frames.
 
+The -r option dumps the registers for each stack frame.
+
+The -all option dumps all the managed threads' stacks.
+
 If the debugger has the option SYMOPT_LOAD_LINES specified (either by the
 .lines or .symopt commands), SOS will look up the symbols for every managed 
 frame and if successful will display the corresponding source file name and 
@@ -1887,11 +1893,14 @@ You can use the "dotnet --info" in a command shell to find the path of an instal
 
 COMMAND: setsymbolserver.
 COMMAND: loadsymbols.
-SetSymbolServer [-ms] [-disable] [-log] [-cache <cache-path>] [-loadsymbols] [<symbol-server-URL>]
+COMMAND: sympath.
+SetSymbolServer [-ms] [-disable] [-log]  [-loadsymbols] [-cache <cache-path>] [-directory <search-directory>] [-sympath <windows-symbol-path>] [<symbol-server-URL>]
 
 -ms - Use the public Microsoft symbol server.
 -disable - Disable symbol download support.
+-directory - Directory to search for symbols. Can be more than one.
 -cache - Specific a symbol cache directory. The default is $HOME/.dotnet/symbolcache if not specified.
+-sympath - Add server, cache and directory paths in the Windows symbol path format.
 -log - Enable symbol download logging.
 -loadsymbols - Attempts to download the native .NET Core symbols for the runtime
 <symbol-server-URL> - Symbol server URL.
@@ -1905,10 +1914,21 @@ To enable downloading symbols from the Microsoft symbol server:
 
 This command may take some time without any output while it attempts to download the symbol files. 
 
-To disable download:
+To disable downloading or clear the current SOS symbol settings allowing new symbol paths to be set:
 
     (lldb) setsymbolserver -disable
 
+To add a directory to search for symbols:
+
+    (lldb) setsymbolserver -directory /home/mikem/symbols
+
+This command can be used so the module/symbol file structure does not have to match the machine 
+file structure that the core dump was generated.
+
+The "sympath" option/command alias allows Windows symbol paths to be parsed:
+
+    (lldb) sympath "/home/mikem/localsymbols;srv*/home/mikem/symbolcache*https://msdl.microsoft.com/download/symbols".
+
 To clear the default cache run "rm -r $HOME/.dotnet/symbolcache" in a command shell.
 
 If you receive an error like the one below on a core dump, you need to set the .NET Core