Recently linux introduced the ability to mark structure members as
__private and access them via ACCESS_PRIVATE(). This mechanism ensures
that internal implementation details are only accessible by the owning
subsystem, enforcing better encapsulation.

However, struct list_head is frequently used as an internal linkage
mechanism within these private sections. The standard macros in
<linux/list.h> (such as list_entry and list_for_each_entry) do not
support ACCESS_PRIVATE() natively. Consequently, subsystems using
private lists are forced to implement ad-hoc workarounds, verbose
casting, or local iterator macros to avoid compiler warnings and access
violations.

This series introduces <linux/list_private.h>, which provides a set of
primitives identical in function to those in <linux/list.h>, but
designed specifically for cases where the embedded struct list_head is a
private member.

The series is structured as follows:
Core Implementation: Adds the list_private.h header with support for
entry retrieval and iteration (forward, reverse, safe, etc.).

Testing: Adds a KUnit test suite to verify that the macros compile
correctly and handle pointer offsets/qualifiers as expected.

Adoption: Updates the liveupdate subsystem to use the new generic API,
replacing its local luo_list_for_each_private implementation.

Pasha Tatashin (3):
  list: add primitives for private list manipulations
  list: add kunit test for private list primitives
  liveupdate: luo_file: Use private list

 Documentation/core-api/list.rst  |   9 ++
 include/linux/list_private.h     | 256 +++++++++++++++++++++++++++++++
 kernel/liveupdate/luo_file.c     |   7 +-
 kernel/liveupdate/luo_internal.h |   7 -
 lib/Kconfig.debug                |  14 ++
 lib/tests/Makefile               |   1 +
 lib/tests/list-private-test.c    |  76 +++++++++
 7 files changed, 360 insertions(+), 10 deletions(-)
 create mode 100644 include/linux/list_private.h
 create mode 100644 lib/tests/list-private-test.c


base-commit: 663d0d1af3faefe673cabf4b6b077149a87ad71f
-- 
2.52.0.487.g5c8c507ade-goog

(added Dan Carpenter)

On Wed, Nov 26, 2025 at 01:57:22PM -0500, Pasha Tatashin wrote:
> Recently linux introduced the ability to mark structure members as
> __private and access them via ACCESS_PRIVATE(). This mechanism ensures
> that internal implementation details are only accessible by the owning
> subsystem, enforcing better encapsulation.
> 
> However, struct list_head is frequently used as an internal linkage
> mechanism within these private sections. The standard macros in
> <linux/list.h> (such as list_entry and list_for_each_entry) do not
> support ACCESS_PRIVATE() natively. Consequently, subsystems using
> private lists are forced to implement ad-hoc workarounds, verbose
> casting, or local iterator macros to avoid compiler warnings and access
> violations.
> 
> This series introduces <linux/list_private.h>, which provides a set of
> primitives identical in function to those in <linux/list.h>, but
> designed specifically for cases where the embedded struct list_head is a
> private member.
> 
> The series is structured as follows:
> Core Implementation: Adds the list_private.h header with support for
> entry retrieval and iteration (forward, reverse, safe, etc.).
> 
> Testing: Adds a KUnit test suite to verify that the macros compile
> correctly and handle pointer offsets/qualifiers as expected.
> 
> Adoption: Updates the liveupdate subsystem to use the new generic API,
> replacing its local luo_list_for_each_private implementation.
> 
> Pasha Tatashin (3):
>   list: add primitives for private list manipulations
>   list: add kunit test for private list primitives
>   liveupdate: luo_file: Use private list
> 
>  Documentation/core-api/list.rst  |   9 ++
>  include/linux/list_private.h     | 256 +++++++++++++++++++++++++++++++
>  kernel/liveupdate/luo_file.c     |   7 +-
>  kernel/liveupdate/luo_internal.h |   7 -
>  lib/Kconfig.debug                |  14 ++
>  lib/tests/Makefile               |   1 +
>  lib/tests/list-private-test.c    |  76 +++++++++
>  7 files changed, 360 insertions(+), 10 deletions(-)
>  create mode 100644 include/linux/list_private.h
>  create mode 100644 lib/tests/list-private-test.c
> 
> 
> base-commit: 663d0d1af3faefe673cabf4b6b077149a87ad71f
> -- 
> 2.52.0.487.g5c8c507ade-goog
> 

-- 
Sincerely yours,
Mike.

On Wed, 26 Nov 2025 13:57:22 -0500 Pasha Tatashin <pasha.tatashin@soleen.com> wrote:

> Recently

Well, 2015, in ad315455d396, it seems.

> linux introduced the ability to mark structure members as
> __private and access them via ACCESS_PRIVATE(). This mechanism ensures
> that internal implementation details are only accessible by the owning
> subsystem, enforcing better encapsulation.

Didn't know about this.  It's a thing which requires running sparse
(which is fine, people run sparse).  It isn't used much at all.

> However, struct list_head is frequently used as an internal linkage
> mechanism within these private sections. The standard macros in
> <linux/list.h> (such as list_entry and list_for_each_entry) do not
> support ACCESS_PRIVATE() natively. Consequently, subsystems using
> private lists are forced to implement ad-hoc workarounds, verbose
> casting, or local iterator macros to avoid compiler warnings and access
> violations.
> 
> This series introduces <linux/list_private.h>, which provides a set of
> primitives identical in function to those in <linux/list.h>, but
> designed specifically for cases where the embedded struct list_head is a
> private member.
> 
> The series is structured as follows:
> Core Implementation: Adds the list_private.h header with support for
> entry retrieval and iteration (forward, reverse, safe, etc.).
> 
> Testing: Adds a KUnit test suite to verify that the macros compile
> correctly and handle pointer offsets/qualifiers as expected.
> 
> Adoption: Updates the liveupdate subsystem to use the new generic API,
> replacing its local luo_list_for_each_private implementation.

Fair enough.  Let's push this into the next -rc cycle, OK?

On Wed, Nov 26, 2025 at 2:19 PM Andrew Morton <akpm@linux-foundation.org> wrote:
>
> On Wed, 26 Nov 2025 13:57:22 -0500 Pasha Tatashin <pasha.tatashin@soleen.com> wrote:
>
> > Recently
>
> Well, 2015, in ad315455d396, it seems.
>
> > linux introduced the ability to mark structure members as
> > __private and access them via ACCESS_PRIVATE(). This mechanism ensures
> > that internal implementation details are only accessible by the owning
> > subsystem, enforcing better encapsulation.
>
> Didn't know about this.  It's a thing which requires running sparse
> (which is fine, people run sparse).  It isn't used much at all.
>
> > However, struct list_head is frequently used as an internal linkage
> > mechanism within these private sections. The standard macros in
> > <linux/list.h> (such as list_entry and list_for_each_entry) do not
> > support ACCESS_PRIVATE() natively. Consequently, subsystems using
> > private lists are forced to implement ad-hoc workarounds, verbose
> > casting, or local iterator macros to avoid compiler warnings and access
> > violations.
> >
> > This series introduces <linux/list_private.h>, which provides a set of
> > primitives identical in function to those in <linux/list.h>, but
> > designed specifically for cases where the embedded struct list_head is a
> > private member.
> >
> > The series is structured as follows:
> > Core Implementation: Adds the list_private.h header with support for
> > entry retrieval and iteration (forward, reverse, safe, etc.).
> >
> > Testing: Adds a KUnit test suite to verify that the macros compile
> > correctly and handle pointer offsets/qualifiers as expected.
> >
> > Adoption: Updates the liveupdate subsystem to use the new generic API,
> > replacing its local luo_list_for_each_private implementation.
>
> Fair enough.  Let's push this into the next -rc cycle, OK?

Yes, this works.

Thank you,
Pasha