1<?xml version="1.0"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
4[
5  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
6  <!ENTITY version SYSTEM "version.xml">
7]>
8
9<chapter id="test-programs">
10  <title>Test Programs</title>
11
12  <refentry id="igt-test-programs-common-features">
13    <refnamediv>
14      <refname>Common Features</refname>
15      <refpurpose>Features available in all test programs</refpurpose>
16    </refnamediv>
17    <refsect1>
18      <title>Command Line Options</title>
19      <para>
20        All tests support the following command line options:
21
22        <variablelist>
23          <varlistentry>
24            <term><option>--list-subtests</option></term>
25            <listitem><para>
26                list the available subtests and exit
27            </para></listitem>
28          </varlistentry>
29
30          <varlistentry>
31            <term><option>--run-subtest <replaceable>subtest</replaceable></option></term>
32            <listitem><para>
33                run the specified subtest
34            </para></listitem>
35          </varlistentry>
36
37          <varlistentry>
38            <term><option>--debug[=log-domain]</option></term>
39            <listitem><para>
40                print extra debugging information when running tests and
41                optionally only show the messages from the specified log domain
42                (use "application" to specify the default application domain)
43            </para></listitem>
44          </varlistentry>
45
46          <varlistentry>
47            <term><option>--help-description</option></term>
48            <listitem><para>
49                print a short description of the test and exit
50            </para></listitem>
51          </varlistentry>
52
53          <varlistentry>
54            <term><option>--help</option></term>
55            <listitem><para>
56                print help and exit
57            </para></listitem>
58          </varlistentry>
59        </variablelist>
60      </para>
61    </refsect1>
62
63    <refsect1>
64      <title>Exit Status</title>
65      <para>
66      The following exit status codes are defined:
67
68      <informaltable pgwide="1" frame="none">
69        <tgroup cols="3" align="left">
70          <thead>
71            <row><entry>Name</entry><entry>Value</entry><entry>Description</entry></row>
72          </thead>
73          <tbody>
74            <row>
75              <entry>#IGT_EXIT_SUCCESS</entry>
76              <entry>0</entry>
77              <entry>The test was successful</entry>
78            </row>
79            <row>
80              <entry>#IGT_EXIT_SKIP</entry>
81              <entry>77</entry>
82              <entry>The test was skipped</entry>
83            </row>
84            <row>
85              <entry>#IGT_EXIT_INVALID</entry>
86              <entry>79</entry>
87              <entry>An invalid option or subtest was specified</entry>
88            </row>
89          </tbody>
90        </tgroup>
91      </informaltable>
92
93      Any other exit status indicates a test failure.
94    </para>
95    </refsect1>
96  </refentry>
97
98  <refentry id="igt-amdgpu-tests">
99    <refnamediv>
100      <refname>AMDGPU Tests</refname>
101      <refpurpose>Tests for amdgpu driver behaviour</refpurpose>
102    </refnamediv>
103    <xi:include href="igt_test_programs_amdgpu_programs.xml"/>
104    <xi:include href="igt_test_programs_amdgpu_description.xml"/>
105  </refentry>
106
107  <refentry id="igt-chamelium-tests">
108    <refnamediv>
109      <refname>Chamelium Tests</refname>
110      <refpurpose>Tests using the Chamelium platform</refpurpose>
111    </refnamediv>
112    <xi:include href="igt_test_programs_chamelium_programs.xml"/>
113    <xi:include href="igt_test_programs_chamelium_description.xml"/>
114  </refentry>
115
116  <refentry id="igt-core-tests">
117    <refnamediv>
118      <refname>Core Tests</refname>
119      <refpurpose>Tests for core drm ioctls and behaviour</refpurpose>
120    </refnamediv>
121    <xi:include href="igt_test_programs_core_programs.xml"/>
122    <xi:include href="igt_test_programs_core_description.xml"/>
123  </refentry>
124
125  <refentry id="igt-debugfs-tests">
126    <refnamediv>
127      <refname>Debugfs Tests</refname>
128      <refpurpose>Tests for debugfs behaviour</refpurpose>
129    </refnamediv>
130    <xi:include href="igt_test_programs_debugfs_programs.xml"/>
131    <xi:include href="igt_test_programs_debugfs_description.xml"/>
132  </refentry>
133
134  <refentry id="igt-drm-tests">
135    <refnamediv>
136      <refname>DRM Tests</refname>
137      <refpurpose>Tests for libdrm behaviour</refpurpose>
138    </refnamediv>
139    <xi:include href="igt_test_programs_drm_programs.xml"/>
140    <xi:include href="igt_test_programs_drm_description.xml"/>
141  </refentry>
142
143  <refentry id="igt-gem-tests">
144    <refnamediv>
145      <refname>GEM Tests</refname>
146      <refpurpose>Tests for the graphics execution manager</refpurpose>
147    </refnamediv>
148    <xi:include href="igt_test_programs_gem_programs.xml"/>
149    <xi:include href="igt_test_programs_gem_description.xml"/>
150  </refentry>
151
152  <refentry id="igt-gen3-tests">
153    <refnamediv>
154      <refname>Gen 3 Tests</refname>
155      <refpurpose>Tests specific to gen 3</refpurpose>
156    </refnamediv>
157    <xi:include href="igt_test_programs_gen3_programs.xml"/>
158    <xi:include href="igt_test_programs_gen3_description.xml"/>
159  </refentry>
160
161  <refentry id="igt-gen7-tests">
162    <refnamediv>
163      <refname>Gen 7 Tests</refname>
164      <refpurpose>Tests specific to gen 7</refpurpose>
165    </refnamediv>
166    <xi:include href="igt_test_programs_gen7_programs.xml"/>
167    <xi:include href="igt_test_programs_gen7_description.xml"/>
168  </refentry>
169
170  <refentry id="igt-gvt-tests">
171    <refnamediv>
172      <refname>GVT Tests</refname>
173      <refpurpose>Tests for graphics virtualization technology</refpurpose>
174    </refnamediv>
175    <xi:include href="igt_test_programs_gvt_programs.xml"/>
176    <xi:include href="igt_test_programs_gvt_description.xml"/>
177  </refentry>
178
179  <refentry id="igt-i915-tests">
180    <refnamediv>
181      <refname>i915 Tests</refname>
182      <refpurpose>Tests for overall i915 driver behaviour</refpurpose>
183    </refnamediv>
184    <xi:include href="igt_test_programs_i915_programs.xml"/>
185    <xi:include href="igt_test_programs_i915_description.xml"/>
186  </refentry>
187
188  <refentry id="igt-kms-tests">
189    <refnamediv>
190      <refname>KMS Tests</refname>
191      <refpurpose>Tests for kernel mode setting</refpurpose>
192    </refnamediv>
193    <xi:include href="igt_test_programs_kms_programs.xml"/>
194    <xi:include href="igt_test_programs_kms_description.xml"/>
195  </refentry>
196
197  <refentry id="igt-meta-tests">
198    <refnamediv>
199      <refname>Meta Tests</refname>
200      <refpurpose>Tests for the CI system itself</refpurpose>
201    </refnamediv>
202    <xi:include href="igt_test_programs_meta_programs.xml"/>
203    <xi:include href="igt_test_programs_meta_description.xml"/>
204  </refentry>
205
206  <refentry id="igt-perf-tests">
207    <refnamediv>
208      <refname>Perf Tests</refname>
209      <refpurpose>Tests for the performance metrics</refpurpose>
210    </refnamediv>
211    <xi:include href="igt_test_programs_perf_programs.xml"/>
212    <xi:include href="igt_test_programs_perf_description.xml"/>
213  </refentry>
214
215  <refentry id="igt-pm-tests">
216    <refnamediv>
217      <refname>PM Tests</refname>
218      <refpurpose>Tests for power management features</refpurpose>
219    </refnamediv>
220    <xi:include href="igt_test_programs_pm_programs.xml"/>
221    <xi:include href="igt_test_programs_pm_description.xml"/>
222  </refentry>
223
224  <refentry id="igt-prime-tests">
225    <refnamediv>
226      <refname>Prime Tests</refname>
227      <refpurpose>Tests for buffer sharing</refpurpose>
228    </refnamediv>
229    <xi:include href="igt_test_programs_prime_programs.xml"/>
230    <xi:include href="igt_test_programs_prime_description.xml"/>
231  </refentry>
232
233  <refentry id="igt-sw-sync-tests">
234    <refnamediv>
235      <refname>SW Sync Tests</refname>
236      <refpurpose>Tests for software sync (fencing)</refpurpose>
237    </refnamediv>
238    <xi:include href="igt_test_programs_sw_sync_programs.xml"/>
239    <xi:include href="igt_test_programs_sw_sync_description.xml"/>
240  </refentry>
241
242  <refentry id="igt-testdisplay-tests">
243    <refnamediv>
244      <refname>Display Tests</refname>
245      <refpurpose>Tests for display validation</refpurpose>
246    </refnamediv>
247    <xi:include href="igt_test_programs_testdisplay_programs.xml"/>
248    <xi:include href="igt_test_programs_testdisplay_description.xml"/>
249  </refentry>
250
251  <refentry id="igt-tools-tests">
252    <refnamediv>
253      <refname>Tools Tests</refname>
254      <refpurpose>Tests for IGT tools behaviour</refpurpose>
255    </refnamediv>
256    <xi:include href="igt_test_programs_tools_programs.xml"/>
257    <xi:include href="igt_test_programs_tools_description.xml"/>
258  </refentry>
259
260  <refentry id="igt-vgem-tests">
261    <refnamediv>
262      <refname>vGEM Tests</refname>
263      <refpurpose>Tests for the vitual graphics execution manager</refpurpose>
264    </refnamediv>
265    <xi:include href="igt_test_programs_vgem_programs.xml"/>
266    <xi:include href="igt_test_programs_vgem_description.xml"/>
267  </refentry>
268
269  <glossary>
270    <title>Glossary</title>
271
272    <para>The following terms are commonly used in test names to describe
273      various features of the test and can be used to filter and select
274      particular tests.</para>
275
276    <glossentry id="invalid">
277      <glossterm>invalid</glossterm>
278      <glossdef>
279        <para>Negative tests to validate kernel interface input validation.</para>
280      </glossdef>
281    </glossentry>
282
283    <glossentry id="hang">
284      <glossterm>hang</glossterm>
285      <glossdef>
286        <para>Tests that provoke gpu hangs.</para>
287      </glossdef>
288    </glossentry>
289
290    <glossentry id="swap">
291      <glossterm>swap</glossterm>
292      <glossdef>
293        <para>Tests that force their full working sets through swap.</para>
294      </glossdef>
295    </glossentry>
296
297    <glossentry id="thrash">
298      <glossterm>thrash</glossterm>
299      <glossdef>
300        <para>Tests that tend to have really slow forward progress due to gtt/memory/.. thrashing.</para>
301      </glossdef>
302    </glossentry>
303
304    <glossentry id="crc">
305      <glossterm>crc</glossterm>
306      <glossdef>
307        <para>Tests that use the display CRC infrastructure to check the results.</para>
308      </glossdef>
309    </glossentry>
310
311    <glossentry id="tiled">
312      <glossterm>tiled</glossterm>
313      <glossdef>
314        <para>Tests that exercise behaviour on tiled buffers.</para>
315      </glossdef>
316    </glossentry>
317
318    <glossentry id="tiling">
319      <glossterm>tiling</glossterm>
320      <glossdef>
321        <para>Tests that exercise behaviour on tiled buffers.</para>
322      </glossdef>
323    </glossentry>
324
325    <glossentry id="rte">
326      <glossterm>rte</glossterm>
327      <glossdef>
328        <para>Runtime environment checks.</para>
329      </glossdef>
330    </glossentry>
331
332    <glossentry id="ctx">
333      <glossterm>ctx</glossterm>
334      <glossdef>
335        <para>Tests that exercise the hardware context support.</para>
336      </glossdef>
337    </glossentry>
338
339    <glossentry id="render">
340      <glossterm>render</glossterm>
341      <glossdef>
342        <para>Tests which apply to the render ring.</para>
343      </glossdef>
344    </glossentry>
345
346    <glossentry id="blt">
347      <glossterm>blt</glossterm>
348      <glossdef>
349        <para>Tests which apply to the blt ring.</para>
350      </glossdef>
351    </glossentry>
352
353    <glossentry id="bsd">
354      <glossterm>bsd</glossterm>
355      <glossdef>
356        <para>Tests which apply to the bsd ring.</para>
357      </glossdef>
358    </glossentry>
359
360    <glossentry id="vebox">
361      <glossterm>vebox</glossterm>
362      <glossdef>
363        <para>Tests which apply to the vebox ring.</para>
364      </glossdef>
365    </glossentry>
366
367    <glossentry id="exec">
368      <glossterm>exec</glossterm>
369      <glossdef>
370        <para>Tests that exercise the execbuf code in various ways.</para>
371      </glossdef>
372    </glossentry>
373
374    <glossentry id="rpm">
375      <glossterm>rpm</glossterm>
376      <glossdef>
377        <para>Runtime power management tests.</para>
378      </glossdef>
379    </glossentry>
380  </glossary>
381</chapter>
382