Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit d52e2381 authored by Laurent Pinchart's avatar Laurent Pinchart Committed by Mauro Carvalho Chehab
Browse files

[media] v4l: Support extending the v4l2_pix_format structure 



The v4l2_pix_format structure has no reserved field. It is embedded in
the v4l2_framebuffer structure which has no reserved fields either, and
in the v4l2_format structure which has reserved fields that were not
previously required to be zeroed out by applications.

To allow extending v4l2_pix_format, inline it in the v4l2_framebuffer
structure, and use the priv field as a magic value to indicate that the
application has set all v4l2_pix_format extended fields and zeroed all
reserved fields following the v4l2_pix_format field in the v4l2_format
structure.

The availability of this API extension is reported to userspace through
the new V4L2_CAP_EXT_PIX_FORMAT capability flag. Just checking that the
priv field is still set to the magic value at [GS]_FMT return wouldn't
be enough, as older kernels don't zero the priv field on return.

To simplify the internal API towards drivers zero the extended fields
and set the priv field to the magic value for applications not aware of
the extensions.

Signed-off-by: default avatarLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Signed-off-by: default avatarMauro Carvalho Chehab <m.chehab@samsung.com>
parent b04ef7c0

Documentation/DocBook/media/Makefile

+1 −1
Original line number Diff line number Diff line
@@ -174,7 +174,7 @@ FILENAME = \ 
DOCUMENTED = \

	-e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" \

	-e "s/\(\(enum\|struct\) *\)\(v4l2_[a-zA-Z0-9_]*\)/\1<link linkend=\"\3\">\3<\/link>/g" \

	-e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\) /<link linkend=\"\1\">\1<\/link> /g" \

	-e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\)\(\s\+v4l2_fourcc\)/<link linkend=\"\1\">\1<\/link>\2/g" \

	-e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \

	-e "s/v4l2\-mpeg\-vbi\-ITV0/v4l2-mpeg-vbi-itv0-1/g"

Documentation/DocBook/media/v4l/pixfmt.xml

+22 −3
Original line number Diff line number Diff line
@@ -112,9 +112,28 @@ see <xref linkend="colorspaces" />.</entry> 
	<row>

	  <entry>__u32</entry>

	  <entry><structfield>priv</structfield></entry>

	  <entry>Reserved for custom (driver defined) additional

information about formats. When not used drivers and applications must

set this field to zero.</entry>

	  <entry><para>This field indicates whether the remaining fields of the

<structname>v4l2_pix_format</structname> structure, also called the extended

fields, are valid. When set to <constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, it

indicates that the extended fields have been correctly initialized. When set to

any other value it indicates that the extended fields contain undefined values.

</para>

<para>Applications that wish to use the pixel format extended fields must first

ensure that the feature is supported by querying the device for the

<link linkend="querycap"><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></link>

capability. If the capability isn't set the pixel format extended fields are not

supported and using the extended fields will lead to undefined results.</para>

<para>To use the extended fields, applications must set the

<structfield>priv</structfield> field to

<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant>, initialize all the extended fields

and zero the unused bytes of the <structname>v4l2_format</structname>

<structfield>raw_data</structfield> field.</para>

<para>When the <structfield>priv</structfield> field isn't set to

<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> drivers must act as if all the

extended fields were set to zero. On return drivers must set the

<structfield>priv</structfield> field to

<constant>V4L2_PIX_FMT_PRIV_MAGIC</constant> and all the extended fields to

applicable values.</para></entry>

	</row>

      </tbody>

    </tgroup>

Documentation/DocBook/media/v4l/v4l2.xml

+8 −0
Original line number Diff line number Diff line
@@ -151,6 +151,14 @@ structs, ioctls) must be noted in more detail in the history chapter 
(compat.xml), along with the possible impact on existing drivers and

applications. -->



      <revision>

	<revnumber>3.16</revnumber>

	<date>2014-05-27</date>

	<authorinitials>lp</authorinitials>

	<revremark>Extended &v4l2-pix-format;.

	</revremark>

      </revision>



      <revision>

	<revnumber>3.15</revnumber>

	<date>2014-02-03</date>

Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml

+4 −8
Original line number Diff line number Diff line
@@ -152,13 +152,10 @@ a valid base address, so applications can find the corresponding Linux 
framebuffer device (see <xref linkend="osd" />).</entry>

	  </row>

	  <row>

	    <entry>&v4l2-pix-format;</entry>

	    <entry>struct</entry>

	    <entry><structfield>fmt</structfield></entry>

	    <entry></entry>

	    <entry>Layout of the frame buffer. The

<structname>v4l2_pix_format</structname> structure is defined in <xref

linkend="pixfmt" />, for clarification the fields and acceptable values

	    are listed below:</entry>

	    <entry>Layout of the frame buffer.</entry>

	  </row>

	  <row>

	    <entry></entry>
@@ -276,9 +273,8 @@ see <xref linkend="colorspaces" />.</entry> 
	    <entry></entry>

	    <entry>__u32</entry>

	    <entry><structfield>priv</structfield></entry>

	    <entry>Reserved for additional information about custom

(driver defined) formats. When not used drivers and applications must

set this field to zero.</entry>

	    <entry>Reserved. Drivers and applications must set this field to

zero.</entry>

	  </row>

	</tbody>

      </tgroup>

Documentation/DocBook/media/v4l/vidioc-querycap.xml

+6 −0
Original line number Diff line number Diff line
@@ -300,6 +300,12 @@ modulator programming see 
	    <entry>0x00100000</entry>

	    <entry>The device supports the

<link linkend="sdr">SDR Capture</link> interface.</entry>

	  </row>

	  <row>

	    <entry><constant>V4L2_CAP_EXT_PIX_FORMAT</constant></entry>

	    <entry>0x00200000</entry>

	    <entry>The device supports the &v4l2-pix-format; extended

fields.</entry>

	  </row>

	  <row>

	    <entry><constant>V4L2_CAP_READWRITE</constant></entry>