Skip to contentSkip to conversation

Reference kernel-doc for container_of

PATCH New [email protected] 1 participant 1 message Aug 26, 2023

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Reference kernel-doc for container_of

From: René Nyffenegger <[email protected]>

The file include/linux/container_of.h contained kernel-doc but was not referenced in any .rst file. In addition, the file Documentation/core-api/kobject.rst wrongly located the definition of the macro container_of in linux/kernel.h while in reality it is defined in linux/container_of.h

This patch adds a new .rst file that includes the kernel-doc of container_of.h and rectifies the wrong reference of the header file.

---
 Documentation/core-api/container_of.rst | 64 +++++++++++++++++++++++++
 Documentation/core-api/index.rst        |  1 +
 Documentation/core-api/kobject.rst      | 58 +++++++++++-----------
 3 files changed, 93 insertions(+), 30 deletions(-)
 create mode 100644 Documentation/core-api/container_of.rst
Documentation/core-api/container_of.rst new file +64 -0
new file mode 100644
index 000000000000..f063d3f9e536
@@ -0,0 +1,64 @@
+=====================================================================================
+Given a pointer to a member of a struct, returning a pointer to the containing struct
+=====================================================================================
+
+.. _container_of:
+
+Overview
+========
+
+The two macros ``container_of`` and ``container_of_const``, defined in ``<include/linux/container_of.h>``, return a pointer to the ``struct`` (i. e. the *container*) from a pointer to a member of this ``struct``.
+
+These macros might be used when :ref:`embedding kobjects<embedding_kobjects>`, but see also :ref:`usage<container_of_usage>`.
+
+
+.. kernel-doc:: include/linux/container_of.h
+
+Usage
+=====
+
+.. _container_of_usage:
+
+The following simple code demonstrates the usage of ``container_of``
+
+.. code-block:: c
+
+ struct inner_struct
+ {
+ 	int abc;
+ 	int def;
+ }
+ 
+ struct container_struct
+ {
+ 	struct inner_struct inner;
+ 	char               *member_xyz;
+ 	int                 member_val;
+ };
+ 
+ static void f(struct inner_struct *inr)
+ {
+ 	struct container_struct *cont;
+ 
+ 	cont = container_of(inr, struct container_struct, inner);
+ 
+        /* Use cont and its members */
+ }
+ 
+ static void g(char** member)
+ {
+ 	struct container_struct *cont;
+ 
+ 	cont = container_of(member, struct container_struct, member_xyz);
+        /* Use cont and its members */
+ }
+ 
+ void somewhere()
+ {
+ 	struct container_struct cont;
+ 
+ 	/* Initialize cont */
+ 
+ 	f(& cont.inner      );
+ 	g(& cont.member_xyz );
+ }
Documentation/core-api/index.rst +1 -0
index 7a3a08d81f11..595af47d0d5f 100644
@@ -37,6 +37,7 @@ Library functionality that is used throughout the kernel.
    kref
    assoc_array
    xarray
+   container_of
    maple_tree
    idr
    circular-buffers
Documentation/core-api/kobject.rst +28 -30

84 lines not on this page · raw message

Signature · 1 line
2.30.2