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

   1 <refentry id="vidioc-g-edid">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_G_EDID, VIDIOC_S_EDID</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_G_EDID</refname>
   9     <refname>VIDIOC_S_EDID</refname>
  10     <refpurpose>Get or set the EDID of a video receiver/transmitter</refpurpose>
  11   </refnamediv>
  12
  13   <refsynopsisdiv>
  14     <funcsynopsis>
  15       <funcprototype>
  16         <funcdef>int <function>ioctl</function></funcdef>
  17         <paramdef>int <parameter>fd</parameter></paramdef>
  18         <paramdef>int <parameter>request</parameter></paramdef>
  19         <paramdef>struct v4l2_edid *<parameter>argp</parameter></paramdef>
  20       </funcprototype>
  21     </funcsynopsis>
  22     <funcsynopsis>
  23       <funcprototype>
  24         <funcdef>int <function>ioctl</function></funcdef>
  25         <paramdef>int <parameter>fd</parameter></paramdef>
  26         <paramdef>int <parameter>request</parameter></paramdef>
  27         <paramdef>const struct v4l2_edid *<parameter>argp</parameter></paramdef>
  28       </funcprototype>
  29     </funcsynopsis>
  30   </refsynopsisdiv>
  31
  32   <refsect1>
  33     <title>Arguments</title>
  34
  35     <variablelist>
  36       <varlistentry>
  37         <term><parameter>fd</parameter></term>
  38         <listitem>
  39           <para>&fd;</para>
  40         </listitem>
  41       </varlistentry>
  42       <varlistentry>
  43         <term><parameter>request</parameter></term>
  44         <listitem>
  45           <para>VIDIOC_G_EDID, VIDIOC_S_EDID</para>
  46         </listitem>
  47       </varlistentry>
  48       <varlistentry>
  49         <term><parameter>argp</parameter></term>
  50         <listitem>
  51           <para></para>
  52         </listitem>
  53       </varlistentry>
  54     </variablelist>
  55   </refsect1>
  56
  57   <refsect1>
  58     <title>Description</title>
  59     <para>These ioctls can be used to get or set an EDID associated with an input
  60     from a receiver or an output of a transmitter device. They can be
  61     used with subdevice nodes (/dev/v4l-subdevX) or with video nodes (/dev/videoX).</para>
  62
  63     <para>When used with video nodes the <structfield>pad</structfield> field represents the
  64     input (for video capture devices) or output (for video output devices) index as
  65     is returned by &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; respectively. When used
  66     with subdevice nodes the <structfield>pad</structfield> field represents the
  67     input or output pad of the subdevice. If there is no EDID support for the given
  68     <structfield>pad</structfield> value, then the &EINVAL; will be returned.</para>
  69
  70     <para>To get the EDID data the application has to fill in the <structfield>pad</structfield>,
  71     <structfield>start_block</structfield>, <structfield>blocks</structfield> and <structfield>edid</structfield>
  72     fields and call <constant>VIDIOC_G_EDID</constant>. The current EDID from block
  73     <structfield>start_block</structfield> and of size <structfield>blocks</structfield>
  74     will be placed in the memory <structfield>edid</structfield> points to. The <structfield>edid</structfield>
  75     pointer must point to memory at least <structfield>blocks</structfield>&nbsp;*&nbsp;128 bytes
  76     large (the size of one block is 128 bytes).</para>
  77
  78     <para>If there are fewer blocks than specified, then the driver will set <structfield>blocks</structfield>
  79     to the actual number of blocks. If there are no EDID blocks available at all, then the error code
  80     ENODATA is set.</para>
  81
  82     <para>If blocks have to be retrieved from the sink, then this call will block until they
  83     have been read.</para>
  84
  85     <para>To set the EDID blocks of a receiver the application has to fill in the <structfield>pad</structfield>,
  86     <structfield>blocks</structfield> and <structfield>edid</structfield> fields and set
  87     <structfield>start_block</structfield> to 0. It is not possible to set part of an EDID,
  88     it is always all or nothing. Setting the EDID data is only valid for receivers as it makes
  89     no sense for a transmitter.</para>
  90
  91     <para>The driver assumes that the full EDID is passed in. If there are more EDID blocks than
  92     the hardware can handle then the EDID is not written, but instead the error code E2BIG is set
  93     and <structfield>blocks</structfield> is set to the maximum that the hardware supports.
  94     If <structfield>start_block</structfield> is any
  95     value other than 0 then the error code EINVAL is set.</para>
  96
  97     <para>To disable an EDID you set <structfield>blocks</structfield> to 0. Depending on the
  98     hardware this will drive the hotplug pin low and/or block the source from reading the EDID
  99     data in some way. In any case, the end result is the same: the EDID is no longer available.
 100     </para>
 101
 102     <table pgwide="1" frame="none" id="v4l2-edid">
 103       <title>struct <structname>v4l2_edid</structname></title>
 104       <tgroup cols="3">
 105         &cs-str;
 106         <tbody valign="top">
 107           <row>
 108             <entry>__u32</entry>
 109             <entry><structfield>pad</structfield></entry>
 110             <entry>Pad for which to get/set the EDID blocks. When used with a video device
 111             node the pad represents the input or output index as returned by
 112             &VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; respectively.</entry>
 113           </row>
 114           <row>
 115             <entry>__u32</entry>
 116             <entry><structfield>start_block</structfield></entry>
 117             <entry>Read the EDID from starting with this block. Must be 0 when setting
 118             the EDID.</entry>
 119           </row>
 120           <row>
 121             <entry>__u32</entry>
 122             <entry><structfield>blocks</structfield></entry>
 123             <entry>The number of blocks to get or set. Must be less or equal to 256 (the
 124             maximum number of blocks as defined by the standard). When you set the EDID and
 125             <structfield>blocks</structfield> is 0, then the EDID is disabled or erased.</entry>
 126           </row>
 127           <row>
 128             <entry>__u8&nbsp;*</entry>
 129             <entry><structfield>edid</structfield></entry>
 130             <entry>Pointer to memory that contains the EDID. The minimum size is
 131             <structfield>blocks</structfield>&nbsp;*&nbsp;128.</entry>
 132           </row>
 133           <row>
 134             <entry>__u32</entry>
 135             <entry><structfield>reserved</structfield>[5]</entry>
 136             <entry>Reserved for future extensions. Applications and drivers must
 137             set the array to zero.</entry>
 138           </row>
 139         </tbody>
 140       </tgroup>
 141     </table>
 142   </refsect1>
 143
 144   <refsect1>
 145     &return-value;
 146
 147     <variablelist>
 148       <varlistentry>
 149         <term><errorcode>ENODATA</errorcode></term>
 150         <listitem>
 151           <para>The EDID data is not available.</para>
 152         </listitem>
 153       </varlistentry>
 154       <varlistentry>
 155         <term><errorcode>E2BIG</errorcode></term>
 156         <listitem>
 157           <para>The EDID data you provided is more than the hardware can handle.</para>
 158         </listitem>
 159       </varlistentry>
 160     </variablelist>
 161   </refsect1>
 162 </refentry>