From nobody Thu Apr 2 20:41:07 2026 Received: from galois.linutronix.de (Galois.linutronix.de [193.142.43.55]) (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 83E59296BBF; Thu, 26 Mar 2026 12:59:58 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=193.142.43.55 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774530000; cv=none; b=Y31d84luKFUmk7KRrTUMo8srK/pHGERayA3nlOvnMB/T6NKbZxdtr1GFnPDUgMzJe+3sjwh1b4amfQ7VgrfvJQfsiMcYIiLVZ4Ni2tR1ZB4fESHlTab4cxCiUrU9AGmkvP2Z1wNVOKYis84Q/5heDiwiq93xJcIqPnqnRxhHK1E= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1774530000; c=relaxed/simple; bh=RK/RHmJT2WHm9MCfaTl8bLmJjvi9alQUBNP3D8IVoP8=; h=Date:From:To:Subject:Cc:In-Reply-To:References:MIME-Version: Message-ID:Content-Type; b=JUcdAUWLkJFnKFY3L8/mkZqRvChSCo9wXL7kdtTE4niWrd/KT6mDEa4JVYf0H+WldUxLzvNH34zHyKWu+/mfRH+FgTsUdblr6/DQ/J0RCje01p9DgXy9X0WIub7KiYOHQUevMG6Yz/Ks/HTpEqWNutX9ctAeUJ16NPCP3IRHWz0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linutronix.de; spf=pass smtp.mailfrom=linutronix.de; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=0hF6HVVr; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b=IQp78ylQ; arc=none smtp.client-ip=193.142.43.55 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=linutronix.de Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=linutronix.de Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="0hF6HVVr"; dkim=permerror (0-bit key) header.d=linutronix.de header.i=@linutronix.de header.b="IQp78ylQ" Date: Thu, 26 Mar 2026 12:59:55 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020; t=1774529997; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=nTjPJaRxXM9NerQfjEMyAy2CfqFd1DXt3w+g8xRNa+w=; b=0hF6HVVrXjh3oxDgl2gNyD3OtWFQTjIL+5UdPnf4NxdWVqzqkj8YHhn5sIEqm5Idn+wIFQ 53dYbyKP3P/20oW9eMH3IioY6nYJ6O8tHkH1ZIazwwfEbCbFaM3eHL6KwqGodSBFC1kB8R jB8whsFvv80NwGT9ZdznMLgFHMJf/N907zLx0atrYitrJMOjgzSGgyeUgQ98y/koLUNIH1 gY4zrmgzR8uZpPn/SZ8Hx6B0cv32TtUpPvNal1XsWj95ioqJ2Y3gIDk5LQzcA4Tch5O9Mi ON3p5S+ktkcynJoahEXo7dRwKrldbh+SR6rltxlBbOxJzINIyAt5Bj89bWp2nQ== DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=linutronix.de; s=2020e; t=1774529997; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=nTjPJaRxXM9NerQfjEMyAy2CfqFd1DXt3w+g8xRNa+w=; b=IQp78ylQGviAIFtqi7UhB2DI9n42op5vBaR06C8NR9z+DMXbA+zRyAuDX5vzZfyWsTIOFc kS7ySG5+AB0oGdCw== From: "tip-bot2 for Randy Dunlap" Sender: tip-bot2@linutronix.de Reply-to: linux-kernel@vger.kernel.org To: linux-tip-commits@vger.kernel.org Subject: [tip: smp/core] smp: Add missing kernel-doc comments Cc: Randy Dunlap , Thomas Gleixner , x86@kernel.org, linux-kernel@vger.kernel.org In-Reply-To: <20260310061726.1153764-1-rdunlap@infradead.org> References: <20260310061726.1153764-1-rdunlap@infradead.org> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Message-ID: <177452999549.1647592.8807025246353664259.tip-bot2@tip-bot2> Robot-ID: Robot-Unsubscribe: Contact to get blacklisted from these emails Precedence: bulk Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable The following commit has been merged into the smp/core branch of tip: Commit-ID: cc5623947f3d86687c39771fcbea641907966d5c Gitweb: https://git.kernel.org/tip/cc5623947f3d86687c39771fcbea64190= 7966d5c Author: Randy Dunlap AuthorDate: Mon, 09 Mar 2026 23:17:26 -07:00 Committer: Thomas Gleixner CommitterDate: Wed, 25 Mar 2026 20:11:29 +01:00 smp: Add missing kernel-doc comments 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) - remove "Returns" from smp_call_function() since it doesn't return a value Signed-off-by: Randy Dunlap Signed-off-by: Thomas Gleixner Link: https://patch.msgid.link/20260310061726.1153764-1-rdunlap@infradead.o= rg --- include/linux/smp.h | 38 +++++++++++++++++++++----------------- kernel/smp.c | 38 +++++++++++++++++++++++++------------- 2 files changed, 46 insertions(+), 30 deletions(-) diff --git a/include/linux/smp.h b/include/linux/smp.h index 1ebd880..6925d15 100644 --- a/include/linux/smp.h +++ b/include/linux/smp.h @@ -73,7 +73,7 @@ static inline void on_each_cpu(smp_call_func_t func, void= *info, int wait) } =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 =20 diff --git a/kernel/smp.c b/kernel/smp.c index f349960..b179424 100644 --- a/kernel/smp.c +++ b/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,18 +739,18 @@ 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). - * * Selection preference: * 1) current cpu if in @mask * 2) nearest cpu in @mask, based on NUMA topology + * + * Returns: %0 on success, else a negative status code (if no cpus were on= line). */ int smp_call_function_any(const struct cpumask *mask, smp_call_func_t func, void *info, int wait) @@ -880,7 +881,7 @@ static void smp_call_function_many_cond(const struct cp= umask *mask, } =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,14 +903,12 @@ void smp_call_function_many(const struct cpumask *mas= k, 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 * on other CPUs. * - * Returns 0. - * * If @wait is true, then returns once @func has returned; otherwise * it returns just before the target cpu calls @func. * @@ -1009,8 +1008,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 +1023,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 +1095,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 +1145,18 @@ static void smp_call_on_cpu_callback(struct work_str= uct *work) 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 {