Documentation/media/uapi/v4l/vidioc-g-edid.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_G_EDID:
  11
  12 ******************************************************************************
  13 ioctl VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID
  14 ******************************************************************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_G_EDID - VIDIOC_S_EDID - VIDIOC_SUBDEV_G_EDID - VIDIOC_SUBDEV_S_EDID - Get or set the EDID of a video receiver/transmitter
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_G_EDID, struct v4l2_edid *argp )
  26     :name: VIDIOC_G_EDID
  27
  28 .. c:function:: int ioctl( int fd, VIDIOC_S_EDID, struct v4l2_edid *argp )
  29     :name: VIDIOC_S_EDID
  30
  31
  32 .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_EDID, struct v4l2_edid *argp )
  33     :name: VIDIOC_SUBDEV_G_EDID
  34
  35 .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_EDID, struct v4l2_edid *argp )
  36     :name: VIDIOC_SUBDEV_S_EDID
  37
  38
  39 Arguments
  40 =========
  41
  42 ``fd``
  43     File descriptor returned by :ref:`open() <func-open>`.
  44
  45 ``argp``
  46    Pointer to struct :c:type:`v4l2_edid`.
  47
  48
  49 Description
  50 ===========
  51
  52 These ioctls can be used to get or set an EDID associated with an input
  53 from a receiver or an output of a transmitter device. They can be used
  54 with subdevice nodes (/dev/v4l-subdevX) or with video nodes
  55 (/dev/videoX).
  56
  57 When used with video nodes the ``pad`` field represents the input (for
  58 video capture devices) or output (for video output devices) index as is
  59 returned by :ref:`VIDIOC_ENUMINPUT` and
  60 :ref:`VIDIOC_ENUMOUTPUT` respectively. When used
  61 with subdevice nodes the ``pad`` field represents the input or output
  62 pad of the subdevice. If there is no EDID support for the given ``pad``
  63 value, then the ``EINVAL`` error code will be returned.
  64
  65 To get the EDID data the application has to fill in the ``pad``,
  66 ``start_block``, ``blocks`` and ``edid`` fields, zero the ``reserved``
  67 array and call :ref:`VIDIOC_G_EDID <VIDIOC_G_EDID>`. The current EDID from block
  68 ``start_block`` and of size ``blocks`` will be placed in the memory
  69 ``edid`` points to. The ``edid`` pointer must point to memory at least
  70 ``blocks`` * 128 bytes large (the size of one block is 128 bytes).
  71
  72 If there are fewer blocks than specified, then the driver will set
  73 ``blocks`` to the actual number of blocks. If there are no EDID blocks
  74 available at all, then the error code ``ENODATA`` is set.
  75
  76 If blocks have to be retrieved from the sink, then this call will block
  77 until they have been read.
  78
  79 If ``start_block`` and ``blocks`` are both set to 0 when
  80 :ref:`VIDIOC_G_EDID <VIDIOC_G_EDID>` is called, then the driver will set ``blocks`` to the
  81 total number of available EDID blocks and it will return 0 without
  82 copying any data. This is an easy way to discover how many EDID blocks
  83 there are.
  84
  85 .. note::
  86
  87    If there are no EDID blocks available at all, then
  88    the driver will set ``blocks`` to 0 and it returns 0.
  89
  90 To set the EDID blocks of a receiver the application has to fill in the
  91 ``pad``, ``blocks`` and ``edid`` fields, set ``start_block`` to 0 and
  92 zero the ``reserved`` array. It is not possible to set part of an EDID,
  93 it is always all or nothing. Setting the EDID data is only valid for
  94 receivers as it makes no sense for a transmitter.
  95
  96 The driver assumes that the full EDID is passed in. If there are more
  97 EDID blocks than the hardware can handle then the EDID is not written,
  98 but instead the error code ``E2BIG`` is set and ``blocks`` is set to the
  99 maximum that the hardware supports. If ``start_block`` is any value
 100 other than 0 then the error code ``EINVAL`` is set.
 101
 102 To disable an EDID you set ``blocks`` to 0. Depending on the hardware
 103 this will drive the hotplug pin low and/or block the source from reading
 104 the EDID data in some way. In any case, the end result is the same: the
 105 EDID is no longer available.
 106
 107
 108 .. c:type:: v4l2_edid
 109
 110 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
 111
 112 .. flat-table:: struct v4l2_edid
 113     :header-rows:  0
 114     :stub-columns: 0
 115     :widths:       1 1 2
 116
 117     * - __u32
 118       - ``pad``
 119       - Pad for which to get/set the EDID blocks. When used with a video
 120         device node the pad represents the input or output index as
 121         returned by :ref:`VIDIOC_ENUMINPUT` and
 122         :ref:`VIDIOC_ENUMOUTPUT` respectively.
 123     * - __u32
 124       - ``start_block``
 125       - Read the EDID from starting with this block. Must be 0 when
 126         setting the EDID.
 127     * - __u32
 128       - ``blocks``
 129       - The number of blocks to get or set. Must be less or equal to 256
 130         (the maximum number of blocks as defined by the standard). When
 131         you set the EDID and ``blocks`` is 0, then the EDID is disabled or
 132         erased.
 133     * - __u32
 134       - ``reserved``\ [5]
 135       - Reserved for future extensions. Applications and drivers must set
 136         the array to zero.
 137     * - __u8 *
 138       - ``edid``
 139       - Pointer to memory that contains the EDID. The minimum size is
 140         ``blocks`` * 128.
 141
 142
 143 Return Value
 144 ============
 145
 146 On success 0 is returned, on error -1 and the ``errno`` variable is set
 147 appropriately. The generic error codes are described at the
 148 :ref:`Generic Error Codes <gen-errors>` chapter.
 149
 150 ``ENODATA``
 151     The EDID data is not available.
 152
 153 ``E2BIG``
 154     The EDID data you provided is more than the hardware can handle.