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 <[email protected]> 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 struct debugfs_short_fops { 71 ssize_t (*read)(struct file *, char __user *, size_t, loff_t *); 72 ssize_t (*write)(struct file *, const char __user *, size_t, loff_t *); 73 loff_t (*llseek) (struct file *, loff_t, int); 74 }; 75 76 #if defined(CONFIG_DEBUG_FS) 77 78 struct dentry *debugfs_lookup(const char *name, struct dentry *parent); 79 80 struct dentry *debugfs_create_file_full(const char *name, umode_t mode, 81 struct dentry *parent, void *data, 82 const void *aux, 83 const struct file_operations *fops); 84 struct dentry *debugfs_create_file_short(const char *name, umode_t mode, 85 struct dentry *parent, void *data, 86 const void *aux, 87 const struct debugfs_short_fops *fops); 88 89 /** 90 * debugfs_create_file - create a file in the debugfs filesystem 91 * @name: a pointer to a string containing the name of the file to create. 92 * @mode: the permission that the file should have. 93 * @parent: a pointer to the parent dentry for this file. This should be a 94 * directory dentry if set. If this parameter is NULL, then the 95 * file will be created in the root of the debugfs filesystem. 96 * @data: a pointer to something that the caller will want to get to later 97 * on. The inode.i_private pointer will point to this value on 98 * the open() call. 99 * @fops: a pointer to a struct file_operations or struct debugfs_short_fops that 100 * should be used for this file. 101 * 102 * This is the basic "create a file" function for debugfs. It allows for a 103 * wide range of flexibility in creating a file, or a directory (if you want 104 * to create a directory, the debugfs_create_dir() function is 105 * recommended to be used instead.) 106 * 107 * This function will return a pointer to a dentry if it succeeds. This 108 * pointer must be passed to the debugfs_remove() function when the file is 109 * to be removed (no automatic cleanup happens if your module is unloaded, 110 * you are responsible here.) If an error occurs, ERR_PTR(-ERROR) will be 111 * returned. 112 * 113 * If debugfs is not enabled in the kernel, the value -%ENODEV will be 114 * returned. 115 * 116 * If fops points to a struct debugfs_short_fops, then simple_open() will be 117 * used for the open, and only read/write/llseek are supported and are proxied, 118 * so no module reference or release are needed. 119 * 120 * NOTE: it's expected that most callers should _ignore_ the errors returned 121 * by this function. Other debugfs functions handle the fact that the "dentry" 122 * passed to them could be an error and they don't crash in that case. 123 * Drivers should generally work fine even if debugfs fails to init anyway. 124 */ 125 #define debugfs_create_file(name, mode, parent, data, fops) \ 126 _Generic(fops, \ 127 const struct file_operations *: debugfs_create_file_full, \ 128 const struct debugfs_short_fops *: debugfs_create_file_short, \ 129 struct file_operations *: debugfs_create_file_full, \ 130 struct debugfs_short_fops *: debugfs_create_file_short) \ 131 (name, mode, parent, data, NULL, fops) 132 133 #define debugfs_create_file_aux(name, mode, parent, data, aux, fops) \ 134 _Generic(fops, \ 135 const struct file_operations *: debugfs_create_file_full, \ 136 const struct debugfs_short_fops *: debugfs_create_file_short, \ 137 struct file_operations *: debugfs_create_file_full, \ 138 struct debugfs_short_fops *: debugfs_create_file_short) \ 139 (name, mode, parent, data, aux, fops) 140 141 struct dentry *debugfs_create_file_unsafe(const char *name, umode_t mode, 142 struct dentry *parent, void *data, 143 const struct file_operations *fops); 144 145 void debugfs_create_file_size(const char *name, umode_t mode, 146 struct dentry *parent, void *data, 147 const struct file_operations *fops, 148 loff_t file_size); 149 150 struct dentry *debugfs_create_dir(const char *name, struct dentry *parent); 151 152 struct dentry *debugfs_create_symlink(const char *name, struct dentry *parent, 153 const char *dest); 154 155 struct dentry *debugfs_create_automount(const char *name, 156 struct dentry *parent, 157 debugfs_automount_t f, 158 void *data); 159 160 void debugfs_remove(struct dentry *dentry); 161 #define debugfs_remove_recursive debugfs_remove 162 163 void debugfs_lookup_and_remove(const char *name, struct dentry *parent); 164 165 const struct file_operations *debugfs_real_fops(const struct file *filp); 166 const void *debugfs_get_aux(const struct file *file); 167 168 int debugfs_file_get(struct dentry *dentry); 169 void debugfs_file_put(struct dentry *dentry); 170 171 ssize_t debugfs_attr_read(struct file *file, char __user *buf, 172 size_t len, loff_t *ppos); 173 ssize_t debugfs_attr_write(struct file *file, const char __user *buf, 174 size_t len, loff_t *ppos); 175 ssize_t debugfs_attr_write_signed(struct file *file, const char __user *buf, 176 size_t len, loff_t *ppos); 177 178 int debugfs_change_name(struct dentry *dentry, const char *fmt, ...) __printf(2, 3); 179 180 void debugfs_create_u8(const char *name, umode_t mode, struct dentry *parent, 181 u8 *value); 182 void debugfs_create_u16(const char *name, umode_t mode, struct dentry *parent, 183 u16 *value); 184 void debugfs_create_u32(const char *name, umode_t mode, struct dentry *parent, 185 u32 *value); 186 void debugfs_create_u64(const char *name, umode_t mode, struct dentry *parent, 187 u64 *value); 188 void debugfs_create_ulong(const char *name, umode_t mode, struct dentry *parent, 189 unsigned long *value); 190 void debugfs_create_x8(const char *name, umode_t mode, struct dentry *parent, 191 u8 *value); 192 void debugfs_create_x16(const char *name, umode_t mode, struct dentry *parent, 193 u16 *value); 194 void debugfs_create_x32(const char *name, umode_t mode, struct dentry *parent, 195 u32 *value); 196 void debugfs_create_x64(const char *name, umode_t mode, struct dentry *parent, 197 u64 *value); 198 void debugfs_create_size_t(const char *name, umode_t mode, 199 struct dentry *parent, size_t *value); 200 void debugfs_create_atomic_t(const char *name, umode_t mode, 201 struct dentry *parent, atomic_t *value); 202 void debugfs_create_bool(const char *name, umode_t mode, struct dentry *parent, 203 bool *value); 204 void debugfs_create_str(const char *name, umode_t mode, 205 struct dentry *parent, char **value); 206 207 struct dentry *debugfs_create_blob(const char *name, umode_t mode, 208 struct dentry *parent, 209 struct debugfs_blob_wrapper *blob); 210 211 void debugfs_create_regset32(const char *name, umode_t mode, 212 struct dentry *parent, 213 struct debugfs_regset32 *regset); 214 215 void debugfs_print_regs32(struct seq_file *s, const struct debugfs_reg32 *regs, 216 int nregs, void __iomem *base, char *prefix); 217 218 void debugfs_create_u32_array(const char *name, umode_t mode, 219 struct dentry *parent, 220 struct debugfs_u32_array *array); 221 222 void debugfs_create_devm_seqfile(struct device *dev, const char *name, 223 struct dentry *parent, 224 int (*read_fn)(struct seq_file *s, void *data)); 225 226 bool debugfs_initialized(void); 227 228 ssize_t debugfs_read_file_bool(struct file *file, char __user *user_buf, 229 size_t count, loff_t *ppos); 230 231 ssize_t debugfs_write_file_bool(struct file *file, const char __user *user_buf, 232 size_t count, loff_t *ppos); 233 234 ssize_t debugfs_read_file_str(struct file *file, char __user *user_buf, 235 size_t count, loff_t *ppos); 236 237 /** 238 * struct debugfs_cancellation - cancellation data 239 * @list: internal, for keeping track 240 * @cancel: callback to call 241 * @cancel_data: extra data for the callback to call 242 */ 243 struct debugfs_cancellation { 244 struct list_head list; 245 void (*cancel)(struct dentry *, void *); 246 void *cancel_data; 247 }; 248 249 void __acquires(cancellation) 250 debugfs_enter_cancellation(struct file *file, 251 struct debugfs_cancellation *cancellation); 252 void __releases(cancellation) 253 debugfs_leave_cancellation(struct file *file, 254 struct debugfs_cancellation *cancellation); 255 256 #else 257 258 #include <linux/err.h> 259 260 /* 261 * We do not return NULL from these functions if CONFIG_DEBUG_FS is not enabled 262 * so users have a chance to detect if there was a real error or not. We don't 263 * want to duplicate the design decision mistakes of procfs and devfs again. 264 */ 265 266 static inline struct dentry *debugfs_lookup(const char *name, 267 struct dentry *parent) 268 { 269 return ERR_PTR(-ENODEV); 270 } 271 272 static inline struct dentry *debugfs_create_file_aux(const char *name, 273 umode_t mode, struct dentry *parent, 274 void *data, void *aux, 275 const void *fops) 276 { 277 return ERR_PTR(-ENODEV); 278 } 279 280 static inline struct dentry *debugfs_create_file(const char *name, umode_t mode, 281 struct dentry *parent, void *data, 282 const void *fops) 283 { 284 return ERR_PTR(-ENODEV); 285 } 286 287 static inline struct dentry *debugfs_create_file_unsafe(const char *name, 288 umode_t mode, struct dentry *parent, 289 void *data, 290 const struct file_operations *fops) 291 { 292 return ERR_PTR(-ENODEV); 293 } 294 295 static inline void debugfs_create_file_size(const char *name, umode_t mode, 296 struct dentry *parent, void *data, 297 const struct file_operations *fops, 298 loff_t file_size) 299 { } 300 301 static inline struct dentry *debugfs_create_dir(const char *name, 302 struct dentry *parent) 303 { 304 return ERR_PTR(-ENODEV); 305 } 306 307 static inline struct dentry *debugfs_create_symlink(const char *name, 308 struct dentry *parent, 309 const char *dest) 310 { 311 return ERR_PTR(-ENODEV); 312 } 313 314 static inline struct dentry *debugfs_create_automount(const char *name, 315 struct dentry *parent, 316 debugfs_automount_t f, 317 void *data) 318 { 319 return ERR_PTR(-ENODEV); 320 } 321 322 static inline void debugfs_remove(struct dentry *dentry) 323 { } 324 325 static inline void debugfs_remove_recursive(struct dentry *dentry) 326 { } 327 328 static inline void debugfs_lookup_and_remove(const char *name, 329 struct dentry *parent) 330 { } 331 332 const struct file_operations *debugfs_real_fops(const struct file *filp); 333 void *debugfs_get_aux(const struct file *file); 334 335 static inline int debugfs_file_get(struct dentry *dentry) 336 { 337 return 0; 338 } 339 340 static inline void debugfs_file_put(struct dentry *dentry) 341 { } 342 343 static inline ssize_t debugfs_attr_read(struct file *file, char __user *buf, 344 size_t len, loff_t *ppos) 345 { 346 return -ENODEV; 347 } 348 349 static inline ssize_t debugfs_attr_write(struct file *file, 350 const char __user *buf, 351 size_t len, loff_t *ppos) 352 { 353 return -ENODEV; 354 } 355 356 static inline ssize_t debugfs_attr_write_signed(struct file *file, 357 const char __user *buf, 358 size_t len, loff_t *ppos) 359 { 360 return -ENODEV; 361 } 362 363 static inline int __printf(2, 3) debugfs_change_name(struct dentry *dentry, 364 const char *fmt, ...) 365 { 366 return -ENODEV; 367 } 368 369 static inline void debugfs_create_u8(const char *name, umode_t mode, 370 struct dentry *parent, u8 *value) { } 371 372 static inline void debugfs_create_u16(const char *name, umode_t mode, 373 struct dentry *parent, u16 *value) { } 374 375 static inline void debugfs_create_u32(const char *name, umode_t mode, 376 struct dentry *parent, u32 *value) { } 377 378 static inline void debugfs_create_u64(const char *name, umode_t mode, 379 struct dentry *parent, u64 *value) { } 380 381 static inline void debugfs_create_ulong(const char *name, umode_t mode, 382 struct dentry *parent, 383 unsigned long *value) { } 384 385 static inline void debugfs_create_x8(const char *name, umode_t mode, 386 struct dentry *parent, u8 *value) { } 387 388 static inline void debugfs_create_x16(const char *name, umode_t mode, 389 struct dentry *parent, u16 *value) { } 390 391 static inline void debugfs_create_x32(const char *name, umode_t mode, 392 struct dentry *parent, u32 *value) { } 393 394 static inline void debugfs_create_x64(const char *name, umode_t mode, 395 struct dentry *parent, u64 *value) { } 396 397 static inline void debugfs_create_size_t(const char *name, umode_t mode, 398 struct dentry *parent, size_t *value) 399 { } 400 401 static inline void debugfs_create_atomic_t(const char *name, umode_t mode, 402 struct dentry *parent, 403 atomic_t *value) 404 { } 405 406 static inline void debugfs_create_bool(const char *name, umode_t mode, 407 struct dentry *parent, bool *value) { } 408 409 static inline void debugfs_create_str(const char *name, umode_t mode, 410 struct dentry *parent, 411 char **value) 412 { } 413 414 static inline struct dentry *debugfs_create_blob(const char *name, umode_t mode, 415 struct dentry *parent, 416 struct debugfs_blob_wrapper *blob) 417 { 418 return ERR_PTR(-ENODEV); 419 } 420 421 static inline void debugfs_create_regset32(const char *name, umode_t mode, 422 struct dentry *parent, 423 struct debugfs_regset32 *regset) 424 { 425 } 426 427 static inline void debugfs_print_regs32(struct seq_file *s, const struct debugfs_reg32 *regs, 428 int nregs, void __iomem *base, char *prefix) 429 { 430 } 431 432 static inline bool debugfs_initialized(void) 433 { 434 return false; 435 } 436 437 static inline void debugfs_create_u32_array(const char *name, umode_t mode, 438 struct dentry *parent, 439 struct debugfs_u32_array *array) 440 { 441 } 442 443 static inline void debugfs_create_devm_seqfile(struct device *dev, 444 const char *name, 445 struct dentry *parent, 446 int (*read_fn)(struct seq_file *s, 447 void *data)) 448 { 449 } 450 451 static inline ssize_t debugfs_read_file_bool(struct file *file, 452 char __user *user_buf, 453 size_t count, loff_t *ppos) 454 { 455 return -ENODEV; 456 } 457 458 static inline ssize_t debugfs_write_file_bool(struct file *file, 459 const char __user *user_buf, 460 size_t count, loff_t *ppos) 461 { 462 return -ENODEV; 463 } 464 465 static inline ssize_t debugfs_read_file_str(struct file *file, 466 char __user *user_buf, 467 size_t count, loff_t *ppos) 468 { 469 return -ENODEV; 470 } 471 472 #endif 473 474 #define debugfs_create_file_aux_num(name, mode, parent, data, n, fops) \ 475 debugfs_create_file_aux(name, mode, parent, data, \ 476 (void *)(unsigned long)n, fops) 477 #define debugfs_get_aux_num(f) (unsigned long)debugfs_get_aux(f) 478 479 /** 480 * debugfs_create_xul - create a debugfs file that is used to read and write an 481 * unsigned long value, formatted in hexadecimal 482 * @name: a pointer to a string containing the name of the file to create. 483 * @mode: the permission that the file should have 484 * @parent: a pointer to the parent dentry for this file. This should be a 485 * directory dentry if set. If this parameter is %NULL, then the 486 * file will be created in the root of the debugfs filesystem. 487 * @value: a pointer to the variable that the file should read to and write 488 * from. 489 */ 490 static inline void debugfs_create_xul(const char *name, umode_t mode, 491 struct dentry *parent, 492 unsigned long *value) 493 { 494 if (sizeof(*value) == sizeof(u32)) 495 debugfs_create_x32(name, mode, parent, (u32 *)value); 496 else 497 debugfs_create_x64(name, mode, parent, (u64 *)value); 498 } 499 500 #endif 501