README.md 15.5 KB
Newer Older
Nicolai Hähnle's avatar
Nicolai Hähnle committed
1 2

Piglit
3 4
======

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


1. About
--------

16 17
Piglit is a collection of automated tests for OpenGL and OpenCL
implementations.
Nicolai Hähnle's avatar
Nicolai Hähnle committed
18 19

The goal of Piglit is to help improve the quality of open source
20
OpenGL and OpenCL drivers by providing developers with a simple means to
Nicolai Hähnle's avatar
Nicolai Hähnle committed
21 22 23 24 25 26 27 28 29 30 31 32
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:

33
  - Python 2.7.x or >=3.4
34
  - Python Mako module
35
  - numpy (http://www.numpy.org)
36
  - six (https://pypi.python.org/pypi/six)
Nicolai Hähnle's avatar
Nicolai Hähnle committed
37 38 39
  - cmake (http://www.cmake.org)
  - GL, glu and glut libraries and development packages (i.e. headers)
  - X11 libraries and development packages (i.e. headers)
40
  - waffle (http://www.waffle-gl.org)
41
  - mako
42 43 44 45 46 47

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/)
48 49
  - jsonstreams. A JSON stream writer for python.
    (https://jsonstreams.readthedocs.io/en/stable/)
50 51
  - VkRunner. A shader script testing tool for Vulkan.
    (https://github.com/igalia/vkrunner)
52 53 54

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

61
For testing the python framework using `py.test unittests/framework`
62 63 64 65
  - 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)
66 67
  - mock. A python module for mocking other python modules. Required only for
    unittests (https://github.com/testing-cabal/mock)
68 69 70 71
  - 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
72
  - pytest-raises. A plugin for pytest that allows decorating tests that expect
73 74 75
    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
76 77 78

Now configure the build system:

79
    $ ccmake .
Nicolai Hähnle's avatar
Nicolai Hähnle committed
80 81 82 83

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
84
 - Set `CMAKE_BUILD_TYPE` to `Debug` Now you can press 'c' again and then 'g' to generate the build system.
Nicolai Hähnle's avatar
Nicolai Hähnle committed
85 86
Now build everything:

87
    $ make
Nicolai Hähnle's avatar
Nicolai Hähnle committed
88 89


90
### 2.1 Cross Compiling
91

92 93
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
94 95
flags), then you must invoke cmake with options
`-DCMAKE_SYSTEM_PROCESSOR=x86 -DCMAKE_C_FLAGS=-m32 -DCMAKE_CXX_FLAGS=-m32`.
96

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

98
### 2.2 Ubuntu
99 100

Install development packages.
101 102

    $ 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
103

104
Configure and build.
105 106 107

    $ cmake .
    $ make
108 109


110
### 2.3 Mac OS X
111

112
Install CMake.
113 114 115 116 117 118 119
http://cmake.org/cmake/resources/software.html
Download and install 'Mac OSX Universal' platform.

Install Xcode.
http://developer.apple.com/xcode

Configure and build.
120 121 122

    $ cmake .
    $ make
123 124


125
### 2.4 Cygwin
126 127 128 129 130 131 132 133 134 135 136 137

Install development packages.
  - cmake
  - gcc4
  - make
  - opengl
  - libGL-devel
  - python
  - python-numpy
  - libglut-devel

Configure and build.
138 139 140

    $ cmake .
    $ make
141 142


143
### 2.5 Windows
144

145
Install Python 3.
146 147 148 149 150 151
http://www.python.org/download

Install CMake.
http://cmake.org/cmake/resources/software.html
Download and install 'Windows' platform.

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

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

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

Install python mako.
163 164

    pip install mako
165 166

Install NumPy.
167 168

    pip install numpy
169

170

171
#### 2.5.1 GLUT
172

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

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


180
#### 2.5.2 Waffle
181

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

Open the Command Prompt.
CD to piglit directory.

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

190

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

Make sure that everything is set up correctly:

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

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

201 202 203
You may also preface test profiles with tests/ (or any other path you like),
which may be useful for shell tab completion.

204
You may provide multiple profiles to be run at the same time:
205

206
    $ ./piglit run quick_cl gpu deqp_gles3 results/gl-cl-combined
207

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

210 211 212 213 214
    $ ./piglit run

or

    $ ./piglit run -h
Nicolai Hähnle's avatar
Nicolai Hähnle committed
215

216 217 218
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
219

220
    $ ls tests/*.py
Nicolai Hähnle's avatar
Nicolai Hähnle committed
221

222 223
See also section 4.

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

226
    $ ./piglit summary html summary/sanity results/sanity
Nicolai Hähnle's avatar
Nicolai Hähnle committed
227 228

Hint: You can combine multiple test results into a single summary.
229
During development, you can use this to watch for regressions:
Nicolai Hähnle's avatar
Nicolai Hähnle committed
230

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

233 234
You can combine as many testruns as you want this way (in theory;
the HTML layout becomes awkward when the number of testruns increases)
Nicolai Hähnle's avatar
Nicolai Hähnle committed
235 236 237

Have a look at the results with a browser:

238
    $ xdg-open summary/sanity/index.html
Nicolai Hähnle's avatar
Nicolai Hähnle committed
239 240 241

The summary shows the 'status' of a test:

242 243 244 245 246 247 248
  - **pass:**   This test has completed successfully.
  - **warn:**   The test completed successfully, but something unexpected happened.
    Look at the details for more information.
  - **fail:**   The test failed.
  - **crash:**  The test binary exited with a non-zero exit code.
  - **skip:**   The test was skipped.
  - **timeout:**  The test ran longer than its allotted time and was forcibly killed.
249

250 251 252

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
253

254 255

### 3.1 Environment Variables
256 257 258 259

There are a number of environment variables that control the way piglit
behaves.

260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288
  - `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 ESX_compatability extensions
    for OpenGL

  - `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.

  - `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.
289

290 291 292 293 294 295 296
  - `PIGLIT_VKRUNNER_BINARY`

    Can be used to override the path to the vkrunner executable for
    running Vulkan shader tests. Alternatively the config option
    vkrunner:bin can be used instead. If neither are set then vkrunner
    will be searched for in the search path.

297 298

### 3.2 Note
299

300 301 302 303 304 305
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`.
306

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

308
### 3.3 Shell Completions
309 310 311 312 313 314 315 316

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.


317 318 319 320 321 322
4. Available test sets
----------------------

Test sets are specified as Python scripts in the tests directory.
The following test sets are currently available:

323

324
### 4.1 OpenGL Tests
325

326 327 328 329
  - **sanity.py** This suite contains minimal OpenGL sanity tests. These tests
    must pass, otherwise the other tests will not generate reliable results.
  - **all.py** This suite contains all OpenGL tests.
  - **quick.py** Run all tests, but cut down significantly on their runtime
Nicolai Hähnle's avatar
Nicolai Hähnle committed
330
    (and thus on the number of problems they can find).
331 332 333 334 335 336 337 338 339 340
  - **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.
  - **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
  - **glslparser.py** A subset of all.py which runs only glslparser tests
  - **shader.py** A subset of all.py which runs only shader tests
  - **no_error.py** A modified version of the test list run as khr_no_error
    variants
341

342

343
### 4.2 OpenCL Tests
344

345 346 347
  - **cl.py** This suite contains all OpenCL tests.
  - **quick_cl.py** This runs all of the tests from cl.py as well as tests from
    opencv and oclconform.
348 349


350 351 352 353 354 355 356
### 4.3 Vulkan tests

  - **vulkan.py** This suite contains all Vulkan tests. Note that
    currently all of the Vulkan tests require VkRunner. If it is not
    installed then all of the tests will be skipped.

### 4.4 External Integration
357

358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377
  - **xts.py** Support for running the X Test Suite using piglit.
  - **igt.py** Support for running Intel-gpu-tools test suite using piglit.
  - **deqp_egl.py** Support for running dEQP's EGL profile with piglit.
  - **deqp_gles2.py** Support for running dEQP's gles2 profile with piglit.
  - **deqp_gles3.py** Support for running dEQP's gles3 profile with piglit.
  - **deqp_gles31.py** Support for running dEQP's gles3.1 profile with piglit.
  - **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.
378

379

380
5. How to write tests
Nicolai Hähnle's avatar
Nicolai Hähnle committed
381 382 383 384 385 386
---------------------

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.
387
C is the preferred language for compiled tests, piglit also supports its own
388
simple formats for test shaders and glsl parser input.
Nicolai Hähnle's avatar
Nicolai Hähnle committed
389

390 391 392
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
393

394 395
  - `PiglitBaseTest`
    A shared base class for all native piglit tests.
396

397 398
    It starts each test as a subprocess, captures stdout and stderr, and waits
    for the test to return.
399

400 401
    It provides test timeouts by setting the instances 'timeout' attribute to an
    integer > 0 which is the number of seconds the test should run.
402

403 404 405
    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.
406

407 408
    This is a base class and should not be used directly, but provides an
    explanation of the behavior of the following classes.
409

410 411
  - `PiglitGLTest`
    A test class for native piglit OpenGL tests.
412

413 414 415
    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.
416

417 418
  - `PiglitCLTest`
    A test class for native piglit OpenCL tests.
419

420
    It currently provides no special features.
421

422 423
  - `GLSLParserTest`
    A class for testing a glsl parser.
424

425 426
    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
427

428 429
  - `ShaderTest`
    A class for testing using OpenGL shaders.
Nicolai Hähnle's avatar
Nicolai Hähnle committed
430

431 432
    It is generally unnecessary to call this class directly as it uses a helper
    function to search directories for tests.
433 434 435 436 437 438 439 440 441 442 443 444 445 446


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.


447
### 6.1 dEQP
448 449 450 451 452 453 454 455

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:
456 457

    cmake . -DDEQP_TARGET=gbm -GNinja
458 459 460 461 462 463 464 465

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
466 467
either be located in the root of the piglit repo, or in `$XDG_CONFIG_HOME`
(usually `$HOME/.config`).
468

469 470
    [deqp-gles2]
    bin=<deqp source dir>/modules/gles2/deqp-gles2
471

472 473
    [deqp-gles3]
    bin=<deqp source dir>/modules/gles3/deqp-gles3
474

475 476
    [deqp-gles31]
    bin=<deqp source dir>/modules/gles31/deqp-gles31
477 478

These platforms can be run using deqp_gles*.py as a suite in piglit.
479 480 481
For example:

    ./piglit run deqp_gles31 my_results -c
482 483

It is also possible to mix integrated suites and piglit profiles together:
484 485

    ./piglit run deqp_gles31 quick cl my_results
486 487 488 489 490

dEQP profiles generally contain all of the tests from the previous profile, so
gles31 covers gles3 and gles2.


491
### 6.2 Khronos CTS
492 493 494

Add the following to your piglit.conf file:

495 496
    [cts]
    bin=<cts source dir>/cts/glcts