[PATCH 1/1] container_of: Document container_of() is not to be used in new code

[Sakari Ailus <sakari.ailus@linux.intel.com>]

There is a warning in the kerneldoc documentation of container_of() that
constness of its ptr argument is lost. While this is a faible suggestion
container_of_const() should be used instead, the vast majority of new code
still uses container_of():

$ git diff v6.13 v6.14|grep container_of\(|wc -l
646
$ git diff v6.13 v6.14|grep container_of_const|wc -l
9

Make an explicit recommendation to use container_of_const().

Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
Hi Greg, Andy,

I guess we generally agree the additional constness check in
container_of_const() is useful, but adding the same check to
container_of() generates warnings -- there are some errors, too -- such as
this one currently:

In file included from /home/sailus/src/linux/include/linux/bcma/bcma.h:14,
                 from /home/sailus/src/linux/arch/x86/kernel/early-quirks.c:17:
/home/sailus/src/linux/include/linux/ssb/ssb.h: In function ‘dev_to_ssb_dev’:
/home/sailus/src/linux/include/linux/ssb/ssb.h:291:14: warning: assignment discards ‘const’ qualifier from pointer target type [-Wdiscarded-qualifiers]
  291 |         wrap = container_of(dev, struct __ssb_dev_wrapper, dev);
      |              ^

As noted above, 646 new missing constness checks were introduced through
container_of() macro use during the 6.14 cycle alone. Most of these are
likely harmless, but with so many new users some are bound to be ignoring
constness.

Once the warnings from bad container_of() use are worked out in a way or
another, the constness check could be added to the container_of() macro
and the current container_of_const() be dropped altogether.

If this patch is accepted, I'll see how to add a warning on container_of()
to checkpatch.pl.

- Sakari

 include/linux/container_of.h | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/include/linux/container_of.h b/include/linux/container_of.h
index 713890c867be..40139b52036a 100644
--- a/include/linux/container_of.h
+++ b/include/linux/container_of.h
@@ -13,7 +13,8 @@
  * @type:	the type of the container struct this is embedded in.
  * @member:	the name of the member within the struct.
  *
- * WARNING: any const qualifier of @ptr is lost.
+ * WARNING: any const qualifier of @ptr is lost. DO NOT USE container_of() IN
+ * NEW CODE.
  */
 #define container_of(ptr, type, member) ({				\
 	void *__mptr = (void *)(ptr);					\
@@ -28,6 +29,8 @@
  * @ptr:		the pointer to the member
  * @type:		the type of the container struct this is embedded in.
  * @member:		the name of the member within the struct.
+ *
+ * Always prefer container_of_const() over container_of() in new code.
  */
 #define container_of_const(ptr, type, member)				\
 	_Generic(ptr,							\
-- 
2.39.5