media: mc: Improve the media_entity_has_pad_interdep() documentation

Document the function parameters, the requirements on the pad0 and pad1
arguments, the locking requirements and the return value. Also improve
the documentation of the corresponding .has_pad_interdep() operation,
stating clearly that the operation must be called through the
media_entity_has_pad_interdep() function only.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

diff --git a/drivers/media/mc/mc-entity.c b/drivers/media/mc/mc-entity.c
index b8bcbc734eaf4895d27b879441ac25e5060b1f06..35ef52f6da6f66a9ff42c916f2e69830d54199f6 100644 (file)
--- a/drivers/media/mc/mc-entity.c
+++ b/drivers/media/mc/mc-entity.c
@@ -226,7 +226,13 @@ EXPORT_SYMBOL_GPL(media_entity_pads_init);
  * Graph traversal
  */
 
-/*
+/**
+ * media_entity_has_pad_interdep - Check interdependency between two pads
+ *
+ * @entity: The entity
+ * @pad0: The first pad index
+ * @pad1: The second pad index
+ *
  * This function checks the interdependency inside the entity between @pad0
  * and @pad1. If two pads are interdependent they are part of the same pipeline
  * and enabling one of the pads means that the other pad will become "locked"
@@ -236,6 +242,13 @@ EXPORT_SYMBOL_GPL(media_entity_pads_init);
  * to check the dependency inside the entity between @pad0 and @pad1. If the
  * has_pad_interdep operation is not implemented, all pads of the entity are
  * considered to be interdependent.
+ *
+ * One of @pad0 and @pad1 must be a sink pad and the other one a source pad.
+ * The function returns false if both pads are sinks or sources.
+ *
+ * The caller must hold entity->graph_obj.mdev->mutex.
+ *
+ * Return: true if the pads are connected internally and false otherwise.
  */
 static bool media_entity_has_pad_interdep(struct media_entity *entity,
                                          unsigned int pad0, unsigned int pad1)

diff --git a/include/media/media-entity.h b/include/media/media-entity.h
index 85ed08ddee9d2d5362dd09861c0ecf09bdd017d1..47863e8fde7b8c44790a218209ccb04f561b47f6 100644 (file)
--- a/include/media/media-entity.h
+++ b/include/media/media-entity.h
@@ -242,7 +242,9 @@ struct media_pad {
  *                     part of the same pipeline and enabling one of the pads
  *                     means that the other pad will become "locked" and
  *                     doesn't allow configuration changes. pad0 and pad1 are
- *                     guaranteed to not both be sinks or sources.
+ *                     guaranteed to not both be sinks or sources. Never call
+ *                     the .has_pad_interdep() operation directly, always use
+ *                     media_entity_has_pad_interdep().
  *                     Optional: If the operation isn't implemented all pads
  *                     will be considered as interdependent.
  *