0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_DECODER_CMD:
0005
0006 ************************************************
0007 ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD
0008 ************************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - Execute an decoder command
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_DECODER_CMD
0019
0020 ``int ioctl(int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp)``
0021
0022 .. c:macro:: VIDIOC_TRY_DECODER_CMD
0023
0024 ``int ioctl(int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *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_decoder_cmd`.
0034
0035 Description
0036 ===========
0037
0038 These ioctls control an audio/video (usually MPEG-) decoder.
0039 ``VIDIOC_DECODER_CMD`` sends a command to the decoder,
0040 ``VIDIOC_TRY_DECODER_CMD`` can be used to try a command without actually
0041 executing it. To send a command applications must initialize all fields
0042 of a struct :c:type:`v4l2_decoder_cmd` and call
0043 ``VIDIOC_DECODER_CMD`` or ``VIDIOC_TRY_DECODER_CMD`` with a pointer to
0044 this structure.
0045
0046 The ``cmd`` field must contain the command code. Some commands use the
0047 ``flags`` field for additional information.
0048
0049 A :c:func:`write()` or :ref:`VIDIOC_STREAMON`
0050 call sends an implicit START command to the decoder if it has not been
0051 started yet. Applies to both queues of mem2mem decoders.
0052
0053 A :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
0054 call of a streaming file descriptor sends an implicit immediate STOP
0055 command to the decoder, and all buffered data is discarded. Applies to both
0056 queues of mem2mem decoders.
0057
0058 In principle, these ioctls are optional, not all drivers may support them. They were
0059 introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decoders
0060 (as further documented in :ref:`decoder`).
0061
0062 .. tabularcolumns:: |p{2.0cm}|p{1.1cm}|p{2.2cm}|p{11.8cm}|
0063
0064 .. c:type:: v4l2_decoder_cmd
0065
0066 .. cssclass:: longtable
0067
0068 .. flat-table:: struct v4l2_decoder_cmd
0069 :header-rows: 0
0070 :stub-columns: 0
0071 :widths: 1 1 1 3
0072
0073 * - __u32
0074 - ``cmd``
0075 -
0076 - The decoder command, see :ref:`decoder-cmds`.
0077 * - __u32
0078 - ``flags``
0079 -
0080 - Flags to go with the command. If no flags are defined for this
0081 command, drivers and applications must set this field to zero.
0082 * - union {
0083 - (anonymous)
0084 * - struct
0085 - ``start``
0086 -
0087 - Structure containing additional data for the
0088 ``V4L2_DEC_CMD_START`` command.
0089 * -
0090 - __s32
0091 - ``speed``
0092 - Playback speed and direction. The playback speed is defined as
0093 ``speed``/1000 of the normal speed. So 1000 is normal playback.
0094 Negative numbers denote reverse playback, so -1000 does reverse
0095 playback at normal speed. Speeds -1, 0 and 1 have special
0096 meanings: speed 0 is shorthand for 1000 (normal playback). A speed
0097 of 1 steps just one frame forward, a speed of -1 steps just one
0098 frame back.
0099 * -
0100 - __u32
0101 - ``format``
0102 - Format restrictions. This field is set by the driver, not the
0103 application. Possible values are ``V4L2_DEC_START_FMT_NONE`` if
0104 there are no format restrictions or ``V4L2_DEC_START_FMT_GOP`` if
0105 the decoder operates on full GOPs (*Group Of Pictures*). This is
0106 usually the case for reverse playback: the decoder needs full
0107 GOPs, which it can then play in reverse order. So to implement
0108 reverse playback the application must feed the decoder the last
0109 GOP in the video file, then the GOP before that, etc. etc.
0110 * - struct
0111 - ``stop``
0112 -
0113 - Structure containing additional data for the ``V4L2_DEC_CMD_STOP``
0114 command.
0115 * -
0116 - __u64
0117 - ``pts``
0118 - Stop playback at this ``pts`` or immediately if the playback is
0119 already past that timestamp. Leave to 0 if you want to stop after
0120 the last frame was decoded.
0121 * - struct
0122 - ``raw``
0123 * -
0124 - __u32
0125 - ``data``\ [16]
0126 - Reserved for future extensions. Drivers and applications must set
0127 the array to zero.
0128 * - }
0129 -
0130
0131
0132 .. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.1cm}|
0133
0134 .. cssclass:: longtable
0135
0136 .. _decoder-cmds:
0137
0138 .. flat-table:: Decoder Commands
0139 :header-rows: 0
0140 :stub-columns: 0
0141 :widths: 56 6 113
0142
0143 * - ``V4L2_DEC_CMD_START``
0144 - 0
0145 - Start the decoder. When the decoder is already running or paused,
0146 this command will just change the playback speed. That means that
0147 calling ``V4L2_DEC_CMD_START`` when the decoder was paused will
0148 *not* resume the decoder. You have to explicitly call
0149 ``V4L2_DEC_CMD_RESUME`` for that. This command has one flag:
0150 ``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be
0151 muted when playing back at a non-standard speed.
0152
0153 For a device implementing the :ref:`decoder`, once the drain sequence
0154 is initiated with the ``V4L2_DEC_CMD_STOP`` command, it must be driven
0155 to completion before this command can be invoked. Any attempt to
0156 invoke the command while the drain sequence is in progress will trigger
0157 an ``EBUSY`` error code. The command may be also used to restart the
0158 decoder in case of an implicit stop initiated by the decoder itself,
0159 without the ``V4L2_DEC_CMD_STOP`` being called explicitly. See
0160 :ref:`decoder` for more details.
0161 * - ``V4L2_DEC_CMD_STOP``
0162 - 1
0163 - Stop the decoder. When the decoder is already stopped, this
0164 command does nothing. This command has two flags: if
0165 ``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set
0166 the picture to black after it stopped decoding. Otherwise the last
0167 image will repeat. If
0168 ``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops
0169 immediately (ignoring the ``pts`` value), otherwise it will keep
0170 decoding until timestamp >= pts or until the last of the pending
0171 data from its internal buffers was decoded.
0172
0173 For a device implementing the :ref:`decoder`, the command will initiate
0174 the drain sequence as documented in :ref:`decoder`. No flags or other
0175 arguments are accepted in this case. Any attempt to invoke the command
0176 again before the sequence completes will trigger an ``EBUSY`` error
0177 code.
0178 * - ``V4L2_DEC_CMD_PAUSE``
0179 - 2
0180 - Pause the decoder. When the decoder has not been started yet, the
0181 driver will return an ``EPERM`` error code. When the decoder is
0182 already paused, this command does nothing. This command has one
0183 flag: if ``V4L2_DEC_CMD_PAUSE_TO_BLACK`` is set, then set the
0184 decoder output to black when paused.
0185 * - ``V4L2_DEC_CMD_RESUME``
0186 - 3
0187 - Resume decoding after a PAUSE command. When the decoder has not
0188 been started yet, the driver will return an ``EPERM`` error code. When
0189 the decoder is already running, this command does nothing. No
0190 flags are defined for this command.
0191 * - ``V4L2_DEC_CMD_FLUSH``
0192 - 4
0193 - Flush any held capture buffers. Only valid for stateless decoders.
0194 This command is typically used when the application reached the
0195 end of the stream and the last output buffer had the
0196 ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` flag set. This would prevent
0197 dequeueing the capture buffer containing the last decoded frame.
0198 So this command can be used to explicitly flush that final decoded
0199 frame. This command does nothing if there are no held capture buffers.
0200
0201 Return Value
0202 ============
0203
0204 On success 0 is returned, on error -1 and the ``errno`` variable is set
0205 appropriately. The generic error codes are described at the
0206 :ref:`Generic Error Codes <gen-errors>` chapter.
0207
0208 EBUSY
0209 A drain sequence of a device implementing the :ref:`decoder` is still in
0210 progress. It is not allowed to issue another decoder command until it
0211 completes.
0212
0213 EINVAL
0214 The ``cmd`` field is invalid.
0215
0216 EPERM
0217 The application sent a PAUSE or RESUME command when the decoder was
0218 not running.
