Nicolai Hähnle committed Mar 24, 2007 1 2 3 4 5 6  Piglit ------ 1. About 2. Setup 3. How to run tests  Nicolai Hähnle committed Sep 21, 2009 7 8 9 4. Available test sets 5. How to write tests 6. Todo  Nicolai Hähnle committed Mar 24, 2007 10 11 12 13 14  1. About --------  Blaž Tomažič committed Sep 05, 2012 15 16 Piglit is a collection of automated tests for OpenGL and OpenCL implementations.  Nicolai Hähnle committed Mar 24, 2007 17 18  The goal of Piglit is to help improve the quality of open source  Blaž Tomažič committed Sep 05, 2012 19 OpenGL and OpenCL drivers by providing developers with a simple means to  Nicolai Hähnle committed Mar 24, 2007 20 21 22 23 24 25 26 27 28 29 30 31 perform regression tests. The original tests have been taken from - Glean ( http://glean.sf.net/ ) and - Mesa ( http://www.mesa3d.org/ ) 2. Setup -------- First of all, you need to make sure that the following are installed:  Dylan Baker committed Aug 19, 2014 32  - Python 2.7.x  Brian Paul committed Mar 18, 2013 33  - Python Mako module  Paul Berry committed Aug 05, 2011 34  - numpy (http://www.numpy.org)  Dylan Baker committed Feb 23, 2015 35  - six (https://pypi.python.org/pypi/six)  Nicolai Hähnle committed Mar 24, 2007 36 37 38  - cmake (http://www.cmake.org) - GL, glu and glut libraries and development packages (i.e. headers) - X11 libraries and development packages (i.e. headers)  Chad Versace committed May 27, 2014 39  - waffle (http://www.waffle-gl.org)  Dylan Baker committed Aug 05, 2016 40  - mako  Dylan Baker committed Oct 28, 2014 41 42 43 44 45 46  Optionally, you can install the following: - lxml. An accelerated python xml library using libxml2 (http://lxml.de/) - simplejson. A fast C based implementation of the python json library. (https://simplejson.readthedocs.org/en/latest/)  Dylan Baker committed Sep 09, 2016 47 48  - jsonstreams. A JSON stream writer for python. (https://jsonstreams.readthedocs.io/en/stable/)  Dylan Baker committed Aug 05, 2016 49 50 51  For Python 2.x you can install the following to add features, these are unnecessary for python3:  Rhys Kidd committed Dec 23, 2017 52  - backports.lzma. A backport of python3's lzma module to python2,  Dylan Baker committed Jul 09, 2015 53 54  this enables fast native xz (de)compression in piglit for results files (https://github.com/peterjc/backports.lzma)  Dylan Baker committed Aug 05, 2016 55 56 57  - subprocess32. A backport of the subprocess from python3.2, which includes timeout support. This only works for Linux  Eric Anholt committed Aug 24, 2016 58 For testing the python framework using "py.test unittests/framework"  Dylan Baker committed Aug 05, 2016 59 60 61 62  - py.test. A python test framework, used for running the python framework test suite. - tox. A tool for testing python packages against multiple configurations of python (https://tox.readthedocs.org/en/latest/index.html)  Dylan Baker committed Oct 29, 2015 63 64  - mock. A python module for mocking other python modules. Required only for unittests (https://github.com/testing-cabal/mock)  Dylan Baker committed Aug 05, 2016 65 66 67 68  - psutil. A portable process library for python - jsonschema. A JSON validator library for python - pytest-mock. A mock plugin for pytest - pytest-pythonpath. A plugin for pytest to do automagic with sys.path  Rhys Kidd committed Dec 23, 2017 69  - pytest-raises. A plugin for pytest that allows decorating tests that expect  Dylan Baker committed Aug 05, 2016 70 71 72  failure - pytest-warnings. A plugin for pytest that handles python warnings - pytest-timeout. A plugin for pytest to timeout tests.  Nicolai Hähnle committed Mar 24, 2007 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87  Now configure the build system: $ccmake . This will start cmake's configuration tool, just follow the onscreen instructions. The default settings should be fine, but I recommend you: - Press 'c' once (this will also check for dependencies) and then - Set "CMAKE_BUILD_TYPE" to "Debug" Now you can press 'c' again and then 'g' to generate the build system. Now build everything:$ make  chadversary committed Jul 20, 2011 88 89 90 2.1 Cross Compiling -------------------  Konstantin Kharlamov committed Mar 08, 2017 91 92 93 94 On Linux, if cross-compiling a 32-bit build on a 64-bit host, first make sure you didn't have CMakeCache.txt file left from 64-bit build (it would retain old flags), then you must invoke cmake with options "-DCMAKE_SYSTEM_PROCESSOR=x86 -DCMAKE_C_FLAGS=-m32 -DCMAKE_CXX_FLAGS=-m32".  chadversary committed Jul 20, 2011 95   Nicolai Hähnle committed Mar 24, 2007 96   Vinson Lee committed Aug 08, 2011 97 98 99 100 2.2 Ubuntu ---------- Install development packages.  Erik Brangs committed Apr 14, 2016 101  $sudo apt-get install cmake g++ mesa-common-dev libgl1-mesa-dev python-numpy python-mako freeglut3-dev x11proto-gl-dev libxrender-dev libwaffle-dev  Chad Versace committed Nov 05, 2012 102   Vinson Lee committed Aug 08, 2011 103 104 105 106 107 Configure and build.$ cmake . $make  Vinson Lee committed Aug 08, 2011 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 2.3 Mac OS X ------------ Install CMake. http://cmake.org/cmake/resources/software.html Download and install 'Mac OSX Universal' platform. Install Xcode. http://developer.apple.com/xcode Configure and build.$ cmake . $make  Vinson Lee committed Aug 11, 2011 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 2.4 Cygwin ---------- Install development packages. - cmake - gcc4 - make - opengl - libGL-devel - python - python-numpy - libglut-devel Configure and build.$ cmake . $make  Vinson Lee committed Nov 02, 2011 141 142 143 2.5 Windows -----------  Jose Fonseca committed Jul 31, 2017 144 Install Python 3.  Vinson Lee committed Nov 02, 2011 145 146 147 148 149 150 http://www.python.org/download Install CMake. http://cmake.org/cmake/resources/software.html Download and install 'Windows' platform.  Jose Fonseca committed Jul 31, 2017 151 152 153 154 155 Download and install Ninja https://github.com/ninja-build/ninja/releases Install MinGW-w64 https://mingw-w64.org/  Vinson Lee committed Nov 02, 2011 156 157 158  Download OpenGL Core API and Extension Header Files. http://www.opengl.org/registry/#headers  Jose Fonseca committed Jul 31, 2017 159 Pass -DGLEXT_INCLUDE_DIR=/path/to/headers  Jordan Justen committed Apr 02, 2014 160 161  Install python mako.  Jose Fonseca committed Jul 31, 2017 162 163 164 165 > pip install mako Install NumPy. > pip install numpy  Jordan Justen committed Apr 02, 2014 166   Emil Velikov committed Dec 14, 2014 167 168 169 170  2.5.1 GLUT ----------  Jose Fonseca committed Jul 31, 2017 171 172 Download freeglut for Mingw. http://www.transmissionzero.co.uk/software/freeglut-devel/  Emil Velikov committed Dec 14, 2014 173   Jose Fonseca committed Jul 31, 2017 174 175 > cmake -H. -Bbuild -G "Ninja" -DGLEXT_INCLUDE_DIR=\path\to\glext -DGLUT_INCLUDE_DIR=\path\to\freeglut\include -DGLUT_glut_LIBRARY=\path\to\freeglut\lib\x64\libfreeglut.a -DGLEXT_INCLUDE_DIR=\path\to\glext > ninja -C build  Vinson Lee committed Nov 02, 2011 176 177   Emil Velikov committed Dec 14, 2014 178 179 180 2.5.2 Waffle ------------  Jose Fonseca committed Jul 31, 2017 181 Download and build waffle for MinGW.  Emil Velikov committed Dec 14, 2014 182 183 184 185 186 http://www.waffle-gl.org/ Open the Command Prompt. CD to piglit directory.  Jose Fonseca committed Jul 31, 2017 187 188 > cmake -H. -Bbuild -G "Ninja" -DGLEXT_INCLUDE_DIR=\path\to\glext -DPIGLIT_USE_WAFFLE=TRUE -DWAFFLE_INCLUDE_DIRS=\path\to\waffle\include\waffle WAFFLE_LDFLAGS=\path\to\waffle\lib\libwaffle-1.a  Vinson Lee committed Nov 02, 2011 189   Nicolai Hähnle committed Mar 24, 2007 190 191 192 193 194 3. How to run tests ------------------- Make sure that everything is set up correctly:  Dylan Baker committed Jan 27, 2015 195 $ ./piglit run sanity results/sanity  Nicolai Hähnle committed Mar 24, 2007 196   Dylan Baker committed Oct 28, 2014 197 198 You may include '.py' on the profile, or you may exclude it (sanity vs sanity.py), both are equally valid.  Chad Versace committed Mar 12, 2011 199   Dylan Baker committed Jan 27, 2015 200 201 202 You may also preface test profiles with tests/ (or any other path you like), which may be useful for shell tab completion.  Dylan Baker committed Jan 27, 2015 203 204 You may provide multiple profiles to be run at the same time:  Dylan Baker committed Jan 27, 2015 205  $./piglit run quick_cl gpu deqp_gles3 results/gl-cl-combined  Dylan Baker committed Jan 27, 2015 206   Chad Versace committed Mar 12, 2011 207 Use  Nicolai Hähnle committed Mar 24, 2007 208   Dylan Baker committed Oct 28, 2014 209 210 211 $ ./piglit run or $./piglit run -h  Nicolai Hähnle committed Mar 24, 2007 212   Dylan Baker committed Jan 27, 2015 213 214 215 To learn more about the command's syntax. Have a look into the tests/ directory to see what test profiles are available:  Nicolai Hähnle committed Mar 24, 2007 216   Dylan Baker committed Jan 12, 2014 217 $ ls tests/*.py  Nicolai Hähnle committed Mar 24, 2007 218   Nicolai Hähnle committed Sep 21, 2009 219 220 See also section 4.  Nicolai Hähnle committed Mar 24, 2007 221 222 To create some nice formatted test summaries, run  Rhys Kidd committed Oct 03, 2017 223  $./piglit summary html summary/sanity results/sanity  Nicolai Hähnle committed Mar 24, 2007 224 225 226 227  Hint: You can combine multiple test results into a single summary. During development, you can use this to watch for regressions:  Rhys Kidd committed Oct 03, 2017 228 $ ./piglit summary html summary/compare results/baseline results/current  Nicolai Hähnle committed Mar 24, 2007 229   Dylan Baker committed Oct 28, 2014 230  You can combine as many testruns as you want this way (in theory;  Nicolai Hähnle committed Mar 24, 2007 231 232 233 234 235 236 237 238  the HTML layout becomes awkward when the number of testruns increases) Have a look at the results with a browser: $xdg-open summary/sanity/index.html The summary shows the 'status' of a test:  Dylan Baker committed Oct 28, 2014 239  pass This test has completed successfully.  Nicolai Hähnle committed Mar 24, 2007 240   Dylan Baker committed Oct 28, 2014 241 242  warn The test completed successfully, but something unexpected happened. Look at the details for more information.  Nicolai Hähnle committed Mar 24, 2007 243   Dylan Baker committed Oct 28, 2014 244  fail The test failed.  Nicolai Hähnle committed Mar 24, 2007 245   Rhys Kidd committed Dec 23, 2017 246  crash The test binary exited with a non-zero exit code.  Nicolai Hähnle committed Mar 24, 2007 247   Dylan Baker committed Oct 28, 2014 248 249 250 251 252 253 254  skip The test was skipped. timeout The test ran longer than its allotted time and was forcibly killed. There are also dmesg-* statuses. These have the same meaning as above, but are triggered by dmesg related messages.  Nicolai Hähnle committed Mar 24, 2007 255   Dylan Baker committed Jan 07, 2016 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 3.1 Environment Variables ------------------------- There are a number of environment variables that control the way piglit behaves. PIGLIT_COMPRESSION Overrides the compression method used. The same values that piglit.conf allows for core:compression. PIGLIT_PLATFORM Overrides the platform run on. These allow the same values as piglit run -p. This values is honored by the tests themselves, and can be used when running a single test. PIGLIT_FORCE_GLSLPARSER_DESKTOP Force glslparser tests to be run with the desktop (non-gles) version of glslparsertest. This can be used to test ES_COMPATABILITY extensions for OpenGL  Dylan Baker committed Jan 08, 2016 276 277 278 279 280 281 282  PIGLIT_NO_FAST_SKIP Piglit has a mechanism run in the python layer for skipping tests with unmet OpenGL or window system dependencies without starting a new process (which is expensive). Sometimes this system doesn't work or is undesirable, setting this environment variable to True will disable this system.  Dylan Baker committed Jan 21, 2016 283 284 285 286  PIGLIT_NO_TIMEOUT When this variable is true in python then any timeouts given by tests will be ignored, and they will run until completion or they are killed.  Dylan Baker committed Jan 07, 2016 287 3.2 Note  Dylan Baker committed Aug 28, 2015 288 289 290 291 292 293 294 295 -------- The way 'piglit run' and 'piglit summary' count tests are different, 'piglit run' counts the number of Test derived instance in the profile(s) selected, while 'piglit summary' counts the number of subtests a result contains, or it's result if there are no subtests. This means that the number shown by 'piglit run' will be less than or equal to the number calculated by 'piglit summary'.  Nicolai Hähnle committed Mar 24, 2007 296   Dylan Baker committed Mar 03, 2016 297 298 299 300 301 302 303 304 305 306 3.3 Shell Completions --------------------- Piglit has completions for bash, located in completions/bash/piglit. Once this file is sourced into bash piglit and ./piglit will have tab completion available. For global availability place the file somewhere that bash will source the file on startup. If piglit is installed and bash-completions are available, then this completion file will be installed system-wide.  Nicolai Hähnle committed Sep 21, 2009 307 308 309 310 311 312 4. Available test sets ---------------------- Test sets are specified as Python scripts in the tests directory. The following test sets are currently available:  Dylan Baker committed Oct 28, 2014 313 314 315 316  4.1 OpenGL Tests ----------------  Dylan Baker committed Jan 12, 2014 317 sanity.py  Dylan Baker committed Oct 28, 2014 318  This suite contains minimal OpenGL sanity tests. These tests must  Nicolai Hähnle committed Sep 21, 2009 319 320  pass, otherwise the other tests will not generate reliable results.  Dylan Baker committed Jan 12, 2014 321 322 all.py This suite contains all OpenGL tests.  Nicolai Hähnle committed Sep 21, 2009 323   Dylan Baker committed Jan 12, 2014 324 quick.py  Nicolai Hähnle committed Sep 21, 2009 325 326 327  Run all tests, but cut down significantly on their runtime (and thus on the number of problems they can find).  Dylan Baker committed Oct 28, 2014 328 329 330 331 gpu.py A further reduced set of tests from quick.py, this runs tests only for hardware functionality and not tests for the software stack.  Dylan Baker committed Jan 27, 2015 332 333 334 335 336 337 338 llvmpipe.py A reduced set of tests from gpu.py removing tests that are problematic using llvmpipe cpu.py This profile runs tests that don't touch the gpu, in other words all of the tests in quick.py that are not run by gpu.py  Nicolai Hähnle committed Sep 21, 2009 339   Dylan Baker committed Feb 23, 2015 340 341 342 343 344 345 glslparser.py A subset of all.py which runs only glslparser tests shader.py A subset of all.py which runs only shader tests  Rhys Kidd committed Oct 03, 2017 346 347 348 no_error.py A modified version of the test list run as khr_no_error variants  Nicolai Hähnle committed Sep 21, 2009 349   Dylan Baker committed Oct 28, 2014 350 351 352 353 354 355 356 4.2 OpenCL Tests ---------------- cl.py This suite contains all OpenCL tests. quick_cl.py  Dylan Baker committed Jan 27, 2015 357  This runs all of the tests from cl.py as well as tests from opencv  Dylan Baker committed Oct 28, 2014 358 359 360 361 362 363 364 365 366 367 368 369  and oclconform. 4.3 External Integration ------------------------ xts.py Support for running the X Test Suite using piglit. igt.py Support for running Intel-gpu-tools test suite using piglit.  Rhys Kidd committed Oct 03, 2017 370 371 372 deqp_egl.py Support for running dEQP's EGL profile with piglit.  Dylan Baker committed Jun 01, 2015 373 deqp_gles2.py  Rhys Kidd committed Oct 03, 2017 374  Support for running dEQP's gles2 profile with piglit.  Dylan Baker committed Jun 01, 2015 375   Dylan Baker committed Jan 27, 2015 376 deqp_gles3.py  Rhys Kidd committed Oct 03, 2017 377  Support for running dEQP's gles3 profile with piglit.  Dylan Baker committed Jan 27, 2015 378   Dylan Baker committed Jun 01, 2015 379 deqp_gles31.py  Rhys Kidd committed Oct 03, 2017 380  Support for running dEQP's gles3.1 profile with piglit.  Dylan Baker committed Jun 01, 2015 381   Rhys Kidd committed Oct 03, 2017 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 deqp_vk.py Support for running the official Khronos Vulkan CTS profile with piglit. khr_gl.py Support for running the open source Khronos OpenGL CTS tests with piglit. khr_gl45.py Support for running the open source Khronos OpenGL 4.5 CTS tests with piglit. cts_gl.py Support for running the closed source Khronos OpenGL CTS tests with piglit. cts_gl45.py Support for running the closed source Khronos OpenGL 4.5 CTS tests with piglit. cts_gles.py Support for running the closed source Khronos GLES CTS tests with piglit. oglconform.py Support for running sub-test of the Intel oglconform test suite with piglit.  Dylan Baker committed Oct 28, 2014 403   Nicolai Hähnle committed Sep 21, 2009 404 5. How to write tests  Nicolai Hähnle committed Mar 24, 2007 405 406 407 408 409 410 --------------------- Every test is run as a separate process. This minimizes the impact that severe bugs like memory corruption have on the testing process. Therefore, tests can be implemented in an arbitrary standalone language.  Eric Engestrom committed Apr 16, 2016 411 C is the preferred language for compiled tests, piglit also supports its own  Dylan Baker committed Oct 28, 2014 412 simple formats for test shaders and glsl parser input.  Nicolai Hähnle committed Mar 24, 2007 413   Dylan Baker committed Oct 28, 2014 414 415 416 All new tests must be added to the appropriate profile, all.py profile for OpenGL and cl.py for OpenCL. There are a few basic test classes supported by the python framework:  Nicolai Hähnle committed Mar 24, 2007 417   Dylan Baker committed Oct 28, 2014 418 419 420 421 422 423 424 425 426 427 428 429 430  PiglitBaseTest A shared base class for all native piglit tests. It starts each test as a subprocess, captures stdout and stderr, and waits for the test to return. It provides test timeouts by setting the instances 'timeout' attribute to an integer > 0 which is the number of seconds the test should run. It interprets output by reading stdout and looking for 'PIGLIT: ' in the output, and then reading any trailing characters as well formed json returning the test result.  Pavol Klačanský committed Dec 15, 2014 431 432  This is a base class and should not be used directly, but provides an explanation of the behavior of the following classes.  Dylan Baker committed Oct 28, 2014 433 434 435 436 437 438 439 440 441 442 443  PiglitGLTest A test class for native piglit OpenGL tests. In addition to the properties of PiglitBaseTest it provides a mechanism for detecting test window resizes and rerunning tests as well as keyword arguments for platform requirements. PiglitCLTest A test class for native piglit OpenCL tests.  Pavol Klačanský committed Dec 15, 2014 444  It currently provides no special features.  Dylan Baker committed Oct 28, 2014 445 446 447 448  GLSLParserTest A class for testing a glsl parser.  Pavol Klačanský committed Dec 15, 2014 449 450  It is generally unnecessary to call this class directly as it uses a helper function to search directories for tests.  Nicolai Hähnle committed Mar 24, 2007 451   Dylan Baker committed Oct 28, 2014 452  ShaderTest  Pavol Klačanský committed Dec 15, 2014 453  A class for testing using OpenGL shaders.  Nicolai Hähnle committed Mar 24, 2007 454   Pavol Klačanský committed Dec 15, 2014 455 456  It is generally unnecessary to call this class directly as it uses a helper function to search directories for tests.  Dylan Baker committed Dec 31, 2015 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497  6. Integration -------------- Piglit provides integration for other test suites as well. The rational for this is that it provides piglit's one process per test protections (one test crashing does not crash the whole suite), and access to piglit's reporting tools. Most integration is done through the use of piglit.conf, or through environment variables, with piglit.conf being the preferred method. 6.1 dEQP -------- Piglit provides a generic layer for dEQP based test suites, and specific integration for several suites. I suggest using Chad Versace's repo of dEQP, which contains a gbm target. https://github.com/chadversary/deqp It should be built as follows: cmake . -DDEQP_TARGET=gbm -GNinja Additional targets are available in the targets directory. gbm isn't compatible for most (any?) blob driver, so another target might be necessary if that is a requirement. One of the x11_* targets or drm is probably a good choice. The use of ninja is optional. Once dEQP is built add the following information to piglit.conf, which can either be located in the root of the piglit repo, or in$XDG_CONFIG_HOME (usually \$HOME/.config). """ [deqp-gles2] bin=/modules/gles2/deqp-gles2 [deqp-gles3]  Rhys Kidd committed Dec 23, 2017 498 bin=/modules/gles3/deqp-gles3  Dylan Baker committed Dec 31, 2015 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522  [deqp-gles31] bin=/modules/gles31/deqp-gles31 """ These platforms can be run using deqp_gles*.py as a suite in piglit. For example: ./piglit run deqp_gles31 my_results -c It is also possible to mix integrated suites and piglit profiles together: ./piglit run deqp_gles31 quick cl my_results dEQP profiles generally contain all of the tests from the previous profile, so gles31 covers gles3 and gles2. 6.2 Khronos CTS --------------- Add the following to your piglit.conf file: """ [cts] bin=/cts/glcts """