[libcamera-devel] [PATCH 2/4] media: docs: Describe targets for sensor properties

[Jacopo Mondi]

Hi Hans,

On Thu, Aug 06, 2020 at 12:15:49PM +0200, Hans Verkuil wrote:
> On 06/08/2020 12:08, Jacopo Mondi wrote:
> > Hi Hans,
> >
> > On Thu, Aug 06, 2020 at 10:45:17AM +0200, Hans Verkuil wrote:
> >> On 05/08/2020 12:57, Jacopo Mondi wrote:
> >>> Provide a table to describe how the V4L2 selection targets can be used
> >>> to access an image sensor pixel array properties.
> >>>
> >>> Reference the table in the sub-device documentation.
> >>>
> >>> Signed-off-by: Jacopo Mondi <jacopo at jmondi.org>
> >>> ---
> >>>  .../userspace-api/media/v4l/dev-subdev.rst    |  4 ++
> >>>  .../media/v4l/v4l2-selection-targets.rst      | 49 +++++++++++++++++++
> >>>  2 files changed, 53 insertions(+)
> >>>
> >>> diff --git a/Documentation/userspace-api/media/v4l/dev-subdev.rst b/Documentation/userspace-api/media/v4l/dev-subdev.rst
> >>> index c47861dff9b9b..2f7da3832f458 100644
> >>> --- a/Documentation/userspace-api/media/v4l/dev-subdev.rst
> >>> +++ b/Documentation/userspace-api/media/v4l/dev-subdev.rst
> >>> @@ -467,6 +467,10 @@ desired image resolution. If the sub-device driver supports that, userspace
> >>>  can set the analog crop rectangle to select which portion of the pixel array
> >>>  to read out.
> >>>
> >>> +A description of each of the above mentioned targets when used to access the
> >>> +image sensor pixel array properties is provided by
> >>> +:ref:`v4l2-selection-targets-image-sensor-table`
> >>> +
> >>>
> >>>  Types of selection targets
> >>>  --------------------------
> >>> diff --git a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst
> >>> index 69f500093aa2a..632e6448b784e 100644
> >>> --- a/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst
> >>> +++ b/Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst
> >>> @@ -76,3 +76,52 @@ of the two interfaces they are used.
> >>>  	modified by hardware.
> >>>        - Yes
> >>>        - No
> >>> +
> >>> +
> >>> +.. _v4l2-selection-targets-image-sensor-table:
> >>> +
> >>> +********************************************
> >>> +Selection Targets For Pixel Array Properties
> >>> +********************************************
> >>> +
> >>> +The V4L2 selection API can be used to retrieve the size and disposition of the
> >>> +pixel units that compose and image sensor pixel matrix when applied to a video
> >>> +sub-device that represents an image sensor.
> >>> +
> >>> +A description of the properties associated with each of the sensor pixel array
> >>> +areas is provided by the :ref:`v4l2-subdev-pixel-array-properties` section.
> >>> +
> >>> +.. tabularcolumns:: |p{6.0cm}|p{1.4cm}|p{7.4cm}|p(1.4cm)|
> >>> +
> >>> +.. flat-table:: Selection target definitions
> >>> +    :header-rows:  1
> >>> +    :stub-columns: 0
> >>> +
> >>> +    * - Target name
> >>> +      - id
> >>> +      - Definition
> >>> +      - Read/Write
> >>> +    * - ``V4L2_SEL_TGT_CROP``
> >>> +      - 0x0000
> >>> +      - The analog crop rectangle. Represents the portion of the active pixel
> >>> +        array which is processed to produce images.
> >>> +      - RW
> >>> +    * - ``V4L2_SEL_TGT_CROP_DEFAULT``
> >>> +      - 0x0001
> >>> +      - The active pixel array rectangle. It includes only active pixels and
> >>> +        excludes other ones such as optical black pixels. Its width and height
> >>> +        represent the maximum image resolution an image sensor can produce.
> >>> +      - RO
> >>> +    * - ``V4L2_SEL_TGT_CROP_BOUNDS``
> >>> +      - 0x0002
> >>> +      - The readable portion of the physical pixel array matrix. It includes
> >>> +        pixels that contains valid image data and calibration pixels such as the
> >>> +        optical black ones.
> >>> +      - RO
> >>> +    * - ``V4L2_SEL_TGT_NATIVE_SIZE``
> >>> +      - 0x0003
> >>> +      - The physical pixel array size, including readable and not readable
> >>> +        pixels. As pixels that cannot be read from application processor are not
> >>> +        relevant for calibration purposes, this rectangle is useful to calculate
> >>> +        the physical properties of the image sensor.
> >>> +      - RO
> >>>
> >>
> >> Hmm, this basically just duplicates the previous patch.
> >>
> >> I think you are documenting things at the wrong place. What you documented in the
> >> previous patch really belongs here since it is shared between the subdev API and the
> >> regular V4L2 API. And in dev-subdev.rst you then refer to here.
> >
> > I originally had it here, but then I moved to dev-subdev as an image
> > sensor will always be represented as a video sub-device, doen't it ?
>
> No. Some camera drivers are V4L2 only, most notably uvc. Also there are several simple
> platform drivers that don't use the subdev API.

Do we expect to be able to retrieve sensor array properties from video
device nodes which represents, in my understanding a DMA engine that
writes data to memory ? As I see it, not subdev for the image sensor,
no pixel array properties. How can these be exposed by a video device
which abstracts the full capture pipeline ?