diff options
Diffstat (limited to 'Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst')
| -rw-r--r-- | Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst new file mode 100644 index 000000000000..7986a248bff9 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst @@ -0,0 +1,226 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _VIDIOC_DECODER_CMD: + +************************************************ +ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD +************************************************ + +Name +==== + +VIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - Execute an decoder command + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp ) + :name: VIDIOC_DECODER_CMD + + +.. c:function:: int ioctl( int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *argp ) + :name: VIDIOC_TRY_DECODER_CMD + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <func-open>`. + +``argp`` + pointer to struct :c:type:`v4l2_decoder_cmd`. + + +Description +=========== + +These ioctls control an audio/video (usually MPEG-) decoder. +``VIDIOC_DECODER_CMD`` sends a command to the decoder, +``VIDIOC_TRY_DECODER_CMD`` can be used to try a command without actually +executing it. To send a command applications must initialize all fields +of a struct :c:type:`v4l2_decoder_cmd` and call +``VIDIOC_DECODER_CMD`` or ``VIDIOC_TRY_DECODER_CMD`` with a pointer to +this structure. + +The ``cmd`` field must contain the command code. Some commands use the +``flags`` field for additional information. + +A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON` +call sends an implicit START command to the decoder if it has not been +started yet. Applies to both queues of mem2mem decoders. + +A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` +call of a streaming file descriptor sends an implicit immediate STOP +command to the decoder, and all buffered data is discarded. Applies to both +queues of mem2mem decoders. + +In principle, these ioctls are optional, not all drivers may support them. They were +introduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decoders +(as further documented in :ref:`decoder`). + + +.. tabularcolumns:: |p{1.1cm}|p{2.4cm}|p{1.2cm}|p{1.6cm}|p{10.6cm}| + +.. c:type:: v4l2_decoder_cmd + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_decoder_cmd + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 3 + + * - __u32 + - ``cmd`` + - + - The decoder command, see :ref:`decoder-cmds`. + * - __u32 + - ``flags`` + - + - Flags to go with the command. If no flags are defined for this + command, drivers and applications must set this field to zero. + * - union { + - (anonymous) + * - struct + - ``start`` + - + - Structure containing additional data for the + ``V4L2_DEC_CMD_START`` command. + * - + - __s32 + - ``speed`` + - Playback speed and direction. The playback speed is defined as + ``speed``/1000 of the normal speed. So 1000 is normal playback. + Negative numbers denote reverse playback, so -1000 does reverse + playback at normal speed. Speeds -1, 0 and 1 have special + meanings: speed 0 is shorthand for 1000 (normal playback). A speed + of 1 steps just one frame forward, a speed of -1 steps just one + frame back. + * - + - __u32 + - ``format`` + - Format restrictions. This field is set by the driver, not the + application. Possible values are ``V4L2_DEC_START_FMT_NONE`` if + there are no format restrictions or ``V4L2_DEC_START_FMT_GOP`` if + the decoder operates on full GOPs (*Group Of Pictures*). This is + usually the case for reverse playback: the decoder needs full + GOPs, which it can then play in reverse order. So to implement + reverse playback the application must feed the decoder the last + GOP in the video file, then the GOP before that, etc. etc. + * - struct + - ``stop`` + - + - Structure containing additional data for the ``V4L2_DEC_CMD_STOP`` + command. + * - + - __u64 + - ``pts`` + - Stop playback at this ``pts`` or immediately if the playback is + already past that timestamp. Leave to 0 if you want to stop after + the last frame was decoded. + * - struct + - ``raw`` + * - + - __u32 + - ``data``\ [16] + - Reserved for future extensions. Drivers and applications must set + the array to zero. + * - } + - + + + +.. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.3cm}| + +.. _decoder-cmds: + +.. flat-table:: Decoder Commands + :header-rows: 0 + :stub-columns: 0 + :widths: 56 6 113 + + * - ``V4L2_DEC_CMD_START`` + - 0 + - Start the decoder. When the decoder is already running or paused, + this command will just change the playback speed. That means that + calling ``V4L2_DEC_CMD_START`` when the decoder was paused will + *not* resume the decoder. You have to explicitly call + ``V4L2_DEC_CMD_RESUME`` for that. This command has one flag: + ``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be + muted when playing back at a non-standard speed. + + For a device implementing the :ref:`decoder`, once the drain sequence + is initiated with the ``V4L2_DEC_CMD_STOP`` command, it must be driven + to completion before this command can be invoked. Any attempt to + invoke the command while the drain sequence is in progress will trigger + an ``EBUSY`` error code. The command may be also used to restart the + decoder in case of an implicit stop initiated by the decoder itself, + without the ``V4L2_DEC_CMD_STOP`` being called explicitly. See + :ref:`decoder` for more details. + * - ``V4L2_DEC_CMD_STOP`` + - 1 + - Stop the decoder. When the decoder is already stopped, this + command does nothing. This command has two flags: if + ``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set + the picture to black after it stopped decoding. Otherwise the last + image will repeat. If + ``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops + immediately (ignoring the ``pts`` value), otherwise it will keep + decoding until timestamp >= pts or until the last of the pending + data from its internal buffers was decoded. + + For a device implementing the :ref:`decoder`, the command will initiate + the drain sequence as documented in :ref:`decoder`. No flags or other + arguments are accepted in this case. Any attempt to invoke the command + again before the sequence completes will trigger an ``EBUSY`` error + code. + * - ``V4L2_DEC_CMD_PAUSE`` + - 2 + - Pause the decoder. When the decoder has not been started yet, the + driver will return an ``EPERM`` error code. When the decoder is + already paused, this command does nothing. This command has one + flag: if ``V4L2_DEC_CMD_PAUSE_TO_BLACK`` is set, then set the + decoder output to black when paused. + * - ``V4L2_DEC_CMD_RESUME`` + - 3 + - Resume decoding after a PAUSE command. When the decoder has not + been started yet, the driver will return an ``EPERM`` error code. When + the decoder is already running, this command does nothing. No + flags are defined for this command. + * - ``V4L2_DEC_CMD_FLUSH`` + - 4 + - Flush any held capture buffers. Only valid for stateless decoders. + This command is typically used when the application reached the + end of the stream and the last output buffer had the + ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` flag set. This would prevent + dequeueing the capture buffer containing the last decoded frame. + So this command can be used to explicitly flush that final decoded + frame. This command does nothing if there are no held capture buffers. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EBUSY + A drain sequence of a device implementing the :ref:`decoder` is still in + progress. It is not allowed to issue another decoder command until it + completes. + +EINVAL + The ``cmd`` field is invalid. + +EPERM + The application sent a PAUSE or RESUME command when the decoder was + not running. |