From nobody Thu Apr 9 23:26:09 2026 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 738A1296BD6 for ; Thu, 5 Mar 2026 06:36:16 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=198.137.202.133 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772692580; cv=none; b=ZAcwSrIUTU7nR0JWKRGDl3JTjgWK0gDPvpPGrvHPF2/38j/7/HmR11HQTA4joUxH/ljioXor14NrD2CxwkL0CumsCn4iaamzC6FcAZdX6H5o1Gj9rSSxSdVsnfRzeDo0FMHMPqII5NFdP5KmWAvhyvF7c/DF+h3GEQEZ5YSzo98= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772692580; c=relaxed/simple; bh=33Xg+DQKC530+d4SnEsHhaZyuGasMTmS0xyO6evdgRo=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version; b=ojHPwxZr9Le8o9t6nOJ3W3n7OQDSh0M+AU3G+pLSkVsS7mEcYg+9DiYCJHJkwKRoOJE7ojl7UZ4Erx9dF9oW1MPwIC3HA7RN1wwAngel75+Ri4wDDBjRNlFQpwn0b07fn0v5TKx4JVjjBUMpZD+tRA+Fm6Zt28HayZVl4IFh06U= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=infradead.org; spf=none smtp.mailfrom=infradead.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b=xiiaTmXC; arc=none smtp.client-ip=198.137.202.133 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=infradead.org Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=infradead.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="xiiaTmXC" 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=7ewnYcy2nslV+UYY3LSEqG9S+1+3RsehqZnnndfPHQA=; b=xiiaTmXCaI6gzksErCQ/Kt4Bdh ne0920L+SxNBxWh82/5IQv8BOQMbMYo9U970ILq89SCaX5ojFAHtBVJvJYZFaG/GGM9saj5EGc37+ w4r+SSyepJTyM954VN5CRnxr+BpKnA3a5EWMYBP+1OMhGi44X088p54Py/wg3t9Yf/FGHsAMslqc7 m3gR4qFplnoEEvK11cdpq92adFgY1uvA3MmUxLz74EP0rZGCA9aSDHoMZTFWNRGyucGRzuPOWicHO bKnlRDVBoieD6nlNgYBEj6PfWlN9CvN2O+I8W05ip9xTLGdQYD1pGgU0rbY4woaVFhOaXBksDDLmR XTWgnUFw==; Received: from [50.53.43.113] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.98.2 #2 (Red Hat Linux)) id 1vy2Jj-000000011IM-0I4d; Thu, 05 Mar 2026 06:36:15 +0000 From: Randy Dunlap To: linux-kernel@vger.kernel.org Cc: Randy Dunlap , Thomas Gleixner , Peter Zijlstra , Andrew Morton Subject: [PATCH] smp: add missing kernel-doc comments Date: Wed, 4 Mar 2026 22:36:14 -0800 Message-ID: <20260305063614.1520684-1-rdunlap@infradead.org> X-Mailer: git-send-email 2.53.0 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Add missing kernel-doc comments and rearrange the order of others to prevent all kernel-doc warnings. - add function Returns: sections or format existing comments as kernel-doc - add missing function parameter comments - use "/**" for smp_call_function_any() and on_each_cpu_cond_mask() - correct the commented function name for on_each_cpu_cond_mask() - use correct format for function short descriptions - add all kernel-doc comments for smp_call_on_cpu() - remove kernel-doc comments for raw_smp_processor_id() since there is no prototype for it here (other than !SMP) - in smp.h, rearrange some lines so that the kernel-doc comments for smp_processor_id() are immediately before the macro (to prevent kernel-doc warnings) Signed-off-by: Randy Dunlap --- Cc: Thomas Gleixner Cc: Peter Zijlstra Cc: Andrew Morton include/linux/smp.h | 38 +++++++++++++++++++++----------------- kernel/smp.c | 34 ++++++++++++++++++++++++---------- 2 files changed, 45 insertions(+), 27 deletions(-) --- linux-next-20260304.orig/kernel/smp.c +++ linux-next-20260304/kernel/smp.c @@ -215,7 +215,7 @@ static atomic_t n_csd_lock_stuck; /** * csd_lock_is_stuck - Has a CSD-lock acquisition been stuck too long? * - * Returns @true if a CSD-lock acquisition is stuck and has been stuck + * Returns: @true if a CSD-lock acquisition is stuck and has been stuck * long enough for a "non-responsive CSD lock" message to be printed. */ bool csd_lock_is_stuck(void) @@ -625,13 +625,14 @@ void flush_smp_call_function_queue(void) local_irq_restore(flags); } =20 -/* +/** * smp_call_function_single - Run a function on a specific CPU + * @cpu: Specific target CPU for this function. * @func: The function to run. This must be fast and non-blocking. * @info: An arbitrary pointer to pass to the function. * @wait: If true, wait until function has completed on other CPUs. * - * Returns 0 on success, else a negative status code. + * Returns: %0 on success, else a negative status code. */ int smp_call_function_single(int cpu, smp_call_func_t func, void *info, int wait) @@ -738,14 +739,14 @@ out: } EXPORT_SYMBOL_GPL(smp_call_function_single_async); =20 -/* +/** * smp_call_function_any - Run a function on any of the given cpus * @mask: The mask of cpus it can run on. * @func: The function to run. This must be fast and non-blocking. * @info: An arbitrary pointer to pass to the function. * @wait: If true, wait until function has completed. * - * Returns 0 on success, else a negative status code (if no cpus were onli= ne). + * Returns: %0 on success, else a negative status code (if no cpus were on= line). * * Selection preference: * 1) current cpu if in @mask @@ -880,7 +881,7 @@ static void smp_call_function_many_cond( } =20 /** - * smp_call_function_many(): Run a function on a set of CPUs. + * smp_call_function_many() - Run a function on a set of CPUs. * @mask: The set of cpus to run on (only runs on online subset). * @func: The function to run. This must be fast and non-blocking. * @info: An arbitrary pointer to pass to the function. @@ -902,7 +903,7 @@ void smp_call_function_many(const struct EXPORT_SYMBOL(smp_call_function_many); =20 /** - * smp_call_function(): Run a function on all other CPUs. + * smp_call_function() - Run a function on all other CPUs. * @func: The function to run. This must be fast and non-blocking. * @info: An arbitrary pointer to pass to the function. * @wait: If true, wait (atomically) until function has completed @@ -1009,8 +1010,8 @@ void __init smp_init(void) smp_cpus_done(setup_max_cpus); } =20 -/* - * on_each_cpu_cond(): Call a function on each processor for which +/** + * on_each_cpu_cond_mask() - Call a function on each processor for which * the supplied function cond_func returns true, optionally waiting * for all the required CPUs to finish. This may include the local * processor. @@ -1024,6 +1025,7 @@ void __init smp_init(void) * @info: An arbitrary pointer to pass to both functions. * @wait: If true, wait (atomically) until function has * completed on other CPUs. + * @mask: The set of cpus to run on (only runs on online subset). * * Preemption is disabled to protect against CPUs going offline but not on= line. * CPUs going online during the call will not be seen or sent an IPI. @@ -1095,7 +1097,7 @@ EXPORT_SYMBOL_GPL(wake_up_all_idle_cpus) * scheduled, for any of the CPUs in the @mask. It does not guarantee * correctness as it only provides a racy snapshot. * - * Returns true if there is a pending IPI scheduled and false otherwise. + * Returns: true if there is a pending IPI scheduled and false otherwise. */ bool cpus_peek_for_pending_ipi(const struct cpumask *mask) { @@ -1145,6 +1147,18 @@ static void smp_call_on_cpu_callback(str complete(&sscs->done); } =20 +/** + * smp_call_on_cpu() - Call a function on a specific CPU and wait + * for it to return. + * @cpu: The CPU to run on. + * @func: The function to run + * @par: An arbitrary pointer parameter for @func. + * @phys: If @true, force to run on physical @cpu. See + * &struct smp_call_on_cpu_struct for more info. + * + * Returns: %-ENXIO if the @cpu is invalid; otherwise the return value + * from @func. + */ int smp_call_on_cpu(unsigned int cpu, int (*func)(void *), void *par, bool= phys) { struct smp_call_on_cpu_struct sscs =3D { --- linux-next-20260304.orig/include/linux/smp.h +++ linux-next-20260304/include/linux/smp.h @@ -73,7 +73,7 @@ static inline void on_each_cpu(smp_call_ } =20 /** - * on_each_cpu_mask(): Run a function on processors specified by + * on_each_cpu_mask() - Run a function on processors specified by * cpumask, which may include the local processor. * @mask: The set of cpus to run on (only runs on online subset). * @func: The function to run. This must be fast and non-blocking. @@ -239,13 +239,30 @@ static inline int get_boot_cpu_id(void) =20 #endif /* !SMP */ =20 -/** +/* * raw_smp_processor_id() - get the current (unstable) CPU id * - * For then you know what you are doing and need an unstable + * raw_smp_processor_id() is arch-specific/arch-defined and + * may be a macro or a static inline function. + * + * For when you know what you are doing and need an unstable * CPU id. */ =20 +/* + * Allow the architecture to differentiate between a stable and unstable r= ead. + * For example, x86 uses an IRQ-safe asm-volatile read for the unstable bu= t a + * regular asm read for the stable. + */ +#ifndef __smp_processor_id +#define __smp_processor_id() raw_smp_processor_id() +#endif + +#ifdef CONFIG_DEBUG_PREEMPT + extern unsigned int debug_smp_processor_id(void); +# define smp_processor_id() debug_smp_processor_id() + +#else /** * smp_processor_id() - get the current (stable) CPU id * @@ -258,23 +275,10 @@ static inline int get_boot_cpu_id(void) * - preemption is disabled; * - the task is CPU affine. * - * When CONFIG_DEBUG_PREEMPT; we verify these assumption and WARN + * When CONFIG_DEBUG_PREEMPT=3Dy, we verify these assumptions and WARN * when smp_processor_id() is used when the CPU id is not stable. */ =20 -/* - * Allow the architecture to differentiate between a stable and unstable r= ead. - * For example, x86 uses an IRQ-safe asm-volatile read for the unstable bu= t a - * regular asm read for the stable. - */ -#ifndef __smp_processor_id -#define __smp_processor_id() raw_smp_processor_id() -#endif - -#ifdef CONFIG_DEBUG_PREEMPT - extern unsigned int debug_smp_processor_id(void); -# define smp_processor_id() debug_smp_processor_id() -#else # define smp_processor_id() __smp_processor_id() #endif