[media] doc-rst: improve display of notes and warnings
There are several notes and warning mesages in the middle of
the media docbook. Use the ReST tags for that, as it makes
them visually better and hightlights them.
While here, modify a few ones to make them clearer.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
diff --git a/Documentation/media/uapi/v4l/audio.rst b/Documentation/media/uapi/v4l/audio.rst
index 47f8334..cd30573 100644
--- a/Documentation/media/uapi/v4l/audio.rst
+++ b/Documentation/media/uapi/v4l/audio.rst
@@ -35,11 +35,12 @@
The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
:ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current
-audio input and output, respectively. Note that, unlike
-:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
-:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a
-structure as :ref:`VIDIOC_ENUMAUDIO` and
-:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index.
+audio input and output, respectively.
+
+.. note:: Note that, unlike :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
+ :ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a
+ structure as :ref:`VIDIOC_ENUMAUDIO` and
+ :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index.
To select an audio input and change its properties applications call the
:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio
diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst
index b195eb5..16cdd8e 100644
--- a/Documentation/media/uapi/v4l/buffer.rst
+++ b/Documentation/media/uapi/v4l/buffer.rst
@@ -166,11 +166,11 @@
output device because the application did not pass new data in
time.
- Note this may count the frames received e.g. over USB, without
- taking into account the frames dropped by the remote hardware due
- to limited compression throughput or bus bandwidth. These devices
- identify by not enumerating any video standards, see
- :ref:`standard`.
+ .. note:: This may count the frames received e.g. over USB, without
+ taking into account the frames dropped by the remote hardware due
+ to limited compression throughput or bus bandwidth. These devices
+ identify by not enumerating any video standards, see
+ :ref:`standard`.
- .. row 10
@@ -297,8 +297,10 @@
stream, applications when it refers to an output stream. If the
application sets this to 0 for an output stream, then
``bytesused`` will be set to the size of the plane (see the
- ``length`` field of this struct) by the driver. Note that the
- actual image data starts at ``data_offset`` which may not be 0.
+ ``length`` field of this struct) by the driver.
+
+ .. note:: Note that the actual image data starts at ``data_offset``
+ which may not be 0.
- .. row 2
@@ -367,10 +369,11 @@
-
- Offset in bytes to video data in the plane. Drivers must set this
field when ``type`` refers to a capture stream, applications when
- it refers to an output stream. Note that data_offset is included
- in ``bytesused``. So the size of the image in the plane is
- ``bytesused``-``data_offset`` at offset ``data_offset`` from the
- start of the plane.
+ it refers to an output stream.
+
+ .. note:: That data_offset is included in ``bytesused``. So the
+ size of the image in the plane is ``bytesused``-``data_offset``
+ at offset ``data_offset`` from the start of the plane.
- .. row 8
diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst
index 51b1949..0913822 100644
--- a/Documentation/media/uapi/v4l/crop.rst
+++ b/Documentation/media/uapi/v4l/crop.rst
@@ -15,9 +15,9 @@
Applications can use the following API to select an area in the video
signal, query the default area and the hardware limits.
-**NOTE**: Despite their name, the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`,
-:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP
-<VIDIOC_G_CROP>` ioctls apply to input as well as output devices.
+.. note:: Despite their name, the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`,
+ :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP
+ <VIDIOC_G_CROP>` ioctls apply to input as well as output devices.
Scaling requires a source and a target. On a video capture or overlay
device the source is the video signal, and the cropping ioctls determine
@@ -38,9 +38,9 @@
:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctls. Their size (and position
where applicable) will be fixed in this case.
-**NOTE:** All capture and output devices must support the
-:ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl such that applications can
-determine if scaling takes place.
+.. note:: All capture and output devices must support the
+ :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl such that applications
+ can determine if scaling takes place.
Cropping Structures
@@ -144,8 +144,8 @@
work without special preparations. More advanced applications should
ensure the parameters are suitable before starting I/O.
-**NOTE:** on the next two examples, a video capture device is assumed;
-change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device.
+.. note:: On the next two examples, a video capture device is assumed;
+ change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device.
Example: Resetting the cropping parameters
==========================================
@@ -207,7 +207,7 @@
Example: Selecting an output area
=================================
-**NOTE:** This example assumes an output device.
+.. note:: This example assumes an output device.
.. code-block:: c
@@ -246,7 +246,7 @@
Example: Current scaling factor and pixel aspect
================================================
-**NOTE:** This example assumes a video capture device.
+.. note:: This example assumes a video capture device.
.. code-block:: c
diff --git a/Documentation/media/uapi/v4l/dev-capture.rst b/Documentation/media/uapi/v4l/dev-capture.rst
index 16030a8..8d04947 100644
--- a/Documentation/media/uapi/v4l/dev-capture.rst
+++ b/Documentation/media/uapi/v4l/dev-capture.rst
@@ -15,7 +15,9 @@
device special files named ``/dev/video`` and ``/dev/video0`` to
``/dev/video63`` with major number 81 and minor numbers 0 to 63.
``/dev/video`` is typically a symbolic link to the preferred video
-device. Note the same device files are used for video output devices.
+device.
+
+.. note:: The same device file names are used for video output devices.
Querying Capabilities
diff --git a/Documentation/media/uapi/v4l/dev-codec.rst b/Documentation/media/uapi/v4l/dev-codec.rst
index 7fd28d0..dfb2032 100644
--- a/Documentation/media/uapi/v4l/dev-codec.rst
+++ b/Documentation/media/uapi/v4l/dev-codec.rst
@@ -19,8 +19,10 @@
for both capture and output to start the codec.
Video compression codecs use the MPEG controls to setup their codec
-parameters (note that the MPEG controls actually support many more
-codecs than just MPEG). See :ref:`mpeg-controls`.
+parameters
+
+.. note:: The MPEG controls actually support many more codecs than
+ just MPEG. See :ref:`mpeg-controls`.
Memory-to-memory devices can often be used as a shared resource: you can
open the video node multiple times, each application setting up their
diff --git a/Documentation/media/uapi/v4l/dev-effect.rst b/Documentation/media/uapi/v4l/dev-effect.rst
index be4de3b..b946cc9 100644
--- a/Documentation/media/uapi/v4l/dev-effect.rst
+++ b/Documentation/media/uapi/v4l/dev-effect.rst
@@ -6,11 +6,10 @@
Effect Devices Interface
************************
- **Note**
-
- This interface has been be suspended from the V4L2 API implemented
- in Linux 2.6 until we have more experience with effect device
- interfaces.
+.. note::
+ This interface has been be suspended from the V4L2 API.
+ The implementation for such effects should be done
+ via mem2mem devices.
A V4L2 video effect device can do image effects, filtering, or combine
two or more images or image streams. For example video transitions or
diff --git a/Documentation/media/uapi/v4l/dev-osd.rst b/Documentation/media/uapi/v4l/dev-osd.rst
index 98570ce..fadda13 100644
--- a/Documentation/media/uapi/v4l/dev-osd.rst
+++ b/Documentation/media/uapi/v4l/dev-osd.rst
@@ -14,10 +14,11 @@
:ref:`Video Overlay <overlay>` interface.
The OSD function is accessible through the same character special file
-as the :ref:`Video Output <capture>` function. Note the default
-function of such a ``/dev/video`` device is video capturing or output.
-The OSD function is only available after calling the
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+as the :ref:`Video Output <capture>` function.
+
+.. note:: The default function of such a ``/dev/video`` device is video
+ capturing or output. The OSD function is only available after calling
+ the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
Querying Capabilities
diff --git a/Documentation/media/uapi/v4l/dev-output.rst b/Documentation/media/uapi/v4l/dev-output.rst
index 5063be7..4f1123a 100644
--- a/Documentation/media/uapi/v4l/dev-output.rst
+++ b/Documentation/media/uapi/v4l/dev-output.rst
@@ -14,7 +14,9 @@
device special files named ``/dev/video`` and ``/dev/video0`` to
``/dev/video63`` with major number 81 and minor numbers 0 to 63.
``/dev/video`` is typically a symbolic link to the preferred video
-device. Note the same device files are used for video capture devices.
+device.
+
+..note:: The same device file names are used also for video capture devices.
Querying Capabilities
diff --git a/Documentation/media/uapi/v4l/dev-overlay.rst b/Documentation/media/uapi/v4l/dev-overlay.rst
index bed00bf..bf8a418 100644
--- a/Documentation/media/uapi/v4l/dev-overlay.rst
+++ b/Documentation/media/uapi/v4l/dev-overlay.rst
@@ -17,10 +17,11 @@
video into a window.
Video overlay devices are accessed through the same character special
-files as :ref:`video capture <capture>` devices. Note the default
-function of a ``/dev/video`` device is video capturing. The overlay
-function is only available after calling the
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+files as :ref:`video capture <capture>` devices.
+
+.. note:: The default function of a ``/dev/video`` device is video
+ capturing. The overlay function is only available after calling
+ the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
The driver may support simultaneous overlay and capturing using the
read/write and streaming I/O methods. If so, operation at the nominal
@@ -235,10 +236,10 @@
:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`,
:ref:`framebuffer-flags`).
- **Note**: this field was added in Linux 2.6.23, extending the structure.
- However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>`
- ioctls, which take a pointer to a :ref:`v4l2_format <v4l2-format>`
- parent structure with padding bytes at the end, are not affected.
+ .. note:: This field was added in Linux 2.6.23, extending the
+ structure. However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>`
+ ioctls, which take a pointer to a :ref:`v4l2_format <v4l2-format>`
+ parent structure with padding bytes at the end, are not affected.
.. _v4l2-clip:
diff --git a/Documentation/media/uapi/v4l/dev-rds.rst b/Documentation/media/uapi/v4l/dev-rds.rst
index 6a0b1a8..cd6ad63 100644
--- a/Documentation/media/uapi/v4l/dev-rds.rst
+++ b/Documentation/media/uapi/v4l/dev-rds.rst
@@ -14,10 +14,10 @@
For more information see the core RDS standard :ref:`iec62106` and the
RBDS standard :ref:`nrsc4`.
-Note that the RBDS standard as is used in the USA is almost identical to
-the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only
-some of the fields have slightly different meanings. See the RBDS
-standard for more information.
+.. note:: Note that the RBDS standard as is used in the USA is almost
+ identical to the RDS standard. Any RDS decoder/encoder can also handle
+ RBDS. Only some of the fields have slightly different meanings. See the
+ RBDS standard for more information.
The RBDS standard also specifies support for MMBS (Modified Mobile
Search). This is a proprietary format which seems to be discontinued.
diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
index 39d3d86..5a112eb 100644
--- a/Documentation/media/uapi/v4l/dev-subdev.rst
+++ b/Documentation/media/uapi/v4l/dev-subdev.rst
@@ -72,14 +72,14 @@
Pad-level Formats
=================
- **Warning**
+.. warning::
- Pad-level formats are only applicable to very complex device that
+ Pad-level formats are only applicable to very complex devices that
need to expose low-level format configuration to user space. Generic
V4L2 applications do *not* need to use the API described in this
section.
- **Note**
+.. note::
For the purpose of this section, the term *format* means the
combination of media bus data format, frame width and frame height.
diff --git a/Documentation/media/uapi/v4l/dmabuf.rst b/Documentation/media/uapi/v4l/dmabuf.rst
index 57917fb..675768f 100644
--- a/Documentation/media/uapi/v4l/dmabuf.rst
+++ b/Documentation/media/uapi/v4l/dmabuf.rst
@@ -143,13 +143,16 @@
To start and stop capturing or displaying applications call the
:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls. Note that
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
-both queues and unlocks all buffers as a side effect. Since there is no
-notion of doing anything "now" on a multitasking system, if an
-application needs to synchronize with another event it should examine
-the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
-outputted buffers.
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls.
+
+.. note::
+
+ :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
+ both queues and unlocks all buffers as a side effect. Since there is no
+ notion of doing anything "now" on a multitasking system, if an
+ application needs to synchronize with another event it should examine
+ the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
+ outputted buffers.
Drivers implementing DMABUF importing I/O must support the
:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst
index 26eb6ee..11d15d3 100644
--- a/Documentation/media/uapi/v4l/extended-controls.rst
+++ b/Documentation/media/uapi/v4l/extended-controls.rst
@@ -84,17 +84,20 @@
particular, this ioctl gives the dimensions of the N-dimensional array
if this control consists of more than one element.
-It is important to realize that due to the flexibility of controls it is
-necessary to check whether the control you want to set actually is
-supported in the driver and what the valid range of values is. So use
-the :ref:`VIDIOC_QUERYCTRL` (or
-:ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`) and
-:ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls to check this. Also
-note that it is possible that some of the menu indices in a control of
-type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU``
-will return an error). A good example is the list of supported MPEG
-audio bitrates. Some drivers only support one or two bitrates, others
-support a wider range.
+.. note::
+
+ #. It is important to realize that due to the flexibility of controls it is
+ necessary to check whether the control you want to set actually is
+ supported in the driver and what the valid range of values is. So use
+ the :ref:`VIDIOC_QUERYCTRL` (or :ref:`VIDIOC_QUERY_EXT_CTRL
+ <VIDIOC_QUERYCTRL>`) and :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`
+ ioctls to check this.
+
+ #. It is possible that some of the menu indices in a control of
+ type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU``
+ will return an error). A good example is the list of supported MPEG
+ audio bitrates. Some drivers only support one or two bitrates, others
+ support a wider range.
All controls use machine endianness.
@@ -181,10 +184,10 @@
Below all controls within the Codec control class are described. First
the generic controls, then controls specific for certain hardware.
-Note: These controls are applicable to all codecs and not just MPEG. The
-defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls
-were originally made for MPEG codecs and later extended to cover all
-encoding formats.
+.. note:: These controls are applicable to all codecs and not just MPEG. The
+ defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls
+ were originally made for MPEG codecs and later extended to cover all
+ encoding formats.
Generic Codec Controls
@@ -2282,13 +2285,15 @@
``V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF (integer)``
Reaction coefficient for MFC rate control. Applicable to encoders.
- Note 1: Valid only when the frame level RC is enabled.
+ .. note::
- Note 2: For tight CBR, this field must be small (ex. 2 ~ 10). For
- VBR, this field must be large (ex. 100 ~ 1000).
+ #. Valid only when the frame level RC is enabled.
- Note 3: It is not recommended to use the greater number than
- FRAME_RATE * (10^9 / BIT_RATE).
+ #. For tight CBR, this field must be small (ex. 2 ~ 10). For
+ VBR, this field must be large (ex. 100 ~ 1000).
+
+ #. It is not recommended to use the greater number than
+ FRAME_RATE * (10^9 / BIT_RATE).
``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK (boolean)``
Adaptive rate control for dark region. Valid only when H.264 and
@@ -4107,14 +4112,16 @@
the receiver or transmitter subdevice that implements them, so they are
only exposed on the ``/dev/v4l-subdev*`` device node.
-Note that these devices can have multiple input or output pads which are
-hooked up to e.g. HDMI connectors. Even though the subdevice will
-receive or transmit video from/to only one of those pads, the other pads
-can still be active when it comes to EDID (Extended Display
-Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital
-Content Protection System, :ref:`hdcp`) processing, allowing the
-device to do the fairly slow EDID/HDCP handling in advance. This allows
-for quick switching between connectors.
+.. note::
+
+ Note that these devices can have multiple input or output pads which are
+ hooked up to e.g. HDMI connectors. Even though the subdevice will
+ receive or transmit video from/to only one of those pads, the other pads
+ can still be active when it comes to EDID (Extended Display
+ Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital
+ Content Protection System, :ref:`hdcp`) processing, allowing the
+ device to do the fairly slow EDID/HDCP handling in advance. This allows
+ for quick switching between connectors.
These pads appear in several of the controls in this section as
bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad
diff --git a/Documentation/media/uapi/v4l/func-mmap.rst b/Documentation/media/uapi/v4l/func-mmap.rst
index 3502c2a..c156fb7 100644
--- a/Documentation/media/uapi/v4l/func-mmap.rst
+++ b/Documentation/media/uapi/v4l/func-mmap.rst
@@ -47,17 +47,20 @@
Regardless of the device type and the direction of data exchange it
should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read
and write access to image buffers. Drivers should support at least
- this combination of flags. Note the Linux ``video-buf`` kernel
- module, which is used by the bttv, saa7134, saa7146, cx88 and vivi
- driver supports only ``PROT_READ`` | ``PROT_WRITE``. When the
- driver does not support the desired protection the
- :ref:`mmap() <func-mmap>` function fails.
+ this combination of flags.
- Note device memory accesses (e. g. the memory on a graphics card
- with video capturing hardware) may incur a performance penalty
- compared to main memory accesses, or reads may be significantly
- slower than writes or vice versa. Other I/O methods may be more
- efficient in this case.
+ .. note::
+
+ #. The Linux ``videobuf`` kernel module, which is used by some
+ drivers supports only ``PROT_READ`` | ``PROT_WRITE``. When the
+ driver does not support the desired protection, the
+ :ref:`mmap() <func-mmap>` function fails.
+
+ #. Device memory accesses (e. g. the memory on a graphics card
+ with video capturing hardware) may incur a performance penalty
+ compared to main memory accesses, or reads may be significantly
+ slower than writes or vice versa. Other I/O methods may be more
+ efficient in such case.
``flags``
The ``flags`` parameter specifies the type of the mapped object,
@@ -73,11 +76,13 @@
One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set.
``MAP_SHARED`` allows applications to share the mapped memory with
- other (e. g. child-) processes. Note the Linux ``video-buf`` module
- which is used by the bttv, saa7134, saa7146, cx88 and vivi driver
- supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests copy-on-write
- semantics. V4L2 applications should not set the ``MAP_PRIVATE``,
- ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` flag.
+ other (e. g. child-) processes.
+
+ .. note:: The Linux ``videobuf`` module which is used by some
+ drivers supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests
+ copy-on-write semantics. V4L2 applications should not set the
+ ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON``
+ flags.
``fd``
File descriptor returned by :ref:`open() <func-open>`.
diff --git a/Documentation/media/uapi/v4l/mmap.rst b/Documentation/media/uapi/v4l/mmap.rst
index b01f448..260c2db 100644
--- a/Documentation/media/uapi/v4l/mmap.rst
+++ b/Documentation/media/uapi/v4l/mmap.rst
@@ -245,12 +245,14 @@
To start and stop capturing or output applications call the
:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF
-<VIDIOC_STREAMON>` ioctl. Note :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
-removes all buffers from both queues as a side effect. Since there is
-no notion of doing anything "now" on a multitasking system, if an
-application needs to synchronize with another event it should examine
-the struct ::ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured
-or outputted buffers.
+<VIDIOC_STREAMON>` ioctl.
+
+.. note:::ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
+ removes all buffers from both queues as a side effect. Since there is
+ no notion of doing anything "now" on a multitasking system, if an
+ application needs to synchronize with another event it should examine
+ the struct ::ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured
+ or outputted buffers.
Drivers implementing memory mapping I/O must support the
:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QUERYBUF
diff --git a/Documentation/media/uapi/v4l/pixfmt-006.rst b/Documentation/media/uapi/v4l/pixfmt-006.rst
index b9e7c68..9a0f494 100644
--- a/Documentation/media/uapi/v4l/pixfmt-006.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-006.rst
@@ -17,9 +17,11 @@
specify non-standard quantization methods. Most of the time only the
colorspace field of struct :ref:`v4l2_pix_format <v4l2-pix-format>`
or struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>`
-needs to be filled in. Note that the default R'G'B' quantization is full
-range for all colorspaces except for BT.2020 which uses limited range
-R'G'B' quantization.
+needs to be filled in.
+
+.. note:: The default R'G'B' quantization is full range for all
+ colorspaces except for BT.2020 which uses limited range R'G'B'
+ quantization.
.. _v4l2-colorspace:
diff --git a/Documentation/media/uapi/v4l/pixfmt-007.rst b/Documentation/media/uapi/v4l/pixfmt-007.rst
index 5e39cda..8c946b0 100644
--- a/Documentation/media/uapi/v4l/pixfmt-007.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-007.rst
@@ -536,11 +536,13 @@
The :ref:`smpte431` standard defines the colorspace used by cinema
projectors that use the DCI-P3 colorspace. The default transfer function
is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_709``. Note that this colorspace does not specify a
-Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this
-default Y'CbCr encoding was picked because it is the HDTV encoding. The
-default Y'CbCr quantization is limited range. The chromaticities of the
-primary colors and the white reference are:
+``V4L2_YCBCR_ENC_709``.
+
+.. note:: Note that this colorspace does not specify a
+ Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this
+ default Y'CbCr encoding was picked because it is the HDTV encoding. The
+ default Y'CbCr quantization is limited range. The chromaticities of the
+ primary colors and the white reference are:
@@ -752,10 +754,10 @@
- 0.316
-Note that this colorspace uses Illuminant C instead of D65 as the white
-reference. To correctly convert an image in this colorspace to another
-that uses D65 you need to apply a chromatic adaptation algorithm such as
-the Bradford method.
+.. note:: This colorspace uses Illuminant C instead of D65 as the white
+ reference. To correctly convert an image in this colorspace to another
+ that uses D65 you need to apply a chromatic adaptation algorithm such as
+ the Bradford method.
The transfer function was never properly defined for NTSC 1953. The Rec.
709 transfer function is recommended in the literature:
@@ -886,9 +888,9 @@
with full range quantization where Y' is scaled to [0…255] and Cb/Cr are
scaled to [-128…128] and then clipped to [-128…127].
-Note that the JPEG standard does not actually store colorspace
-information. So if something other than sRGB is used, then the driver
-will have to set that information explicitly. Effectively
-``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for
-``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and
-``V4L2_QUANTIZATION_FULL_RANGE``.
+.. note:: The JPEG standard does not actually store colorspace
+ information. So if something other than sRGB is used, then the driver
+ will have to set that information explicitly. Effectively
+ ``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for
+ ``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and
+ ``V4L2_QUANTIZATION_FULL_RANGE``.
diff --git a/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst b/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst
index 2cfcc97..14446ed 100644
--- a/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst
@@ -17,9 +17,10 @@
This format is similar to
:ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`, except each pixel
has a depth of 16 bits. The least significant byte is stored at lower
-memory addresses (little-endian). Note the actual sampling precision may
-be lower than 16 bits, for example 10 bits per pixel with values in
-range 0 to 1023.
+memory addresses (little-endian).
+
+..note:: The actual sampling precision may be lower than 16 bits,
+ for example 10 bits per pixel with values in tange 0 to 1023.
**Byte Order.**
Each cell is one byte.
diff --git a/Documentation/media/uapi/v4l/pixfmt-y16-be.rst b/Documentation/media/uapi/v4l/pixfmt-y16-be.rst
index 0c61a10..37fa099 100644
--- a/Documentation/media/uapi/v4l/pixfmt-y16-be.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-y16-be.rst
@@ -15,9 +15,10 @@
===========
This is a grey-scale image with a depth of 16 bits per pixel. The most
-significant byte is stored at lower memory addresses (big-endian). Note
-the actual sampling precision may be lower than 16 bits, for example 10
-bits per pixel with values in range 0 to 1023.
+significant byte is stored at lower memory addresses (big-endian).
+
+.. note:: Tthe actual sampling precision may be lower than 16 bits, for
+ example 10 bits per pixel with values in range 0 to 1023.
**Byte Order.**
Each cell is one byte.
diff --git a/Documentation/media/uapi/v4l/pixfmt-y16.rst b/Documentation/media/uapi/v4l/pixfmt-y16.rst
index a8d4b71..4c41c04 100644
--- a/Documentation/media/uapi/v4l/pixfmt-y16.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-y16.rst
@@ -16,8 +16,9 @@
This is a grey-scale image with a depth of 16 bits per pixel. The least
significant byte is stored at lower memory addresses (little-endian).
-Note the actual sampling precision may be lower than 16 bits, for
-example 10 bits per pixel with values in range 0 to 1023.
+
+.. note:: The actual sampling precision may be lower than 16 bits, for
+ example 10 bits per pixel with values in range 0 to 1023.
**Byte Order.**
Each cell is one byte.
diff --git a/Documentation/media/uapi/v4l/standard.rst b/Documentation/media/uapi/v4l/standard.rst
index 529891c..9c390c2 100644
--- a/Documentation/media/uapi/v4l/standard.rst
+++ b/Documentation/media/uapi/v4l/standard.rst
@@ -39,11 +39,12 @@
output applications call the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and
:ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctl, respectively. The
*received* standard can be sensed with the
-:ref:`VIDIOC_QUERYSTD` ioctl. Note that the
-parameter of all these ioctls is a pointer to a
-:ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an
-index into the standard enumeration. Drivers must implement all video
-standard ioctls when the device has one or more video inputs or outputs.
+:ref:`VIDIOC_QUERYSTD` ioctl.
+
+..note:: The parameter of all these ioctls is a pointer to a
+ :ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an
+ index into the standard enumeration. Drivers must implement all video
+ standard ioctls when the device has one or more video inputs or outputs.
Special rules apply to devices such as USB cameras where the notion of
video standards makes little sense. More generally for any capture or
diff --git a/Documentation/media/uapi/v4l/tuner.rst b/Documentation/media/uapi/v4l/tuner.rst
index 23d0e00..37eb4b9 100644
--- a/Documentation/media/uapi/v4l/tuner.rst
+++ b/Documentation/media/uapi/v4l/tuner.rst
@@ -26,13 +26,14 @@
:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` ioctls, respectively. The
struct :ref:`v4l2_tuner <v4l2-tuner>` returned by :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>`
also contains signal status information applicable when the tuner of the
-current video or radio input is queried. Note that :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>`
-does not switch the current tuner, when there is more than one at all.
-The tuner is solely determined by the current video input. Drivers must
-support both ioctls and set the ``V4L2_CAP_TUNER`` flag in the struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl when the device has
-one or more tuners.
+current video or radio input is queried.
+
+.. note:: :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` does not switch the
+ current tuner, when there is more than one at all. The tuner is solely
+ determined by the current video input. Drivers must support both ioctls
+ and set the ``V4L2_CAP_TUNER`` flag in the struct :ref:`v4l2_capability
+ <v4l2-capability>` returned by the :ref:`VIDIOC_QUERYCAP` ioctl when the
+ device has one or more tuners.
Modulators
diff --git a/Documentation/media/uapi/v4l/userp.rst b/Documentation/media/uapi/v4l/userp.rst
index 0871c20..601963a 100644
--- a/Documentation/media/uapi/v4l/userp.rst
+++ b/Documentation/media/uapi/v4l/userp.rst
@@ -86,13 +86,14 @@
To start and stop capturing or output applications call the
:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl. Note
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from both
-queues and unlocks all buffers as a side effect. Since there is no
-notion of doing anything "now" on a multitasking system, if an
-application needs to synchronize with another event it should examine
-the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
-outputted buffers.
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl.
+
+.. note:: ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
+ both queues and unlocks all buffers as a side effect. Since there is no
+ notion of doing anything "now" on a multitasking system, if an
+ application needs to synchronize with another event it should examine
+ the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
+ outputted buffers.
Drivers implementing user pointer I/O must support the
:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
diff --git a/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst b/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst
index efa911c..f7e1b80 100644
--- a/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst
+++ b/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst
@@ -33,7 +33,7 @@
Description
===========
- **Note**
+.. note::
This is an :ref:`experimental` interface and may
change in the future.
diff --git a/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst b/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst
index 345aa32..09d2880 100644
--- a/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst
+++ b/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst
@@ -35,7 +35,7 @@
Description
===========
- **Note**
+.. note::
This is an :ref:`experimental` interface and may
change in the future.
diff --git a/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst b/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst
index 5a35bb2..6e05957 100644
--- a/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst
+++ b/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst
@@ -37,8 +37,10 @@
initialize the ``pad`` field to 0, zero the reserved array of struct
:ref:`v4l2_dv_timings_cap <v4l2-dv-timings-cap>` and call the
``VIDIOC_DV_TIMINGS_CAP`` ioctl on a video node and the driver will fill
-in the structure. Note that drivers may return different values after
-switching the video input or output.
+in the structure.
+
+.. note:: Drivers may return different values after
+ switching the video input or output.
When implemented by the driver DV capabilities of subdevices can be
queried by calling the ``VIDIOC_SUBDEV_DV_TIMINGS_CAP`` ioctl directly
diff --git a/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst
index f0dd0c4..3ba75d3 100644
--- a/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst
@@ -47,8 +47,10 @@
structure. Drivers fill the rest of the structure or return an ``EINVAL``
error code when the index is out of bounds. To enumerate all supported
DV timings, applications shall begin at index zero, incrementing by one
-until the driver returns ``EINVAL``. Note that drivers may enumerate a
-different set of DV timings after switching the video input or output.
+until the driver returns ``EINVAL``.
+
+.. note:: Drivers may enumerate a different set of DV timings after
+ switching the video input or output.
When implemented by the driver DV timings of subdevices can be queried
by calling the ``VIDIOC_SUBDEV_ENUM_DV_TIMINGS`` ioctl directly on a
diff --git a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst
index 257c624..90996f6 100644
--- a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst
@@ -40,8 +40,8 @@
formats are enumerable by beginning at index zero and incrementing by
one until ``EINVAL`` is returned.
-Note that after switching input or output the list of enumerated image
-formats may be different.
+.. note:: After switching input or output the list of enumerated image
+ formats may be different.
.. _v4l2-fmtdesc:
@@ -111,8 +111,10 @@
#define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))
Several image formats are already defined by this specification in
- :ref:`pixfmt`. Note these codes are not the same as those used
- in the Windows world.
+ :ref:`pixfmt`.
+
+ .. attention:: These codes are not the same as those used
+ in the Windows world.
- .. row 7
diff --git a/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst b/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst
index 5d5de53..ceae600 100644
--- a/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst
@@ -73,25 +73,21 @@
does it make sense to increase the index value to receive more frame
intervals.
-Note that the order in which the frame intervals are returned has no
-special meaning. In particular does it not say anything about potential
-default frame intervals.
+.. note:: The order in which the frame intervals are returned has no
+ special meaning. In particular does it not say anything about potential
+ default frame intervals.
Applications can assume that the enumeration data does not change
without any interaction from the application itself. This means that the
enumeration data is consistent if the application does not perform any
other ioctl calls while it runs the frame interval enumeration.
+.. note::
-Notes
-=====
-
-- **Frame intervals and frame rates:** The V4L2 API uses frame
+ **Frame intervals and frame rates:** The V4L2 API uses frame
intervals instead of frame rates. Given the frame interval the frame
rate can be computed as follows:
-
-
::
frame_rate = 1 / frame_interval
diff --git a/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst b/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst
index d3b2e97..8b26835 100644
--- a/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst
@@ -72,9 +72,9 @@
device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does
it make sense to increase the index value to receive more frame sizes.
-Note that the order in which the frame sizes are returned has no special
-meaning. In particular does it not say anything about potential default
-format sizes.
+.. note:: The order in which the frame sizes are returned has no special
+ meaning. In particular does it not say anything about potential default
+ format sizes.
Applications can assume that the enumeration data does not change
without any interaction from the application itself. This means that the
diff --git a/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst b/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst
index ea754f4..00ab5e1 100644
--- a/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst
@@ -127,12 +127,14 @@
- ``modulation``
- :cspan:`2` The supported modulation systems of this frequency
- band. See :ref:`band-modulation`. Note that currently only one
- modulation system per frequency band is supported. More work will
- need to be done if multiple modulation systems are possible.
- Contact the linux-media mailing list
- (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
- if you need that functionality.
+ band. See :ref:`band-modulation`.
+
+ .. note:: Currently only one modulation system per frequency band
+ is supported. More work will need to be done if multiple
+ modulation systems are possible. Contact the linux-media
+ mailing list
+ (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
+ if you need such functionality.
- .. row 8
diff --git a/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst b/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst
index 15bc5a4..cde1db5 100644
--- a/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst
@@ -41,8 +41,8 @@
bounds. To enumerate all audio outputs applications shall begin at index
zero, incrementing by one until the driver returns ``EINVAL``.
-Note connectors on a TV card to loop back the received audio signal to a
-sound card are not audio outputs in this sense.
+.. note:: Connectors on a TV card to loop back the received audio signal
+ to a sound card are not audio outputs in this sense.
See :ref:`VIDIOC_G_AUDIOout <VIDIOC_G_AUDOUT>` for a description of struct
:ref:`v4l2_audioout <v4l2-audioout>`.
diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
index c1fc2e1..5060f54 100644
--- a/Documentation/media/uapi/v4l/vidioc-enuminput.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
@@ -233,8 +233,8 @@
- The input is connected to a device that produces a signal that is
flipped vertically and does not correct this before passing the
- signal to userspace. Note that a 180 degree rotation is the same
- as HFLIP | VFLIP
+ signal to userspace.
+ .. note:: A 180 degree rotation is the same as HFLIP | VFLIP
- .. row 8
diff --git a/Documentation/media/uapi/v4l/vidioc-g-audioout.rst b/Documentation/media/uapi/v4l/vidioc-g-audioout.rst
index bee5f78..b1c1bfe 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-audioout.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-audioout.rst
@@ -51,8 +51,8 @@
write-only ioctl, it does not return the current audio output attributes
as ``VIDIOC_G_AUDOUT`` does.
-Note connectors on a TV card to loop back the received audio signal to a
-sound card are not audio outputs in this sense.
+.. note:: Connectors on a TV card to loop back the received audio signal
+ to a sound card are not audio outputs in this sense.
.. _v4l2-audioout:
diff --git a/Documentation/media/uapi/v4l/vidioc-g-edid.rst b/Documentation/media/uapi/v4l/vidioc-g-edid.rst
index 907b2c1..1a982b6 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-edid.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-edid.rst
@@ -65,8 +65,10 @@
:ref:`VIDIOC_G_EDID <VIDIOC_G_EDID>` is called, then the driver will set ``blocks`` to the
total number of available EDID blocks and it will return 0 without
copying any data. This is an easy way to discover how many EDID blocks
-there are. Note that if there are no EDID blocks available at all, then
-the driver will set ``blocks`` to 0 and it returns 0.
+there are.
+
+.. note:: If there are no EDID blocks available at all, then
+ the driver will set ``blocks`` to 0 and it returns 0.
To set the EDID blocks of a receiver the application has to fill in the
``pad``, ``blocks`` and ``edid`` fields, set ``start_block`` to 0 and
diff --git a/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst b/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst
index 96b6eac..39e24ad 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst
@@ -125,10 +125,12 @@
the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is
less than is required to store the payload result, then it is set
to a value large enough to store the payload result and ``ENOSPC`` is
- returned. Note that for string controls this ``size`` field should
- not be confused with the length of the string. This field refers
- to the size of the memory that contains the string. The actual
- *length* of the string may well be much smaller.
+ returned.
+
+ .. note:: For string controls, this ``size`` field should
+ not be confused with the length of the string. This field refers
+ to the size of the memory that contains the string. The actual
+ *length* of the string may well be much smaller.
- .. row 3
@@ -261,8 +263,10 @@
- Which value of the control to get/set/try.
``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the
control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default
- value of the control. Please note that you can only get the
- default value of the control, you cannot set or try it.
+ value of the control.
+
+ .. note:: You can only get the default value of the control,
+ you cannot set or try it.
For backwards compatibility you can also use a control class here
(see :ref:`ctrl-class`). In that case all controls have to
diff --git a/Documentation/media/uapi/v4l/vidioc-g-modulator.rst b/Documentation/media/uapi/v4l/vidioc-g-modulator.rst
index 05d8361..a2e8c73 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-modulator.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-modulator.rst
@@ -128,12 +128,14 @@
- With this field applications can determine how audio sub-carriers
shall be modulated. It contains a set of flags as defined in
- :ref:`modulator-txsubchans`. Note the tuner ``rxsubchans`` flags
- are reused, but the semantics are different. Video output devices
- are assumed to have an analog or PCM audio input with 1-3
- channels. The ``txsubchans`` flags select one or more channels for
- modulation, together with some audio subprogram indicator, for
- example a stereo pilot tone.
+ :ref:`modulator-txsubchans`.
+
+ .. note:: The tuner ``rxsubchans`` flags are reused, but the
+ semantics are different. Video output devices
+ are assumed to have an analog or PCM audio input with 1-3
+ channels. The ``txsubchans`` flags select one or more channels
+ for modulation, together with some audio subprogram indicator,
+ for example, a stereo pilot tone.
- .. row 7
diff --git a/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst
index 76dd4ba..f1f661d 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst
@@ -40,8 +40,8 @@
driver fills in the remaining fields or returns an ``EINVAL`` error code if
the sliced VBI API is unsupported or ``type`` is invalid.
-Note the ``type`` field was added, and the ioctl changed from read-only
-to write-read, in Linux 2.6.19.
+.. note:: The ``type`` field was added, and the ioctl changed from read-only
+ to write-read, in Linux 2.6.19.
.. _v4l2-sliced-vbi-cap:
diff --git a/Documentation/media/uapi/v4l/vidioc-g-tuner.rst b/Documentation/media/uapi/v4l/vidioc-g-tuner.rst
index a8d7ebd..c820855 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-tuner.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-tuner.rst
@@ -391,9 +391,9 @@
carrier for a monaural secondary language. Only
``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
- Note the ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` flags
- are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
- supports the ``V4L2_STD_NTSC_M`` video standard.
+ .. note:: The ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP``
+ flags are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
+ supports the ``V4L2_STD_NTSC_M`` video standard.
- .. row 9
@@ -500,10 +500,11 @@
- 0x0004
- - The tuner receives a Second Audio Program. Note the
- ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` flags are
- synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies when the current
- video standard is ``V4L2_STD_NTSC_M``.
+ - The tuner receives a Second Audio Program.
+
+ .. note:: The ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP``
+ flags are synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies
+ when the current video standard is ``V4L2_STD_NTSC_M``.
- .. row 6
@@ -578,9 +579,10 @@
- Play the Second Audio Program. When the tuner receives no
bilingual audio or SAP, or their reception is not supported the
driver shall fall back to mono or stereo mode. Only
- ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. Note the
- ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP`` are
- synonyms.
+ ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
+
+ .. note:: The ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP``
+ are synonyms.
- .. row 6
diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
index 9870d24..3b927f3 100644
--- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst
+++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
@@ -135,14 +135,15 @@
EIO
``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate
- temporary problems like signal loss. Note the driver might dequeue
- an (empty) buffer despite returning an error, or even stop
- capturing. Reusing such buffer may be unsafe though and its details
- (e.g. ``index``) may not be returned either. It is recommended that
- drivers indicate recoverable errors by setting the
- ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the
- application should be able to safely reuse the buffer and continue
- streaming.
+ temporary problems like signal loss.
+
+ .. note:: The driver might dequeue an (empty) buffer despite returning
+ an error, or even stop capturing. Reusing such buffer may be unsafe
+ though and its details (e.g. ``index``) may not be returned either.
+ It is recommended that drivers indicate recoverable errors by setting
+ the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the
+ application should be able to safely reuse the buffer and continue
+ streaming.
EPIPE
``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem
diff --git a/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst
index 338b80d..416d8d6 100644
--- a/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst
+++ b/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst
@@ -39,16 +39,16 @@
:ref:`v4l2_dv_timings <v4l2-dv-timings>`. Once the hardware detects
the timings, it will fill in the timings structure.
-Please note that drivers shall *not* switch timings automatically if new
-timings are detected. Instead, drivers should send the
-``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect
-that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`.
-The reason is that new timings usually mean different buffer sizes as
-well, and you cannot change buffer sizes on the fly. In general,
-applications that receive the Source Change event will have to call
-:ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they
-will have to stop streaming, set the new timings, allocate new buffers
-and start streaming again.
+.. note:: Drivers shall *not* switch timings automatically if new
+ timings are detected. Instead, drivers should send the
+ ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect
+ that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`.
+ The reason is that new timings usually mean different buffer sizes as
+ well, and you cannot change buffer sizes on the fly. In general,
+ applications that receive the Source Change event will have to call
+ :ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they
+ will have to stop streaming, set the new timings, allocate new buffers
+ and start streaming again.
If the timings could not be detected because there was no signal, then
ENOLINK is returned. If a signal was detected, but it was unstable and
diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
index 0f27e71..4342ace 100644
--- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
+++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
@@ -82,10 +82,12 @@
``id`` or ``index`` is invalid. Menu items are enumerated by calling
``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
:ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
-inclusive. Note that it is possible for ``VIDIOC_QUERYMENU`` to return
-an ``EINVAL`` error code for some indices between ``minimum`` and
-``maximum``. In that case that particular menu item is not supported by
-this driver. Also note that the ``minimum`` value is not necessarily 0.
+inclusive.
+
+.. note:: It is possible for ``VIDIOC_QUERYMENU`` to return
+ an ``EINVAL`` error code for some indices between ``minimum`` and
+ ``maximum``. In that case that particular menu item is not supported by
+ this driver. Also note that the ``minimum`` value is not necessarily 0.
See also the examples in :ref:`control`.
@@ -184,9 +186,10 @@
- The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
- for other types of controls. Note that drivers reset controls to
- their default value only when the driver is first loaded, never
- afterwards.
+ for other types of controls.
+
+ .. note:: Drivers reset controls to their default value only when
+ the driver is first loaded, never afterwards.
- .. row 8
@@ -301,9 +304,10 @@
- The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
- or ``_U16`` control. Not valid for other types of controls. Note
- that drivers reset controls to their default value only when the
- driver is first loaded, never afterwards.
+ or ``_U16`` control. Not valid for other types of controls.
+
+ .. note:: Drivers reset controls to their default value only when
+ the driver is first loaded, never afterwards.
- .. row 8
@@ -722,11 +726,12 @@
control changes continuously. A typical example would be the
current gain value if the device is in auto-gain mode. In such a
case the hardware calculates the gain value based on the lighting
- conditions which can change over time. Note that setting a new
- value for a volatile control will have no effect and no
- ``V4L2_EVENT_CTRL_CH_VALUE`` will be sent, unless the
- ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` flag (see below) is also set.
- Otherwise the new value will just be ignored.
+ conditions which can change over time.
+
+ .. note:: Setting a new value for a volatile control will have no
+ effect and no ``V4L2_EVENT_CTRL_CH_VALUE`` will be sent, unless
+ the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` flag (see below) is
+ also set. Otherwise the new value will just be ignored.
- .. row 9
diff --git a/Documentation/media/uapi/v4l/vidioc-querystd.rst b/Documentation/media/uapi/v4l/vidioc-querystd.rst
index 5bf6277..b4a4e22 100644
--- a/Documentation/media/uapi/v4l/vidioc-querystd.rst
+++ b/Documentation/media/uapi/v4l/vidioc-querystd.rst
@@ -43,16 +43,16 @@
the set must contain all standards supported by the current video input
or output.
-Please note that drivers shall *not* switch the video standard
-automatically if a new video standard is detected. Instead, drivers
-should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support
-this) and expect that userspace will take action by calling
-:ref:`VIDIOC_QUERYSTD`. The reason is that a new video standard can mean
-different buffer sizes as well, and you cannot change buffer sizes on
-the fly. In general, applications that receive the Source Change event
-will have to call :ref:`VIDIOC_QUERYSTD`, and if the detected video
-standard is valid they will have to stop streaming, set the new
-standard, allocate new buffers and start streaming again.
+.. note:: Drivers shall *not* switch the video standard
+ automatically if a new video standard is detected. Instead, drivers
+ should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support
+ this) and expect that userspace will take action by calling
+ :ref:`VIDIOC_QUERYSTD`. The reason is that a new video standard can mean
+ different buffer sizes as well, and you cannot change buffer sizes on
+ the fly. In general, applications that receive the Source Change event
+ will have to call :ref:`VIDIOC_QUERYSTD`, and if the detected video
+ standard is valid they will have to stop streaming, set the new
+ standard, allocate new buffers and start streaming again.
Return Value
diff --git a/Documentation/media/uapi/v4l/vidioc-streamon.rst b/Documentation/media/uapi/v4l/vidioc-streamon.rst
index e87500e..bb23745e 100644
--- a/Documentation/media/uapi/v4l/vidioc-streamon.rst
+++ b/Documentation/media/uapi/v4l/vidioc-streamon.rst
@@ -76,10 +76,10 @@
but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
state as mentioned above.
-Note that applications can be preempted for unknown periods right before
-or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
-no notion of starting or stopping "now". Buffer timestamps can be used
-to synchronize with other events.
+.. note:: Applications can be preempted for unknown periods right before
+ or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
+ no notion of starting or stopping "now". Buffer timestamps can be used
+ to synchronize with other events.
Return Value
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
index 690034a..ae802f1 100644
--- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
+++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
@@ -35,7 +35,7 @@
Description
===========
- **Note**
+.. note::
This is an :ref:`obsolete` interface and may be removed
in the future. It is superseded by
diff --git a/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst b/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst
index a027f60..3ed91c6 100644
--- a/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst
+++ b/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst
@@ -51,9 +51,11 @@
- ``type``
- - Type of the event, see :ref:`event-type`. Note that
- ``V4L2_EVENT_ALL`` can be used with VIDIOC_UNSUBSCRIBE_EVENT for
- unsubscribing all events at once.
+ - Type of the event, see :ref:`event-type`.
+
+ .. note:: ``V4L2_EVENT_ALL`` can be used with
+ :ref:`VIDIOC_UNSUBSCRIBE_EVENT` for unsubscribing all events
+ at once.
- .. row 2