1V4L2-COMPLIANCE(1)                 1.25.0""                 V4L2-COMPLIANCE(1)
2
3
4

NAME

6       v4l2-compliance - An application to test video4linux drivers
7

SYNOPSIS

9       v4l2-compliance [-h] [-d <dev>] [many other options]
10

DESCRIPTION

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
18       The support for memory-to-memory devices is limited at the moment.
19
20       If  you  have  questions  about  v4l2-compliance then mail those to the
21       linux-media@vger.kernel.org mailinglist.
22
23       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
28       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
32       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
39       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
46       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
49       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
55       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
61       If your driver passes all tests, then your can be confident  that  your
62       driver is in very good shape!
63

OPTIONS

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
72       -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
79       -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
86       -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
93       -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
100       -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
113       -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
119       -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
127       -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
135
136       --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
145       -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
152              The configuration of the driver at the time v4l2-compliance  was
153              called will be used for the streaming tests.
154
155       -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
166              The  configuration of the driver at the time v4l2-compliance was
167              called will be used for the streaming tests.
168
169       -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
181              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
185              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
189              The  configuration of the driver at the time v4l2-compliance was
190              called will be used for the streaming tests.
191
192       -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
198       -E, --exit-on-fail
199              Exit  this  application when the first failure occurs instead of
200              continuing with a possible inconsistent state.
201
202       -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
207       -n, --no-warnings
208              Turn off warning messages. They are still counted  in  the  sum‐
209              mary, but you won't see them.
210
211       -P, --no-progress
212              Turn  off  progress messages. Useful when redirecting the output
213              to a file.
214
215       -T, --trace
216              Trace all called ioctls.
217
218       -v, --verbose
219              Turn on verbose reporting.
220
221       --version
222              Show version information.
223
224       -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
231       -W, --exit-on-warn
232              Exit this application when the first warning occurs  instead  of
233              continuing.
234
235       -h, --help
236              Prints the help message.
237

EXIT STATUS

239       On success, it returns 0. Otherwise, it will return the error code.
240

BUGS

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.
246
247
248
249v4l-utils                         March 2015                V4L2-COMPLIANCE(1)
Impressum