Running v4l2-compliance

Like the other V4L2 tools in this series, v4l2-compliance targets /dev/video0 by default, or a specific node with -d:

$ v4l2-compliance -d /dev/video0

It begins by printing the same driver info block you saw from v4l2-ctl -D, then runs through every applicable test category — required ioctls, buffer allocation, control ioctls, format ioctls, streaming ioctls, and more — printing one line per test with a final pass/fail summary. For a full breakdown of every check rather than a compact summary, add --verbose:

$ v4l2-compliance -d /dev/video0 --verbose

Reading The Compliance Report

A typical run against a well-behaved UVC webcam driver looks like this:

v4l2-compliance SHA: not available, unable to check for modifications

Driver Info:
        Driver name      : uvcvideo
        Card type        : USB HD Camera
        Driver version   : 6.8.0

Required ioctls:
        test VIDIOC_QUERYCAP: OK

Allow for multiple opens:
        test second video open: OK
        test VIDIOC_QUERYCAP: OK
        test VIDIOC_G/S_PRIORITY: OK
        test for unlimited opens: OK

Debug ioctls:
        test VIDIOC_DBG_G/S_REGISTER: OK (Not Supported)
        test VIDIOC_LOG_STATUS: OK (Not Supported)

Output ioctls:
        test VIDIOC_G/S_MODULATOR: OK (Not Supported)
        test VIDIOC_G/S_FREQUENCY: OK (Not Supported)

Test input 0:
        Control ioctls:
                test VIDIOC_QUERYCTRL: OK
                test VIDIOC_G/S_CTRL: OK
                test VIDIOC_QUERY_EXT_CTRL/QUERYMENU: OK

Total: 45, Succeeded: 45, Failed: 0, Warnings: 0

Three outcomes matter here. OK means the test passed. OK (Not Supported) means the feature is genuinely optional and the driver correctly reports that it doesn’t implement it — this is not a problem. A bare FAIL means the driver implements the ioctl incorrectly, and that is what needs fixing before the driver can be considered compliant.

Fixing Common Compliance Failures

A driver in early development often fails the control ioctl tests first, since controls are one of the more intricate parts of the V4L2 API to implement correctly:

Control ioctls:
        fail: v4l2-test-controls.cpp(214): missing control class for class 00980000
        test VIDIOC_QUERY_EXT_CTRL/QUERYMENU: FAIL
        test VIDIOC_QUERYCTRL: OK
        fail: v4l2-test-controls.cpp(437): s_ctrl returned an error (84)
        test VIDIOC_G/S_CTRL: FAIL

The “missing control class” failure means the driver registered individual controls (like brightness) under the standard “User Controls” class (V4L2_CID_BASE, class ID 0x00980000) but never registered the class descriptor itself — a one-line fix in the driver’s control handler setup using v4l2_ctrl_handler_init() correctly initializes this. The s_ctrl returned an error (84) failure (errno 84, EILSEQ) typically indicates the driver’s .s_ctrl callback rejected a value that VIDIOC_QUERYCTRL itself had reported as valid — a mismatch between the advertised range and the actual implementation that must be corrected in the driver source.

Comparison Table: V4L2 Testing Tools In This Series

Tool	Purpose	When To Use
v4l2-ctl	Inspect and configure a device	Day-to-day device control and capture
dev_debug / videobuf2 debug	Live ioctl and buffer state tracing	Diagnosing a specific misbehaving capture
v4l2-compliance	Validate ioctl-level driver correctness	Driver bring-up and upstream submission

Demo: A Reusable Compliance Check Script

Here is an original helper script, ep_v4l2_compliance_check.sh, that runs v4l2-compliance, extracts the summary line, and exits with a non-zero status on any failure — handy for wiring into a CI pipeline or a driver bring-up checklist.

#!/bin/sh
# ep_v4l2_compliance_check.sh — EmbeddedPathashala compliance gate
set -e

DEV=${1:-/dev/video0}
LOG=$(mktemp)

echo "[ep] running v4l2-compliance against ${DEV}..."
v4l2-compliance -d "$DEV" --verbose > "$LOG" 2>&1 || true

SUMMARY=$(grep -E "^Total:" "$LOG")
FAILED=$(echo "$SUMMARY" | sed -n 's/.*Failed: \([0-9]*\).*/\1/p')

echo "[ep] ${SUMMARY}"

if [ "$FAILED" -gt 0 ]; then
    echo "[ep] COMPLIANCE FAILED — details below:"
    grep -B1 "FAIL" "$LOG"
    rm -f "$LOG"
    exit 1
fi

echo "[ep] COMPLIANCE PASSED"
rm -f "$LOG"
exit 0

Run it:

$ chmod +x ep_v4l2_compliance_check.sh
$ ./ep_v4l2_compliance_check.sh /dev/video0

Expected output on a compliant driver:

[ep] running v4l2-compliance against /dev/video0...
[ep] Total: 45, Succeeded: 45, Failed: 0, Warnings: 0
[ep] COMPLIANCE PASSED

Expected output on a driver with control bugs:

[ep] running v4l2-compliance against /dev/video0...
[ep] Total: 45, Succeeded: 42, Failed: 3, Warnings: 0
[ep] COMPLIANCE FAILED — details below:
        test VIDIOC_QUERY_EXT_CTRL/QUERYMENU: FAIL
        test VIDIOC_G/S_CTRL: FAIL

Real-World Use Cases

V4L2 compliance testing is a mandatory step before any camera or capture driver is submitted to the linux-media mailing list for upstream review — maintainers routinely ask contributors to attach a clean v4l2-compliance run with their patch series. Hardware vendors building custom Linux BSPs run it as part of board bring-up to confirm a vendor-supplied sensor driver actually implements the V4L2 contract correctly rather than only working with one specific vendor application. CI systems for embedded camera products wire the script style shown above directly into automated hardware-in-the-loop test rigs, failing a build the moment a driver change regresses compliance.

Common Mistakes And Troubleshooting

Best Practices

Run v4l2-compliance early and often during driver development, not just before submission — catching a missing control class on day one is far cheaper than debugging it after the format and streaming ioctls are already layered on top. Keep a compliance log from each driver revision so regressions are easy to spot in a diff.

Performance Considerations

v4l2-compliance itself briefly starts and stops streaming multiple times during a full run, which is safe on real hardware but can be slow (tens of seconds) on devices with high buffer-allocation latency; this is a one-time development-time cost, not a runtime concern.

Security Considerations

Because several compliance tests intentionally probe boundary and invalid input values (out-of-range control values, malformed format requests), only ever run it against test hardware or development boards — never against a camera actively in production use, since a poorly hardened driver could behave unpredictably under adversarial ioctl input.

Series Summary And Key Takeaways

Across this four-part mini-series on the V4L2 user space API, you have covered the full lifecycle a Linux camera application and driver go through: dequeuing buffers with MMAP, USERPTR, and DMABUF; controlling and configuring devices with v4l2-ctl; capturing and debugging streams with live kernel tracing; and finally validating driver correctness with v4l2-compliance. Together, these four lectures give you everything needed to both build a V4L2 capture application and evaluate whether a kernel-side V4L2 driver is implemented correctly.

Conclusion

V4L2 compliance testing closes the loop on this series: it is the objective, tool-driven answer to “does my driver actually implement V4L2 correctly,” rather than “does it merely work with the one application I tested.” Whether you are porting a new camera sensor, reviewing a colleague’s driver, or preparing a patch for the mainline Linux kernel, running v4l2-compliance before, during, and after development is one of the highest-leverage habits you can build as a Linux device driver engineer.

Frequently Asked Questions

What is v4l2-compliance used for?

It is a test tool from v4l-utils that exercises nearly every V4L2 ioctl against a driver and reports which ones pass, fail, or are correctly unsupported, used to validate driver correctness before upstream submission.

Does every V4L2 driver need to pass v4l2-compliance?

Any driver intended for mainline Linux kernel inclusion is expected to pass cleanly; vendor out-of-tree drivers are not strictly required to, but doing so catches real correctness bugs regardless.

What does “OK (Not Supported)” mean in the compliance report?

It means the driver correctly reports that it does not implement an optional feature, such as tuner or debug ioctls on a plain capture-only device — this is expected behavior, not a failure.

How do I see exactly why a test failed?

Re-run v4l2-compliance with the –verbose flag, or grep the output for FAIL, which shows the specific assertion, source file, and line number from the compliance test suite.

Can v4l2-compliance be run automatically in CI?

Yes, wrapping it in a script that checks the Failed count in the Total summary line (as shown in this lecture’s demo) makes it straightforward to fail a build on any compliance regression.

What package provides v4l2-compliance?

It ships in the same v4l-utils package as v4l2-ctl, so no separate installation is needed if you already have v4l2-ctl available.