[0/3] Documentation: media: camera_sensor: Document blankings handling

Hello,
   this series updates the camera-sensor documentation to indicate that
vertical and horizontal blankings should be updated when a new image format
is applied on the sensor.

1/3 is more for discussion than inclusion, as I noticed the documentation and
the CCS driver use the analogue crop rectangle sizes to compute blanking limits
while most driver use the visible size.

Which ones are correct ?

As I interpret "Figure 47 Line and Frame Blanking Definitions" in CSI-2 spec (I
have version 1.01.00 r0.04 2-Apr-2009) it seems clear to me that blankings
surround the visible size ("valid data"). However it is also correct to consider
blanking limits are a property of the pixel array usually represented by a
minx/max limits of some "total output size" register.

I wonder if it makes any real difference in practice...

3/3 also documents that exposure limits should be updated when a new vertical
blankings are applied.

I haven't documented if the actual control value should be reset to some
know value as the init-time default or to its minimum value, as described in
https://lore.kernel.org/linux-media/20221019065801.4n7alfivhffbvgzo@uno.localdomain/T/

A question for Dave: should the registration of events handler callbacks be
documented too as clarified in:
https://www.spinics.net/lists/linux-media/msg220715.html

Thanks!
  j

Jacopo Mondi (3):
  Documentation: media: camera-sensor: Correct frame interval
  documentation: media: camera_sensor: Document blankings handling
  documentation: media: camera_sensor: Update exposure on blanking
    change

 .../driver-api/media/camera-sensor.rst        | 69 +++++++++++++++++--
 1 file changed, 65 insertions(+), 4 deletions(-)

--
2.38.1

Hi Jacopo

Sorry, I should have read this fully first :)

Thanks for your efforts in writing the docs, and I appreciate it's
worse when English isn't your native language.

On Mon, 7 Nov 2022 at 20:50, Jacopo Mondi <jacopo@jmondi.org> wrote:
>
> Hello,
>    this series updates the camera-sensor documentation to indicate that
> vertical and horizontal blankings should be updated when a new image format
> is applied on the sensor.
>
> 1/3 is more for discussion than inclusion, as I noticed the documentation and
> the CCS driver use the analogue crop rectangle sizes to compute blanking limits
> while most driver use the visible size.
>
> Which ones are correct ?
>
> As I interpret "Figure 47 Line and Frame Blanking Definitions" in CSI-2 spec (I
> have version 1.01.00 r0.04 2-Apr-2009) it seems clear to me that blankings
> surround the visible size ("valid data").

I'll agree when considering the CSI-2 link.
However this is the same discussion as PIXEL_RATE vs LINK_FREQUENCY -
the blanking interval on the sensor array can differ from that on the
CSI-2 link. Largely we don't care about the CSI-2 link timings, and
frame rate is configured from PIXEL_RATE and not LINK_FREQUENCY.

> However it is also correct to consider
> blanking limits are a property of the pixel array usually represented by a
> minx/max limits of some "total output size" register.
>
> I wonder if it makes any real difference in practice...

It's only going to make any difference on binned or scaled modes,
which are not overly common in mainline drivers.

However we do have an issue of drivers accepted into mainline that
define blanking intervals based on the binned/scaled resolution and
not the analogue crop only, so how do you fix them without regressions
in the form of altered behaviour?

> 3/3 also documents that exposure limits should be updated when a new vertical
> blankings are applied.
>
> I haven't documented if the actual control value should be reset to some
> know value as the init-time default or to its minimum value, as described in
> https://lore.kernel.org/linux-media/20221019065801.4n7alfivhffbvgzo@uno.localdomain/T/
>
> A question for Dave: should the registration of events handler callbacks be
> documented too as clarified in:
> https://www.spinics.net/lists/linux-media/msg220715.html

Absolutely. Unless it gets fixed in the core then the drivers need to do it.

I have created the patches at [1] to address that issue (and the lack
of V4L2_CTRL_FLAG_MODIFY_LAYOUT on flips), but need to curate the list
of maintainers to send it to. Compile tested only as I don't have the
hardware to test all of them.
I've also pushed the start of the doc changes I was considering for
all the bits needed when implementing sensor drivers - top commit on
the same branch.

  Dave

[1] https://github.com/6by9/linux/tree/linux-media


> Thanks!
>   j
>
> Jacopo Mondi (3):
>   Documentation: media: camera-sensor: Correct frame interval
>   documentation: media: camera_sensor: Document blankings handling
>   documentation: media: camera_sensor: Update exposure on blanking
>     change
>
>  .../driver-api/media/camera-sensor.rst        | 69 +++++++++++++++++--
>  1 file changed, 65 insertions(+), 4 deletions(-)
>
> --
> 2.38.1
>