0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_SUBDEV_G_FRAME_INTERVAL:
0005
0006 ********************************************************************
0007 ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL
0008 ********************************************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_SUBDEV_G_FRAME_INTERVAL - VIDIOC_SUBDEV_S_FRAME_INTERVAL - Get or set the frame interval on a subdev pad
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_SUBDEV_G_FRAME_INTERVAL
0019
0020 ``int ioctl(int fd, VIDIOC_SUBDEV_G_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp)``
0021
0022 .. c:macro:: VIDIOC_SUBDEV_S_FRAME_INTERVAL
0023
0024 ``int ioctl(int fd, VIDIOC_SUBDEV_S_FRAME_INTERVAL, struct v4l2_subdev_frame_interval *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to struct :c:type:`v4l2_subdev_frame_interval`.
0034
0035 Description
0036 ===========
0037
0038 These ioctls are used to get and set the frame interval at specific
0039 subdev pads in the image pipeline. The frame interval only makes sense
0040 for sub-devices that can control the frame period on their own. This
0041 includes, for instance, image sensors and TV tuners. Sub-devices that
0042 don't support frame intervals must not implement these ioctls.
0043
0044 To retrieve the current frame interval applications set the ``pad``
0045 field of a struct
0046 :c:type:`v4l2_subdev_frame_interval` to
0047 the desired pad number as reported by the media controller API. When
0048 they call the ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` ioctl with a pointer to
0049 this structure the driver fills the members of the ``interval`` field.
0050
0051 To change the current frame interval applications set both the ``pad``
0052 field and all members of the ``interval`` field. When they call the
0053 ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl with a pointer to this
0054 structure the driver verifies the requested interval, adjusts it based
0055 on the hardware capabilities and configures the device. Upon return the
0056 struct
0057 :c:type:`v4l2_subdev_frame_interval`
0058 contains the current frame interval as would be returned by a
0059 ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
0060
0061 Calling ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` on a subdev device node that has been
0062 registered in read-only mode is not allowed. An error is returned and the errno
0063 variable is set to ``-EPERM``.
0064
0065 Drivers must not return an error solely because the requested interval
0066 doesn't match the device capabilities. They must instead modify the
0067 interval to match what the hardware can provide. The modified interval
0068 should be as close as possible to the original request.
0069
0070 Changing the frame interval shall never change the format. Changing the
0071 format, on the other hand, may change the frame interval.
0072
0073 Sub-devices that support the frame interval ioctls should implement them
0074 on a single pad only. Their behaviour when supported on multiple pads of
0075 the same sub-device is not defined.
0076
0077 .. c:type:: v4l2_subdev_frame_interval
0078
0079 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0080
0081 .. flat-table:: struct v4l2_subdev_frame_interval
0082 :header-rows: 0
0083 :stub-columns: 0
0084 :widths: 1 1 2
0085
0086 * - __u32
0087 - ``pad``
0088 - Pad number as reported by the media controller API.
0089 * - struct :c:type:`v4l2_fract`
0090 - ``interval``
0091 - Period, in seconds, between consecutive video frames.
0092 * - __u32
0093 - ``reserved``\ [9]
0094 - Reserved for future extensions. Applications and drivers must set
0095 the array to zero.
0096
0097 Return Value
0098 ============
0099
0100 On success 0 is returned, on error -1 and the ``errno`` variable is set
0101 appropriately. The generic error codes are described at the
0102 :ref:`Generic Error Codes <gen-errors>` chapter.
0103
0104 EBUSY
0105 The frame interval can't be changed because the pad is currently
0106 busy. This can be caused, for instance, by an active video stream on
0107 the pad. The ioctl must not be retried without performing another
0108 action to fix the problem first. Only returned by
0109 ``VIDIOC_SUBDEV_S_FRAME_INTERVAL``
0110
0111 EINVAL
0112 The struct
0113 :c:type:`v4l2_subdev_frame_interval`
0114 ``pad`` references a non-existing pad, or the pad doesn't support
0115 frame intervals.
0116
0117 EPERM
0118 The ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl has been called on a read-only
0119 subdevice.
