From patchwork Fri Dec 22 05:25:19 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 182542 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:2483:b0:fb:cd0c:d3e with SMTP id q3csp859107dyi; Thu, 21 Dec 2023 21:25:52 -0800 (PST) X-Google-Smtp-Source: AGHT+IHzVpsHWuezsw3AWHphi8EO6tsExr6PonCpyqB+6TCQnh0fqjQf0bFSScN2uxLystOMccYt X-Received: by 2002:a05:6a21:3397:b0:194:e01b:bd14 with SMTP id yy23-20020a056a21339700b00194e01bbd14mr694962pzb.18.1703222752463; Thu, 21 Dec 2023 21:25:52 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1703222752; cv=none; d=google.com; s=arc-20160816; b=J8l98TLv+rIzEWKgy+TaXhTJi8fMkefKEQ1kV0FEgFnpKMu93bl3GYRVisdEgWpf9/ 4VYry4Pd5wpYXXoEc5/9ZE4jFvl4qS9HS87DYQQOjLrfrCHm9z/KiGmcHANTpUf9ntur NlG/uCVmBRzMZjlklXUCErb/2UX7xwkMM46qe224T34iYl0TWfVbRdn4DXcOB8+QDL2O mDkDFvYXllosO0H0y78z28uFBxjL0ZGJkuhQ16hUKWJKFcBlGblKR+hGd/KAsByxeILy Wgi0JpSnHw0u8KgxELoRdRlPDsOQOvO62VY0FJurUK4qEGMw+hFYfmeQvYY+ssSgGKaI y7+A== 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=EBqowUzGpDWua1BG7YiJIcY9apvHph/sydmOhBcHXkU=; fh=fZ0/Cw+xoRxI3Qielm39cPIAeEqmtcSUTkwOIQBAkI0=; b=bdPGWnXHAZkLARlzVHWT6ZHvLGzLSX3zXDHOOPFGQeFYZqMHa2dJTrUowyHtvjUZ3Q b52cUxsq7sJBkA0zAG7kKzr+7GkPqP7si/nqrXLIydjMiaqp8Q4Pup4Y5cTkR6DCX+bG oxJGN5QLepzY4jcyYR33wZeOTOBKp3AF+VYPKJDVRxucsG374r9jMJI516U6f0J3r/SM R81yNmy+ye1cgPMu/dpm30VdstqvtzKbTJ82QUrzxD4x5DsQg3RQ8aqBM5gAJT9t++29 j7qSuSVgRg7KboYOrE8lk8KvzwCx9VkHsBfoT9hqaV6/X4TXoq0YHJdW+9qv82bet7q8 U7gg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@infradead.org header.s=bombadil.20210309 header.b=nzF0NmxM; spf=pass (google.com: domain of linux-kernel+bounces-9364-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-9364-ouuuleilei=gmail.com@vger.kernel.org" Received: from sv.mirrors.kernel.org (sv.mirrors.kernel.org. [2604:1380:45e3:2400::1]) by mx.google.com with ESMTPS id 1-20020a17090a0cc100b0028bc575e78csi2735729pjt.189.2023.12.21.21.25.52 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Dec 2023 21:25:52 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-9364-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) client-ip=2604:1380:45e3:2400::1; Authentication-Results: mx.google.com; dkim=pass header.i=@infradead.org header.s=bombadil.20210309 header.b=nzF0NmxM; spf=pass (google.com: domain of linux-kernel+bounces-9364-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45e3:2400::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-9364-ouuuleilei=gmail.com@vger.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 1C215286DC7 for ; Fri, 22 Dec 2023 05:25:52 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 98101B667; Fri, 22 Dec 2023 05:25:26 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="nzF0NmxM" X-Original-To: linux-kernel@vger.kernel.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (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 7224A6124 for ; Fri, 22 Dec 2023 05:25:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:Message-ID:Date:Subject:Cc:To:From:Sender:Reply-To:Content-Type: Content-ID:Content-Description:In-Reply-To:References; bh=EBqowUzGpDWua1BG7YiJIcY9apvHph/sydmOhBcHXkU=; b=nzF0NmxMWhBMlmbAGsuap5JedS 47DFcSlDbj6impoGUffP5ZbA1rDRbTw/56ag6h1Ga3GQM/AJPeDnKzoylMqyMVqbp6VjgYfwVBg89 3CLmf1zvCI2Kj+PoQ0vp8ztjMgUECAZiTC5L64eZOJKZ1pxfpHn4tjI34OnvcQlYXtp4of7Xh3eQU CO8nmN+RV6kH9mD8bQT69TZq3feKVwugRE6cxi1MP0pF6T3A/52q9A4VyZcEfV4aHeREBeYkpO6vz ZmxKdZu90YQThN9I+oJeTMaavgROCKDr/lQDFeqj+0UH9qkSB2dSRU6a1IftgkbvSBvUC842neIT9 FQFm07pA==; Received: from [50.53.46.231] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.96 #2 (Red Hat Linux)) id 1rGY2D-004y0F-20; Fri, 22 Dec 2023 05:25:21 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Hans de Goede , Arnd Bergmann , Greg Kroah-Hartman Subject: [PATCH 1/3] virt: vbox: core: fix all kernel-doc warnings Date: Thu, 21 Dec 2023 21:25:19 -0800 Message-ID: <20231222052521.14333-1-rdunlap@infradead.org> X-Mailer: git-send-email 2.43.0 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: 1785958500825439492 X-GMAIL-MSGID: 1785958500825439492 Use kernel-doc format for functions that have comments that begin with "/**". This prevents 26 kernel-doc warnings. Signed-off-by: Randy Dunlap Cc: Hans de Goede Cc: Arnd Bergmann Cc: Greg Kroah-Hartman --- drivers/virt/vboxguest/vboxguest_core.c | 154 +++++++++++++--------- 1 file changed, 91 insertions(+), 63 deletions(-) diff -- a/drivers/virt/vboxguest/vboxguest_core.c b/drivers/virt/vboxguest/vboxguest_core.c --- a/drivers/virt/vboxguest/vboxguest_core.c +++ b/drivers/virt/vboxguest/vboxguest_core.c @@ -33,16 +33,15 @@ VMMDEV_REQUESTOR_CON_DONT_KNOW | VMMDEV_REQUESTOR_TRUST_NOT_GIVEN) /** - * Reserves memory in which the VMM can relocate any guest mappings - * that are floating around. + * vbg_guest_mappings_init - Reserves memory in which the VMM can + * relocate any guest mappings that are floating around. + * @gdev: The Guest extension device. * * This operation is a little bit tricky since the VMM might not accept * just any address because of address clashes between the three contexts * it operates in, so we try several times. * * Failure to reserve the guest mappings is ignored. - * - * @gdev: The Guest extension device. */ static void vbg_guest_mappings_init(struct vbg_dev *gdev) { @@ -125,7 +124,7 @@ out: } /** - * Undo what vbg_guest_mappings_init did. + * vbg_guest_mappings_exit - Undo what vbg_guest_mappings_init did. * * @gdev: The Guest extension device. */ @@ -166,9 +165,10 @@ static void vbg_guest_mappings_exit(stru } /** - * Report the guest information to the host. - * Return: 0 or negative errno value. + * vbg_report_guest_info - Report the guest information to the host. * @gdev: The Guest extension device. + * + * Return: %0 or negative errno value. */ static int vbg_report_guest_info(struct vbg_dev *gdev) { @@ -229,10 +229,11 @@ out_free: } /** - * Report the guest driver status to the host. - * Return: 0 or negative errno value. + * vbg_report_driver_status - Report the guest driver status to the host. * @gdev: The Guest extension device. * @active: Flag whether the driver is now active or not. + * + * Return: 0 or negative errno value. */ static int vbg_report_driver_status(struct vbg_dev *gdev, bool active) { @@ -261,10 +262,12 @@ static int vbg_report_driver_status(stru } /** - * Inflate the balloon by one chunk. The caller owns the balloon mutex. - * Return: 0 or negative errno value. + * vbg_balloon_inflate - Inflate the balloon by one chunk. The caller + * owns the balloon mutex. * @gdev: The Guest extension device. * @chunk_idx: Index of the chunk. + * + * Return: %0 or negative errno value. */ static int vbg_balloon_inflate(struct vbg_dev *gdev, u32 chunk_idx) { @@ -312,10 +315,12 @@ out_error: } /** - * Deflate the balloon by one chunk. The caller owns the balloon mutex. - * Return: 0 or negative errno value. + * vbg_balloon_deflate - Deflate the balloon by one chunk. The caller + * owns the balloon mutex. * @gdev: The Guest extension device. * @chunk_idx: Index of the chunk. + * + * Return: %0 or negative errno value. */ static int vbg_balloon_deflate(struct vbg_dev *gdev, u32 chunk_idx) { @@ -344,7 +349,7 @@ static int vbg_balloon_deflate(struct vb return 0; } -/** +/* * Respond to VMMDEV_EVENT_BALLOON_CHANGE_REQUEST events, query the size * the host wants the balloon to be and adjust accordingly. */ @@ -409,7 +414,7 @@ static void vbg_balloon_work(struct work } } -/** +/* * Callback for heartbeat timer. */ static void vbg_heartbeat_timer(struct timer_list *t) @@ -422,11 +427,12 @@ static void vbg_heartbeat_timer(struct t } /** - * Configure the host to check guest's heartbeat - * and get heartbeat interval from the host. - * Return: 0 or negative errno value. + * vbg_heartbeat_host_config - Configure the host to check guest's heartbeat + * and get heartbeat interval from the host. * @gdev: The Guest extension device. * @enabled: Set true to enable guest heartbeat checks on host. + * + * Return: %0 or negative errno value. */ static int vbg_heartbeat_host_config(struct vbg_dev *gdev, bool enabled) { @@ -449,9 +455,11 @@ static int vbg_heartbeat_host_config(str } /** - * Initializes the heartbeat timer. This feature may be disabled by the host. - * Return: 0 or negative errno value. + * vbg_heartbeat_init - Initializes the heartbeat timer. This feature + * may be disabled by the host. * @gdev: The Guest extension device. + * + * Return: %0 or negative errno value. */ static int vbg_heartbeat_init(struct vbg_dev *gdev) { @@ -481,7 +489,8 @@ static int vbg_heartbeat_init(struct vbg } /** - * Cleanup hearbeat code, stop HB timer and disable host heartbeat checking. + * vbg_heartbeat_exit - Cleanup heartbeat code, stop HB timer and disable + * host heartbeat checking. * @gdev: The Guest extension device. */ static void vbg_heartbeat_exit(struct vbg_dev *gdev) @@ -493,11 +502,12 @@ static void vbg_heartbeat_exit(struct vb } /** - * Applies a change to the bit usage tracker. - * Return: true if the mask changed, false if not. + * vbg_track_bit_usage - Applies a change to the bit usage tracker. * @tracker: The bit usage tracker. * @changed: The bits to change. * @previous: The previous value of the bits. + * + * Return: %true if the mask changed, %false if not. */ static bool vbg_track_bit_usage(struct vbg_bit_usage_tracker *tracker, u32 changed, u32 previous) @@ -529,10 +539,12 @@ static bool vbg_track_bit_usage(struct v } /** - * Init and termination worker for resetting the (host) event filter on the host - * Return: 0 or negative errno value. + * vbg_reset_host_event_filter - Init and termination worker for + * resetting the (host) event filter on the host * @gdev: The Guest extension device. * @fixed_events: Fixed events (init time). + * + * Return: %0 or negative errno value. */ static int vbg_reset_host_event_filter(struct vbg_dev *gdev, u32 fixed_events) @@ -556,12 +568,8 @@ static int vbg_reset_host_event_filter(s } /** - * Changes the event filter mask for the given session. - * - * This is called in response to VBG_IOCTL_CHANGE_FILTER_MASK as well as to - * do session cleanup. Takes the session mutex. - * - * Return: 0 or negative errno value. + * vbg_set_session_event_filter - Changes the event filter mask for the + * given session. * @gdev: The Guest extension device. * @session: The session. * @or_mask: The events to add. @@ -570,6 +578,11 @@ static int vbg_reset_host_event_filter(s * This tweaks the error handling so we perform * proper session cleanup even if the host * misbehaves. + * + * This is called in response to VBG_IOCTL_CHANGE_FILTER_MASK as well as to + * do session cleanup. Takes the session mutex. + * + * Return: 0 or negative errno value. */ static int vbg_set_session_event_filter(struct vbg_dev *gdev, struct vbg_session *session, @@ -637,9 +650,11 @@ out: } /** - * Init and termination worker for set guest capabilities to zero on the host. - * Return: 0 or negative errno value. + * vbg_reset_host_capabilities - Init and termination worker for set + * guest capabilities to zero on the host. * @gdev: The Guest extension device. + * + * Return: %0 or negative errno value. */ static int vbg_reset_host_capabilities(struct vbg_dev *gdev) { @@ -662,12 +677,14 @@ static int vbg_reset_host_capabilities(s } /** - * Set guest capabilities on the host. - * Must be called with gdev->session_mutex hold. - * Return: 0 or negative errno value. + * vbg_set_host_capabilities - Set guest capabilities on the host. * @gdev: The Guest extension device. * @session: The session. * @session_termination: Set if we're called by the session cleanup code. + * + * Must be called with gdev->session_mutex hold. + * + * Return: %0 or negative errno value. */ static int vbg_set_host_capabilities(struct vbg_dev *gdev, struct vbg_session *session, @@ -704,9 +721,8 @@ static int vbg_set_host_capabilities(str } /** - * Acquire (get exclusive access) guest capabilities for a session. - * Takes the session mutex. - * Return: 0 or negative errno value. + * vbg_acquire_session_capabilities - Acquire (get exclusive access) + * guest capabilities for a session. * @gdev: The Guest extension device. * @session: The session. * @flags: Flags (VBGL_IOC_AGC_FLAGS_XXX). @@ -716,6 +732,10 @@ static int vbg_set_host_capabilities(str * This tweaks the error handling so we perform * proper session cleanup even if the host * misbehaves. + * + * Takes the session mutex. + * + * Return: %0 or negative errno value. */ static int vbg_acquire_session_capabilities(struct vbg_dev *gdev, struct vbg_session *session, @@ -811,8 +831,8 @@ out: } /** - * Sets the guest capabilities for a session. Takes the session mutex. - * Return: 0 or negative errno value. + * vbg_set_session_capabilities - Sets the guest capabilities for a + * session. Takes the session mutex. * @gdev: The Guest extension device. * @session: The session. * @or_mask: The capabilities to add. @@ -821,6 +841,8 @@ out: * This tweaks the error handling so we perform * proper session cleanup even if the host * misbehaves. + * + * Return: %0 or negative errno value. */ static int vbg_set_session_capabilities(struct vbg_dev *gdev, struct vbg_session *session, @@ -866,9 +888,10 @@ out: } /** - * vbg_query_host_version get the host feature mask and version information. - * Return: 0 or negative errno value. + * vbg_query_host_version - get the host feature mask and version information. * @gdev: The Guest extension device. + * + * Return: %0 or negative errno value. */ static int vbg_query_host_version(struct vbg_dev *gdev) { @@ -905,19 +928,18 @@ out: } /** - * Initializes the VBoxGuest device extension when the - * device driver is loaded. + * vbg_core_init - Initializes the VBoxGuest device extension when the + * device driver is loaded. + * @gdev: The Guest extension device. + * @fixed_events: Events that will be enabled upon init and no client + * will ever be allowed to mask. * * The native code locates the VMMDev on the PCI bus and retrieve * the MMIO and I/O port ranges, this function will take care of * mapping the MMIO memory (if present). Upon successful return * the native code should set up the interrupt handler. * - * Return: 0 or negative errno value. - * - * @gdev: The Guest extension device. - * @fixed_events: Events that will be enabled upon init and no client - * will ever be allowed to mask. + * Return: %0 or negative errno value. */ int vbg_core_init(struct vbg_dev *gdev, u32 fixed_events) { @@ -1017,11 +1039,12 @@ err_free_reqs: } /** - * Call this on exit to clean-up vboxguest-core managed resources. + * vbg_core_exit - Call this on exit to clean-up vboxguest-core managed + * resources. + * @gdev: The Guest extension device. * * The native code should call this before the driver is loaded, * but don't call this on shutdown. - * @gdev: The Guest extension device. */ void vbg_core_exit(struct vbg_dev *gdev) { @@ -1046,12 +1069,13 @@ void vbg_core_exit(struct vbg_dev *gdev) } /** - * Creates a VBoxGuest user session. + * vbg_core_open_session - Creates a VBoxGuest user session. + * @gdev: The Guest extension device. + * @requestor: VMMDEV_REQUESTOR_* flags * * vboxguest_linux.c calls this when userspace opens the char-device. + * * Return: A pointer to the new session or an ERR_PTR on error. - * @gdev: The Guest extension device. - * @requestor: VMMDEV_REQUESTOR_* flags */ struct vbg_session *vbg_core_open_session(struct vbg_dev *gdev, u32 requestor) { @@ -1068,7 +1092,7 @@ struct vbg_session *vbg_core_open_sessio } /** - * Closes a VBoxGuest session. + * vbg_core_close_session - Closes a VBoxGuest session. * @session: The session to close (and free). */ void vbg_core_close_session(struct vbg_session *session) @@ -1250,11 +1274,13 @@ static int vbg_ioctl_interrupt_all_wait_ } /** - * Checks if the VMM request is allowed in the context of the given session. - * Return: 0 or negative errno value. + * vbg_req_allowed - Checks if the VMM request is allowed in the + * context of the given session. * @gdev: The Guest extension device. * @session: The calling session. * @req: The request. + * + * Return: %0 or negative errno value. */ static int vbg_req_allowed(struct vbg_dev *gdev, struct vbg_session *session, const struct vmmdev_request_header *req) @@ -1670,11 +1696,12 @@ static int vbg_ioctl_write_core_dump(str } /** - * Common IOCtl for user to kernel communication. - * Return: 0 or negative errno value. + * vbg_core_ioctl - Common IOCtl for user to kernel communication. * @session: The client session. * @req: The requested function. * @data: The i/o data buffer, minimum size sizeof(struct vbg_ioctl_hdr). + * + * Return: %0 or negative errno value. */ int vbg_core_ioctl(struct vbg_session *session, unsigned int req, void *data) { @@ -1744,11 +1771,12 @@ int vbg_core_ioctl(struct vbg_session *s } /** - * Report guest supported mouse-features to the host. + * vbg_core_set_mouse_status - Report guest supported mouse-features to the host. * - * Return: 0 or negative errno value. * @gdev: The Guest extension device. * @features: The set of features to report to the host. + * + * Return: %0 or negative errno value. */ int vbg_core_set_mouse_status(struct vbg_dev *gdev, u32 features) { @@ -1772,7 +1800,7 @@ int vbg_core_set_mouse_status(struct vbg return vbg_status_code_to_errno(rc); } -/** Core interrupt service routine. */ +/* Core interrupt service routine. */ irqreturn_t vbg_core_isr(int irq, void *dev_id) { struct vbg_dev *gdev = dev_id; From patchwork Fri Dec 22 05:25:20 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 182541 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:2483:b0:fb:cd0c:d3e with SMTP id q3csp859088dyi; Thu, 21 Dec 2023 21:25:48 -0800 (PST) X-Google-Smtp-Source: AGHT+IFn7LL8ZuXx8tsvj00cVs4cuG9tLd+hQcQwz66bt0wiwRmARHklz+PuE/uM94sDRVyfnT9R X-Received: by 2002:a05:6214:258a:b0:67a:6216:4a01 with SMTP id fq10-20020a056214258a00b0067a62164a01mr859029qvb.0.1703222748643; Thu, 21 Dec 2023 21:25:48 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1703222748; cv=none; d=google.com; s=arc-20160816; b=1H1k4sHQtQe1HoVTfbTurpuKxqxuk3hBJmrr8I5MzogBPNlOmkg/cRVijkuMY7SIyq IYnmoRdEjYGSz/72xDkXZpj6VfAIWiUEyWGjs/40YF//Z179RL0Otu7izwrf5p6OaFZ6 OQH2n3ETSDNOSgMuN6H8dub8RGkq0llRc1Rq09eR8gsovLR0ccRC4/k2EwIKy+G5ynt+ 89BUKc05DpsxSF17Oq9KXjU6PFqqUyq9LewwthUWzMEvXqiOaHf33O+MoJuecwSBTbRi YG57v1wHSgU60TQ63U6RirLS3D6ai+giGAUyMmmwlNsjnmW3y8W99zTLC3rvT1khkF6A 79bg== 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:references:in-reply-to:message-id :date:subject:cc:to:from:dkim-signature; bh=dsMR+WACwlCN6vo2Aferq2y6mgFg8ofBbNv8oumItv4=; fh=fZ0/Cw+xoRxI3Qielm39cPIAeEqmtcSUTkwOIQBAkI0=; b=Xn/YYhJy7J+pPyJh0xA1f56emGg2hH9VUv3zZM+ZhVTACBalFsP4iZ0PZQqyavpJ+e 9pvSTplytYbaXj7fF/2b8OVWv9G6XiZgUHq07lw9wGw79lVFxmAsh/bPHm5rZGivhh9g lsqBeEmfAkqc2C9jvEC16hnH4ZdJ/T5JydGBP5X89pvvS6IheGShYe4GeJhGYvQMnBlm Dq/eLs4Nudw2DL7ZYduVmKUq7GmWAbagdVuU9RiDr1PQNN4zfc+S+ZBAIprsITeAERsR jRCIFAwDdZEnhQCspf7e3tzcReFD6End9Mkkv3gfLaSJvbBYnNDRxntx2TFtRo6ohs5u /itg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@infradead.org header.s=bombadil.20210309 header.b=0eo9Cvsx; spf=pass (google.com: domain of linux-kernel+bounces-9363-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-9363-ouuuleilei=gmail.com@vger.kernel.org" Received: from ny.mirrors.kernel.org (ny.mirrors.kernel.org. [2604:1380:45d1:ec00::1]) by mx.google.com with ESMTPS id c2-20020a0ce642000000b0067f8284e660si2975186qvn.214.2023.12.21.21.25.48 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Dec 2023 21:25:48 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-9363-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) client-ip=2604:1380:45d1:ec00::1; Authentication-Results: mx.google.com; dkim=pass header.i=@infradead.org header.s=bombadil.20210309 header.b=0eo9Cvsx; spf=pass (google.com: domain of linux-kernel+bounces-9363-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:45d1:ec00::1 as permitted sender) smtp.mailfrom="linux-kernel+bounces-9363-ouuuleilei=gmail.com@vger.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 ny.mirrors.kernel.org (Postfix) with ESMTPS id 676431C24AE0 for ; Fri, 22 Dec 2023 05:25:48 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 45C13B64C; Fri, 22 Dec 2023 05:25:26 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="0eo9Cvsx" X-Original-To: linux-kernel@vger.kernel.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (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 721E46112 for ; Fri, 22 Dec 2023 05:25:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-ID:Date:Subject:Cc:To:From:Sender :Reply-To:Content-Type:Content-ID:Content-Description; bh=dsMR+WACwlCN6vo2Aferq2y6mgFg8ofBbNv8oumItv4=; b=0eo9CvsxjzpdF4U8hBbO9yLtRL uH7OLXC6gHLsYCYHri2luyui/yGzD1l0Yls0YhM0QWEyjG8Xb64le1VcBc2AFFavd+aJkAhBp8HY+ kSjMRJEA1S5g2L1TcL6X8Rkz/BM7KnY1e233RDtwoCcmgjNMUurH+a88nkIa4efdl6hmdUZgE5lap fij3uPbGitQYLy5E01roa3wQ6mP/ZE0DZRpjs5rO3DVuPBnIsGYAgb/lMg6PKryF9koOFSt0u/glN y6VeCt+jD9rAUdJKude4AbmFuthCKyhyMJnVg0Rw3GMJFbGlyHB9iYj6rQHgUfYRpxoB15IPNrU08 KFhMwalQ==; Received: from [50.53.46.231] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.96 #2 (Red Hat Linux)) id 1rGY2D-004y0F-2j; Fri, 22 Dec 2023 05:25:21 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Hans de Goede , Arnd Bergmann , Greg Kroah-Hartman Subject: [PATCH 2/3] virt: vbox: linux: fix all kernel-doc warnings Date: Thu, 21 Dec 2023 21:25:20 -0800 Message-ID: <20231222052521.14333-2-rdunlap@infradead.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20231222052521.14333-1-rdunlap@infradead.org> References: <20231222052521.14333-1-rdunlap@infradead.org> 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: 1785958496713319538 X-GMAIL-MSGID: 1785958496713319538 Use kernel-doc format for functions that are almost complete in their kernel-doc comments. For other functions, just change the comment to a common C comment. This prevents 7 kernel-doc warnings. Signed-off-by: Randy Dunlap Cc: Hans de Goede Cc: Arnd Bergmann Cc: Greg Kroah-Hartman --- drivers/virt/vboxguest/vboxguest_linux.c | 22 +++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff -- a/drivers/virt/vboxguest/vboxguest_linux.c b/drivers/virt/vboxguest/vboxguest_linux.c --- a/drivers/virt/vboxguest/vboxguest_linux.c +++ b/drivers/virt/vboxguest/vboxguest_linux.c @@ -81,10 +81,11 @@ static int vbg_misc_device_user_open(str } /** - * Close device. - * Return: 0 on success, negated errno on failure. + * vbg_misc_device_close - Close device. * @inode: Pointer to inode info structure. * @filp: Associated file pointer. + * + * Return: %0 on success, negated errno on failure. */ static int vbg_misc_device_close(struct inode *inode, struct file *filp) { @@ -94,11 +95,12 @@ static int vbg_misc_device_close(struct } /** - * Device I/O Control entry point. - * Return: 0 on success, negated errno on failure. + * vbg_misc_device_ioctl - Device I/O Control entry point. * @filp: Associated file pointer. * @req: The request specified to ioctl(). * @arg: The argument specified to ioctl(). + * + * Return: %0 on success, negated errno on failure. */ static long vbg_misc_device_ioctl(struct file *filp, unsigned int req, unsigned long arg) @@ -173,7 +175,7 @@ out: return ret; } -/** The file_operations structures. */ +/* The file_operations structures. */ static const struct file_operations vbg_misc_device_fops = { .owner = THIS_MODULE, .open = vbg_misc_device_open, @@ -193,7 +195,7 @@ static const struct file_operations vbg_ #endif }; -/** +/* * Called when the input device is first opened. * * Sets up absolute mouse reporting. @@ -206,7 +208,7 @@ static int vbg_input_open(struct input_d return vbg_core_set_mouse_status(gdev, feat); } -/** +/* * Called if all open handles to the input device are closed. * * Disables absolute reporting. @@ -218,7 +220,7 @@ static void vbg_input_close(struct input vbg_core_set_mouse_status(gdev, 0); } -/** +/* * Creates the kernel input device. * * Return: 0 on success, negated errno on failure. @@ -277,7 +279,7 @@ static struct attribute *vbg_pci_attrs[] }; ATTRIBUTE_GROUPS(vbg_pci); -/** +/* * Does the PCI detection and init of the device. * * Return: 0 on success, negated errno on failure. @@ -453,7 +455,7 @@ void vbg_put_gdev(struct vbg_dev *gdev) } EXPORT_SYMBOL(vbg_put_gdev); -/** +/* * Callback for mouse events. * * This is called at the end of the ISR, after leaving the event spinlock, if From patchwork Fri Dec 22 05:25:21 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Randy Dunlap X-Patchwork-Id: 182543 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7300:2483:b0:fb:cd0c:d3e with SMTP id q3csp859133dyi; Thu, 21 Dec 2023 21:26:01 -0800 (PST) X-Google-Smtp-Source: AGHT+IEATlfN6J7v4qgap2iLHVe+ulXGaTQaBYdsgpDRP3lBy0kzMMGjIBHWkTQxDX/jGROtBsCP X-Received: by 2002:a05:6402:22c3:b0:554:595:9805 with SMTP id dm3-20020a05640222c300b0055405959805mr300691edb.74.1703222761758; Thu, 21 Dec 2023 21:26:01 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1703222761; cv=none; d=google.com; s=arc-20160816; b=g/6woU8s/9u42gWX9p/deeUWPgb+zhAaWVUhyPA2g/5goECOst9ByNpOK5q1rF2Xz/ h5csMCCP0aRaqQBd/qGfpeAQ4ca8QSPA8DXBpUBCIblDkQ3O5az0BwK0K1T9bVI4vnaB Yak/ur5G8dX2G7mMVWlmYTK1Enw1mwoEQKg4cxilPOs5FpNbMq8GuWiK5vxjKMKq03Be U2CNVVjSwgCR1Qht0/UmnxCaHWoGpRtezJzv54JBIf1ujZ5WFEsHj11cJkS3o05slxHY Gc8lOU6ppu86/X+ZvEhL8fiDn4wfvqb1g3wRxVI5XuCLzDcULNUbrn2bVIKPcyhC1YYB oqdQ== 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:references:in-reply-to:message-id :date:subject:cc:to:from:dkim-signature; bh=NcgjXN95RsDAjlsvl0lPtlflx+Yff9K/qAsTAqvV9q4=; fh=fZ0/Cw+xoRxI3Qielm39cPIAeEqmtcSUTkwOIQBAkI0=; b=yX3itrBDaeF7DlGYgJNmLUtg8B61uZEl1ylnfkAIqhkHENGiCUinaX1yUdVqEFlofl jDxyRQB6JXAm1atorDnsuN7Lg2FqTuJqZL9+pVJhfrDjPaNcQ3cBchRFG4sZ3ZJBUVLX UYSBuZ77ISUUMsxa/BMiPFgTMu31Ih+MHX1de5u6xNKR13WEOmlrqj0LmpW+embhlX9P YTaBrUZNoejK00nsylKeZd+Ma/GF+ERgw8hCJEKsn2g/AHvgLEbPNnXbjiIFqpiNETNu +4Xy0qbLDdvRwT+praSmYWdFo60RVZgb2lHyj4E4WAXsQHGjnCLIXIOOKbHBzw9zrLfp vQkg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@infradead.org header.s=bombadil.20210309 header.b=Ib0tjcY5; spf=pass (google.com: domain of linux-kernel+bounces-9365-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) smtp.mailfrom="linux-kernel+bounces-9365-ouuuleilei=gmail.com@vger.kernel.org" Received: from am.mirrors.kernel.org (am.mirrors.kernel.org. [147.75.80.249]) by mx.google.com with ESMTPS id q6-20020a056402518600b00553366d0746si1545771edd.439.2023.12.21.21.26.01 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 21 Dec 2023 21:26:01 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-9365-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) client-ip=147.75.80.249; Authentication-Results: mx.google.com; dkim=pass header.i=@infradead.org header.s=bombadil.20210309 header.b=Ib0tjcY5; spf=pass (google.com: domain of linux-kernel+bounces-9365-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) smtp.mailfrom="linux-kernel+bounces-9365-ouuuleilei=gmail.com@vger.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 am.mirrors.kernel.org (Postfix) with ESMTPS id E35D91F22D35 for ; Fri, 22 Dec 2023 05:26:00 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id B519EC12D; Fri, 22 Dec 2023 05:25:27 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="Ib0tjcY5" X-Original-To: linux-kernel@vger.kernel.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (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 722216120 for ; Fri, 22 Dec 2023 05:25:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20210309; h=Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-ID:Date:Subject:Cc:To:From:Sender :Reply-To:Content-Type:Content-ID:Content-Description; bh=NcgjXN95RsDAjlsvl0lPtlflx+Yff9K/qAsTAqvV9q4=; b=Ib0tjcY5MpF4PWKRkRejF/bvZv i08sfXeqCuXE22jRpC3ZJw+Izi3HZdADzRbVrtQj8vo3rgbTLCGtCPRzl8p16l6n9lf85xCJZhJEL x8Ll8zdf6jY79f19MAtSyRst12Urun4k8BNu2u2rj5f8CeHP1GLLkdlkBoPPJKK3O2RAWL3gbdfl7 nrSe5aoAJBt7wTUxyIGMX5vWyabfK0iALpCUJa1RI43EEWR7kpMHvRezXD1gP5NZApK5HborMixFF fvFHSYuGKCkM2UAoHzsJwk0j/rC5A6NcVHHIctMIPsWiHT3U6INVUHQBaun64aNdl7DBUxo6sph5h RH5NAezg==; Received: from [50.53.46.231] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.96 #2 (Red Hat Linux)) id 1rGY2E-004y0F-0B; Fri, 22 Dec 2023 05:25:22 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Hans de Goede , Arnd Bergmann , Greg Kroah-Hartman Subject: [PATCH 3/3] virt: vbox: utils: fix all kernel-doc warnings Date: Thu, 21 Dec 2023 21:25:21 -0800 Message-ID: <20231222052521.14333-3-rdunlap@infradead.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20231222052521.14333-1-rdunlap@infradead.org> References: <20231222052521.14333-1-rdunlap@infradead.org> 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: 1785958510777213206 X-GMAIL-MSGID: 1785958510777213206 Use kernel-doc format for functions that have comments that begin with "/**". This prevents 6 kernel-doc warnings. Signed-off-by: Randy Dunlap Cc: Hans de Goede Cc: Arnd Bergmann Cc: Greg Kroah-Hartman --- drivers/virt/vboxguest/vboxguest_utils.c | 33 +++++++++++++-------- 1 file changed, 21 insertions(+), 12 deletions(-) diff -- a/drivers/virt/vboxguest/vboxguest_utils.c b/drivers/virt/vboxguest/vboxguest_utils.c --- a/drivers/virt/vboxguest/vboxguest_utils.c +++ b/drivers/virt/vboxguest/vboxguest_utils.c @@ -237,14 +237,16 @@ static int hgcm_call_preprocess_linaddr( } /** - * Preprocesses the HGCM call, validate parameters, alloc bounce buffers and - * figure out how much extra storage we need for page lists. - * Return: 0 or negative errno value. + * hgcm_call_preprocess - Preprocesses the HGCM call, validate parameters, + * alloc bounce buffers and figure out how much extra storage we need for + * page lists. * @src_parm: Pointer to source function call parameters * @parm_count: Number of function call parameters. * @bounce_bufs_ret: Where to return the allocated bouncebuffer array * @extra: Where to return the extra request space needed for * physical page lists. + * + * Return: %0 or negative errno value. */ static int hgcm_call_preprocess( const struct vmmdev_hgcm_function_parameter *src_parm, @@ -301,10 +303,11 @@ static int hgcm_call_preprocess( } /** - * Translates linear address types to page list direction flags. + * hgcm_call_linear_addr_type_to_pagelist_flags - Translates linear address + * types to page list direction flags. + * @type: The type. * * Return: page list flags. - * @type: The type. */ static u32 hgcm_call_linear_addr_type_to_pagelist_flags( enum vmmdev_hgcm_function_parameter_type type) @@ -369,7 +372,8 @@ static void hgcm_call_init_linaddr(struc } /** - * Initializes the call request that we're sending to the host. + * hgcm_call_init_call - Initializes the call request that we're sending + * to the host. * @call: The call to initialize. * @client_id: The client ID of the caller. * @function: The function number of the function to call. @@ -425,7 +429,9 @@ static void hgcm_call_init_call( } /** - * Tries to cancel a pending HGCM call. + * hgcm_cancel_call - Tries to cancel a pending HGCM call. + * @gdev: The VBoxGuest device extension. + * @call: The call to cancel. * * Return: VBox status code */ @@ -459,13 +465,15 @@ static int hgcm_cancel_call(struct vbg_d } /** - * Performs the call and completion wait. - * Return: 0 or negative errno value. + * vbg_hgcm_do_call - Performs the call and completion wait. * @gdev: The VBoxGuest device extension. * @call: The call to execute. * @timeout_ms: Timeout in ms. + * @interruptible: whether this call is interruptible * @leak_it: Where to return the leak it / free it, indicator. * Cancellation fun. + * + * Return: %0 or negative errno value. */ static int vbg_hgcm_do_call(struct vbg_dev *gdev, struct vmmdev_hgcm_call *call, u32 timeout_ms, bool interruptible, bool *leak_it) @@ -545,13 +553,14 @@ static int vbg_hgcm_do_call(struct vbg_d } /** - * Copies the result of the call back to the caller info structure and user - * buffers. - * Return: 0 or negative errno value. + * hgcm_call_copy_back_result - Copies the result of the call back to + * the caller info structure and user buffers. * @call: HGCM call request. * @dst_parm: Pointer to function call parameters destination. * @parm_count: Number of function call parameters. * @bounce_bufs: The bouncebuffer array. + * + * Return: %0 or negative errno value. */ static int hgcm_call_copy_back_result( const struct vmmdev_hgcm_call *call,