tests/cl/README

   1
   2 OpenCL testing framework
   3 ------------------------
   4 1. About
   5 2. Test types
   6 3. How to run tests
   7 4. How to write tests
   8
   9
  10 1. About
  11 --------
  12
  13 This framework is used to write OpenCL tests for Piglit framework.
  14
  15 The framework supports creating tests to run once or per each platform (if
  16 cl_khr_icd is supported, else only one platform is tested) or per each
  17 device. Each test can be limited to a particular group of platforms or
  18 devices.
  19
  20 There are different test types which can be used to write a test. These
  21 test types automate checking for different implementation functionality
  22 (OpenCL version, extensions, filter by platform name,...) and creating
  23 objects (context creation, program creation and building, source code
  24 loading, buffer creation and buffer data initialization,...).
  25
  26 2. Test types
  27 -------------
  28
  29 Currently there are three different types of tests:
  30
  31  * API tests:
  32     These type of tests are meant for testing the API functions.
  33     Documentation is located at tests/cl/doc_api.c.
  34
  35  * Program tests:
  36     These type of tests are meant for testing compilation of OpenCL C
  37     programs and kernel execution. These tests can be normal C/C++ programs
  38     or special files that are parsed by program-tester
  39     (bin/cl-program-tester). This program takes in an ini-like file
  40     (test.program_test) or an OpenCL source code (test.cl) with a special
  41     comment. The binary programs (test.bin) can be referenced from
  42     program_test files.
  43     Documentation is located at tests/cl/doc_program.c,
  44     test/cl/doc_program.cl and test/cl/doc_program.program_test.
  45
  46  * Custom tests:
  47     These type of tests are for tests that don't fit well in any other test
  48     type.
  49     Documentation is located at tests/cl/doc_custom.c.
  50
  51 3. How to run tests
  52 -------------------
  53
  54 All compilable tests are compiled to the bin/ folder. Each test has a
  55 prefix applied to it, depending on its type:
  56   * API: cl-api-
  57   * Program: cl-program-
  58   * Custom: cl-custom-
  59
  60 The OpenCL C and program_test tests are parsed and run by program-tester
  61 that is located at bin/cl-program-tester.
  62
  63 Each test can be run independently or they can all be run by Piglit as a
  64 test set. The test set is located at tests/all_cl.tests.
  65
  66 Each test accepts the following environment variables:
  67  * PIGLIT_CL_PLATFORM: Only run test on platforms whose platform name
  68                        begins with PIGLIT_CL_PLATFORM. (This variable
  69                        is accepted only when the test is run per platform
  70                        or per device)
  71  * PIGLIT_CL_DEVICE: Only run tests on devices whose device name begins
  72                      with PIGLIT_CL_DEVICE. (This variable is accepted only
  73                      when the test is run per device)
  74  * PIGLIT_CL_VERSION: Test against OpenCL version PIGLIT_CL_VERSION. This
  75                       variable is a normal OprnCL versioning number
  76                       (example: 1.1).
  77
  78 The same variables are accepted as program arguments:
  79  * -platform name: Same as PIGLIT_CL_PLATFORM.
  80  * -device name: Same as PIGLIT_CL_DEVICE.
  81  * -version ver: Same as PIGLIT_CL_VERSION.
  82
  83 4. How to write tests
  84 ---------------------
  85
  86 Tests should be created in appropriate folder in cl/tests:
  87  * api/: API tests
  88  * program/: Program tests
  89  * program/build/: Program-tester compilation tests
  90  * program/build/fail/: Program-tester compilation tests that should fail
  91  * program/execute: Program-tester kernel execution tests
  92
  93 Templates for the different types of tests and documentation for them is
  94 located at tests/cl/doc_* and tests/cl/template_*.
  95
  96 To cover the widest range of OpenCL versions with one test, each compiled
  97 test is passed an env->version variable which contains a version number
  98 against which the test should test. Also the PIGLIT_CL_VERSION macro
  99 present in piglit-util-cl.h contains a version number against which Piglit
 100 was compiled. Both numbers are multiples of 10 of OpenCL version (1.1 -> 11).
 101
 102 The program tests run by program-tester (bin/cl-program-tester) are compiled
 103 with a macro __OPENCL_C_VERSION__ which tells against which version the
 104 source will be compiled. To comply with OpenCL spec this version number is a
 105 multiple of 100 of OpenCL C version (1.1 -> 110).
 106
 107 All new tests should be added to an appropriate group in tests/all_cl.tests.