Extensively document the cause of GPU device issues and the use of --gpu-map.

README

@@ -184,6 +184,7 @@ GPU only options:
 --gpu-dyninterval <arg> Set the refresh interval in ms for GPUs using dynamic intensity (default: 7)
 --gpu-engine <arg>  GPU engine (over)clock range in Mhz - one value, range and/or comma separated list (e.g. 850-900,900,750-850)
 --gpu-fan <arg>     GPU fan percentage range - one value, range and/or comma separated list (e.g. 25-85,85,65)
+--gpu-map <arg>     Map OpenCL to ADL device order manually, paired CSV (e.g. 1:0,2:1 maps OpenCL 1 to ADL 0, 2 to 1)
 --gpu-memclock <arg> Set the GPU memory (over)clock in Mhz - one value for all or separate by commas for per card.
 --gpu-memdiff <arg> Set a fixed difference in clock speed between the GPU and memory in auto-gpu mode
 --gpu-powertune <arg> Set the GPU powertune percentage - one value for all or separate by commas for per card.
@@ -217,7 +218,7 @@ FPGA mining boards(BitForce, Icarus) only options:
        (where n = the correct device number for the FPGA device)
 
 
-CPU only options:
+CPU only options (deprecated, not included in binaries!):
 
 --algo|-a <arg>     Specify sha256 implementation for CPU mining:
         auto            Benchmark at startup and pick fastest algorithm
@@ -836,6 +837,81 @@ miner.php - an example web page to access the API
  Read the top of the file (miner.php) for details of how to tune the display
  and also to use the option to display a multi-rig summary
 
+---
+
+GPU DEVICE ISSUES and use of --gpu-map
+
+GPUs mine with OpenCL software via the GPU device driver. This means you need
+to have both an OpenCL SDK installed, and the GPU device driver RUNNING (i.e.
+Xorg up and running configured for all devices that will mine on linux etc.)
+Meanwhile, the hardware monitoring that cgminer offers for AMD devices relies
+on the ATI Display Library (ADL) software to work. OpenCL DOES NOT TALK TO THE
+ADL. There is no 100% reliable way to know that OpenCL devices are identical
+to the ADL devices, as neither give off the same information. cgminer does its
+best to correlate these devices based on the order that OpenCL and ADL numbers
+them. It is possible that this will fail for the following reasons:
+
+1. The device order is listed differently by OpenCL and ADL (rare), even if the
+number of devices is the same.
+2. There are more OpenCL devices than ADL. OpenCL stupidly sees one GPU as two
+devices if you have two monitors connected to the one GPU.
+3. There are more ADL devices than OpenCL. ADL devices include any ATI GPUs,
+including ones that can't mine, like some older R4xxx cards.
+
+To cope with this, the ADVANCED option for --gpu-map is provided with cgminer.
+DO NOT USE THIS UNLESS YOU KNOW WHAT YOU ARE DOING. The default will work the
+vast majority of the time unless you know you have a problem already.
+
+To get useful information, start cgminer with just the -n option. You will get
+output that looks like this:
+
+[2012-04-25 13:17:34] CL Platform 0 vendor: Advanced Micro Devices, Inc.
+[2012-04-25 13:17:34] CL Platform 0 name: AMD Accelerated Parallel Processing
+[2012-04-25 13:17:34] CL Platform 0 version: OpenCL 1.1 AMD-APP (844.4)
+[2012-04-25 13:17:34] Platform 0 devices: 3
+[2012-04-25 13:17:34]   0       Tahiti
+[2012-04-25 13:17:34]   1       Tahiti
+[2012-04-25 13:17:34]   2       Cayman
+[2012-04-25 13:17:34] GPU 0 AMD Radeon HD 7900 Series  hardware monitoring enabled
+[2012-04-25 13:17:34] GPU 1 AMD Radeon HD 7900 Series  hardware monitoring enabled
+[2012-04-25 13:17:34] GPU 2 AMD Radeon HD 6900 Series hardware monitoring enabled
+[2012-04-25 13:17:34] 3 GPU devices max detected
+
+Note the number of devices here match, and the order is the same. If devices 1
+and 2 were different between Tahiti and Cayman, you could run cgminer with:
+--gpu-map 2:1,1:2
+And it would swap the monitoring it received from ADL device 1 and put it to
+opencl device 2 and vice versa.
+
+If you have 2 monitors connected to the first device it would look like this:
+
+[2012-04-25 13:17:34] Platform 0 devices: 4
+[2012-04-25 13:17:34]   0       Tahiti
+[2012-04-25 13:17:34]   1       Tahiti
+[2012-04-25 13:17:34]   2       Tahiti
+[2012-04-25 13:17:34]   3       Cayman
+[2012-04-25 13:17:34] GPU 0 AMD Radeon HD 7900 Series  hardware monitoring enabled
+[2012-04-25 13:17:34] GPU 1 AMD Radeon HD 7900 Series  hardware monitoring enabled
+[2012-04-25 13:17:34] GPU 2 AMD Radeon HD 6900 Series hardware monitoring enabled
+
+To work around this, you would use:
+-d 0 -d 2 -d 3 --gpu-map 2:1,3:2
+
+If you have an older card as well as the rest it would look like this:
+
+[2012-04-25 13:17:34] Platform 0 devices: 3
+[2012-04-25 13:17:34]   0       Tahiti
+[2012-04-25 13:17:34]   1       Tahiti
+[2012-04-25 13:17:34]   2       Cayman
+[2012-04-25 13:17:34] GPU 0 AMD Radeon HD 4500 Series  hardware monitoring enabled
+[2012-04-25 13:17:34] GPU 1 AMD Radeon HD 7900 Series  hardware monitoring enabled
+[2012-04-25 13:17:34] GPU 2 AMD Radeon HD 7900 Series  hardware monitoring enabled
+[2012-04-25 13:17:34] GPU 3 AMD Radeon HD 6900 Series hardware monitoring enabled
+
+To work around this you would use:
+--gpu-map 0:1,1:2,2:3
+
+
 ---
 
 FAQ