Re: [PATCH v2] V4L2: add documentation for V4L2 clock helpers and asynchronous probing

[Sylwester Nawrocki <sylvester.nawrocki@gmail.com>]

Hi Guennadi,

On 06/24/2013 01:20 PM, Guennadi Liakhovetski wrote:
> Add documentation for the V4L2 clock and V4L2 asynchronous probing APIs
> to v4l2-framework.txt.
>
> Signed-off-by: Guennadi Liakhovetski<g.liakhovetski@gmx.de>
> ---
>
> v2: addressed comments by Hans and Laurent (thanks), including
> (a) language clean up
> (b) extended the V4L2 clock API section with an explanation, what special
> requirements V4L2 has and a mention of it being temporary until CCF is
> used by all
> (c) added an explanation of the use of -EPROBE_DEFER

Looks pretty good.

  Reviewed-by: Sylwester Nawrocki <s.nawrocki@samsung.com>

Just one remark below...

>   Documentation/video4linux/v4l2-framework.txt |   73 +++++++++++++++++++++++++-
>   1 files changed, 71 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt
> index b5e6347..00a9d21 100644
> --- a/Documentation/video4linux/v4l2-framework.txt
> +++ b/Documentation/video4linux/v4l2-framework.txt
> @@ -325,8 +325,27 @@ that width, height and the media bus pixel code are equal on both source and
>   sink of the link. Subdev drivers are also free to use this function to
>   perform the checks mentioned above in addition to their own checks.
>
> -A device (bridge) driver needs to register the v4l2_subdev with the
> -v4l2_device:
> +There are currently two ways to register subdevices with the V4L2 core. The
> +first (traditional) possibility is to have subdevices registered by bridge
> +drivers. This can be done when the bridge driver has the complete information
> +about subdevices connected to it and knows exactly when to register them. This
> +is typically the case for internal subdevices, like video data processing units
> +within SoCs or complex PCI(e) boards, camera sensors in USB cameras or connected
> +to SoCs, which pass information about them to bridge drivers, usually in their
> +platform data.
> +
> +There are however also situations where subdevices have to be registered
> +asynchronously to bridge devices. An example of such a configuration is a Device
> +Tree based systems where information about subdevices is made available to the

I think you need to substitute "is a Device Tree based systems" with either:
"are Device Tree based systems" or
"is a Device Tree based system".

> +system independently from the bridge devices, e.g. when subdevices are defined
> +in DT as I2C device nodes. The API used in this second case is described further
> +below.
> +
> +Using one or the other registration method only affects the probing process, the
> +run-time bridge-subdevice interaction is in both cases the same.
> +
> +In the synchronous case a device (bridge) driver needs to register the
> +v4l2_subdev with the v4l2_device:
>
>   	int err = v4l2_device_register_subdev(v4l2_dev, sd);
>
> @@ -393,6 +412,30 @@ controlled through GPIO pins. This distinction is only relevant when setting
>   up the device, but once the subdev is registered it is completely transparent.
>
>
> +In the asynchronous case subdevice probing can be invoked independently of the
> +bridge driver availability. The subdevice driver then has to verify whether all
> +the requirements for a successful probing are satisfied. This can include a
> +check for a master clock availability. If any of the conditions aren't satisfied
> +the driver might decide to return -EPROBE_DEFER to request further reprobing
> +attempts. Once all conditions are met the subdevice shall be registered using
> +the v4l2_async_register_subdev() function. Unregistration is performed using
> +the v4l2_async_unregister_subdev() call. Subdevices registered this way are
> +stored in a global list of subdevices, ready to be picked up by bridge drivers.
> +
> +Bridge drivers in turn have to register a notifier object with an array of
> +subdevice descriptors that the bridge device needs for its operation. This is
> +performed using the v4l2_async_notifier_register() call. To unregister the
> +notifier the driver has to call v4l2_async_notifier_unregister(). The former of
> +the two functions takes two arguments: a pointer to struct v4l2_device and a
> +pointer to struct v4l2_async_notifier. The latter contains a pointer to an array
> +of pointers to subdevice descriptors of type struct v4l2_async_subdev type. The
> +V4L2 core will then use these descriptors to match asynchronously registered
> +subdevices to them. If a match is detected the .bound() notifier callback is
> +called. After all subdevices have been located the .complete() callback is
> +called. When a subdevice is removed from the system the .unbind() method is
> +called. All three callbacks are optional.
> +
> +
>   V4L2 sub-device userspace API
>   -----------------------------
>
> @@ -1065,3 +1108,29 @@ available event type is 'class base + 1'.
>
>   An example on how the V4L2 events may be used can be found in the OMAP
>   3 ISP driver (drivers/media/platform/omap3isp).
> +
> +
> +V4L2 clocks
> +-----------
> +
> +Many subdevices, like camera sensors, TV decoders and encoders, need a clock
> +signal to be supplied by the system. Often this clock is supplied by the
> +respective bridge device. The Linux kernel provides a Common Clock Framework for
> +this purpose. However, it is not (yet) available on all architectures. Besides,
> +the nature of the multi-functional (clock, data + synchronisation, I2C control)
> +connection of subdevices to the system might impose special requirements on the
> +clock API usage. E.g. V4L2 has to support clock provider driver unregistration
> +while a subdevice driver is holding a reference to the clock. For these reasons
> +a V4L2 clock helper API has been developed and is provided to bridge and
> +subdevice drivers.
> +
> +The API consists of two parts: two functions to register and unregister a V4L2
> +clock source: v4l2_clk_register() and v4l2_clk_unregister() and calls to control
> +a clock object, similar to the respective generic clock API calls:
> +v4l2_clk_get(), v4l2_clk_put(), v4l2_clk_enable(), v4l2_clk_disable(),
> +v4l2_clk_get_rate(), and v4l2_clk_set_rate(). Clock suppliers have to provide
> +clock operations that will be called when clock users invoke respective API
> +methods.
> +
> +It is expected that once the CCF becomes available on all relevant
> +architectures this API will be removed.

Thanks,
Sylwester