Branch data     Line data    Source code

       1                 :            : /* SPDX-License-Identifier: GPL-2.0-or-later */
       2                 :            : /* -*- mode: c; c-basic-offset: 8; -*-
       3                 :            :  * vim: noexpandtab sw=8 ts=8 sts=0:
       4                 :            :  *
       5                 :            :  * configfs.h - definitions for the device driver filesystem
       6                 :            :  *
       7                 :            :  * Based on sysfs:
       8                 :            :  *      sysfs is Copyright (C) 2001, 2002, 2003 Patrick Mochel
       9                 :            :  *
      10                 :            :  * Based on kobject.h:
      11                 :            :  *      Copyright (c) 2002-2003 Patrick Mochel
      12                 :            :  *      Copyright (c) 2002-2003 Open Source Development Labs
      13                 :            :  *
      14                 :            :  * configfs Copyright (C) 2005 Oracle.  All rights reserved.
      15                 :            :  *
      16                 :            :  * Please read Documentation/filesystems/configfs/configfs.txt before using
      17                 :            :  * the configfs interface, ESPECIALLY the parts about reference counts and
      18                 :            :  * item destructors.
      19                 :            :  */
      20                 :            : 
      21                 :            : #ifndef _CONFIGFS_H_
      22                 :            : #define _CONFIGFS_H_
      23                 :            : 
      24                 :            : #include <linux/stat.h>   /* S_IRUGO */
      25                 :            : #include <linux/types.h>  /* ssize_t */
      26                 :            : #include <linux/list.h>   /* struct list_head */
      27                 :            : #include <linux/kref.h>   /* struct kref */
      28                 :            : #include <linux/mutex.h>  /* struct mutex */
      29                 :            : 
      30                 :            : #define CONFIGFS_ITEM_NAME_LEN  20
      31                 :            : 
      32                 :            : struct module;
      33                 :            : 
      34                 :            : struct configfs_item_operations;
      35                 :            : struct configfs_group_operations;
      36                 :            : struct configfs_attribute;
      37                 :            : struct configfs_bin_attribute;
      38                 :            : struct configfs_subsystem;
      39                 :            : 
      40                 :            : struct config_item {
      41                 :            :         char                    *ci_name;
      42                 :            :         char                    ci_namebuf[CONFIGFS_ITEM_NAME_LEN];
      43                 :            :         struct kref             ci_kref;
      44                 :            :         struct list_head        ci_entry;
      45                 :            :         struct config_item      *ci_parent;
      46                 :            :         struct config_group     *ci_group;
      47                 :            :         const struct config_item_type   *ci_type;
      48                 :            :         struct dentry           *ci_dentry;
      49                 :            : };
      50                 :            : 
      51                 :            : extern __printf(2, 3)
      52                 :            : int config_item_set_name(struct config_item *, const char *, ...);
      53                 :            : 
      54                 :            : static inline char *config_item_name(struct config_item * item)
      55                 :            : {
      56                 :          0 :         return item->ci_name;
      57                 :            : }
      58                 :            : 
      59                 :            : extern void config_item_init_type_name(struct config_item *item,
      60                 :            :                                        const char *name,
      61                 :            :                                        const struct config_item_type *type);
      62                 :            : 
      63                 :            : extern struct config_item *config_item_get(struct config_item *);
      64                 :            : extern struct config_item *config_item_get_unless_zero(struct config_item *);
      65                 :            : extern void config_item_put(struct config_item *);
      66                 :            : 
      67                 :            : struct config_item_type {
      68                 :            :         struct module                           *ct_owner;
      69                 :            :         struct configfs_item_operations         *ct_item_ops;
      70                 :            :         struct configfs_group_operations        *ct_group_ops;
      71                 :            :         struct configfs_attribute               **ct_attrs;
      72                 :            :         struct configfs_bin_attribute           **ct_bin_attrs;
      73                 :            : };
      74                 :            : 
      75                 :            : /**
      76                 :            :  *      group - a group of config_items of a specific type, belonging
      77                 :            :  *      to a specific subsystem.
      78                 :            :  */
      79                 :            : struct config_group {
      80                 :            :         struct config_item              cg_item;
      81                 :            :         struct list_head                cg_children;
      82                 :            :         struct configfs_subsystem       *cg_subsys;
      83                 :            :         struct list_head                default_groups;
      84                 :            :         struct list_head                group_entry;
      85                 :            : };
      86                 :            : 
      87                 :            : extern void config_group_init(struct config_group *group);
      88                 :            : extern void config_group_init_type_name(struct config_group *group,
      89                 :            :                                         const char *name,
      90                 :            :                                         const struct config_item_type *type);
      91                 :            : 
      92                 :            : static inline struct config_group *to_config_group(struct config_item *item)
      93                 :            : {
      94                 :          3 :         return item ? container_of(item,struct config_group,cg_item) : NULL;
      95                 :            : }
      96                 :            : 
      97                 :            : static inline struct config_group *config_group_get(struct config_group *group)
      98                 :            : {
      99                 :          3 :         return group ? to_config_group(config_item_get(&group->cg_item)) : NULL;
     100                 :            : }
     101                 :            : 
     102                 :            : static inline void config_group_put(struct config_group *group)
     103                 :            : {
     104                 :          0 :         config_item_put(&group->cg_item);
     105                 :            : }
     106                 :            : 
     107                 :            : extern struct config_item *config_group_find_item(struct config_group *,
     108                 :            :                                                   const char *);
     109                 :            : 
     110                 :            : 
     111                 :            : static inline void configfs_add_default_group(struct config_group *new_group,
     112                 :            :                 struct config_group *group)
     113                 :            : {
     114                 :            :         list_add_tail(&new_group->group_entry, &group->default_groups);
     115                 :            : }
     116                 :            : 
     117                 :            : struct configfs_attribute {
     118                 :            :         const char              *ca_name;
     119                 :            :         struct module           *ca_owner;
     120                 :            :         umode_t                 ca_mode;
     121                 :            :         ssize_t (*show)(struct config_item *, char *);
     122                 :            :         ssize_t (*store)(struct config_item *, const char *, size_t);
     123                 :            : };
     124                 :            : 
     125                 :            : #define CONFIGFS_ATTR(_pfx, _name)                      \
     126                 :            : static struct configfs_attribute _pfx##attr_##_name = { \
     127                 :            :         .ca_name        = __stringify(_name),           \
     128                 :            :         .ca_mode        = S_IRUGO | S_IWUSR,            \
     129                 :            :         .ca_owner       = THIS_MODULE,                  \
     130                 :            :         .show           = _pfx##_name##_show,           \
     131                 :            :         .store          = _pfx##_name##_store,          \
     132                 :            : }
     133                 :            : 
     134                 :            : #define CONFIGFS_ATTR_RO(_pfx, _name)                   \
     135                 :            : static struct configfs_attribute _pfx##attr_##_name = { \
     136                 :            :         .ca_name        = __stringify(_name),           \
     137                 :            :         .ca_mode        = S_IRUGO,                      \
     138                 :            :         .ca_owner       = THIS_MODULE,                  \
     139                 :            :         .show           = _pfx##_name##_show,           \
     140                 :            : }
     141                 :            : 
     142                 :            : #define CONFIGFS_ATTR_WO(_pfx, _name)                   \
     143                 :            : static struct configfs_attribute _pfx##attr_##_name = { \
     144                 :            :         .ca_name        = __stringify(_name),           \
     145                 :            :         .ca_mode        = S_IWUSR,                      \
     146                 :            :         .ca_owner       = THIS_MODULE,                  \
     147                 :            :         .store          = _pfx##_name##_store,          \
     148                 :            : }
     149                 :            : 
     150                 :            : struct file;
     151                 :            : struct vm_area_struct;
     152                 :            : 
     153                 :            : struct configfs_bin_attribute {
     154                 :            :         struct configfs_attribute cb_attr;      /* std. attribute */
     155                 :            :         void *cb_private;                       /* for user       */
     156                 :            :         size_t cb_max_size;                     /* max core size  */
     157                 :            :         ssize_t (*read)(struct config_item *, void *, size_t);
     158                 :            :         ssize_t (*write)(struct config_item *, const void *, size_t);
     159                 :            : };
     160                 :            : 
     161                 :            : #define CONFIGFS_BIN_ATTR(_pfx, _name, _priv, _maxsz)           \
     162                 :            : static struct configfs_bin_attribute _pfx##attr_##_name = {     \
     163                 :            :         .cb_attr = {                                            \
     164                 :            :                 .ca_name        = __stringify(_name),           \
     165                 :            :                 .ca_mode        = S_IRUGO | S_IWUSR,            \
     166                 :            :                 .ca_owner       = THIS_MODULE,                  \
     167                 :            :         },                                                      \
     168                 :            :         .cb_private     = _priv,                                \
     169                 :            :         .cb_max_size    = _maxsz,                               \
     170                 :            :         .read           = _pfx##_name##_read,                   \
     171                 :            :         .write          = _pfx##_name##_write,                  \
     172                 :            : }
     173                 :            : 
     174                 :            : #define CONFIGFS_BIN_ATTR_RO(_pfx, _name, _priv, _maxsz)        \
     175                 :            : static struct configfs_bin_attribute _pfx##attr_##_name = {     \
     176                 :            :         .cb_attr = {                                            \
     177                 :            :                 .ca_name        = __stringify(_name),           \
     178                 :            :                 .ca_mode        = S_IRUGO,                      \
     179                 :            :                 .ca_owner       = THIS_MODULE,                  \
     180                 :            :         },                                                      \
     181                 :            :         .cb_private     = _priv,                                \
     182                 :            :         .cb_max_size    = _maxsz,                               \
     183                 :            :         .read           = _pfx##_name##_read,                   \
     184                 :            : }
     185                 :            : 
     186                 :            : #define CONFIGFS_BIN_ATTR_WO(_pfx, _name, _priv, _maxsz)        \
     187                 :            : static struct configfs_bin_attribute _pfx##attr_##_name = {     \
     188                 :            :         .cb_attr = {                                            \
     189                 :            :                 .ca_name        = __stringify(_name),           \
     190                 :            :                 .ca_mode        = S_IWUSR,                      \
     191                 :            :                 .ca_owner       = THIS_MODULE,                  \
     192                 :            :         },                                                      \
     193                 :            :         .cb_private     = _priv,                                \
     194                 :            :         .cb_max_size    = _maxsz,                               \
     195                 :            :         .write          = _pfx##_name##_write,                  \
     196                 :            : }
     197                 :            : 
     198                 :            : /*
     199                 :            :  * If allow_link() exists, the item can symlink(2) out to other
     200                 :            :  * items.  If the item is a group, it may support mkdir(2).
     201                 :            :  * Groups supply one of make_group() and make_item().  If the
     202                 :            :  * group supports make_group(), one can create group children.  If it
     203                 :            :  * supports make_item(), one can create config_item children.  make_group()
     204                 :            :  * and make_item() return ERR_PTR() on errors.  If it has
     205                 :            :  * default_groups on group->default_groups, it has automatically created
     206                 :            :  * group children.  default_groups may coexist alongsize make_group() or
     207                 :            :  * make_item(), but if the group wishes to have only default_groups
     208                 :            :  * children (disallowing mkdir(2)), it need not provide either function.
     209                 :            :  * If the group has commit(), it supports pending and committed (active)
     210                 :            :  * items.
     211                 :            :  */
     212                 :            : struct configfs_item_operations {
     213                 :            :         void (*release)(struct config_item *);
     214                 :            :         int (*allow_link)(struct config_item *src, struct config_item *target);
     215                 :            :         void (*drop_link)(struct config_item *src, struct config_item *target);
     216                 :            : };
     217                 :            : 
     218                 :            : struct configfs_group_operations {
     219                 :            :         struct config_item *(*make_item)(struct config_group *group, const char *name);
     220                 :            :         struct config_group *(*make_group)(struct config_group *group, const char *name);
     221                 :            :         int (*commit_item)(struct config_item *item);
     222                 :            :         void (*disconnect_notify)(struct config_group *group, struct config_item *item);
     223                 :            :         void (*drop_item)(struct config_group *group, struct config_item *item);
     224                 :            : };
     225                 :            : 
     226                 :            : struct configfs_subsystem {
     227                 :            :         struct config_group     su_group;
     228                 :            :         struct mutex            su_mutex;
     229                 :            : };
     230                 :            : 
     231                 :            : static inline struct configfs_subsystem *to_configfs_subsystem(struct config_group *group)
     232                 :            : {
     233                 :            :         return group ?
     234                 :          3 :                 container_of(group, struct configfs_subsystem, su_group) :
     235                 :            :                 NULL;
     236                 :            : }
     237                 :            : 
     238                 :            : int configfs_register_subsystem(struct configfs_subsystem *subsys);
     239                 :            : void configfs_unregister_subsystem(struct configfs_subsystem *subsys);
     240                 :            : 
     241                 :            : int configfs_register_group(struct config_group *parent_group,
     242                 :            :                             struct config_group *group);
     243                 :            : void configfs_unregister_group(struct config_group *group);
     244                 :            : 
     245                 :            : void configfs_remove_default_groups(struct config_group *group);
     246                 :            : 
     247                 :            : struct config_group *
     248                 :            : configfs_register_default_group(struct config_group *parent_group,
     249                 :            :                                 const char *name,
     250                 :            :                                 const struct config_item_type *item_type);
     251                 :            : void configfs_unregister_default_group(struct config_group *group);
     252                 :            : 
     253                 :            : /* These functions can sleep and can alloc with GFP_KERNEL */
     254                 :            : /* WARNING: These cannot be called underneath configfs callbacks!! */
     255                 :            : int configfs_depend_item(struct configfs_subsystem *subsys,
     256                 :            :                          struct config_item *target);
     257                 :            : void configfs_undepend_item(struct config_item *target);
     258                 :            : 
     259                 :            : /*
     260                 :            :  * These functions can sleep and can alloc with GFP_KERNEL
     261                 :            :  * NOTE: These should be called only underneath configfs callbacks.
     262                 :            :  * NOTE: First parameter is a caller's subsystem, not target's.
     263                 :            :  * WARNING: These cannot be called on newly created item
     264                 :            :  *        (in make_group()/make_item() callback)
     265                 :            :  */
     266                 :            : int configfs_depend_item_unlocked(struct configfs_subsystem *caller_subsys,
     267                 :            :                                   struct config_item *target);
     268                 :            : 
     269                 :            : 
     270                 :            : static inline void configfs_undepend_item_unlocked(struct config_item *target)
     271                 :            : {
     272                 :            :         configfs_undepend_item(target);
     273                 :            : }
     274                 :            : 
     275                 :            : #endif /* _CONFIGFS_H_ */