linux-kernel - Re: [PATCH] lock: Add doc comments for spin_lock

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20251011142804.29da9591@azalea>
Date: Sat, 11 Oct 2025 14:28:04 -0400
From: Daroc Alden <daroc@....net>
To: Waiman Long <llong@...hat.com>
Cc: corbet@....net, Peter Zijlstra <peterz@...radead.org>, Ingo Molnar
 <mingo@...hat.com>, Will Deacon <will@...nel.org>, Boqun Feng
 <boqun.feng@...il.com>, "open list:LOCKING PRIMITIVES"
 <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH] lock: Add doc comments for spin_lock_irq()

On Fri, 10 Oct 2025 23:15:50 -0400
Waiman Long <llong@...hat.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@....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