[RFC PATCH] Docbook/media: improve data_offset/bytesused documentation

[RFC PATCH] Docbook/media: improve data_offset/bytesused documentation

[Hans Verkuil]

This patch explicitly documents the relationship between bytesused and data_offset.

But looking in the kernel there isn't a single driver that actually sets data_offset.
Do such beasts exist? It's also annoying that there is no such equivalent for the
single planar API, so it is asymmetrical. What was the reason that we never did that
for single planar? Because existing applications wouldn't know what to do with it?

Regards,

	Hans

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>

diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
index 8c4ee74..e5e8325 100644
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -870,7 +870,8 @@ should set this to 0.</entry>
 	      If the application sets this to 0 for an output stream, then
 	      <structfield>bytesused</structfield> will be set to the size of the
 	      plane (see the <structfield>length</structfield> field of this struct)
-	      by the driver.</entry>
+	      by the driver. Note that the actual image data starts at
+	      <structfield>data_offset</structfield> which may not be 0.</entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
@@ -919,6 +920,10 @@ should set this to 0.</entry>
 	    <entry>Offset in bytes to video data in the plane.
 	      Drivers must set this field when <structfield>type</structfield>
 	      refers to an input stream, applications when it refers to an output stream.
+	      Note that data_offset is included in <structfield>bytesused</structfield>.
+	      So the size of the image in the plane is
+	      <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at
+	      offset <structfield>data_offset</structfield> from the start of the plane.
 	    </entry>
 	  </row>
 	  <row>

Re: [RFC PATCH] Docbook/media: improve data_offset/bytesused documentation

[Nicolas Dufresne]

Le lundi 21 juillet 2014 à 15:16 +0200, Hans Verkuil a écrit :
> +             Note that data_offset is included in <structfield>bytesused</structfield>.
> +             So the size of the image in the plane is
> +             <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at
> +             offset <structfield>data_offset</structfield> from the start of the plane.

This seem like messing applications a lot. Let's say you have a well
known format, NV12, but your driver add some customer header at the
beginning. Pretty much all the application in the world would work just
fine ignoring that header, but in fact most of them will not work,
because bytesused is including the header. Considering this wasn't
documented before, I would strongly suggest to keep the bytesused as
being the size for the format know by everyone.

Re: [RFC PATCH] Docbook/media: improve data_offset/bytesused documentation

[Hans Verkuil]

On 07/21/2014 03:30 PM, Nicolas Dufresne wrote:
> Le lundi 21 juillet 2014 à 15:16 +0200, Hans Verkuil a écrit :
>> +             Note that data_offset is included in <structfield>bytesused</structfield>.
>> +             So the size of the image in the plane is
>> +             <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at
>> +             offset <structfield>data_offset</structfield> from the start of the plane.
> 
> This seem like messing applications a lot. Let's say you have a well
> known format, NV12, but your driver add some customer header at the
> beginning. Pretty much all the application in the world would work just
> fine ignoring that header, but in fact most of them will not work,
> because bytesused is including the header. Considering this wasn't
> documented before, I would strongly suggest to keep the bytesused as
> being the size for the format know by everyone.

1) data_offset applies *only* to drivers that use the multiplanar API (i.e. have
V4L2_CAP_VIDEO_CAPTURE/OUTPUT/M2M_MPLANE set). The older single planar API is not
touched by this. So only applications that can handle the mp API should take
data_offset into account.

2) I don't see how it matters whether or not bytesused includes the data_offset.
With a non-zero data_offset and an application that doesn't understand data_offset
it will be wrong either way. In the case of V4L2 'bytesused' has always been the
amount of data that is stored in the buffer. It makes no assumptions on what that
data contains. And that's not going to change.

I've added this patch to a pull request to at least get the documentation fixed,
because the documentation was really not clear on this topic, so that's a real
bug.

Regards,

	Hans