1V4L2-COMPLIANCE(1) 1.25.0"" V4L2-COMPLIANCE(1)
2
6 v4l2-compliance - An application to test video4linux drivers
7
9 v4l2-compliance [-h] [-d <dev>] [many other options]
10
12 The v4l2-compliance tool is used to test video4linux devices, either
13 video, vbi, radio or swradio, both input and output. It attempts to
14 test almost all aspects of a V4L2 device and it covers almost all V4L2
15 ioctls. It has very good support for video capture and output, VBI cap‐
16 ture and output and (software) radio tuning and transmitting.
17 The support for memory-to-memory devices is limited at the moment.
19 If you have questions about v4l2-compliance then mail those to the
21 linux-media@vger.kernel.org mailinglist.
22 When testing a driver always compile the utility from the latest source
24 code from the git repository (http://git.linuxtv.org/cgit.cgi/v4l-
25 utils.git/). The version supplied by linux distributions is almost cer‐
26 tainly too old.
27 In addition, if a test fails then it will output the source and line
29 where the failure occurred, so you often need access to the source code
30 to see what that test is all about.
31 Note that v4l2-compliance not only tests for compliance against the
33 V4L2 API, but also whether the driver is using all the correct frame‐
34 works. These frameworks often automatically provide ioctls that are
35 strictly speaking optional, but that come for free if you use those
36 frameworks. By requiring their presence the v4l2-compliance utility
37 will enforce their use.
38 If you want to submit a new V4L2 driver, then that driver must pass the
40 v4l2-compliance tests without fails. The best method of using this tool
41 to test your driver is to first test without any streaming options and
42 fix any failures from the first reported failure to the last. Sometimes
43 earlier failures can generate later failures, so just start fixing them
44 in order and test again after each fix.
45 Next test your driver with the -s option to do the basic streaming
47 tests. This requires that there is a valid input or output.
48 Whenever you run v4l2-compliance it will save the current driver state
50 and restore it after all tests are done (including when you press Ctrl-
51 C). All the streaming tests are performed using the saved configura‐
52 tion. This makes it possible to prepare for the streaming tests by con‐
53 figuring the device before calling v4l2-compliance.
54 Finally you should test your driver using the -f and -c options to ver‐
56 ify that all video pixel formats are correctly supported. You need to
57 perform all three streaming tests for all inputs and outputs. You can
58 use the -a option to automate that if that is possible for your hard‐
59 ware.
60 If your driver passes all tests, then your can be confident that your
62 driver is in very good shape!
63
65 -d, --device <dev>
66 Use device <dev> as the video device. If <dev> is a number, then
67 /dev/video<dev> is used. Otherwise if -z was specified earlier,
68 then <dev> is the entity name or interface ID (if prefixed with
69 0x) as found in the topology of the media device with the bus
70 info string as specified by the -z option.
71 -V, --vbi-device <dev>
73 Use device <dev> as the vbi device. If <dev> is a number, then
74 /dev/vbi<dev> is used. Otherwise if -z was specified earlier,
75 then <dev> is the entity name or interface ID (if prefixed with
76 0x) as found in the topology of the media device with the bus
77 info string as specified by the -z option.
78 -r, --radio-device <dev>
80 Use device <dev> as the radio device. If <dev> is a number, then
81 /dev/radio<dev> is used. Otherwise if -z was specified earlier,
82 then <dev> is the entity name or interface ID (if prefixed with
83 0x) as found in the topology of the media device with the bus
84 info string as specified by the -z option.
85 -S, --sdr-device <dev>
87 Use device <dev> as the SDR device. If <dev> is a number, then
88 /dev/swradio<dev> is used. Otherwise if -z was specified ear‐
89 lier, then <dev> is the entity name or interface ID (if prefixed
90 with 0x) as found in the topology of the media device with the
91 bus info string as specified by the -z option.
92 -t, --touch-device <dev>
94 Use device <dev> as the touch device. If <dev> is a number, then
95 /dev/v4l-touch<dev> is used. Otherwise if -z was specified ear‐
96 lier, then <dev> is the entity name or interface ID (if prefixed
97 with 0x) as found in the topology of the media device with the
98 bus info string as specified by the -z option.
99 -u, --subdev-device <dev>
101 Use device <dev> as the v4l-subdevX device. If <dev> is a num‐
102 ber, then /dev/v4l-subdev<dev> is used. Otherwise if -z was
103 specified earlier, then <dev> is the entity name -e,
104 --exp-buf-device <dev> Use device <dev> as the video device used
105 to export DMABUFfers for doing DMABUF streaming tests. If <dev>
106 is a number, then /dev/video<dev> is used. Otherwise if -z was
107 specified earlier, then <dev> is the entity name or interface ID
108 (if prefixed with 0x) as found in the topology of the media de‐
109 vice with the bus info string as specified by the -z option. If
110 this option is not specified, then the DMABUF streaming tests
111 will be skipped.
112 -z, --media-bus-info <bus-info>
114 Find the media device with the given bus info string. If set,
115 then the options above can use the entity name or interface ID
116 to refer to the device nodes. Example: v4l2-compliance -z plat‐
117 form:vivid-000 -d vivid-000-vid-cap
118 -m, --media-device <dev>
120 Use device <dev> as the media controller device. Besides this
121 device it also tests all interfaces it finds. If <dev> starts
122 with a digit, then /dev/media<dev> is used. If <dev> doesn't
123 exist, then attempt to find a media device with a bus info
124 string equal to <dev>. Example: v4l2-compliance -m plat‐
125 form:vivid-000
126 -M, --media-device-only <dev>
128 Use device <dev> as the media controller device. Only test this
129 device, don't walk over all the interfaces. If <dev> starts
130 with a digit, then /dev/media<dev> is used. If <dev> doesn't
131 exist, then attempt to find a media device with a bus info
132 string equal to <dev>. Example: v4l2-compliance -M plat‐
133 form:vivid-000
134 --stream-from [<pixelformat>=]<file>, --stream-from-hdr [<pixelfor‐
137 mat>=]<file>
138 Use the contents of the file to fill in output buffers. If the
139 fourcc of the pixelformat is given, then use the file for output
140 buffers using that pixelformat only. The --stream-from-hdr
141 variant uses the format written by v4l2-ctl --stream-to-hdr
142 where the payload sizes for each buffer are stored in a header.
143 Useful for compressed formats.
144 -s, --streaming <count>
146 Enable the streaming tests. Set <count> to the number of frames
147 to stream (default 60). This requires that before v4l2-compli‐
148 ance is called the device has been configured with a valid input
149 (or output) and frequency (when the device has a tuner). For
150 DMABUF testing --expbuf-device needs to be set as well.
151 The configuration of the driver at the time v4l2-compliance was
153 called will be used for the streaming tests.
154 -f, --stream-all-formats [<count>]
156 Test whether all available formats can be streamed. This at‐
157 tempts to stream using MMAP mode or read/write (if V4L2_MEM‐
158 ORY_MMAP is not available) for one second for all formats, at
159 all sizes, at all intervals and with all field values. In addi‐
160 tion, if the driver supports scaling, cropping or composing it
161 will test that as well in various combinations. If the driver
162 supports a lot of combinations then this test can take a long
163 time. If <count> is given, then stream for that many frames in‐
164 stead of for one second.
165 The configuration of the driver at the time v4l2-compliance was
167 called will be used for the streaming tests.
168 -c, --stream-all-color color=red|green|blue,skip=<skip>,perc=<perc>
170 For all supported, non-compressed formats stream <skip + 1>
171 frames. For the last frame go over all pixels and calculate
172 which of the R, G and B color components of a pixel has the
173 highest value and count that as a red, green or blue pixel. The
174 test succeeds if at least perc percent of the frame has the
175 given color. This requires that a valid and predominantly red,
176 green or blue video signal is present on the input(s). If skip
177 is not specified, then just capture the first frame. A non-zero
178 skip value is useful if it takes a few frames for the device to
179 calibrate. If perc is not specified, then this defaults to 90%.
180 Most signal generators are able to generate pure red, blue or
182 green video. For cameras you can print a completely red, green
183 or blue picture and hold it before the camera.
184 The goal of this test is to determine if all pixel formats will
186 interpret the red, green and blue colors correctly and that no
187 color components are swapped.
188 The configuration of the driver at the time v4l2-compliance was
190 called will be used for the streaming tests.
191 -a, --stream-all-io
193 Do the -s, -c and -f streaming tests for all inputs or outputs
194 instead of just the current input or output. This requires that
195 a valid video signal is present on all inputs or that all out‐
196 puts are hooked up.
197 -E, --exit-on-fail
199 Exit this application when the first failure occurs instead of
200 continuing with a possible inconsistent state.
201 -C, --color <when>
203 Highlight OK/warn/fail/FAIL strings with colors. OK is marked
204 green, warn is marked bold, and fail/FAIL are marked bright red
205 if enabled. <when> can be always, never, or auto (the default).
206 -n, --no-warnings
208 Turn off warning messages. They are still counted in the sum‐
209 mary, but you won't see them.
210 -P, --no-progress
212 Turn off progress messages. Useful when redirecting the output
213 to a file.
214 -T, --trace
216 Trace all called ioctls.
217 -v, --verbose
219 Turn on verbose reporting.
220 --version
222 Show version information.
223 -w, --wrapper
225 Use the libv4l2 wrapper library for all V4L2 device accesses.
226 Note that doing this will cause some tests to fail because the
227 libv4l2 library isn't fully V4L2 compliant. By default v4l2-com‐
228 pliance will bypass libv4l2 and access the V4L2 devices di‐
229 rectly.
230 -W, --exit-on-warn
232 Exit this application when the first warning occurs instead of
233 continuing.
234 -h, --help
236 Prints the help message.
237
239 On success, it returns 0. Otherwise, it will return the error code.
240
242 This is a work in progress, and every so often it turns out that some
243 tests done by v4l2-compliance are too strict or plain wrong. If you
244 suspect that might be the case, then report such bugs to the linux-me‐
245 dia@vger.kernel.org mailinglist.
246v4l-utils March 2015 V4L2-COMPLIANCE(1)