Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
| 3 | .. _vidioc-subdev-g-frame-interval: |
| 4 | |
| 5 | ******************************************************************** |
| 6 | ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL |
| 7 | ******************************************************************** |
| 8 | |
| 9 | *man VIDIOC_SUBDEV_G_FRAME_INTERVAL(2)* |
| 10 | |
| 11 | VIDIOC_SUBDEV_S_FRAME_INTERVAL |
| 12 | Get or set the frame interval on a subdev pad |
| 13 | |
| 14 | |
| 15 | Synopsis |
| 16 | ======== |
| 17 | |
| 18 | .. c:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_interval *argp ) |
| 19 | |
| 20 | Arguments |
| 21 | ========= |
| 22 | |
| 23 | ``fd`` |
| 24 | File descriptor returned by :ref:`open() <func-open>`. |
| 25 | |
| 26 | ``request`` |
| 27 | VIDIOC_SUBDEV_G_FRAME_INTERVAL, |
| 28 | VIDIOC_SUBDEV_S_FRAME_INTERVAL |
| 29 | |
| 30 | ``argp`` |
| 31 | |
| 32 | |
| 33 | Description |
| 34 | =========== |
| 35 | |
| 36 | These ioctls are used to get and set the frame interval at specific |
| 37 | subdev pads in the image pipeline. The frame interval only makes sense |
| 38 | for sub-devices that can control the frame period on their own. This |
| 39 | includes, for instance, image sensors and TV tuners. Sub-devices that |
| 40 | don't support frame intervals must not implement these ioctls. |
| 41 | |
| 42 | To retrieve the current frame interval applications set the ``pad`` |
| 43 | field of a struct |
| 44 | :ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>` to |
| 45 | the desired pad number as reported by the media controller API. When |
| 46 | they call the ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` ioctl with a pointer to |
| 47 | this structure the driver fills the members of the ``interval`` field. |
| 48 | |
| 49 | To change the current frame interval applications set both the ``pad`` |
| 50 | field and all members of the ``interval`` field. When they call the |
| 51 | ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl with a pointer to this |
| 52 | structure the driver verifies the requested interval, adjusts it based |
| 53 | on the hardware capabilities and configures the device. Upon return the |
| 54 | struct |
| 55 | :ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>` |
| 56 | contains the current frame interval as would be returned by a |
| 57 | ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call. |
| 58 | |
| 59 | Drivers must not return an error solely because the requested interval |
| 60 | doesn't match the device capabilities. They must instead modify the |
| 61 | interval to match what the hardware can provide. The modified interval |
| 62 | should be as close as possible to the original request. |
| 63 | |
| 64 | Sub-devices that support the frame interval ioctls should implement them |
| 65 | on a single pad only. Their behaviour when supported on multiple pads of |
| 66 | the same sub-device is not defined. |
| 67 | |
| 68 | |
| 69 | .. _v4l2-subdev-frame-interval: |
| 70 | |
| 71 | .. flat-table:: struct v4l2_subdev_frame_interval |
| 72 | :header-rows: 0 |
| 73 | :stub-columns: 0 |
| 74 | :widths: 1 1 2 |
| 75 | |
| 76 | |
| 77 | - .. row 1 |
| 78 | |
| 79 | - __u32 |
| 80 | |
| 81 | - ``pad`` |
| 82 | |
| 83 | - Pad number as reported by the media controller API. |
| 84 | |
| 85 | - .. row 2 |
| 86 | |
| 87 | - struct :ref:`v4l2_fract <v4l2-fract>` |
| 88 | |
| 89 | - ``interval`` |
| 90 | |
| 91 | - Period, in seconds, between consecutive video frames. |
| 92 | |
| 93 | - .. row 3 |
| 94 | |
| 95 | - __u32 |
| 96 | |
| 97 | - ``reserved``\ [9] |
| 98 | |
| 99 | - Reserved for future extensions. Applications and drivers must set |
| 100 | the array to zero. |
| 101 | |
| 102 | |
| 103 | |
| 104 | Return Value |
| 105 | ============ |
| 106 | |
| 107 | On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 108 | appropriately. The generic error codes are described at the |
| 109 | :ref:`Generic Error Codes <gen-errors>` chapter. |
| 110 | |
| 111 | EBUSY |
| 112 | The frame interval can't be changed because the pad is currently |
| 113 | busy. This can be caused, for instance, by an active video stream on |
| 114 | the pad. The ioctl must not be retried without performing another |
| 115 | action to fix the problem first. Only returned by |
| 116 | ``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` |
| 117 | |
| 118 | EINVAL |
| 119 | The struct |
| 120 | :ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>` |
| 121 | ``pad`` references a non-existing pad, or the pad doesn't support |
| 122 | frame intervals. |
| 123 | |
| 124 | |
| 125 | .. ------------------------------------------------------------------------------ |
| 126 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 127 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 128 | .. from the linux kernel, refer to: |
| 129 | .. |
| 130 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 131 | .. ------------------------------------------------------------------------------ |