From patchwork Thu Mar 24 08:00:23 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tomi Valkeinen X-Patchwork-Id: 553968 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 19E7BC433F5 for ; Thu, 24 Mar 2022 08:01:34 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1348770AbiCXIDC (ORCPT ); Thu, 24 Mar 2022 04:03:02 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54268 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1348772AbiCXICv (ORCPT ); Thu, 24 Mar 2022 04:02:51 -0400 Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 3B5A399EE4 for ; Thu, 24 Mar 2022 01:01:20 -0700 (PDT) Received: from deskari.lan (91-156-85-209.elisa-laajakaista.fi [91.156.85.209]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id C029712E9; Thu, 24 Mar 2022 09:01:17 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1648108878; bh=+hylM7NeXm+nd2uuFuUmdfiUgbmAgKxJSXurPNZnfu4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ZN/ziLF/9zfbicAUrO0CgH0+0X7UQJSqQq+ZIKJkljoblQ+R7DznlrayFIGlxS5Wi ZIq+ZnYzuGgOCyscHibFa8oojtcnFDk7R+zKGQkW5MuSnrOm5WuBHrODmcU0s/9pl2 c86Gz5PfBTpoL+tn/EYgFY13dBjSWgK7PbrArVI8= From: Tomi Valkeinen To: linux-media@vger.kernel.org, sakari.ailus@linux.intel.com, Jacopo Mondi , Laurent Pinchart , niklas.soderlund+renesas@ragnatech.se, Mauro Carvalho Chehab , Hans Verkuil , Pratyush Yadav Cc: Tomi Valkeinen , Jacopo Mondi Subject: [PATCH v6 1/8] media: subdev: rename subdev-state alloc & free Date: Thu, 24 Mar 2022 10:00:23 +0200 Message-Id: <20220324080030.216716-2-tomi.valkeinen@ideasonboard.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20220324080030.216716-1-tomi.valkeinen@ideasonboard.com> References: <20220324080030.216716-1-tomi.valkeinen@ideasonboard.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org v4l2_subdev_alloc_state() and v4l2_subdev_free_state() are not supposed to be used by the drivers. However, we do have a few drivers that use those at the moment, so we need to expose these functions for the time being. Prefix the functions with __ to mark the functions as internal. At the same time, rename them to v4l2_subdev_state_alloc and v4l2_subdev_state_free to match the style used for other functions like video_device_alloc() and media_request_alloc(). Signed-off-by: Tomi Valkeinen Reviewed-by: Laurent Pinchart Reviewed-by: Hans Verkuil Reviewed-by: Jacopo Mondi --- .../media/platform/renesas/rcar-vin/rcar-v4l2.c | 8 ++++++-- drivers/media/platform/renesas/vsp1/vsp1_entity.c | 8 ++++++-- drivers/media/v4l2-core/v4l2-subdev.c | 12 ++++++------ drivers/staging/media/tegra-video/vi.c | 8 ++++++-- include/media/v4l2-subdev.h | 14 +++++++++----- 5 files changed, 33 insertions(+), 17 deletions(-) diff --git a/drivers/media/platform/renesas/rcar-vin/rcar-v4l2.c b/drivers/media/platform/renesas/rcar-vin/rcar-v4l2.c index 2e60b9fce03b..da88f968c31a 100644 --- a/drivers/media/platform/renesas/rcar-vin/rcar-v4l2.c +++ b/drivers/media/platform/renesas/rcar-vin/rcar-v4l2.c @@ -263,7 +263,11 @@ static int rvin_try_format(struct rvin_dev *vin, u32 which, u32 width, height; int ret; - sd_state = v4l2_subdev_alloc_state(sd); + /* + * FIXME: Drop this call, drivers are not supposed to use + * __v4l2_subdev_state_alloc(). + */ + sd_state = __v4l2_subdev_state_alloc(sd); if (IS_ERR(sd_state)) return PTR_ERR(sd_state); @@ -299,7 +303,7 @@ static int rvin_try_format(struct rvin_dev *vin, u32 which, rvin_format_align(vin, pix); done: - v4l2_subdev_free_state(sd_state); + __v4l2_subdev_state_free(sd_state); return ret; } diff --git a/drivers/media/platform/renesas/vsp1/vsp1_entity.c b/drivers/media/platform/renesas/vsp1/vsp1_entity.c index 823c15facd1b..c82b3fb7b89a 100644 --- a/drivers/media/platform/renesas/vsp1/vsp1_entity.c +++ b/drivers/media/platform/renesas/vsp1/vsp1_entity.c @@ -675,7 +675,11 @@ int vsp1_entity_init(struct vsp1_device *vsp1, struct vsp1_entity *entity, * Allocate the pad configuration to store formats and selection * rectangles. */ - entity->config = v4l2_subdev_alloc_state(&entity->subdev); + /* + * FIXME: Drop this call, drivers are not supposed to use + * __v4l2_subdev_state_alloc(). + */ + entity->config = __v4l2_subdev_state_alloc(&entity->subdev); if (IS_ERR(entity->config)) { media_entity_cleanup(&entity->subdev.entity); return PTR_ERR(entity->config); @@ -690,6 +694,6 @@ void vsp1_entity_destroy(struct vsp1_entity *entity) entity->ops->destroy(entity); if (entity->subdev.ctrl_handler) v4l2_ctrl_handler_free(entity->subdev.ctrl_handler); - v4l2_subdev_free_state(entity->config); + __v4l2_subdev_state_free(entity->config); media_entity_cleanup(&entity->subdev.entity); } diff --git a/drivers/media/v4l2-core/v4l2-subdev.c b/drivers/media/v4l2-core/v4l2-subdev.c index 30eb50407db5..376595954db0 100644 --- a/drivers/media/v4l2-core/v4l2-subdev.c +++ b/drivers/media/v4l2-core/v4l2-subdev.c @@ -28,7 +28,7 @@ static int subdev_fh_init(struct v4l2_subdev_fh *fh, struct v4l2_subdev *sd) { struct v4l2_subdev_state *state; - state = v4l2_subdev_alloc_state(sd); + state = __v4l2_subdev_state_alloc(sd); if (IS_ERR(state)) return PTR_ERR(state); @@ -39,7 +39,7 @@ static int subdev_fh_init(struct v4l2_subdev_fh *fh, struct v4l2_subdev *sd) static void subdev_fh_free(struct v4l2_subdev_fh *fh) { - v4l2_subdev_free_state(fh->state); + __v4l2_subdev_state_free(fh->state); fh->state = NULL; } @@ -862,7 +862,7 @@ int v4l2_subdev_link_validate(struct media_link *link) } EXPORT_SYMBOL_GPL(v4l2_subdev_link_validate); -struct v4l2_subdev_state *v4l2_subdev_alloc_state(struct v4l2_subdev *sd) +struct v4l2_subdev_state *__v4l2_subdev_state_alloc(struct v4l2_subdev *sd) { struct v4l2_subdev_state *state; int ret; @@ -895,9 +895,9 @@ struct v4l2_subdev_state *v4l2_subdev_alloc_state(struct v4l2_subdev *sd) return ERR_PTR(ret); } -EXPORT_SYMBOL_GPL(v4l2_subdev_alloc_state); +EXPORT_SYMBOL_GPL(__v4l2_subdev_state_alloc); -void v4l2_subdev_free_state(struct v4l2_subdev_state *state) +void __v4l2_subdev_state_free(struct v4l2_subdev_state *state) { if (!state) return; @@ -905,7 +905,7 @@ void v4l2_subdev_free_state(struct v4l2_subdev_state *state) kvfree(state->pads); kfree(state); } -EXPORT_SYMBOL_GPL(v4l2_subdev_free_state); +EXPORT_SYMBOL_GPL(__v4l2_subdev_state_free); #endif /* CONFIG_MEDIA_CONTROLLER */ diff --git a/drivers/staging/media/tegra-video/vi.c b/drivers/staging/media/tegra-video/vi.c index d1f43f465c22..07d368f345cd 100644 --- a/drivers/staging/media/tegra-video/vi.c +++ b/drivers/staging/media/tegra-video/vi.c @@ -507,7 +507,11 @@ static int __tegra_channel_try_format(struct tegra_vi_channel *chan, if (!subdev) return -ENODEV; - sd_state = v4l2_subdev_alloc_state(subdev); + /* + * FIXME: Drop this call, drivers are not supposed to use + * __v4l2_subdev_state_alloc(). + */ + sd_state = __v4l2_subdev_state_alloc(subdev); if (IS_ERR(sd_state)) return PTR_ERR(sd_state); /* @@ -558,7 +562,7 @@ static int __tegra_channel_try_format(struct tegra_vi_channel *chan, v4l2_fill_pix_format(pix, &fmt.format); tegra_channel_fmt_align(chan, pix, fmtinfo->bpp); - v4l2_subdev_free_state(sd_state); + __v4l2_subdev_state_free(sd_state); return 0; } diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h index 6c153b33bb04..5d6f56648ad6 100644 --- a/include/media/v4l2-subdev.h +++ b/include/media/v4l2-subdev.h @@ -1122,20 +1122,24 @@ int v4l2_subdev_link_validate_default(struct v4l2_subdev *sd, int v4l2_subdev_link_validate(struct media_link *link); /** - * v4l2_subdev_alloc_state - allocate v4l2_subdev_state + * __v4l2_subdev_state_alloc - allocate v4l2_subdev_state * * @sd: pointer to &struct v4l2_subdev for which the state is being allocated. * - * Must call v4l2_subdev_free_state() when state is no longer needed. + * Must call __v4l2_subdev_state_free() when state is no longer needed. + * + * Not to be called directly by the drivers. */ -struct v4l2_subdev_state *v4l2_subdev_alloc_state(struct v4l2_subdev *sd); +struct v4l2_subdev_state *__v4l2_subdev_state_alloc(struct v4l2_subdev *sd); /** - * v4l2_subdev_free_state - free a v4l2_subdev_state + * __v4l2_subdev_state_free - free a v4l2_subdev_state * * @state: v4l2_subdev_state to be freed. + * + * Not to be called directly by the drivers. */ -void v4l2_subdev_free_state(struct v4l2_subdev_state *state); +void __v4l2_subdev_state_free(struct v4l2_subdev_state *state); #endif /* CONFIG_MEDIA_CONTROLLER */ From patchwork Thu Mar 24 08:00:25 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tomi Valkeinen X-Patchwork-Id: 553969 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id CC4ADC433F5 for ; Thu, 24 Mar 2022 08:01:30 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1348766AbiCXIDA (ORCPT ); Thu, 24 Mar 2022 04:03:00 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54288 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1348780AbiCXICx (ORCPT ); Thu, 24 Mar 2022 04:02:53 -0400 Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 651C799ED5 for ; Thu, 24 Mar 2022 01:01:22 -0700 (PDT) Received: from deskari.lan (91-156-85-209.elisa-laajakaista.fi [91.156.85.209]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 5D87714CD; Thu, 24 Mar 2022 09:01:19 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1648108879; bh=rsVji2hD+87e+gDSymMZyQMGnzaMwO7BqmYRfTVlu5I=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=g8xlOJ9Ga8NHejdWZOOQdKoWw9wUm45zuGjmqyxnRtrQ9fSUMJ29ij8FZRT42waod n/CxJIcc/YX5PzywfPIkzxTzzggwKcjgLgkzYzcNf3fCal2qqTvhYZ0VEeR0940Izx zKrN+j4pxb1RUC6R4DbxbN7SZsAOFIOmjRFzHYTw= From: Tomi Valkeinen To: linux-media@vger.kernel.org, sakari.ailus@linux.intel.com, Jacopo Mondi , Laurent Pinchart , niklas.soderlund+renesas@ragnatech.se, Mauro Carvalho Chehab , Hans Verkuil , Pratyush Yadav Cc: Tomi Valkeinen Subject: [PATCH v6 3/8] media: subdev: add v4l2_subdev_get_pad_* helpers Date: Thu, 24 Mar 2022 10:00:25 +0200 Message-Id: <20220324080030.216716-4-tomi.valkeinen@ideasonboard.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20220324080030.216716-1-tomi.valkeinen@ideasonboard.com> References: <20220324080030.216716-1-tomi.valkeinen@ideasonboard.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org The subdev state is now used for both try and active cases. We should rename v4l2_subdev_get_try_* helpers to v4l2_subdev_get_pad_*, but due to the size of that change lets add temporary wrapper helpers which can be used in drivers that support active state. Signed-off-by: Tomi Valkeinen --- include/media/v4l2-subdev.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h index 1bbe4383966c..b9587a265b32 100644 --- a/include/media/v4l2-subdev.h +++ b/include/media/v4l2-subdev.h @@ -1042,6 +1042,16 @@ v4l2_subdev_get_try_compose(struct v4l2_subdev *sd, return &state->pads[pad].try_compose; } +/* Temprary helpers until v4l2_subdev_get_try_* functions have been renamed */ +#define v4l2_subdev_get_pad_format(sd, state, pad) \ + v4l2_subdev_get_try_format(sd, state, pad) + +#define v4l2_subdev_get_pad_crop(sd, state, pad) \ + v4l2_subdev_get_try_crop(sd, state, pad) + +#define v4l2_subdev_get_pad_compose(sd, state, pad) \ + v4l2_subdev_get_try_compose(sd, state, pad) + #endif extern const struct v4l2_file_operations v4l2_subdev_fops; From patchwork Thu Mar 24 08:00:28 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tomi Valkeinen X-Patchwork-Id: 553967 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id DA74DC433EF for ; Thu, 24 Mar 2022 08:01:35 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1348774AbiCXIDF (ORCPT ); Thu, 24 Mar 2022 04:03:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54332 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S242442AbiCXIC6 (ORCPT ); Thu, 24 Mar 2022 04:02:58 -0400 Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 0FF4191AE1 for ; Thu, 24 Mar 2022 01:01:27 -0700 (PDT) Received: from deskari.lan (91-156-85-209.elisa-laajakaista.fi [91.156.85.209]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id B56851852; Thu, 24 Mar 2022 09:01:21 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1648108882; bh=rJlSjP4XRW7QLe5g9DHeDeBOxrTpEEzB/H/TfPrkRMs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gQD/qtuqcI36E5AVMM1bjWtRS2iuuqy2lm37qwltG3hgliqM+dCq3Cr2U0qtmZEqm zhSpT9DVAFwIyxwqOOFqo/7ftltbG8nSCDwLvOvQzPmwb5woseNTDBauEARZgSOGBB QXS+bN8M89U6cP0K5DfhuAC2+zP9CESr7ObS7tTg= From: Tomi Valkeinen To: linux-media@vger.kernel.org, sakari.ailus@linux.intel.com, Jacopo Mondi , Laurent Pinchart , niklas.soderlund+renesas@ragnatech.se, Mauro Carvalho Chehab , Hans Verkuil , Pratyush Yadav Cc: Tomi Valkeinen Subject: [PATCH v6 6/8] media: subdev: add locking wrappers to subdev op wrappers Date: Thu, 24 Mar 2022 10:00:28 +0200 Message-Id: <20220324080030.216716-7-tomi.valkeinen@ideasonboard.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20220324080030.216716-1-tomi.valkeinen@ideasonboard.com> References: <20220324080030.216716-1-tomi.valkeinen@ideasonboard.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org It is common that media drivers call subdev ops in source subdevs, and pass NULL as the state. This was the way to indicate that the callee should use the callee's private active state. E.g.: v4l2_subdev_call(priv->source_sd, pad, get_fmt, NULL, &sd_fmt); Now that we have a real subdev active state in the v4l2_subdev struct, we want the caller to pass a proper state (when available). And furthermore, the state should be locked. This would mean changing all the callers, which is the long term goal. To fix this issue in the short term, let's add an extra wrapper layer to all v4l2_subdev_call_pad_wrappers which deal with states. These wrappers handle the state == NULL case by using the locked active state instead (when available). Signed-off-by: Tomi Valkeinen Reviewed-by: Hans Verkuil --- drivers/media/v4l2-core/v4l2-subdev.c | 42 ++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 7 deletions(-) diff --git a/drivers/media/v4l2-core/v4l2-subdev.c b/drivers/media/v4l2-core/v4l2-subdev.c index 824424f0a741..d8d1c9ef4dc4 100644 --- a/drivers/media/v4l2-core/v4l2-subdev.c +++ b/drivers/media/v4l2-core/v4l2-subdev.c @@ -319,14 +319,42 @@ static int call_get_mbus_config(struct v4l2_subdev *sd, unsigned int pad, sd->ops->pad->get_mbus_config(sd, pad, config); } +/* + * Create state-management wrapper for pad ops dealing with subdev state. The + * wrapper handles the case where the caller does not provide the called + * subdev's state. This should be removed when all the callers are fixed. + */ +#define DEFINE_STATE_WRAPPER(f, arg_type) \ + static int call_##f##_state(struct v4l2_subdev *sd, \ + struct v4l2_subdev_state *_state, \ + arg_type *format) \ + { \ + struct v4l2_subdev_state *state = _state; \ + int ret; \ + if (!_state) \ + state = v4l2_subdev_lock_and_get_active_state(sd); \ + ret = call_##f(sd, state, format); \ + if (!_state && state) \ + v4l2_subdev_unlock_state(state); \ + return ret; \ + } + +DEFINE_STATE_WRAPPER(get_fmt, struct v4l2_subdev_format); +DEFINE_STATE_WRAPPER(set_fmt, struct v4l2_subdev_format); +DEFINE_STATE_WRAPPER(enum_mbus_code, struct v4l2_subdev_mbus_code_enum); +DEFINE_STATE_WRAPPER(enum_frame_size, struct v4l2_subdev_frame_size_enum); +DEFINE_STATE_WRAPPER(enum_frame_interval, struct v4l2_subdev_frame_interval_enum); +DEFINE_STATE_WRAPPER(get_selection, struct v4l2_subdev_selection); +DEFINE_STATE_WRAPPER(set_selection, struct v4l2_subdev_selection); + static const struct v4l2_subdev_pad_ops v4l2_subdev_call_pad_wrappers = { - .get_fmt = call_get_fmt, - .set_fmt = call_set_fmt, - .enum_mbus_code = call_enum_mbus_code, - .enum_frame_size = call_enum_frame_size, - .enum_frame_interval = call_enum_frame_interval, - .get_selection = call_get_selection, - .set_selection = call_set_selection, + .get_fmt = call_get_fmt_state, + .set_fmt = call_set_fmt_state, + .enum_mbus_code = call_enum_mbus_code_state, + .enum_frame_size = call_enum_frame_size_state, + .enum_frame_interval = call_enum_frame_interval_state, + .get_selection = call_get_selection_state, + .set_selection = call_set_selection_state, .get_edid = call_get_edid, .set_edid = call_set_edid, .dv_timings_cap = call_dv_timings_cap, From patchwork Thu Mar 24 08:00:30 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tomi Valkeinen X-Patchwork-Id: 553966 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id B568FC4332F for ; Thu, 24 Mar 2022 08:01:36 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1348776AbiCXIDG (ORCPT ); Thu, 24 Mar 2022 04:03:06 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54352 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1348765AbiCXIDA (ORCPT ); Thu, 24 Mar 2022 04:03:00 -0400 Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 06E1B91AE1 for ; Thu, 24 Mar 2022 01:01:29 -0700 (PDT) Received: from deskari.lan (91-156-85-209.elisa-laajakaista.fi [91.156.85.209]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 4EC6FFEF; Thu, 24 Mar 2022 09:01:23 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1648108883; bh=IYPnR8Ge+MaF3C77/TcHMv1Px3XrYK0N0px0pN+CAN0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=E7o2B/Yjr+xtNoZiJY4wMqnxOMomc6AMpFtgy6tmkTwsxIe/qIUhi2okqKDazE2jF mYFZydJ/DF+v8Vtam40FmG7owhpl2qp5ljP5VzA8EMLYCfKG5QRQ4p1/CEOuGxLSxy dx6iXXG7H7pRYLtFacUBfgiG8Ev0EMYQSzozxFZA= From: Tomi Valkeinen To: linux-media@vger.kernel.org, sakari.ailus@linux.intel.com, Jacopo Mondi , Laurent Pinchart , niklas.soderlund+renesas@ragnatech.se, Mauro Carvalho Chehab , Hans Verkuil , Pratyush Yadav Cc: Tomi Valkeinen Subject: [PATCH v6 8/8] media: Documentation: add documentation about subdev state Date: Thu, 24 Mar 2022 10:00:30 +0200 Message-Id: <20220324080030.216716-9-tomi.valkeinen@ideasonboard.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20220324080030.216716-1-tomi.valkeinen@ideasonboard.com> References: <20220324080030.216716-1-tomi.valkeinen@ideasonboard.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org Add documentation about centrally managed subdev state. Signed-off-by: Tomi Valkeinen Reviewed-by: Jacopo Mondi Reviewed-by: Hans Verkuil Reviewed-by: Laurent Pinchart --- .../driver-api/media/v4l2-subdev.rst | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index 08ea2673b19e..7fa950b1bff0 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -518,6 +518,81 @@ 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 +` receive the correct state to operate on through +the 'state' parameter. The state must be locked and unlocked by the +caller by calling :c:func:`v4l2_subdev_lock_state()` and +:c:func:`v4l2_subdev_unlock_state()`. The caller can do so by calling the subdev +operation through the :c:func:`v4l2_subdev_call_state_active()` macro. + +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_and_get_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. + +The whole subdev state is in reality split into three parts: the +v4l2_subdev_state, subdev controls and subdev driver's internal state. In the +future these parts should be combined into a single state. For the time being +we need a way to handle the locking for these parts. This can be accomplished +by sharing a lock. The v4l2_ctrl_handler already supports this via its 'lock' +pointer and the same model is used with states. The driver can do the following +before calling v4l2_subdev_init_finalize(): + +.. code-block:: c + + sd->ctrl_handler->lock = &priv->mutex; + sd->state_lock = &priv->mutex; + +This shares the driver's private mutex between the controls and the states. + V4L2 sub-device functions and data structures ---------------------------------------------