The documentation of that function promises to never sleep.
However on PREEMPT_RT a spinlock_t might in fact sleep.

Reword the documentation so users can predict its behavior better.

mempool could also replace spinlock_t with raw_spinlock_t which doesn't
sleep even on PREEMPT_RT but that would take away the improved
preemptibility of sleeping locks.

Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de>
---
 mm/mempool.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/mm/mempool.c b/mm/mempool.c
index 1c38e873e546fadcc594f041874eb42774e3df16..cceb09b75ebe35f263a5fb95ff6d400221ecbdd5 100644
--- a/mm/mempool.c
+++ b/mm/mempool.c
@@ -461,8 +461,8 @@ EXPORT_SYMBOL(mempool_alloc_noprof);
  *             mempool_create().
  *
  * This function is similar to mempool_alloc, but it only attempts allocating
- * an element from the preallocated elements. It does not sleep and immediately
- * returns if no preallocated elements are available.
+ * an element from the preallocated elements. It only takes a single spinlock_t
+ * and immediately returns if no preallocated elements are available.
  *
  * Return: pointer to the allocated element or %NULL if no elements are
  * available.

---
base-commit: 3a8660878839faadb4f1a6dd72c3179c1df56787
change-id: 20251014-mempool-doc-625dd4996110

Best regards,
-- 
Thomas Weißschuh <thomas.weissschuh@linutronix.de>

On Tue, Oct 14, 2025 at 02:17:23PM +0200, Thomas Weißschuh wrote:
> The documentation of that function promises to never sleep.
> However on PREEMPT_RT a spinlock_t might in fact sleep.
> 
> Reword the documentation so users can predict its behavior better.
> 
> mempool could also replace spinlock_t with raw_spinlock_t which doesn't
> sleep even on PREEMPT_RT but that would take away the improved
> preemptibility of sleeping locks.
> 
> Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de>
> ---
>  mm/mempool.c | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/mm/mempool.c b/mm/mempool.c
> index 1c38e873e546fadcc594f041874eb42774e3df16..cceb09b75ebe35f263a5fb95ff6d400221ecbdd5 100644
> --- a/mm/mempool.c
> +++ b/mm/mempool.c
> @@ -461,8 +461,8 @@ EXPORT_SYMBOL(mempool_alloc_noprof);
>   *             mempool_create().
>   *
>   * This function is similar to mempool_alloc, but it only attempts allocating
> - * an element from the preallocated elements. It does not sleep and immediately
> - * returns if no preallocated elements are available.
> + * an element from the preallocated elements. It only takes a single spinlock_t

Might it make more sense to say "It may sleep" instead of "takes a
single spinlock_t"?

I feel like the fact that we take a spinlock isn't the important part
here (especially because we always drop it before returning).

> + * and immediately returns if no preallocated elements are available.
>   *
>   * Return: pointer to the allocated element or %NULL if no elements are
>   * available.
> 
> ---
> base-commit: 3a8660878839faadb4f1a6dd72c3179c1df56787
> change-id: 20251014-mempool-doc-625dd4996110
> 
> Best regards,
> -- 
> Thomas Weißschuh <thomas.weissschuh@linutronix.de>
> 

On 2025-10-15 11:52:24 [-0700], Vishal Moola (Oracle) wrote:
> > --- a/mm/mempool.c
> > +++ b/mm/mempool.c
> > @@ -461,8 +461,8 @@ EXPORT_SYMBOL(mempool_alloc_noprof);
> >   *             mempool_create().
> >   *
> >   * This function is similar to mempool_alloc, but it only attempts allocating
> > - * an element from the preallocated elements. It does not sleep and immediately
> > - * returns if no preallocated elements are available.
> > + * an element from the preallocated elements. It only takes a single spinlock_t
> 
> Might it make more sense to say "It may sleep" instead of "takes a
> single spinlock_t"?

May sleep usually refers to something that can not be used in an
interrupt handler.

> I feel like the fact that we take a spinlock isn't the important part
> here (especially because we always drop it before returning).
It actually is. A spinlock_t can not be acquired in hardirq context or
when interrupts are explicitly disabled via local_irq_disable().
Therefore you should use the function in a local_irq_disable() section.

Sebastian

On Wed, Oct 15, 2025 at 09:27:17PM +0200, Sebastian Andrzej Siewior wrote:
> On 2025-10-15 11:52:24 [-0700], Vishal Moola (Oracle) wrote:
> > > --- a/mm/mempool.c
> > > +++ b/mm/mempool.c
> > > @@ -461,8 +461,8 @@ EXPORT_SYMBOL(mempool_alloc_noprof);
> > >   *             mempool_create().
> > >   *
> > >   * This function is similar to mempool_alloc, but it only attempts allocating
> > > - * an element from the preallocated elements. It does not sleep and immediately
> > > - * returns if no preallocated elements are available.
> > > + * an element from the preallocated elements. It only takes a single spinlock_t
> > 
> > Might it make more sense to say "It may sleep" instead of "takes a
> > single spinlock_t"?
> 
> May sleep usually refers to something that can not be used in an
> interrupt handler.

Gotcha. 

> > I feel like the fact that we take a spinlock isn't the important part
> > here (especially because we always drop it before returning).
> It actually is. A spinlock_t can not be acquired in hardirq context or
> when interrupts are explicitly disabled via local_irq_disable().
> Therefore you should use the function in a local_irq_disable() section.

As someone not too familiar with how the locking intertwines with the
scheduler contexts, seeing something like that makes much more sense
to me than seeing "it only takes a single spinlock_t."

On 2025-10-15 15:46:13 [-0700], Vishal Moola (Oracle) wrote:
> On Wed, Oct 15, 2025 at 09:27:17PM +0200, Sebastian Andrzej Siewior wrote:
> > On 2025-10-15 11:52:24 [-0700], Vishal Moola (Oracle) wrote:
> > > > --- a/mm/mempool.c
> > > > +++ b/mm/mempool.c
> > > > @@ -461,8 +461,8 @@ EXPORT_SYMBOL(mempool_alloc_noprof);
> > > >   *             mempool_create().
> > > >   *
> > > >   * This function is similar to mempool_alloc, but it only attempts allocating
> > > > - * an element from the preallocated elements. It does not sleep and immediately
> > > > - * returns if no preallocated elements are available.
> > > > + * an element from the preallocated elements. It only takes a single spinlock_t
> > > 
> > > Might it make more sense to say "It may sleep" instead of "takes a
> > > single spinlock_t"?
> > 
> > May sleep usually refers to something that can not be used in an
> > interrupt handler.
> 
> Gotcha. 
> 
> > > I feel like the fact that we take a spinlock isn't the important part
> > > here (especially because we always drop it before returning).
> > It actually is. A spinlock_t can not be acquired in hardirq context or
> > when interrupts are explicitly disabled via local_irq_disable().
> > Therefore you should use the function in a local_irq_disable() section.
> 
> As someone not too familiar with how the locking intertwines with the
> scheduler contexts, seeing something like that makes much more sense
> to me than seeing "it only takes a single spinlock_t."

I am not too happy about this wording but I don't have a better idea
either. However "may sleep" is too broad. The spinlock_t is at the very
least documented in
	Documentation/locking/locktypes.rst

Sebastian