Re: [PATCH] lock: Add doc comments for spin_lock_irq()

[Daroc Alden <daroc@lwn.net>]

On Fri, 10 Oct 2025 23:15:50 -0400
Waiman Long <llong@redhat.com> wrote:

> On 10/10/25 5:53 PM, Daroc Alden wrote:
> > The commonly used spin_lock_irq(), spin_lock_irqsave(),
> > spin_unlock_irq(), and spin_unlock_irqrestore() functions do not
> > currently have any documentation; this commit adds kerneldoc
> > comments to these four functions describing when their behavior and
> > when they are appropriate to use.
> >
> > Signed-off-by: Daroc Alden <daroc@lwn.net>  
> 
> This patch looks fine. Just wonder why just 
> spin_lock_irq()/spin_lock_irqsave() and not
> spin_lock()/spin_lock_bh() as these functions also don't have
> kerneldoc comments. Also spin_lock_irqsave() is a macro and not
> actually a function, maybe we should mention that in the comment.
> 

Because I had to research spin_lock_irq()/spin_lock_irqsave() for a
recent article, and therefore felt confident that I understood how they
behaved and what should go in the doc comment.

If you — as a more experienced kernel person — can describe how/why the
_bh() variants are used, I'm happy to add doc comments for them as
well. My current understanding is that they interact with whatever is
left of the "big kernel lock". Is that right?

-- 
Daroc Alden (they/them)
Editor, LWN | https://lwn.net