xref: /linux/include/linux/debugfs.h (revision 3fd6c59042dbba50391e30862beac979491145fe)
1 // SPDX-License-Identifier: GPL-2.0
2 /*
3  *  debugfs.h - a tiny little debug file system
4  *
5  *  Copyright (C) 2004 Greg Kroah-Hartman <greg@kroah.com>
6  *  Copyright (C) 2004 IBM Inc.
7  *
8  *  debugfs is for people to use instead of /proc or /sys.
9  *  See Documentation/filesystems/ for more details.
10  */
11 
12 #ifndef _DEBUGFS_H_
13 #define _DEBUGFS_H_
14 
15 #include <linux/fs.h>
16 #include <linux/seq_file.h>
17 
18 #include <linux/types.h>
19 #include <linux/compiler.h>
20 
21 struct device;
22 struct file_operations;
23 
24 struct debugfs_blob_wrapper {
25 	void *data;
26 	unsigned long size;
27 };
28 
29 struct debugfs_reg32 {
30 	char *name;
31 	unsigned long offset;
32 };
33 
34 struct debugfs_regset32 {
35 	const struct debugfs_reg32 *regs;
36 	int nregs;
37 	void __iomem *base;
38 	struct device *dev;	/* Optional device for Runtime PM */
39 };
40 
41 struct debugfs_u32_array {
42 	u32 *array;
43 	u32 n_elements;
44 };
45 
46 extern struct dentry *arch_debugfs_dir;
47 
48 #define DEFINE_DEBUGFS_ATTRIBUTE_XSIGNED(__fops, __get, __set, __fmt, __is_signed)	\
49 static int __fops ## _open(struct inode *inode, struct file *file)	\
50 {									\
51 	__simple_attr_check_format(__fmt, 0ull);			\
52 	return simple_attr_open(inode, file, __get, __set, __fmt);	\
53 }									\
54 static const struct file_operations __fops = {				\
55 	.owner	 = THIS_MODULE,						\
56 	.open	 = __fops ## _open,					\
57 	.release = simple_attr_release,					\
58 	.read	 = debugfs_attr_read,					\
59 	.write	 = (__is_signed) ? debugfs_attr_write_signed : debugfs_attr_write,	\
60 }
61 
62 #define DEFINE_DEBUGFS_ATTRIBUTE(__fops, __get, __set, __fmt)		\
63 	DEFINE_DEBUGFS_ATTRIBUTE_XSIGNED(__fops, __get, __set, __fmt, false)
64 
65 #define DEFINE_DEBUGFS_ATTRIBUTE_SIGNED(__fops, __get, __set, __fmt)	\
66 	DEFINE_DEBUGFS_ATTRIBUTE_XSIGNED(__fops, __get, __set, __fmt, true)
67 
68 typedef struct vfsmount *(*debugfs_automount_t)(struct dentry *, void *);
69 
70 #if defined(CONFIG_DEBUG_FS)
71 
72 struct dentry *debugfs_lookup(const char *name, struct dentry *parent);
73 
74 struct debugfs_short_fops {
75 	ssize_t (*read)(struct file *, char __user *, size_t, loff_t *);
76 	ssize_t (*write)(struct file *, const char __user *, size_t, loff_t *);
77 	loff_t (*llseek) (struct file *, loff_t, int);
78 };
79 
80 struct dentry *debugfs_create_file_full(const char *name, umode_t mode,
81 					struct dentry *parent, void *data,
82 					const struct file_operations *fops);
83 struct dentry *debugfs_create_file_short(const char *name, umode_t mode,
84 					 struct dentry *parent, void *data,
85 					 const struct debugfs_short_fops *fops);
86 
87 /**
88  * debugfs_create_file - create a file in the debugfs filesystem
89  * @name: a pointer to a string containing the name of the file to create.
90  * @mode: the permission that the file should have.
91  * @parent: a pointer to the parent dentry for this file.  This should be a
92  *          directory dentry if set.  If this parameter is NULL, then the
93  *          file will be created in the root of the debugfs filesystem.
94  * @data: a pointer to something that the caller will want to get to later
95  *        on.  The inode.i_private pointer will point to this value on
96  *        the open() call.
97  * @fops: a pointer to a struct file_operations or struct debugfs_short_fops that
98  *        should be used for this file.
99  *
100  * This is the basic "create a file" function for debugfs.  It allows for a
101  * wide range of flexibility in creating a file, or a directory (if you want
102  * to create a directory, the debugfs_create_dir() function is
103  * recommended to be used instead.)
104  *
105  * This function will return a pointer to a dentry if it succeeds.  This
106  * pointer must be passed to the debugfs_remove() function when the file is
107  * to be removed (no automatic cleanup happens if your module is unloaded,
108  * you are responsible here.)  If an error occurs, ERR_PTR(-ERROR) will be
109  * returned.
110  *
111  * If debugfs is not enabled in the kernel, the value -%ENODEV will be
112  * returned.
113  *
114  * If fops points to a struct debugfs_short_fops, then simple_open() will be
115  * used for the open, and only read/write/llseek are supported and are proxied,
116  * so no module reference or release are needed.
117  *
118  * NOTE: it's expected that most callers should _ignore_ the errors returned
119  * by this function. Other debugfs functions handle the fact that the "dentry"
120  * passed to them could be an error and they don't crash in that case.
121  * Drivers should generally work fine even if debugfs fails to init anyway.
122  */
123 #define debugfs_create_file(name, mode, parent, data, fops)			\
124 	_Generic(fops,								\
125 		 const struct file_operations *: debugfs_create_file_full,	\
126 		 const struct debugfs_short_fops *: debugfs_create_file_short,	\
127 		 struct file_operations *: debugfs_create_file_full,		\
128 		 struct debugfs_short_fops *: debugfs_create_file_short)	\
129 		(name, mode, parent, data, fops)
130 
131 struct dentry *debugfs_create_file_unsafe(const char *name, umode_t mode,
132 				   struct dentry *parent, void *data,
133 				   const struct file_operations *fops);
134 
135 void debugfs_create_file_size(const char *name, umode_t mode,
136 			      struct dentry *parent, void *data,
137 			      const struct file_operations *fops,
138 			      loff_t file_size);
139 
140 struct dentry *debugfs_create_dir(const char *name, struct dentry *parent);
141 
142 struct dentry *debugfs_create_symlink(const char *name, struct dentry *parent,
143 				      const char *dest);
144 
145 struct dentry *debugfs_create_automount(const char *name,
146 					struct dentry *parent,
147 					debugfs_automount_t f,
148 					void *data);
149 
150 void debugfs_remove(struct dentry *dentry);
151 #define debugfs_remove_recursive debugfs_remove
152 
153 void debugfs_lookup_and_remove(const char *name, struct dentry *parent);
154 
155 const struct file_operations *debugfs_real_fops(const struct file *filp);
156 
157 int debugfs_file_get(struct dentry *dentry);
158 void debugfs_file_put(struct dentry *dentry);
159 
160 ssize_t debugfs_attr_read(struct file *file, char __user *buf,
161 			size_t len, loff_t *ppos);
162 ssize_t debugfs_attr_write(struct file *file, const char __user *buf,
163 			size_t len, loff_t *ppos);
164 ssize_t debugfs_attr_write_signed(struct file *file, const char __user *buf,
165 			size_t len, loff_t *ppos);
166 
167 struct dentry *debugfs_rename(struct dentry *old_dir, struct dentry *old_dentry,
168                 struct dentry *new_dir, const char *new_name);
169 
170 void debugfs_create_u8(const char *name, umode_t mode, struct dentry *parent,
171 		       u8 *value);
172 void debugfs_create_u16(const char *name, umode_t mode, struct dentry *parent,
173 			u16 *value);
174 void debugfs_create_u32(const char *name, umode_t mode, struct dentry *parent,
175 			u32 *value);
176 void debugfs_create_u64(const char *name, umode_t mode, struct dentry *parent,
177 			u64 *value);
178 void debugfs_create_ulong(const char *name, umode_t mode, struct dentry *parent,
179 			  unsigned long *value);
180 void debugfs_create_x8(const char *name, umode_t mode, struct dentry *parent,
181 		       u8 *value);
182 void debugfs_create_x16(const char *name, umode_t mode, struct dentry *parent,
183 			u16 *value);
184 void debugfs_create_x32(const char *name, umode_t mode, struct dentry *parent,
185 			u32 *value);
186 void debugfs_create_x64(const char *name, umode_t mode, struct dentry *parent,
187 			u64 *value);
188 void debugfs_create_size_t(const char *name, umode_t mode,
189 			   struct dentry *parent, size_t *value);
190 void debugfs_create_atomic_t(const char *name, umode_t mode,
191 			     struct dentry *parent, atomic_t *value);
192 void debugfs_create_bool(const char *name, umode_t mode, struct dentry *parent,
193 			 bool *value);
194 void debugfs_create_str(const char *name, umode_t mode,
195 			struct dentry *parent, char **value);
196 
197 struct dentry *debugfs_create_blob(const char *name, umode_t mode,
198 				  struct dentry *parent,
199 				  struct debugfs_blob_wrapper *blob);
200 
201 void debugfs_create_regset32(const char *name, umode_t mode,
202 			     struct dentry *parent,
203 			     struct debugfs_regset32 *regset);
204 
205 void debugfs_print_regs32(struct seq_file *s, const struct debugfs_reg32 *regs,
206 			  int nregs, void __iomem *base, char *prefix);
207 
208 void debugfs_create_u32_array(const char *name, umode_t mode,
209 			      struct dentry *parent,
210 			      struct debugfs_u32_array *array);
211 
212 void debugfs_create_devm_seqfile(struct device *dev, const char *name,
213 				 struct dentry *parent,
214 				 int (*read_fn)(struct seq_file *s, void *data));
215 
216 bool debugfs_initialized(void);
217 
218 ssize_t debugfs_read_file_bool(struct file *file, char __user *user_buf,
219 			       size_t count, loff_t *ppos);
220 
221 ssize_t debugfs_write_file_bool(struct file *file, const char __user *user_buf,
222 				size_t count, loff_t *ppos);
223 
224 ssize_t debugfs_read_file_str(struct file *file, char __user *user_buf,
225 			      size_t count, loff_t *ppos);
226 
227 /**
228  * struct debugfs_cancellation - cancellation data
229  * @list: internal, for keeping track
230  * @cancel: callback to call
231  * @cancel_data: extra data for the callback to call
232  */
233 struct debugfs_cancellation {
234 	struct list_head list;
235 	void (*cancel)(struct dentry *, void *);
236 	void *cancel_data;
237 };
238 
239 void __acquires(cancellation)
240 debugfs_enter_cancellation(struct file *file,
241 			   struct debugfs_cancellation *cancellation);
242 void __releases(cancellation)
243 debugfs_leave_cancellation(struct file *file,
244 			   struct debugfs_cancellation *cancellation);
245 
246 #else
247 
248 #include <linux/err.h>
249 
250 /*
251  * We do not return NULL from these functions if CONFIG_DEBUG_FS is not enabled
252  * so users have a chance to detect if there was a real error or not.  We don't
253  * want to duplicate the design decision mistakes of procfs and devfs again.
254  */
255 
debugfs_lookup(const char * name,struct dentry * parent)256 static inline struct dentry *debugfs_lookup(const char *name,
257 					    struct dentry *parent)
258 {
259 	return ERR_PTR(-ENODEV);
260 }
261 
debugfs_create_file(const char * name,umode_t mode,struct dentry * parent,void * data,const void * fops)262 static inline struct dentry *debugfs_create_file(const char *name, umode_t mode,
263 					struct dentry *parent, void *data,
264 					const void *fops)
265 {
266 	return ERR_PTR(-ENODEV);
267 }
268 
debugfs_create_file_unsafe(const char * name,umode_t mode,struct dentry * parent,void * data,const struct file_operations * fops)269 static inline struct dentry *debugfs_create_file_unsafe(const char *name,
270 					umode_t mode, struct dentry *parent,
271 					void *data,
272 					const struct file_operations *fops)
273 {
274 	return ERR_PTR(-ENODEV);
275 }
276 
debugfs_create_file_size(const char * name,umode_t mode,struct dentry * parent,void * data,const struct file_operations * fops,loff_t file_size)277 static inline void debugfs_create_file_size(const char *name, umode_t mode,
278 					    struct dentry *parent, void *data,
279 					    const struct file_operations *fops,
280 					    loff_t file_size)
281 { }
282 
debugfs_create_dir(const char * name,struct dentry * parent)283 static inline struct dentry *debugfs_create_dir(const char *name,
284 						struct dentry *parent)
285 {
286 	return ERR_PTR(-ENODEV);
287 }
288 
debugfs_create_symlink(const char * name,struct dentry * parent,const char * dest)289 static inline struct dentry *debugfs_create_symlink(const char *name,
290 						    struct dentry *parent,
291 						    const char *dest)
292 {
293 	return ERR_PTR(-ENODEV);
294 }
295 
debugfs_create_automount(const char * name,struct dentry * parent,debugfs_automount_t f,void * data)296 static inline struct dentry *debugfs_create_automount(const char *name,
297 					struct dentry *parent,
298 					debugfs_automount_t f,
299 					void *data)
300 {
301 	return ERR_PTR(-ENODEV);
302 }
303 
debugfs_remove(struct dentry * dentry)304 static inline void debugfs_remove(struct dentry *dentry)
305 { }
306 
debugfs_remove_recursive(struct dentry * dentry)307 static inline void debugfs_remove_recursive(struct dentry *dentry)
308 { }
309 
debugfs_lookup_and_remove(const char * name,struct dentry * parent)310 static inline void debugfs_lookup_and_remove(const char *name,
311 					     struct dentry *parent)
312 { }
313 
314 const struct file_operations *debugfs_real_fops(const struct file *filp);
315 
debugfs_file_get(struct dentry * dentry)316 static inline int debugfs_file_get(struct dentry *dentry)
317 {
318 	return 0;
319 }
320 
debugfs_file_put(struct dentry * dentry)321 static inline void debugfs_file_put(struct dentry *dentry)
322 { }
323 
debugfs_attr_read(struct file * file,char __user * buf,size_t len,loff_t * ppos)324 static inline ssize_t debugfs_attr_read(struct file *file, char __user *buf,
325 					size_t len, loff_t *ppos)
326 {
327 	return -ENODEV;
328 }
329 
debugfs_attr_write(struct file * file,const char __user * buf,size_t len,loff_t * ppos)330 static inline ssize_t debugfs_attr_write(struct file *file,
331 					const char __user *buf,
332 					size_t len, loff_t *ppos)
333 {
334 	return -ENODEV;
335 }
336 
debugfs_attr_write_signed(struct file * file,const char __user * buf,size_t len,loff_t * ppos)337 static inline ssize_t debugfs_attr_write_signed(struct file *file,
338 					const char __user *buf,
339 					size_t len, loff_t *ppos)
340 {
341 	return -ENODEV;
342 }
343 
debugfs_rename(struct dentry * old_dir,struct dentry * old_dentry,struct dentry * new_dir,char * new_name)344 static inline struct dentry *debugfs_rename(struct dentry *old_dir, struct dentry *old_dentry,
345                 struct dentry *new_dir, char *new_name)
346 {
347 	return ERR_PTR(-ENODEV);
348 }
349 
debugfs_create_u8(const char * name,umode_t mode,struct dentry * parent,u8 * value)350 static inline void debugfs_create_u8(const char *name, umode_t mode,
351 				     struct dentry *parent, u8 *value) { }
352 
debugfs_create_u16(const char * name,umode_t mode,struct dentry * parent,u16 * value)353 static inline void debugfs_create_u16(const char *name, umode_t mode,
354 				      struct dentry *parent, u16 *value) { }
355 
debugfs_create_u32(const char * name,umode_t mode,struct dentry * parent,u32 * value)356 static inline void debugfs_create_u32(const char *name, umode_t mode,
357 				      struct dentry *parent, u32 *value) { }
358 
debugfs_create_u64(const char * name,umode_t mode,struct dentry * parent,u64 * value)359 static inline void debugfs_create_u64(const char *name, umode_t mode,
360 				      struct dentry *parent, u64 *value) { }
361 
debugfs_create_ulong(const char * name,umode_t mode,struct dentry * parent,unsigned long * value)362 static inline void debugfs_create_ulong(const char *name, umode_t mode,
363 					struct dentry *parent,
364 					unsigned long *value) { }
365 
debugfs_create_x8(const char * name,umode_t mode,struct dentry * parent,u8 * value)366 static inline void debugfs_create_x8(const char *name, umode_t mode,
367 				     struct dentry *parent, u8 *value) { }
368 
debugfs_create_x16(const char * name,umode_t mode,struct dentry * parent,u16 * value)369 static inline void debugfs_create_x16(const char *name, umode_t mode,
370 				      struct dentry *parent, u16 *value) { }
371 
debugfs_create_x32(const char * name,umode_t mode,struct dentry * parent,u32 * value)372 static inline void debugfs_create_x32(const char *name, umode_t mode,
373 				      struct dentry *parent, u32 *value) { }
374 
debugfs_create_x64(const char * name,umode_t mode,struct dentry * parent,u64 * value)375 static inline void debugfs_create_x64(const char *name, umode_t mode,
376 				      struct dentry *parent, u64 *value) { }
377 
debugfs_create_size_t(const char * name,umode_t mode,struct dentry * parent,size_t * value)378 static inline void debugfs_create_size_t(const char *name, umode_t mode,
379 					 struct dentry *parent, size_t *value)
380 { }
381 
debugfs_create_atomic_t(const char * name,umode_t mode,struct dentry * parent,atomic_t * value)382 static inline void debugfs_create_atomic_t(const char *name, umode_t mode,
383 					   struct dentry *parent,
384 					   atomic_t *value)
385 { }
386 
debugfs_create_bool(const char * name,umode_t mode,struct dentry * parent,bool * value)387 static inline void debugfs_create_bool(const char *name, umode_t mode,
388 				       struct dentry *parent, bool *value) { }
389 
debugfs_create_str(const char * name,umode_t mode,struct dentry * parent,char ** value)390 static inline void debugfs_create_str(const char *name, umode_t mode,
391 				      struct dentry *parent,
392 				      char **value)
393 { }
394 
debugfs_create_blob(const char * name,umode_t mode,struct dentry * parent,struct debugfs_blob_wrapper * blob)395 static inline struct dentry *debugfs_create_blob(const char *name, umode_t mode,
396 				  struct dentry *parent,
397 				  struct debugfs_blob_wrapper *blob)
398 {
399 	return ERR_PTR(-ENODEV);
400 }
401 
debugfs_create_regset32(const char * name,umode_t mode,struct dentry * parent,struct debugfs_regset32 * regset)402 static inline void debugfs_create_regset32(const char *name, umode_t mode,
403 					   struct dentry *parent,
404 					   struct debugfs_regset32 *regset)
405 {
406 }
407 
debugfs_print_regs32(struct seq_file * s,const struct debugfs_reg32 * regs,int nregs,void __iomem * base,char * prefix)408 static inline void debugfs_print_regs32(struct seq_file *s, const struct debugfs_reg32 *regs,
409 			 int nregs, void __iomem *base, char *prefix)
410 {
411 }
412 
debugfs_initialized(void)413 static inline bool debugfs_initialized(void)
414 {
415 	return false;
416 }
417 
debugfs_create_u32_array(const char * name,umode_t mode,struct dentry * parent,struct debugfs_u32_array * array)418 static inline void debugfs_create_u32_array(const char *name, umode_t mode,
419 					    struct dentry *parent,
420 					    struct debugfs_u32_array *array)
421 {
422 }
423 
debugfs_create_devm_seqfile(struct device * dev,const char * name,struct dentry * parent,int (* read_fn)(struct seq_file * s,void * data))424 static inline void debugfs_create_devm_seqfile(struct device *dev,
425 					       const char *name,
426 					       struct dentry *parent,
427 					       int (*read_fn)(struct seq_file *s,
428 							      void *data))
429 {
430 }
431 
debugfs_read_file_bool(struct file * file,char __user * user_buf,size_t count,loff_t * ppos)432 static inline ssize_t debugfs_read_file_bool(struct file *file,
433 					     char __user *user_buf,
434 					     size_t count, loff_t *ppos)
435 {
436 	return -ENODEV;
437 }
438 
debugfs_write_file_bool(struct file * file,const char __user * user_buf,size_t count,loff_t * ppos)439 static inline ssize_t debugfs_write_file_bool(struct file *file,
440 					      const char __user *user_buf,
441 					      size_t count, loff_t *ppos)
442 {
443 	return -ENODEV;
444 }
445 
debugfs_read_file_str(struct file * file,char __user * user_buf,size_t count,loff_t * ppos)446 static inline ssize_t debugfs_read_file_str(struct file *file,
447 					    char __user *user_buf,
448 					    size_t count, loff_t *ppos)
449 {
450 	return -ENODEV;
451 }
452 
453 #endif
454 
455 /**
456  * debugfs_create_xul - create a debugfs file that is used to read and write an
457  * unsigned long value, formatted in hexadecimal
458  * @name: a pointer to a string containing the name of the file to create.
459  * @mode: the permission that the file should have
460  * @parent: a pointer to the parent dentry for this file.  This should be a
461  *          directory dentry if set.  If this parameter is %NULL, then the
462  *          file will be created in the root of the debugfs filesystem.
463  * @value: a pointer to the variable that the file should read to and write
464  *         from.
465  */
debugfs_create_xul(const char * name,umode_t mode,struct dentry * parent,unsigned long * value)466 static inline void debugfs_create_xul(const char *name, umode_t mode,
467 				      struct dentry *parent,
468 				      unsigned long *value)
469 {
470 	if (sizeof(*value) == sizeof(u32))
471 		debugfs_create_x32(name, mode, parent, (u32 *)value);
472 	else
473 		debugfs_create_x64(name, mode, parent, (u64 *)value);
474 }
475 
476 #endif
477