Documentation/media/uapi/v4l/vidioc-enum-dv-timings.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_ENUM_DV_TIMINGS:
  11
  12 ***********************************************************
  13 ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS
  14 ***********************************************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_ENUM_DV_TIMINGS - VIDIOC_SUBDEV_ENUM_DV_TIMINGS - Enumerate supported Digital Video timings
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp )
  26     :name: VIDIOC_ENUM_DV_TIMINGS
  27
  28 .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_ENUM_DV_TIMINGS, struct v4l2_enum_dv_timings *argp )
  29     :name: VIDIOC_SUBDEV_ENUM_DV_TIMINGS
  30
  31
  32 Arguments
  33 =========
  34
  35 ``fd``
  36     File descriptor returned by :ref:`open() <func-open>`.
  37
  38 ``argp``
  39     Pointer to struct :c:type:`v4l2_enum_dv_timings`.
  40
  41
  42 Description
  43 ===========
  44
  45 While some DV receivers or transmitters support a wide range of timings,
  46 others support only a limited number of timings. With this ioctl
  47 applications can enumerate a list of known supported timings. Call
  48 :ref:`VIDIOC_DV_TIMINGS_CAP` to check if it
  49 also supports other standards or even custom timings that are not in
  50 this list.
  51
  52 To query the available timings, applications initialize the ``index``
  53 field, set the ``pad`` field to 0, zero the reserved array of struct
  54 :c:type:`v4l2_enum_dv_timings` and call the
  55 ``VIDIOC_ENUM_DV_TIMINGS`` ioctl on a video node with a pointer to this
  56 structure. Drivers fill the rest of the structure or return an ``EINVAL``
  57 error code when the index is out of bounds. To enumerate all supported
  58 DV timings, applications shall begin at index zero, incrementing by one
  59 until the driver returns ``EINVAL``.
  60
  61 .. note::
  62
  63    Drivers may enumerate a different set of DV timings after
  64    switching the video input or output.
  65
  66 When implemented by the driver DV timings of subdevices can be queried
  67 by calling the ``VIDIOC_SUBDEV_ENUM_DV_TIMINGS`` ioctl directly on a
  68 subdevice node. The DV timings are specific to inputs (for DV receivers)
  69 or outputs (for DV transmitters), applications must specify the desired
  70 pad number in the struct
  71 :c:type:`v4l2_enum_dv_timings` ``pad`` field.
  72 Attempts to enumerate timings on a pad that doesn't support them will
  73 return an ``EINVAL`` error code.
  74
  75
  76 .. c:type:: v4l2_enum_dv_timings
  77
  78 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  79
  80 .. flat-table:: struct v4l2_enum_dv_timings
  81     :header-rows:  0
  82     :stub-columns: 0
  83     :widths:       1 1 2
  84
  85     * - __u32
  86       - ``index``
  87       - Number of the DV timings, set by the application.
  88     * - __u32
  89       - ``pad``
  90       - Pad number as reported by the media controller API. This field is
  91         only used when operating on a subdevice node. When operating on a
  92         video node applications must set this field to zero.
  93     * - __u32
  94       - ``reserved``\ [2]
  95       - Reserved for future extensions. Drivers and applications must set
  96         the array to zero.
  97     * - struct :c:type:`v4l2_dv_timings`
  98       - ``timings``
  99       - The timings.
 100
 101
 102 Return Value
 103 ============
 104
 105 On success 0 is returned, on error -1 and the ``errno`` variable is set
 106 appropriately. The generic error codes are described at the
 107 :ref:`Generic Error Codes <gen-errors>` chapter.
 108
 109 EINVAL
 110     The struct :c:type:`v4l2_enum_dv_timings`
 111     ``index`` is out of bounds or the ``pad`` number is invalid.
 112
 113 ENODATA
 114     Digital video presets are not supported for this input or output.