summaryrefslogtreecommitdiff
path: root/Documentation/media/uapi
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/media/uapi')
-rw-r--r--Documentation/media/uapi/cec/cec-func-ioctl.rst2
-rw-r--r--Documentation/media/uapi/cec/cec-func-open.rst2
-rw-r--r--Documentation/media/uapi/cec/cec-func-poll.rst4
-rw-r--r--Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst13
-rw-r--r--Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst13
-rw-r--r--Documentation/media/uapi/cec/cec-ioc-dqevent.rst13
-rw-r--r--Documentation/media/uapi/cec/cec-ioc-g-mode.rst12
-rw-r--r--Documentation/media/uapi/cec/cec-ioc-receive.rst55
-rw-r--r--Documentation/media/uapi/mediactl/media-types.rst3
-rw-r--r--Documentation/media/uapi/rc/lirc-dev-intro.rst53
-rw-r--r--Documentation/media/uapi/rc/lirc-get-features.rst13
-rw-r--r--Documentation/media/uapi/rc/lirc-get-length.rst3
-rw-r--r--Documentation/media/uapi/rc/lirc-get-rec-mode.rst4
-rw-r--r--Documentation/media/uapi/rc/lirc-get-send-mode.rst7
-rw-r--r--Documentation/media/uapi/rc/lirc-read.rst16
-rw-r--r--Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst2
-rw-r--r--Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst2
-rw-r--r--Documentation/media/uapi/rc/lirc-write.rst17
-rw-r--r--Documentation/media/uapi/v4l/buffer.rst122
-rw-r--r--Documentation/media/uapi/v4l/depth-formats.rst1
-rw-r--r--Documentation/media/uapi/v4l/dev-capture.rst4
-rw-r--r--Documentation/media/uapi/v4l/dev-meta.rst58
-rw-r--r--Documentation/media/uapi/v4l/dev-output.rst4
-rw-r--r--Documentation/media/uapi/v4l/devices.rst1
-rw-r--r--Documentation/media/uapi/v4l/meta-formats.rst16
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-007.rst13
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-inzi.rst81
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst168
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst120
-rw-r--r--Documentation/media/uapi/v4l/pixfmt.rst1
-rw-r--r--Documentation/media/uapi/v4l/subdev-formats.rst240
-rw-r--r--Documentation/media/uapi/v4l/video.rst7
-rw-r--r--Documentation/media/uapi/v4l/vidioc-enuminput.rst11
-rw-r--r--Documentation/media/uapi/v4l/vidioc-enumoutput.rst15
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst16
-rw-r--r--Documentation/media/uapi/v4l/vidioc-querycap.rst3
-rw-r--r--Documentation/media/uapi/v4l/vidioc-queryctrl.rst17
37 files changed, 942 insertions, 190 deletions
diff --git a/Documentation/media/uapi/cec/cec-func-ioctl.rst b/Documentation/media/uapi/cec/cec-func-ioctl.rst
index 7dcfd178fb24..22fb6304a2df 100644
--- a/Documentation/media/uapi/cec/cec-func-ioctl.rst
+++ b/Documentation/media/uapi/cec/cec-func-ioctl.rst
@@ -30,7 +30,7 @@ Arguments
``request``
CEC ioctl request code as defined in the cec.h header file, for
- example :c:func:`CEC_ADAP_G_CAPS`.
+ example :ref:`CEC_ADAP_G_CAPS <CEC_ADAP_G_CAPS>`.
``argp``
Pointer to a request-specific structure.
diff --git a/Documentation/media/uapi/cec/cec-func-open.rst b/Documentation/media/uapi/cec/cec-func-open.rst
index 0304388cd159..18dfb62f2efe 100644
--- a/Documentation/media/uapi/cec/cec-func-open.rst
+++ b/Documentation/media/uapi/cec/cec-func-open.rst
@@ -33,7 +33,7 @@ Arguments
Open flags. Access mode must be ``O_RDWR``.
When the ``O_NONBLOCK`` flag is given, the
- :ref:`CEC_RECEIVE <CEC_RECEIVE>` and :c:func:`CEC_DQEVENT` ioctls
+ :ref:`CEC_RECEIVE <CEC_RECEIVE>` and :ref:`CEC_DQEVENT <CEC_DQEVENT>` ioctls
will return the ``EAGAIN`` error code when no message or event is available, and
ioctls :ref:`CEC_TRANSMIT <CEC_TRANSMIT>`,
:ref:`CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` and
diff --git a/Documentation/media/uapi/cec/cec-func-poll.rst b/Documentation/media/uapi/cec/cec-func-poll.rst
index 6a863cfda6e0..fa0abd8fb160 100644
--- a/Documentation/media/uapi/cec/cec-func-poll.rst
+++ b/Documentation/media/uapi/cec/cec-func-poll.rst
@@ -30,7 +30,7 @@ Arguments
List of FD events to be watched
``nfds``
- Number of FD efents at the \*ufds array
+ Number of FD events at the \*ufds array
``timeout``
Timeout to wait for events
@@ -49,7 +49,7 @@ is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in
the ``revents`` field if there are messages in the receive queue. If the
transmit queue has room for new messages, the ``POLLOUT`` and
``POLLWRNORM`` flags are set. If there are events in the event queue,
-then the ``POLLPRI`` flag is set. When the function timed out it returns
+then the ``POLLPRI`` flag is set. When the function times out it returns
a value of zero, on failure it returns -1 and the ``errno`` variable is
set appropriately.
diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst
index 09f09bbe28d4..fcf863ab6f43 100644
--- a/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst
+++ b/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst
@@ -351,3 +351,16 @@ 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.
+The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` can return the following
+error codes:
+
+ENOTTY
+ The ``CEC_CAP_LOG_ADDRS`` capability wasn't set, so this ioctl is not supported.
+
+EBUSY
+ The CEC adapter is currently configuring itself, or it is already configured and
+ ``num_log_addrs`` is non-zero, or another filehandle is in exclusive follower or
+ initiator mode, or the filehandle is in mode ``CEC_MODE_NO_INITIATOR``.
+
+EINVAL
+ The contents of struct :c:type:`cec_log_addrs` is invalid.
diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst
index a3cdc75cec3e..9e49d4be35d5 100644
--- a/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst
+++ b/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst
@@ -78,3 +78,16 @@ 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.
+
+The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can return the following
+error codes:
+
+ENOTTY
+ The ``CEC_CAP_PHYS_ADDR`` capability wasn't set, so this ioctl is not supported.
+
+EBUSY
+ Another filehandle is in exclusive follower or initiator mode, or the filehandle
+ is in mode ``CEC_MODE_NO_INITIATOR``.
+
+EINVAL
+ The physical address is malformed.
diff --git a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst
index 6e589a1fae17..4d3570c2e0b3 100644
--- a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst
+++ b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst
@@ -56,7 +56,7 @@ it is guaranteed that the state did change in between the two events.
* - __u16
- ``phys_addr``
- The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no
- valid physical address is set.
+ valid physical address is set.
* - __u16
- ``log_addr_mask``
- The current set of claimed logical addresses. This is 0 if no logical
@@ -174,3 +174,14 @@ 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.
+
+The :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>` can return the following
+error codes:
+
+EAGAIN
+ This is returned when the filehandle is in non-blocking mode and there
+ are no pending events.
+
+ERESTARTSYS
+ An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for
+ events to arrive.
diff --git a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst
index e4ded9df0a84..664f0d47bbcd 100644
--- a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst
+++ b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst
@@ -249,3 +249,15 @@ 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.
+
+The :ref:`ioctl CEC_S_MODE <CEC_S_MODE>` can return the following
+error codes:
+
+EINVAL
+ The requested mode is invalid.
+
+EPERM
+ Monitor mode is requested without having root permissions
+
+EBUSY
+ Someone else is already an exclusive follower or initiator.
diff --git a/Documentation/media/uapi/cec/cec-ioc-receive.rst b/Documentation/media/uapi/cec/cec-ioc-receive.rst
index dc2adb391c0a..267044f7ac30 100644
--- a/Documentation/media/uapi/cec/cec-ioc-receive.rst
+++ b/Documentation/media/uapi/cec/cec-ioc-receive.rst
@@ -51,13 +51,13 @@ A received message can be:
be non-zero).
To send a CEC message the application has to fill in the struct
-:c:type:` cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
+:c:type:`cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is only available if
``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit
queue, then it will return -1 and set errno to the ``EBUSY`` error code.
The transmit queue has enough room for 18 messages (about 1 second worth
of 2-byte messages). Note that the CEC kernel framework will also reply
-to core messages (see :ref:cec-core-processing), so it is not a good
+to core messages (see :ref:`cec-core-processing`), so it is not a good
idea to fully fill up the transmit queue.
If the file descriptor is in non-blocking mode then the transmit will
@@ -69,6 +69,18 @@ The ``sequence`` field is filled in for every transmit and this can be
checked against the received messages to find the corresponding transmit
result.
+Normally calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` when the physical
+address is invalid (due to e.g. a disconnect) will return ``ENONET``.
+
+However, the CEC specification allows sending messages from 'Unregistered' to
+'TV' when the physical address is invalid since some TVs pull the hotplug detect
+pin of the HDMI connector low when they go into standby, or when switching to
+another input.
+
+When the hotplug detect pin goes low the EDID disappears, and thus the
+physical address, but the cable is still connected and CEC still works.
+In order to detect/wake up the device it is allowed to send poll and 'Image/Text
+View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}|
@@ -289,3 +301,42 @@ 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.
+
+The :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` can return the following
+error codes:
+
+EAGAIN
+ No messages are in the receive queue, and the filehandle is in non-blocking mode.
+
+ETIMEDOUT
+ The ``timeout`` was reached while waiting for a message.
+
+ERESTARTSYS
+ The wait for a message was interrupted (e.g. by Ctrl-C).
+
+The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` can return the following
+error codes:
+
+ENOTTY
+ The ``CEC_CAP_TRANSMIT`` capability wasn't set, so this ioctl is not supported.
+
+EPERM
+ The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
+ has never been called.
+
+ENONET
+ The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
+ was called, but the physical address is invalid so no logical address was claimed.
+ An exception is made in this case for transmits from initiator 0xf ('Unregistered')
+ to destination 0 ('TV'). In that case the transmit will proceed as usual.
+
+EBUSY
+ Another filehandle is in exclusive follower or initiator mode, or the filehandle
+ is in mode ``CEC_MODE_NO_INITIATOR``. This is also returned if the transmit
+ queue is full.
+
+EINVAL
+ The contents of struct :c:type:`cec_msg` is invalid.
+
+ERESTARTSYS
+ The wait for a successful transmit was interrupted (e.g. by Ctrl-C).
diff --git a/Documentation/media/uapi/mediactl/media-types.rst b/Documentation/media/uapi/mediactl/media-types.rst
index 3e03dc2e6003..2a5164aea2b4 100644
--- a/Documentation/media/uapi/mediactl/media-types.rst
+++ b/Documentation/media/uapi/mediactl/media-types.rst
@@ -284,7 +284,8 @@ Types and flags used to represent the media graph elements
supported scaling ratios is entity-specific and can differ
between the horizontal and vertical directions (in particular
scaling can be supported in one direction only). Binning and
- skipping are considered as scaling.
+ sub-sampling (occasionally also referred to as skipping) are
+ considered as scaling.
- .. row 28
diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst
index ef97e40f2fd8..d1936eeb9ce0 100644
--- a/Documentation/media/uapi/rc/lirc-dev-intro.rst
+++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst
@@ -27,6 +27,8 @@ What you should see for a chardev:
$ ls -l /dev/lirc*
crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
+.. _lirc_modes:
+
**********
LIRC modes
**********
@@ -38,25 +40,62 @@ on the following table.
``LIRC_MODE_MODE2``
- The driver returns a sequence of pulse and space codes to userspace.
+ The driver returns a sequence of pulse and space codes to userspace,
+ as a series of u32 values.
This mode is used only for IR receive.
+ The upper 8 bits determine the packet type, and the lower 24 bits
+ the payload. Use ``LIRC_VALUE()`` macro to get the payload, and
+ the macro ``LIRC_MODE2()`` will give you the type, which
+ is one of:
+
+ ``LIRC_MODE2_PULSE``
+
+ Signifies the presence of IR in microseconds.
+
+ ``LIRC_MODE2_SPACE``
+
+ Signifies absence of IR in microseconds.
+
+ ``LIRC_MODE2_FREQUENCY``
+
+ If measurement of the carrier frequency was enabled with
+ :ref:`lirc_set_measure_carrier_mode` then this packet gives you
+ the carrier frequency in Hertz.
+
+ ``LIRC_MODE2_TIMEOUT``
+
+ If timeout reports are enabled with
+ :ref:`lirc_set_rec_timeout_reports`, when the timeout set with
+ :ref:`lirc_set_rec_timeout` expires due to no IR being detected,
+ this packet will be sent, with the number of microseconds with
+ no IR.
+
.. _lirc-mode-lirccode:
``LIRC_MODE_LIRCCODE``
- The IR signal is decoded internally by the receiver. The LIRC interface
- returns the scancode as an integer value. This is the usual mode used
- by several TV media cards.
+ This mode can be used for IR receive and send.
- This mode is used only for IR receive.
+ The IR signal is decoded internally by the receiver, or encoded by the
+ transmitter. The LIRC interface represents the scancode as byte string,
+ which might not be a u32, it can be any length. The value is entirely
+ driver dependent. This mode is used by some older lirc drivers.
+
+ The length of each code depends on the driver, which can be retrieved
+ with :ref:`lirc_get_length`. This length is used both
+ for transmitting and receiving IR.
.. _lirc-mode-pulse:
``LIRC_MODE_PULSE``
- On puse mode, a sequence of pulse/space integer values are written to the
- lirc device using :Ref:`lirc-write`.
+ In pulse mode, a sequence of pulse/space integer values are written to the
+ lirc device using :ref:`lirc-write`.
+
+ The values are alternating pulse and space lengths, in microseconds. The
+ first and last entry must be a pulse, so there must be an odd number
+ of entries.
This mode is used only for IR send.
diff --git a/Documentation/media/uapi/rc/lirc-get-features.rst b/Documentation/media/uapi/rc/lirc-get-features.rst
index 79e07b4d44d6..64f89a4f9d9c 100644
--- a/Documentation/media/uapi/rc/lirc-get-features.rst
+++ b/Documentation/media/uapi/rc/lirc-get-features.rst
@@ -48,8 +48,8 @@ LIRC features
``LIRC_CAN_REC_PULSE``
- The driver is capable of receiving using
- :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>`.
+ Unused. Kept just to avoid breaking uAPI.
+ :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>` can only be used for transmitting.
.. _LIRC-CAN-REC-MODE2:
@@ -156,19 +156,22 @@ LIRC features
``LIRC_CAN_SEND_PULSE``
- The driver supports sending using :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>`.
+ The driver supports sending (also called as IR blasting or IR TX) using
+ :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>`.
.. _LIRC-CAN-SEND-MODE2:
``LIRC_CAN_SEND_MODE2``
- The driver supports sending using :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`.
+ Unused. Kept just to avoid breaking uAPI.
+ :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` can only be used for receiving.
.. _LIRC-CAN-SEND-LIRCCODE:
``LIRC_CAN_SEND_LIRCCODE``
- The driver supports sending codes (also called as IR blasting or IR TX).
+ The driver supports sending (also called as IR blasting or IR TX) using
+ :ref:`LIRC_MODE_LIRCCODE <lirc-mode-LIRCCODE>`.
Return Value
diff --git a/Documentation/media/uapi/rc/lirc-get-length.rst b/Documentation/media/uapi/rc/lirc-get-length.rst
index 8c2747c8d2c9..3990af5de0e9 100644
--- a/Documentation/media/uapi/rc/lirc-get-length.rst
+++ b/Documentation/media/uapi/rc/lirc-get-length.rst
@@ -30,7 +30,8 @@ Arguments
Description
===========
-Retrieves the code length in bits (only for ``LIRC-MODE-LIRCCODE``).
+Retrieves the code length in bits (only for
+:ref:`LIRC_MODE_LIRCCODE <lirc-mode-lirccode>`).
Reads on the device must be done in blocks matching the bit count.
The bit could should be rounded up so that it matches full bytes.
diff --git a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst
index a5023e0194c1..a4eb6c0a26e9 100644
--- a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst
+++ b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst
@@ -35,8 +35,8 @@ Description
Get/set supported receive modes. Only :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`
and :ref:`LIRC_MODE_LIRCCODE <lirc-mode-lirccode>` are supported for IR
-receive.
-
+receive. Use :ref:`lirc_get_features` to find out which modes the driver
+supports.
Return Value
============
diff --git a/Documentation/media/uapi/rc/lirc-get-send-mode.rst b/Documentation/media/uapi/rc/lirc-get-send-mode.rst
index 51ac13428969..a169b234290e 100644
--- a/Documentation/media/uapi/rc/lirc-get-send-mode.rst
+++ b/Documentation/media/uapi/rc/lirc-get-send-mode.rst
@@ -34,9 +34,12 @@ Arguments
Description
===========
-Get/set supported transmit mode.
+Get/set current transmit mode.
-Only :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>` is supported by for IR send.
+Only :ref:`LIRC_MODE_PULSE <lirc-mode-pulse>` and
+:ref:`LIRC_MODE_LIRCCODE <lirc-mode-lirccode>` is supported by for IR send,
+depending on the driver. Use :ref:`lirc_get_features` to find out which
+modes the driver supports.
Return Value
============
diff --git a/Documentation/media/uapi/rc/lirc-read.rst b/Documentation/media/uapi/rc/lirc-read.rst
index 4c678f60e872..ff14a69104e5 100644
--- a/Documentation/media/uapi/rc/lirc-read.rst
+++ b/Documentation/media/uapi/rc/lirc-read.rst
@@ -44,17 +44,13 @@ descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero,
:ref:`read() <lirc-read>` returns zero and has no other results. If ``count``
is greater than ``SSIZE_MAX``, the result is unspecified.
-The lircd userspace daemon reads raw IR data from the LIRC chardev. The
-exact format of the data depends on what modes a driver supports, and
-what mode has been selected. lircd obtains supported modes and sets the
-active mode via the ioctl interface, detailed at :ref:`lirc_func`.
-The generally preferred mode for receive is
-:ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`, in which packets containing an
-int value describing an IR signal are read from the chardev.
+The exact format of the data depends on what :ref:`lirc_modes` a driver
+uses. Use :ref:`lirc_get_features` to get the supported mode.
-See also
-`http://www.lirc.org/html/technical.html <http://www.lirc.org/html/technical.html>`__
-for more info.
+The generally preferred mode for receive is
+:ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>`,
+in which packets containing an int value describing an IR signal are
+read from the chardev.
Return Value
============
diff --git a/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst b/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst
index a83fbbfa0d3b..a89246806c4b 100644
--- a/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst
+++ b/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst
@@ -9,7 +9,7 @@ ioctl LIRC_SET_REC_CARRIER_RANGE
Name
====
-LIRC_SET_REC_CARRIER_RANGE - Set lower bond of the carrier used to modulate
+LIRC_SET_REC_CARRIER_RANGE - Set lower bound of the carrier used to modulate
IR receive.
Synopsis
diff --git a/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst b/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst
index 9c501bbf4c62..86353e602695 100644
--- a/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst
+++ b/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst
@@ -31,6 +31,8 @@ Arguments
Description
===========
+.. _lirc-mode2-timeout:
+
Enable or disable timeout reports for IR receive. By default, timeout reports
should be turned off.
diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst
index 3b035c6613b1..2aad0fef4a5b 100644
--- a/Documentation/media/uapi/rc/lirc-write.rst
+++ b/Documentation/media/uapi/rc/lirc-write.rst
@@ -42,13 +42,16 @@ Description
referenced by the file descriptor ``fd`` from the buffer starting at
``buf``.
-The data written to the chardev is a pulse/space sequence of integer
-values. Pulses and spaces are only marked implicitly by their position.
-The data must start and end with a pulse, therefore, the data must
-always include an uneven number of samples. The write function must
-block until the data has been transmitted by the hardware. If more data
-is provided than the hardware can send, the driver returns ``EINVAL``.
-
+The exact format of the data depends on what mode a driver uses, use
+:ref:`lirc_get_features` to get the supported mode.
+
+When in :ref:`LIRC_MODE_PULSE <lirc-mode-PULSE>` mode, the data written to
+the chardev is a pulse/space sequence of integer values. Pulses and spaces
+are only marked implicitly by their position. The data must start and end
+with a pulse, therefore, the data must always include an uneven number of
+samples. The write function must block until the data has been transmitted
+by the hardware. If more data is provided than the hardware can send, the
+driver returns ``EINVAL``.
Return Value
============
diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst
index ac58966ccb9b..ae6ee73f151c 100644
--- a/Documentation/media/uapi/v4l/buffer.rst
+++ b/Documentation/media/uapi/v4l/buffer.rst
@@ -34,6 +34,125 @@ flags are copied from the OUTPUT video buffer to the CAPTURE video
buffer.
+Interactions between formats, controls and buffers
+==================================================
+
+V4L2 exposes parameters that influence the buffer size, or the way data is
+laid out in the buffer. Those parameters are exposed through both formats and
+controls. One example of such a control is the ``V4L2_CID_ROTATE`` control
+that modifies the direction in which pixels are stored in the buffer, as well
+as the buffer size when the selected format includes padding at the end of
+lines.
+
+The set of information needed to interpret the content of a buffer (e.g. the
+pixel format, the line stride, the tiling orientation or the rotation) is
+collectively referred to in the rest of this section as the buffer layout.
+
+Controls that can modify the buffer layout shall set the
+``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` flag.
+
+Modifying formats or controls that influence the buffer size or layout require
+the stream to be stopped. Any attempt at such a modification while the stream
+is active shall cause the ioctl setting the format or the control to return
+the ``EBUSY`` error code. In that case drivers shall also set the
+``V4L2_CTRL_FLAG_GRABBED`` flag when calling
+:c:func:`VIDIOC_QUERYCTRL` or :c:func:`VIDIOC_QUERY_EXT_CTRL` for such a
+control while the stream is active.
+
+.. note::
+
+ The :c:func:`VIDIOC_S_SELECTION` ioctl can, depending on the hardware (for
+ instance if the device doesn't include a scaler), modify the format in
+ addition to the selection rectangle. Similarly, the
+ :c:func:`VIDIOC_S_INPUT`, :c:func:`VIDIOC_S_OUTPUT`, :c:func:`VIDIOC_S_STD`
+ and :c:func:`VIDIOC_S_DV_TIMINGS` ioctls can also modify the format and
+ selection rectangles. When those ioctls result in a buffer size or layout
+ change, drivers shall handle that condition as they would handle it in the
+ :c:func:`VIDIOC_S_FMT` ioctl in all cases described in this section.
+
+Controls that only influence the buffer layout can be modified at any time
+when the stream is stopped. As they don't influence the buffer size, no
+special handling is needed to synchronize those controls with buffer
+allocation and the ``V4L2_CTRL_FLAG_GRABBED`` flag is cleared once the
+stream is stopped.
+
+Formats and controls that influence the buffer size interact with buffer
+allocation. The simplest way to handle this is for drivers to always require
+buffers to be reallocated in order to change those formats or controls. In
+that case, to perform such changes, userspace applications shall first stop
+the video stream with the :c:func:`VIDIOC_STREAMOFF` ioctl if it is running
+and free all buffers with the :c:func:`VIDIOC_REQBUFS` ioctl if they are
+allocated. After freeing all buffers the ``V4L2_CTRL_FLAG_GRABBED`` flag
+for controls is cleared. The format or controls can then be modified, and
+buffers shall then be reallocated and the stream restarted. A typical ioctl
+sequence is
+
+ #. VIDIOC_STREAMOFF
+ #. VIDIOC_REQBUFS(0)
+ #. VIDIOC_S_EXT_CTRLS
+ #. VIDIOC_S_FMT
+ #. VIDIOC_REQBUFS(n)
+ #. VIDIOC_QBUF
+ #. VIDIOC_STREAMON
+
+The second :c:func:`VIDIOC_REQBUFS` call will take the new format and control
+value into account to compute the buffer size to allocate. Applications can
+also retrieve the size by calling the :c:func:`VIDIOC_G_FMT` ioctl if needed.
+
+.. note::
+
+ The API doesn't mandate the above order for control (3.) and format (4.)
+ changes. Format and controls can be set in a different order, or even
+ interleaved, depending on the device and use case. For instance some
+ controls might behave differently for different pixel formats, in which
+ case the format might need to be set first.
+
+When reallocation is required, any attempt to modify format or controls that
+influences the buffer size while buffers are allocated shall cause the format
+or control set ioctl to return the ``EBUSY`` error. Any attempt to queue a
+buffer too small for the current format or controls shall cause the
+:c:func:`VIDIOC_QBUF` ioctl to return a ``EINVAL`` error.
+
+Buffer reallocation is an expensive operation. To avoid that cost, drivers can
+(and are encouraged to) allow format or controls that influence the buffer
+size to be changed with buffers allocated. In that case, a typical ioctl
+sequence to modify format and controls is
+
+ #. VIDIOC_STREAMOFF
+ #. VIDIOC_S_EXT_CTRLS
+ #. VIDIOC_S_FMT
+ #. VIDIOC_QBUF
+ #. VIDIOC_STREAMON
+
+For this sequence to operate correctly, queued buffers need to be large enough
+for the new format or controls. Drivers shall return a ``ENOSPC`` error in
+response to format change (:c:func:`VIDIOC_S_FMT`) or control changes
+(:c:func:`VIDIOC_S_CTRL` or :c:func:`VIDIOC_S_EXT_CTRLS`) if buffers too small
+for the new format are currently queued. As a simplification, drivers are
+allowed to return a ``EBUSY`` error from these ioctls if any buffer is
+currently queued, without checking the queued buffers sizes.
+
+Additionally, drivers shall return a ``EINVAL`` error from the
+:c:func:`VIDIOC_QBUF` ioctl if the buffer being queued is too small for the
+current format or controls. Together, these requirements ensure that queued
+buffers will always be large enough for the configured format and controls.
+
+Userspace applications can query the buffer size required for a given format
+and controls by first setting the desired control values and then trying the
+desired format. The :c:func:`VIDIOC_TRY_FMT` ioctl will return the required
+buffer size.
+
+ #. VIDIOC_S_EXT_CTRLS(x)
+ #. VIDIOC_TRY_FMT()
+ #. VIDIOC_S_EXT_CTRLS(y)
+ #. VIDIOC_TRY_FMT()
+
+The :c:func:`VIDIOC_CREATE_BUFS` ioctl can then be used to allocate buffers
+based on the queried sizes (for instance by allocating a set of buffers large
+enough for all the desired formats and controls, or by allocating separate set
+of appropriately sized buffers for each use case).
+
+
.. c:type:: v4l2_buffer
struct v4l2_buffer
@@ -330,6 +449,9 @@ enum v4l2_buf_type
- 12
- Buffer for Software Defined Radio (SDR) output stream, see
:ref:`sdr`.
+ * - ``V4L2_BUF_TYPE_META_CAPTURE``
+ - 13
+ - Buffer for metadata capture, see :ref:`metadata`.
diff --git a/Documentation/media/uapi/v4l/depth-formats.rst b/Documentation/media/uapi/v4l/depth-formats.rst
index 82f183870aae..d1641e9687a6 100644
--- a/Documentation/media/uapi/v4l/depth-formats.rst
+++ b/Documentation/media/uapi/v4l/depth-formats.rst
@@ -12,4 +12,5 @@ Depth data provides distance to points, mapped onto the image plane
.. toctree::
:maxdepth: 1
+ pixfmt-inzi
pixfmt-z16
diff --git a/Documentation/media/uapi/v4l/dev-capture.rst b/Documentation/media/uapi/v4l/dev-capture.rst
index 32b32055d070..4218742ab5d9 100644
--- a/Documentation/media/uapi/v4l/dev-capture.rst
+++ b/Documentation/media/uapi/v4l/dev-capture.rst
@@ -42,8 +42,8 @@ Video capture devices shall support :ref:`audio input <audio>`,
:ref:`tuner`, :ref:`controls <control>`,
:ref:`cropping and scaling <crop>` and
:ref:`streaming parameter <streaming-par>` ioctls as needed. The
-:ref:`video input <video>` and :ref:`video standard <standard>`
-ioctls must be supported by all video capture devices.
+:ref:`video input <video>` ioctls must be supported by all video
+capture devices.
Image Format Negotiation
diff --git a/Documentation/media/uapi/v4l/dev-meta.rst b/Documentation/media/uapi/v4l/dev-meta.rst
new file mode 100644
index 000000000000..62518adfe37b
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-meta.rst
@@ -0,0 +1,58 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _metadata:
+
+******************
+Metadata Interface
+******************
+
+Metadata refers to any non-image data that supplements video frames with
+additional information. This may include statistics computed over the image
+or frame capture parameters supplied by the image source. This interface is
+intended for transfer of metadata to userspace and control of that operation.
+
+The metadata interface is implemented on video capture device nodes. The device
+can be dedicated to metadata or can implement both video and metadata capture
+as specified in its reported capabilities.
+
+Querying Capabilities
+=====================
+
+Device nodes supporting the metadata interface set the ``V4L2_CAP_META_CAPTURE``
+flag in the ``device_caps`` field of the
+:c:type:`v4l2_capability` structure returned by the :c:func:`VIDIOC_QUERYCAP`
+ioctl. That flag means the device can capture metadata to memory.
+
+At least one of the read/write or streaming I/O methods must be supported.
+
+
+Data Format Negotiation
+=======================
+
+The metadata device uses the :ref:`format` ioctls to select the capture format.
+The metadata buffer content format is bound to that selected format. In addition
+to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be
+supported as well.
+
+To use the :ref:`format` ioctls applications set the ``type`` field of the
+:c:type:`v4l2_format` structure to ``V4L2_BUF_TYPE_META_CAPTURE`` and use the
+:c:type:`v4l2_meta_format` ``meta`` member of the ``fmt`` union as needed per
+the desired operation. Both drivers and applications must set the remainder of
+the :c:type:`v4l2_format` structure to 0.
+
+.. _v4l2-meta-format:
+
+.. flat-table:: struct v4l2_meta_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+ * - __u32
+ - ``dataformat``
+ - The data format, set by the application. This is a little endian
+ :ref:`four character code <v4l2-fourcc>`. V4L2 defines metadata formats
+ in :ref:`meta-formats`.
+ * - __u32
+ - ``buffersize``
+ - Maximum buffer size in bytes required for data. The value is set by the
+ driver.
diff --git a/Documentation/media/uapi/v4l/dev-output.rst b/Documentation/media/uapi/v4l/dev-output.rst
index 25ae8ec96fdf..342eb4931f5c 100644
--- a/Documentation/media/uapi/v4l/dev-output.rst
+++ b/Documentation/media/uapi/v4l/dev-output.rst
@@ -40,8 +40,8 @@ Video output devices shall support :ref:`audio output <audio>`,
:ref:`modulator <tuner>`, :ref:`controls <control>`,
:ref:`cropping and scaling <crop>` and
:ref:`streaming parameter <streaming-par>` ioctls as needed. The
-:ref:`video output <video>` and :ref:`video standard <standard>`
-ioctls must be supported by all video output devices.
+:ref:`video output <video>` ioctls must be supported by all video
+output devices.
Image Format Negotiation
diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst
index 5c3d6c29e12c..fb7f8c26cf09 100644
--- a/Documentation/media/uapi/v4l/devices.rst
+++ b/Documentation/media/uapi/v4l/devices.rst
@@ -25,3 +25,4 @@ Interfaces
dev-touch
dev-event
dev-subdev
+ dev-meta
diff --git a/Documentation/media/uapi/v4l/meta-formats.rst b/Documentation/media/uapi/v4l/meta-formats.rst
new file mode 100644
index 000000000000..01e24e3df571
--- /dev/null
+++ b/Documentation/media/uapi/v4l/meta-formats.rst
@@ -0,0 +1,16 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _meta-formats:
+
+****************
+Metadata Formats
+****************
+
+These formats are used for the :ref:`metadata` interface only.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-meta-vsp1-hgo
+ pixfmt-meta-vsp1-hgt
diff --git a/Documentation/media/uapi/v4l/pixfmt-007.rst b/Documentation/media/uapi/v4l/pixfmt-007.rst
index 95a23a28c595..0c30ee2577d3 100644
--- a/Documentation/media/uapi/v4l/pixfmt-007.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-007.rst
@@ -174,7 +174,7 @@ this colorspace:
The xvYCC 709 encoding (``V4L2_YCBCR_ENC_XV709``, :ref:`xvycc`) is
similar to the Rec. 709 encoding, but it allows for R', G' and B' values
that are outside the range [0…1]. The resulting Y', Cb and Cr values are
-scaled and offset:
+scaled and offset according to the limited range formula:
.. math::
@@ -187,7 +187,7 @@ scaled and offset:
The xvYCC 601 encoding (``V4L2_YCBCR_ENC_XV601``, :ref:`xvycc`) is
similar to the BT.601 encoding, but it allows for R', G' and B' values
that are outside the range [0…1]. The resulting Y', Cb and Cr values are
-scaled and offset:
+scaled and offset according to the limited range formula:
.. math::
@@ -198,9 +198,14 @@ scaled and offset:
Cr = \frac{224}{256} * (0.5R' - 0.4187G' - 0.0813B')
Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be
+[-0.5…0.5] and quantized without further scaling or offsets.
+The non-standard xvYCC 709 or xvYCC 601 encodings can be
used by selecting ``V4L2_YCBCR_ENC_XV709`` or ``V4L2_YCBCR_ENC_XV601``.
-The xvYCC encodings always use full range quantization.
+As seen by the xvYCC formulas these encodings always use limited range quantization,
+there is no full range variant. The whole point of these extended gamut encodings
+is that values outside the limited range are still valid, although they
+map to R', G' and B' values outside the [0…1] range and are therefore outside
+the Rec. 709 colorspace gamut.
.. _col-srgb:
diff --git a/Documentation/media/uapi/v4l/pixfmt-inzi.rst b/Documentation/media/uapi/v4l/pixfmt-inzi.rst
new file mode 100644
index 000000000000..9849e799f205
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-inzi.rst
@@ -0,0 +1,81 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-INZI:
+
+**************************
+V4L2_PIX_FMT_INZI ('INZI')
+**************************
+
+Infrared 10-bit linked with Depth 16-bit images
+
+
+Description
+===========
+
+Proprietary multi-planar format used by Intel SR300 Depth cameras, comprise of
+Infrared image followed by Depth data. The pixel definition is 32-bpp,
+with the Depth and Infrared Data split into separate continuous planes of
+identical dimensions.
+
+
+
+The first plane - Infrared data - is stored according to
+:ref:`V4L2_PIX_FMT_Y10 <V4L2-PIX-FMT-Y10>` greyscale format.
+Each pixel is 16-bit cell, with actual data stored in the 10 LSBs
+with values in range 0 to 1023.
+The six remaining MSBs are padded with zeros.
+
+
+The second plane provides 16-bit per-pixel Depth data arranged in
+:ref:`V4L2-PIX-FMT-Z16 <V4L2-PIX-FMT-Z16>` format.
+
+
+**Frame Structure.**
+Each cell is a 16-bit word with more significant data stored at higher
+memory address (byte order is little-endian).
+
+.. raw:: latex
+
+ \newline\newline\begin{adjustbox}{width=\columnwidth}
+
+.. tabularcolumns:: |p{4.0cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}|
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 1
+ :widths: 1 1 1 1 1 1
+
+ * - Ir\ :sub:`0,0`
+ - Ir\ :sub:`0,1`
+ - Ir\ :sub:`0,2`
+ - ...
+ - ...
+ - ...
+ * - :cspan:`5` ...
+ * - :cspan:`5` Infrared Data
+ * - :cspan:`5` ...
+ * - ...
+ - ...
+ - ...
+ - Ir\ :sub:`n-1,n-3`
+ - Ir\ :sub:`n-1,n-2`
+ - Ir\ :sub:`n-1,n-1`
+ * - Depth\ :sub:`0,0`
+ - Depth\ :sub:`0,1`
+ - Depth\ :sub:`0,2`
+ - ...
+ - ...
+ - ...
+ * - :cspan:`5` ...
+ * - :cspan:`5` Depth Data
+ * - :cspan:`5` ...
+ * - ...
+ - ...
+ - ...
+ - Depth\ :sub:`n-1,n-3`
+ - Depth\ :sub:`n-1,n-2`
+ - Depth\ :sub:`n-1,n-1`
+
+.. raw:: latex
+
+ \end{adjustbox}\newline\newline
diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst
new file mode 100644
index 000000000000..67796594fd48
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst
@@ -0,0 +1,168 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-meta-fmt-vsp1-hgo:
+
+*******************************
+V4L2_META_FMT_VSP1_HGO ('VSPH')
+*******************************
+
+Renesas R-Car VSP1 1-D Histogram Data
+
+
+Description
+===========
+
+This format describes histogram data generated by the Renesas R-Car VSP1 1-D
+Histogram (HGO) engine.
+
+The VSP1 HGO is a histogram computation engine that can operate on RGB, YCrCb
+or HSV data. It operates on a possibly cropped and subsampled input image and
+computes the minimum, maximum and sum of all pixels as well as per-channel
+histograms.
+
+The HGO can compute histograms independently per channel, on the maximum of the
+three channels (RGB data only) or on the Y channel only (YCbCr only). It can
+additionally output the histogram with 64 or 256 bins, resulting in four
+possible modes of operation.
+
+- In *64 bins normal mode*, the HGO operates on the three channels independently
+ to compute three 64-bins histograms. RGB, YCbCr and HSV image formats are
+ supported.
+- In *64 bins maximum mode*, the HGO operates on the maximum of the (R, G, B)
+ channels to compute a single 64-bins histogram. Only the RGB image format is
+ supported.
+- In *256 bins normal mode*, the HGO operates on the Y channel to compute a
+ single 256-bins histogram. Only the YCbCr image format is supported.
+- In *256 bins maximum mode*, the HGO operates on the maximum of the (R, G, B)
+ channels to compute a single 256-bins histogram. Only the RGB image format is
+ supported.
+
+**Byte Order.**
+All data is stored in memory in little endian format. Each cell in the tables
+contains one byte.
+
+.. flat-table:: VSP1 HGO Data - 64 Bins, Normal Mode (792 bytes)
+ :header-rows: 2
+ :stub-columns: 0
+
+ * - Offset
+ - :cspan:`4` Memory
+ * -
+ - [31:24]
+ - [23:16]
+ - [15:8]
+ - [7:0]
+ * - 0
+ -
+ - R/Cr/H max [7:0]
+ -
+ - R/Cr/H min [7:0]
+ * - 4
+ -
+ - G/Y/S max [7:0]
+ -
+ - G/Y/S min [7:0]
+ * - 8
+ -
+ - B/Cb/V max [7:0]
+ -
+ - B/Cb/V min [7:0]
+ * - 12
+ - :cspan:`4` R/Cr/H sum [31:0]
+ * - 16
+ - :cspan:`4` G/Y/S sum [31:0]
+ * - 20
+ - :cspan:`4` B/Cb/V sum [31:0]
+ * - 24
+ - :cspan:`4` R/Cr/H bin 0 [31:0]
+ * -
+ - :cspan:`4` ...
+ * - 276
+ - :cspan:`4` R/Cr/H bin 63 [31:0]
+ * - 280
+ - :cspan:`4` G/Y/S bin 0 [31:0]
+ * -
+ - :cspan:`4` ...
+ * - 532
+ - :cspan:`4` G/Y/S bin 63 [31:0]
+ * - 536
+ - :cspan:`4` B/Cb/V bin 0 [31:0]
+ * -
+ - :cspan:`4` ...
+ * - 788
+ - :cspan:`4` B/Cb/V bin 63 [31:0]
+
+.. flat-table:: VSP1 HGO Data - 64 Bins, Max Mode (264 bytes)
+ :header-rows: 2
+ :stub-columns: 0
+
+ * - Offset
+ - :cspan:`4` Memory
+ * -
+ - [31:24]
+ - [23:16]
+ - [15:8]
+ - [7:0]
+ * - 0
+ -
+ - max(R,G,B) max [7:0]
+ -
+ - max(R,G,B) min [7:0]
+ * - 4
+ - :cspan:`4` max(R,G,B) sum [31:0]
+ * - 8
+ - :cspan:`4` max(R,G,B) bin 0 [31:0]
+ * -
+ - :cspan:`4` ...
+ * - 260
+ - :cspan:`4` max(R,G,B) bin 63 [31:0]
+
+.. flat-table:: VSP1 HGO Data - 256 Bins, Normal Mode (1032 bytes)
+ :header-rows: 2
+ :stub-columns: 0
+
+ * - Offset
+ - :cspan:`4` Memory
+ * -
+ - [31:24]
+ - [23:16]
+ - [15:8]
+ - [7:0]
+ * - 0
+ -
+ - Y max [7:0]
+ -
+ - Y min [7:0]
+ * - 4
+ - :cspan:`4` Y sum [31:0]
+ * - 8
+ - :cspan:`4` Y bin 0 [31:0]
+ * -
+ - :cspan:`4` ...
+ * - 1028
+ - :cspan:`4` Y bin 255 [31:0]
+
+.. flat-table:: VSP1 HGO Data - 256 Bins, Max Mode (1032 bytes)
+ :header-rows: 2
+ :stub-columns: 0
+
+ * - Offset
+ - :cspan:`4` Memory
+ * -
+ - [31:24]
+ - [23:16]
+ - [15:8]
+ - [7:0]
+ * - 0
+ -
+ - max(R,G,B) max [7:0]
+ -
+ - max(R,G,B) min [7:0]
+ * - 4
+ - :cspan:`4` max(R,G,B) sum [31:0]
+ * - 8
+ - :cspan:`4` max(R,G,B) bin 0 [31:0]
+ * -
+ - :cspan:`4` ...
+ * - 1028
+ - :cspan:`4` max(R,G,B) bin 255 [31:0]
diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst
new file mode 100644
index 000000000000..fb9f79466319
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst
@@ -0,0 +1,120 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-meta-fmt-vsp1-hgt:
+
+*******************************
+V4L2_META_FMT_VSP1_HGT ('VSPT')
+*******************************
+
+Renesas R-Car VSP1 2-D Histogram Data
+
+
+Description
+===========
+
+This format describes histogram data generated by the Renesas R-Car VSP1
+2-D Histogram (HGT) engine.
+
+The VSP1 HGT is a histogram computation engine that operates on HSV
+data. It operates on a possibly cropped and subsampled input image and
+computes the sum, maximum and minimum of the S component as well as a
+weighted frequency histogram based on the H and S components.
+
+The histogram is a matrix of 6 Hue and 32 Saturation buckets, 192 in
+total. Each HSV value is added to one or more buckets with a weight
+between 1 and 16 depending on the Hue areas configuration. Finding the
+corresponding buckets is done by inspecting the H and S value independently.
+
+The Saturation position **n** (0 - 31) of the bucket in the matrix is
+found by the expression:
+
+ n = S / 8
+
+The Hue position **m** (0 - 5) of the bucket in the matrix depends on
+how the HGT Hue areas are configured. There are 6 user configurable Hue
+Areas which can be configured to cover overlapping Hue values:
+
+::
+
+ Area 0 Area 1 Area 2 Area 3 Area 4 Area 5
+ ________ ________ ________ ________ ________ ________
+ \ /| |\ /| |\ /| |\ /| |\ /| |\ /| |\ /
+ \ / | | \ / | | \ / | | \ / | | \ / | | \ / | | \ /
+ X | | X | | X | | X | | X | | X | | X
+ / \ | | / \ | | / \ | | / \ | | / \ | | / \ | | / \
+ / \| |/ \| |/ \| |/ \| |/ \| |/ \| |/ \
+ 5U 0L 0U 1L 1U 2L 2U 3L 3U 4L 4U 5L 5U 0L
+ <0..............................Hue Value............................255>
+
+When two consecutive areas don't overlap (n+1L is equal to nU) the boundary
+value is considered as part of the lower area.
+
+Pixels with a hue value included in the centre of an area (between nL and nU
+included) are attributed to that single area and given a weight of 16. Pixels
+with a hue value included in the overlapping region between two areas (between
+n+1L and nU excluded) are attributed to both areas and given a weight for each
+of these areas proportional to their position along the diagonal lines
+(rounded down).
+
+The Hue area setup must match one of the following constrains:
+
+::
+
+ 0L <= 0U <= 1L <= 1U <= 2L <= 2U <= 3L <= 3U <= 4L <= 4U <= 5L <= 5U
+
+::
+
+ 0U <= 1L <= 1U <= 2L <= 2U <= 3L <= 3U <= 4L <= 4U <= 5L <= 5U <= 0L
+
+**Byte Order.**
+All data is stored in memory in little endian format. Each cell in the tables
+contains one byte.
+
+.. flat-table:: VSP1 HGT Data - (776 bytes)
+ :header-rows: 2
+ :stub-columns: 0
+
+ * - Offset
+ - :cspan:`4` Memory
+ * -
+ - [31:24]
+ - [23:16]
+ - [15:8]
+ - [7:0]
+ * - 0
+ - -
+ - S max [7:0]
+ - -
+ - S min [7:0]
+ * - 4
+ - :cspan:`4` S sum [31:0]
+ * - 8
+ - :cspan:`4` Histogram bucket (m=0, n=0) [31:0]
+ * - 12
+ - :cspan:`4` Histogram bucket (m=0, n=1) [31:0]
+ * -
+ - :cspan:`4` ...
+ * - 132
+ - :cspan:`4` Histogram bucket (m=0, n=31) [31:0]
+ * - 136
+ - :cspan:`4` Histogram bucket (m=1, n=0) [31:0]
+ * -
+ - :cspan:`4` ...
+ * - 264
+ - :cspan:`4` Histogram bucket (m=2, n=0) [31:0]
+ * -
+ - :cspan:`4` ...
+ * - 392
+ - :cspan:`4` Histogram bucket (m=3, n=0) [31:0]
+ * -
+ - :cspan:`4` ...
+ * - 520
+ - :cspan:`4` Histogram bucket (m=4, n=0) [31:0]
+ * -
+ - :cspan:`4` ...
+ * - 648
+ - :cspan:`4` Histogram bucket (m=5, n=0) [31:0]
+ * -
+ - :cspan:`4` ...
+ * - 772
+ - :cspan:`4` Histogram bucket (m=5, n=31) [31:0]
diff --git a/Documentation/media/uapi/v4l/pixfmt.rst b/Documentation/media/uapi/v4l/pixfmt.rst
index 4f184c7aedab..00737152497b 100644
--- a/Documentation/media/uapi/v4l/pixfmt.rst
+++ b/Documentation/media/uapi/v4l/pixfmt.rst
@@ -34,4 +34,5 @@ see also :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`.)
pixfmt-013
sdr-formats
tch-formats
+ meta-formats
pixfmt-reserved
diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst
index 09e2798b4966..8e73bb00c0d5 100644
--- a/Documentation/media/uapi/v4l/subdev-formats.rst
+++ b/Documentation/media/uapi/v4l/subdev-formats.rst
@@ -1890,10 +1890,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- b\ :sub:`7`
- b\ :sub:`6`
- b\ :sub:`5`
@@ -1911,10 +1911,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- g\ :sub:`7`
- g\ :sub:`6`
- g\ :sub:`5`
@@ -1932,10 +1932,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- g\ :sub:`7`
- g\ :sub:`6`
- g\ :sub:`5`
@@ -1953,10 +1953,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- r\ :sub:`7`
- r\ :sub:`6`
- r\ :sub:`5`
@@ -1974,10 +1974,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- b\ :sub:`7`
- b\ :sub:`6`
- b\ :sub:`5`
@@ -1995,10 +1995,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- g\ :sub:`7`
- g\ :sub:`6`
- g\ :sub:`5`
@@ -2016,10 +2016,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- g\ :sub:`7`
- g\ :sub:`6`
- g\ :sub:`5`
@@ -2037,10 +2037,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- r\ :sub:`7`
- r\ :sub:`6`
- r\ :sub:`5`
@@ -2058,10 +2058,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- b\ :sub:`7`
- b\ :sub:`6`
- b\ :sub:`5`
@@ -2079,10 +2079,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- g\ :sub:`7`
- g\ :sub:`6`
- g\ :sub:`5`
@@ -2100,10 +2100,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- g\ :sub:`7`
- g\ :sub:`6`
- g\ :sub:`5`
@@ -2121,10 +2121,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- r\ :sub:`7`
- r\ :sub:`6`
- r\ :sub:`5`
@@ -2142,10 +2142,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- 0
- 0
- 0
@@ -2161,10 +2161,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- b\ :sub:`7`
- b\ :sub:`6`
- b\ :sub:`5`
@@ -2182,10 +2182,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- b\ :sub:`7`
- b\ :sub:`6`
- b\ :sub:`5`
@@ -2201,10 +2201,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- 0
- 0
- 0
@@ -2222,10 +2222,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- b\ :sub:`9`
- b\ :sub:`8`
- b\ :sub:`7`
@@ -2241,10 +2241,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- b\ :sub:`1`
- b\ :sub:`0`
- 0
@@ -2262,10 +2262,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- b\ :sub:`1`
- b\ :sub:`0`
- 0
@@ -2281,10 +2281,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- b\ :sub:`9`
- b\ :sub:`8`
- b\ :sub:`7`
@@ -2300,10 +2300,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- b\ :sub:`9`
- b\ :sub:`8`
- b\ :sub:`7`
@@ -2321,10 +2321,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- g\ :sub:`9`
- g\ :sub:`8`
- g\ :sub:`7`
@@ -2342,10 +2342,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- g\ :sub:`9`
- g\ :sub:`8`
- g\ :sub:`7`
@@ -2363,10 +2363,10 @@ organization is given as an example for the first pixel only.
-
-
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- r\ :sub:`9`
- r\ :sub:`8`
- r\ :sub:`7`
@@ -2382,10 +2382,10 @@ organization is given as an example for the first pixel only.
- MEDIA_BUS_FMT_SBGGR12_1X12
- 0x3008
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- b\ :sub:`11`
- b\ :sub:`10`
- b\ :sub:`9`
@@ -2403,10 +2403,10 @@ organization is given as an example for the first pixel only.
- MEDIA_BUS_FMT_SGBRG12_1X12
- 0x3010
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- g\ :sub:`11`
- g\ :sub:`10`
- g\ :sub:`9`
@@ -2424,10 +2424,10 @@ organization is given as an example for the first pixel only.
- MEDIA_BUS_FMT_SGRBG12_1X12
- 0x3011
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- g\ :sub:`11`
- g\ :sub:`10`
- g\ :sub:`9`
@@ -2445,10 +2445,10 @@ organization is given as an example for the first pixel only.
- MEDIA_BUS_FMT_SRGGB12_1X12
- 0x3012
-
- - -
- - -
- - -
- - -
+ -
+ -
+ -
+ -
- r\ :sub:`11`
- r\ :sub:`10`
- r\ :sub:`9`
@@ -2466,8 +2466,8 @@ organization is given as an example for the first pixel only.
- MEDIA_BUS_FMT_SBGGR14_1X14
- 0x3019
-
- - -
- - -
+ -
+ -
- b\ :sub:`13`
- b\ :sub:`12`
- b\ :sub:`11`
@@ -2487,8 +2487,8 @@ organization is given as an example for the first pixel only.
- MEDIA_BUS_FMT_SGBRG14_1X14
- 0x301a
-
- - -
- - -
+ -
+ -
- g\ :sub:`13`
- g\ :sub:`12`
- g\ :sub:`11`
@@ -2508,8 +2508,8 @@ organization is given as an example for the first pixel only.
- MEDIA_BUS_FMT_SGRBG14_1X14
- 0x301b
-
- - -
- - -
+ -
+ -
- g\ :sub:`13`
- g\ :sub:`12`
- g\ :sub:`11`
@@ -2529,8 +2529,8 @@ organization is given as an example for the first pixel only.
- MEDIA_BUS_FMT_SRGGB14_1X14
- 0x301c
-
- - -
- - -
+ -
+ -
- r\ :sub:`13`
- r\ :sub:`12`
- r\ :sub:`11`
diff --git a/Documentation/media/uapi/v4l/video.rst b/Documentation/media/uapi/v4l/video.rst
index a205fb87d566..d2bc06b064ad 100644
--- a/Documentation/media/uapi/v4l/video.rst
+++ b/Documentation/media/uapi/v4l/video.rst
@@ -8,9 +8,10 @@ Video Inputs and Outputs
Video inputs and outputs are physical connectors of a device. These can
be for example RF connectors (antenna/cable), CVBS a.k.a. Composite
-Video, S-Video or RGB connectors. Video and VBI capture devices have
-inputs. Video and VBI output devices have outputs, at least one each.
-Radio devices have no video inputs or outputs.
+Video, S-Video and RGB connectors. Camera sensors are also considered to
+be a video input. Video and VBI capture devices have inputs. Video and
+VBI output devices have outputs, at least one each. Radio devices have
+no video inputs or outputs.
To learn about the number and attributes of the available inputs and
outputs applications can enumerate them with the
diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
index 17aaaf939757..266e48ab237f 100644
--- a/Documentation/media/uapi/v4l/vidioc-enuminput.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
@@ -33,7 +33,7 @@ Description
To query the attributes of a video input applications initialize the
``index`` field of struct :c:type:`v4l2_input` and call the
-:ref:`VIDIOC_ENUMINPUT` ioctl with a pointer to this structure. Drivers
+:ref:`VIDIOC_ENUMINPUT` with a pointer to this structure. Drivers
fill the rest of the structure or return an ``EINVAL`` error code when the
index is out of bounds. To enumerate all inputs applications shall begin
at index zero, incrementing by one until the driver returns ``EINVAL``.
@@ -117,8 +117,9 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
- This input uses a tuner (RF demodulator).
* - ``V4L2_INPUT_TYPE_CAMERA``
- 2
- - Analog baseband input, for example CVBS / Composite Video,
- S-Video, RGB.
+ - Any non-tuner video input, for example Composite Video,
+ S-Video, HDMI, camera sensor. The naming as ``_TYPE_CAMERA`` is historical,
+ today we would have called it ``_TYPE_VIDEO``.
* - ``V4L2_INPUT_TYPE_TOUCH``
- 3
- This input is a touch device for capturing raw touch data.
@@ -209,11 +210,11 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
* - ``V4L2_IN_CAP_DV_TIMINGS``
- 0x00000002
- This input supports setting video timings by using
- VIDIOC_S_DV_TIMINGS.
+ ``VIDIOC_S_DV_TIMINGS``.
* - ``V4L2_IN_CAP_STD``
- 0x00000004
- This input supports setting the TV standard by using
- VIDIOC_S_STD.
+ ``VIDIOC_S_STD``.
* - ``V4L2_IN_CAP_NATIVE_SIZE``
- 0x00000008
- This input supports setting the native size using the
diff --git a/Documentation/media/uapi/v4l/vidioc-enumoutput.rst b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst
index d7dd2742475a..93a2cf3b310c 100644
--- a/Documentation/media/uapi/v4l/vidioc-enumoutput.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst
@@ -33,11 +33,11 @@ Description
To query the attributes of a video outputs applications initialize the
``index`` field of struct :c:type:`v4l2_output` and call
-the :ref:`VIDIOC_ENUMOUTPUT` ioctl with a pointer to this structure.
+the :ref:`VIDIOC_ENUMOUTPUT` with a pointer to this structure.
Drivers fill the rest of the structure or return an ``EINVAL`` error code
when the index is out of bounds. To enumerate all outputs applications
shall begin at index zero, incrementing by one until the driver returns
-EINVAL.
+``EINVAL``.
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -112,11 +112,12 @@ EINVAL.
- This output is an analog TV modulator.
* - ``V4L2_OUTPUT_TYPE_ANALOG``
- 2
- - Analog baseband output, for example Composite / CVBS, S-Video,
- RGB.
+ - Any non-modulator video output, for example Composite Video,
+ S-Video, HDMI. The naming as ``_TYPE_ANALOG`` is historical,
+ today we would have called it ``_TYPE_VIDEO``.
* - ``V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY``
- 3
- - [?]
+ - The video output will be copied to a :ref:`video overlay <overlay>`.
@@ -132,11 +133,11 @@ EINVAL.
* - ``V4L2_OUT_CAP_DV_TIMINGS``
- 0x00000002
- This output supports setting video timings by using
- VIDIOC_S_DV_TIMINGS.
+ ``VIDIOC_S_DV_TIMINGS``.
* - ``V4L2_OUT_CAP_STD``
- 0x00000004
- This output supports setting the TV standard by using
- VIDIOC_S_STD.
+ ``VIDIOC_S_STD``.
* - ``V4L2_OUT_CAP_NATIVE_SIZE``
- 0x00000008
- This output supports setting the native size using the
diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
index aea276502f5e..e573c74138de 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
@@ -146,8 +146,20 @@ EBUSY
- ``flags``
- Several flags giving more information about the format. See
:ref:`dv-bt-flags` for a description of the flags.
- * - __u32
- - ``reserved[14]``
+ * - struct :c:type:`v4l2_fract`
+ - ``picture_aspect``
+ - The picture aspect if the pixels are not square. Only valid if the
+ ``V4L2_DV_FL_HAS_PICTURE_ASPECT`` flag is set.
+ * - __u8
+ - ``cea861_vic``
+ - The Video Identification Code according to the CEA-861 standard.
+ Only valid if the ``V4L2_DV_FL_HAS_CEA861_VIC`` flag is set.
+ * - __u8
+ - ``hdmi_vic``
+ - The Video Identification Code according to the HDMI standard.
+ Only valid if the ``V4L2_DV_FL_HAS_HDMI_VIC`` flag is set.
+ * - __u8
+ - ``reserved[46]``
- Reserved for future extensions. Drivers and applications must set
the array to zero.
diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst b/Documentation/media/uapi/v4l/vidioc-querycap.rst
index 165d8314327e..12e0d9a63cd8 100644
--- a/Documentation/media/uapi/v4l/vidioc-querycap.rst
+++ b/Documentation/media/uapi/v4l/vidioc-querycap.rst
@@ -236,6 +236,9 @@ specification the ioctl returns an ``EINVAL`` error code.
* - ``V4L2_CAP_SDR_OUTPUT``
- 0x00400000
- The device supports the :ref:`SDR Output <sdr>` interface.
+ * - ``V4L2_CAP_META_CAPTURE``
+ - 0x00800000
+ - The device supports the :ref:`metadata` capture interface.
* - ``V4L2_CAP_READWRITE``
- 0x01000000
- The device supports the :ref:`read() <rw>` and/or
diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
index 82769de801b1..41c5744a1239 100644
--- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
+++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
@@ -301,12 +301,12 @@ See also the examples in :ref:`control`.
- ``name``\ [32]
- Name of the menu item, a NUL-terminated ASCII string. This
information is intended for the user. This field is valid for
- ``V4L2_CTRL_FLAG_MENU`` type controls.
+ ``V4L2_CTRL_TYPE_MENU`` type controls.
* -
- __s64
- ``value``
- Value of the integer menu item. This field is valid for
- ``V4L2_CTRL_FLAG_INTEGER_MENU`` type controls.
+ ``V4L2_CTRL_TYPE_INTEGER_MENU`` type controls.
* - __u32
-
- ``reserved``
@@ -507,6 +507,19 @@ See also the examples in :ref:`control`.
represents an action on the hardware. For example: clearing an
error flag or triggering the flash. All the controls of the type
``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
+ * .. _FLAG_MODIFY_LAYOUT:
+
+ - ``V4L2_CTRL_FLAG_MODIFY_LAYOUT``
+ - 0x0400
+ - Changing this control value may modify the layout of the
+ buffer (for video devices) or the media bus format (for sub-devices).
+
+ A typical example would be the ``V4L2_CID_ROTATE`` control.
+
+ Note that typically controls with this flag will also set the
+ ``V4L2_CTRL_FLAG_GRABBED`` flag when buffers are allocated or
+ streaming is in progress since most drivers do not support changing
+ the format in that case.
Return Value