From 2371517601aa2b7189a10236328dff0993b0294f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hanne-Lotta=20M=C3=A4enp=C3=A4=C3=A4?= Date: Thu, 12 Jun 2025 20:27:03 +0300 Subject: media: Documentation: Improve grammar, formatting in Video4Linux MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix typos, punctuation and improve grammar and formatting in documentation for Video4Linux (V4L). Signed-off-by: Hanne-Lotta Mäenpää Signed-off-by: Sakari Ailus Signed-off-by: Hans Verkuil --- Documentation/userspace-api/media/v4l/biblio.rst | 2 +- .../userspace-api/media/v4l/dev-sliced-vbi.rst | 4 ++-- .../userspace-api/media/v4l/ext-ctrls-fm-rx.rst | 11 +++-------- .../userspace-api/media/v4l/ext-ctrls-fm-tx.rst | 21 +++++++-------------- .../userspace-api/media/v4l/pixfmt-srggb12p.rst | 4 ++-- .../userspace-api/media/v4l/pixfmt-srggb14p.rst | 2 +- 6 files changed, 16 insertions(+), 28 deletions(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/media/v4l/biblio.rst b/Documentation/userspace-api/media/v4l/biblio.rst index 35674eeae20d..856acf6a890c 100644 --- a/Documentation/userspace-api/media/v4l/biblio.rst +++ b/Documentation/userspace-api/media/v4l/biblio.rst @@ -150,7 +150,7 @@ ITU-T.81 ======== -:title: ITU-T Recommendation T.81 "Information Technology --- Digital Compression and Coding of Continous-Tone Still Images --- Requirements and Guidelines" +:title: ITU-T Recommendation T.81 "Information Technology --- Digital Compression and Coding of Continuous-Tone Still Images --- Requirements and Guidelines" :author: International Telecommunication Union (http://www.itu.int) diff --git a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst index 42cdb0a9f786..96e0e85a822c 100644 --- a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst @@ -48,7 +48,7 @@ capabilities, and they may support :ref:`control` ioctls. The :ref:`video standard ` ioctls provide information vital to program a sliced VBI device, therefore must be supported. -.. _sliced-vbi-format-negotitation: +.. _sliced-vbi-format-negotiation: Sliced VBI Format Negotiation ============================= @@ -377,7 +377,7 @@ Sliced VBI Data in MPEG Streams If a device can produce an MPEG output stream, it may be capable of providing -:ref:`negotiated sliced VBI services ` +:ref:`negotiated sliced VBI services ` as data embedded in the MPEG stream. Users or applications control this sliced VBI data insertion with the :ref:`V4L2_CID_MPEG_STREAM_VBI_FMT ` diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst index b6cfc0e823d2..ccd439e9e0e3 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst @@ -64,17 +64,12 @@ FM_RX Control IDs broadcasts speech. If the transmitter doesn't make this distinction, then it will be set. -``V4L2_CID_TUNE_DEEMPHASIS`` - (enum) - -enum v4l2_deemphasis - +``V4L2_CID_TUNE_DEEMPHASIS (enum)`` Configures the de-emphasis value for reception. A de-emphasis filter is applied to the broadcast to accentuate the high audio frequencies. Depending on the region, a time constant of either 50 - or 75 useconds is used. The enum v4l2_deemphasis defines possible - values for de-emphasis. Here they are: - - + or 75 microseconds is used. The enum v4l2_deemphasis defines possible + values for de-emphasis. They are: .. flat-table:: :header-rows: 0 diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst index 04c997c9a4c3..cb40cf4cc3ec 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst @@ -104,7 +104,7 @@ FM_TX Control IDs ``V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (integer)`` Sets the audio deviation limiter feature release time. Unit is in - useconds. Step and range are driver-specific. + microseconds. Step and range are driver-specific. ``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)`` Configures audio frequency deviation level in Hz. The range and step @@ -121,16 +121,16 @@ FM_TX Control IDs range and step are driver-specific. ``V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (integer)`` - Sets the threshold level for audio compression freature. It is a dB + Sets the threshold level for audio compression feature. It is a dB value. The range and step are driver-specific. ``V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (integer)`` - Sets the attack time for audio compression feature. It is a useconds + Sets the attack time for audio compression feature. It is a microseconds value. The range and step are driver-specific. ``V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (integer)`` Sets the release time for audio compression feature. It is a - useconds value. The range and step are driver-specific. + microseconds value. The range and step are driver-specific. ``V4L2_CID_PILOT_TONE_ENABLED (boolean)`` Enables or disables the pilot tone generation feature. @@ -143,17 +143,12 @@ FM_TX Control IDs Configures pilot tone frequency value. Unit is in Hz. The range and step are driver-specific. -``V4L2_CID_TUNE_PREEMPHASIS`` - (enum) - -enum v4l2_preemphasis - +``V4L2_CID_TUNE_PREEMPHASIS (enum)`` Configures the pre-emphasis value for broadcasting. A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies. Depending on the region, a time constant of either 50 - or 75 useconds is used. The enum v4l2_preemphasis defines possible - values for pre-emphasis. Here they are: - - + or 75 microseconds is used. The enum v4l2_preemphasis defines possible + values for pre-emphasis. They are: .. flat-table:: :header-rows: 0 @@ -166,8 +161,6 @@ enum v4l2_preemphasis - * - ``V4L2_PREEMPHASIS_75_uS`` - A pre-emphasis of 75 uS is used. - - ``V4L2_CID_TUNE_POWER_LEVEL (integer)`` Sets the output power level for signal transmission. Unit is in dBuV. Range and step are driver-specific. diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst index 7c3810ff783c..8c03aedcc00e 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst @@ -6,7 +6,7 @@ .. _v4l2-pix-fmt-sgrbg12p: ******************************************************************************************************************************* -V4L2_PIX_FMT_SRGGB12P ('pRCC'), V4L2_PIX_FMT_SGRBG12P ('pgCC'), V4L2_PIX_FMT_SGBRG12P ('pGCC'), V4L2_PIX_FMT_SBGGR12P ('pBCC'), +V4L2_PIX_FMT_SRGGB12P ('pRCC'), V4L2_PIX_FMT_SGRBG12P ('pgCC'), V4L2_PIX_FMT_SGBRG12P ('pGCC'), V4L2_PIX_FMT_SBGGR12P ('pBCC') ******************************************************************************************************************************* @@ -20,7 +20,7 @@ Description These four pixel formats are packed raw sRGB / Bayer formats with 12 bits per colour. Every two consecutive samples are packed into three bytes. Each of the first two bytes contain the 8 high order bits of -the pixels, and the third byte contains the four least significants +the pixels, and the third byte contains the four least significant bits of each pixel, in the same order. Each n-pixel row contains n/2 green samples and n/2 blue or red diff --git a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst index 3572e42adb22..f4f53d7dbdeb 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst @@ -24,7 +24,7 @@ These four pixel formats are packed raw sRGB / Bayer formats with 14 bits per colour. Every four consecutive samples are packed into seven bytes. Each of the first four bytes contain the eight high order bits of the pixels, and the three following bytes contains the six least -significants bits of each pixel, in the same order. +significant bits of each pixel, in the same order. Each n-pixel row contains n/2 green samples and n/2 blue or red samples, with alternating green-red and green-blue rows. They are conventionally -- cgit v1.2.3 From 78584431e2cea6b60909cfa23c90ac8b33ab4198 Mon Sep 17 00:00:00 2001 From: Daniel Scally Date: Mon, 30 Jun 2025 23:27:34 +0100 Subject: media: v4l2: Add Renesas Camera Receiver Unit pixel formats The Renesas Camera Receiver Unit in the RZ/V2H SoC can output RAW data captured from an image sensor without conversion to an RGB/YUV format. In that case the data are packed into 64-bit blocks, with a variable amount of padding in the most significant bits depending on the bitdepth of the data. Add new V4L2 pixel format codes for the new formats, along with documentation to describe them. Reviewed-by: Lad Prabhakar Reviewed-by: Laurent Pinchart Reviewed-by: Jacopo Mondi Signed-off-by: Daniel Scally Link: https://lore.kernel.org/r/20250630222734.2712390-1-dan.scally@ideasonboard.com Signed-off-by: Laurent Pinchart Signed-off-by: Hans Verkuil --- .../userspace-api/media/v4l/pixfmt-bayer.rst | 1 + .../userspace-api/media/v4l/pixfmt-rawnn-cru.rst | 143 +++++++++++++++++++++ 2 files changed, 144 insertions(+) create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-rawnn-cru.rst (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst b/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst index ed3eb432967d..b5ca501842b0 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-bayer.rst @@ -19,6 +19,7 @@ orders. See also `the Wikipedia article on Bayer filter .. toctree:: :maxdepth: 1 + pixfmt-rawnn-cru pixfmt-srggb8 pixfmt-srggb8-pisp-comp pixfmt-srggb10 diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rawnn-cru.rst b/Documentation/userspace-api/media/v4l/pixfmt-rawnn-cru.rst new file mode 100644 index 000000000000..db81f1cfe0f5 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/pixfmt-rawnn-cru.rst @@ -0,0 +1,143 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _v4l2-pix-fmt-raw-cru10: +.. _v4l2-pix-fmt-raw-cru12: +.. _v4l2-pix-fmt-raw-cru14: +.. _v4l2-pix-fmt-raw-cru20: + +********************************************************************************************************************************** +V4L2_PIX_FMT_RAW_CRU10 ('CR10'), V4L2_PIX_FMT_RAW_CRU12 ('CR12'), V4L2_PIX_FMT_RAW_CRU14 ('CR14'), V4L2_PIX_FMT_RAW_CRU20 ('CR20') +********************************************************************************************************************************** + +=============================================================== +Renesas RZ/V2H Camera Receiver Unit 64-bit packed pixel formats +=============================================================== + +| V4L2_PIX_FMT_RAW_CRU10 (CR10) +| V4L2_PIX_FMT_RAW_CRU12 (CR12) +| V4L2_PIX_FMT_RAW_CRU14 (CR14) +| V4L2_PIX_FMT_RAW_CRU20 (CR20) + +Description +=========== + +These pixel formats are some of the RAW outputs for the Camera Receiver Unit in +the Renesas RZ/V2H SoC. They are raw formats which pack pixels contiguously into +64-bit units, with the 4 or 8 most significant bits padded. + +**Byte Order** + +.. flat-table:: RAW formats + :header-rows: 2 + :stub-columns: 0 + :widths: 36 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 + :fill-cells: + + * - :rspan:`1` Pixel Format Code + - :cspan:`63` Data organization + * - 63 + - 62 + - 61 + - 60 + - 59 + - 58 + - 57 + - 56 + - 55 + - 54 + - 53 + - 52 + - 51 + - 50 + - 49 + - 48 + - 47 + - 46 + - 45 + - 44 + - 43 + - 42 + - 41 + - 40 + - 39 + - 38 + - 37 + - 36 + - 35 + - 34 + - 33 + - 32 + - 31 + - 30 + - 29 + - 28 + - 27 + - 26 + - 25 + - 24 + - 23 + - 22 + - 21 + - 20 + - 19 + - 18 + - 17 + - 16 + - 15 + - 14 + - 13 + - 12 + - 11 + - 10 + - 9 + - 8 + - 7 + - 6 + - 5 + - 4 + - 3 + - 2 + - 1 + - 0 + * - V4L2_PIX_FMT_RAW_CRU10 + - 0 + - 0 + - 0 + - 0 + - :cspan:`9` P5 + - :cspan:`9` P4 + - :cspan:`9` P3 + - :cspan:`9` P2 + - :cspan:`9` P1 + - :cspan:`9` P0 + * - V4L2_PIX_FMT_RAW_CRU12 + - 0 + - 0 + - 0 + - 0 + - :cspan:`11` P4 + - :cspan:`11` P3 + - :cspan:`11` P2 + - :cspan:`11` P1 + - :cspan:`11` P0 + * - V4L2_PIX_FMT_RAW_CRU14 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - :cspan:`13` P3 + - :cspan:`13` P2 + - :cspan:`13` P1 + - :cspan:`13` P0 + * - V4L2_PIX_FMT_RAW_CRU20 + - 0 + - 0 + - 0 + - 0 + - :cspan:`19` P2 + - :cspan:`19` P1 + - :cspan:`19` P0 -- cgit v1.2.3 From a8c42a5bf5ea9914d662db799a1d5c93c2176a5c Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 30 Jun 2025 13:08:48 +0200 Subject: Documentation: media: cec: update error inj doc Document rx-no-low-drive and the new support to inject glitches. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- .../userspace-api/media/cec/cec-pin-error-inj.rst | 42 ++++++++++++++++++++++ 1 file changed, 42 insertions(+) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst index 411d42a742f3..c02790319f3f 100644 --- a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst +++ b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst @@ -41,6 +41,9 @@ error injection status:: # rx-clear clear all rx error injections for # tx-clear clear all tx error injections for # + # RX error injection settings: + # rx-no-low-drive do not generate low-drive pulses + # # RX error injection: # [,] rx-nack NACK the message instead of sending an ACK # [,] rx-low-drive force a low-drive condition at this bit position @@ -53,6 +56,10 @@ error injection status:: # tx-custom-low-usecs define the 'low' time for the custom pulse # tx-custom-high-usecs define the 'high' time for the custom pulse # tx-custom-pulse transmit the custom pulse once the bus is idle + # tx-glitch-low-usecs define the 'low' time for the glitch pulse + # tx-glitch-high-usecs define the 'high' time for the glitch pulse + # tx-glitch-falling-edge send the glitch pulse after every falling edge + # tx-glitch-rising-edge send the glitch pulse after every rising edge # # TX error injection: # [,] tx-no-eom don't set the EOM bit @@ -193,6 +200,14 @@ Receive Messages This does not work if the remote CEC transmitter has logical address 0 ('TV') since that will always win. +``rx-no-low-drive`` + The receiver will ignore situations that would normally generate a + Low Drive pulse (3.6 ms). This is typically done if a spurious pulse is + detected when receiving a message, and it indicates to the transmitter that + the message has to be retransmitted since the receiver got confused. + Disabling this is useful to test how other CEC devices handle glitches + by ensuring we will not be the one that generates a Low Drive. + Transmit Messages ----------------- @@ -327,3 +342,30 @@ Custom Pulses ``tx-custom-pulse`` Transmit a single custom pulse as soon as the CEC bus is idle. + +Glitch Pulses +------------- + +This emulates what happens if the signal on the CEC line is seeing spurious +pulses. Typically this happens after the falling or rising edge where there +is a short voltage fluctuation that, if the CEC hardware doesn't do +deglitching, can be seen as a spurious pulse and can cause a Low Drive +condition or corrupt data. + +``tx-glitch-low-usecs `` + This defines the duration in microseconds that the glitch pulse pulls + the CEC line low. The default is 1 microsecond. The range is 0-100 + microseconds. If 0, then no glitch pulse will be generated. + +``tx-glitch-high-usecs `` + This defines the duration in microseconds that the glitch pulse keeps the + CEC line high (unless another CEC adapter pulls it low in that time). + The default is 1 microseconds. The range is 0-100 microseconds. If 0, then + no glitch pulse will be generated.The total period of the glitch pulse is + ``tx-custom-low-usecs + tx-custom-high-usecs``. + +``tx-glitch-falling-edge`` + Send the glitch pulse right after the falling edge. + +``tx-glitch-rising-edge`` + Send the glitch pulse right after the rising edge. -- cgit v1.2.3 From e1ad27027587cc9ea03889c63d9d402a61d8e553 Mon Sep 17 00:00:00 2001 From: Ricardo Ribalda Date: Mon, 7 Jul 2025 18:34:02 +0000 Subject: media: Documentation: Add note about UVCH length field The documentation currently describes the UVC length field as the "length of the rest of the block", which can be misleading. The driver limits the data copied to a maximum of 12 bytes. This change adds a clarifying sentence to the documentation to make this restriction explicit. Reviewed-by: Hans de Goede Signed-off-by: Ricardo Ribalda Link: https://lore.kernel.org/r/20250707-uvc-meta-v8-2-ed17f8b1218b@chromium.org Signed-off-by: Hans de Goede Signed-off-by: Hans Verkuil --- Documentation/userspace-api/media/v4l/metafmt-uvc.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/media/v4l/metafmt-uvc.rst b/Documentation/userspace-api/media/v4l/metafmt-uvc.rst index 784346d14bbd..4c05e9e54683 100644 --- a/Documentation/userspace-api/media/v4l/metafmt-uvc.rst +++ b/Documentation/userspace-api/media/v4l/metafmt-uvc.rst @@ -44,7 +44,9 @@ Each individual block contains the following fields: them * - :cspan:`1` *The rest is an exact copy of the UVC payload header:* * - __u8 length; - - length of the rest of the block, including this field + - length of the rest of the block, including this field. Please note that + regardless of this value, for V4L2_META_FMT_UVC the kernel will never + copy more than 2-12 bytes. * - __u8 flags; - Flags, indicating presence of other standard UVC fields * - __u8 buf[]; -- cgit v1.2.3 From 2ab4019aa34dc2aec4a0824fbf1e49300884fbbf Mon Sep 17 00:00:00 2001 From: Ricardo Ribalda Date: Mon, 7 Jul 2025 18:34:04 +0000 Subject: media: uvcvideo: Introduce V4L2_META_FMT_UVC_MSXU_1_5 The UVC driver provides two metadata types V4L2_META_FMT_UVC, and V4L2_META_FMT_D4XX. The only difference between the two of them is that V4L2_META_FMT_UVC only copies PTS, SCR, size and flags, and V4L2_META_FMT_D4XX copies the whole metadata section. Now we only enable V4L2_META_FMT_D4XX for the Intel D4xx family of devices, but it is useful to have the whole metadata payload for any device where vendors include other metadata, such as the one described by Microsoft: https://learn.microsoft.com/en-us/windows-hardware/drivers/stream/mf-capture-metadata This patch introduces a new format V4L2_META_FMT_UVC_MSXU_1_5, that is identical to V4L2_META_FMT_D4XX. Let the user enable this format with a quirk for now. This way they can test if their devices provide useful metadata without rebuilding the kernel. They can later contribute patches to auto-quirk their devices. We will also work in methods to auto-detect devices compatible with this new metadata format. Suggested-by: Hans de Goede Reviewed-by: Hans de Goede Signed-off-by: Ricardo Ribalda Link: https://lore.kernel.org/r/20250707-uvc-meta-v8-4-ed17f8b1218b@chromium.org Signed-off-by: Hans de Goede Signed-off-by: Hans Verkuil --- .../userspace-api/media/v4l/meta-formats.rst | 1 + .../media/v4l/metafmt-uvc-msxu-1-5.rst | 23 ++++++++++++++++++++++ 2 files changed, 24 insertions(+) create mode 100644 Documentation/userspace-api/media/v4l/metafmt-uvc-msxu-1-5.rst (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/media/v4l/meta-formats.rst b/Documentation/userspace-api/media/v4l/meta-formats.rst index bb6876cfc271..0de80328c36b 100644 --- a/Documentation/userspace-api/media/v4l/meta-formats.rst +++ b/Documentation/userspace-api/media/v4l/meta-formats.rst @@ -20,6 +20,7 @@ These formats are used for the :ref:`metadata` interface only. metafmt-pisp-fe metafmt-rkisp1 metafmt-uvc + metafmt-uvc-msxu-1-5 metafmt-vivid metafmt-vsp1-hgo metafmt-vsp1-hgt diff --git a/Documentation/userspace-api/media/v4l/metafmt-uvc-msxu-1-5.rst b/Documentation/userspace-api/media/v4l/metafmt-uvc-msxu-1-5.rst new file mode 100644 index 000000000000..dd1c3076df24 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/metafmt-uvc-msxu-1-5.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _v4l2-meta-fmt-uvc-msxu-1-5: + +*********************************** +V4L2_META_FMT_UVC_MSXU_1_5 ('UVCM') +*********************************** + +Microsoft(R)'s UVC Payload Metadata. + + +Description +=========== + +V4L2_META_FMT_UVC_MSXU_1_5 buffers follow the metadata buffer layout of +V4L2_META_FMT_UVC with the only difference that it includes all the UVC +metadata in the `buffer[]` field, not just the first 2-12 bytes. + +The metadata format follows the specification from Microsoft(R) [1]. + +.. _1: + +[1] https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5 -- cgit v1.2.3