[v4l-utils] [RFC/PATCH] v4l2-compliance: Don't check bytesused or timestamp for error buffers

[v4l-utils] [RFC/PATCH] v4l2-compliance: Don't check bytesused or timestamp for error buffers

[Laurent Pinchart]

When DQBUF returns a buffer marked with the ERROR flag, the bytesused
and timestamp fields are not meaningful. Don't check them.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
I'm sending this as an RFC because the V4L2 API documentation isn't
clear on the subject.

For the bytesused fields, I'm fairly confident that this change is good.
A driver can't be expected to provide data for buffers with errors,
especially if a transmission error occurred.

Similarly, timestamping a buffer upon error may not be something we can
always expect from drivers. I'm a bit more hesitant here though: while
precise timestamping can't be guaranteed, a driver can always use some
sort of timestamp. Doing so could cause issues though, as a driver for a
device that provides hardware timestamping would need to switch to a
software timestamp source for buffers with errors. That would not just
complicate drivers, but would also make it awkward for userspace.

There are a few open questions:

- Are there other buffer fields that we should ignore ?

- Shoulg (some of) the ignored fields be required to have a specific
  value ? For instance we could require the timestamp to be 0 on error.
---
 utils/v4l2-compliance/v4l2-test-buffers.cpp | 22 ++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/utils/v4l2-compliance/v4l2-test-buffers.cpp b/utils/v4l2-compliance/v4l2-test-buffers.cpp
index dba471e5b488..47d4627ee373 100644
--- a/utils/v4l2-compliance/v4l2-test-buffers.cpp
+++ b/utils/v4l2-compliance/v4l2-test-buffers.cpp
@@ -393,16 +393,20 @@ int buffer::check(unsigned type, unsigned memory, unsigned index,
 		warn_once("V4L2_BUF_FLAG_TIMECODE was used!\n");
 
 	if (mode == Dequeued) {
-		for (unsigned p = 0; p < g_num_planes(); p++) {
-			if (!(g_flags() & V4L2_BUF_FLAG_LAST))
-				fail_on_test(!g_bytesused(p));
-			if (!g_bytesused(p))
-				fail_on_test(g_data_offset(p));
-			else
-				fail_on_test(g_data_offset(p) >= g_bytesused(p));
-			fail_on_test(g_bytesused(p) > g_length(p));
+		if (!(g_flags() & V4L2_BUF_FLAG_ERROR)) {
+			for (unsigned p = 0; p < g_num_planes(); p++) {
+				if (!(g_flags() & V4L2_BUF_FLAG_LAST))
+					fail_on_test(!g_bytesused(p));
+				if (!g_bytesused(p))
+					fail_on_test(g_data_offset(p));
+				else
+					fail_on_test(g_data_offset(p) >= g_bytesused(p));
+				fail_on_test(g_bytesused(p) > g_length(p));
+			}
+
+			fail_on_test(!g_timestamp().tv_sec && !g_timestamp().tv_usec);
 		}
-		fail_on_test(!g_timestamp().tv_sec && !g_timestamp().tv_usec);
+
 		fail_on_test(g_flags() & V4L2_BUF_FLAG_DONE);
 
 		// The vivid driver has unreliable timings causing wrong

base-commit: c6600a7e342ef6e336fba02212c90b60a36ca02d
-- 
Regards,

Laurent Pinchart

Re: [v4l-utils] [RFC/PATCH] v4l2-compliance: Don't check bytesused or timestamp for error buffers

[Hans Verkuil]

Hi Laurent,

On 27/10/2026 20:19, Laurent Pinchart wrote:
> When DQBUF returns a buffer marked with the ERROR flag, the bytesused
> and timestamp fields are not meaningful. Don't check them.
> 
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
> I'm sending this as an RFC because the V4L2 API documentation isn't
> clear on the subject.
> 
> For the bytesused fields, I'm fairly confident that this change is good.
> A driver can't be expected to provide data for buffers with errors,
> especially if a transmission error occurred.

Dropping all the bytesused tests if ERROR is set isn't a good idea.
If ERROR is set, then bytesused is allowed to be 0, but you still want
to check that e.g. bytesused isn't > length. Otherwise applications that
do not check for the ERROR flag might try to read beyond the buffer size.

So we have to ensure that what the driver returns for data_offset and
bytesused won't go beyond the buffer size. But they may be 0 if the ERROR
flag is set.

> 
> Similarly, timestamping a buffer upon error may not be something we can
> always expect from drivers. I'm a bit more hesitant here though: while
> precise timestamping can't be guaranteed, a driver can always use some
> sort of timestamp. Doing so could cause issues though, as a driver for a
> device that provides hardware timestamping would need to switch to a
> software timestamp source for buffers with errors. That would not just
> complicate drivers, but would also make it awkward for userspace.

Makes sense.

> 
> There are a few open questions:
> 
> - Are there other buffer fields that we should ignore ?

Possibly the 'field'. In practice I think this might only be an issue for
interlaced formats. If we run into problems with that in v4l2-compliance,
then we can always address that later.

> 
> - Shoulg (some of) the ignored fields be required to have a specific
>   value ? For instance we could require the timestamp to be 0 on error.

No. Leave that to the driver. You'd have to analyze the existing drivers
just to figure out what they are doing today, and drivers using
V4L2_BUF_FLAG_TIMESTAMP_COPY may still copy the timestamp if they have
enough information to tell which output buffer originated the error.

But perhaps adding a note in the documentation saying that the timestamp is
unreliable for an ERROR buffer would be useful.

Regards,

	Hans

> ---
>  utils/v4l2-compliance/v4l2-test-buffers.cpp | 22 ++++++++++++---------
>  1 file changed, 13 insertions(+), 9 deletions(-)
> 
> diff --git a/utils/v4l2-compliance/v4l2-test-buffers.cpp b/utils/v4l2-compliance/v4l2-test-buffers.cpp
> index dba471e5b488..47d4627ee373 100644
> --- a/utils/v4l2-compliance/v4l2-test-buffers.cpp
> +++ b/utils/v4l2-compliance/v4l2-test-buffers.cpp
> @@ -393,16 +393,20 @@ int buffer::check(unsigned type, unsigned memory, unsigned index,
>  		warn_once("V4L2_BUF_FLAG_TIMECODE was used!\n");
>  
>  	if (mode == Dequeued) {
> -		for (unsigned p = 0; p < g_num_planes(); p++) {
> -			if (!(g_flags() & V4L2_BUF_FLAG_LAST))
> -				fail_on_test(!g_bytesused(p));
> -			if (!g_bytesused(p))
> -				fail_on_test(g_data_offset(p));
> -			else
> -				fail_on_test(g_data_offset(p) >= g_bytesused(p));
> -			fail_on_test(g_bytesused(p) > g_length(p));
> +		if (!(g_flags() & V4L2_BUF_FLAG_ERROR)) {
> +			for (unsigned p = 0; p < g_num_planes(); p++) {
> +				if (!(g_flags() & V4L2_BUF_FLAG_LAST))
> +					fail_on_test(!g_bytesused(p));
> +				if (!g_bytesused(p))
> +					fail_on_test(g_data_offset(p));
> +				else
> +					fail_on_test(g_data_offset(p) >= g_bytesused(p));
> +				fail_on_test(g_bytesused(p) > g_length(p));
> +			}
> +
> +			fail_on_test(!g_timestamp().tv_sec && !g_timestamp().tv_usec);
>  		}
> -		fail_on_test(!g_timestamp().tv_sec && !g_timestamp().tv_usec);
> +
>  		fail_on_test(g_flags() & V4L2_BUF_FLAG_DONE);
>  
>  		// The vivid driver has unreliable timings causing wrong
> 
> base-commit: c6600a7e342ef6e336fba02212c90b60a36ca02d

Re: [v4l-utils] [RFC/PATCH] v4l2-compliance: Don't check bytesused or timestamp for error buffers

[Laurent Pinchart]

Hi Hans,

On Thu, Oct 29, 2026 at 11:07:38AM +0100, Hans Verkuil wrote:
> On 27/10/2026 20:19, Laurent Pinchart wrote:
> > When DQBUF returns a buffer marked with the ERROR flag, the bytesused
> > and timestamp fields are not meaningful. Don't check them.
> > 
> > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > ---
> > I'm sending this as an RFC because the V4L2 API documentation isn't
> > clear on the subject.
> > 
> > For the bytesused fields, I'm fairly confident that this change is good.
> > A driver can't be expected to provide data for buffers with errors,
> > especially if a transmission error occurred.
> 
> Dropping all the bytesused tests if ERROR is set isn't a good idea.
> If ERROR is set, then bytesused is allowed to be 0, but you still want
> to check that e.g. bytesused isn't > length. Otherwise applications that
> do not check for the ERROR flag might try to read beyond the buffer size.
> 
> So we have to ensure that what the driver returns for data_offset and
> bytesused won't go beyond the buffer size. But they may be 0 if the ERROR
> flag is set.

Good points. I'll send a v2.

> > Similarly, timestamping a buffer upon error may not be something we can
> > always expect from drivers. I'm a bit more hesitant here though: while
> > precise timestamping can't be guaranteed, a driver can always use some
> > sort of timestamp. Doing so could cause issues though, as a driver for a
> > device that provides hardware timestamping would need to switch to a
> > software timestamp source for buffers with errors. That would not just
> > complicate drivers, but would also make it awkward for userspace.
> 
> Makes sense.
> 
> > There are a few open questions:
> > 
> > - Are there other buffer fields that we should ignore ?
> 
> Possibly the 'field'. In practice I think this might only be an issue for
> interlaced formats. If we run into problems with that in v4l2-compliance,
> then we can always address that later.

There was a failure with the libcamera v4l2-compat adaptation layer that
didn't set the field in that case, leaving it to 0. I've handled that in
libcamera for now, hardcoding V4L2_FIELD_NONE as we don't support
interlaced formats. We can revisit that later if needed.

> > - Shoulg (some of) the ignored fields be required to have a specific
> >   value ? For instance we could require the timestamp to be 0 on error.
> 
> No. Leave that to the driver. You'd have to analyze the existing drivers
> just to figure out what they are doing today, and drivers using
> V4L2_BUF_FLAG_TIMESTAMP_COPY may still copy the timestamp if they have
> enough information to tell which output buffer originated the error.
> 
> But perhaps adding a note in the documentation saying that the timestamp is
> unreliable for an ERROR buffer would be useful.

OK, I'll do that.

Thank you for your thoughts on the topic.

> > ---
> >  utils/v4l2-compliance/v4l2-test-buffers.cpp | 22 ++++++++++++---------
> >  1 file changed, 13 insertions(+), 9 deletions(-)
> > 
> > diff --git a/utils/v4l2-compliance/v4l2-test-buffers.cpp b/utils/v4l2-compliance/v4l2-test-buffers.cpp
> > index dba471e5b488..47d4627ee373 100644
> > --- a/utils/v4l2-compliance/v4l2-test-buffers.cpp
> > +++ b/utils/v4l2-compliance/v4l2-test-buffers.cpp
> > @@ -393,16 +393,20 @@ int buffer::check(unsigned type, unsigned memory, unsigned index,
> >  		warn_once("V4L2_BUF_FLAG_TIMECODE was used!\n");
> >  
> >  	if (mode == Dequeued) {
> > -		for (unsigned p = 0; p < g_num_planes(); p++) {
> > -			if (!(g_flags() & V4L2_BUF_FLAG_LAST))
> > -				fail_on_test(!g_bytesused(p));
> > -			if (!g_bytesused(p))
> > -				fail_on_test(g_data_offset(p));
> > -			else
> > -				fail_on_test(g_data_offset(p) >= g_bytesused(p));
> > -			fail_on_test(g_bytesused(p) > g_length(p));
> > +		if (!(g_flags() & V4L2_BUF_FLAG_ERROR)) {
> > +			for (unsigned p = 0; p < g_num_planes(); p++) {
> > +				if (!(g_flags() & V4L2_BUF_FLAG_LAST))
> > +					fail_on_test(!g_bytesused(p));
> > +				if (!g_bytesused(p))
> > +					fail_on_test(g_data_offset(p));
> > +				else
> > +					fail_on_test(g_data_offset(p) >= g_bytesused(p));
> > +				fail_on_test(g_bytesused(p) > g_length(p));
> > +			}
> > +
> > +			fail_on_test(!g_timestamp().tv_sec && !g_timestamp().tv_usec);
> >  		}
> > -		fail_on_test(!g_timestamp().tv_sec && !g_timestamp().tv_usec);
> > +
> >  		fail_on_test(g_flags() & V4L2_BUF_FLAG_DONE);
> >  
> >  		// The vivid driver has unreliable timings causing wrong
> > 
> > base-commit: c6600a7e342ef6e336fba02212c90b60a36ca02d

-- 
Regards,

Laurent Pinchart