1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
\ Initial design decisions
-------------------------
Before I started working on Piglit, I asked around for OpenGL testing methods.
There were basically two kinds of tests:
1. Glean, which is fully automatic and intends to test the letter of the
OpenGL specification (at least partially).
2. Manual tests using Mesa samples or third-party software.
The weakness of Glean is that it is not flexible, not pragmatic enough for
driver development. For example, it tests for precision requirements in
blending, where a driver just cannot reasonably improve on what the hardware
delivers. As a driver developer, one wants to consider a test successful
when it reaches the optimal results that the hardware can give, even when
these results may be non-compliant.
Manual tests are not well repeatable. They require a considerable amount of
work on the part of the developer, so most of the time they aren't done at all.
On the other hand, those manual tests have sometimes been created to test for
a particular weakness in implementations, so they may be very suitable to
detect future, similar weaknesses.
Due to these weaknesses, the test coverage of open source OpenGL drivers
is suboptimal at best. My goal for Piglit is to create a useful test system
that helps driver developers in improving driver quality.
With that in mind, my sub-goals are:
1. Combine the strengths of the two kinds of tests (Glean, manual tests)
into a single framework.
2. Provide concise, human readable summaries of the test results, with the
option to increase the detail of the report when desired.
3. Allow easy visualization of regressions.
4. Allow easy detection of performance regressions.
I briefly considered extending Glean, but then decided for creating an
entirely new project. The most important reasons are:
1. I do not want to pollute the very clean philosophy behind Glean.
2. The model behind Glean is that one process runs all the tests.
During driver development, one often gets bugs that cause tests to crash.
This means that one failed test can disrupt the entire test batch.
I want to use a more robust model, where each test runs in its own process.
This model does not easily fit onto Glean.
3. The amount of code duplication and forking overhead is minimal because
a) I can use Glean as a "subroutine", so no code is actually duplicated,
there's just a tiny amount of additional Python glue code.
b) It's unlikely that this project makes significant changes to Glean
that need to be merged upstream.
4. While it remains reasonable to use C++ for the actual OpenGL tests,
it is easier to use a higher level language like Python for the framework
(summary processing etc.)
\ Coding style
-------------
Basic formatting:
* Indent with 8-column tabs
* Limit lines to 78 characters or less
* Function return type and name go on successive lines
* Opening function brace goes on line by itself
* Opening statement braces go on same line as the 'for' or 'else'
The following indent command will generally format your code for piglit's
style:
indent -br -i8 -npcs -ce input.c -o output.c
Though, that doesn't give perfect results. It messes up the
PIGLIT_GL_TEST_CONFIG_BEGIN/END section. And array initializers sometimes
come out funny.
When in doubt see other recently added piglit tests for coding style.
Code conventions:
* Use "const" qualifiers whenever possible on array declarations, pointers
and global variables.
* Use "static const" for initialized arrays whenever possible.
* Preprocessor macros should be UPPER_CASE
* Enumeration tokens should be UPPER_CASE
* Most other identifiers are lower_case_with_underscores
* Use int, float, bool except when GL types (GLint, GLfloat) are really needed
* Don't put declarations after code. For example:
if (x < 3)
x = 0;
int y = x * x;
This will not compile with MSVC. The 'int y' declaration must be at the
top of the brace-block.
* Don't use named/designated initializers. They don't compile with MSVC.
* Write tests that are easily read, understood and debugged. Long, complicated
functions are frowned upon.
* Don't try to test too much in a single test program. Most piglit programs
are less than 300 lines long.
Utility code:
Piglit has a rich set of utility functions for basic drawing, setting
up shaders, probing pixels, error checking, etc. Try to use them before
rolling your own.
\ Release Philosophy
-------------------
Since Piglit is a test suite, it is "production software" at all times.
Test case might be incorrect, but despite that it is not useful to speak of
"stable" and "unstable" versions of a test suite, especially one that sees
a relatively small rate of change like Piglit.
For this reason, developers of OpenGL drivers and related software, and even
testers are encouraged to follow the git repository on freedesktop.org at all
times. A web interface to this repository can be found here:
http://cgit.freedesktop.org/piglit
Nevertheless, for purposes of marking a specific point in time for packaging
in an environment where non-developers do tests on a wide range of hardware,
it has been pointed out that it would be useful to have official releases.
For this reason, we will occasionally bump the version number in the file
RELEASE and create an appropriate tag in the git repository.
This tag is the official way of marking a release, so the tarballs provided
automatically by the cgit frontend are official release tarballs.
|
