Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
kernel
os
linux
kobject: documentation: Fix erroneous example in kobject doc.
Replace uio_mem example for kobjects with uio_map, since the uio_mem
struct no longer contains a kobject.
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
authored by Robert P. J. Day and committed by Greg Kroah-Hartman 462bd295 e59817bf
+38
-19
Documentation/kobject.txt
+38
-19
Documentation/kobject.txt
···
59
59
direct expression of inheritance, so other techniques - such as structure
60
60
embedding - must be used.
61
61
62
-
So, for example, the UIO code has a structure that defines the memory
63
-
region associated with a uio device:
62
+
(As an aside, for those familiar with the kernel linked list implementation,
63
+
this is analogous as to how "list_head" structs are rarely useful on
64
+
their own, but are invariably found embedded in the larger objects of
65
+
interest.)
64
66
65
-
struct uio_mem {
67
+
So, for example, the UIO code in drivers/uio/uio.c has a structure that
68
+
defines the memory region associated with a uio device:
69
+
70
+
struct uio_map {
66
71
struct kobject kobj;
67
-
unsigned long addr;
68
-
unsigned long size;
69
-
int memtype;
70
-
void __iomem *internal_addr;
71
-
};
72
+
struct uio_mem *mem;
73
+
};
72
74
73
-
If you have a struct uio_mem structure, finding its embedded kobject is
75
+
If you have a struct uio_map structure, finding its embedded kobject is
74
76
just a matter of using the kobj member. Code that works with kobjects will
75
77
often have the opposite problem, however: given a struct kobject pointer,
76
78
what is the pointer to the containing structure? You must avoid tricks
77
79
(such as assuming that the kobject is at the beginning of the structure)
78
80
and, instead, use the container_of() macro, found in <linux/kernel.h>:
79
81
80
-
container_of(pointer, type, member)
82
+
container_of(pointer, type, member)
81
83
82
-
where pointer is the pointer to the embedded kobject, type is the type of
83
-
the containing structure, and member is the name of the structure field to
84
-
which pointer points. The return value from container_of() is a pointer to
85
-
the given type. So, for example, a pointer "kp" to a struct kobject
86
-
embedded within a struct uio_mem could be converted to a pointer to the
87
-
containing uio_mem structure with:
84
+
where:
88
85
89
-
struct uio_mem *u_mem = container_of(kp, struct uio_mem, kobj);
86
+
* "pointer" is the pointer to the embedded kobject,
87
+
* "type" is the type of the containing structure, and
88
+
* "member" is the name of the structure field to which "pointer" points.
90
89
91
-
Programmers often define a simple macro for "back-casting" kobject pointers
92
-
to the containing type.
90
+
The return value from container_of() is a pointer to the corresponding
91
+
container type. So, for example, a pointer "kp" to a struct kobject
92
+
embedded *within* a struct uio_map could be converted to a pointer to the
93
+
*containing* uio_map structure with:
94
+
95
+
struct uio_map *u_map = container_of(kp, struct uio_map, kobj);
96
+
97
+
For convenience, programmers often define a simple macro for "back-casting"
98
+
kobject pointers to the containing type. Exactly this happens in the
99
+
earlier drivers/uio/uio.c, as you can see here:
100
+
101
+
struct uio_map {
102
+
struct kobject kobj;
103
+
struct uio_mem *mem;
104
+
};
105
+
106
+
#define to_map(map) container_of(map, struct uio_map, kobj)
107
+
108
+
where the macro argument "map" is a pointer to the struct kobject in
109
+
question. That macro is subsequently invoked with:
110
+
111
+
struct uio_map *map = to_map(kobj);
93
112
94
113
95
114
Initialization of kobjects