README for MemtestCL
Version 1.00
Imran Haque
12 Aug 2010

CONTENTS
1. Description
2. Basic Usage
3. Advanced Usage
4. FAQ
5. Licensing


1. DESCRIPTION

MemtestCL is a program to test the memory and logic of OpenCL-enabled
GPUs, CPUs, and accelerators for errors. It has been tested on NVIDIA
GPUs using the NVIDIA OpenCL implementation, AMD/ATI GPUs using the AMD
OpenCL implementation, as well as Intel and AMD CPUs using the AMD
OpenCL implementation. MemtestCL is an OpenCL port of our CUDA-based
tester for NVIDIA GPUs, MemtestG80.

MemtestCL is licensed under a closed-source license found in the COPYING
file included with this distribution. It can also be found by running
MemtestCL with the --license flag, or at the end of this README.

An open-source version of MemtestCL implementing the same memory tests as
the closed-source version is also available. However, certain functionality
is missing, such as the ability to transmit test results back to Stanford
to help gather statistics and improve the state of GPU computing. 

Up-to-date versions of both the closed- and open-source versions of MemtestCL
may be downloaded at https://simtk.org/home/memtest. The closed-source version
is available as precompiled binaries; the open-source version is available only
as a source package.

This document concerns the closed-source version.

2. BASIC USAGE

MemtestCL is available for Windows, Linux, and Mac OS X-based machines. In the
following directions, please replace "MemtestCL" with the name of the program
included in the distribution for your operating system.

MemtestCL is a command line application; to run it, start it from a command
prompt (Start->Run->cmd in Windows, Terminal.app in OS X). For basic operation,
just run it from the command prompt:

    MemtestCL

By default, MemtestCL will test 128 megabytes of memory on the first OpenCL
device on the first OpenCL platform found,running 50 iterations of its tests.
On typical machines, each iteration will complete in under 10 seconds with
these parameters (the speed will vary both with the speed of the card tested
and the amount of memory tested). The amount of memory tested and number of 
test iterations can be modified by adding command line parameters as follows:

    MemtestCL [amount of RAM in megabytes] [number of test iterations]

For example, to run MemtestCL over 256 megabytes of RAM, with 100 test
iterations, execute the following command:
    
    MemtestCL 256 100

Be aware that not all of the memory on your video card can be tested, as part
of it is reserved for use by the operating system, and (as of this writing)
both ATI and NVIDIA OpenCL drivers severely restrict the amount of memory 
available to an OpenCL program running on a GPU. If too large a test region
is specified, the program will print a warning and quit. Also, if the tested
GPU is currently driving a graphical desktop, the driver may impose time
limits on test execution such that tests over very large test regions will
time out. Timeouts or other execution errors will be trapped and will cause
the test to terminate early. Due to the currently immature state of OpenCL
implementations, they may also cause the program to crash.

If you suspect that your graphics card is having issues (for example, it fails
running Folding@home work units), we strongly recommend that you test as large
a memory region as is practical, and run thousands of test iterations. In our
testing, we have found that even "problematic" cards may only fail sporadically
(e.g., once every 50,000 test iterations). Like other stress testing tools,
to properly verify stability MemtestCL should be run for an extended period of
time.

3. ADVANCED USAGE

MemtestCL supports the use of various command line flags to enable
advanced functionality. Flags may be issued in any order, and may precede
or follow the memory size and iteration count parameters (but the memory size
must always precede the iteration count).

To run MemtestCL on an OpenCL platform other than the first (e.g., if you have
both the AMD and NVIDIA OpenCL implementations installed), use the --platform
or -p flags, passing the index of the platform to test (starting at zero). If
you do not know the index of the OpenCL platform you want, just run MemtestCL
with no parameters - a list of all platforms found will be printed immediately
following the usage summary. For example, to run MemtestCL on the second
platform in a system:
    
    MemtestCL --platform 1

To run MemtestCL on an OpenCL device (e.g., GPU) other than the first one on
the selected platform, use the --gpu or -g flags, passing the index of the
device to test (starting at zero). MemtestCL prints a list of all devices on
the selected platform (and their indices) before running tests. For example,
to run MemtestCL on the third OpenCL device on the default platform (platform
index 0):
    
    MemtestCL --gpu 2

The --platform and --gpu flags may be combined, to select a different platform
and device. This may be necessary in multi-vendor or multi-GPU configurations.
Refer to the list of platforms and devices on the current platform printed at
program start to determine the right combination. To select the third GPU on
the second platform:

    MemtestCL --platform 1 --gpu 2

At the beginning of test execution, MemtestCL issues a prompt to receive
consent to transmit the results of test data back to Stanford. No personally
identifying information is transmitted. To assist in automation, this answer
can be provided at the command prompt. To implicitly answer "yes" (that is, to
transmit results back), use the --forcecomm or -f options:
    
    MemtestCL --forcecomm

To implicitly answer "no" (that is, to forbid the tester from communicating
with Stanford) use the --bancomm or -b options:

    MemtestCL --bancomm

If transmitting data back to Stanford, the memory and core (non-shader) clock
speeds of the card are very useful data. The tester will normally prompt for
these. To provide them at the command line, use the --coreclock/-c and
--ramclock/-r options:

    MemtestCL --forcecomm --ramclock 700 --coreclock 650

Finally, to display the license agreement for MemtestCL, provide the --license
or -l options:

    MemtestCL -l

4. Frequently Asked Questions

    - I have an {ATI 2xxx/3xxx ,NVIDIA 5/6/7-series} video card and it doesn't
      work!
        - Only OpenCL-capable hardware is supported. As of this writing, this
          includes any NVIDIA GeForce 8-series or newer graphics cards (e.g.,
          GeForce 8-, 9-, GT- GTS-, GTX-series; Quadro FX, and Tesla boards),
          and the ATI Radeon 4xxx and 5xxx-series graphics cards. MemtestCL
          has also been tested on Intel and AMD CPUs using the AMD OpenCL
          implementation. OpenCL implementations exist for the Cell processor,
          but this has not been tested.

    - I have an OpenCL-capable card, but it still doesn't work!
        - You must have an OpenCL-enabled graphics driver and OpenCL runtime
          installed. For NVIDIA hardware, this requires a version 195 ForceWare
          driver or newer; ATI requires BOTH a v9.12 or newer Catalyst driver,
          as well as (at the time of writing) the ATI Stream SDK.
        
    - I get an error complaining about a missing "OpenCL.dll" on Windows!
        - You must install OpenCL. NVIDIA bundles OpenCL.dll with recent
          (v195 or newer) drivers. For ATI GPUs, you must install an OpenCL-
          capable video driver, and also install the ATI Stream SDK
          (http://developer.amd.com/gpu/atistreamsdk/). For CPU support,
          installing only the ATI Stream SDK is sufficient.

5. Licensing

Copyright 2010, Stanford University. All Rights Reserved.

Please carefully read the following terms and conditions before using this software. Use of this software indicates acceptance of this license agreement and disclaimer of all warranties.

Disclaimer of Warranty:

IN NO EVENT SHALL STANFORD UNIVERSITY BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF STANFORD UNIVERSITY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

STANFORD UNIVERSITY SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOTLIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE AND ACCOMPANYING DOCUMENTATION PROVIDED HEREUNDER IS PROVIDED "AS IS". Folding@home HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

Restrictions:

You may use this software on a computer system only if you own the system or have the written permission of the owner.

You may not alter the software or associated data files. 

Certain builds of this software incorporate by linkage code from the libintl
and libiconv libraries, which are covered by the Library GNU Public License,
available at http://www.gnu.org/licenses/lgpl-3.0.txt.

