Linux Media Controller development
 help / color / mirror / Atom feed
From: Sakari Ailus <sakari.ailus@linux.intel.com>
To: linux-media@vger.kernel.org
Cc: hans@jjverkuil.nl, laurent.pinchart@ideasonboard.com,
	Prabhakar <prabhakar.csengg@gmail.com>,
	"Kate Hsuan" <hpa@redhat.com>,
	"Dave Stevenson" <dave.stevenson@raspberrypi.com>,
	"Tommaso Merciai" <tomm.merciai@gmail.com>,
	"Benjamin Mugnier" <benjamin.mugnier@foss.st.com>,
	"Sylvain Petinot" <sylvain.petinot@foss.st.com>,
	"Christophe JAILLET" <christophe.jaillet@wanadoo.fr>,
	"Julien Massot" <julien.massot@collabora.com>,
	"Naushir Patuck" <naush@raspberrypi.com>,
	"Yan, Dongcheng" <dongcheng.yan@intel.com>,
	"Stefan Klug" <stefan.klug@ideasonboard.com>,
	"Mirela Rabulea" <mirela.rabulea@nxp.com>,
	"André Apitzsch" <git@apitzsch.eu>,
	"Heimir Thor Sverrisson" <heimir.sverrisson@gmail.com>,
	"Kieran Bingham" <kieran.bingham@ideasonboard.com>,
	"Mehdi Djait" <mehdi.djait@linux.intel.com>,
	"Ricardo Ribalda Delgado" <ribalda@kernel.org>,
	"Hans de Goede" <hansg@kernel.org>,
	"Jacopo Mondi" <jacopo.mondi@ideasonboard.com>,
	"Tomi Valkeinen" <tomi.valkeinen@ideasonboard.com>,
	"David Plowman" <david.plowman@raspberrypi.com>,
	"Yu, Ong Hock" <ong.hock.yu@intel.com>,
	"Ng, Khai Wen" <khai.wen.ng@intel.com>,
	"Jai Luthra" <jai.luthra@ideasonboard.com>,
	"Rishikesh Donadkar" <r-donadkar@ti.com>,
	"Mattijs Korpershoek" <mkorpershoek@kernel.org>,
	"Antti Laakso" <antti.laakso@linux.intel.com>,
	"Bajpai, Manik" <manik.bajpai@intel.com>,
	"Divyamani Tripathi" <divyamani.tripathi@intel.com>
Subject: [PATCH v13 71/73] Documentation: media: Reword blanking control documentation
Date: Wed, 18 Nov 2026 15:28:17 +0200	[thread overview]
Message-ID: <20261118132819.213473-72-sakari.ailus@linux.intel.com> (raw)
In-Reply-To: <20261118132819.213473-1-sakari.ailus@linux.intel.com>

Originally the VBLANK and HBLANK controls were intended to signify camera
sensor vertical and horizontal blanking values, respectively, and were
used with the analogue crop rectangle and the pixel rate to calculate the
frame interval. Due to various factors, namely the reference size of
output format rather than analogue crop (non-CCS sensors) and the use of
analogue binning, these values in fact have primarily served frame
interval configuration whereas they may not have reflected blanking
anymore. Take this into account in documentation.

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 .../media/v4l/ext-ctrls-image-source.rst      | 22 ++++++++++++-------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
index b2c515e519f2..3a2dbf64fb72 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
@@ -22,16 +22,22 @@ Image Source Control IDs
     The IMAGE_SOURCE class descriptor.
 
 ``V4L2_CID_VBLANK (integer)``
-    Vertical blanking. The idle period after every frame during which no
-    image data is produced. The unit of vertical blanking is a line.
-    Every line has length of the image width plus horizontal blanking at
-    the pixel rate defined by ``V4L2_CID_PIXEL_RATE`` control in the
-    same sub-device.
+    Difference between the reference analogue crop rectangle (CCS) height or
+    output format height and the frame length in lines. See :ref:`frame interval
+    configuration <media_camera_sensor_frame_rate_raw>`.
+
+    The primary purpose of this control is low level frame interval
+    configuration. The value may also reflect vertical blanking but this is not
+    guaranteed.
 
 ``V4L2_CID_HBLANK (integer)``
-    Horizontal blanking. The idle period after every line of image data
-    during which no image data is produced. The unit of horizontal
-    blanking is pixels.
+    Difference between the reference analogue crop rectangle (CCS) width or
+    output format width and the line length in pixels. See :ref:`frame interval
+    configuration <media_camera_sensor_frame_rate_raw>`.
+
+    The primary purpose of this control is low level frame interval
+    configuration. The value may also reflect horizontal blanking but this is
+    not guaranteed.
 
 ``V4L2_CID_ANALOGUE_GAIN (integer)``
     Analogue gain is gain affecting all colour components in the pixel
-- 
2.47.3


  parent reply	other threads:[~2026-11-18 13:28 UTC|newest]

Thread overview: 74+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-18 13:27 [PATCH v13 00/72] Generic line based metadata support, internal pads Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 01/73] media: uapi: Bump the STREAMS bit a little Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 02/73] Revert "media: mc: Keep INTERNAL pad flags just for the kernel, for now" Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 03/73] media: uapi: Add generic CSI-2 raw pixelformats Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 04/73] media: uapi: Add new media bus codes for generic raw formats Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 05/73] media: uapi: Add V4L2_CID_CONFIG_MODEL control Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 06/73] media: uapi: Add V4L2_CID_CFA_PATTERN for describing color patterns Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 07/73] media: uapi: Add monochromatic CFA pattern Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 08/73] media: Documentation: Reference CFA pattern control in pixelformat docs Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 09/73] media: Documentation: Reference CFA_PATTERN control in raw mbus docs Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 10/73] media: v4l: uapi: Add a control for color pattern flipping effect Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 11/73] media: Documentation: Reference flipping controls in raw format docs Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 12/73] media: Documentation: Document raw mbus codes and CFA for cameras Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 13/73] media: uapi: Add V4L2_CID_METADATA_LAYOUT control Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 14/73] media: Documentation: Refer to metadata layout in metadata documentation Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 15/73] media: Documentation: v4l: Document internal sink pads Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 16/73] media: Documentation: Document embedded data guidelines for camera sensors Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 17/73] media: uapi: Correct generic CSI-2 metadata format 4cc Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 18/73] Revert "media: uapi: v4l: Don't expose generic metadata formats to userspace" Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 19/73] media: v4l: Add V4L2_SUBDEV_ROUTE_FL_IMMUTABLE sub-device routing flag Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 20/73] media: v4l: Add V4L2_SUBDEV_ROUTE_FL_STATIC " Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 21/73] media: Documentation: There are either immutable or mutable routes Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 22/73] media: Documentation: Document IMMUTABLE and STATIC route flags Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 23/73] media: Documentation: Add subdev configuration models, raw sensor model Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 24/73] media: v4l2-subdev: Prevent accessing internal pads without STREAMS cap Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 25/73] media: subdev: Make get_fmt on INTERNAL pads without STREAMS an error Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 26/73] media: Documentation: Add scaling and post-scaler crop for common raw Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 27/73] media: uapi: Add MIPI CCS configuration model Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 28/73] media: uapi: Add V4L2_SUBDEV_CLIENT_CAP_COMMON_RAW_SENSOR Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 29/73] media: uapi: Add V4L2_CID_BINNING_FACTORS control for binning configuration Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 30/73] media: uapi: Add controls for sub-sampling configuration Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 31/73] media: uapi: Add new controls for camera sensor FLL and LLP Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 32/73] media: v4l2-common: Add v4l2_sensor_fll_llp_set() Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 33/73] media: Documentation: Add binning and sub-sampling controls Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 34/73] media: v4l2-subdev: Set STATIC route flag if IMMUTABLE route flag is set Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 35/73] media: uapi: v4l: subdev: Enable streams API Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 36/73] media: uapi: Add binning factor helper macros Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 37/73] media: Documentation: Document frame controls for common raw sensor model Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 38/73] media: v4l2-ctrl: Improve v4l2_ctrl_g_ctrl{,int64} documentation Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 39/73] media: Documentation: Add sub-device internal pads example Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 40/73] media: Documentation: Document streaming behaviour for common raw cameras Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 41/73] media: Documentation: Add a note on Bayer raw mbus codes Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 42/73] media: uapi: Add generic raw pixelformats for 10, 12 and 14 bits Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 43/73] media: uapi: Add more media bus codes for generic raw formats Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 44/73] media: uapi: ccs: Add metadata layout for MIPI CCS embedded data Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 45/73] media: Documentation: Document non-CCS use of CCS embedded data layout Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 46/73] media: ccs: Add support for generic raw mbus codes Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 47/73] media: ccs: Add support for embedded data stream Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 48/73] media: Documentation: ccs: Document routing Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 49/73] media: ccs: Add IMMUTABLE and STATIC route flags Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 50/73] media: uapi: Add metadata layout for ov2740 embedded data Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 51/73] media: ov2740: Add support for " Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 52/73] media: ov2740: Add support for generic raw formats Sakari Ailus
2026-11-18 13:27 ` [PATCH v13 53/73] media: ov2740: Add metadata layout control Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 54/73] media: ov2740: Add support for G_SELECTION IOCTL Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 55/73] media: ov2740: Add support for FLL and LLP controls Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 56/73] media: ov2740: Signal common raw sensor model support Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 57/73] media: ov2740: Add IMMUTABLE and STATIC route flags Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 58/73] media: imx219: Add internal image pad for Common Raw Sensor Model Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 59/73] media: imx219: Add image stream Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 60/73] media: imx219: Report internal routes to userspace Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 61/73] media: imx219: Report streams using frame descriptors Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 62/73] media: imx219: Add embedded data support Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 63/73] media: imx219: Add support for generic raw formats Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 64/73] media: imx219: Add V4L2_CID_BINNING_FACTORS Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 65/73] media: imx219: Allow configuring cropping and binning through CRSM Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 66/73] media: imx219: Support LINE_LENGTH_PIXELS and FRAME_LENGTH_LINES controls Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 67/73] media: v4l2-common: Add helper function media_bus_fmt_to_csi2_(bpp|dt)() Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 68/73] media: bcm2835-unicam: Support generic raw formats Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 69/73] media: ipu6: Add support for raw CFA-agnostic formats Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 70/73] media: ipu6: Add support for generic unpacked pixel and metadata formats Sakari Ailus
2026-11-18 13:28 ` Sakari Ailus [this message]
2026-11-18 13:28 ` [PATCH v13 72/73] media: uapi: Add generic raw pixelformat for 16 bpp Sakari Ailus
2026-11-18 13:28 ` [PATCH v13 73/73] media: uapi: Add generic CSI-2 raw pixelformats for 16, 20, 24 and 28 bpp Sakari Ailus

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261118132819.213473-72-sakari.ailus@linux.intel.com \
    --to=sakari.ailus@linux.intel.com \
    --cc=antti.laakso@linux.intel.com \
    --cc=benjamin.mugnier@foss.st.com \
    --cc=christophe.jaillet@wanadoo.fr \
    --cc=dave.stevenson@raspberrypi.com \
    --cc=david.plowman@raspberrypi.com \
    --cc=divyamani.tripathi@intel.com \
    --cc=dongcheng.yan@intel.com \
    --cc=git@apitzsch.eu \
    --cc=hans@jjverkuil.nl \
    --cc=hansg@kernel.org \
    --cc=heimir.sverrisson@gmail.com \
    --cc=hpa@redhat.com \
    --cc=jacopo.mondi@ideasonboard.com \
    --cc=jai.luthra@ideasonboard.com \
    --cc=julien.massot@collabora.com \
    --cc=khai.wen.ng@intel.com \
    --cc=kieran.bingham@ideasonboard.com \
    --cc=laurent.pinchart@ideasonboard.com \
    --cc=linux-media@vger.kernel.org \
    --cc=manik.bajpai@intel.com \
    --cc=mehdi.djait@linux.intel.com \
    --cc=mirela.rabulea@nxp.com \
    --cc=mkorpershoek@kernel.org \
    --cc=naush@raspberrypi.com \
    --cc=ong.hock.yu@intel.com \
    --cc=prabhakar.csengg@gmail.com \
    --cc=r-donadkar@ti.com \
    --cc=ribalda@kernel.org \
    --cc=stefan.klug@ideasonboard.com \
    --cc=sylvain.petinot@foss.st.com \
    --cc=tomi.valkeinen@ideasonboard.com \
    --cc=tomm.merciai@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox