1 | // SPDX-License-Identifier: GPL-2.0 |
2 | /* |
3 | * kobject.h - generic kernel object infrastructure. |
4 | * |
5 | * Copyright (c) 2002-2003 Patrick Mochel |
6 | * Copyright (c) 2002-2003 Open Source Development Labs |
7 | * Copyright (c) 2006-2008 Greg Kroah-Hartman <greg@kroah.com> |
8 | * Copyright (c) 2006-2008 Novell Inc. |
9 | * |
10 | * Please read Documentation/core-api/kobject.rst before using the kobject |
11 | * interface, ESPECIALLY the parts about reference counts and object |
12 | * destructors. |
13 | */ |
14 | |
15 | #ifndef _KOBJECT_H_ |
16 | #define _KOBJECT_H_ |
17 | |
18 | #include <linux/types.h> |
19 | #include <linux/list.h> |
20 | #include <linux/sysfs.h> |
21 | #include <linux/compiler.h> |
22 | #include <linux/container_of.h> |
23 | #include <linux/spinlock.h> |
24 | #include <linux/kref.h> |
25 | #include <linux/kobject_ns.h> |
26 | #include <linux/wait.h> |
27 | #include <linux/atomic.h> |
28 | #include <linux/workqueue.h> |
29 | #include <linux/uidgid.h> |
30 | |
31 | #define UEVENT_HELPER_PATH_LEN 256 |
32 | #define UEVENT_NUM_ENVP 64 /* number of env pointers */ |
33 | #define UEVENT_BUFFER_SIZE 2048 /* buffer for the variables */ |
34 | |
35 | #ifdef CONFIG_UEVENT_HELPER |
36 | /* path to the userspace helper executed on an event */ |
37 | extern char uevent_helper[]; |
38 | #endif |
39 | |
40 | /* counter to tag the uevent, read only except for the kobject core */ |
41 | extern u64 uevent_seqnum; |
42 | |
43 | /* |
44 | * The actions here must match the index to the string array |
45 | * in lib/kobject_uevent.c |
46 | * |
47 | * Do not add new actions here without checking with the driver-core |
48 | * maintainers. Action strings are not meant to express subsystem |
49 | * or device specific properties. In most cases you want to send a |
50 | * kobject_uevent_env(kobj, KOBJ_CHANGE, env) with additional event |
51 | * specific variables added to the event environment. |
52 | */ |
53 | enum kobject_action { |
54 | KOBJ_ADD, |
55 | KOBJ_REMOVE, |
56 | KOBJ_CHANGE, |
57 | KOBJ_MOVE, |
58 | KOBJ_ONLINE, |
59 | KOBJ_OFFLINE, |
60 | KOBJ_BIND, |
61 | KOBJ_UNBIND, |
62 | }; |
63 | |
64 | struct kobject { |
65 | const char *name; |
66 | struct list_head entry; |
67 | struct kobject *parent; |
68 | struct kset *kset; |
69 | const struct kobj_type *ktype; |
70 | struct kernfs_node *sd; /* sysfs directory entry */ |
71 | struct kref kref; |
72 | |
73 | unsigned int state_initialized:1; |
74 | unsigned int state_in_sysfs:1; |
75 | unsigned int state_add_uevent_sent:1; |
76 | unsigned int state_remove_uevent_sent:1; |
77 | unsigned int uevent_suppress:1; |
78 | |
79 | #ifdef CONFIG_DEBUG_KOBJECT_RELEASE |
80 | struct delayed_work release; |
81 | #endif |
82 | }; |
83 | |
84 | __printf(2, 3) int kobject_set_name(struct kobject *kobj, const char *name, ...); |
85 | __printf(2, 0) int kobject_set_name_vargs(struct kobject *kobj, const char *fmt, va_list vargs); |
86 | |
87 | static inline const char *kobject_name(const struct kobject *kobj) |
88 | { |
89 | return kobj->name; |
90 | } |
91 | |
92 | void kobject_init(struct kobject *kobj, const struct kobj_type *ktype); |
93 | __printf(3, 4) __must_check int kobject_add(struct kobject *kobj, |
94 | struct kobject *parent, |
95 | const char *fmt, ...); |
96 | __printf(4, 5) __must_check int kobject_init_and_add(struct kobject *kobj, |
97 | const struct kobj_type *ktype, |
98 | struct kobject *parent, |
99 | const char *fmt, ...); |
100 | |
101 | void kobject_del(struct kobject *kobj); |
102 | |
103 | struct kobject * __must_check kobject_create_and_add(const char *name, struct kobject *parent); |
104 | |
105 | int __must_check kobject_rename(struct kobject *, const char *new_name); |
106 | int __must_check kobject_move(struct kobject *, struct kobject *); |
107 | |
108 | struct kobject *kobject_get(struct kobject *kobj); |
109 | struct kobject * __must_check kobject_get_unless_zero(struct kobject *kobj); |
110 | void kobject_put(struct kobject *kobj); |
111 | |
112 | const void *kobject_namespace(const struct kobject *kobj); |
113 | void kobject_get_ownership(const struct kobject *kobj, kuid_t *uid, kgid_t *gid); |
114 | char *kobject_get_path(const struct kobject *kobj, gfp_t flag); |
115 | |
116 | struct kobj_type { |
117 | void (*release)(struct kobject *kobj); |
118 | const struct sysfs_ops *sysfs_ops; |
119 | const struct attribute_group **default_groups; |
120 | const struct kobj_ns_type_operations *(*child_ns_type)(const struct kobject *kobj); |
121 | const void *(*namespace)(const struct kobject *kobj); |
122 | void (*get_ownership)(const struct kobject *kobj, kuid_t *uid, kgid_t *gid); |
123 | }; |
124 | |
125 | struct kobj_uevent_env { |
126 | char *argv[3]; |
127 | char *envp[UEVENT_NUM_ENVP]; |
128 | int envp_idx; |
129 | char buf[UEVENT_BUFFER_SIZE]; |
130 | int buflen; |
131 | }; |
132 | |
133 | struct kset_uevent_ops { |
134 | int (* const filter)(const struct kobject *kobj); |
135 | const char *(* const name)(const struct kobject *kobj); |
136 | int (* const uevent)(const struct kobject *kobj, struct kobj_uevent_env *env); |
137 | }; |
138 | |
139 | struct kobj_attribute { |
140 | struct attribute attr; |
141 | ssize_t (*show)(struct kobject *kobj, struct kobj_attribute *attr, |
142 | char *buf); |
143 | ssize_t (*store)(struct kobject *kobj, struct kobj_attribute *attr, |
144 | const char *buf, size_t count); |
145 | }; |
146 | |
147 | extern const struct sysfs_ops kobj_sysfs_ops; |
148 | |
149 | struct sock; |
150 | |
151 | /** |
152 | * struct kset - a set of kobjects of a specific type, belonging to a specific subsystem. |
153 | * |
154 | * A kset defines a group of kobjects. They can be individually |
155 | * different "types" but overall these kobjects all want to be grouped |
156 | * together and operated on in the same manner. ksets are used to |
157 | * define the attribute callbacks and other common events that happen to |
158 | * a kobject. |
159 | * |
160 | * @list: the list of all kobjects for this kset |
161 | * @list_lock: a lock for iterating over the kobjects |
162 | * @kobj: the embedded kobject for this kset (recursion, isn't it fun...) |
163 | * @uevent_ops: the set of uevent operations for this kset. These are |
164 | * called whenever a kobject has something happen to it so that the kset |
165 | * can add new environment variables, or filter out the uevents if so |
166 | * desired. |
167 | */ |
168 | struct kset { |
169 | struct list_head list; |
170 | spinlock_t list_lock; |
171 | struct kobject kobj; |
172 | const struct kset_uevent_ops *uevent_ops; |
173 | } __randomize_layout; |
174 | |
175 | void kset_init(struct kset *kset); |
176 | int __must_check kset_register(struct kset *kset); |
177 | void kset_unregister(struct kset *kset); |
178 | struct kset * __must_check kset_create_and_add(const char *name, const struct kset_uevent_ops *u, |
179 | struct kobject *parent_kobj); |
180 | |
181 | static inline struct kset *to_kset(struct kobject *kobj) |
182 | { |
183 | return kobj ? container_of(kobj, struct kset, kobj) : NULL; |
184 | } |
185 | |
186 | static inline struct kset *kset_get(struct kset *k) |
187 | { |
188 | return k ? to_kset(kobj: kobject_get(kobj: &k->kobj)) : NULL; |
189 | } |
190 | |
191 | static inline void kset_put(struct kset *k) |
192 | { |
193 | kobject_put(kobj: &k->kobj); |
194 | } |
195 | |
196 | static inline const struct kobj_type *get_ktype(const struct kobject *kobj) |
197 | { |
198 | return kobj->ktype; |
199 | } |
200 | |
201 | struct kobject *kset_find_obj(struct kset *, const char *); |
202 | |
203 | /* The global /sys/kernel/ kobject for people to chain off of */ |
204 | extern struct kobject *kernel_kobj; |
205 | /* The global /sys/kernel/mm/ kobject for people to chain off of */ |
206 | extern struct kobject *mm_kobj; |
207 | /* The global /sys/hypervisor/ kobject for people to chain off of */ |
208 | extern struct kobject *hypervisor_kobj; |
209 | /* The global /sys/power/ kobject for people to chain off of */ |
210 | extern struct kobject *power_kobj; |
211 | /* The global /sys/firmware/ kobject for people to chain off of */ |
212 | extern struct kobject *firmware_kobj; |
213 | |
214 | int kobject_uevent(struct kobject *kobj, enum kobject_action action); |
215 | int kobject_uevent_env(struct kobject *kobj, enum kobject_action action, |
216 | char *envp[]); |
217 | int kobject_synth_uevent(struct kobject *kobj, const char *buf, size_t count); |
218 | |
219 | __printf(2, 3) |
220 | int add_uevent_var(struct kobj_uevent_env *env, const char *format, ...); |
221 | |
222 | #endif /* _KOBJECT_H_ */ |
223 | |