From 1ec061243edeb729ac249b278bb241a846cc8e64 Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Fri, 14 Jan 2022 01:26:26 +0100 Subject: [PATCH] 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 Reviewed-by: Tomi Valkeinen Signed-off-by: Mauro Carvalho Chehab --- drivers/media/mc/mc-entity.c | 15 ++++++++++++++- include/media/media-entity.h | 4 +++- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/drivers/media/mc/mc-entity.c b/drivers/media/mc/mc-entity.c index b8bcbc734eaf..35ef52f6da6f 100644 --- 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 85ed08ddee9d..47863e8fde7b 100644 --- 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. *