From 87665bac37c752b681b6fb76e00bde4cdcd8b6ff Mon Sep 17 00:00:00 2001
From: Aleksei Vereshchagin <avereschagin@dev.rtsoft.ru>
Date: Fri, 6 Apr 2018 14:38:54 +0300
Subject: [PATCH] Update README.md

---
 README.md | 399 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 350 insertions(+), 49 deletions(-)

diff --git a/README.md b/README.md
index 4c05c0c..b1d9335 100644
--- a/README.md
+++ b/README.md
@@ -1,49 +1,350 @@
-## Tizen Profiler for CoreCLR
-
-This project provdes profiler facility for CoreCLR. It is an implementation of ICorProfilerCallback3 interface. 
-Currently tested on ARM, x86-64 and i586 platforms.
-
-## Prerequisites
-In oder to build cross platform CoreCLR on Ubuntu 14.0 one need to follow prerequisites instructions on CoreCLR site:
-https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md
-
-## Build
-The profiler loadable module (libcoreprof.so) is built with gbs.
-
-## Use
-In order to obtain sampling information the Lttng (the same version as in coreclr cross rootfs) should be installed on target.
-
-$ CORECLR_PROFILER={101DA8FE-FDCA-4D0E-9712-7639CDE48EBA} CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER_PATH=./libcoreprof.so PROF_EXECUTION_TRACE=1 PROF_COLLECT_METHOD=Sampling PROF_LINE_TRACE=1 PROF_TRACE_FILENAME=trace.log  ./corerun Program.exe
-
-### Options
-1.	PROF_EXECUTION_TRACE=1 – turns tracing on
-    a.	PROF_COLLECT_METHOD=<Instrumentation|Sampling> – set the trace mode 
-        i.	Instrumentation - trace all ELT events (instrumentation)
-        ii.	Sampling – aggregate ELT events into samples (stack snapshots, sampling)
-            1.	PROF_SAMPLING_TIMEOUT=<time in ms> – sampling time interval (default - 10)
-            2.	PROF_HIGH_GRAN=<0|1> – a mode, where (default 1):
-                a.	if 1,  all samples are printed out to a log file with a rate defined in PROF_SAMPLING_TIMEOUT (high-granularity sampling)
-        3.	if 0, samples are printed out to a log file in ELT-events only (low-granularity sampling)
-    b.	PROF_LINE_TRACE=<0|1> – turns the collection on the source lines level on (default 1)
-        i.	when (PROF_COLLECT_METHOD= Sampling && PROF_HIGH_GRAN=1) , every sample has a source line information for each stack call element
-        ii.	when (PROF_COLLECT_METHOD=Instrumentation || PROF_COLLECT_METHOD=Sampling && PROF_HIGH_GRAN=0), there is no source line information for top stack element
-2.	PROF_MEMORY_TRACE=<0|1> turns on memory tracing (not yet implemented, default 0).
-3.	PROF_TRACE_STREAM=<output> - set the output channel of the profiling information, where <output> is:
-    a.	Stdout – out to stdout (default)
-    b.	Stderr - out to stderr
-    c.	File – out to a file
-        i.	PROF_TRACE_FILENAME=<name of the profiling information file>
-4.	PROF_LOG_STREAM=<output> - set the output channel of the log information, where <output> is:
-    a.	Stdout - out to stdout (default)
-    b.	Stderr - out to stderr
-    c.	File - out to a file
-        i.	PROF_LOG_FILENAME=<name of the log information file>
-5.	PROF_LOG_LEVEL=<level> - set the log level, where <level> is:
-    a.	None – nothing to print
-    b.	Fatal – print out fatal errors only
-    c.	Error - print out all errors
-    d.	Warn – print out warnings
-    e.	Info - print out info messages
-    f.	Debug - print out debug messages
-    g.	Trace - print out all messages
-    h.	All – same as Trace.
+# Managed code profiler library for .NET Core runtime
+
+This project provides profiling library for CoreCLR that can be used
+to generate tracing data with performance information during managed
+application execution. File with tracing data than can be analyzed using
+compatible profiling tool.
+
+The library uses `ICorProfilerCallback3` and `ICorProfilerInfo4` interfaces
+of CoreCLR to control profilability and obtain profiling information. It also
+uses Linux real-time signals (from `SIGRTMIN + 4` to `SIGRTMIN + 10`)
+for control and communication purposes.
+
+CoreProfiler library currently tested on Linux (x86-64) and Tizen (ARM, x86)
+platforms.
+
+## Building the Repository (Ubuntu 16.04)
+
+In order to build CoreProfiler on Ubuntu 16.04 one need to build CoreCLR
+at first. Follow prerequisites from
+[documentation](https://github.com/dotnet/coreclr/blob/master/Documentation/building/linux-instructions.md)
+on CoreCLR site.
+
+Next instructions describes building of debug and release versions of CoreCLR
+and CoreProfiler. Result of building is `libcoreprof.so` in `install`
+subdirectory (default location  can be changed using
+`CMAKE_INSTALL_PREFIX_OVERRIDE` CMake variable).
+
+### Debug Build
+
+```console
+~$ cd ~/coreclr
+~/coreclr$ ./build debug skiptests skipnuget
+~/coreclr$ cd ~/coreprofiler
+~/coreprofiler$ mkdir -p build/debug
+~/coreprofiler$ cd build/debug
+~/coreprofiler/build/debug$ CC=clang-3.9 CXX=clang++-3.9 \
+    cmake ../.. \
+    -DCMAKE_BUILD_TYPE=Debug \
+    -DCLR_SRC_DIR=~/coreclr
+~/coreprofiler/build/debug$ make -j install
+```
+
+### Release Build
+
+```console
+~$ cd ~/coreclr
+~/coreclr$ ./build release skiptests skipnuget
+~/coreclr$ cd ~/coreprofiler
+~/coreprofiler$ mkdir -p build/release
+~/coreprofiler$ cd build/release
+~/coreprofiler/build/release$ CC=clang-3.9 CXX=clang++-3.9 \
+    cmake ../.. \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DCLR_SRC_DIR=~/coreclr
+~/coreprofiler/build/release$ make -j install
+```
+
+## Building the Repository (GBS)
+
+GBS tool should be installed on the system. GBS installation instructions
+can be found
+[here](https://source.tizen.org/documentation/developer-guide/getting-started-guide/installing-development-tools).
+For the following commands it is assumed that the correct `.gbs.conf` file
+can be found by utility in the default location.
+
+Default building configuration is `Release`. You can add
+`--define "buildtype Debug"` to `gbs` options to change building
+configuration type. Additionally use `--overwrite` flag to rebuild previous
+results.
+
+GBS store resulted RPMs and SRPMs at
+`~/GBS-ROOT/local/repos/<distro>/<arch>` directories.
+
+### Build for ARM Tizen TM1 target
+
+```
+~/coreprofiler$ gbs build -P profile.target-TM1.unified -A armv7l
+```
+
+### Build for x86 Tizen emulator
+
+```
+~/coreprofiler$ gbs build -P profile.emulator32.unified -A i586
+```
+
+## Configuration
+
+CoreProfiler is controlled by set of parameters. Currently configuration file
+and/or environment variables can be used as source of the configuration.
+Environment variables takes precedence over parameters specified by the file.
+Environment variables can specify additional parameters to configuration or
+override defined options. Unsetting of configuration parameters
+by environment variables is not supported.
+
+Path to configuration file can be defined by special environment variable
+`PROF_CONFIG_FILENAME`. If parameter is omitted, only environment variables
+and default settings is used.
+
+Configuration file have following syntax: `<name>=<value>`. Configuration
+file use same names of parameters as configuration environment variables.
+Spaces before `=` character is not permitted. Spaces after `=` character
+is part of `<value>`. Quotation is not supported. Empty lines is ignored.
+There is not support for commentaries in configuration file.
+
+For boolean flags values `1`, `true`, `on`, `yes`, `enabled` and empty string
+can be used as True and `0`, `false`, `no`, `disabled` as False.
+
+Here description of different set of parameters.
+
+### Tracing Subsystems
+
+CoreProfiler have different tracing subsystems each of them can be enabled
+separately. By default all subsystems is disabled, and no tracing data is
+dumped (only timestamp of execution and configuration parameters is stored).
+
+  - `PROF_EXECUTION_TRACE` - enables Execution Trace subsystem. The main purpose
+    of this subsystem is to track changes of execution stack.
+    `PROF_EXECUTION_TRACE` is defaulted to `false`.
+
+  - `PROF_MEMORY_TRACE` - enables Memory Trace subsystem. This subsystem
+    collects data about allocations. `PROF_MEMORY_TRACE` is defaulted to
+    `false`.
+
+      - `PROF_STACK_TRACK` - enables tracking of execution stack state for
+        memory allocations. With this option additional samples with stack
+        changes between allocations will be recorded.
+
+        If `PROF_EXECUTION_TRACE` is disabled, only stack states for allocations
+        will be stored.
+
+        If `PROF_EXECUTION_TRACE` is enabled and `PROF_STACK_TRACK` is disabled,
+        no additional samples will be generated.
+
+        This option is enabled by default if `PROF_EXECUTION_TRACE` and
+        `PROF_MEMORY_TRACE` turned on in conjunction for sampling mode (see
+        below).
+
+  - `PROF_GC_TRACE` - enables tracking of GC events. Value of this options is
+    used as default for following options. However, each following
+    option can be turned on or off manually. `PROF_GC_TRACE` is defaulted to
+    `false`.
+
+      - `PROF_GC_TRACE_ALT` - enables tracking of 'Heap Allocation Tables'
+        for each GC invocation. Heap Allocation Table is set of records
+        containing information about objects count and summary memory usage for
+        all classes.
+
+        _Current limitation: `PROF_MEMORY_TRACE` should be enabled to use this
+        option._
+
+  - `PROF_CPU_TRACE` - enables tracking of CPU usage by process and/or managed
+    threads. Value of this options is used as default for both process and
+    threads CPU tracking. However, each of this can be turned on or off
+    manually. `PROF_CPU_TRACE` is defaulted to `false`.
+
+      - `PROF_CPU_TRACE_PROC` - enables tracking of CPU usage by
+        application process.
+      - `PROF_CPU_TRACE_THREAD` - enables tracking of CPU usage by
+        application managed threads.
+      - `PROF_CPU_TRACE_TIMEOUT` - timeout between CPU usage measurements
+        in milliseconds. Default value is `10`.
+
+    _Current limitation: `PROF_EXECUTION_TRACE` or `PROF_MEMORY_TRACE`
+    should also be enabled to use this options._
+
+### Collection Methods
+
+  - `PROF_COLLECT_METHOD` - defines profiler mode for collecting data. Possible
+    values is:
+
+      - `None` - only basic information from runtime collected by subsystems.
+        No stack and allocations tracking is performed. (It is default.)
+      - `Instrumentation` - each event dumped to trace log as separate record.
+        It is slow, but provides detailed information.
+      - `Sampling` - events is grouped to samples. The higher the sampling
+        rate, the lower detailing level and the less application slowdown.
+
+        When `PROF_STACK_TRACK` is enabled, samples can be generated more often
+        than sampling rate (see option description), that can be slow.
+
+          - `PROF_SAMPLING_TIMEOUT` - timeout between samples generation
+            (within the same managed thread) in milliseconds.
+            Default value is `10`.
+
+          - `PROF_HIGH_GRAN` - enables signals generation for better granularity
+            of sampling. If option is disabled, samples dumped only on
+            allocation and stack changing events. This option is enabled by
+            default for `Sampling` mode. Disabling is not recommended
+            (but can be rarely useful for testing purposes).
+
+    _Current limitation: `Instrumentation` mod is not well tested and can cause
+    crashes._
+
+### Obtain information about source lines
+
+  - `PROF_LINE_TRACE` - enables collection of instruction pointers (IP) for
+    samples. Profiler generates information about IL to native code mapping,
+    that can be used for matching between IP and source code fragments.
+
+    This option requires execution and/or memory tracing enabled and sampling or
+    instrumentation profiling mode activated. Default value is `false`.
+
+    CoreProfiler itself doesn't have information about sources,
+    so matching should be done by external tool that requires PDB files with
+    information about symbols.
+
+    CoreProfiler try to collect IP (according to enabled subsystems) when one
+    function calls another, when allocations is occurred, and for the time of
+    sample generation (for high granularity sampling - see `PROF_HIGH_GRAN`
+    option description). Profiler uses context information from signal handlers
+    and stack frames when it is possible.
+
+    _Current limitations: line tracing is not implemented very well and can be
+    issued by ABI changes and other limitations. We need more research for this
+    area._
+
+### Control tracing data stream
+
+  - `PROF_TRACE_STREAM` - defines the output channel for tracing data. Can be
+    one of:
+
+      - `Stdout` - use `stdout` (default);
+      - `Stderr` - use `stderr`;
+      - `File` - use file (see `PROF_TRACE_FILENAME`).
+
+  - `PROF_TRACE_FILENAME` - defines path to output file. `PROF_TRACE_STREAM`
+    should be `File` or unspecified.
+
+### Control logging
+
+  - `PROF_LOG_STREAM` - defines the output channel for log messages. Can be
+    one of:
+
+      - `Stdout` - use `stdout` (default);
+      - `Stderr` - use `stderr`;
+      - `File` - use file (see `PROF_LOG_FILENAME`).
+
+  - `PROF_LOG_FILENAME` - defines path to output file. `PROF_LOG_STREAM`
+    should be `File` or unspecified.
+
+  - `PROF_LOG_LEVEL` - defines minimal log level to printed messages. Possibles
+    values (from maximum to minimum):
+
+      - `None` - nothing to print;
+      - `Fatal` - print out fatal errors only;
+      - `Error` - print out all errors;
+      - `Warn` - print out warning too (default);
+      - `Info` - print out information messages too;
+      - `Debug` - print out debug messages too (not available for Release
+        version);
+      - `Trace` - print out trace messages too (not available for Release
+        version);
+      - `All` - print out all available messages.
+
+### Examples
+
+#### Stack Sampling
+
+```
+PROF_COLLECT_METHOD=Sampling
+PROF_EXECUTION_TRACE=1
+PROF_CPU_TRACE=1
+PROF_LINE_TRACE=1
+PROF_TRACE_FILENAME=trace.log
+```
+
+#### Memory Sampling
+
+```
+PROF_COLLECT_METHOD=Sampling
+PROF_MEMORY_TRACE=1
+PROF_GC_TRACE=1
+PROF_LINE_TRACE=1
+PROF_TRACE_FILENAME=trace.log
+```
+
+#### Complex Sampling
+
+```
+PROF_COLLECT_METHOD=Sampling
+PROF_EXECUTION_TRACE=1
+PROF_CPU_TRACE=1
+PROF_MEMORY_TRACE=1
+PROF_GC_TRACE=1
+PROF_LINE_TRACE=1
+PROF_TRACE_FILENAME=trace.log
+```
+
+## Usage
+
+CoreProfiler is a library loaded by .NET Core Runtime. CoreCLR loads
+profiler if environment variable `CORECLR_ENABLE_PROFILING` is set to `1`.
+`CORECLR_PROFILER_PATH` should define path to `libcoreprof.so` and
+`CORECLR_PROFILER` variable should have value
+`{101DA8FE-FDCA-4D0E-9712-7639CDE48EBA}` (it is GUID of CoreProfiler).
+
+CoreProfiler uses environment variables, files and signals to communicate
+with 'world'. See above detailed description how to control profiler work.
+If no files specified, CoreProfiler outputs tracing data and log messages
+to `stdout`.
+
+### Usage with console apps
+
+To build a console application use dotnet CLI. Its version should be compatible
+with compiled CoreCLR. For example (Ubutntu 16.04):
+
+```console
+~$ curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
+~$ sudo mv microsoft.gpg /etc/apt/trusted.gpg.d/microsoft.gpg
+~$ sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-ubuntu-xenial-prod xenial main" > /etc/apt/sources.list.d/dotnetdev.list'
+~$ sudo apt-get update
+~$ sudo apt-get install dotnet-sdk-2.1.300-preview1-008174
+```
+
+Then try to create and build simple application:
+
+```console
+~$ mkdir -p ~/demo/hello && cd ~/demo/hello
+~/demo/hello$ dotnet new console
+~/demo/hello$ dotnet build
+~/demo/hello$ cd bin/Debug/netcoreapp2.1/
+```
+
+You can use bash aliases to simplify run of profiling. Add this lines to
+`~/.bash_aliases` and restart shell:
+
+```bash
+alias corerun_prof='\
+CORE_LIBRARIES=/usr/share/dotnet/shared/Microsoft.NETCore.App/2.1.0-preview1-26216-03/ \
+CORECLR_ENABLE_PROFILING=1 \
+CORECLR_PROFILER={101DA8FE-FDCA-4D0E-9712-7639CDE48EBA} \
+CORECLR_PROFILER_PATH=~/coreprofiler/build/release/install/libcoreprof.so \
+~/coreclr/bin/Product/Linux.x64.Release/corerun'
+
+alias corerun_prof_debug='\
+CORE_LIBRARIES=/usr/share/dotnet/shared/Microsoft.NETCore.App/2.1.0-preview1-26216-03/ \
+CORECLR_ENABLE_PROFILING=1 \
+CORECLR_PROFILER={101DA8FE-FDCA-4D0E-9712-7639CDE48EBA} \
+CORECLR_PROFILER_PATH=~/coreprofiler/build/debug/install/libcoreprof.so \
+~/coreclr/bin/Product/Linux.x64.Debug/corerun'
+```
+
+You can start profiling with command like this:
+
+```console
+~/demo/hello/bin/Debug/netcoreapp2.1$ PROF_CONFIG_FILENAME=~/profiler.cfg corerun_prof hello.dll
+```
+
+If you stored one of exampled above configuration to `~/profiler.cfg`, you
+would get tracing log in `trace.log` file.
-- 
2.34.1