1V4L2-COMPLIANCE(1) User Commands V4L2-COMPLIANCE(1)
2
6 v4l2-compliance - An application to test video4linux drivers
7
9 v4l2-compliance [-h] [-d <dev>] [-r <dev>] [-V <dev>] [-S <dev>] [-e
10 <dev>] [-s <count>] [-f] [-a] [-c
11 color=<color>,skip=<skip>,perc=<perc>] [-n] [-T] [-v] [-w]
12
14 The v4l2-compliance tool is used to test video4linux devices, either
15 video, vbi, radio or swradio, both input and output. It attempts to
16 test almost all aspects of a V4L2 device and it covers almost all V4L2
17 ioctls. It has very good support for video capture and output, VBI cap‐
18 ture and output and (software) radio tuning and transmitting.
19 The support for memory-to-memory devices is limited at the moment.
21 If you have questions about v4l2-compliance then mail those to the
23 linux-media@vger.kernel.org mailinglist.
24 When testing a driver always compile the utility from the latest source
26 code from the git repository (http://git.linuxtv.org/cgit.cgi/v4l-
27 utils.git/). The version supplied by linux distributions is almost cer‐
28 tainly too old.
29 In addition, if a test fails then it will output the source and line
31 where the failure occurred, so you often need access to the source code
32 to see what that test is all about.
33 Note that v4l2-compliance not only tests for compliance against the
35 V4L2 API, but also whether the driver is using all the correct frame‐
36 works. These frameworks often automatically provide ioctls that are
37 strictly speaking optional, but that come for free if you use those
38 frameworks. By requiring their presence the v4l2-compliance utility
39 will enforce their use.
40 If you want to submit a new V4L2 driver, then that driver must pass the
42 v4l2-compliance tests without fails. The best method of using this tool
43 to test your driver is to first test without any streaming options and
44 fix any failures from the first reported failure to the last. Sometimes
45 earlier failures can generate later failures, so just start fixing them
46 in order and test again after each fix.
47 Next test your driver with the -s option to do the basic streaming
49 tests. This requires that there is a valid input or output.
50 Whenever you run v4l2-compliance it will save the current driver state
52 and restore it after all tests are done (including when you press Ctrl-
53 C). All the streaming tests are performed using the saved configura‐
54 tion. This makes it possible to prepare for the streaming tests by con‐
55 figuring the device before calling v4l2-compliance.
56 Finally you should test your driver using the -f and -c options to ver‐
58 ify that all video pixel formats are correctly supported. You need to
59 perform all three streaming tests for all inputs and outputs. You can
60 use the -a option to automate that if that is possible for your hard‐
61 ware.
62 If your driver passes all tests, then your can be confident that your
64 driver is in very good shape!
65
67 -d, --device <dev>
68 Use device <dev> as the video device. If <dev> is a number, then
69 /dev/video<dev> is used.
70 -V, --vbi-device <dev>
72 Use device <dev> as the vbi device. If <dev> is a number, then
73 /dev/vbi<dev> is used.
74 -r, --radio-device <dev>
76 Use device <dev> as the radio device. If <dev> is a number, then
77 /dev/radio<dev> is used.
78 -S, --sdr-device <dev>
80 Use device <dev> as the SDR device. If <dev> is a number, then
81 /dev/swradio<dev> is used.
82 -t, --touch-device <dev>
84 Use device <dev> as the touch device. If <dev> is a number, then
85 /dev/v4l-touch<dev> is used.
86 -u, --subdev-device <dev>
88 Use device <dev> as the v4l-subdevX device. If <dev> is a num‐
89 ber, then /dev/v4l-subdev<dev> is used.
90 -m, --media-device <dev>
92 Use device <dev> as the media controller device. Besides this
93 device it also tests all interfaces it finds. If <dev> starts
94 with a digit, then /dev/media<dev> is used.
95 -M, --media-device-only <dev>
97 Use device <dev> as the media controller device. Only test this
98 device, don't walk over all the interfaces. If <dev> starts
99 with a digit, then /dev/media<dev> is used.
100 -e, --exp-buf-device <dev>
102 Use device <dev> as the video device used to export DMABUFfers
103 for doing DMABUF streaming tests. If <dev> is a number, then
104 /dev/video<dev> is used. If this option is not specified, then
105 the DMABUF streaming tests will be skipped.
106 -s, --streaming <count>
108 Enable the streaming tests. Set <count> to the number of frames
109 to stream (default 60). This requires that before v4l2-compli‐
110 ance is called the device has been configured with a valid input
111 (or output) and frequency (when the device has a tuner). For
112 DMABUF testing --expbuf-device needs to be set as well.
113 The configuration of the driver at the time v4l2-compliance was
115 called will be used for the streaming tests.
116 -f, --stream-all-formats
118 Test whether all available formats can be streamed. This
119 attempts to stream using MMAP mode or read/write (if V4L2_MEM‐
120 ORY_MMAP is not available) for one second for all formats, at
121 all sizes, at all intervals and with all field values. In addi‐
122 tion, if the driver supports scaling, cropping or composing it
123 will test that as well in various combinations. If the driver
124 supports a lot of combinations then this test can take a long
125 time.
126 The configuration of the driver at the time v4l2-compliance was
128 called will be used for the streaming tests.
129 -c, --stream-all-color color=red|green|blue,skip=<skip>,perc=<perc>
131 For all supported, non-compressed formats stream <skip + 1>
132 frames. For the last frame go over all pixels and calculate
133 which of the R, G and B color components of a pixel has the
134 highest value and count that as a red, green or blue pixel. The
135 test succeeds if at least perc percent of the frame has the
136 given color. This requires that a valid and predominantly red,
137 green or blue video signal is present on the input(s). If skip
138 is not specified, then just capture the first frame. A non-zero
139 skip value is useful if it takes a few frames for the device to
140 calibrate. If perc is not specified, then this defaults to 90%.
141 Most signal generators are able to generate pure red, blue or
143 green video. For cameras you can print a completely red, green
144 or blue picture and hold it before the camera.
145 The goal of this test is to determine if all pixel formats will
147 interpret the red, green and blue colors correctly and that no
148 color components are swapped.
149 The configuration of the driver at the time v4l2-compliance was
151 called will be used for the streaming tests.
152 -a, --stream-all-io
154 Do the -s, -c and -f streaming tests for all inputs or outputs
155 instead of just the current input or output. This requires that
156 a valid video signal is present on all inputs or that all out‐
157 puts are hooked up.
158 -E, --exit-on-fail
160 Exit this application when the first failure occurs instead of
161 continuing with a possible inconsistent state.
162 -n, --no-warnings
164 Turn off warning messages. They are still counted in the sum‐
165 mary, but you won't see them.
166 -T, --trace
168 Trace all called ioctls.
169 -v, --verbose
171 Turn on verbose reporting.
172 -w, --wrapper
174 Use the libv4l2 wrapper library for all V4L2 device accesses.
175 Note that doing this will cause some tests to fail because the
176 libv4l2 library isn't fully V4L2 compliant. By default v4l2-com‐
177 pliance will bypass libv4l2 and access the V4L2 devices
178 directly.
179 -W, --exit-on-warn
181 Exit this application when the first warning occurs instead of
182 continuing.
183 -h, --help
185 Prints the help message.
186
188 On success, it returns 0. Otherwise, it will return the error code.
189
191 This is a work in progress, and every so often it turns out that some
192 tests done by v4l2-compliance are too strict or plain wrong. If you
193 suspect that might be the case, then report such bugs to the linux-
194 media@vger.kernel.org mailinglist.
195v4l-utils 1.16.5 March 2015 V4L2-COMPLIANCE(1)