media: docs: move uAPI book to userspace-api/media

Since 2017, there is an space reserved for userspace API,
created by changeset 1d596dee3862 ("docs: Create a user-space API guide").

As the media subsystem was one of the first subsystems to use
Sphinx, until this patch, we were keeping things on a separate
place.

Let's just use the new location, as having all uAPI altogether
will likely make things easier for developers.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

1 files changed, 0 insertions, 362 deletions

diff --git a/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst b/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst
deleted file mode 100644
index 2d197e6bba8f..000000000000
--- a/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst
+++ /dev/null
@@ -1,362 +0,0 @@
-.. 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/media/uapi/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _VIDIOC_G_FBUF:
-
-**********************************
-ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
-**********************************
-
-Name
-====
-
-VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters
-
-
-Synopsis
-========
-
-.. c:function:: int ioctl( int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp )
-    :name: VIDIOC_G_FBUF
-
-.. c:function:: int ioctl( int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp )
-    :name: VIDIOC_S_FBUF
-
-
-Arguments
-=========
-
-``fd``
-    File descriptor returned by :ref:`open() <func-open>`.
-
-``argp``
-    Pointer to struct :c:type:`v4l2_framebuffer`.
-
-
-Description
-===========
-
-Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl
-to get and set the framebuffer parameters for a
-:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`
-(OSD). The type of overlay is implied by the device type (capture or
-output device) and can be determined with the
-:ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN``
-device must not support both kinds of overlay.
-
-The V4L2 API distinguishes destructive and non-destructive overlays. A
-destructive overlay copies captured video images into the video memory
-of a graphics card. A non-destructive overlay blends video images into a
-VGA signal or graphics into a video signal. *Video Output Overlays* are
-always non-destructive.
-
-To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
-ioctl with a pointer to a struct :c:type:`v4l2_framebuffer`
-structure. The driver fills all fields of the structure or returns an
-EINVAL error code when overlays are not supported.
-
-To set the parameters for a *Video Output Overlay*, applications must
-initialize the ``flags`` field of a struct
-:c:type:`v4l2_framebuffer`. Since the framebuffer is
-implemented on the TV card all other parameters are determined by the
-driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to
-this structure, the driver prepares for the overlay and returns the
-framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error
-code.
-
-To set the parameters for a *non-destructive Video Overlay*,
-applications must initialize the ``flags`` field, the ``fmt``
-substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for
-the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
-does, or it returns an error code.
-
-For a *destructive Video Overlay* applications must additionally provide
-a ``base`` address. Setting up a DMA to a random memory location can
-jeopardize the system security, its stability or even damage the
-hardware, therefore only the superuser can set the parameters for a
-destructive video overlay.
-
-
-.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
-
-.. c:type:: v4l2_framebuffer
-
-.. cssclass:: longtable
-
-.. flat-table:: struct v4l2_framebuffer
-    :header-rows:  0
-    :stub-columns: 0
-    :widths:       1 1 1 2
-
-    * - __u32
-      - ``capability``
-      -
-      - Overlay capability flags set by the driver, see
-	:ref:`framebuffer-cap`.
-    * - __u32
-      - ``flags``
-      -
-      - Overlay control flags set by application and driver, see
-	:ref:`framebuffer-flags`
-    * - void *
-      - ``base``
-      -
-      - Physical base address of the framebuffer, that is the address of
-	the pixel in the top left corner of the framebuffer. [#f1]_
-    * -
-      -
-      -
-      - This field is irrelevant to *non-destructive Video Overlays*. For
-	*destructive Video Overlays* applications must provide a base
-	address. The driver may accept only base addresses which are a
-	multiple of two, four or eight bytes. For *Video Output Overlays*
-	the driver must return a valid base address, so applications can
-	find the corresponding Linux framebuffer device (see
-	:ref:`osd`).
-    * - struct
-      - ``fmt``
-      -
-      - Layout of the frame buffer.
-    * -
-      - __u32
-      - ``width``
-      - Width of the frame buffer in pixels.
-    * -
-      - __u32
-      - ``height``
-      - Height of the frame buffer in pixels.
-    * -
-      - __u32
-      - ``pixelformat``
-      - The pixel format of the framebuffer.
-    * -
-      -
-      -
-      - For *non-destructive Video Overlays* this field only defines a
-	format for the struct :c:type:`v4l2_window`
-	``chromakey`` field.
-    * -
-      -
-      -
-      - For *destructive Video Overlays* applications must initialize this
-	field. For *Video Output Overlays* the driver must return a valid
-	format.
-    * -
-      -
-      -
-      - Usually this is an RGB format (for example
-	:ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
-	formats (only packed YUV formats when chroma keying is used, not
-	including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
-	``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
-	the driver when an application requests a compressed format is
-	undefined. See :ref:`pixfmt` for information on pixel formats.
-    * -
-      - enum :c:type:`v4l2_field`
-      - ``field``
-      - Drivers and applications shall ignore this field. If applicable,
-	the field order is selected with the
-	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
-	field of struct :c:type:`v4l2_window`.
-    * -
-      - __u32
-      - ``bytesperline``
-      - Distance in bytes between the leftmost pixels in two adjacent
-	lines.
-    * - :cspan:`3`
-
-	This field is irrelevant to *non-destructive Video Overlays*.
-
-	For *destructive Video Overlays* both applications and drivers can
-	set this field to request padding bytes at the end of each line.
-	Drivers however may ignore the requested value, returning
-	``width`` times bytes-per-pixel or a larger value required by the
-	hardware. That implies applications can just set this field to
-	zero to get a reasonable default.
-
-	For *Video Output Overlays* the driver must return a valid value.
-
-	Video hardware may access padding bytes, therefore they must
-	reside in accessible memory. Consider for example the case where
-	padding bytes after the last line of an image cross a system page
-	boundary. Capture devices may write padding bytes, the value is
-	undefined. Output devices ignore the contents of padding bytes.
-
-	When the image format is planar the ``bytesperline`` value applies
-	to the first plane and is divided by the same factor as the
-	``width`` field for the other planes. For example the Cb and Cr
-	planes of a YUV 4:2:0 image have half as many padding bytes
-	following each line as the Y plane. To avoid ambiguities drivers
-	must return a ``bytesperline`` value rounded up to a multiple of
-	the scale factor.
-    * -
-      - __u32
-      - ``sizeimage``
-      - This field is irrelevant to *non-destructive Video Overlays*. For
-	*destructive Video Overlays* applications must initialize this
-	field. For *Video Output Overlays* the driver must return a valid
-	format.
-
-	Together with ``base`` it defines the framebuffer memory
-	accessible by the driver.
-    * -
-      - enum :c:type:`v4l2_colorspace`
-      - ``colorspace``
-      - This information supplements the ``pixelformat`` and must be set
-	by the driver, see :ref:`colorspaces`.
-    * -
-      - __u32
-      - ``priv``
-      - Reserved. Drivers and applications must set this field to zero.
-
-
-.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
-
-.. _framebuffer-cap:
-
-.. flat-table:: Frame Buffer Capability Flags
-    :header-rows:  0
-    :stub-columns: 0
-    :widths:       3 1 4
-
-    * - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
-      - 0x0001
-      - The device is capable of non-destructive overlays. When the driver
-	clears this flag, only destructive overlays are supported. There
-	are no drivers yet which support both destructive and
-	non-destructive overlays. Video Output Overlays are in practice
-	always non-destructive.
-    * - ``V4L2_FBUF_CAP_CHROMAKEY``
-      - 0x0002
-      - The device supports clipping by chroma-keying the images. That is,
-	image pixels replace pixels in the VGA or video signal only where
-	the latter assume a certain color. Chroma-keying makes no sense
-	for destructive overlays.
-    * - ``V4L2_FBUF_CAP_LIST_CLIPPING``
-      - 0x0004
-      - The device supports clipping using a list of clip rectangles.
-    * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
-      - 0x0008
-      - The device supports clipping using a bit mask.
-    * - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
-      - 0x0010
-      - The device supports clipping/blending using the alpha channel of
-	the framebuffer or VGA signal. Alpha blending makes no sense for
-	destructive overlays.
-    * - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
-      - 0x0020
-      - The device supports alpha blending using a global alpha value.
-	Alpha blending makes no sense for destructive overlays.
-    * - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
-      - 0x0040
-      - The device supports clipping/blending using the inverted alpha
-	channel of the framebuffer or VGA signal. Alpha blending makes no
-	sense for destructive overlays.
-    * - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
-      - 0x0080
-      - The device supports Source Chroma-keying. Video pixels with the
-	chroma-key colors are replaced by framebuffer pixels, which is
-	exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
-
-
-.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
-
-.. _framebuffer-flags:
-
-.. cssclass:: longtable
-
-.. flat-table:: Frame Buffer Flags
-    :header-rows:  0
-    :stub-columns: 0
-    :widths:       3 1 4
-
-    * - ``V4L2_FBUF_FLAG_PRIMARY``
-      - 0x0001
-      - The framebuffer is the primary graphics surface. In other words,
-	the overlay is destructive. This flag is typically set by any
-	driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
-	capability and it is cleared otherwise.
-    * - ``V4L2_FBUF_FLAG_OVERLAY``
-      - 0x0002
-      - If this flag is set for a video capture device, then the driver
-	will set the initial overlay size to cover the full framebuffer
-	size, otherwise the existing overlay size (as set by
-	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
-	video capture driver (bttv) supports this flag. The use of this
-	flag for capture devices is deprecated. There is no way to detect
-	which drivers support this flag, so the only reliable method of
-	setting the overlay size is through
-	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
-	video output device, then the video output overlay window is
-	relative to the top-left corner of the framebuffer and restricted
-	to the size of the framebuffer. If it is cleared, then the video
-	output overlay window is relative to the video output display.
-    * - ``V4L2_FBUF_FLAG_CHROMAKEY``
-      - 0x0004
-      - Use chroma-keying. The chroma-key color is determined by the
-	``chromakey`` field of struct :c:type:`v4l2_window`
-	and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
-	ioctl, see :ref:`overlay` and :ref:`osd`.
-    * - :cspan:`2` There are no flags to enable clipping using a list of
-	clip rectangles or a bitmap. These methods are negotiated with the
-	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
-	and :ref:`osd`.
-    * - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
-      - 0x0008
-      - Use the alpha channel of the framebuffer to clip or blend
-	framebuffer pixels with video images. The blend function is:
-	output = framebuffer pixel * alpha + video pixel * (1 - alpha).
-	The actual alpha depth depends on the framebuffer pixel format.
-    * - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
-      - 0x0010
-      - Use a global alpha value to blend the framebuffer with video
-	images. The blend function is: output = (framebuffer pixel * alpha
-	+ video pixel * (255 - alpha)) / 255. The alpha value is
-	determined by the ``global_alpha`` field of struct
-	:c:type:`v4l2_window` and negotiated with the
-	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
-	and :ref:`osd`.
-    * - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
-      - 0x0020
-      - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
-	framebuffer to clip or blend framebuffer pixels with video images,
-	but with an inverted alpha value. The blend function is: output =
-	framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
-	alpha depth depends on the framebuffer pixel format.
-    * - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
-      - 0x0040
-      - Use source chroma-keying. The source chroma-key color is
-	determined by the ``chromakey`` field of struct
-	:c:type:`v4l2_window` and negotiated with the
-	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
-	and :ref:`osd`. Both chroma-keying are mutual exclusive to each
-	other, so same ``chromakey`` field of struct
-	:c:type:`v4l2_window` is being used.
-
-
-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.
-
-EPERM
-    :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to
-    negotiate the parameters for a destructive overlay.
-
-EINVAL
-    The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.
-
-.. [#f1]
-   A physical base address may not suit all platforms. GK notes in
-   theory we should pass something like PCI device + memory region +
-   offset instead. If you encounter problems please discuss on the
-   linux-media mailing list:
-   `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.