Sending patches with SVG files via e-mail has a drawback: line
size could be bigger than 998, with is the limit given by
RFC 5322[1]. So, we need to enforce a lower limit, in order to
allow those patches to be properly reviewed.

[1] https://tools.ietf.org/html/rfc5322#section-2.1.1

So, use this small Perl script to limit columns size to ~900.

use Text::Wrap;
$Text::Wrap::columns = 900;

$t.=$_ while (<>);

print wrap("","",$t);
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Debian's ImageMagick is currently unable to decode those
images. Use scour to simplify the SVG, and provide only
one font type, in order to make it more palatable.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This file is too big, with cause it to require a lot
of memory when parsed by texlive.

Optimize it, in order to avoid the need of touching at
main_memory at texmf.cnf.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

VIDIOC_S_FMT may return EBUSY if the device is streaming or there are
buffers allocated. Document this.
Signed-off-by: NSakari Ailus <sakari.ailus@linux.intel.com>
Acked-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

...otherwise the PDF build fails when it can't find constraints.pdf.
Acked-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Unfortunately the use of 'type' was inconsistent for multiplanar
buffer types. Starting with 4.13 both the normal and _MPLANE variants
are allowed, thus making it possible to write sensible code.

Yes, we messed up :-(
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Reviewed-by: NSylwester Nawrocki <s.nawrocki@samsung.com>
Acked-by: NSakari Ailus <sakari.ailus@linux.intel.com>
[hans.verkuil@cisco.com: 4.14 -> 4.13 since this would go in for 4.13 after all]
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Elaborate the differences between V4L2_CID_GAIN and gain-type specific
V4L2_CID_DIGITAL_GAIN and V4L2_CID_ANALOGUE_GAIN.
Signed-off-by: NSakari Ailus <sakari.ailus@linux.intel.com>
Acked-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Add V4L2_CID_DIGITAL_GAIN to control explicitly digital gain.

We already have analogue gain control which the digital gain control
complements. Typically higher quality images are obtained using analogue
gain only as the digital gain does not add information to the image
(rather it may remove it).
Signed-off-by: NSakari Ailus <sakari.ailus@linux.intel.com>
Acked-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This patch adds documentation for the three new SDR formats

V4L2_SDR_FMT_PCU16BE
V4L2_SDR_FMT_PCU18BE
V4L2_SDR_FMT_PCU20BE
Signed-off-by: NRamesh Shanmugasundaram <ramesh.shanmugasundaram@bp.renesas.com>
Signed-off-by: NHans Verkuil <hansverk@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

V4L2_CID_EXPOSURE_BIAS does not exist, fix documentation.
Signed-off-by: NPavel Machek <pavel@ucw.cz>
Acked-by: NSakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The documentation incorrectly mentions MENU and INTEGER_MENU
at struct v4l2_querymenu table as if they were flags. They're
not: they're types.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Reviewed-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Remove spurious '-' in the VSP1 hgo table.

This resulted in a weird dot character that also caused
the row to be double-height.

We used to have it on other tables, but we got rid of them
on changeset 8ed29e30 ("[media] subdev-formats.rst: remove
spurious '-'").

Fixes: 14d66538 ("[media] v4l: Define a pixel format for the R-Car VSP1 1-D histogram engine")
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Remove spurious duplicate '-' in the Bayer Formats description. This resulted in a
weird dot character that also caused the row to be double-height.

The - character was probably used originally as indicator of an unused bit, but as the
number of columns was increased it was never used for the new columns.

Other tables do not use '-' either, so just remove it.
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Acked-by: NSakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Explain when the V4L2_CTRL_FLAG_MODIFY_LAYOUT and
V4L2_CTRL_FLAG_MODIFY_GRABBER flags should be used.
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Acked-by: NSakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Document this new control flag.
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Acked-by: NSakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The format is used on the R-Car VSP1 video queues that carry
2-D histogram statistics data.
Signed-off-by: NNiklas Söderlund <niklas.soderlund+renesas@ragnatech.se>
Reviewed-by: NLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Signed-off-by: NLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The format is used on the R-Car VSP1 video queues that carry
1-D histogram statistics data.
Signed-off-by: NLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Acked-by: NSakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The metadata buffer type is used to transfer metadata between userspace
and kernelspace through a V4L2 buffers queue. It comes with a new
metadata capture capability and format description.
Signed-off-by: NLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Tested-by: NGuennadi Liakhovetski <guennadi.liakhovetski@intel.com>
Acked-by: NSakari Ailus <sakari.ailus@linux.intel.com>
Acked-by: NHans Verkuil <hans.verkuil@cisco.com>
[hans.verkuil@cisco.com: removed left-over 'experimental' note]
[hans.verkuil@cisco.com: add newline after _v4l2-meta-format label]
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

V4L2 exposes parameters that influence buffers sizes through the format
ioctls (VIDIOC_G_FMT, VIDIOC_TRY_FMT, VIDIOC_S_FMT, and possibly
VIDIOC_G_SELECTION and VIDIOC_S_SELECTION). Other parameters not part of
the format structure may also influence buffer sizes or buffer layout in
general. One existing such parameter is rotation, which is implemented
by the V4L2_CID_ROTATE control and thus exposed through the V4L2 control
ioctls.

The interaction between those parameters and buffers is currently only
partially specified by the V4L2 API. In particular interactions between
controls and buffers isn't specified at all. The behaviour of the
VIDIOC_S_FMT and VIDIOC_S_SELECTION ioctls when buffers are allocated is
also not fully specified.

This patch clearly defines and documents the interactions between
formats, selections, controls and buffers.

The preparatory discussions for the documentation change considered
completely disallowing controls that change the buffer size or layout,
in favour of extending the format API with a new ioctl that would bundle
those controls with format information. The idea has been rejected, as
this would essentially be a restricted version of the upcoming request
API that wouldn't bring any additional value.

Another option we have considered was to mandate the use of the request
API to modify controls that influence buffer size or layout. This has
also been rejected on the grounds that requiring the request API to
change rotation even when streaming is stopped would significantly
complicate implementation of drivers and usage of the V4L2 API for
applications.

Applications will however be required to use the upcoming request API to
change at runtime formats or controls that influence the buffer size or
layout, because of the need to synchronize buffers with the formats and
controls. Otherwise there would be no way to interpret the content of a
buffer correctly.
Signed-off-by: NLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Acked-by: NSakari Ailus <sakari.ailus@linux.intel.com>
Acked-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The documentation for video capture and output devices claims that the video standard
ioctls are required. This is not the case, they are only required for PAL/NTSC/SECAM
type inputs and outputs. Sensors do not implement this at all and e.g. HDMI inputs
implement the DV Timings ioctls.

Just drop the mention of 'video standard' ioctls.
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Provide the frame structure and data layout of V4L2-PIX-FMT-INZI
format utilized by Intel SR300 Depth camera.
Signed-off-by: NEvgeni Raikhel <evgeni.raikhel@intel.com>
Acked-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The V4L2_INPUT_TYPE_CAMERA and V4L2_OUTPUT_TYPE_ANALOG descriptions were
hopelessly out of date. Fix this, and also fix a few style issues in these
documents. Finally add the missing documentation for V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY
(only used by the zoran driver).
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Add the line "Camera sensors are also considered to be a video input."

In practice all non-MC drivers for sensors support the input ioctls, and the
compliance test actually tests for the presence of these ioctls. So clarify
the documentation by explicitly mentioning sensors.
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Add documentation for added Bus Formats to describe RGB and YUV formats used
as input to the Synopsys DesignWare HDMI TX Controller.
Acked-by: NHans Verkuil <hans.verkuil@cisco.com>
Reviewed-by: NArchit Taneja <architt@codeaurora.org>
Acked-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NNeil Armstrong <narmstrong@baylibre.com>
Signed-off-by: NSean Paul <seanpaul@chromium.org>
Link: http://patchwork.freedesktop.org/patch/msgid/1491230558-10804-4-git-send-email-narmstrong@baylibre.com

The xvYCC601/709 encodings were mapped by default to full range quantization.
This is actually wrong since these encodings use limited range quantization,
but accept values outside of the limited range.

This makes sense since for values within the limited range it behaves exactly
the same as BT.601 or Rec. 709. The only difference is that with the xvYCC
encodings the values outside of the limited range also produce value colors.

Talking to people who know a lot more about this than I do made me realize
that mapping xvYCC to full range quantization was wrong, so this patch corrects
this and also improves the documentation.

These formats are very rare, and since the formula for decoding these Y'CbCr
encodings is actually fixed and independent of the quantization field value
it is safe to make this change.

The main advantage is that keeps the V4L2 specification in sync with the
corresponding colorspace, HDMI and CEA861 standards when it comes to these
xvYCC formats.
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Now that we have an extension to handle images, use it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The new picture_aspect, cea861_vic and hdmi_vic fields were not documented,
even though the corresponding flags were.

Add documentation for these new fields.
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This reverts 'commit 7e0739cd ("[media] videodev2.h: fix
sYCC/AdobeYCC default quantization range").

The problem is that many drivers can convert R'G'B' content (often
from sensors) to Y'CbCr, but they all produce limited range Y'CbCr.

To stay backwards compatible the default quantization range for
sRGB and AdobeRGB Y'CbCr encoding should be limited range, not full
range, even though the corresponding standards specify full range.

Update the V4L2_MAP_QUANTIZATION_DEFAULT define accordingly and
also update the documentation.

Fixes: 7e0739cd ("[media] videodev2.h: fix sYCC/AdobeYCC default quantization range")
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Cc: <stable@vger.kernel.org>      # for v4.9 and up
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Instead of keeping both SVG and graphviz files, dynamically
build SVG from its graphviz sources.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

SVG images are scalable, with makes easier to output on
different formats.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

bitmap images don't scale too well. So, replace it by a SVG
image, written in inkscape. I'm using the 2009's temporary
logo.svg image from 8032b526 ("linux.conf.au 2009: Tuz"),
with a Tasmanian Devil wearing a tux mask.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The pipeline image was produced from some dot file that has
long missed. Create a pipeline.dot with the graph and convert
it to SVG. As we're planning to add future support for graphviz
graphics, also store the .dot file on the tree, as this will
make easier when we add such Sphinx extension.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Instead of using bitmap images to show the zigzag macroblock
parsing, replace it by a SVG ones, with is scalable.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Use sans-serif font on all documents, split text lines,
ungroup elements, and do other misc cleanups, in order to make
all of them to look better, and to have smaller columns inside
their lines.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Using vectorial graphics provide a better visual. As those images
are originally using a vectorial graphics input at the pdf files,
use them, from an old media tree repository, converting them to SVG.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The documentation simply mentioned that one of the four pixel orders was
used in the example. Now specify the exact pixelformat instead.
Signed-off-by: NSakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The formats added by this patch are:

	V4L2_PIX_FMT_SBGGR16
	V4L2_PIX_FMT_SGBRG16
	V4L2_PIX_FMT_SGRBG16

V4L2_PIX_FMT_SRGGB16 already existed before the patch. Rework the
documentation to match that of the other sample depths.

Also align the description of V4L2_PIX_FMT_SRGGB16 to match with other
similar formats.
Signed-off-by: NSakari Ailus <sakari.ailus@linux.intel.com>
Acked-by: NLad, Prabhakar <prabhakar.csengg@gmail.com>
Signed-off-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Fix a typo on a word inside it.
Signed-off-by: NAndrea Gelmini <andrea.gelmini@gelma.net>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The SVG files are larger than the draw dimentions, have long
lines and aren't cleaned. Use inkscape to automatically fix
those issues.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The PDF files that contain media images were actually generated
offline from their SVG or PNG source files.

Sphinx can handle PNG sources automatially. So, let's just
drop their PDF counterparts.

For SVG, however, Sphinx doesn't produce the right tags to
use the TexLive SVG support. Also, the SVG support is done via
shell execution, with is not nice.

So, while we don't have any support for SVG inside Sphinx
core or as an extension, move the logic to build them to Makefile,
producing the PDF images on runtime.

NOTE: due to the way Sphinx works, the PDF images should be
generated inside the Kernel source tree, as otherwise Sphinx
won't find it, not obeying what's specified by "O=" makefile
parameter.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>