README

   1
   2 Piglit
   3 ------
   4 1. About
   5 2. Setup
   6 3. How to run tests
   7 4. Available test sets
   8 5. How to write tests
   9 6. Todo
  10
  11
  12 1. About
  13 --------
  14
  15 Piglit is a collection of automated tests for OpenGL and OpenCL
  16 implementations.
  17
  18 The goal of Piglit is to help improve the quality of open source
  19 OpenGL and OpenCL drivers by providing developers with a simple means to
  20 perform regression tests.
  21
  22 The original tests have been taken from
  23 - Glean ( http://glean.sf.net/ ) and
  24 - Mesa ( http://www.mesa3d.org/ )
  25
  26
  27 2. Setup
  28 --------
  29
  30 First of all, you need to make sure that the following are installed:
  31
  32   - Python 2.7.x
  33   - Python Mako module
  34   - numpy (http://www.numpy.org)
  35   - six (https://pypi.python.org/pypi/six)
  36   - cmake (http://www.cmake.org)
  37   - GL, glu and glut libraries and development packages (i.e. headers)
  38   - X11 libraries and development packages (i.e. headers)
  39   - waffle (http://www.waffle-gl.org)
  40
  41 Optionally, you can install the following:
  42
  43   - nose. A python test framework, used for running the python framework
  44     test suite. (https://nose.readthedocs.org/en/latest/)
  45   - tox. A tool for testing python packages against multiple configurations of
  46     python (https://tox.readthedocs.org/en/latest/index.html)
  47   - lxml. An accelerated python xml library using libxml2 (http://lxml.de/)
  48   - simplejson. A fast C based implementation of the python json library.
  49     (https://simplejson.readthedocs.org/en/latest/)
  50   - backports.lzma. A packport of python3's lzma module to python2,
  51     this enables fast native xz (de)compression in piglit for results files
  52     (https://github.com/peterjc/backports.lzma)
  53
  54 Now configure the build system:
  55
  56   $ ccmake .
  57
  58 This will start cmake's configuration tool, just follow the onscreen
  59 instructions. The default settings should be fine, but I recommend you:
  60  - Press 'c' once (this will also check for dependencies) and then
  61  - Set "CMAKE_BUILD_TYPE" to "Debug"
  62 Now you can press 'c' again and then 'g' to generate the build system.
  63 Now build everything:
  64
  65   $ make
  66
  67
  68 2.1 Cross Compiling
  69 -------------------
  70
  71 On Linux, if cross-compiling a 32-bit build on a 64-bit host, then you must
  72 invoke cmake with option "-DCMAKE_SYSTEM_PROCESSOR=i386".
  73
  74
  75 2.2 Ubuntu
  76 ----------
  77
  78 Install development packages.
  79   $ sudo apt-get install cmake g++ mesa-common-dev libgl1-mesa-dev python-numpy python-mako freeglut3-dev x11proto-gl-dev libxrender-dev
  80
  81 Install additional components for which Ubuntu packages do not yet exist:
  82   - waffle (http://www.waffle-gl.org)
  83
  84 Configure and build.
  85   $ cmake .
  86   $ make
  87
  88
  89 2.3 Mac OS X
  90 ------------
  91
  92 Install CMake.
  93 http://cmake.org/cmake/resources/software.html
  94 Download and install 'Mac OSX Universal' platform.
  95
  96 Install Xcode.
  97 http://developer.apple.com/xcode
  98
  99 Configure and build.
 100   $ cmake .
 101   $ make
 102
 103 glean
 104
 105 glean will not build with MacOSX10.7.sdk. If you are trying to
 106 build glean on Mac OS 10.7 (Lion), you will have to use MacOSX10.6.sdk.
 107   $ ccmake .
 108 Set 'CMAKE_OSX_SYSROOT' to '/Developer/SDKs/MacOSX10.6.sdk'. Configure.
 109 Generate and exit.
 110   $ make
 111
 112
 113 2.4 Cygwin
 114 ----------
 115
 116 Install development packages.
 117   - cmake
 118   - gcc4
 119   - make
 120   - opengl
 121   - libGL-devel
 122   - python
 123   - python-numpy
 124   - libglut-devel
 125
 126 Configure and build.
 127   $ cmake .
 128   $ make
 129
 130
 131 2.5 Windows
 132 -----------
 133
 134 Install Python.
 135 http://www.python.org/download
 136
 137 Install NumPy.
 138 http://sourceforge.net/projects/numpy/files/NumPy
 139
 140 Install CMake.
 141 http://cmake.org/cmake/resources/software.html
 142 Download and install 'Windows' platform.
 143
 144 Install Microsoft Visual Studio 2013 or later.
 145 Install 'Visual C++' feature.
 146
 147 Download OpenGL Core API and Extension Header Files.
 148 http://www.opengl.org/registry/#headers
 149 Copy header files to MSVC.
 150 C:\Program Files\Microsoft Visual Studio 12.0\VC\include\GL
 151
 152 Install pip.
 153 http://www.pip-installer.org/en/latest/installing.html
 154
 155 Install python mako.
 156   > c:\Python27\Scripts\pip.exe install mako
 157
 158
 159 2.5.1 GLUT
 160 ----------
 161
 162 Download freeglut for MSVC.
 163 http://www.transmissionzero.co.uk/software/freeglut-devel
 164
 165 Open Visual Studio Command Prompt.
 166 Start Menu->All Programs->Visual Studio 2013->Visual Studio Tools->VS2013 x86 Native Tools Command Prompt
 167 CD to piglit directory.
 168
 169 Run CMake GUI.
 170   > C:\Program Files\CMake 2.8\bin\cmake-gui.exe .
 171 Configure
 172   - NMake Makefiles
 173   - Use default native compilers
 174 Set these variables in the Advanced view.
 175   - GLUT_INCLUDE_DIR
 176   - GLUT_glut_LIBRARY
 177 Configure
 178 Generate
 179 File->Exit
 180
 181 Build from the Visual Studio Command Prompt.
 182   > nmake
 183
 184 2.5.2 Waffle
 185 ------------
 186
 187 Download waffle for MSVC.
 188 http://www.waffle-gl.org/
 189
 190 Open the Command Prompt.
 191 CD to piglit directory.
 192
 193 Run CMake GUI.
 194   > C:\Program Files\CMake 2.8\bin\cmake-gui.exe .
 195 Configure
 196   - 'Visual Studio 12 2013', or
 197   - 'Visual Studio 12 2013 Win64'
 198   - Use default native compilers
 199 Set these variables in the Advanced view.
 200 Note that the values provided are for reference purposed and may differ on your system.
 201   - PIGLIT_USE_WAFFLE, BOOL, TRUE
 202   - WAFFLE_INCLUDE_DIRS, PATH, ${waffle_root}\include\waffle
 203   - WAFFLE_LDFLAGS, FILEPATH, ${waffle_root}\lib\waffle-1.lib
 204   - GLEXT_INCLUDE_DIR, PATH, C:\Program Files\Microsoft Visual Studio 12.0\VC\include\GL
 205 Configure
 206 Generate
 207 File->Exit
 208
 209 Build from the Command Prompt.
 210   > cmake --build .
 211
 212 3. How to run tests
 213 -------------------
 214
 215 Make sure that everything is set up correctly:
 216
 217   $ ./piglit run sanity results/sanity
 218
 219 You may include '.py' on the profile, or you may exclude it (sanity vs sanity.py),
 220 both are equally valid.
 221
 222 You may also preface test profiles with tests/ (or any other path you like),
 223 which may be useful for shell tab completion.
 224
 225 You may provide multiple profiles to be run at the same time:
 226
 227   $ ./piglit run quick_cl gpu deqp_gles3 results/gl-cl-combined
 228
 229 Use
 230
 231   $ ./piglit run
 232   or
 233   $ ./piglit run -h
 234
 235 To learn more about the command's syntax.
 236
 237 Have a look into the tests/ directory to see what test profiles are available:
 238
 239   $ ls tests/*.py
 240
 241 See also section 4.
 242
 243 To create some nice formatted test summaries, run
 244
 245   $ ./piglit summary html summary/sanity results/sanity.results
 246
 247 Hint: You can combine multiple test results into a single summary.
 248       During development, you can use this to watch for regressions:
 249
 250   $ ./piglit summary html summary/compare results/baseline.results results/current.results
 251
 252       You can combine as many testruns as you want this way (in theory;
 253       the HTML layout becomes awkward when the number of testruns increases)
 254
 255 Have a look at the results with a browser:
 256
 257   $ xdg-open summary/sanity/index.html
 258
 259 The summary shows the 'status' of a test:
 260
 261  pass   This test has completed successfully.
 262
 263  warn   The test completed successfully, but something unexpected happened.
 264         Look at the details for more information.
 265
 266  fail   The test failed.
 267
 268  crash  The test binary exited with a non-zero exit code
 269
 270  skip   The test was skipped.
 271
 272  timeout  The test ran longer than its allotted time and was forcibly killed.
 273
 274
 275 There are also dmesg-* statuses. These have the same meaning as above, but are
 276 triggered by dmesg related messages.
 277
 278 3.1 Note
 279 --------
 280
 281 The way 'piglit run' and 'piglit summary' count tests are different, 'piglit
 282 run' counts the number of Test derived instance in the profile(s) selected,
 283 while 'piglit summary' counts the number of subtests a result contains, or it's
 284 result if there are no subtests. This means that the number shown by 'piglit
 285 run' will be less than or equal to the number calculated by 'piglit summary'.
 286
 287
 288 4. Available test sets
 289 ----------------------
 290
 291 Test sets are specified as Python scripts in the tests directory.
 292 The following test sets are currently available:
 293
 294
 295 4.1 OpenGL Tests
 296 ----------------
 297
 298 sanity.py
 299     This suite contains minimal OpenGL sanity tests. These tests must
 300     pass, otherwise the other tests will not generate reliable results.
 301
 302 all.py
 303     This suite contains all OpenGL tests.
 304
 305 quick.py
 306     Run all tests, but cut down significantly on their runtime
 307     (and thus on the number of problems they can find).
 308     In particular, this runs Glean with the --quick option, which
 309     reduces the number of visuals and state combinations tested.
 310
 311 gpu.py
 312         A further reduced set of tests from quick.py, this runs tests only
 313         for hardware functionality and not tests for the software stack.
 314
 315 llvmpipe.py
 316         A reduced set of tests from gpu.py removing tests that are problematic
 317         using llvmpipe
 318
 319 cpu.py
 320         This profile runs tests that don't touch the gpu, in other words all of
 321         the tests in quick.py that are not run by gpu.py
 322
 323 glslparser.py
 324         A subset of all.py which runs only glslparser tests
 325
 326 shader.py
 327         A subset of all.py which runs only shader tests
 328
 329
 330 4.2 OpenCL Tests
 331 ----------------
 332
 333 cl.py
 334     This suite contains all OpenCL tests.
 335
 336 quick_cl.py
 337         This runs all of the tests from cl.py as well as tests from opencv
 338         and oclconform.
 339
 340
 341 4.3 External Integration
 342 ------------------------
 343
 344 xts.py
 345         Support for running the X Test Suite using piglit.
 346
 347 igt.py
 348         Support for running Intel-gpu-tools test suite using piglit.
 349
 350 deqp_gles2.py
 351         Support for running deQP's gles2 profile with piglit.
 352
 353 deqp_gles3.py
 354         Support for running deQP's gles3 profile with piglit.
 355
 356 deqp_gles31.py
 357         Support for running deQP's gles3.1 profile with piglit.
 358
 359
 360 5. How to write tests
 361 ---------------------
 362
 363 Every test is run as a separate process. This minimizes the impact that
 364 severe bugs like memory corruption have on the testing process.
 365
 366 Therefore, tests can be implemented in an arbitrary standalone language.
 367 C is the prefered language for compiled tests, piglit also supports its own
 368 simple formats for test shaders and glsl parser input.
 369
 370 All new tests must be added to the appropriate profile, all.py profile for
 371 OpenGL and cl.py for OpenCL. There are a few basic test classes supported by the
 372 python framework:
 373
 374  GleanTest
 375    This is a test that is only used to integrate Glean tests
 376
 377  PiglitBaseTest
 378    A shared base class for all native piglit tests.
 379
 380    It starts each test as a subprocess, captures stdout and stderr, and waits
 381    for the test to return.
 382
 383    It provides test timeouts by setting the instances 'timeout' attribute to an
 384    integer > 0 which is the number of seconds the test should run.
 385
 386    It interprets output by reading stdout and looking for 'PIGLIT: ' in the
 387    output, and then reading any trailing characters as well formed json
 388    returning the test result.
 389
 390    This is a base class and should not be used directly, but provides an
 391    explanation of the behavior of the following classes.
 392
 393  PiglitGLTest
 394    A test class for native piglit OpenGL tests.
 395
 396    In addition to the properties of PiglitBaseTest it provides a mechanism for
 397    detecting test window resizes and rerunning tests as well as keyword
 398    arguments for platform requirements.
 399
 400  PiglitCLTest
 401    A test class for native piglit OpenCL tests.
 402
 403    It currently provides no special features.
 404
 405  GLSLParserTest
 406    A class for testing a glsl parser.
 407
 408    It is generally unnecessary to call this class directly as it uses a helper
 409    function to search directories for tests.
 410
 411  ShaderTest
 412    A class for testing using OpenGL shaders.
 413
 414    It is generally unnecessary to call this class directly as it uses a helper
 415    function to search directories for tests.