From: Mike McLaughlin Date: Tue, 11 Jun 2019 00:59:13 +0000 (-0700) Subject: Update Documents (#323) X-Git-Tag: submit/tizen/20190813.035844~6^2^2~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=3bd3deb7332d9e889ea8a7c6e5e89e0c8f20cacc;p=platform%2Fcore%2Fdotnet%2Fdiagnostics.git 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 a216e0054..3aa6de88e 100644 --- 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 index 000000000..36beae009 --- /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 e3106244f..7bcb83a94 100644 --- 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 8dba30753..4cc420d06 100644 --- 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 a235104ac..e62aadb5e 100644 --- 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 Enables the symbol server support soshelp Displays all available commands when no parameter is specified, or displays detailed help information about the specified command. soshelp +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