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/userspace-api/media/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******************************************************************************
13ioctl VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID
14******************************************************************************
15
16Name
17====
18
19VIDIOC_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
22Synopsis
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
39Arguments
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
49Description
50===========
51
52These ioctls can be used to get or set an EDID associated with an input
53from a receiver or an output of a transmitter device. They can be used
54with subdevice nodes (/dev/v4l-subdevX) or with video nodes
55(/dev/videoX).
56
57When used with video nodes the ``pad`` field represents the input (for
58video capture devices) or output (for video output devices) index as is
59returned by :ref:`VIDIOC_ENUMINPUT` and
60:ref:`VIDIOC_ENUMOUTPUT` respectively. When used
61with subdevice nodes the ``pad`` field represents the input or output
62pad of the subdevice. If there is no EDID support for the given ``pad``
63value, then the ``EINVAL`` error code will be returned.
64
65To get the EDID data the application has to fill in the ``pad``,
66``start_block``, ``blocks`` and ``edid`` fields, zero the ``reserved``
67array 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
72If 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
74available at all, then the error code ``ENODATA`` is set.
75
76If blocks have to be retrieved from the sink, then this call will block
77until they have been read.
78
79If ``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
81total number of available EDID blocks and it will return 0 without
82copying any data. This is an easy way to discover how many EDID blocks
83there 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
90To 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
92zero the ``reserved`` array. It is not possible to set part of an EDID,
93it is always all or nothing. Setting the EDID data is only valid for
94receivers as it makes no sense for a transmitter.
95
96The driver assumes that the full EDID is passed in. If there are more
97EDID blocks than the hardware can handle then the EDID is not written,
98but instead the error code ``E2BIG`` is set and ``blocks`` is set to the
99maximum that the hardware supports. If ``start_block`` is any value
100other than 0 then the error code ``EINVAL`` is set.
101
102To disable an EDID you set ``blocks`` to 0. Depending on the hardware
103this will drive the hotplug pin low and/or block the source from reading
104the EDID data in some way. In any case, the end result is the same: the
105EDID 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
143Return Value
144============
145
146On success 0 is returned, on error -1 and the ``errno`` variable is set
147appropriately. 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.
155