From patchwork Fri Jan 12 18:59:03 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: SeongJae Park X-Patchwork-Id: 187818 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:693c:2614:b0:101:6a76:bbe3 with SMTP id mm20csp378430dyc; Fri, 12 Jan 2024 10:59:21 -0800 (PST) X-Google-Smtp-Source: AGHT+IEBWsnkMGkIZFHkaTdf0ERsjKLU1ZFN2KRFSvx5oMCQE/9V2gUI+ghuBtKPmJpiESfou/aw X-Received: by 2002:a92:d943:0:b0:360:60e1:f94c with SMTP id l3-20020a92d943000000b0036060e1f94cmr1577808ilq.33.1705085961429; Fri, 12 Jan 2024 10:59:21 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1705085961; cv=none; d=google.com; s=arc-20160816; b=jSStjHpfkAWUVGCk+bD1iXFFTh5Q63PMMJX2D+ouCl2i/gwwZi68eoPwFRv+GMSOk9 JCSDhNTn/XtXJgG9Z2DJY+Xr8LyC31WLGybDd7IGHv+w4uqffp/f7/1GqFwIOjvsV9bb BUNVChAR+e83iPw2ei6rGfUxluV5bVsbyASOWc6SfHdbmbFxritxCv6HqIr4tc7jG7zb iBMLxdQvQ0UTrDReI6LQkmN7CYG6wJcQYxKQFIu6gWFsykPGGBzYYDf9zFBtkexQKZkx ri6qlpJWlilyAo30ob7L9DTdFZ+3G9F5cQJSu+LJWT9jr1M6S6LC7iJ+fH+c1DSqYqZH 9Yhg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:message-id:date:subject:cc:to :from:dkim-signature; bh=Gj3LENuA4mdz1E+PWsgemdUY0ZpKFhTln1U3B4aadfE=; fh=6ETOqft+SoAA//SyZIrLdq6Af5ehFF7Mehqxbg72JJ4=; b=0xyBUtLIHBcBB7ALEjzmXC/8CA2Xm8X2C1amgofsw+sA/70iT6hSmtFWkYQVIwemqK Qb4vGFz5cn6Fu+fyH+k/YMHwbIUgdQ8a9I6YVRUDFxze2x9FmWxWxsvdRao3Zv2M+aFi PkCR9VHw2NrFEg0bxJrHRfYsARYZu7agL17s4zsrndxUsFLut/VtZgJQidLT+xirG5Rh KN8XGIdecKwljtNSY2J+IDDwA7re2H7pyC9xdz16w3sZOl0Pwcof92vpT0VWLAEYAPRd n0qf5Z91WaE9uB8LzLF9APIMKhJljg8sLg9uDlzVSolCTO8p5kvSEGUCZ8iB0XeY2xSc kKFg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@kernel.org header.s=k20201202 header.b=DtIkcx34; spf=pass (google.com: domain of linux-kernel+bounces-24988-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) smtp.mailfrom="linux-kernel+bounces-24988-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: from sv.mirrors.kernel.org (sv.mirrors.kernel.org. [139.178.88.99]) by mx.google.com with ESMTPS id 137-20020a63018f000000b005cdf4899a56si3779923pgb.658.2024.01.12.10.59.21 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 12 Jan 2024 10:59:21 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-24988-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99; Authentication-Results: mx.google.com; dkim=pass header.i=@kernel.org header.s=k20201202 header.b=DtIkcx34; spf=pass (google.com: domain of linux-kernel+bounces-24988-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) smtp.mailfrom="linux-kernel+bounces-24988-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sv.mirrors.kernel.org (Postfix) with ESMTPS id 27D9A285C85 for ; Fri, 12 Jan 2024 18:59:21 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 8B3F415AFD; Fri, 12 Jan 2024 18:59:10 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="DtIkcx34" Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id ED30A15AC6 for ; Fri, 12 Jan 2024 18:59:07 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id EE036C433C7; Fri, 12 Jan 2024 18:59:06 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1705085947; bh=3ibygWlbfSkC0FBcuBrq55XAKl25vUGqLzjDUTlhUwQ=; h=From:To:Cc:Subject:Date:From; b=DtIkcx34By6VgPFf8lo2BTDnvhF6QQjOelSvfydld6vmUqrdazzSRqg0pIDwXN7Uo H8k77MepDSjADQ6+o12Va2qKoR+Fsi8FA5TvLceCZkPHyFnaAwsJyVWehm55sXWPFX /TLYirvpcvcqUi3V+O5qKWVGDcvTapvRDVSR1i57cvnKpe4bBwcA7NxRdKiJMmZ4GO RTPCI1ib6ToxxEbz/dXoFDl5C6ubioYCFqJbiJIadjvVzrhIjUHXMbqWTHdQKwl22e 7i5J4q2Xd7VXIEh5ATPJB2CytgzqBuZkuM4lcytWnCg1wLF7odfhbmT+TfK2AFDoE+ 86QwFMkrXh1hQ== From: SeongJae Park To: jgross@suse.com Cc: sstabellini@kernel.org, oleksandr_tyshchenko@epam.com, xen-devel@lists.xenproject.org, linux-kernel@vger.kernel.org, SeongJae Park , kernel test robot Subject: [PATCH] xen/xenbus: document will_handle argument for xenbus_watch_path() Date: Fri, 12 Jan 2024 10:59:03 -0800 Message-Id: <20240112185903.83737-1-sj@kernel.org> X-Mailer: git-send-email 2.39.2 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1787912216943697019 X-GMAIL-MSGID: 1787912216943697019 Commit 2e85d32b1c86 ("xen/xenbus: Add 'will_handle' callback support in xenbus_watch_path()") added will_handle argument to xenbus_watch_path() and its wrapper, xenbus_watch_pathfmt(), but didn't document it on the kerneldoc comments of the function. This is causing warnings that reported by kernel test robot. Add the documentation to fix it. Fixes: 2e85d32b1c86 ("xen/xenbus: Add 'will_handle' callback support in xenbus_watch_path()") Reported-by: kernel test robot Closes: https://lore.kernel.org/oe-kbuild-all/202401121154.FI8jDGun-lkp@intel.com/ Signed-off-by: SeongJae Park Reviewed-by: Juergen Gross --- drivers/xen/xenbus/xenbus_client.c | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/drivers/xen/xenbus/xenbus_client.c b/drivers/xen/xenbus/xenbus_client.c index d4b251925796..d539210b39d8 100644 --- a/drivers/xen/xenbus/xenbus_client.c +++ b/drivers/xen/xenbus/xenbus_client.c @@ -116,14 +116,16 @@ EXPORT_SYMBOL_GPL(xenbus_strstate); * @dev: xenbus device * @path: path to watch * @watch: watch to register + * @will_handle: events queuing determine callback * @callback: callback to register * * Register a @watch on the given path, using the given xenbus_watch structure - * for storage, and the given @callback function as the callback. Return 0 on - * success, or -errno on error. On success, the given @path will be saved as - * @watch->node, and remains the caller's to free. On error, @watch->node will - * be NULL, the device will switch to %XenbusStateClosing, and the error will - * be saved in the store. + * for storage, @will_handle function as the callback to determine if each + * event need to be queued, and the given @callback function as the callback. + * Return 0 on success, or -errno on error. On success, the given @path will + * be saved as @watch->node, and remains the caller's to free. On error, + * @watch->node will be NULL, the device will switch to %XenbusStateClosing, + * and the error will be saved in the store. */ int xenbus_watch_path(struct xenbus_device *dev, const char *path, struct xenbus_watch *watch, @@ -156,16 +158,18 @@ EXPORT_SYMBOL_GPL(xenbus_watch_path); * xenbus_watch_pathfmt - register a watch on a sprintf-formatted path * @dev: xenbus device * @watch: watch to register + * @will_handle: events queuing determine callback * @callback: callback to register * @pathfmt: format of path to watch * * Register a watch on the given @path, using the given xenbus_watch - * structure for storage, and the given @callback function as the callback. - * Return 0 on success, or -errno on error. On success, the watched path - * (@path/@path2) will be saved as @watch->node, and becomes the caller's to - * kfree(). On error, watch->node will be NULL, so the caller has nothing to - * free, the device will switch to %XenbusStateClosing, and the error will be - * saved in the store. + * structure for storage, @will_handle function as the callback to determine if + * each event need to be queued, and the given @callback function as the + * callback. Return 0 on success, or -errno on error. On success, the watched + * path (@path/@path2) will be saved as @watch->node, and becomes the caller's + * to kfree(). On error, watch->node will be NULL, so the caller has nothing + * to free, the device will switch to %XenbusStateClosing, and the error will + * be saved in the store. */ int xenbus_watch_pathfmt(struct xenbus_device *dev, struct xenbus_watch *watch,