Docbook/media: improve data_offset/bytesused documentation
Subsystems (2)
RFC PATCH 1/1 Docbook/media: improve data_offset/bytesused documentation
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
Documentation/DocBook/media/v4l/io.xml +6 -1
@@ -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>
Documentation/DocBook/media/v4l/io.xml should set this to 0.</entry> · line 926
Quoted 4 lines · Hans Verkuil
Documentation/DocBook/media/v4l/io.xml +4
-0+ 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.
Quoted 6 lines · Nicolas Dufresne
Documentation/DocBook/media/v4l/io.xml should set this to 0.</entry> · line 926
Quoted 4 lines · Hans Verkuil
Documentation/DocBook/media/v4l/io.xml +4
-0+ 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.
Quoted 7 lines
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