README 14.7 KB
Newer Older
Nicolai Hähnle's avatar
Nicolai Hähnle committed
1 2 3 4 5 6

Piglit
------
1. About
2. Setup
3. How to run tests
7 8 9
4. Available test sets
5. How to write tests
6. Todo
Nicolai Hähnle's avatar
Nicolai Hähnle committed
10 11 12 13 14


1. About
--------

15 16
Piglit is a collection of automated tests for OpenGL and OpenCL
implementations.
Nicolai Hähnle's avatar
Nicolai Hähnle committed
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
Nicolai Hähnle's avatar
Nicolai Hähnle committed
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:

32
  - Python 2.7.x
33
  - Python Mako module
34
  - numpy (http://www.numpy.org)
35
  - six (https://pypi.python.org/pypi/six)
Nicolai Hähnle's avatar
Nicolai Hähnle committed
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)
39
  - waffle (http://www.waffle-gl.org)
40
  - mako
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/)
47 48
  - jsonstreams. A JSON stream writer for python.
    (https://jsonstreams.readthedocs.io/en/stable/)
49 50 51

For Python 2.x you can install the following to add features, these are
unnecessary for python3:
52
  - backports.lzma. A backport of python3's lzma module to python2,
53 54
    this enables fast native xz (de)compression in piglit for results files
    (https://github.com/peterjc/backports.lzma)
55 56 57
  - subprocess32. A backport of the subprocess from python3.2, which includes
    timeout support. This only works for Linux

58
For testing the python framework using "py.test unittests/framework"
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)
63 64
  - mock. A python module for mocking other python modules. Required only for
    unittests (https://github.com/testing-cabal/mock)
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
69
  - pytest-raises. A plugin for pytest that allows decorating tests that expect
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's avatar
Nicolai Hähnle committed
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


88 89 90
2.1 Cross Compiling
-------------------

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".
95

Nicolai Hähnle's avatar
Nicolai Hähnle committed
96

97 98 99 100
2.2 Ubuntu
----------

Install development packages.
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
102

103 104 105 106 107
Configure and build.
  $ cmake .
  $ make


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


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


141 142 143
2.5 Windows
-----------

144
Install Python 3.
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.

151 152 153 154 155
Download and install Ninja
https://github.com/ninja-build/ninja/releases

Install MinGW-w64
https://mingw-w64.org/
156 157 158

Download OpenGL Core API and Extension Header Files.
http://www.opengl.org/registry/#headers
159
Pass -DGLEXT_INCLUDE_DIR=/path/to/headers
160 161

Install python mako.
162 163 164 165
> pip install mako

Install NumPy.
> pip install numpy
166

167 168 169 170

2.5.1 GLUT
----------

171 172
Download freeglut for Mingw.
http://www.transmissionzero.co.uk/software/freeglut-devel/
173

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
176 177


178 179 180
2.5.2 Waffle
------------

181
Download and build waffle for MinGW.
182 183 184 185 186
http://www.waffle-gl.org/

Open the Command Prompt.
CD to piglit directory.

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

189

Nicolai Hähnle's avatar
Nicolai Hähnle committed
190 191 192 193 194
3. How to run tests
-------------------

Make sure that everything is set up correctly:

195
  $ ./piglit run sanity results/sanity
Nicolai Hähnle's avatar
Nicolai Hähnle committed
196

197 198
You may include '.py' on the profile, or you may exclude it (sanity vs sanity.py),
both are equally valid.
199

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.

203 204
You may provide multiple profiles to be run at the same time:
  
205
  $ ./piglit run quick_cl gpu deqp_gles3 results/gl-cl-combined
206

207
Use
Nicolai Hähnle's avatar
Nicolai Hähnle committed
208

209 210 211
  $ ./piglit run
  or
  $ ./piglit run -h
Nicolai Hähnle's avatar
Nicolai Hähnle committed
212

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's avatar
Nicolai Hähnle committed
216

217
  $ ls tests/*.py
Nicolai Hähnle's avatar
Nicolai Hähnle committed
218

219 220
See also section 4.

Nicolai Hähnle's avatar
Nicolai Hähnle committed
221 222
To create some nice formatted test summaries, run

223
  $ ./piglit summary html summary/sanity results/sanity
Nicolai Hähnle's avatar
Nicolai Hähnle committed
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:

228
  $ ./piglit summary html summary/compare results/baseline results/current
Nicolai Hähnle's avatar
Nicolai Hähnle committed
229

230
      You can combine as many testruns as you want this way (in theory;
Nicolai Hähnle's avatar
Nicolai Hähnle committed
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:

239
 pass   This test has completed successfully.
Nicolai Hähnle's avatar
Nicolai Hähnle committed
240

241 242
 warn   The test completed successfully, but something unexpected happened.
        Look at the details for more information.
Nicolai Hähnle's avatar
Nicolai Hähnle committed
243

244
 fail   The test failed.
Nicolai Hähnle's avatar
Nicolai Hähnle committed
245

246
 crash  The test binary exited with a non-zero exit code.
Nicolai Hähnle's avatar
Nicolai Hähnle committed
247

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's avatar
Nicolai Hähnle committed
255

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<x>_COMPATABILITY extensions
      for OpenGL

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.

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.

287
3.2 Note
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's avatar
Nicolai Hähnle committed
296

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.


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:

313 314 315 316

4.1 OpenGL Tests 
----------------

317
sanity.py
318
    This suite contains minimal OpenGL sanity tests. These tests must
319 320
    pass, otherwise the other tests will not generate reliable results.

321 322
all.py
    This suite contains all OpenGL tests.
323

324
quick.py
Nicolai Hähnle's avatar
Nicolai Hähnle committed
325 326 327
    Run all tests, but cut down significantly on their runtime
    (and thus on the number of problems they can find).

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.

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
339

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

346 347 348
no_error.py
	A modified version of the test list run as khr_no_error variants

349

350 351 352 353 354 355 356
4.2 OpenCL Tests
----------------

cl.py
    This suite contains all OpenCL tests.

quick_cl.py
357
	This runs all of the tests from cl.py as well as tests from opencv
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.

370 371 372
deqp_egl.py
	Support for running dEQP's EGL profile with piglit.

373
deqp_gles2.py
374
	Support for running dEQP's gles2 profile with piglit.
375

376
deqp_gles3.py
377
	Support for running dEQP's gles3 profile with piglit.
378

379
deqp_gles31.py
380
	Support for running dEQP's gles3.1 profile with piglit.
381

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.

403

404
5. How to write tests
Nicolai Hähnle's avatar
Nicolai Hähnle committed
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.
411
C is the preferred language for compiled tests, piglit also supports its own
412
simple formats for test shaders and glsl parser input.
Nicolai Hähnle's avatar
Nicolai Hähnle committed
413

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's avatar
Nicolai Hähnle committed
417

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.

431 432
   This is a base class and should not be used directly, but provides an
   explanation of the behavior of the following classes.
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.

444
   It currently provides no special features.
445 446 447 448

 GLSLParserTest
   A class for testing a glsl parser.

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's avatar
Nicolai Hähnle committed
451

452
 ShaderTest
453
   A class for testing using OpenGL shaders.
Nicolai Hähnle's avatar
Nicolai Hähnle committed
454

455 456
   It is generally unnecessary to call this class directly as it uses a helper
   function to search directories for tests.
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=<deqp source dir>/modules/gles2/deqp-gles2

[deqp-gles3]
498
bin=<deqp source dir>/modules/gles3/deqp-gles3
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=<deqp source dir>/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 source dir>/cts/glcts
"""