From patchwork Sun Oct 9 21:35:09 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 13002148 X-Patchwork-Delegate: kieran@bingham.xyz 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 50F17C433F5 for ; Sun, 9 Oct 2022 21:35:22 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230072AbiJIVfU (ORCPT ); Sun, 9 Oct 2022 17:35:20 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:52860 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229887AbiJIVfT (ORCPT ); Sun, 9 Oct 2022 17:35:19 -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 1B2101C915; Sun, 9 Oct 2022 14:35:18 -0700 (PDT) Received: from pendragon.ideasonboard.com (62-78-145-57.bb.dnainternet.fi [62.78.145.57]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 3520B9C4; Sun, 9 Oct 2022 23:35:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1665351315; bh=G039zjAux/RiMi/GUO2mIlJOW1hz3O4bVoFnIHRELoY=; h=From:To:Cc:Subject:Date:From; b=ta8zRipDyLUBh/MjWNX50cjYaBMx862MqfEkdd2FfiqIuKm2CZJKd62CfhM/v+wmL 4sj3FUZ1eU8/28vplMFFV37P/KBHvjGu/dZRdTNr2YpfQj9dhzwh7DhUKCdnGVPhQi 3LUDT31OmqjiOCSQ4+keFBwIP/YPt3KDsbvEpBkw= From: Laurent Pinchart To: linux-media@vger.kernel.org Cc: linux-renesas-soc@vger.kernel.org, Hans Verkuil , Sakari Ailus , Laurent Pinchart Subject: [RFC PATCH] media: Documentation: Drop deprecated bytesused == 0 Date: Mon, 10 Oct 2022 00:35:09 +0300 Message-Id: <20221009213509.860-1-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.35.1 MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-renesas-soc@vger.kernel.org From: Laurent Pinchart The V4L2 API historically allowed buffers to be queued with bytesused set to 0 on output devices, in which case the driver would use the buffer length. This behaviour is deprecated, and videobuf2 prints a warning message in the kernel log. Drop it from the documentation. Signed-off-by: Laurent Pinchart Reviewed-by: Hans Verkuil Reviewed-by: Sakari Ailus --- This patch aims at starting (or continuing) the discussion related to handling of bytesused == 0 on video output devices. videobuf2 currently printes a warning that indicates the behaviour is deprecated, but the API documentation allows it explicitly. This discrepency bothers me and I think we should fix it. We probably won't be able to drop support for the deprecated behaviour in the near future, if ever. If we want to push applications to get fixed, we may want to replace the dev_warn() with a WARN_ONCE(), which could be done in a v2 of this patch, or in another patch. Another option would be to consider that the behaviour is fine and keep official support for it in the documentation, in which case vb2 should stop warning about it. This wouldn't be my preference. --- Documentation/userspace-api/media/v4l/buffer.rst | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst index 4638ec64db00..04dec3e570ed 100644 --- a/Documentation/userspace-api/media/v4l/buffer.rst +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -187,10 +187,8 @@ struct v4l2_buffer on the negotiated data format and may change with each buffer for compressed variable size data like JPEG images. Drivers must set this field when ``type`` refers to a capture stream, applications - when it refers to an output stream. If the application sets this - to 0 for an output stream, then ``bytesused`` will be set to the - size of the buffer (see the ``length`` field of this struct) by - the driver. For multiplanar formats this field is ignored and the + when it refers to an output stream. For multiplanar formats this field + is ignored and the ``planes`` pointer is used instead. * - __u32 - ``flags`` @@ -327,10 +325,7 @@ struct v4l2_plane - ``bytesused`` - The number of bytes occupied by data in the plane (its payload). Drivers must set this field when ``type`` refers to a capture - stream, applications when it refers to an output stream. If the - application sets this to 0 for an output stream, then - ``bytesused`` will be set to the size of the plane (see the - ``length`` field of this struct) by the driver. + stream, applications when it refers to an output stream. .. note::