From patchwork Mon Jan 20 12:46:14 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hans Verkuil X-Patchwork-Id: 3512441 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 3EC39C02DC for ; Mon, 20 Jan 2014 12:47:11 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 2DFCE20108 for ; Mon, 20 Jan 2014 12:47:10 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 0AEA2200F2 for ; Mon, 20 Jan 2014 12:47:09 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753515AbaATMrG (ORCPT ); Mon, 20 Jan 2014 07:47:06 -0500 Received: from smtp-vbr9.xs4all.nl ([194.109.24.29]:2196 "EHLO smtp-vbr9.xs4all.nl" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753304AbaATMqw (ORCPT ); Mon, 20 Jan 2014 07:46:52 -0500 Received: from tschai.lan (173-38-208-169.cisco.com [173.38.208.169]) (authenticated bits=0) by smtp-vbr9.xs4all.nl (8.13.8/8.13.8) with ESMTP id s0KCkfDh023268; Mon, 20 Jan 2014 13:46:43 +0100 (CET) (envelope-from hverkuil@xs4all.nl) Received: from tschai.cisco.com (localhost [127.0.0.1]) by tschai.lan (Postfix) with ESMTPSA id 1448B2A00B6; Mon, 20 Jan 2014 13:46:17 +0100 (CET) From: Hans Verkuil To: linux-media@vger.kernel.org Cc: m.chehab@samsung.com, laurent.pinchart@ideasonboard.com, t.stanislaws@samsung.com, Hans Verkuil Subject: [RFCv2 PATCH 21/21] v4l2-controls.txt: update to the new way of accessing controls. Date: Mon, 20 Jan 2014 13:46:14 +0100 Message-Id: <1390221974-28194-22-git-send-email-hverkuil@xs4all.nl> X-Mailer: git-send-email 1.8.5.2 In-Reply-To: <1390221974-28194-1-git-send-email-hverkuil@xs4all.nl> References: <1390221974-28194-1-git-send-email-hverkuil@xs4all.nl> X-Virus-Scanned: by XS4ALL Virus Scanner Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Spam-Status: No, score=-7.5 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Hans Verkuil The way current and new values are accessed has changed. Update the document to bring it up to date with the code. Signed-off-by: Hans Verkuil Reviewed-by: Sylwester Nawrocki --- Documentation/video4linux/v4l2-controls.txt | 46 +++++++++++++++++++---------- 1 file changed, 31 insertions(+), 15 deletions(-) diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt index 1c353c2..f94dcfd 100644 --- a/Documentation/video4linux/v4l2-controls.txt +++ b/Documentation/video4linux/v4l2-controls.txt @@ -77,9 +77,9 @@ Basic usage for V4L2 and sub-device drivers Where foo->v4l2_dev is of type struct v4l2_device. - Finally, remove all control functions from your v4l2_ioctl_ops: - vidioc_queryctrl, vidioc_querymenu, vidioc_g_ctrl, vidioc_s_ctrl, - vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls. + Finally, remove all control functions from your v4l2_ioctl_ops (if any): + vidioc_queryctrl, vidioc_query_ext_ctrl, vidioc_querymenu, vidioc_g_ctrl, + vidioc_s_ctrl, vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls. Those are now no longer needed. 1.3.2) For sub-device drivers do this: @@ -258,8 +258,8 @@ The new control value has already been validated, so all you need to do is to actually update the hardware registers. You're done! And this is sufficient for most of the drivers we have. No need -to do any validation of control values, or implement QUERYCTRL/QUERYMENU. And -G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported. +to do any validation of control values, or implement QUERYCTRL, QUERY_EXT_CTRL +and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported. ============================================================================== @@ -288,24 +288,40 @@ of v4l2_device. Accessing Control Values ======================== -The v4l2_ctrl struct contains these two unions: +The following union is used inside the control framework to access control +values: - /* The current control value. */ - union { - s32 val; - s64 val64; - char *string; - } cur; +union v4l2_ctrl_ptr { + s32 *p_s32; + s64 *p_s64; + char *p_char; + void *p; +}; + +The v4l2_ctrl struct contains these fields that can be used to access both +current and new values: - /* The new control value. */ union { s32 val; s64 val64; - char *string; }; + union v4l2_ctrl_ptr new; + union v4l2_ctrl_ptr cur; + +If the control has a simple s32 type or s64 type, then: + + &ctrl->val == ctrl->new.p_s32 + +or: + + &ctrl->val64 == ctrl->new.p_s64 + +For all other types use ctrl->new.p instead of ctrl->val/val64. +Basically the val and val64 fields can be considered aliases since these +are used so often. Within the control ops you can freely use these. The val and val64 speak for -themselves. The string pointers point to character buffers of length +themselves. The p_char pointers point to character buffers of length ctrl->maximum + 1, and are always 0-terminated. In most cases 'cur' contains the current cached control value. When you create