Update Documents (#323)

Update documents

Remove Release notes on main README, add notes to dotnet-dump instructions, update coredump debugging instructions and add FAQ.

diff --git a/README.md b/README.md
index a216e00549ddf89b07b8a37e2ffa60d372a6c91f..3aa6de88e30d9a8ff3c454aa9b352e47b2bf6364 100644 (file)
--- a/README.md
+++ b/README.md
@@ -64,24 +64,9 @@ Before executing the "bt" command to dump native frames to load the native symbo
 
     (lldb) loadsymbols
 
-## Release Notes
-
-### dotnet-dump
-
-* Does not work on alpine and other MUSL based distros. Issue [#195](https://github.com/dotnet/diagnostics/issues/195).
-* Not supported ARM32 or ARM64. Issue [#168](https://github.com/dotnet/diagnostics/issues/168).
-* Not supported on MacOS.
-* Dump collection (dotnet dump collect) requires SYS\_PTRACE docker capabilities (--cap-add=SYS\_PTRACE or --privileged).
-* Dump analysis (dotnet dump analyze) in on Microsoft SDK Linux docker images throws `Unhandled exception: System.DllNotFoundException: Unable to load shared library 'libdl.so' or one of its dependencies` exception. Issue [#201](https://github.com/dotnet/diagnostics/issues/201). A work around is to install the "libc6-dev" package.
-* Dump analysis on Windows is not supported. Minidump collection is support. Issue [#157](https://github.com/dotnet/diagnostics/issues/157).
-
-### dotnet-sos
-
-* Does not work on alpine and other MUSL based distros. Issue [#195](https://github.com/dotnet/diagnostics/issues/195).
-* Not supported ARM32 or ARM64. Issue [#168](https://github.com/dotnet/diagnostics/issues/168).
-
 ## Useful Links
 
+* [FAQ](documentation/FAQ.md) - Frequently asked questions.
 * [The LLDB Debugger](http://lldb.llvm.org/index.html) - More information about lldb.
 * [SOS](https://msdn.microsoft.com/en-us/library/bb190764(v=vs.110).aspx) - More information about SOS.
 * [Debugging CoreCLR](https://github.com/dotnet/coreclr/blob/master/Documentation/building/debugging-instructions.md) - Instructions for debugging .NET Core and the CoreCLR runtime.

diff --git a/documentation/FAQ.md b/documentation/FAQ.md
new file mode 100644 (file)
index 0000000..36beae0
--- /dev/null
+++ b/documentation/FAQ.md
@@ -0,0 +1,9 @@
+Frequently Asked Questions
+==========================
+
+* If SOS or dotnet-dump analyze commands display "UNKNOWN" for types or functions names, your core dump may not have all the managed state. Dumps created with gdb or gcore have this problem. Linux system generated core dumps need the `coredump_filter` for the process to be set to at least 0x3f. See [core](http://man7.org/linux/man-pages/man5/core.5.html) for more information.
+
+* If dump collection (`dotnet dump collect` or `createdump`) doesn't work in a docker container, try adding the SYS\_TRACE capablity with --cap-add=SYS\_PTRACE or --privileged.
+ 
+* If dump analysis (`dotnet dump analyze`) on Microsoft .NET Core SDK Linux docker images fails with an`Unhandled exception: System.DllNotFoundException: Unable to load shared library 'libdl.so' or one of its dependencies` exception. Try installing the "libc6-dev" package.
+ 

diff --git a/documentation/building/windows-instructions.md b/documentation/building/windows-instructions.md
index e3106244f22f35584f7c2155df05688a972cac0e..7bcb83a94257948a81ca349dd425d9f483408817 100644 (file)
--- a/documentation/building/windows-instructions.md
+++ b/documentation/building/windows-instructions.md
@@ -99,6 +99,12 @@ the PATH variable persistent by going to  Control Panel -> System And Security -
 and select the 'Path' variable in the 'System variables' (if you want to change it for all users) or 'User variables' (if you only want
 to change it for the current user).  Simply edit the PATH variable's value and add the directory (with a semicolon separator).
 
+## Cross Compilation for ARM on Windows
+
+Building ARM for Windows can be done using cross compilation. Make sure the above requirements for building for arm32 are installed.
+
+    C:\diagnostics> build.cmd -architecture arm
+
 ## Building
 
 To build under Windows, run build.cmd from the root of the repository:

diff --git a/documentation/debugging-coredump.md b/documentation/debugging-coredump.md
index 8dba307539ca7215dd3dd60d3e7c1ca7040dc08e..4cc420d060934a941ef79f4f321b3b892174281b 100644 (file)
--- a/documentation/debugging-coredump.md
+++ b/documentation/debugging-coredump.md
@@ -3,6 +3,8 @@ Debugging Linux or MacOS Core Dump
 
 These instructions will lead you through getting symbols, loading and debugging a Linux or MacOS core dump. The best way to generate a core dump on Linux (only) is through the [createdump](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy) facility.
 
+Dumps created with gdb or gcore do not have all the managed state so various SOS or dotnet-dump commands may display "UNKNOWN" for type and function names. This can also happen with Linux system generated core dumps if the `coredump_filter` for the process is not set to at least 0x3f. See [core](http://man7.org/linux/man-pages/man5/core.5.html) for more information.
+
 ### Getting symbols ###
 
 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.
@@ -18,28 +20,24 @@ Download the modules and symbols for the core dump:
 
     ~$ dotnet symbol /tmp/dump/coredump.32232
 
-Remove (Linux only) the the libcoreclrtraceptprovider to avoid crashing lldb to avoid issue #[20205](https://github.com/dotnet/coreclr/issues/20205).
+### Install lldb ###
 
-    ~$ rm /tmp/dump/libcoreclrtraceptprovider.*
+See the instructions on the main [README.md](../README.md) under "Getting lldb".
 
-### Install lldb and build the diagnostic repo ###
+### Install the latest SOS ###
 
-See the instructions on the main README.md.
+See the instructions on the main [README.md](../README.md) under "Installing SOS".
 
 ### Launch lldb under Linux ###
 
     ~$ lldb
-    (lldb) plugin load $(HOME)/diagnostics/artifacts/bin/Linux.x64.Debug/libsosplugin.so
-    (lldb) sethostruntime /usr/share/dotnet/shared/Microsoft.NETCore.App/2.1.0
     (lldb) target create --core /tmp/dump/coredump.32232
 
-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. Note that path passed to the `sethostruntime` needs to be a .NET Core runtime installed on the machine. See `dotnet --info` for information on the installed runtimes and SDKs.
+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) plugin load $(HOME)/diagnostics/artifacts/bin/OSX.x64.Debug/libsosplugin.dylib
-    (lldb) sethostruntime /usr/share/dotnet/shared/Microsoft.NETCore.App/2.1.0
     (lldb) target create --core /tmp/dump/coredump.32232
 
 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.

diff --git a/documentation/dotnet-dump-instructions.md b/documentation/dotnet-dump-instructions.md
index a235104acd8762087ad351e231be5abef8105f59..e62aadb5eeb7a8169430dca027698d8536ae23a9 100644 (file)
--- a/documentation/dotnet-dump-instructions.md
+++ b/documentation/dotnet-dump-instructions.md
@@ -3,6 +3,8 @@ Dump collection and analysis utility (dotnet-dump)
 
 The dotnet-dump CLI global tool is way to collect and analyze Windows and Linux dumps all without any native debugger involved like lldb on Linux. This is important on platforms like Alpine Linux where a fully working lldb isn't available. The dotnet-dump tool will allow you to run SOS commands to analyze crashes and the GC, but it isn't a native debugger so things like displaying the native stack frames isn't supported.
 
+Currently not supported on macOS.
+
 ## Installing dotnet-dump
 
 The first step is to install the dotnet-dump CLI global tool. This requires at least the 2.1 or greater .NET Core SDK to be installed. If you see the error message `Tool 'dotnet-dump' is already installed`, you will need to uninstall the global tool (see below). 
@@ -11,6 +13,10 @@ The first step is to install the dotnet-dump CLI global tool. This requires at l
     You can invoke the tool using the following command: dotnet-dump
     Tool 'dotnet-dump' (version '1.0.3-preview5.19251.2') was successfully installed.
 
+If this is the first global tool installed or you get message `Could not execute because the specified command or file was not found.` you need to add `$HOME/.dotnet/tools` to your path.
+
+    export PATH=$PATH:$HOME/.dotnet/tools
+
 ## Using dotnet-dump
 
 The next step is to collect a dump. This can be skipped if a core dump has already been generated by the operating system or [createdump](https://github.com/dotnet/coreclr/blob/master/Documentation/botr/xplat-minidump-generation.md#configurationpolicy) on Linux.
@@ -22,6 +28,8 @@ On Linux, the runtime version must be 3.0 or greater.
     Written 98983936 bytes (24166 pages) to core file
     Complete
 
+If you are running under docker, dump collection requires SYS_PTRACE docker capabilities (--cap-add=SYS_PTRACE or --privileged).
+
 Now analyze the core dump. Only works on Linux for this preview.
 
     $ dotnet-dump analyze ./core_20190226_135850
@@ -105,6 +113,8 @@ To display the help:
       setsymbolserver <arguments>          Enables the symbol server support
       soshelp <arguments>                  Displays all available commands when no parameter is specified, or displays detailed help information about the specified command. soshelp <command>
 
+This command on Microsoft .NET Core SDK Linux docker images can throw `Unhandled exception: System.DllNotFoundException: Unable to load shared library 'libdl.so' or one of its dependencies` exception. To work around this problem install the "libc6-dev" package.
+
 ## Uninstalling dotnet-dump 
 
     $ dotnet tool uninstall -g dotnet-dump