From mboxrd@z Thu Jan 1 00:00:00 1970 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 8F699C05027 for ; Fri, 17 Feb 2023 11:44:33 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229522AbjBQLob (ORCPT ); Fri, 17 Feb 2023 06:44:31 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:55994 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229507AbjBQLob (ORCPT ); Fri, 17 Feb 2023 06:44:31 -0500 Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5238B5BD86; Fri, 17 Feb 2023 03:44:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1676634270; x=1708170270; h=date:from:to:cc:subject:message-id:references: mime-version:in-reply-to; bh=LsporBvbvkhAN2zntnBXKCyzIPBXsJmRP2z5y0oC/HA=; b=N65OH9Gat4iDQ7HfdnljQo1PXQuTxRsS4hngdKauUUlF958XXUY8tjnU gYYKtXLsK73SjCehfaiHTO10S11fWvNw4QD850l0TkzyZkj58ovtrIHEX OEFf5j6L9RClEsJFyC/4BypPzCvSE8jtPlPnBltMeVZv3w4Wb4mYd0sQD iE7Bvy90Ij5LcXvB4f/qK/xKVl+mvpm/eK13HL6yxw8hNOvCBVYUEhx9N mFi1j0D8ZOCdkQE4le3RBAMW7ShQjHxMhMIKNxDVyjEBTmmh6CmOePPaa tGmy87Z9PPZaS7CoY0L3tY5ehLC7T2SnIZtwqw4o79jXCjaeyiGG3K06f g==; X-IronPort-AV: E=McAfee;i="6500,9779,10623"; a="331971396" X-IronPort-AV: E=Sophos;i="5.97,304,1669104000"; d="scan'208";a="331971396" Received: from orsmga005.jf.intel.com ([10.7.209.41]) by fmsmga103.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 17 Feb 2023 03:44:30 -0800 X-IronPort-AV: E=McAfee;i="6500,9779,10623"; a="844546742" X-IronPort-AV: E=Sophos;i="5.97,304,1669104000"; d="scan'208";a="844546742" Received: from turnipsi.fi.intel.com (HELO kekkonen.fi.intel.com) ([10.237.72.44]) by orsmga005-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 17 Feb 2023 03:44:27 -0800 Received: from kekkonen.localdomain (localhost [IPv6:::1]) by kekkonen.fi.intel.com (Postfix) with SMTP id 44FB911FC11; Fri, 17 Feb 2023 13:44:25 +0200 (EET) Date: Fri, 17 Feb 2023 13:44:25 +0200 From: Sakari Ailus To: Andy Shevchenko Cc: linux-acpi@vger.kernel.org, linux-kernel@vger.kernel.org, Daniel Scally , Heikki Krogerus , Greg Kroah-Hartman , "Rafael J. Wysocki" , Daniel Kaehn Subject: Re: [PATCH v1 1/1] device property: Clarify description on returned value in some functions Message-ID: References: <20230216205708.13453-1-andriy.shevchenko@linux.intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: Precedence: bulk List-ID: X-Mailing-List: linux-acpi@vger.kernel.org On Fri, Feb 17, 2023 at 01:28:55PM +0200, Andy Shevchenko wrote: > On Fri, Feb 17, 2023 at 01:18:31PM +0200, Sakari Ailus wrote: > > On Fri, Feb 17, 2023 at 01:01:39PM +0200, Andy Shevchenko wrote: > > > On Fri, Feb 17, 2023 at 12:27:53PM +0200, Sakari Ailus wrote: > > > > On Thu, Feb 16, 2023 at 10:57:08PM +0200, Andy Shevchenko wrote: > > ... > > > > > > * fwnode_get_next_child_node - Return the next child node handle for a node > > > > > * @fwnode: Firmware node to find the next child node for. > > > > > * @child: Handle to one of the node's child nodes or a %NULL handle. > > > > > + * > > > > > + * Caller is responsible to call fwnode_handle_put() on the returned fwnode > > > > > + * pointer. > > > > > > > > The loop itself will also put the child node, so this is only relevant > > > > outside the loop. > > > > > > Yes and this is exactly what people stumbled over. Hence this note. > > > This call per se doesn't loop, so I didn't get how your comment can > > > be transformed to anything here. Care to elaborate a bit more on > > > what I have to add here or reword? > > > > Ah, indeed. This is achieved by putting the previous child. Generally this > > function is used via the loop helper macro and not called directly, hence > > the documentation there matters the most. Those functions appear to be > > without any documentation though. > > So, what should I do? Good question. How about this text: The caller is responsible for calling fwnode_handle_put() put on the returned fwnode. Note that this function also puts a reference to @child unconditionally. This is actually done by the firmware specific implementation, namely on OF and at least should be done on swnode. A second patch to document the fwnode iterator macros would be nice. -- Sakari Ailus