diff options
Diffstat (limited to 'Documentation/kobject.txt')
-rw-r--r-- | Documentation/kobject.txt | 60 |
1 files changed, 40 insertions, 20 deletions
diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt index bdb13817e1e9..3ab2472509cb 100644 --- a/Documentation/kobject.txt +++ b/Documentation/kobject.txt | |||
@@ -59,37 +59,56 @@ nice to have in other objects. The C language does not allow for the | |||
59 | direct expression of inheritance, so other techniques - such as structure | 59 | direct expression of inheritance, so other techniques - such as structure |
60 | embedding - must be used. | 60 | embedding - must be used. |
61 | 61 | ||
62 | So, for example, the UIO code has a structure that defines the memory | 62 | (As an aside, for those familiar with the kernel linked list implementation, |
63 | region associated with a uio device: | 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 | struct kobject kobj; | 71 | struct kobject kobj; |
67 | unsigned long addr; | 72 | struct uio_mem *mem; |
68 | unsigned long size; | 73 | }; |
69 | int memtype; | ||
70 | void __iomem *internal_addr; | ||
71 | }; | ||
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 | just a matter of using the kobj member. Code that works with kobjects will | 76 | just a matter of using the kobj member. Code that works with kobjects will |
75 | often have the opposite problem, however: given a struct kobject pointer, | 77 | often have the opposite problem, however: given a struct kobject pointer, |
76 | what is the pointer to the containing structure? You must avoid tricks | 78 | what is the pointer to the containing structure? You must avoid tricks |
77 | (such as assuming that the kobject is at the beginning of the structure) | 79 | (such as assuming that the kobject is at the beginning of the structure) |
78 | and, instead, use the container_of() macro, found in <linux/kernel.h>: | 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) |
83 | |||
84 | where: | ||
85 | |||
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. | ||
89 | |||
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 | }; | ||
81 | 105 | ||
82 | where pointer is the pointer to the embedded kobject, type is the type of | 106 | #define to_map(map) container_of(map, struct uio_map, kobj) |
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: | ||
88 | 107 | ||
89 | struct uio_mem *u_mem = container_of(kp, struct uio_mem, kobj); | 108 | where the macro argument "map" is a pointer to the struct kobject in |
109 | question. That macro is subsequently invoked with: | ||
90 | 110 | ||
91 | Programmers often define a simple macro for "back-casting" kobject pointers | 111 | struct uio_map *map = to_map(kobj); |
92 | to the containing type. | ||
93 | 112 | ||
94 | 113 | ||
95 | Initialization of kobjects | 114 | Initialization of kobjects |
@@ -387,4 +406,5 @@ called, and the objects in the former circle release each other. | |||
387 | Example code to copy from | 406 | Example code to copy from |
388 | 407 | ||
389 | For a more complete example of using ksets and kobjects properly, see the | 408 | For a more complete example of using ksets and kobjects properly, see the |
390 | sample/kobject/kset-example.c code. | 409 | example programs samples/kobject/{kobject-example.c,kset-example.c}, |
410 | which will be built as loadable modules if you select CONFIG_SAMPLE_KOBJECT. | ||