documentation

- add more documentation
- split documentation into different files

7 files changed, 267 insertions, 11 deletions

diff --git a/doc/FAQ.md b/doc/FAQ.md
new file mode 100644
index 0000000..995a421
--- /dev/null
+++ b/doc/FAQ.md
@@ -0,0 +1,61 @@
+# FAQ
+
+## Content Overview
+* [SeLockMemoryPrivilege failed](#selockmemoryprivilege-failed)
+* [VirtualAlloc failed](#virtualalloc-failed)
+* [Error msvcp140.dll and vcruntime140.dll not available](#error-msvcp140dll-and-vcruntime140dll-not-available)
+* [Error: MEMORY ALLOC FAILED: mmap failed](#error-memory-alloc-failed-mmap-failed)
+* [Illegal instruction (core dumped)](#illegal-instruction)
+* [Virus Protection Alert](#virus-protection-alert)
+
+## SeLockMemoryPrivilege failed
+
+Please see [config.txt](config.txt) under section **LARGE PAGE SUPPORT**
+
+For Windows 7 pro, or Windows 8 and above see [this article](https://msdn.microsoft.com/en-gb/library/ms190730.aspx)  (make sure to reboot afterwards!).
+
+For Windows 7 Home :
+
+1) Download and install [Windows Server 2003 Resource Kit Tools](https://www.microsoft.com/en-us/download/details.aspx?id=17657).  Ignore incompatiablity warning during installation.
+
+2) In cmd or power shell: `ntrights -u %USERNAME% +r SeLockMemoryPrivilege`  (where %USERNAME% is the user that will be running the program.  This command needs to be run as admin)
+
+3) Reboot.
+
+Reference: http://rybkaforum.net/cgi-bin/rybkaforum/topic_show.pl?pid=259791#pid259791
+
+*Warning: do not download ntrights.exe from any other site other then the offical Microsoft download page.*
+
+## VirtualAlloc failed
+
+If you set up the user rights properly (see above), and your system has 4-8GB of RAM (50%+ use), there is a significant chance that there simply won't be a large enough chunk of contiguous memory because Windows is fairly bad at mitigating memory fragmentation.
+
+If that happens, disable all auto-staring applications and run the miner after a reboot.
+
+## Error msvcp140.dll and vcruntime140.dll not available
+
+Download and install this [runtime package](https://go.microsoft.com/fwlink/?LinkId=746572) from Microsoft.  *Warning: Do NOT use "missing dll" sites - dll's are exe files with another name, and it is a fairly safe bet that any dll on a shady site like that will be trojaned.  Please download offical runtimes from Microsoft above.*
+
+
+## Error: MEMORY ALLOC FAILED: mmap failed
+
+On Linux you will need to configure large page support `sudo sysctl -w vm.nr_hugepages=128` and increase your
+ulimit -l. To do this you need to add following lines to /etc/security/limits.conf:
+
+    * soft memlock 262144
+    * hard memlock 262144
+
+Save file.  You WILL need to log out and log back in for these settings to take affect on your user (no need to reboot, just relogin in your session).
+
+You can also do it Windows-style and simply run-as-root, but this is NOT recommended for security reasons.
+
+## Illegal Instruction
+
+This typically means you are trying to run it on a CPU that does not have [AES](https://en.wikipedia.org/wiki/AES_instruction_set).  This only happens on older version of miner, new version gives better error message (but still wont' work since your CPU doesn't support the required instructions).
+
+## Virus Protection Alert
+
+Some Virus protection software flag the miner binary as *Male Ware*.
+In this case the binary is moved to the quarantine area of the protection software.
+This is a wrong alert and not avoid by use.
+Add the binary to to protection software white list to solve this issue.s
diff --git a/doc/compile.md b/doc/compile.md
new file mode 100644
index 0000000..04b1fe4
--- /dev/null
+++ b/doc/compile.md
@@ -0,0 +1,81 @@
+# Compile xmr-stak
+
+## Content Overview
+* [Build System](#build-system)
+* [Generic Build Options](#generic-build-options)
+* [CPU Build Options](#cpu-build-options)
+* [AMD Build Options](#amd-build-options)
+* [NVIDIA Build Options](#nvidia-build-options)
+* [Compile in Windows](compile_Windows.md)
+* [Compile in Linux](compile_Linux.md)
+* [Compile in FreeBSD](compile_FreeBSD.md)
+
+## Build System
+
+The build system is CMake, if you are not familiar with CMake you can learn more [here](https://cmake.org/runningcmake/).
+
+By default the miner will be build with all dependencies. Each optional dependency can be disabled (this will reduce the miner features).
+
+There are two easy ways to set variables for `cmake` to configure *xmr-stak*
+- use the ncurses GUI
+  - `ccmake .`
+  - edit your options
+  - end the GUI by pressing the key `c`(create) and than `g`(generate)
+- set Options on the command line
+  - enable a option: `cmake . -DNAME_OF_THE_OPTION=ON`
+  - disable a option `cmake . -DNAME_OF_THE_OPTION=OFF`
+  - set a value `cmake . -DNAME_OF_THE_OPTION=value`
+
+After the configuration you need to compile the miner, follow the guide for your platform:
+* [Compile in Windows](compile_Windows.md)
+* [Compile in Linux](compile_Linux.md)
+* [Compile in FreeBSD](compile_FreeBSD.md)
+
+## Generic Build Options
+- `CMAKE_INSTALL_PREFIX` install miner to the home folder
+  - `cmake . -DCMAKE_INSTALL_PREFIX=$HOME/xmr-stak-cpu`
+  - you can find the binary and the `config.txt` file after `make install` in `$HOME/xmr-stak-cpu/bin`
+- `CMAKE_LINK_STATIC` link libgcc and libstdc++ libraries static (default OFF)
+  - disable with `cmake . -DCMAKE_LINK_STATIC=ON`
+- `CMAKE_BUILD_TYPE` set the build type
+  - valid options: `Release` or `Debug`
+  - you should always keep `Release` for your productive miners
+- `MICROHTTPD_ENABLE` allow to disable/enable the dependency *microhttpd*
+  - there is no *http* interface available if option is disabled: `cmake . -DMICROHTTPD_ENABLE=OFF`
+- `OpenSSL_ENABLE` allow to disable/enable the dependency *OpenSSL*
+  - it is not possible to connect to a *https* secured pool if option is disabled: `cmake . -DOpenSSL_ENABLE=OFF`
+
+## CPU Build Options
+
+- `CPU_ENABLE` allow to disable/enable the CPU backend of the miner
+- `HWLOC_ENABLE` allow to disable/enable the dependency *hwloc*
+  - the config suggestion is not optimal if option is disabled: `cmake . -DHWLOC_ENABLE=OFF`
+  - disabling can be reduce the miner performance
+
+## AMD Build Options
+
+- `OpenCL_ENABLE` allow to disable/enable the AMD backend of the miner
+
+## NVIDIA Build Options
+
+- `CUDA_ENABLE` allow to disable/enable the NVIDIA backend of the miner
+- `CUDA_ARCH` build for a certain compute architecture
+  - this option needs a semicolon separated list
+  - `cmake . -DCUDA_ARCH=61` or `cmake . -DCUDA_ARCH=20;61`
+  - [list](https://developer.nvidia.com/cuda-gpus) with NVIDIA compute architectures
+  - by default the miner is created for all currently available compute architectures
+- `CUDA_COMPILER` select the compiler for the device code
+  - valid options: `nvcc` or `clang` if clang 3.9+ is installed
+```
+    # compile host and device code with clang
+    export CC=/usr/bin/clang
+    export CXX=/usr/bin/clang++
+    cmake . -DCUDA_COMPILER=clang
+```
+- `XMR-STAK_LARGEGRID` use `32` or `64` bit integer for on device indices
+  - default is enabled
+  - on old GPUs it can increase the hash rate if disabled: `cmake . -DXMR-STAK_LARGEGRID=OFF`
+  - if disabled it is not allowed to use more than `1000` threads on the device
+- `XMR-STAK_THREADS` give the compiler information which value for `threads` is used at runtime
+  - default is `0` (compile time optimization)
+  - if the miner is compiled and used at runtime with the some value it can increase the hash rate: `cmake . -DXMR-STAK_THREADS=32`
diff --git a/doc/FREEBSDCOMPILE.md b/doc/compile_FreeBSD.md
index 230ce73..6dd1165 100644
--- a/doc/FREEBSDCOMPILE.md
+++ b/doc/compile_FreeBSD.md
@@ -13,8 +13,6 @@ Type 'y' and hit enter to proceed with installing the packages.
     git clone https://github.com/fireice-uk/xmr-stak-cpu.git
     cd xmr-stak-cpu
     cmake .
-    make
+    make install
 
-Now you have the binary located at "bin/xmr-stak-cpu". Either move this file to your desired location or run "make install" to install it to your path.
-
-You can edit the prebuilt [config.txt](config.txt) file found in the root of the repository or you can make your own. This file is required to run xmr-stak-cpu.
+Now you have the binary located at "bin/xmr-stak" and the needed shared libraries.
diff --git a/doc/LINUXCOMPILE.md b/doc/compile_Linux.md
index 4486081..4947fd2 100644
--- a/doc/LINUXCOMPILE.md
+++ b/doc/compile_Linux.md
@@ -37,8 +37,7 @@
     make install
 ```
 
-- g++ version 5.1 or higher is required for full C++11 support. CMake release compile scripts, as well as CodeBlocks build environment for debug builds is included.
-
+- g++ version 5.1 or higher is required for full C++11 support. 
 If you want to compile the binary without installing libraries / compiler or just compile binary for some other distribution, please check the [build_xmr-stak_docker.sh script](scripts/build_xmr-stak_docker/build_xmr-stak_docker.sh).
 
 ### To do a static build for a system without gcc 5.1+
@@ -47,6 +46,3 @@ If you want to compile the binary without installing libraries / compiler or jus
     make install
 ```
 Note - cmake caches variables, so if you want to do a dynamic build later you need to specify '-DCMAKE_LINK_STATIC=OFF'
-
-
-
diff --git a/doc/WINCOMPILE.md b/doc/compile_Windows.md
index f70ecff..dec1e75 100644
--- a/doc/WINCOMPILE.md
+++ b/doc/compile_Windows.md
@@ -58,7 +58,7 @@
 
 ## Compile
 
-- download and unzip `xmr-stak-cpu`
+- download and unzip `xmr-stak
 - open the command line terminal `cmd`
 - `cd` to your unzipped source code directory
 - execute the following commands (NOTE: path to VS2017 can be different)
@@ -71,4 +71,3 @@
   cmake --build . --config Release --target install
   cd bin\Release
   ```
-- customize your `config.txt` file by adding the pool, username and password
diff --git a/doc/tuning.md b/doc/tuning.md
new file mode 100644
index 0000000..820fab5
--- /dev/null
+++ b/doc/tuning.md
@@ -0,0 +1,67 @@
+# Tuning Guide
+
+## Content Overview
+* [NVIDIA Backend](#nvidia-backend)
+  * [Choose Value for `threads` and `blocks`](#choose-value-for-threads-and-blocks)
+  * [Add more GPUs](#add-more-gpus)
+* [AMD Backend](#amd-backend)
+  * [Choose `intensity` and `worksize`](#choose-intensity-and-worksize)
+  * [Add more GPUs](#add-more-gpus)
+
+## NVIDIA Backend
+
+By default the NVIDIA backend can be tuned in the config file `nvidia.txt`
+
+### Choose Value for `threads` and `blocks`
+
+The optimal parameter for the `threads` and `blocks` option in `config.txt` depend on your GPU.
+For all GPU's with a compute capability `>=2.0` and `<6.0` there is a restriction of the amount of RAM that can be used for the mining algorithm.
+The maximum RAM that can be used must be less than 2GB (e.g. GTX TITAN) or 1GB (e.g. GTX 750-TI).
+The amount of RAM used for mining can be changed with `"threads" : T, "blocks : B"`.
+  - `T` = threads used per block
+  - `B` = CUDA blocks started (should be a multiple of the multiprocessors `M` on the GPU)
+
+For the 2GB limit the equations must be full filled: `T * B * 2 <= 1900` and ` B mod M == 0`.
+The value `1900` is used because there is a little data overhead for administration.
+The GTX Titan X has 24 multiprocessors `M`, this means a valid and good starting configuration is `"threads" : 16, "blocks : 48"`
+and full fill all restrictions `16 * 48 * 2 = 1536` and `48 mod 24 = 0`.
+
+The memory limit for NVIDIA Pascal GPUs is `16` GiB if the newest CUDA driver is used.
+
+### Add More GPUs
+
+To add a new GPU you need to add a new config set to `gpu_threads_conf`.
+`index` is the number of the gpu, the index order not follow the order from `nvidia-smi` or the order shown in windows.
+
+```
+"gpu_threads_conf" :
+[
+    { "index" : 0, "threads" : 17, "blocks" : 60, "bfactor" : 0, "bsleep" :  0, "affine_to_cpu" : false},
+    { "index" : 1, "threads" : 17, "blocks" : 60, "bfactor" : 0, "bsleep" :  0, "affine_to_cpu" : false},
+],
+```
+
+## AMD Backend
+
+By default the NVIDIA backend can be tuned in the config file `nvidia.txt`
+
+### Choose `intensity` and `worksize`
+
+Intensity means the number of threads used to mine.
+`worksize` is the number of threads working together to increase the miner performance.
+In the most cases a `worksize` of `16` or `8` is optimal.
+
+### Add More GPUs
+
+To add a new GPU you need to add a new config set to `gpu_threads_conf` and increase `gpu_thread_num"` to the number of gpus (entries in `gpu_threads_conf`).
+`index` is the number of the gpu.
+
+```
+"gpu_thread_num" : 2,
+
+"gpu_threads_conf" :
+[
+    { "index" : 0, "intensity" : 1000, "worksize" : 8, "affine_to_cpu" : false },
+    { "index" : 1, "intensity" : 1000, "worksize" : 8, "affine_to_cpu" : false },
+],
+```
\ No newline at end of file
diff --git a/doc/usage.md b/doc/usage.md
new file mode 100644
index 0000000..dfebf21
--- /dev/null
+++ b/doc/usage.md
@@ -0,0 +1,54 @@
+# HowTo Use xmr-stak
+
+## Content Overview
+* [Configuration](#configuration)
+* [Usage on Windows](#usage-on-windows)
+* [Usage on Linux](#usage-on-linux)
+* [Command Line Options](#command-line-options)
+* [HTML and JSON API report configuraton](#xx)
+
+## Configurations
+
+Before you started the miner the first time there are no config files available.
+Config files will be created at the first start.
+The number of files depends on the available backends.
+`config.txt` contains the common miner settings.
+`amd.txt`, `cpu.txt` and `nvidia.txt` contains miner backend specific settings and can be used for further tuning ([Tuning Guide](tuning.md)).
+
+
+## Usage on Windows
+1) Double click the `xmr-stak.exe` file
+2) Fill in the pool url, username and password
+
+## Usage on Linux
+1) Open a terminal within the folder with the binary
+2) Start the miner with `./xmr-stak`
+
+## Command Line Options
+
+The miner allow to overwrite some of the settings via command line options.
+
+```
+Usage: xmr-stak [OPTION]... [CONFIGFILE]
+
+  -c, --config          common miner configuration file
+  -h, --help            show this help
+  --noCPU               disable the CPU miner backend
+  --cpu FILE            CPU backend miner config file
+  --noAMD               disable the AMD miner backend
+  --amd FILE            AMD backend miner config file
+
+The Following options temporary overwrites the config file settings:
+  -o, --url URL         pool url and port, e.g. pool.usxmrpool.com:3333
+  -u, --user USERNAME   pool user name or wallet address
+  -p, --pass PASSWD     pool password, in the most cases x or empty ""
+
+## HTML and JSON API report configuraton
+
+To configure the reports shown on the [README](README.md) side you need to edit the httpd_port variable. Then enable wifi on your phone and navigate to [miner ip address]:[httpd_port] in your phone browser. If you want to use the data in scripts, you can get the JSON version of the data at url [miner ip address]:[httpd_port]/api.json
+
+## Default Developer Donation
+By default the miner will donate 2% of the hashpower (2 minute in 100 minutes) to my pool. If you want to change that, edit **xmrstak/donate-level.hpp** before you build the binaries.
+
+If you want to donate directly to support further development, here is my wallet
+```