1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _VIDIOC_DECODER_CMD: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab************************************************ 754f38fcaSMauro Carvalho Chehabioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD 854f38fcaSMauro Carvalho Chehab************************************************ 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabName 1154f38fcaSMauro Carvalho Chehab==== 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabVIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - Execute an decoder command 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabSynopsis 1654f38fcaSMauro Carvalho Chehab======== 1754f38fcaSMauro Carvalho Chehab 18407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_DECODER_CMD 1954f38fcaSMauro Carvalho Chehab 20407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp)`` 2154f38fcaSMauro Carvalho Chehab 22407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_TRY_DECODER_CMD 2354f38fcaSMauro Carvalho Chehab 24407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *argp)`` 2554f38fcaSMauro Carvalho Chehab 2654f38fcaSMauro Carvalho ChehabArguments 2754f38fcaSMauro Carvalho Chehab========= 2854f38fcaSMauro Carvalho Chehab 2954f38fcaSMauro Carvalho Chehab``fd`` 30407e84cdSMauro Carvalho Chehab File descriptor returned by :c:func:`open()`. 3154f38fcaSMauro Carvalho Chehab 3254f38fcaSMauro Carvalho Chehab``argp`` 3354f38fcaSMauro Carvalho Chehab pointer to struct :c:type:`v4l2_decoder_cmd`. 3454f38fcaSMauro Carvalho Chehab 3554f38fcaSMauro Carvalho ChehabDescription 3654f38fcaSMauro Carvalho Chehab=========== 3754f38fcaSMauro Carvalho Chehab 3854f38fcaSMauro Carvalho ChehabThese ioctls control an audio/video (usually MPEG-) decoder. 3954f38fcaSMauro Carvalho Chehab``VIDIOC_DECODER_CMD`` sends a command to the decoder, 4054f38fcaSMauro Carvalho Chehab``VIDIOC_TRY_DECODER_CMD`` can be used to try a command without actually 4154f38fcaSMauro Carvalho Chehabexecuting it. To send a command applications must initialize all fields 4254f38fcaSMauro Carvalho Chehabof a struct :c:type:`v4l2_decoder_cmd` and call 4354f38fcaSMauro Carvalho Chehab``VIDIOC_DECODER_CMD`` or ``VIDIOC_TRY_DECODER_CMD`` with a pointer to 4454f38fcaSMauro Carvalho Chehabthis structure. 4554f38fcaSMauro Carvalho Chehab 4654f38fcaSMauro Carvalho ChehabThe ``cmd`` field must contain the command code. Some commands use the 4754f38fcaSMauro Carvalho Chehab``flags`` field for additional information. 4854f38fcaSMauro Carvalho Chehab 49407e84cdSMauro Carvalho ChehabA :c:func:`write()` or :ref:`VIDIOC_STREAMON` 5054f38fcaSMauro Carvalho Chehabcall sends an implicit START command to the decoder if it has not been 5154f38fcaSMauro Carvalho Chehabstarted yet. Applies to both queues of mem2mem decoders. 5254f38fcaSMauro Carvalho Chehab 53407e84cdSMauro Carvalho ChehabA :c:func:`close()` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` 5454f38fcaSMauro Carvalho Chehabcall of a streaming file descriptor sends an implicit immediate STOP 5554f38fcaSMauro Carvalho Chehabcommand to the decoder, and all buffered data is discarded. Applies to both 5654f38fcaSMauro Carvalho Chehabqueues of mem2mem decoders. 5754f38fcaSMauro Carvalho Chehab 5854f38fcaSMauro Carvalho ChehabIn principle, these ioctls are optional, not all drivers may support them. They were 5954f38fcaSMauro Carvalho Chehabintroduced in Linux 3.3. They are, however, mandatory for stateful mem2mem decoders 6054f38fcaSMauro Carvalho Chehab(as further documented in :ref:`decoder`). 6154f38fcaSMauro Carvalho Chehab 62fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{2.0cm}|p{1.1cm}|p{2.2cm}|p{11.8cm}| 6354f38fcaSMauro Carvalho Chehab 6454f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_decoder_cmd 6554f38fcaSMauro Carvalho Chehab 6654f38fcaSMauro Carvalho Chehab.. cssclass:: longtable 6754f38fcaSMauro Carvalho Chehab 6854f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_decoder_cmd 6954f38fcaSMauro Carvalho Chehab :header-rows: 0 7054f38fcaSMauro Carvalho Chehab :stub-columns: 0 7154f38fcaSMauro Carvalho Chehab :widths: 1 1 1 3 7254f38fcaSMauro Carvalho Chehab 7354f38fcaSMauro Carvalho Chehab * - __u32 7454f38fcaSMauro Carvalho Chehab - ``cmd`` 7554f38fcaSMauro Carvalho Chehab - 7654f38fcaSMauro Carvalho Chehab - The decoder command, see :ref:`decoder-cmds`. 7754f38fcaSMauro Carvalho Chehab * - __u32 7854f38fcaSMauro Carvalho Chehab - ``flags`` 7954f38fcaSMauro Carvalho Chehab - 8054f38fcaSMauro Carvalho Chehab - Flags to go with the command. If no flags are defined for this 8154f38fcaSMauro Carvalho Chehab command, drivers and applications must set this field to zero. 8254f38fcaSMauro Carvalho Chehab * - union { 8354f38fcaSMauro Carvalho Chehab - (anonymous) 8454f38fcaSMauro Carvalho Chehab * - struct 8554f38fcaSMauro Carvalho Chehab - ``start`` 8654f38fcaSMauro Carvalho Chehab - 8754f38fcaSMauro Carvalho Chehab - Structure containing additional data for the 8854f38fcaSMauro Carvalho Chehab ``V4L2_DEC_CMD_START`` command. 8954f38fcaSMauro Carvalho Chehab * - 9054f38fcaSMauro Carvalho Chehab - __s32 9154f38fcaSMauro Carvalho Chehab - ``speed`` 9254f38fcaSMauro Carvalho Chehab - Playback speed and direction. The playback speed is defined as 9354f38fcaSMauro Carvalho Chehab ``speed``/1000 of the normal speed. So 1000 is normal playback. 9454f38fcaSMauro Carvalho Chehab Negative numbers denote reverse playback, so -1000 does reverse 9554f38fcaSMauro Carvalho Chehab playback at normal speed. Speeds -1, 0 and 1 have special 9654f38fcaSMauro Carvalho Chehab meanings: speed 0 is shorthand for 1000 (normal playback). A speed 9754f38fcaSMauro Carvalho Chehab of 1 steps just one frame forward, a speed of -1 steps just one 9854f38fcaSMauro Carvalho Chehab frame back. 9954f38fcaSMauro Carvalho Chehab * - 10054f38fcaSMauro Carvalho Chehab - __u32 10154f38fcaSMauro Carvalho Chehab - ``format`` 10254f38fcaSMauro Carvalho Chehab - Format restrictions. This field is set by the driver, not the 10354f38fcaSMauro Carvalho Chehab application. Possible values are ``V4L2_DEC_START_FMT_NONE`` if 10454f38fcaSMauro Carvalho Chehab there are no format restrictions or ``V4L2_DEC_START_FMT_GOP`` if 10554f38fcaSMauro Carvalho Chehab the decoder operates on full GOPs (*Group Of Pictures*). This is 10654f38fcaSMauro Carvalho Chehab usually the case for reverse playback: the decoder needs full 10754f38fcaSMauro Carvalho Chehab GOPs, which it can then play in reverse order. So to implement 10854f38fcaSMauro Carvalho Chehab reverse playback the application must feed the decoder the last 10954f38fcaSMauro Carvalho Chehab GOP in the video file, then the GOP before that, etc. etc. 11054f38fcaSMauro Carvalho Chehab * - struct 11154f38fcaSMauro Carvalho Chehab - ``stop`` 11254f38fcaSMauro Carvalho Chehab - 11354f38fcaSMauro Carvalho Chehab - Structure containing additional data for the ``V4L2_DEC_CMD_STOP`` 11454f38fcaSMauro Carvalho Chehab command. 11554f38fcaSMauro Carvalho Chehab * - 11654f38fcaSMauro Carvalho Chehab - __u64 11754f38fcaSMauro Carvalho Chehab - ``pts`` 11854f38fcaSMauro Carvalho Chehab - Stop playback at this ``pts`` or immediately if the playback is 11954f38fcaSMauro Carvalho Chehab already past that timestamp. Leave to 0 if you want to stop after 12054f38fcaSMauro Carvalho Chehab the last frame was decoded. 12154f38fcaSMauro Carvalho Chehab * - struct 12254f38fcaSMauro Carvalho Chehab - ``raw`` 12354f38fcaSMauro Carvalho Chehab * - 12454f38fcaSMauro Carvalho Chehab - __u32 12554f38fcaSMauro Carvalho Chehab - ``data``\ [16] 12654f38fcaSMauro Carvalho Chehab - Reserved for future extensions. Drivers and applications must set 12754f38fcaSMauro Carvalho Chehab the array to zero. 12854f38fcaSMauro Carvalho Chehab * - } 12954f38fcaSMauro Carvalho Chehab - 13054f38fcaSMauro Carvalho Chehab 13154f38fcaSMauro Carvalho Chehab 132fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{5.6cm}|p{0.6cm}|p{11.1cm}| 133fea13a69SMauro Carvalho Chehab 134fea13a69SMauro Carvalho Chehab.. cssclass:: longtable 135fea13a69SMauro Carvalho Chehab 136*c4a1bff9SMauro Carvalho Chehab.. _decoder-cmds: 137*c4a1bff9SMauro Carvalho Chehab 13854f38fcaSMauro Carvalho Chehab.. flat-table:: Decoder Commands 13954f38fcaSMauro Carvalho Chehab :header-rows: 0 14054f38fcaSMauro Carvalho Chehab :stub-columns: 0 14154f38fcaSMauro Carvalho Chehab :widths: 56 6 113 14254f38fcaSMauro Carvalho Chehab 14354f38fcaSMauro Carvalho Chehab * - ``V4L2_DEC_CMD_START`` 14454f38fcaSMauro Carvalho Chehab - 0 14554f38fcaSMauro Carvalho Chehab - Start the decoder. When the decoder is already running or paused, 14654f38fcaSMauro Carvalho Chehab this command will just change the playback speed. That means that 14754f38fcaSMauro Carvalho Chehab calling ``V4L2_DEC_CMD_START`` when the decoder was paused will 14854f38fcaSMauro Carvalho Chehab *not* resume the decoder. You have to explicitly call 14954f38fcaSMauro Carvalho Chehab ``V4L2_DEC_CMD_RESUME`` for that. This command has one flag: 15054f38fcaSMauro Carvalho Chehab ``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be 15154f38fcaSMauro Carvalho Chehab muted when playing back at a non-standard speed. 15254f38fcaSMauro Carvalho Chehab 15354f38fcaSMauro Carvalho Chehab For a device implementing the :ref:`decoder`, once the drain sequence 15454f38fcaSMauro Carvalho Chehab is initiated with the ``V4L2_DEC_CMD_STOP`` command, it must be driven 15554f38fcaSMauro Carvalho Chehab to completion before this command can be invoked. Any attempt to 15654f38fcaSMauro Carvalho Chehab invoke the command while the drain sequence is in progress will trigger 15754f38fcaSMauro Carvalho Chehab an ``EBUSY`` error code. The command may be also used to restart the 15854f38fcaSMauro Carvalho Chehab decoder in case of an implicit stop initiated by the decoder itself, 15954f38fcaSMauro Carvalho Chehab without the ``V4L2_DEC_CMD_STOP`` being called explicitly. See 16054f38fcaSMauro Carvalho Chehab :ref:`decoder` for more details. 16154f38fcaSMauro Carvalho Chehab * - ``V4L2_DEC_CMD_STOP`` 16254f38fcaSMauro Carvalho Chehab - 1 16354f38fcaSMauro Carvalho Chehab - Stop the decoder. When the decoder is already stopped, this 16454f38fcaSMauro Carvalho Chehab command does nothing. This command has two flags: if 16554f38fcaSMauro Carvalho Chehab ``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set 16654f38fcaSMauro Carvalho Chehab the picture to black after it stopped decoding. Otherwise the last 16754f38fcaSMauro Carvalho Chehab image will repeat. If 16854f38fcaSMauro Carvalho Chehab ``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops 16954f38fcaSMauro Carvalho Chehab immediately (ignoring the ``pts`` value), otherwise it will keep 17054f38fcaSMauro Carvalho Chehab decoding until timestamp >= pts or until the last of the pending 17154f38fcaSMauro Carvalho Chehab data from its internal buffers was decoded. 17254f38fcaSMauro Carvalho Chehab 17354f38fcaSMauro Carvalho Chehab For a device implementing the :ref:`decoder`, the command will initiate 17454f38fcaSMauro Carvalho Chehab the drain sequence as documented in :ref:`decoder`. No flags or other 17554f38fcaSMauro Carvalho Chehab arguments are accepted in this case. Any attempt to invoke the command 17654f38fcaSMauro Carvalho Chehab again before the sequence completes will trigger an ``EBUSY`` error 17754f38fcaSMauro Carvalho Chehab code. 17854f38fcaSMauro Carvalho Chehab * - ``V4L2_DEC_CMD_PAUSE`` 17954f38fcaSMauro Carvalho Chehab - 2 18054f38fcaSMauro Carvalho Chehab - Pause the decoder. When the decoder has not been started yet, the 18154f38fcaSMauro Carvalho Chehab driver will return an ``EPERM`` error code. When the decoder is 18254f38fcaSMauro Carvalho Chehab already paused, this command does nothing. This command has one 18354f38fcaSMauro Carvalho Chehab flag: if ``V4L2_DEC_CMD_PAUSE_TO_BLACK`` is set, then set the 18454f38fcaSMauro Carvalho Chehab decoder output to black when paused. 18554f38fcaSMauro Carvalho Chehab * - ``V4L2_DEC_CMD_RESUME`` 18654f38fcaSMauro Carvalho Chehab - 3 18754f38fcaSMauro Carvalho Chehab - Resume decoding after a PAUSE command. When the decoder has not 18854f38fcaSMauro Carvalho Chehab been started yet, the driver will return an ``EPERM`` error code. When 18954f38fcaSMauro Carvalho Chehab the decoder is already running, this command does nothing. No 19054f38fcaSMauro Carvalho Chehab flags are defined for this command. 19154f38fcaSMauro Carvalho Chehab * - ``V4L2_DEC_CMD_FLUSH`` 19254f38fcaSMauro Carvalho Chehab - 4 19354f38fcaSMauro Carvalho Chehab - Flush any held capture buffers. Only valid for stateless decoders. 19454f38fcaSMauro Carvalho Chehab This command is typically used when the application reached the 19554f38fcaSMauro Carvalho Chehab end of the stream and the last output buffer had the 19654f38fcaSMauro Carvalho Chehab ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` flag set. This would prevent 19754f38fcaSMauro Carvalho Chehab dequeueing the capture buffer containing the last decoded frame. 19854f38fcaSMauro Carvalho Chehab So this command can be used to explicitly flush that final decoded 19954f38fcaSMauro Carvalho Chehab frame. This command does nothing if there are no held capture buffers. 20054f38fcaSMauro Carvalho Chehab 20154f38fcaSMauro Carvalho ChehabReturn Value 20254f38fcaSMauro Carvalho Chehab============ 20354f38fcaSMauro Carvalho Chehab 20454f38fcaSMauro Carvalho ChehabOn success 0 is returned, on error -1 and the ``errno`` variable is set 20554f38fcaSMauro Carvalho Chehabappropriately. The generic error codes are described at the 20654f38fcaSMauro Carvalho Chehab:ref:`Generic Error Codes <gen-errors>` chapter. 20754f38fcaSMauro Carvalho Chehab 20854f38fcaSMauro Carvalho ChehabEBUSY 20954f38fcaSMauro Carvalho Chehab A drain sequence of a device implementing the :ref:`decoder` is still in 21054f38fcaSMauro Carvalho Chehab progress. It is not allowed to issue another decoder command until it 21154f38fcaSMauro Carvalho Chehab completes. 21254f38fcaSMauro Carvalho Chehab 21354f38fcaSMauro Carvalho ChehabEINVAL 21454f38fcaSMauro Carvalho Chehab The ``cmd`` field is invalid. 21554f38fcaSMauro Carvalho Chehab 21654f38fcaSMauro Carvalho ChehabEPERM 21754f38fcaSMauro Carvalho Chehab The application sent a PAUSE or RESUME command when the decoder was 21854f38fcaSMauro Carvalho Chehab not running. 219