Extensively document the cause of GPU device issues and the use of --gpu-map.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
diff --git a/README b/README
index 9ae0596..5332ba2 100644
--- a/README
+++ b/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
@@ -838,6 +839,81 @@ miner.php - an example web page to access the API
---
+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
Q: cgminer segfaults when I change my shell window size.