From patchwork Mon Dec 18 19:54:01 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 10121793 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 455C260390 for ; Mon, 18 Dec 2017 19:54:17 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 33DC128DAD for ; Mon, 18 Dec 2017 19:54:17 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 28B5E28DD9; Mon, 18 Dec 2017 19:54:17 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id AF35028DAD for ; Mon, 18 Dec 2017 19:54:16 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758924AbdLRTyP (ORCPT ); Mon, 18 Dec 2017 14:54:15 -0500 Received: from osg.samsung.com ([64.30.133.232]:35389 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1758821AbdLRTyM (ORCPT ); Mon, 18 Dec 2017 14:54:12 -0500 Received: from localhost (localhost [127.0.0.1]) by osg.samsung.com (Postfix) with ESMTP id 3316E33D9F; Mon, 18 Dec 2017 11:54:12 -0800 (PST) X-Virus-Scanned: Debian amavisd-new at dev.s-opensource.com X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" Received: from osg.samsung.com ([127.0.0.1]) by localhost (localhost [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id PrQfdQBRW52Z; Mon, 18 Dec 2017 11:54:07 -0800 (PST) Received: from smtp.s-opensource.com (201.86.134.76.dynamic.adsl.gvt.net.br [201.86.134.76]) by osg.samsung.com (Postfix) with ESMTPSA id 11E1033D54; Mon, 18 Dec 2017 11:54:06 -0800 (PST) Received: from mchehab by smtp.s-opensource.com with local (Exim 4.89) (envelope-from ) id 1eR1UB-0002c0-P7; Mon, 18 Dec 2017 17:54:03 -0200 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab Subject: [PATCH 7/8] media: v4l2-subdev: document remaining undocumented functions Date: Mon, 18 Dec 2017 17:54:01 -0200 Message-Id: X-Mailer: git-send-email 2.14.3 In-Reply-To: References: In-Reply-To: References: Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP There are several undocumented v4l2-subdev functions that are part of kAPI. Document them. Acked-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- include/media/v4l2-subdev.h | 69 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 64 insertions(+), 5 deletions(-) diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h index 1c280cf7dd41..2562e8854022 100644 --- a/include/media/v4l2-subdev.h +++ b/include/media/v4l2-subdev.h @@ -867,6 +867,13 @@ struct v4l2_subdev { struct v4l2_subdev_platform_data *pdata; }; + +/** + * media_entity_to_v4l2_subdev - Returns a &struct v4l2_subdev from + * the &struct media_entity embedded in it. + * + * @ent: pointer to &struct media_entity. + */ #define media_entity_to_v4l2_subdev(ent) \ ({ \ typeof(ent) __me_sd_ent = (ent); \ @@ -876,14 +883,20 @@ struct v4l2_subdev { NULL; \ }) +/** + * vdev_to_v4l2_subdev - Returns a &struct v4l2_subdev from + * the &struct video_device embedded on it. + * + * @vdev: pointer to &struct video_device + */ #define vdev_to_v4l2_subdev(vdev) \ ((struct v4l2_subdev *)video_get_drvdata(vdev)) /** * struct v4l2_subdev_fh - Used for storing subdev information per file handle * - * @vfh: pointer to struct v4l2_fh - * @pad: pointer to v4l2_subdev_pad_config + * @vfh: pointer to &struct v4l2_fh + * @pad: pointer to &struct v4l2_subdev_pad_config */ struct v4l2_subdev_fh { struct v4l2_fh vfh; @@ -892,10 +905,25 @@ struct v4l2_subdev_fh { #endif }; +/** + * to_v4l2_subdev_fh - Returns a &struct v4l2_subdev_fh from + * the &struct v4l2_fh embedded on it. + * + * @fh: pointer to &struct v4l2_fh + */ #define to_v4l2_subdev_fh(fh) \ container_of(fh, struct v4l2_subdev_fh, vfh) #if defined(CONFIG_VIDEO_V4L2_SUBDEV_API) + +/** + * v4l2_subdev_get_try_format - ancillary routine to call + * &struct v4l2_subdev_pad_config->try_fmt + * + * @sd: pointer to &struct v4l2_subdev + * @cfg: pointer to &struct v4l2_subdev_pad_config array. + * @pad: index of the pad in the @cfg array. + */ static inline struct v4l2_mbus_framefmt *v4l2_subdev_get_try_format(struct v4l2_subdev *sd, struct v4l2_subdev_pad_config *cfg, @@ -906,6 +934,14 @@ static inline struct v4l2_mbus_framefmt return &cfg[pad].try_fmt; } +/** + * v4l2_subdev_get_try_crop - ancillary routine to call + * &struct v4l2_subdev_pad_config->try_crop + * + * @sd: pointer to &struct v4l2_subdev + * @cfg: pointer to &struct v4l2_subdev_pad_config array. + * @pad: index of the pad in the @cfg array. + */ static inline struct v4l2_rect *v4l2_subdev_get_try_crop(struct v4l2_subdev *sd, struct v4l2_subdev_pad_config *cfg, @@ -916,6 +952,14 @@ static inline struct v4l2_rect return &cfg[pad].try_crop; } +/** + * v4l2_subdev_get_try_crop - ancillary routine to call + * &struct v4l2_subdev_pad_config->try_compose + * + * @sd: pointer to &struct v4l2_subdev + * @cfg: pointer to &struct v4l2_subdev_pad_config array. + * @pad: index of the pad in the @cfg array. + */ static inline struct v4l2_rect *v4l2_subdev_get_try_compose(struct v4l2_subdev *sd, struct v4l2_subdev_pad_config *cfg, @@ -1032,9 +1076,16 @@ void v4l2_subdev_free_pad_config(struct v4l2_subdev_pad_config *cfg); void v4l2_subdev_init(struct v4l2_subdev *sd, const struct v4l2_subdev_ops *ops); -/* - * Call an ops of a v4l2_subdev, doing the right checks against - * NULL pointers. +/** + * v4l2_subdev_call - call an operation of a v4l2_subdev. + * + * @sd: pointer to the &struct v4l2_subdev + * @o: name of the element at &struct v4l2_subdev_ops that contains @f. + * Each element there groups a set of callbacks functions. + * @f: callback function that will be called if @cond matches. + * The callback functions are defined in groups, according to + * each element at &struct v4l2_subdev_ops. + * @args...: arguments for @f. * * Example: err = v4l2_subdev_call(sd, video, s_std, norm); */ @@ -1050,6 +1101,14 @@ void v4l2_subdev_init(struct v4l2_subdev *sd, __result; \ }) +/** + * v4l2_subdev_has_op - Checks if a subdev defines a certain operation. + * + * @sd: pointer to the &struct v4l2_subdev + * @o: The group of callback functions in &struct v4l2_subdev_ops + * which @f is a part of. + * @f: callback function to be checked for its existence. + */ #define v4l2_subdev_has_op(sd, o, f) \ ((sd)->ops->o && (sd)->ops->o->f)