aboutsummaryrefslogtreecommitdiffstats
path: root/utils/v4l2-compliance/v4l2-compliance.1.in
blob: 94b6e7f65c47e5ede788bf523c8b48503b78feaf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
.TH "V4L2-COMPLIANCE" "1" "March 2015" "v4l-utils @PACKAGE_VERSION@" "User Commands"
.SH NAME
v4l2-compliance - An application to test video4linux drivers
.SH SYNOPSIS
.B v4l2-compliance
[\fI-h\fR] [\fI-d <dev>\fR] [many other options]
.SH DESCRIPTION
The v4l2-compliance tool is used to test video4linux devices, either video, vbi, radio
or swradio, both input and output. It attempts to test almost all aspects of a V4L2 device
and it covers almost all V4L2 ioctls. It has very good support for video capture and output,
VBI capture and output and (software) radio tuning and transmitting.

The support for memory-to-memory devices is limited at the moment.

If you have questions about v4l2-compliance then mail those to the linux-media@vger.kernel.org
mailinglist.

When testing a driver always compile the utility from the latest source code from the
git repository (http://git.linuxtv.org/cgit.cgi/v4l-utils.git/). The version supplied
by linux distributions is almost certainly too old.

In addition, if a test fails then it will output the source and line where the failure
occurred, so you often need access to the source code to see what that test is all about.

Note that v4l2-compliance not only tests for compliance against the V4L2 API, but also
whether the driver is using all the correct frameworks. These frameworks often automatically
provide ioctls that are strictly speaking optional, but that come for free if you use
those frameworks. By requiring their presence the v4l2-compliance utility will enforce
their use.

If you want to submit a new V4L2 driver, then that driver must pass the v4l2-compliance
tests without fails. The best method of using this tool to test your driver is to first
test without any streaming options and fix any failures from the first reported failure
to the last. Sometimes earlier failures can generate later failures, so just start fixing
them in order and test again after each fix.

Next test your driver with the \fB\-s\fR option to do the basic streaming tests. This
requires that there is a valid input or output.

Whenever you run v4l2-compliance it will save the current driver state and restore it
after all tests are done (including when you press Ctrl-C). All the streaming tests are
performed using the saved configuration. This makes it possible to prepare for the streaming
tests by configuring the device before calling v4l2-compliance.

Finally you should test your driver using the \fB\-f\fR and \fB\-c\fR options to
verify that all video pixel formats are correctly supported. You need to perform
all three streaming tests for all inputs and outputs. You can use the \fB\-a\fR option
to automate that if that is possible for your hardware.

If your driver passes all tests, then your can be confident that your driver is in
very good shape!
.SH OPTIONS
.TP
\fB\-d\fR, \fB\-\-device\fR \fI<dev>\fR
Use device \fI<dev>\fR as the video device. If \fI<dev>\fR is a number, then /dev/video\fI<dev>\fR is used.
Otherwise if \fB-z\fR was specified earlier, then \fI<dev>\fR is the entity name
or interface ID (if prefixed with 0x) as found in the topology of the media device
with the bus info string as specified by the \fB-z\fR option.
.TP
\fB\-V\fR, \fB\-\-vbi\-device\fR \fI<dev>\fR
Use device \fI<dev>\fR as the vbi device. If \fI<dev>\fR is a number, then /dev/vbi\fI<dev>\fR is used.
Otherwise if \fB-z\fR was specified earlier, then \fI<dev>\fR is the entity name
or interface ID (if prefixed with 0x) as found in the topology of the media device
with the bus info string as specified by the \fB-z\fR option.
.TP
\fB\-r\fR, \fB\-\-radio\-device\fR \fI<dev>\fR
Use device \fI<dev>\fR as the radio device. If \fI<dev>\fR is a number, then /dev/radio\fI<dev>\fR is used.
Otherwise if \fB-z\fR was specified earlier, then \fI<dev>\fR is the entity name
or interface ID (if prefixed with 0x) as found in the topology of the media device
with the bus info string as specified by the \fB-z\fR option.
.TP
\fB\-S\fR, \fB\-\-sdr\-device\fR \fI<dev>\fR
Use device \fI<dev>\fR as the SDR device. If \fI<dev>\fR is a number, then /dev/swradio\fI<dev>\fR is used.
Otherwise if \fB-z\fR was specified earlier, then \fI<dev>\fR is the entity name
or interface ID (if prefixed with 0x) as found in the topology of the media device
with the bus info string as specified by the \fB-z\fR option.
.TP
\fB\-t\fR, \fB\-\-touch\-device\fR \fI<dev>\fR
Use device \fI<dev>\fR as the touch device. If \fI<dev>\fR is a number, then /dev/v4l-touch\fI<dev>\fR is used.
Otherwise if \fB-z\fR was specified earlier, then \fI<dev>\fR is the entity name
or interface ID (if prefixed with 0x) as found in the topology of the media device
with the bus info string as specified by the \fB-z\fR option.
.TP
\fB\-u\fR, \fB\-\-subdev\-device\fR \fI<dev>\fR
Use device \fI<dev>\fR as the v4l-subdevX device. If \fI<dev>\fR is a number, then /dev/v4l-subdev\fI<dev>\fR is used.
Otherwise if \fB-z\fR was specified earlier, then \fI<dev>\fR is the entity name
\fB\-e\fR, \fB\-\-exp\-buf\-device\fR \fI<dev>\fR
Use device \fI<dev>\fR as the video device used to export DMABUFfers for doing DMABUF
streaming tests. If \fI<dev>\fR is a number, then /dev/video\fI<dev>\fR is used.
Otherwise if \fB-z\fR was specified earlier, then \fI<dev>\fR is the entity name
or interface ID (if prefixed with 0x) as found in the topology of the media device
with the bus info string as specified by the \fB-z\fR option.
If this option is not specified, then the DMABUF streaming tests will be skipped.
.TP
\fB-z\fR, \fB--media-bus-info\fR \fI<bus-info>\fR
Find the media device with the given bus info string. If set, then
the options above can use the entity name or interface ID to refer to the
device nodes. Example: v4l2-compliance -z platform:vivid-000 -d vivid-000-vid-cap
.TP
\fB\-m\fR, \fB\-\-media\-device\fR \fI<dev>\fR
Use device \fI<dev>\fR as the media controller device. Besides this device it also tests
all interfaces it finds.  If \fI<dev>\fR starts with a digit, then /dev/media\fI<dev>\fR is used.
If \fI<dev>\fR doesn't exist, then attempt to find a media device with a
bus info string equal to \fI<dev>\fR. Example: v4l2-compliance -m platform:vivid-000
.TP
\fB\-M\fR, \fB\-\-media\-device\-only\fR \fI<dev>\fR
Use device \fI<dev>\fR as the media controller device. Only test this device, don't walk
over all the interfaces.  If \fI<dev>\fR starts with a digit, then /dev/media\fI<dev>\fR is used.
If \fI<dev>\fR doesn't exist, then attempt to find a media device with a
bus info string equal to \fI<dev>\fR. Example: v4l2-compliance -M platform:vivid-000
.TP
.TP
\fB\-\-stream\-from\fR \fI[<pixelformat>=]<file>\fR, \fB\-\-stream\-from\-hdr\fR \fI[<pixelformat>=]<file>\fR
Use the contents of the file to fill in output buffers.
If the fourcc of the pixelformat is given, then use the file
for output buffers using that pixelformat only.
The --stream-from-hdr variant uses the format written by
v4l2-ctl --stream-to-hdr where the payload sizes for each
buffer are stored in a header. Useful for compressed formats.
.TP
\fB\-s\fR, \fB\-\-streaming\fR \fI<count>\fR
Enable the streaming tests. Set <count> to the number of frames to stream (default 60).
This requires that before v4l2-compliance is called the device has been configured with
a valid input (or output) and frequency (when the device has a tuner). For DMABUF testing
--expbuf-device needs to be set as well.

The configuration of the driver at the time v4l2-compliance was called
will be used for the streaming tests.
.TP
\fB\-f\fR, \fB\-\-stream\-all\-formats\fR
Test whether all available formats can be streamed. This attempts to stream using
MMAP mode or read/write (if V4L2_MEMORY_MMAP is not available) for one second for all
formats, at all sizes, at all intervals and with all field values. In addition, if the
driver supports scaling, cropping or composing it will test that as well in various
combinations. If the driver supports a lot of combinations then this test can take
a long time.

The configuration of the driver at the time v4l2-compliance was called
will be used for the streaming tests.
.TP
\fB\-c\fR, \fB\-\-stream\-all\-color\fR \fBcolor\fR=\fIred|green|blue\fR,\fBskip\fR=\fI<skip>\fR,\fBperc\fR=\fI<perc>\fR
For all supported, non-compressed formats stream <skip + 1> frames. For the
last frame go over all pixels and calculate which of the R, G and B color components
of a pixel has the highest value and count that as a red, green or blue pixel.
The test succeeds if at least \fIperc\fR percent of the frame has the given \fIcolor\fR.
This requires that a valid and predominantly red, green or blue video signal is present
on the input(s). If \fIskip\fR is not specified, then just capture the first frame. A
non-zero \fIskip\fR value is useful if it takes a few frames for the device to
calibrate. If \fIperc\fR is not specified, then this defaults to 90%.

Most signal generators are able to generate pure red, blue or green video. For cameras
you can print a completely red, green or blue picture and hold it before the camera.

The goal of this test is to determine if all pixel formats will interpret the red,
green and blue colors correctly and that no color components are swapped.

The configuration of the driver at the time v4l2-compliance was called
will be used for the streaming tests.
.TP
\fB\-a\fR, \fB\-\-stream\-all\-io\fR
Do the \fB\-s\fR, \fB\-c\fR and \fB\-f\fR streaming tests for all inputs or outputs
instead of just the current input or output. This requires that a valid video
signal is present on all inputs or that all outputs are hooked up.
.TP
\fB\-E\fR, \fB\-\-exit\-on\-fail\fR
Exit this application when the first failure occurs instead of continuing
with a possible inconsistent state.
.TP
\fB\-n\fR, \fB\-\-no\-warnings\fR
Turn off warning messages. They are still counted in the summary, but you won't see them.
.TP
\fB\-T\fR, \fB\-\-trace\fR
Trace all called ioctls.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Turn on verbose reporting.
.TP
\fB\-w\fR, \fB\-\-wrapper\fR
Use the libv4l2 wrapper library for all V4L2 device accesses. Note that doing this will
cause some tests to fail because the libv4l2 library isn't fully V4L2 compliant. By
default v4l2-compliance will bypass libv4l2 and access the V4L2 devices directly.
.TP
\fB\-W\fR, \fB\-\-exit\-on\-warn\fR
Exit this application when the first warning occurs instead of continuing.
.TP
\fB\-h\fR, \fB\-\-help\fR
Prints the help message.
.SH EXIT STATUS
On success, it returns 0. Otherwise, it will return the error code.
.SH BUGS
This is a work in progress, and every so often it turns out that some tests done by
v4l2-compliance are too strict or plain wrong. If you suspect that might be the case,
then report such bugs to the linux-media@vger.kernel.org mailinglist.

Privacy Policy