doc-rst: linux_tv DocBook to reST migration (docs-next)

This is the restructuredText (reST) migration of the ``media``
DocBook-XML set from the linux_tv project.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

1 files changed, 204 insertions, 0 deletions

diff --git a/Documentation/linux_tv/media/v4l/vidioc-encoder-cmd.rst b/Documentation/linux_tv/media/v4l/vidioc-encoder-cmd.rst
new file mode 100644
index 0000000..018f31e
--- /dev/null
+++ b/Documentation/linux_tv/media/v4l/vidioc-encoder-cmd.rst
@@ -0,0 +1,204 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _vidioc-encoder-cmd:
+
+************************************************
+ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
+************************************************
+
+*man VIDIOC_ENCODER_CMD(2)*
+
+VIDIOC_TRY_ENCODER_CMD
+Execute an encoder command
+
+
+Synopsis
+========
+
+.. c:function:: int ioctl( int fd, int request, struct v4l2_encoder_cmd *argp )
+
+Arguments
+=========
+
+``fd``
+    File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+    VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
+
+``argp``
+
+
+Description
+===========
+
+These ioctls control an audio/video (usually MPEG-) encoder.
+``VIDIOC_ENCODER_CMD`` sends a command to the encoder,
+``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually
+executing it.
+
+To send a command applications must initialize all fields of a struct
+:ref:`v4l2_encoder_cmd <v4l2-encoder-cmd>` and call
+``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to
+this structure.
+
+The ``cmd`` field must contain the command code. The ``flags`` field is
+currently only used by the STOP command and contains one bit: If the
+``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue
+until the end of the current *Group Of Pictures*, otherwise it will stop
+immediately.
+
+A :c:func:`read()`() or :ref:`VIDIOC_STREAMON <vidioc-streamon>`
+call sends an implicit START command to the encoder if it has not been
+started yet. After a STOP command, :c:func:`read()`() calls will read
+the remaining data buffered by the driver. When the buffer is empty,
+:c:func:`read()`() will return zero and the next :c:func:`read()`()
+call will restart the encoder.
+
+A :c:func:`close()`() or :ref:`VIDIOC_STREAMOFF <vidioc-streamon>`
+call of a streaming file descriptor sends an implicit immediate STOP to
+the encoder, and all buffered data is discarded.
+
+These ioctls are optional, not all drivers may support them. They were
+introduced in Linux 2.6.21.
+
+
+.. _v4l2-encoder-cmd:
+
+.. flat-table:: struct v4l2_encoder_cmd
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       1 1 2
+
+
+    -  .. row 1
+
+       -  __u32
+
+       -  ``cmd``
+
+       -  The encoder command, see :ref:`encoder-cmds`.
+
+    -  .. row 2
+
+       -  __u32
+
+       -  ``flags``
+
+       -  Flags to go with the command, see :ref:`encoder-flags`. If no
+          flags are defined for this command, drivers and applications must
+          set this field to zero.
+
+    -  .. row 3
+
+       -  __u32
+
+       -  ``data``\ [8]
+
+       -  Reserved for future extensions. Drivers and applications must set
+          the array to zero.
+
+
+
+.. _encoder-cmds:
+
+.. flat-table:: Encoder Commands
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       3 1 4
+
+
+    -  .. row 1
+
+       -  ``V4L2_ENC_CMD_START``
+
+       -  0
+
+       -  Start the encoder. When the encoder is already running or paused,
+          this command does nothing. No flags are defined for this command.
+
+    -  .. row 2
+
+       -  ``V4L2_ENC_CMD_STOP``
+
+       -  1
+
+       -  Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag
+          is set, encoding will continue until the end of the current *Group
+          Of Pictures*, otherwise encoding will stop immediately. When the
+          encoder is already stopped, this command does nothing. mem2mem
+          encoders will send a ``V4L2_EVENT_EOS`` event when the last frame
+          has been encoded and all frames are ready to be dequeued and will
+          set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of
+          the capture queue to indicate there will be no new buffers
+          produced to dequeue. This buffer may be empty, indicated by the
+          driver setting the ``bytesused`` field to 0. Once the
+          ``V4L2_BUF_FLAG_LAST`` flag was set, the
+          :ref:`VIDIOC_DQBUF <vidioc-qbuf>` ioctl will not block anymore,
+          but return an EPIPE error code.
+
+    -  .. row 3
+
+       -  ``V4L2_ENC_CMD_PAUSE``
+
+       -  2
+
+       -  Pause the encoder. When the encoder has not been started yet, the
+          driver will return an EPERM error code. When the encoder is
+          already paused, this command does nothing. No flags are defined
+          for this command.
+
+    -  .. row 4
+
+       -  ``V4L2_ENC_CMD_RESUME``
+
+       -  3
+
+       -  Resume encoding after a PAUSE command. When the encoder has not
+          been started yet, the driver will return an EPERM error code. When
+          the encoder is already running, this command does nothing. No
+          flags are defined for this command.
+
+
+
+.. _encoder-flags:
+
+.. flat-table:: Encoder Command Flags
+    :header-rows:  0
+    :stub-columns: 0
+    :widths:       3 1 4
+
+
+    -  .. row 1
+
+       -  ``V4L2_ENC_CMD_STOP_AT_GOP_END``
+
+       -  0x0001
+
+       -  Stop encoding at the end of the current *Group Of Pictures*,
+          rather than immediately.
+
+
+
+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.
+
+EINVAL
+    The ``cmd`` field is invalid.
+
+EPERM
+    The application sent a PAUSE or RESUME command when the encoder was
+    not running.
+
+
+.. ------------------------------------------------------------------------------
+.. This file was automatically converted from DocBook-XML with the dbxml
+.. library (https://github.com/return42/sphkerneldoc). The origin XML comes
+.. from the linux kernel, refer to:
+..
+.. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook
+.. ------------------------------------------------------------------------------