Commit adb2dcd5 authored by Sakari Ailus's avatar Sakari Ailus Committed by Mauro Carvalho Chehab
Browse files

media: v4l: async: Rename v4l2_async_subdev as v4l2_async_connection 



Rename v4l2_async_subdev as v4l2_async_connection, in order to
differentiate between the sub-devices and their connections: one
sub-device can have many connections but the V4L2 async framework has so
far allowed just a single one. Connections in this context will later
translate into either MC ancillary or data links.

This patch prepares changing that relation by changing existing users of
v4l2_async_subdev to switch to v4l2_async_connection. Async sub-devices
themselves will not be needed anymore

Additionally, __v4l2_async_nf_add_subdev() has been renamed
__v4l2_async_nf_add_connection().

Signed-off-by: default avatarSakari Ailus <sakari.ailus@linux.intel.com>
Tested-by: Philipp Zabel <p.zabel@pengutronix.de> # imx6qp
Tested-by: Niklas Söderlund <niklas.soderlund@ragnatech.se> # rcar + adv746x
Tested-by: Aishwarya Kothari <aishwarya.kothari@toradex.com> # Apalis i.MX6Q with TC358743
Tested-by: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com> # Renesas RZ/G2L SMARC
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@kernel.org>
parent 1029939b

Documentation/driver-api/media/v4l2-subdev.rst

+29 −22
Original line number Diff line number Diff line
@@ -206,60 +206,67 @@ of an unregister notifier, it must be cleaned up by calling 


Before registering the notifier, bridge drivers must do two things: first, the

notifier must be initialized using the :c:func:`v4l2_async_nf_init`.  Second,

bridge drivers can then begin to form a list of subdevice descriptors that the

bridge device needs for its operation. :c:func:`v4l2_async_nf_add_fwnode`,

bridge drivers can then begin to form a list of async connection descriptors

that the bridge device needs for its

operation. :c:func:`v4l2_async_nf_add_fwnode`,

:c:func:`v4l2_async_nf_add_fwnode_remote` and :c:func:`v4l2_async_nf_add_i2c`

are available for that purpose.



Async connection descriptors describe connections to external sub-devices the

drivers for which are not yet probed. Based on an async connection, a media data

or ancillary link may be created when the related sub-device becomes

available. There may be one or more async connections to a given sub-device but

this is not known at the time of adding the connections to the notifier. Async

connections are bound as matching async sub-devices are found, one by one.



Asynchronous sub-device registration helper for camera sensor drivers

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



:c:func:`v4l2_async_register_subdev_sensor` is a helper function for sensor

drivers registering their own async sub-device, but it also registers a notifier

and further registers async sub-devices for lens and flash devices found in

drivers registering their own async connection, but it also registers a notifier

and further registers async connections for lens and flash devices found in

firmware. The notifier for the sub-device is unregistered and cleaned up with

the async sub-device, using :c:func:`v4l2_async_unregister_subdev`.



Asynchronous sub-device notifier example

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



These functions allocate an async sub-device descriptor which is of type struct

:c:type:`v4l2_async_subdev` embedded in a driver-specific struct. The &struct

:c:type:`v4l2_async_subdev` shall be the first member of this struct:

These functions allocate an async connection descriptor which is of type struct

:c:type:`v4l2_async_connection` embedded in a driver-specific struct. The &struct

:c:type:`v4l2_async_connection` shall be the first member of this struct:



.. code-block:: c



	struct my_async_subdev {

		struct v4l2_async_subdev asd;

	struct my_async_connection {

		struct v4l2_async_connection asc;

		...

	};



	struct my_async_subdev *my_asd;

	struct my_async_connection *my_asc;

	struct fwnode_handle *ep;



	...



	my_asd = v4l2_async_nf_add_fwnode_remote(&notifier, ep,

						 struct my_async_subdev);

	my_asc = v4l2_async_nf_add_fwnode_remote(&notifier, ep,

						 struct my_async_connection);

	fwnode_handle_put(ep);



	if (IS_ERR(my_asd))

		return PTR_ERR(my_asd);

	if (IS_ERR(my_asc))

		return PTR_ERR(my_asc);



Asynchronous sub-device notifier callbacks

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



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.

The V4L2 core will then use these connection descriptors to match asynchronously

registered subdevices to them. If a match is detected the ``.bound()`` notifier

callback is called. After all connections have been bound the .complete()

callback is called. When a connection is removed from the system the

``.unbind()`` method is called. All three callbacks are optional.



Drivers can store any type of custom data in their driver-specific

:c:type:`v4l2_async_subdev` wrapper. If any of that data requires special

:c:type:`v4l2_async_connection` wrapper. If any of that data requires special

handling when the structure is freed, drivers must implement the ``.destroy()``

notifier callback. The framework will call it right before freeing the

:c:type:`v4l2_async_subdev`.

:c:type:`v4l2_async_connection`.



Calling subdev operations

~~~~~~~~~~~~~~~~~~~~~~~~~

drivers/media/i2c/ds90ub913.c

+3 −3
Original line number Diff line number Diff line
@@ -518,7 +518,7 @@ static const struct media_entity_operations ub913_entity_ops = { 


static int ub913_notify_bound(struct v4l2_async_notifier *notifier,

			      struct v4l2_subdev *source_subdev,

			      struct v4l2_async_subdev *asd)

			      struct v4l2_async_connection *asd)

{

	struct ub913_data *priv = sd_to_ub913(notifier->sd);

	struct device *dev = &priv->client->dev;
@@ -557,7 +557,7 @@ static const struct v4l2_async_notifier_operations ub913_notify_ops = { 
static int ub913_v4l2_notifier_register(struct ub913_data *priv)

{

	struct device *dev = &priv->client->dev;

	struct v4l2_async_subdev *asd;

	struct v4l2_async_connection *asd;

	struct fwnode_handle *ep_fwnode;

	int ret;
@@ -571,7 +571,7 @@ static int ub913_v4l2_notifier_register(struct ub913_data *priv) 
	v4l2_async_nf_init(&priv->notifier);



	asd = v4l2_async_nf_add_fwnode_remote(&priv->notifier, ep_fwnode,

					      struct v4l2_async_subdev);

					      struct v4l2_async_connection);



	fwnode_handle_put(ep_fwnode);

drivers/media/i2c/ds90ub953.c

+3 −3
Original line number Diff line number Diff line
@@ -723,7 +723,7 @@ static const struct media_entity_operations ub953_entity_ops = { 


static int ub953_notify_bound(struct v4l2_async_notifier *notifier,

			      struct v4l2_subdev *source_subdev,

			      struct v4l2_async_subdev *asd)

			      struct v4l2_async_connection *asd)

{

	struct ub953_data *priv = sd_to_ub953(notifier->sd);

	struct device *dev = &priv->client->dev;
@@ -762,7 +762,7 @@ static const struct v4l2_async_notifier_operations ub953_notify_ops = { 
static int ub953_v4l2_notifier_register(struct ub953_data *priv)

{

	struct device *dev = &priv->client->dev;

	struct v4l2_async_subdev *asd;

	struct v4l2_async_connection *asd;

	struct fwnode_handle *ep_fwnode;

	int ret;
@@ -776,7 +776,7 @@ static int ub953_v4l2_notifier_register(struct ub953_data *priv) 
	v4l2_async_nf_init(&priv->notifier);



	asd = v4l2_async_nf_add_fwnode_remote(&priv->notifier, ep_fwnode,

					      struct v4l2_async_subdev);

					      struct v4l2_async_connection);



	fwnode_handle_put(ep_fwnode);

drivers/media/i2c/ds90ub960.c

+4 −4
Original line number Diff line number Diff line
@@ -471,11 +471,11 @@ struct ub960_rxport { 
};



struct ub960_asd {

	struct v4l2_async_subdev base;

	struct v4l2_async_connection base;

	struct ub960_rxport *rxport;

};



static inline struct ub960_asd *to_ub960_asd(struct v4l2_async_subdev *asd)

static inline struct ub960_asd *to_ub960_asd(struct v4l2_async_connection *asd)

{

	return container_of(asd, struct ub960_asd, base);

}
@@ -3538,7 +3538,7 @@ static int ub960_parse_dt(struct ub960_data *priv) 


static int ub960_notify_bound(struct v4l2_async_notifier *notifier,

			      struct v4l2_subdev *subdev,

			      struct v4l2_async_subdev *asd)

			      struct v4l2_async_connection *asd)

{

	struct ub960_data *priv = sd_to_ub960(notifier->sd);

	struct ub960_rxport *rxport = to_ub960_asd(asd)->rxport;
@@ -3581,7 +3581,7 @@ static int ub960_notify_bound(struct v4l2_async_notifier *notifier, 


static void ub960_notify_unbind(struct v4l2_async_notifier *notifier,

				struct v4l2_subdev *subdev,

				struct v4l2_async_subdev *asd)

				struct v4l2_async_connection *asd)

{

	struct ub960_rxport *rxport = to_ub960_asd(asd)->rxport;

drivers/media/i2c/max9286.c

+5 −4
Original line number Diff line number Diff line
@@ -161,11 +161,12 @@ struct max9286_source { 
};



struct max9286_asd {

	struct v4l2_async_subdev base;

	struct v4l2_async_connection base;

	struct max9286_source *source;

};



static inline struct max9286_asd *to_max9286_asd(struct v4l2_async_subdev *asd)

static inline struct max9286_asd *

to_max9286_asd(struct v4l2_async_connection *asd)

{

	return container_of(asd, struct max9286_asd, base);

}
@@ -659,7 +660,7 @@ static int max9286_set_pixelrate(struct max9286_priv *priv) 


static int max9286_notify_bound(struct v4l2_async_notifier *notifier,

				struct v4l2_subdev *subdev,

				struct v4l2_async_subdev *asd)

				struct v4l2_async_connection *asd)

{

	struct max9286_priv *priv = sd_to_max9286(notifier->sd);

	struct max9286_source *source = to_max9286_asd(asd)->source;
@@ -721,7 +722,7 @@ static int max9286_notify_bound(struct v4l2_async_notifier *notifier, 


static void max9286_notify_unbind(struct v4l2_async_notifier *notifier,

				  struct v4l2_subdev *subdev,

				  struct v4l2_async_subdev *asd)

				  struct v4l2_async_connection *asd)

{

	struct max9286_priv *priv = sd_to_max9286(notifier->sd);

	struct max9286_source *source = to_max9286_asd(asd)->source;