container_of: Document container_of() is not to be used in new code

There is a warning in the kerneldoc documentation of container_of() that
constness of its ptr argument is lost. While this is a valid 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>
Link: https://lore.kernel.org/r/20250520103437.468691-1-sakari.ailus@linux.intel.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

diff --git a/include/linux/container_of.h b/include/linux/container_of.h
index 713890c867bea78804defe1a015e3c362f40f85d..1f6ebf27d962ff01831989cd7744d3cb12c3d37c 100644 (file)
--- a/include/linux/container_of.h
+++ b/include/linux/container_of.h
@@ -14,6 +14,7 @@
  * @member:    the name of the member within the struct.
  *
  * 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() instead of container_of() in new code.
  */
 #define container_of_const(ptr, type, member)                          \
        _Generic(ptr,                                                   \