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

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