[PATCH v1 4/4] media: docs: Add userspace-API guide for the IMX585 driver

[Will Whang <will@willwhang.com>]

The new IMX585 V4L2 sub-device driver introduces several
driver-specific controls for configuring Clear-HDR blending,
gradation compression thresholds, and HCG enabling.  This patch adds
an rst document under Documentation/userspace-api/media/drivers/
that details each control, allowed values, and their effect

Signed-off-by: Will Whang <will@willwhang.com>
---
 .../userspace-api/media/drivers/imx585.rst    | 95 +++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 Documentation/userspace-api/media/drivers/imx585.rst

diff --git a/Documentation/userspace-api/media/drivers/imx585.rst b/Documentation/userspace-api/media/drivers/imx585.rst
new file mode 100644
index 000000000..bb08afa93
--- /dev/null
+++ b/Documentation/userspace-api/media/drivers/imx585.rst
@@ -0,0 +1,95 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+Sony IMX585 driver
+==================
+
+The IMX585 image-sensor driver provides the following *driver-specific*
+V4L2 controls.  They are visible only when the IMX585 driver is loaded
+and sit in the sensor-private control class.
+
+HDR data blending
+-----------------
+
+``V4L2_CID_IMX585_HDR_DATASEL_TH``  (``U16[2]``)
+    Lower/upper **thresholds** (0 – 4095) that decide which exposure is
+    chosen—or blended—for each pixel in Clear-HDR mode.
+
+``V4L2_CID_IMX585_HDR_DATASEL_BK``  (menu)
+    **Blending ratio** between the long-gain (LG) and
+    high-gain (HG) read-outs.
+
+    .. flat-table::
+        :stub-columns: 0
+        :widths: 1 5
+
+        * - ``0``  - HG ½, LG ½
+        * - ``1``  - HG ¾, LG ¼
+        * - ``2``  - HG ½, LG ½  *(duplicate ratio present in the
+          datasheet)*
+        * - ``3``  - HG ⅞, LG ⅛
+        * - ``4``  - HG 15⁄16, LG 1⁄16
+        * - ``5``  - **2ⁿᵈ** HG ½, LG ½  *(second 50 %-50 % entry as
+          documented)*
+        * - ``6``  - HG 1⁄16, LG 15⁄16
+        * - ``7``  - HG ⅛, LG ⅞
+        * - ``8``  - HG ¼, LG ¾
+
+Gradation compression
+---------------------
+
+``V4L2_CID_IMX585_HDR_GRAD_TH``  (``U32[2]``)
+    17-bit **break-points** (0 – 0x1ffff) that shape the 16-bit
+    gradation-compression curve.
+
+``V4L2_CID_IMX585_HDR_GRAD_COMP_L``  (menu)
+``V4L2_CID_IMX585_HDR_GRAD_COMP_H``  (menu)
+    **Compression ratios** below the first break-point and between the
+    two break-points, respectively.
+
+    .. flat-table::
+        :stub-columns: 0
+        :widths: 1 4
+
+        * - ``0``  - 1 : 1
+        * - ``1``  - 1 : 2
+        * - ``2``  - 1 : 4   *(default for COMP_L)*
+        * - ``3``  - 1 : 8
+        * - ``4``  - 1 : 16
+        * - ``5``  - 1 : 32
+        * - ``6``  - 1 : 64  *(default for COMP_H)*
+        * - ``7``  - 1 : 128
+        * - ``8``  - 1 : 256
+        * - ``9``  - 1 : 512
+        * - ``10`` - 1 : 1024
+        * - ``11`` - 1 : 2048
+
+Gain settings
+-------------
+
+``V4L2_CID_IMX585_HDR_GAIN``  (menu)
+    **Additional gain** (in dB) applied to the high-gain path when
+    Clear-HDR is active.
+
+    .. flat-table::
+        :stub-columns: 0
+        :widths: 1 3
+
+        * - ``0``  - +0 dB
+        * - ``1``  - +6 dB
+        * - ``2``  - +12 dB *(default)*
+        * - ``3``  - +18 dB
+        * - ``4``  - +24 dB
+        * - ``5``  - +29.1 dB
+
+``V4L2_CID_IMX585_HCG_GAIN``  (boolean)
+    Toggle **High-Conversion-Gain** mode.
+
+    *0 = LCG (default), 1 = HCG.*
+
+Notes
+-----
+
+* Controls are writable while streaming; changes take effect from the
+  next frame.
+* HDR-specific controls are hidden when HDR is disabled.
+* Inter-control dependencies are enforced by the driver.
-- 
2.39.5