summaryrefslogtreecommitdiff
path: root/Documentation/media/uapi/v4l
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/media/uapi/v4l')
-rw-r--r--Documentation/media/uapi/v4l/biblio.rst10
-rw-r--r--Documentation/media/uapi/v4l/colorspaces-defs.rst8
-rw-r--r--Documentation/media/uapi/v4l/colorspaces-details.rst13
-rw-r--r--Documentation/media/uapi/v4l/func-poll.rst3
-rw-r--r--Documentation/media/uapi/v4l/meta-formats.rst1
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-compressed.rst2
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst210
-rw-r--r--Documentation/media/uapi/v4l/vidioc-cropcap.rst2
-rw-r--r--Documentation/media/uapi/v4l/vidioc-dqevent.rst12
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-crop.rst2
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst27
11 files changed, 256 insertions, 34 deletions
diff --git a/Documentation/media/uapi/v4l/biblio.rst b/Documentation/media/uapi/v4l/biblio.rst
index 1cedcfc04327..386d6cf83e9c 100644
--- a/Documentation/media/uapi/v4l/biblio.rst
+++ b/Documentation/media/uapi/v4l/biblio.rst
@@ -226,16 +226,6 @@ xvYCC
:author: International Electrotechnical Commission (http://www.iec.ch)
-.. _adobergb:
-
-AdobeRGB
-========
-
-
-:title: Adobe© RGB (1998) Color Image Encoding Version 2005-05
-
-:author: Adobe Systems Incorporated (http://www.adobe.com)
-
.. _oprgb:
opRGB
diff --git a/Documentation/media/uapi/v4l/colorspaces-defs.rst b/Documentation/media/uapi/v4l/colorspaces-defs.rst
index 410907fe9415..f24615544792 100644
--- a/Documentation/media/uapi/v4l/colorspaces-defs.rst
+++ b/Documentation/media/uapi/v4l/colorspaces-defs.rst
@@ -51,8 +51,8 @@ whole range, 0-255, dividing the angular value by 1.41. The enum
- See :ref:`col-rec709`.
* - ``V4L2_COLORSPACE_SRGB``
- See :ref:`col-srgb`.
- * - ``V4L2_COLORSPACE_ADOBERGB``
- - See :ref:`col-adobergb`.
+ * - ``V4L2_COLORSPACE_OPRGB``
+ - See :ref:`col-oprgb`.
* - ``V4L2_COLORSPACE_BT2020``
- See :ref:`col-bt2020`.
* - ``V4L2_COLORSPACE_DCI_P3``
@@ -90,8 +90,8 @@ whole range, 0-255, dividing the angular value by 1.41. The enum
- Use the Rec. 709 transfer function.
* - ``V4L2_XFER_FUNC_SRGB``
- Use the sRGB transfer function.
- * - ``V4L2_XFER_FUNC_ADOBERGB``
- - Use the AdobeRGB transfer function.
+ * - ``V4L2_XFER_FUNC_OPRGB``
+ - Use the opRGB transfer function.
* - ``V4L2_XFER_FUNC_SMPTE240M``
- Use the SMPTE 240M transfer function.
* - ``V4L2_XFER_FUNC_NONE``
diff --git a/Documentation/media/uapi/v4l/colorspaces-details.rst b/Documentation/media/uapi/v4l/colorspaces-details.rst
index b5d551b9cc8f..09fabf4cd412 100644
--- a/Documentation/media/uapi/v4l/colorspaces-details.rst
+++ b/Documentation/media/uapi/v4l/colorspaces-details.rst
@@ -290,15 +290,14 @@ Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
170M/BT.601. The Y'CbCr quantization is limited range.
-.. _col-adobergb:
+.. _col-oprgb:
-Colorspace Adobe RGB (V4L2_COLORSPACE_ADOBERGB)
+Colorspace opRGB (V4L2_COLORSPACE_OPRGB)
===============================================
-The :ref:`adobergb` standard defines the colorspace used by computer
-graphics that use the AdobeRGB colorspace. This is also known as the
-:ref:`oprgb` standard. The default transfer function is
-``V4L2_XFER_FUNC_ADOBERGB``. The default Y'CbCr encoding is
+The :ref:`oprgb` standard defines the colorspace used by computer
+graphics that use the opRGB colorspace. The default transfer function is
+``V4L2_XFER_FUNC_OPRGB``. The default Y'CbCr encoding is
``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
range.
@@ -312,7 +311,7 @@ The chromaticities of the primary colors and the white reference are:
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
-.. flat-table:: Adobe RGB Chromaticities
+.. flat-table:: opRGB Chromaticities
:header-rows: 1
:stub-columns: 0
:widths: 1 1 2
diff --git a/Documentation/media/uapi/v4l/func-poll.rst b/Documentation/media/uapi/v4l/func-poll.rst
index 360bc6523ae2..967fe8920729 100644
--- a/Documentation/media/uapi/v4l/func-poll.rst
+++ b/Documentation/media/uapi/v4l/func-poll.rst
@@ -113,4 +113,5 @@ EINTR
The call was interrupted by a signal.
EINVAL
- The ``nfds`` argument is greater than ``OPEN_MAX``.
+ The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use
+ ``getrlimit()`` to obtain this value.
diff --git a/Documentation/media/uapi/v4l/meta-formats.rst b/Documentation/media/uapi/v4l/meta-formats.rst
index 0c4e1ecf5879..cf971d5ad9ea 100644
--- a/Documentation/media/uapi/v4l/meta-formats.rst
+++ b/Documentation/media/uapi/v4l/meta-formats.rst
@@ -12,6 +12,7 @@ These formats are used for the :ref:`metadata` interface only.
.. toctree::
:maxdepth: 1
+ pixfmt-meta-d4xx
pixfmt-meta-uvc
pixfmt-meta-vsp1-hgo
pixfmt-meta-vsp1-hgt
diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
index d382e7a5c38e..d04b18adac33 100644
--- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst
@@ -101,4 +101,4 @@ Compressed Formats
- 'FWHT'
- Video elementary stream using a codec based on the Fast Walsh Hadamard
Transform. This codec is implemented by the vicodec ('Virtual Codec')
- driver. See the vicodec-codec.h header for more details.
+ driver. See the codec-fwht.h header for more details.
diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst b/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst
new file mode 100644
index 000000000000..63bf1a2c9116
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst
@@ -0,0 +1,210 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-meta-fmt-d4xx:
+
+*******************************
+V4L2_META_FMT_D4XX ('D4XX')
+*******************************
+
+Intel D4xx UVC Cameras Metadata
+
+
+Description
+===========
+
+Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC
+payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
+means, that the private D4XX metadata, following the standard UVC header, is
+organised in blocks. D4XX cameras implement several standard block types,
+proposed by Microsoft, and several proprietary ones. Supported standard metadata
+types are MetadataId_CaptureStats (ID 3), MetadataId_CameraExtrinsics (ID 4),
+and MetadataId_CameraIntrinsics (ID 5). For their description see [1_]. This
+document describes proprietary metadata types, used by D4xx cameras.
+
+V4L2_META_FMT_D4XX buffers follow the metadata buffer layout of
+V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
+payload header data. D4xx cameras use bulk transfers and only send one payload
+per frame, therefore their headers cannot be larger than 255 bytes.
+
+Below are proprietary Microsoft style metadata types, used by D4xx cameras,
+where all fields are in little endian order:
+
+.. flat-table:: D4xx metadata
+ :widths: 1 4
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Field
+ - Description
+ * - :cspan:`1` *Depth Control*
+ * - __u32 ID
+ - 0x80000000
+ * - __u32 Size
+ - Size in bytes (currently 56)
+ * - __u32 Version
+ - Version of this structure. The documentation herein corresponds to
+ version xxx. The version number will be incremented when new fields are
+ added.
+ * - __u32 Flags
+ - A bitmask of flags: see [2_] below
+ * - __u32 Gain
+ - Gain value in internal units, same as the V4L2_CID_GAIN control, used to
+ capture the frame
+ * - __u32 Exposure
+ - Exposure time (in microseconds) used to capture the frame
+ * - __u32 Laser power
+ - Power of the laser LED 0-360, used for depth measurement
+ * - __u32 AE mode
+ - 0: manual; 1: automatic exposure
+ * - __u32 Exposure priority
+ - Exposure priority value: 0 - constant frame rate
+ * - __u32 AE ROI left
+ - Left border of the AE Region of Interest (all ROI values are in pixels
+ and lie between 0 and maximum width or height respectively)
+ * - __u32 AE ROI right
+ - Right border of the AE Region of Interest
+ * - __u32 AE ROI top
+ - Top border of the AE Region of Interest
+ * - __u32 AE ROI bottom
+ - Bottom border of the AE Region of Interest
+ * - __u32 Preset
+ - Preset selector value, default: 0, unless changed by the user
+ * - __u32 Laser mode
+ - 0: off, 1: on
+ * - :cspan:`1` *Capture Timing*
+ * - __u32 ID
+ - 0x80000001
+ * - __u32 Size
+ - Size in bytes (currently 40)
+ * - __u32 Version
+ - Version of this structure. The documentation herein corresponds to
+ version xxx. The version number will be incremented when new fields are
+ added.
+ * - __u32 Flags
+ - A bitmask of flags: see [3_] below
+ * - __u32 Frame counter
+ - Monotonically increasing counter
+ * - __u32 Optical time
+ - Time in microseconds from the beginning of a frame till its middle
+ * - __u32 Readout time
+ - Time, used to read out a frame in microseconds
+ * - __u32 Exposure time
+ - Frame exposure time in microseconds
+ * - __u32 Frame interval
+ - In microseconds = 1000000 / framerate
+ * - __u32 Pipe latency
+ - Time in microseconds from start of frame to data in USB buffer
+ * - :cspan:`1` *Configuration*
+ * - __u32 ID
+ - 0x80000002
+ * - __u32 Size
+ - Size in bytes (currently 40)
+ * - __u32 Version
+ - Version of this structure. The documentation herein corresponds to
+ version xxx. The version number will be incremented when new fields are
+ added.
+ * - __u32 Flags
+ - A bitmask of flags: see [4_] below
+ * - __u8 Hardware type
+ - Camera hardware version [5_]
+ * - __u8 SKU ID
+ - Camera hardware configuration [6_]
+ * - __u32 Cookie
+ - Internal synchronisation
+ * - __u16 Format
+ - Image format code [7_]
+ * - __u16 Width
+ - Width in pixels
+ * - __u16 Height
+ - Height in pixels
+ * - __u16 Framerate
+ - Requested frame rate per second
+ * - __u16 Trigger
+ - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
+
+.. _1:
+
+[1] https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5
+
+.. _2:
+
+[2] Depth Control flags specify which fields are valid: ::
+
+ 0x00000001 Gain
+ 0x00000002 Exposure
+ 0x00000004 Laser power
+ 0x00000008 AE mode
+ 0x00000010 Exposure priority
+ 0x00000020 AE ROI
+ 0x00000040 Preset
+
+.. _3:
+
+[3] Capture Timing flags specify which fields are valid: ::
+
+ 0x00000001 Frame counter
+ 0x00000002 Optical time
+ 0x00000004 Readout time
+ 0x00000008 Exposure time
+ 0x00000010 Frame interval
+ 0x00000020 Pipe latency
+
+.. _4:
+
+[4] Configuration flags specify which fields are valid: ::
+
+ 0x00000001 Hardware type
+ 0x00000002 SKU ID
+ 0x00000004 Cookie
+ 0x00000008 Format
+ 0x00000010 Width
+ 0x00000020 Height
+ 0x00000040 Framerate
+ 0x00000080 Trigger
+ 0x00000100 Cal count
+
+.. _5:
+
+[5] Camera model: ::
+
+ 0 DS5
+ 1 IVCAM2
+
+.. _6:
+
+[6] 8-bit camera hardware configuration bitfield: ::
+
+ [1:0] depthCamera
+ 00: no depth
+ 01: standard depth
+ 10: wide depth
+ 11: reserved
+ [2] depthIsActive - has a laser projector
+ [3] RGB presence
+ [4] Inertial Measurement Unit (IMU) presence
+ [5] projectorType
+ 0: HPTG
+ 1: Princeton
+ [6] 0: a projector, 1: an LED
+ [7] reserved
+
+.. _7:
+
+[7] Image format codes per video streaming interface:
+
+Depth: ::
+
+ 1 Z16
+ 2 Z
+
+Left sensor: ::
+
+ 1 Y8
+ 2 UYVY
+ 3 R8L8
+ 4 Calibration
+ 5 W10
+
+Fish Eye sensor: ::
+
+ 1 RAW8
diff --git a/Documentation/media/uapi/v4l/vidioc-cropcap.rst b/Documentation/media/uapi/v4l/vidioc-cropcap.rst
index a65dbec6b20b..0a7b8287fd38 100644
--- a/Documentation/media/uapi/v4l/vidioc-cropcap.rst
+++ b/Documentation/media/uapi/v4l/vidioc-cropcap.rst
@@ -58,7 +58,7 @@ overlay devices.
- Type of the data stream, set by the application. Only these types
are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
- ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note above.
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note below.
* - struct :ref:`v4l2_rect <v4l2-rect-crop>`
- ``bounds``
- Defines the window within capturing or output is possible, this
diff --git a/Documentation/media/uapi/v4l/vidioc-dqevent.rst b/Documentation/media/uapi/v4l/vidioc-dqevent.rst
index cb3565f36793..04416b6943c0 100644
--- a/Documentation/media/uapi/v4l/vidioc-dqevent.rst
+++ b/Documentation/media/uapi/v4l/vidioc-dqevent.rst
@@ -379,7 +379,17 @@ call.
- 0x0001
- This event gets triggered when a resolution change is detected at
an input. This can come from an input connector or from a video
- decoder.
+ decoder. Applications will have to query the new resolution (if
+ any, the signal may also have been lost).
+
+ *Important*: even if the new video timings appear identical to the old
+ ones, receiving this event indicates that there was an issue with the
+ video signal and you must stop and restart streaming
+ (:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
+ followed by :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`). The reason is
+ that many devices are not able to recover from a temporary loss of
+ signal and so restarting streaming I/O is required in order for the
+ hardware to synchronize to the video signal.
Return Value
diff --git a/Documentation/media/uapi/v4l/vidioc-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-g-crop.rst
index a6ed43ba9ca3..b95ba6743cbd 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-crop.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-crop.rst
@@ -84,7 +84,7 @@ When cropping is not supported then no parameters are changed and
- Type of the data stream, set by the application. Only these types
are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
- ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note above.
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note below.
* - struct :c:type:`v4l2_rect`
- ``c``
- Cropping rectangle. The same co-ordinate system as for struct
diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
index 1a034e825161..35cba2c8d459 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
@@ -257,14 +257,19 @@ EBUSY
will also be cleared. This is a read-only flag, applications must
not set this.
* - ``V4L2_DV_FL_REDUCED_FPS``
- - CEA-861 specific: only valid for video transmitters, the flag is
- cleared by receivers. It is also only valid for formats with the
- ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the
- flag will be cleared by the driver. If the application sets this
- flag, then the pixelclock used to set up the transmitter is
- divided by 1.001 to make it compatible with NTSC framerates. If
- the transmitter can't generate such frequencies, then the flag
- will also be cleared.
+ - CEA-861 specific: only valid for video transmitters or video
+ receivers that have the ``V4L2_DV_FL_CAN_DETECT_REDUCED_FPS``
+ set. This flag is cleared otherwise. It is also only valid for
+ formats with the ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other
+ formats the flag will be cleared by the driver.
+
+ If the application sets this flag for a transmitter, then the
+ pixelclock used to set up the transmitter is divided by 1.001 to
+ make it compatible with NTSC framerates. If the transmitter can't
+ generate such frequencies, then the flag will be cleared.
+
+ If a video receiver detects that the format uses a reduced framerate,
+ then it will set this flag to signal this to the application.
* - ``V4L2_DV_FL_HALF_LINE``
- Specific to interlaced formats: if set, then the vertical
backporch of field 1 (aka the odd field) is really one half-line
@@ -294,3 +299,9 @@ EBUSY
- If set, then the hdmi_vic field is valid and contains the Video
Identification Code as per the HDMI standard (HDMI Vendor Specific
InfoFrame).
+ * - ``V4L2_DV_FL_CAN_DETECT_REDUCED_FPS``
+ - CEA-861 specific: only valid for video receivers, the flag is
+ cleared by transmitters.
+ If set, then the hardware can detect the difference between
+ regular framerates and framerates reduced by 1000/1001. E.g.:
+ 60 vs 59.94 Hz, 30 vs 29.97 Hz or 24 vs 23.976 Hz.