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>] [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
109 device with the bus info string as specified by the -z option.
110 If 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 [<pix‐
137 elformat>=]<file>
138 Use the contents of the file to fill in output buffers.
139 If the fourcc of the pixelformat is given, then use the
140 file for output buffers using that pixelformat only. The
141 --stream-from-hdr variant uses the format written by
142 v4l2-ctl --stream-to-hdr where the payload sizes for each
143 buffer are stored in a header. Useful for compressed for‐
144 mats.
145 -s, --streaming <count>
147 Enable the streaming tests. Set <count> to the number of
148 frames to stream (default 60). This requires that before
149 v4l2-compliance is called the device has been configured
150 with a valid input (or output) and frequency (when the
151 device has a tuner). For DMABUF testing --expbuf-device
152 needs to be set as well.
153 The configuration of the driver at the time v4l2-compli‐
155 ance was called will be used for the streaming tests.
156 -f, --stream-all-formats [<count>]
158 Test whether all available formats can be streamed. This
159 attempts to stream using MMAP mode or read/write (if
160 V4L2_MEMORY_MMAP is not available) for one second for all
161 formats, at all sizes, at all intervals and with all
162 field values. In addition, if the driver supports scal‐
163 ing, cropping or composing it will test that as well in
164 various combinations. If the driver supports a lot of
165 combinations then this test can take a long time. If
166 <count> is given, then stream for that many frames
167 instead of for one second.
168 The configuration of the driver at the time v4l2-compli‐
170 ance was called will be used for the streaming tests.
171 -c, --stream-all-color
173 color=red|green|blue,skip=<skip>,perc=<perc>
174 For all supported, non-compressed formats stream <skip +
175 1> frames. For the last frame go over all pixels and cal‐
176 culate which of the R, G and B color components of a
177 pixel has the highest value and count that as a red,
178 green or blue pixel. The test succeeds if at least perc
179 percent of the frame has the given color. This requires
180 that a valid and predominantly red, green or blue video
181 signal is present on the input(s). If skip is not speci‐
182 fied, then just capture the first frame. A non-zero skip
183 value is useful if it takes a few frames for the device
184 to calibrate. If perc is not specified, then this
185 defaults to 90%.
186 Most signal generators are able to generate pure red,
188 blue or green video. For cameras you can print a com‐
189 pletely red, green or blue picture and hold it before the
190 camera.
191 The goal of this test is to determine if all pixel for‐
193 mats will interpret the red, green and blue colors cor‐
194 rectly and that no color components are swapped.
195 The configuration of the driver at the time v4l2-compli‐
197 ance was called will be used for the streaming tests.
198 -a, --stream-all-io
200 Do the -s, -c and -f streaming tests for all inputs or
201 outputs instead of just the current input or output. This
202 requires that a valid video signal is present on all
203 inputs or that all outputs are hooked up.
204 -E, --exit-on-fail
206 Exit this application when the first failure occurs
207 instead of continuing with a possible inconsistent state.
208 -C, --color <when>
210 Highlight OK/warn/fail/FAIL strings with colors. OK is
211 marked green, warn is marked bold, and fail/FAIL are
212 marked bright red if enabled. <when> can be always,
213 never, or auto (the default).
214 -n, --no-warnings
216 Turn off warning messages. They are still counted in the
217 summary, but you won't see them.
218 -P, --no-progress
220 Turn off progress messages. Useful when redirecting the
221 output to a file.
222 -T, --trace
224 Trace all called ioctls.
225 -v, --verbose
227 Turn on verbose reporting.
228 -w, --wrapper
230 Use the libv4l2 wrapper library for all V4L2 device
231 accesses. Note that doing this will cause some tests to
232 fail because the libv4l2 library isn't fully V4L2 compli‐
233 ant. By default v4l2-compliance will bypass libv4l2 and
234 access the V4L2 devices directly.
235 -W, --exit-on-warn
237 Exit this application when the first warning occurs
238 instead of continuing.
239 -h, --help
241 Prints the help message.
242
244 On success, it returns 0. Otherwise, it will return the error
245 code.
246
248 This is a work in progress, and every so often it turns out that
249 some tests done by v4l2-compliance are too strict or plain
250 wrong. If you suspect that might be the case, then report such
251 bugs to the linux-media@vger.kernel.org mailinglist.
252v4l-utils 1.18.0 March 2015 V4L2-COMPLIANCE(1)