Hi Tomi, Thank you for the patch. On Mon, Feb 07, 2022 at 06:11:06PM +0200, Tomi Valkeinen wrote: > Add documentation about centrally managed subdev state. > > Signed-off-by: Tomi Valkeinen <tomi.valkeinen@xxxxxxxxxxxxxxxx> > Reviewed-by: Jacopo Mondi <jacopo+renesas@xxxxxxxxxx> > Reviewed-by: Hans Verkuil <hverkuil-cisco@xxxxxxxxx> Reviewed-by: Laurent Pinchart <laurent.pinchart@xxxxxxxxxxxxxxxx> > --- > .../driver-api/media/v4l2-subdev.rst | 60 +++++++++++++++++++ > 1 file changed, 60 insertions(+) > > diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst > index 08ea2673b19e..6b14cc97afa3 100644 > --- a/Documentation/driver-api/media/v4l2-subdev.rst > +++ b/Documentation/driver-api/media/v4l2-subdev.rst > @@ -518,6 +518,66 @@ The :c:func:`v4l2_i2c_new_subdev` function will call > :c:type:`i2c_board_info` structure using the ``client_type`` and the > ``addr`` to fill it. > > +Centrally managed subdev active state > +------------------------------------- > + > +Traditionally V4L2 subdev drivers maintained internal state for the active > +device configuration. This is often implemented as e.g. an array of struct > +v4l2_mbus_framefmt, one entry for each pad, and similarly for crop and compose > +rectangles. > + > +In addition to the active configuration, each subdev file handle has an array of > +struct v4l2_subdev_pad_config, managed by the V4L2 core, which contains the try > +configuration. > + > +To simplify the subdev drivers the V4L2 subdev API now optionally supports a > +centrally managed active configuration represented by > +:c:type:`v4l2_subdev_state`. One instance of state, which contains the active > +device configuration, is stored in the sub-device itself as part of > +the :c:type:`v4l2_subdev` structure, while the core associates a try state to > +each open file handle, to store the try configuration related to that file > +handle. > + > +Sub-device drivers can opt-in and use state to manage their active configuration > +by initializing the subdevice state with a call to v4l2_subdev_init_finalize() > +before registering the sub-device. They must also call v4l2_subdev_cleanup() > +to release all the allocated resources before unregistering the sub-device. > +The core automatically allocates and initializes a state for each open file > +handle to store the try configurations and frees it when closing the file > +handle. > + > +V4L2 sub-device operations that use both the :ref:`ACTIVE and TRY formats > +<v4l2-subdev-format-whence>` receive the correct state to operate on through the > +'state' parameter. The sub-device driver can access and modify the configuration > + stored in the provided state after having locked the state by calling > +:c:func:`v4l2_subdev_lock_state()`. The driver must then call > +:c:func:`v4l2_subdev_unlock_state()` to unlock the state when done. > + > +Operations that do not receive a state parameter implicitly operate on the > +subdevice active state, which drivers can exclusively access by > +calling :c:func:`v4l2_subdev_lock_active_state()`. The sub-device active state > +must equally be released by calling :c:func:`v4l2_subdev_unlock_state()`. > + > +Drivers must never manually access the state stored in the :c:type:`v4l2_subdev` > +or in the file handle without going through the designated helpers. > + > +While the V4L2 core passes the correct try or active state to the > +subdevice operations, some existing device drivers pass a NULL state > +when calling operations with :c:func:`v4l2_subdev_call()`. This legacy > +construct causes issues with subdevice drivers that let the V4L2 core > +manage the active state, as they expect to receive the appropriate state > +as a parameter. To help the conversion of subdevice drivers to a managed > +active state without having to convert all callers at the same time, the > +:c:func:`v4l2_subdev_lock_and_return_state()` helper function can be > +used by subdevice drivers to retrieve the active state if a NULL state > +is passed to the subdevice operation. > + > +:c:func:`v4l2_subdev_lock_and_return_state()` should only be used when porting > +an existing driver to the new state management when it cannot be guaranteed > +that the current callers will pass the state properly. The function prints a > +notice when the passed state is NULL to encourage the porting of the callers > +to the new state management. > + > V4L2 sub-device functions and data structures > --------------------------------------------- > -- Regards, Laurent Pinchart
