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