[mirror_ubuntu-jammy-kernel.git] / include / linux / configfs.h

/* SPDX-License-Identifier: GPL-2.0-or-later */
/* -*- mode: c; c-basic-offset: 8; -*-
 * vim: noexpandtab sw=8 ts=8 sts=0:
 *
 * configfs.h - definitions for the device driver filesystem
 *
 * Based on sysfs:
 * 	sysfs is Copyright (C) 2001, 2002, 2003 Patrick Mochel
 *
 * Based on kobject.h:
 *      Copyright (c) 2002-2003	Patrick Mochel
 *      Copyright (c) 2002-2003	Open Source Development Labs
 *
 * configfs Copyright (C) 2005 Oracle.  All rights reserved.
 *
 * Please read Documentation/filesystems/configfs/configfs.txt before using
 * the configfs interface, ESPECIALLY the parts about reference counts and
 * item destructors.
 */

#ifndef _CONFIGFS_H_
#define _CONFIGFS_H_

#include <linux/stat.h>   /* S_IRUGO */
#include <linux/types.h>  /* ssize_t */
#include <linux/list.h>   /* struct list_head */
#include <linux/kref.h>   /* struct kref */
#include <linux/mutex.h>  /* struct mutex */

#define CONFIGFS_ITEM_NAME_LEN	20

struct module;

struct configfs_item_operations;
struct configfs_group_operations;
struct configfs_attribute;
struct configfs_bin_attribute;
struct configfs_subsystem;

struct config_item {
	char			*ci_name;
	char			ci_namebuf[CONFIGFS_ITEM_NAME_LEN];
	struct kref		ci_kref;
	struct list_head	ci_entry;
	struct config_item	*ci_parent;
	struct config_group	*ci_group;
	const struct config_item_type	*ci_type;
	struct dentry		*ci_dentry;
};

extern __printf(2, 3)
int config_item_set_name(struct config_item *, const char *, ...);

static inline char *config_item_name(struct config_item * item)
{
	return item->ci_name;
}

extern void config_item_init_type_name(struct config_item *item,
				       const char *name,
				       const struct config_item_type *type);

extern struct config_item *config_item_get(struct config_item *);
extern struct config_item *config_item_get_unless_zero(struct config_item *);
extern void config_item_put(struct config_item *);

struct config_item_type {
	struct module				*ct_owner;
	struct configfs_item_operations		*ct_item_ops;
	struct configfs_group_operations	*ct_group_ops;
	struct configfs_attribute		**ct_attrs;
	struct configfs_bin_attribute		**ct_bin_attrs;
};

/**
 *	group - a group of config_items of a specific type, belonging
 *	to a specific subsystem.
 */
struct config_group {
	struct config_item		cg_item;
	struct list_head		cg_children;
	struct configfs_subsystem 	*cg_subsys;
	struct list_head		default_groups;
	struct list_head		group_entry;
};

extern void config_group_init(struct config_group *group);
extern void config_group_init_type_name(struct config_group *group,
					const char *name,
					const struct config_item_type *type);

static inline struct config_group *to_config_group(struct config_item *item)
{
	return item ? container_of(item,struct config_group,cg_item) : NULL;
}

static inline struct config_group *config_group_get(struct config_group *group)
{
	return group ? to_config_group(config_item_get(&group->cg_item)) : NULL;
}

static inline void config_group_put(struct config_group *group)
{
	config_item_put(&group->cg_item);
}

extern struct config_item *config_group_find_item(struct config_group *,
						  const char *);


static inline void configfs_add_default_group(struct config_group *new_group,
		struct config_group *group)
{
	list_add_tail(&new_group->group_entry, &group->default_groups);
}

struct configfs_attribute {
	const char		*ca_name;
	struct module 		*ca_owner;
	umode_t			ca_mode;
	ssize_t (*show)(struct config_item *, char *);
	ssize_t (*store)(struct config_item *, const char *, size_t);
};

#define CONFIGFS_ATTR(_pfx, _name)			\
static struct configfs_attribute _pfx##attr_##_name = {	\
	.ca_name	= __stringify(_name),		\
	.ca_mode	= S_IRUGO | S_IWUSR,		\
	.ca_owner	= THIS_MODULE,			\
	.show		= _pfx##_name##_show,		\
	.store		= _pfx##_name##_store,		\
}

#define CONFIGFS_ATTR_RO(_pfx, _name)			\
static struct configfs_attribute _pfx##attr_##_name = {	\
	.ca_name	= __stringify(_name),		\
	.ca_mode	= S_IRUGO,			\
	.ca_owner	= THIS_MODULE,			\
	.show		= _pfx##_name##_show,		\
}

#define CONFIGFS_ATTR_WO(_pfx, _name)			\
static struct configfs_attribute _pfx##attr_##_name = {	\
	.ca_name	= __stringify(_name),		\
	.ca_mode	= S_IWUSR,			\
	.ca_owner	= THIS_MODULE,			\
	.store		= _pfx##_name##_store,		\
}

struct file;
struct vm_area_struct;

struct configfs_bin_attribute {
	struct configfs_attribute cb_attr;	/* std. attribute */
	void *cb_private;			/* for user       */
	size_t cb_max_size;			/* max core size  */
	ssize_t (*read)(struct config_item *, void *, size_t);
	ssize_t (*write)(struct config_item *, const void *, size_t);
};

#define CONFIGFS_BIN_ATTR(_pfx, _name, _priv, _maxsz)		\
static struct configfs_bin_attribute _pfx##attr_##_name = {	\
	.cb_attr = {						\
		.ca_name	= __stringify(_name),		\
		.ca_mode	= S_IRUGO | S_IWUSR,		\
		.ca_owner	= THIS_MODULE,			\
	},							\
	.cb_private	= _priv,				\
	.cb_max_size	= _maxsz,				\
	.read		= _pfx##_name##_read,			\
	.write		= _pfx##_name##_write,			\
}

#define CONFIGFS_BIN_ATTR_RO(_pfx, _name, _priv, _maxsz)	\
static struct configfs_bin_attribute _pfx##attr_##_name = {	\
	.cb_attr = {						\
		.ca_name	= __stringify(_name),		\
		.ca_mode	= S_IRUGO,			\
		.ca_owner	= THIS_MODULE,			\
	},							\
	.cb_private	= _priv,				\
	.cb_max_size	= _maxsz,				\
	.read		= _pfx##_name##_read,			\
}

#define CONFIGFS_BIN_ATTR_WO(_pfx, _name, _priv, _maxsz)	\
static struct configfs_bin_attribute _pfx##attr_##_name = {	\
	.cb_attr = {						\
		.ca_name	= __stringify(_name),		\
		.ca_mode	= S_IWUSR,			\
		.ca_owner	= THIS_MODULE,			\
	},							\
	.cb_private	= _priv,				\
	.cb_max_size	= _maxsz,				\
	.write		= _pfx##_name##_write,			\
}

/*
 * If allow_link() exists, the item can symlink(2) out to other
 * items.  If the item is a group, it may support mkdir(2).
 * Groups supply one of make_group() and make_item().  If the
 * group supports make_group(), one can create group children.  If it
 * supports make_item(), one can create config_item children.  make_group()
 * and make_item() return ERR_PTR() on errors.  If it has
 * default_groups on group->default_groups, it has automatically created
 * group children.  default_groups may coexist alongsize make_group() or
 * make_item(), but if the group wishes to have only default_groups
 * children (disallowing mkdir(2)), it need not provide either function.
 * If the group has commit(), it supports pending and committed (active)
 * items.
 */
struct configfs_item_operations {
	void (*release)(struct config_item *);
	int (*allow_link)(struct config_item *src, struct config_item *target);
	void (*drop_link)(struct config_item *src, struct config_item *target);
};

struct configfs_group_operations {
	struct config_item *(*make_item)(struct config_group *group, const char *name);
	struct config_group *(*make_group)(struct config_group *group, const char *name);
	int (*commit_item)(struct config_item *item);
	void (*disconnect_notify)(struct config_group *group, struct config_item *item);
	void (*drop_item)(struct config_group *group, struct config_item *item);
};

struct configfs_subsystem {
	struct config_group	su_group;
	struct mutex		su_mutex;
};

static inline struct configfs_subsystem *to_configfs_subsystem(struct config_group *group)
{
	return group ?
		container_of(group, struct configfs_subsystem, su_group) :
		NULL;
}

int configfs_register_subsystem(struct configfs_subsystem *subsys);
void configfs_unregister_subsystem(struct configfs_subsystem *subsys);

int configfs_register_group(struct config_group *parent_group,
			    struct config_group *group);
void configfs_unregister_group(struct config_group *group);

void configfs_remove_default_groups(struct config_group *group);

struct config_group *
configfs_register_default_group(struct config_group *parent_group,
				const char *name,
				const struct config_item_type *item_type);
void configfs_unregister_default_group(struct config_group *group);

/* These functions can sleep and can alloc with GFP_KERNEL */
/* WARNING: These cannot be called underneath configfs callbacks!! */
int configfs_depend_item(struct configfs_subsystem *subsys,
			 struct config_item *target);
void configfs_undepend_item(struct config_item *target);

/*
 * These functions can sleep and can alloc with GFP_KERNEL
 * NOTE: These should be called only underneath configfs callbacks.
 * NOTE: First parameter is a caller's subsystem, not target's.
 * WARNING: These cannot be called on newly created item
 *        (in make_group()/make_item() callback)
 */
int configfs_depend_item_unlocked(struct configfs_subsystem *caller_subsys,
				  struct config_item *target);


static inline void configfs_undepend_item_unlocked(struct config_item *target)
{
	configfs_undepend_item(target);
}

#endif /* _CONFIGFS_H_ */
Commit	Line	Data
328970de	1	/* SPDX-License-Identifier: GPL-2.0-or-later */
7063fbf2 JB	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	*
7063fbf2 JB	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	*
55dff495 RD	16	* Please read Documentation/filesystems/configfs/configfs.txt before using
55dff495 RD	17	* the configfs interface, ESPECIALLY the parts about reference counts and
7063fbf2 JB	18	* item destructors.
	19	*/
	20
	21	#ifndef _CONFIGFS_H_
	22	#define _CONFIGFS_H_
	23
a6ab5374 BVA	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 */
7063fbf2 JB	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;
03607ace	37	struct configfs_bin_attribute;
7063fbf2 JB	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;
aa293583	47	const struct config_item_type *ci_type;
7063fbf2 JB	48	struct dentry *ci_dentry;
	49	};
	50
8db14860 NI	51	extern __printf(2, 3)
8db14860 NI	52	int config_item_set_name(struct config_item , const char , ...);
7063fbf2 JB	53
	54	static inline char config_item_name(struct config_item item)
	55	{
	56	return item->ci_name;
	57	}
	58
7063fbf2 JB	59	extern void config_item_init_type_name(struct config_item *item,
7063fbf2 JB	60	const char *name,
aa293583	61	const struct config_item_type *type);
7063fbf2	62
19e72d3a BVA	63	extern struct config_item config_item_get(struct config_item );
19e72d3a BVA	64	extern struct config_item config_item_get_unless_zero(struct config_item );
7063fbf2 JB	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;
03607ace	72	struct configfs_bin_attribute **ct_bin_attrs;
7063fbf2 JB	73	};
7063fbf2 JB	74
7063fbf2 JB	75	/**
	76	* group - a group of config_items of a specific type, belonging
	77	* to a specific subsystem.
	78	*/
7063fbf2 JB	79	struct config_group {
	80	struct config_item cg_item;
	81	struct list_head cg_children;
	82	struct configfs_subsystem *cg_subsys;
1ae1602d CH	83	struct list_head default_groups;
1ae1602d CH	84	struct list_head group_entry;
7063fbf2 JB	85	};
7063fbf2 JB	86
7063fbf2 JB	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,
aa293583	90	const struct config_item_type *type);
7063fbf2	91
7063fbf2 JB	92	static inline struct config_group to_config_group(struct config_item item)
	93	{
	94	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	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	config_item_put(&group->cg_item);
	105	}
	106
3fe6c5ce SS	107	extern struct config_item config_group_find_item(struct config_group ,
3fe6c5ce SS	108	const char *);
7063fbf2 JB	109
7063fbf2 JB	110
1ae1602d CH	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
7063fbf2	117	struct configfs_attribute {
3d0f89bb	118	const char *ca_name;
7063fbf2	119	struct module *ca_owner;
43947514	120	umode_t ca_mode;
870823e6 CH	121	ssize_t (show)(struct config_item , char *);
870823e6 CH	122	ssize_t (store)(struct config_item , const char *, size_t);
7063fbf2 JB	123	};
7063fbf2 JB	124
870823e6 CH	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
03607ace PA	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) \
96c22a32	175	static struct configfs_bin_attribute _pfx##attr_##_name = { \
03607ace PA	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) \
96c22a32	187	static struct configfs_bin_attribute _pfx##attr_##_name = { \
03607ace PA	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
7063fbf2 JB	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
a6795e9e JB	203	* supports make_item(), one can create config_item children. make_group()
a6795e9e JB	204	* and make_item() return ERR_PTR() on errors. If it has
7063fbf2 JB	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.
25985edc	209	* If the group has commit(), it supports pending and committed (active)
7063fbf2 JB	210	* items.
	211	*/
	212	struct configfs_item_operations {
	213	void (release)(struct config_item );
7063fbf2	214	int (allow_link)(struct config_item src, struct config_item *target);
e16769d4	215	void (drop_link)(struct config_item src, struct config_item *target);
7063fbf2 JB	216	};
	217
	218	struct configfs_group_operations {
f89ab861 JB	219	struct config_item (make_item)(struct config_group group, const char name);
f89ab861 JB	220	struct config_group (make_group)(struct config_group group, const char name);
7063fbf2	221	int (commit_item)(struct config_item item);
299894cc	222	void (disconnect_notify)(struct config_group group, struct config_item *item);
7063fbf2 JB	223	void (drop_item)(struct config_group group, struct config_item *item);
	224	};
	225
7063fbf2 JB	226	struct configfs_subsystem {
7063fbf2 JB	227	struct config_group su_group;
e6bd07ae	228	struct mutex su_mutex;
7063fbf2 JB	229	};
	230
	231	static inline struct configfs_subsystem to_configfs_subsystem(struct config_group group)
	232	{
	233	return group ?
	234	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
5cf6a51e DB	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
1ae1602d CH	245	void configfs_remove_default_groups(struct config_group *group);
1ae1602d CH	246
5cf6a51e DB	247	struct config_group *
	248	configfs_register_default_group(struct config_group *parent_group,
	249	const char *name,
aa293583	250	const struct config_item_type *item_type);
5cf6a51e DB	251	void configfs_unregister_default_group(struct config_group *group);
5cf6a51e DB	252
631d1feb JB	253	/* These functions can sleep and can alloc with GFP_KERNEL */
631d1feb JB	254	/* WARNING: These cannot be called underneath configfs callbacks!! */
9a9e3415 KO	255	int configfs_depend_item(struct configfs_subsystem *subsys,
	256	struct config_item *target);
	257	void configfs_undepend_item(struct config_item *target);
631d1feb	258
d79d75b5 KO	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	}
631d1feb	274
7063fbf2	275	#endif /* _CONFIGFS_H_ */