Re: [PATCH v4 4/5] mm: rename zone->lock to zone->_lock

[Vlastimil Babka (SUSE)]

On 3/5/26 19:59, Dmitry Ilvokhin wrote:
> On Thu, Mar 05, 2026 at 06:16:26PM +0000, Dmitry Ilvokhin wrote:
>> On Thu, Mar 05, 2026 at 10:27:07AM +0100, Vlastimil Babka (SUSE) wrote:
>> > On 3/4/26 16:13, SeongJae Park wrote:
>> > > On Wed, 4 Mar 2026 13:01:45 +0000 Dmitry Ilvokhin <d@xxxxxxxxxxxx> wrote:
>> > > 
>> > >> On Tue, Mar 03, 2026 at 05:50:34PM -0800, SeongJae Park wrote:
>> > >> > On Tue, 3 Mar 2026 14:25:55 +0000 Dmitry Ilvokhin <d@xxxxxxxxxxxx> wrote:
>> > >> > 
>> > >> > > On Mon, Mar 02, 2026 at 02:37:43PM -0800, Andrew Morton wrote:
>> > >> > > > On Mon, 2 Mar 2026 15:10:03 +0100 "Vlastimil Babka (SUSE)" <vbabka@xxxxxxxxxx> wrote:
>> > >> > > > 
>> > >> > > > > On 2/27/26 17:00, Dmitry Ilvokhin wrote:
>> > >> > > > > > This intentionally breaks direct users of zone->lock at compile time so
>> > >> > > > > > all call sites are converted to the zone lock wrappers. Without the
>> > >> > > > > > rename, present and future out-of-tree code could continue using
>> > >> > > > > > spin_lock(&zone->lock) and bypass the wrappers and tracing
>> > >> > > > > > infrastructure.
>> > >> > > > > > 
>> > >> > > > > > No functional change intended.
>> > >> > > > > > 
>> > >> > > > > > Suggested-by: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx>
>> > >> > > > > > Signed-off-by: Dmitry Ilvokhin <d@xxxxxxxxxxxx>
>> > >> > > > > > Acked-by: Shakeel Butt <shakeel.butt@xxxxxxxxx>
>> > >> > > > > > Acked-by: SeongJae Park <sj@xxxxxxxxxx>
>> > >> > > > > 
>> > >> > > > > I see some more instances of 'zone->lock' in comments in
>> > >> > > > > include/linux/mmzone.h and under Documentation/ but otherwise LGTM.
>> > >> > > > > 
>> > >> > > > 
>> > >> > > > I fixed (most of) that in the previous version but my fix was lost.
>> > >> > > 
>> > >> > > Thanks for the fixups, Andrew.
>> > >> > > 
>> > >> > > I still see a few 'zone->lock' references in Documentation remain on
>> > >> > > mm-new. This patch cleans them up, as noted by Vlastimil.
>> > >> > > 
>> > >> > > I'm happy to adjust this patch if anything else needs attention.
>> > >> > > 
>> > >> > > From 9142d5a8b60038fa424a6033253960682e5a51f4 Mon Sep 17 00:00:00 2001
>> > >> > > From: Dmitry Ilvokhin <d@xxxxxxxxxxxx>
>> > >> > > Date: Tue, 3 Mar 2026 06:13:13 -0800
>> > >> > > Subject: [PATCH] mm: fix remaining zone->lock references
>> > >> > > 
>> > >> > > Signed-off-by: Dmitry Ilvokhin <d@xxxxxxxxxxxx>
>> > >> > > ---
>> > >> > >  Documentation/mm/physical_memory.rst | 4 ++--
>> > >> > >  Documentation/trace/events-kmem.rst  | 8 ++++----
>> > >> > >  2 files changed, 6 insertions(+), 6 deletions(-)
>> > >> > > 
>> > >> > > diff --git a/Documentation/mm/physical_memory.rst b/Documentation/mm/physical_memory.rst
>> > >> > > index b76183545e5b..e344f93515b6 100644
>> > >> > > --- a/Documentation/mm/physical_memory.rst
>> > >> > > +++ b/Documentation/mm/physical_memory.rst
>> > >> > > @@ -500,11 +500,11 @@ General
>> > >> > >  ``nr_isolate_pageblock``
>> > >> > >    Number of isolated pageblocks. It is used to solve incorrect freepage counting
>> > >> > >    problem due to racy retrieving migratetype of pageblock. Protected by
>> > >> > > -  ``zone->lock``. Defined only when ``CONFIG_MEMORY_ISOLATION`` is enabled.
>> > >> > > +  ``zone_lock``. Defined only when ``CONFIG_MEMORY_ISOLATION`` is enabled.
>> > >> > 
>> > >> > Dmitry's original patch [1] was doing 's/zone->lock/zone->_lock/', which aligns
>> > >> > to my expectation.  But this patch is doing 's/zone->lock/zone_lock/'.  Same
>> > >> > for the rest of this patch.
>> > >> > 
>> > >> > I was initially thinking this is just a mistake, but I also found Andrew is
>> > >> > doing same change [2], so I'm bit confused.  Is this an intentional change?
>> > >> > 
>> > >> > [1] https://lore.kernel.org/d61500c5784c64e971f4d328c57639303c475f81.1772206930.git.d@xxxxxxxxxxxx
>> > >> > [2] https://lore.kernel.org/20260302143743.220eed4feb36d7572fe726cc@xxxxxxxxxxxxxxxxxxxx
>> > >> > 
>> > >> 
>> > >> Good catch, thanks for pointing this out, SJ.
>> > >> 
>> > >> Originally the mechanical rename was indeed zone->lock -> zone->_lock.
>> > >> However, in Documentation I intentionally switched references to
>> > >> zone_lock instead of zone->_lock. The reasoning is that _lock is now an
>> > >> internal implementation detail, and direct access is discouraged. The
>> > >> intended interface is via the zone_lock_*() / zone_unlock_*() wrappers,
>> > >> so referencing zone_lock in documentation felt more appropriate than
>> > >> mentioning the private struct field (zone->_lock).
>> > > 
>> > > Thank you for this nice and kind clarification, Dmitry!  I agree mentioning
>> > > zone_[un]lock_*() helpers instead of the hidden member (zone->_lock) can be
>> > > better.
>> > > 
>> > > But, I'm concerned if people like me might not aware the intention under
>> > > 'zone_lock'.  If there is a well-known convention that allows people to know it
>> > > is for 'zone_[un]lock_*()' helpers, making it more clear would be nice, in my
>> > > humble opinion.  If there is such a convention but I'm just missing it, please
>> > > ignore.  If I'm not, for eaxmaple,
>> > > 
>> > > "protected by ``zone->lock``" could be re-wrote to
>> > > "protected by ``zone_[un]lock_*()`` locking helpers" or,
>> > > "protected by zone lock helper functions (``zone_[un]lock_*()``)" ?
>> > > 
>> > >> 
>> > >> That said, I agree this creates inconsistency with the mechanical
>> > >> rename, and I'm happy to adjust either way: either consistently refer
>> > >> to the wrapper API, or keep documentation aligned with zone->_lock.
>> > >> 
>> > >> I slightly prefer referring to the wrapper API, but don't have a strong
>> > >> preference as long as we're consistent.
>> > > 
>> > > I also think both approaches are good.  But for the wrapper approach, I think
>> > > giving more contexts rather than just ``zone_lock`` to readers would be nice.
>> > 
>> > Grep tells me that we also have comments mentioning simply "zone lock", btw.
>> > And it's also a term used often in informal conversations. Maybe we could
>> > just standardize on that in comments/documentations as it's easier to read.
>> > Discovering that the field is called _lock and that wrappers should be used,
>> > is hopefully not that difficult.
>> 
>> Thanks for the suggestion, Vlastimil. That sounds reasonable to me as
>> well. I'll update the comments and documentation to consistently use
>> "zone lock".
> 
> Following the suggestion from SJ and Vlastimil, I prepared fixup to
> standardize documentation and comments on the term "zone lock".
> 
> The patch is based on top of the current mm-new.
> 
> Andrew, please let me know if you would prefer a respin of the series
> instead.
> 
> From 267cda3e0e160f97b346009bc48819bfeed92e52 Mon Sep 17 00:00:00 2001
> From: Dmitry Ilvokhin <d@xxxxxxxxxxxx>
> Date: Thu, 5 Mar 2026 10:36:17 -0800
> Subject: [PATCH] mm: documentation: standardize on "zone lock" terminology
> 
> During review of the zone lock tracing series it was suggested to
> standardize documentation and comments on the term "zone lock"
> instead of using zone_lock or referring to the internal field
> zone->_lock.
> 
> Update references accordingly.
> 
> Signed-off-by: Dmitry Ilvokhin <d@xxxxxxxxxxxx>

Acked-by: Vlastimil Babka (SUSE) <vbabka@xxxxxxxxxx>

Thanks!