The previous frame interval formula used analogue crop dimensions. This
diverges from what most (non-CCS) raw camera sensor drivers do and what
most applications expect.

The CCS specification describes under section "8.2.6 Line Length and
Frame Length" how the horizontal and vertical readout minimums can be
different when binning.

We see the same thing in non-CCS sensor drivers, for example in imx219
the minimum FLL (frame length in lines) can be lower than the analogue
crop height when doing 2x2 or 4x4 binning. Similarly in imx283 HMAX
(line length) can be lower compared to the analogue crop width when
doing 2x2 or 3x3 binning.

While the CCS driver defines the HBLANK/VBLANK controls with respect to
the analogue crop rectangle, with possibly negative values for blanking,
most other raw sensor drivers instead define them with respect to the
output dimensions (width and height of the source pad format) sent on
the bus.

So fix the frame interval calculation described in the documentation to
match the reality of existing drivers, separating out the CCS and
non-CCS cases. In future, with the common raw sensor model, this may
need further updates.

While at it, also clarify the order of operations in the sensor pipeline
and give the "hardware" definition for frame interval using the pixel
readout rate, LLP (line length in pixels) and FLL (frame length in
lines). Also link to the definitions of PIXEL_RATE, HBLANK and VBLANK
controls.

Signed-off-by: Jai Luthra <jai.luthra@ideasonboard.com>
---
Changes in v3:
- Include suggestions from Jacopo (linking to VBLANK/HBLANK/PIXEL_RATE
  controls, rewording a couple of lines)
- Include suggestions from Dave (clarifying LLP/HMAX can be in scaled
  units compared to the pixel rate)
- Reword the whole section again so it makes sense (thus not taking the
  Review tag from Jacopo on v2)
- Link to v2: https://lore.kernel.org/r/20260225-media-fps-docs-v2-1-5cb222d41e4d@ideasonboard.com

Changes in v2:
- Use reStructureText note box for describing the
  HBLANK/VBLANK/PIXEL_RATE controls
- Document the blanking formula for both CCS and non-CCS raw
  sensor drivers
- Drop driver-api documentation as common raw sensor model is coming
  soon
- Link to v1: https://lore.kernel.org/r/20260219-media-fps-docs-v1-1-0387c5c5368c@ideasonboard.com
---
 .../userspace-api/media/drivers/camera-sensor.rst  | 99 ++++++++++++++++------
 .../media/v4l/ext-ctrls-image-source.rst           |  4 +
 2 files changed, 75 insertions(+), 28 deletions(-)

diff --git a/Documentation/userspace-api/media/drivers/camera-sensor.rst b/Documentation/userspace-api/media/drivers/camera-sensor.rst
index 75fd9166383f..07a679525f0c 100644
--- a/Documentation/userspace-api/media/drivers/camera-sensor.rst
+++ b/Documentation/userspace-api/media/drivers/camera-sensor.rst
@@ -49,34 +49,77 @@ depends on the type of the device.
 Raw camera sensors
 ~~~~~~~~~~~~~~~~~~
 
-Instead of a high level parameter such as frame interval, the frame interval is
-a result of the configuration of a number of camera sensor implementation
-specific parameters. Luckily, these parameters tend to be the same for more or
-less all modern raw camera sensors.
-
-The frame interval is calculated using the following equation::
-
-	frame interval = (analogue crop width + horizontal blanking) *
-			 (analogue crop height + vertical blanking) / pixel rate
-
-The formula is bus independent and is applicable for raw timing parameters on
-large variety of devices beyond camera sensors. Devices that have no analogue
-crop, use the full source image size, i.e. pixel array size.
-
-Horizontal and vertical blanking are specified by ``V4L2_CID_HBLANK`` and
-``V4L2_CID_VBLANK``, respectively. The unit of the ``V4L2_CID_HBLANK`` control
-is pixels and the unit of the ``V4L2_CID_VBLANK`` is lines. The pixel rate in
-the sensor's **pixel array** is specified by ``V4L2_CID_PIXEL_RATE`` in the same
-sub-device. The unit of that control is pixels per second.
-
-Register list-based drivers need to implement read-only sub-device nodes for the
-purpose. Devices that are not register list based need these to configure the
-device's internal processing pipeline.
-
-The first entity in the linear pipeline is the pixel array. The pixel array may
-be followed by other entities that are there to allow configuring binning,
-skipping, scaling or digital crop, see :ref:`VIDIOC_SUBDEV_G_SELECTION
-<VIDIOC_SUBDEV_G_SELECTION>`.
+Instead of a high level parameter such as frame interval, the frame interval on
+a raw camera sensor is determined by a number of sensor-specific parameters.
+These parameters tend to be common across most modern raw camera sensors.
+
+The pixel array is the full grid of photosensitive elements on the camera
+sensor. A subregion of it is selected by the analogue crop. The cropped image
+may then be subject to binning (averaging of an NxN block) and subsampling
+which further reduce the image dimensions. The resulting image is then read out
+by the ADC (analogue-to-digital converter) line by line. After ADC readout,
+optional digital crop or scaling may further reduce the image dimensions, see
+:ref:`VIDIOC_SUBDEV_G_SELECTION <VIDIOC_SUBDEV_G_SELECTION>`.
+
+The sensor scales the input clock to a (usually) fixed pixel readout rate. Thus
+the frame interval is determined by two fundamental timing registers: **line
+length in pixels (LLP)** and **frame length in lines (FLL)**.
+
+LLP is the total number of pixels per line, including both the active readout
+width and horizontal blanking. FLL is the total number of lines per frame,
+including both the active readout height and vertical blanking. These two
+parameters allow controlling the total time taken to read out an image by
+adjusting the blanking intervals.
+
+These registers may go by other names for different sensors, like HMAX and
+VMAX, or HTOTAL and VTOTAL, or similar. They are exposed to userspace
+applications through the horizontal and vertical blanking controls.
+
+For some sensors the value for the horizontal timing (LLP/HMAX/HTOTAL) may be
+in cycles of an internal clock, where multiple pixels are read out per cycle.
+In such cases the driver should handle this scaling internally, ensuring the
+userspace control for the horizontal blanking is always in units of pixels.
+
+So the frame interval can be calculated as::
+
+        frame interval = (LLP * FLL) / pixel rate
+
+See the note below on how applications can map this to the blanking and pixel
+rate controls:
+
+.. note::
+
+	Horizontal and vertical blanking are specified by :ref:`V4L2_CID_HBLANK
+	<v4l2-cid-hblank>` and :ref:`V4L2_CID_VBLANK <v4l2-cid-vblank>`,
+	respectively. The unit of ``HBLANK`` is pixels, and the unit of
+	``VBLANK`` is lines.
+
+	The pixel rate in the sensor's pixel array is specified by
+	:ref:`V4L2_CID_PIXEL_RATE <v4l2-cid-pixel-rate>`, in units of pixels
+	per second.
+
+	Sensor drivers are required to implement sub-device nodes that expose
+	these controls. They can be read-only or configurable depending on the
+	device.
+
+	For most raw sensors the blanking is defined relative to the size of
+	the image being sent out to the host over the bus (source pad format)::
+
+                LLP = output width + horizontal blanking
+                FLL = output height + vertical blanking
+
+        For CCS-compliant raw sensors (that use the CCS driver), the blanking
+        controls are defined relative to the analogue crop rectangle::
+
+                LLP = analogue crop width + horizontal blanking
+                FLL = analogue crop height + vertical blanking
+
+Some sensors may lower the minimum allowed values for LLP and/or FLL when
+binning or subsampling, thus increasing the effective frame rate.
+
+The driver shall update the minimum and maximum values of the blanking controls
+so that the resulting LLP and FLL registers are programmed within the range
+permitted by the sensor hardware for the current mode.
 
 USB cameras etc. devices
 ~~~~~~~~~~~~~~~~~~~~~~~~
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 f9c0b7ad3b4e..1a61acb0bb1a 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst
@@ -21,6 +21,8 @@ Image Source Control IDs
 ``V4L2_CID_IMAGE_SOURCE_CLASS (class)``
     The IMAGE_SOURCE class descriptor.
 
+.. _v4l2-cid-vblank:
+
 ``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.
@@ -28,6 +30,8 @@ Image Source Control IDs
     the pixel rate defined by ``V4L2_CID_PIXEL_RATE`` control in the
     same sub-device.
 
+.. _v4l2-cid-hblank:
+
 ``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

---
base-commit: 254f49634ee16a731174d2ae34bc50bd5f45e731
change-id: 20260219-media-fps-docs-fd1da722cc38

Best regards,
-- 
Jai Luthra <jai.luthra@ideasonboard.com>