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

Piglit
3
4
======

5
6
7
8
9
10
1. [About](#1-about)
2. [Setup](#2-setup)
3. [How to run tests](#3-how-to-run-tests)
4. [Available test sets](#4-available-test-sets)
5. [How to write tests](#5-how-to-write-tests)
6. [Integration](#6-integration)
Nicolai Hähnle's avatar
Nicolai Hähnle committed
11
12


13
## 1. About
Nicolai Hähnle's avatar
Nicolai Hähnle committed
14

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
perform regression tests.

The original tests have been taken from
- Glean ( http://glean.sf.net/ ) and
- Mesa ( http://www.mesa3d.org/ )


27
## 2. Setup
Nicolai Hähnle's avatar
Nicolai Hähnle committed
28
29
30

First of all, you need to make sure that the following are installed:

Dylan Baker's avatar
Dylan Baker committed
31
  - Python >=3.6
32
  - Python Mako module
33
  - numpy (http://www.numpy.org)
Nicolai Hähnle's avatar
Nicolai Hähnle committed
34
  - cmake (http://www.cmake.org)
35
  - GL, glu and glut libraries and development packages (i.e. headers)
Nicolai Hähnle's avatar
Nicolai Hähnle committed
36
  - X11 libraries and development packages (i.e. headers)
37
  - waffle (http://www.waffle-gl.org)
38
39
40
41
42
43

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/)
44
45
  - jsonstreams. A JSON stream writer for python.
    (https://jsonstreams.readthedocs.io/en/stable/)
46
47
  - VkRunner. A shader script testing tool for Vulkan.
    (https://github.com/igalia/vkrunner)
48

49
For testing the python framework using `py.test unittests/framework`
50
51
52
53
  - 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)
54
55
  - mock. A python module for mocking other python modules. Required only for
    unittests (https://github.com/testing-cabal/mock)
56
57
58
59
  - 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's avatar
Rhys Kidd committed
60
  - pytest-raises. A plugin for pytest that allows decorating tests that expect
61
62
63
    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
64
65
66

Now configure the build system:

67
    $ ccmake .
Nicolai Hähnle's avatar
Nicolai Hähnle committed
68
69
70
71

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
72
 - 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
73
74
Now build everything:

75
    $ make
Nicolai Hähnle's avatar
Nicolai Hähnle committed
76
77


78
### 2.1 Cross Compiling
79

80
81
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
82
83
flags), then you must invoke cmake with options
`-DCMAKE_SYSTEM_PROCESSOR=x86 -DCMAKE_C_FLAGS=-m32 -DCMAKE_CXX_FLAGS=-m32`.
84

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

86
### 2.2 Ubuntu
87
88

Install development packages.
89

90
    $ 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
91

92
Configure and build.
93
94
95

    $ cmake .
    $ make
96
97


98
### 2.3 Mac OS X
99

100
Install CMake.
101
102
103
104
105
106
107
http://cmake.org/cmake/resources/software.html
Download and install 'Mac OSX Universal' platform.

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

Configure and build.
108
109
110

    $ cmake .
    $ make
111
112


113
### 2.4 Cygwin
114
115
116
117
118
119
120
121
122
123
124
125

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

Configure and build.
126
127
128

    $ cmake .
    $ make
129
130


131
### 2.5 Windows
132

Jose Fonseca's avatar
Jose Fonseca committed
133
Install Python 3.
134
135
136
137
138
139
http://www.python.org/download

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

Jose Fonseca's avatar
Jose Fonseca committed
140
141
142
143
144
Download and install Ninja
https://github.com/ninja-build/ninja/releases

Install MinGW-w64
https://mingw-w64.org/
145
146
147

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

Install python mako.
151
152

    pip install mako
Jose Fonseca's avatar
Jose Fonseca committed
153
154

Install NumPy.
155
156

    pip install numpy
157

158

159
#### 2.5.1 GLUT
160

Jose Fonseca's avatar
Jose Fonseca committed
161
162
Download freeglut for Mingw.
http://www.transmissionzero.co.uk/software/freeglut-devel/
163

164
165
    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
166
167


168
#### 2.5.2 Waffle
169

Jose Fonseca's avatar
Jose Fonseca committed
170
Download and build waffle for MinGW.
171
172
173
174
175
http://www.waffle-gl.org/

Open the Command Prompt.
CD to piglit directory.

176
    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
Jose Fonseca's avatar
Jose Fonseca committed
177

178

179
## 3. How to run tests
Nicolai Hähnle's avatar
Nicolai Hähnle committed
180
181
182

Make sure that everything is set up correctly:

183
    $ ./piglit run sanity results/sanity
Nicolai Hähnle's avatar
Nicolai Hähnle committed
184

185
186
You may include '.py' on the profile, or you may exclude it (sanity vs sanity.py),
both are equally valid.
187

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

191
You may provide multiple profiles to be run at the same time:
192

193
    $ ./piglit run quick_cl gpu deqp_gles3 results/gl-cl-combined
194

195
Use
Nicolai Hähnle's avatar
Nicolai Hähnle committed
196

197
198
199
200
201
    $ ./piglit run

or

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

203
204
205
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
206

207
    $ ls tests/*.py
Nicolai Hähnle's avatar
Nicolai Hähnle committed
208

209
210
See also section 4.

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

213
    $ ./piglit summary html summary/sanity results/sanity
Nicolai Hähnle's avatar
Nicolai Hähnle committed
214
215

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

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

220
221
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
222
223
224

Have a look at the results with a browser:

225
    $ xdg-open summary/sanity/index.html
Nicolai Hähnle's avatar
Nicolai Hähnle committed
226
227
228

The summary shows the 'status' of a test:

229
230
231
232
233
234
235
  - **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.
236

Dylan Baker's avatar
Dylan Baker committed
237
238
239

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
240

241
242

### 3.1 Environment Variables
243
244
245
246

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

247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
  - `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.
276

277
278
279
280
281
282
283
  - `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.

284
285

### 3.2 Note
286

287
288
289
290
291
292
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`.
293

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

295
### 3.3 Shell Completions
Dylan Baker's avatar
Dylan Baker committed
296
297
298
299
300
301
302
303

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.


304
## 4. Available test sets
305
306
307
308

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

309

310
### 4.1 OpenGL Tests
311

312
313
314
315
  - **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
316
    (and thus on the number of problems they can find).
317
318
319
320
321
322
323
324
325
326
  - **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
327

328

329
### 4.2 OpenCL Tests
330

331
332
333
  - **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.
334
335


336
337
338
339
340
341
### 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.

Andres Gomez's avatar
Andres Gomez committed
342
343
344
345
346
347
348
349
350
351

### 4.4 Replay tests

  - **replay.py** This profile allows running
    [replayer.py](replayer/replayer.py) tests from a traces
    description file. Check its [README](replayer/README.md) for
    further information about the format of the description files and
    running dependencies.

### 4.5 External Integration
352

353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
  - **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.
373

374

375
## 5. How to write tests
Nicolai Hähnle's avatar
Nicolai Hähnle committed
376
377
378
379
380

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

384
385
386
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
387

388
389
  - `PiglitBaseTest`
    A shared base class for all native piglit tests.
390

391
392
    It starts each test as a subprocess, captures stdout and stderr, and waits
    for the test to return.
393

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

397
398
399
    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.
400

401
402
    This is a base class and should not be used directly, but provides an
    explanation of the behavior of the following classes.
403

404
405
  - `PiglitGLTest`
    A test class for native piglit OpenGL tests.
406

407
408
409
    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.
410

411
412
  - `PiglitCLTest`
    A test class for native piglit OpenCL tests.
413

414
    It currently provides no special features.
415

416
417
  - `GLSLParserTest`
    A class for testing a glsl parser.
418

419
420
    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
421

422
423
  - `ShaderTest`
    A class for testing using OpenGL shaders.
Nicolai Hähnle's avatar
Nicolai Hähnle committed
424

425
426
    It is generally unnecessary to call this class directly as it uses a helper
    function to search directories for tests.
427
428


429
## 6. Integration
430
431
432
433
434
435
436
437
438
439

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.


440
### 6.1 dEQP
441
442
443
444
445
446
447
448

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:
449
450

    cmake . -DDEQP_TARGET=gbm -GNinja
451
452
453
454
455
456
457
458

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

462
463
    [deqp-gles2]
    bin=<deqp source dir>/modules/gles2/deqp-gles2
464

465
466
    [deqp-gles3]
    bin=<deqp source dir>/modules/gles3/deqp-gles3
467

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

These platforms can be run using deqp_gles*.py as a suite in piglit.
472
473
474
For example:

    ./piglit run deqp_gles31 my_results -c
475
476

It is also possible to mix integrated suites and piglit profiles together:
477
478

    ./piglit run deqp_gles31 quick cl my_results
479
480
481
482
483

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


484
### 6.2 Khronos CTS
485
486
487

Add the following to your piglit.conf file:

488
489
    [cts]
    bin=<cts source dir>/cts/glcts