Branch data     Line data    Source code

       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/kobject.txt 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/spinlock.h>
      23                 :            : #include <linux/kref.h>
      24                 :            : #include <linux/kobject_ns.h>
      25                 :            : #include <linux/kernel.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                 32      /* 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                 :            :         KOBJ_MAX
      63                 :            : };
      64                 :            : 
      65                 :            : struct kobject {
      66                 :            :         const char              *name;
      67                 :            :         struct list_head        entry;
      68                 :            :         struct kobject          *parent;
      69                 :            :         struct kset             *kset;
      70                 :            :         struct kobj_type        *ktype;
      71                 :            :         struct kernfs_node      *sd; /* sysfs directory entry */
      72                 :            :         struct kref             kref;
      73                 :            : #ifdef CONFIG_DEBUG_KOBJECT_RELEASE
      74                 :            :         struct delayed_work     release;
      75                 :            : #endif
      76                 :            :         unsigned int state_initialized:1;
      77                 :            :         unsigned int state_in_sysfs:1;
      78                 :            :         unsigned int state_add_uevent_sent:1;
      79                 :            :         unsigned int state_remove_uevent_sent:1;
      80                 :            :         unsigned int uevent_suppress:1;
      81                 :            : };
      82                 :            : 
      83                 :            : extern __printf(2, 3)
      84                 :            : int kobject_set_name(struct kobject *kobj, const char *name, ...);
      85                 :            : extern __printf(2, 0)
      86                 :            : int kobject_set_name_vargs(struct kobject *kobj, const char *fmt,
      87                 :            :                            va_list vargs);
      88                 :            : 
      89                 :            : static inline const char *kobject_name(const struct kobject *kobj)
      90                 :            : {
      91                 :          3 :         return kobj->name;
      92                 :            : }
      93                 :            : 
      94                 :            : extern void kobject_init(struct kobject *kobj, struct kobj_type *ktype);
      95                 :            : extern __printf(3, 4) __must_check
      96                 :            : int kobject_add(struct kobject *kobj, struct kobject *parent,
      97                 :            :                 const char *fmt, ...);
      98                 :            : extern __printf(4, 5) __must_check
      99                 :            : int kobject_init_and_add(struct kobject *kobj,
     100                 :            :                          struct kobj_type *ktype, struct kobject *parent,
     101                 :            :                          const char *fmt, ...);
     102                 :            : 
     103                 :            : extern void kobject_del(struct kobject *kobj);
     104                 :            : 
     105                 :            : extern struct kobject * __must_check kobject_create(void);
     106                 :            : extern struct kobject * __must_check kobject_create_and_add(const char *name,
     107                 :            :                                                 struct kobject *parent);
     108                 :            : 
     109                 :            : extern int __must_check kobject_rename(struct kobject *, const char *new_name);
     110                 :            : extern int __must_check kobject_move(struct kobject *, struct kobject *);
     111                 :            : 
     112                 :            : extern struct kobject *kobject_get(struct kobject *kobj);
     113                 :            : extern struct kobject * __must_check kobject_get_unless_zero(
     114                 :            :                                                 struct kobject *kobj);
     115                 :            : extern void kobject_put(struct kobject *kobj);
     116                 :            : 
     117                 :            : extern const void *kobject_namespace(struct kobject *kobj);
     118                 :            : extern void kobject_get_ownership(struct kobject *kobj,
     119                 :            :                                   kuid_t *uid, kgid_t *gid);
     120                 :            : extern char *kobject_get_path(struct kobject *kobj, gfp_t flag);
     121                 :            : 
     122                 :            : /**
     123                 :            :  * kobject_has_children - Returns whether a kobject has children.
     124                 :            :  * @kobj: the object to test
     125                 :            :  *
     126                 :            :  * This will return whether a kobject has other kobjects as children.
     127                 :            :  *
     128                 :            :  * It does NOT account for the presence of attribute files, only sub
     129                 :            :  * directories. It also assumes there is no concurrent addition or
     130                 :            :  * removal of such children, and thus relies on external locking.
     131                 :            :  */
     132                 :          1 : static inline bool kobject_has_children(struct kobject *kobj)
     133                 :            : {
     134                 :          1 :         WARN_ON_ONCE(kref_read(&kobj->kref) == 0);
     135                 :            : 
     136                 :          1 :         return kobj->sd && kobj->sd->dir.subdirs;
     137                 :            : }
     138                 :            : 
     139                 :            : struct kobj_type {
     140                 :            :         void (*release)(struct kobject *kobj);
     141                 :            :         const struct sysfs_ops *sysfs_ops;
     142                 :            :         struct attribute **default_attrs;       /* use default_groups instead */
     143                 :            :         const struct attribute_group **default_groups;
     144                 :            :         const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj);
     145                 :            :         const void *(*namespace)(struct kobject *kobj);
     146                 :            :         void (*get_ownership)(struct kobject *kobj, kuid_t *uid, kgid_t *gid);
     147                 :            : };
     148                 :            : 
     149                 :            : struct kobj_uevent_env {
     150                 :            :         char *argv[3];
     151                 :            :         char *envp[UEVENT_NUM_ENVP];
     152                 :            :         int envp_idx;
     153                 :            :         char buf[UEVENT_BUFFER_SIZE];
     154                 :            :         int buflen;
     155                 :            : };
     156                 :            : 
     157                 :            : struct kset_uevent_ops {
     158                 :            :         int (* const filter)(struct kset *kset, struct kobject *kobj);
     159                 :            :         const char *(* const name)(struct kset *kset, struct kobject *kobj);
     160                 :            :         int (* const uevent)(struct kset *kset, struct kobject *kobj,
     161                 :            :                       struct kobj_uevent_env *env);
     162                 :            : };
     163                 :            : 
     164                 :            : struct kobj_attribute {
     165                 :            :         struct attribute attr;
     166                 :            :         ssize_t (*show)(struct kobject *kobj, struct kobj_attribute *attr,
     167                 :            :                         char *buf);
     168                 :            :         ssize_t (*store)(struct kobject *kobj, struct kobj_attribute *attr,
     169                 :            :                          const char *buf, size_t count);
     170                 :            : };
     171                 :            : 
     172                 :            : extern const struct sysfs_ops kobj_sysfs_ops;
     173                 :            : 
     174                 :            : struct sock;
     175                 :            : 
     176                 :            : /**
     177                 :            :  * struct kset - a set of kobjects of a specific type, belonging to a specific subsystem.
     178                 :            :  *
     179                 :            :  * A kset defines a group of kobjects.  They can be individually
     180                 :            :  * different "types" but overall these kobjects all want to be grouped
     181                 :            :  * together and operated on in the same manner.  ksets are used to
     182                 :            :  * define the attribute callbacks and other common events that happen to
     183                 :            :  * a kobject.
     184                 :            :  *
     185                 :            :  * @list: the list of all kobjects for this kset
     186                 :            :  * @list_lock: a lock for iterating over the kobjects
     187                 :            :  * @kobj: the embedded kobject for this kset (recursion, isn't it fun...)
     188                 :            :  * @uevent_ops: the set of uevent operations for this kset.  These are
     189                 :            :  * called whenever a kobject has something happen to it so that the kset
     190                 :            :  * can add new environment variables, or filter out the uevents if so
     191                 :            :  * desired.
     192                 :            :  */
     193                 :            : struct kset {
     194                 :            :         struct list_head list;
     195                 :            :         spinlock_t list_lock;
     196                 :            :         struct kobject kobj;
     197                 :            :         const struct kset_uevent_ops *uevent_ops;
     198                 :            : } __randomize_layout;
     199                 :            : 
     200                 :            : extern void kset_init(struct kset *kset);
     201                 :            : extern int __must_check kset_register(struct kset *kset);
     202                 :            : extern void kset_unregister(struct kset *kset);
     203                 :            : extern struct kset * __must_check kset_create_and_add(const char *name,
     204                 :            :                                                 const struct kset_uevent_ops *u,
     205                 :            :                                                 struct kobject *parent_kobj);
     206                 :            : 
     207                 :            : static inline struct kset *to_kset(struct kobject *kobj)
     208                 :            : {
     209                 :          3 :         return kobj ? container_of(kobj, struct kset, kobj) : NULL;
     210                 :            : }
     211                 :            : 
     212                 :          3 : static inline struct kset *kset_get(struct kset *k)
     213                 :            : {
     214                 :          3 :         return k ? to_kset(kobject_get(&k->kobj)) : NULL;
     215                 :            : }
     216                 :            : 
     217                 :            : static inline void kset_put(struct kset *k)
     218                 :            : {
     219                 :          3 :         kobject_put(&k->kobj);
     220                 :            : }
     221                 :            : 
     222                 :            : static inline struct kobj_type *get_ktype(struct kobject *kobj)
     223                 :            : {
     224                 :          3 :         return kobj->ktype;
     225                 :            : }
     226                 :            : 
     227                 :            : extern struct kobject *kset_find_obj(struct kset *, const char *);
     228                 :            : 
     229                 :            : /* The global /sys/kernel/ kobject for people to chain off of */
     230                 :            : extern struct kobject *kernel_kobj;
     231                 :            : /* The global /sys/kernel/mm/ kobject for people to chain off of */
     232                 :            : extern struct kobject *mm_kobj;
     233                 :            : /* The global /sys/hypervisor/ kobject for people to chain off of */
     234                 :            : extern struct kobject *hypervisor_kobj;
     235                 :            : /* The global /sys/power/ kobject for people to chain off of */
     236                 :            : extern struct kobject *power_kobj;
     237                 :            : /* The global /sys/firmware/ kobject for people to chain off of */
     238                 :            : extern struct kobject *firmware_kobj;
     239                 :            : 
     240                 :            : int kobject_uevent(struct kobject *kobj, enum kobject_action action);
     241                 :            : int kobject_uevent_env(struct kobject *kobj, enum kobject_action action,
     242                 :            :                         char *envp[]);
     243                 :            : int kobject_synth_uevent(struct kobject *kobj, const char *buf, size_t count);
     244                 :            : 
     245                 :            : __printf(2, 3)
     246                 :            : int add_uevent_var(struct kobj_uevent_env *env, const char *format, ...);
     247                 :            : 
     248                 :            : #endif /* _KOBJECT_H_ */