1*57443789SMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 2*57443789SMauro Carvalho Chehab.. include:: <isonum.txt> 3*57443789SMauro Carvalho Chehab 4*57443789SMauro Carvalho Chehab======= 5*57443789SMauro Carvalho ChehabDebugFS 6*57443789SMauro Carvalho Chehab======= 7*57443789SMauro Carvalho Chehab 8*57443789SMauro Carvalho ChehabCopyright |copy| 2009 Jonathan Corbet <corbet@lwn.net> 9*57443789SMauro Carvalho Chehab 10*57443789SMauro Carvalho ChehabDebugfs exists as a simple way for kernel developers to make information 11*57443789SMauro Carvalho Chehabavailable to user space. Unlike /proc, which is only meant for information 12*57443789SMauro Carvalho Chehababout a process, or sysfs, which has strict one-value-per-file rules, 13*57443789SMauro Carvalho Chehabdebugfs has no rules at all. Developers can put any information they want 14*57443789SMauro Carvalho Chehabthere. The debugfs filesystem is also intended to not serve as a stable 15*57443789SMauro Carvalho ChehabABI to user space; in theory, there are no stability constraints placed on 16*57443789SMauro Carvalho Chehabfiles exported there. The real world is not always so simple, though [1]_; 17*57443789SMauro Carvalho Chehabeven debugfs interfaces are best designed with the idea that they will need 18*57443789SMauro Carvalho Chehabto be maintained forever. 19*57443789SMauro Carvalho Chehab 20*57443789SMauro Carvalho ChehabDebugfs is typically mounted with a command like:: 21*57443789SMauro Carvalho Chehab 22*57443789SMauro Carvalho Chehab mount -t debugfs none /sys/kernel/debug 23*57443789SMauro Carvalho Chehab 24*57443789SMauro Carvalho Chehab(Or an equivalent /etc/fstab line). 25*57443789SMauro Carvalho ChehabThe debugfs root directory is accessible only to the root user by 26*57443789SMauro Carvalho Chehabdefault. To change access to the tree the "uid", "gid" and "mode" mount 27*57443789SMauro Carvalho Chehaboptions can be used. 28*57443789SMauro Carvalho Chehab 29*57443789SMauro Carvalho ChehabNote that the debugfs API is exported GPL-only to modules. 30*57443789SMauro Carvalho Chehab 31*57443789SMauro Carvalho ChehabCode using debugfs should include <linux/debugfs.h>. Then, the first order 32*57443789SMauro Carvalho Chehabof business will be to create at least one directory to hold a set of 33*57443789SMauro Carvalho Chehabdebugfs files:: 34*57443789SMauro Carvalho Chehab 35*57443789SMauro Carvalho Chehab struct dentry *debugfs_create_dir(const char *name, struct dentry *parent); 36*57443789SMauro Carvalho Chehab 37*57443789SMauro Carvalho ChehabThis call, if successful, will make a directory called name underneath the 38*57443789SMauro Carvalho Chehabindicated parent directory. If parent is NULL, the directory will be 39*57443789SMauro Carvalho Chehabcreated in the debugfs root. On success, the return value is a struct 40*57443789SMauro Carvalho Chehabdentry pointer which can be used to create files in the directory (and to 41*57443789SMauro Carvalho Chehabclean it up at the end). An ERR_PTR(-ERROR) return value indicates that 42*57443789SMauro Carvalho Chehabsomething went wrong. If ERR_PTR(-ENODEV) is returned, that is an 43*57443789SMauro Carvalho Chehabindication that the kernel has been built without debugfs support and none 44*57443789SMauro Carvalho Chehabof the functions described below will work. 45*57443789SMauro Carvalho Chehab 46*57443789SMauro Carvalho ChehabThe most general way to create a file within a debugfs directory is with:: 47*57443789SMauro Carvalho Chehab 48*57443789SMauro Carvalho Chehab struct dentry *debugfs_create_file(const char *name, umode_t mode, 49*57443789SMauro Carvalho Chehab struct dentry *parent, void *data, 50*57443789SMauro Carvalho Chehab const struct file_operations *fops); 51*57443789SMauro Carvalho Chehab 52*57443789SMauro Carvalho ChehabHere, name is the name of the file to create, mode describes the access 53*57443789SMauro Carvalho Chehabpermissions the file should have, parent indicates the directory which 54*57443789SMauro Carvalho Chehabshould hold the file, data will be stored in the i_private field of the 55*57443789SMauro Carvalho Chehabresulting inode structure, and fops is a set of file operations which 56*57443789SMauro Carvalho Chehabimplement the file's behavior. At a minimum, the read() and/or write() 57*57443789SMauro Carvalho Chehaboperations should be provided; others can be included as needed. Again, 58*57443789SMauro Carvalho Chehabthe return value will be a dentry pointer to the created file, 59*57443789SMauro Carvalho ChehabERR_PTR(-ERROR) on error, or ERR_PTR(-ENODEV) if debugfs support is 60*57443789SMauro Carvalho Chehabmissing. 61*57443789SMauro Carvalho Chehab 62*57443789SMauro Carvalho ChehabCreate a file with an initial size, the following function can be used 63*57443789SMauro Carvalho Chehabinstead:: 64*57443789SMauro Carvalho Chehab 65*57443789SMauro Carvalho Chehab struct dentry *debugfs_create_file_size(const char *name, umode_t mode, 66*57443789SMauro Carvalho Chehab struct dentry *parent, void *data, 67*57443789SMauro Carvalho Chehab const struct file_operations *fops, 68*57443789SMauro Carvalho Chehab loff_t file_size); 69*57443789SMauro Carvalho Chehab 70*57443789SMauro Carvalho Chehabfile_size is the initial file size. The other parameters are the same 71*57443789SMauro Carvalho Chehabas the function debugfs_create_file. 72*57443789SMauro Carvalho Chehab 73*57443789SMauro Carvalho ChehabIn a number of cases, the creation of a set of file operations is not 74*57443789SMauro Carvalho Chehabactually necessary; the debugfs code provides a number of helper functions 75*57443789SMauro Carvalho Chehabfor simple situations. Files containing a single integer value can be 76*57443789SMauro Carvalho Chehabcreated with any of:: 77*57443789SMauro Carvalho Chehab 78*57443789SMauro Carvalho Chehab void debugfs_create_u8(const char *name, umode_t mode, 79*57443789SMauro Carvalho Chehab struct dentry *parent, u8 *value); 80*57443789SMauro Carvalho Chehab void debugfs_create_u16(const char *name, umode_t mode, 81*57443789SMauro Carvalho Chehab struct dentry *parent, u16 *value); 82*57443789SMauro Carvalho Chehab struct dentry *debugfs_create_u32(const char *name, umode_t mode, 83*57443789SMauro Carvalho Chehab struct dentry *parent, u32 *value); 84*57443789SMauro Carvalho Chehab void debugfs_create_u64(const char *name, umode_t mode, 85*57443789SMauro Carvalho Chehab struct dentry *parent, u64 *value); 86*57443789SMauro Carvalho Chehab 87*57443789SMauro Carvalho ChehabThese files support both reading and writing the given value; if a specific 88*57443789SMauro Carvalho Chehabfile should not be written to, simply set the mode bits accordingly. The 89*57443789SMauro Carvalho Chehabvalues in these files are in decimal; if hexadecimal is more appropriate, 90*57443789SMauro Carvalho Chehabthe following functions can be used instead:: 91*57443789SMauro Carvalho Chehab 92*57443789SMauro Carvalho Chehab void debugfs_create_x8(const char *name, umode_t mode, 93*57443789SMauro Carvalho Chehab struct dentry *parent, u8 *value); 94*57443789SMauro Carvalho Chehab void debugfs_create_x16(const char *name, umode_t mode, 95*57443789SMauro Carvalho Chehab struct dentry *parent, u16 *value); 96*57443789SMauro Carvalho Chehab void debugfs_create_x32(const char *name, umode_t mode, 97*57443789SMauro Carvalho Chehab struct dentry *parent, u32 *value); 98*57443789SMauro Carvalho Chehab void debugfs_create_x64(const char *name, umode_t mode, 99*57443789SMauro Carvalho Chehab struct dentry *parent, u64 *value); 100*57443789SMauro Carvalho Chehab 101*57443789SMauro Carvalho ChehabThese functions are useful as long as the developer knows the size of the 102*57443789SMauro Carvalho Chehabvalue to be exported. Some types can have different widths on different 103*57443789SMauro Carvalho Chehabarchitectures, though, complicating the situation somewhat. There are 104*57443789SMauro Carvalho Chehabfunctions meant to help out in such special cases:: 105*57443789SMauro Carvalho Chehab 106*57443789SMauro Carvalho Chehab void debugfs_create_size_t(const char *name, umode_t mode, 107*57443789SMauro Carvalho Chehab struct dentry *parent, size_t *value); 108*57443789SMauro Carvalho Chehab 109*57443789SMauro Carvalho ChehabAs might be expected, this function will create a debugfs file to represent 110*57443789SMauro Carvalho Chehaba variable of type size_t. 111*57443789SMauro Carvalho Chehab 112*57443789SMauro Carvalho ChehabSimilarly, there are helpers for variables of type unsigned long, in decimal 113*57443789SMauro Carvalho Chehaband hexadecimal:: 114*57443789SMauro Carvalho Chehab 115*57443789SMauro Carvalho Chehab struct dentry *debugfs_create_ulong(const char *name, umode_t mode, 116*57443789SMauro Carvalho Chehab struct dentry *parent, 117*57443789SMauro Carvalho Chehab unsigned long *value); 118*57443789SMauro Carvalho Chehab void debugfs_create_xul(const char *name, umode_t mode, 119*57443789SMauro Carvalho Chehab struct dentry *parent, unsigned long *value); 120*57443789SMauro Carvalho Chehab 121*57443789SMauro Carvalho ChehabBoolean values can be placed in debugfs with:: 122*57443789SMauro Carvalho Chehab 123*57443789SMauro Carvalho Chehab struct dentry *debugfs_create_bool(const char *name, umode_t mode, 124*57443789SMauro Carvalho Chehab struct dentry *parent, bool *value); 125*57443789SMauro Carvalho Chehab 126*57443789SMauro Carvalho ChehabA read on the resulting file will yield either Y (for non-zero values) or 127*57443789SMauro Carvalho ChehabN, followed by a newline. If written to, it will accept either upper- or 128*57443789SMauro Carvalho Chehablower-case values, or 1 or 0. Any other input will be silently ignored. 129*57443789SMauro Carvalho Chehab 130*57443789SMauro Carvalho ChehabAlso, atomic_t values can be placed in debugfs with:: 131*57443789SMauro Carvalho Chehab 132*57443789SMauro Carvalho Chehab void debugfs_create_atomic_t(const char *name, umode_t mode, 133*57443789SMauro Carvalho Chehab struct dentry *parent, atomic_t *value) 134*57443789SMauro Carvalho Chehab 135*57443789SMauro Carvalho ChehabA read of this file will get atomic_t values, and a write of this file 136*57443789SMauro Carvalho Chehabwill set atomic_t values. 137*57443789SMauro Carvalho Chehab 138*57443789SMauro Carvalho ChehabAnother option is exporting a block of arbitrary binary data, with 139*57443789SMauro Carvalho Chehabthis structure and function:: 140*57443789SMauro Carvalho Chehab 141*57443789SMauro Carvalho Chehab struct debugfs_blob_wrapper { 142*57443789SMauro Carvalho Chehab void *data; 143*57443789SMauro Carvalho Chehab unsigned long size; 144*57443789SMauro Carvalho Chehab }; 145*57443789SMauro Carvalho Chehab 146*57443789SMauro Carvalho Chehab struct dentry *debugfs_create_blob(const char *name, umode_t mode, 147*57443789SMauro Carvalho Chehab struct dentry *parent, 148*57443789SMauro Carvalho Chehab struct debugfs_blob_wrapper *blob); 149*57443789SMauro Carvalho Chehab 150*57443789SMauro Carvalho ChehabA read of this file will return the data pointed to by the 151*57443789SMauro Carvalho Chehabdebugfs_blob_wrapper structure. Some drivers use "blobs" as a simple way 152*57443789SMauro Carvalho Chehabto return several lines of (static) formatted text output. This function 153*57443789SMauro Carvalho Chehabcan be used to export binary information, but there does not appear to be 154*57443789SMauro Carvalho Chehabany code which does so in the mainline. Note that all files created with 155*57443789SMauro Carvalho Chehabdebugfs_create_blob() are read-only. 156*57443789SMauro Carvalho Chehab 157*57443789SMauro Carvalho ChehabIf you want to dump a block of registers (something that happens quite 158*57443789SMauro Carvalho Chehaboften during development, even if little such code reaches mainline. 159*57443789SMauro Carvalho ChehabDebugfs offers two functions: one to make a registers-only file, and 160*57443789SMauro Carvalho Chehabanother to insert a register block in the middle of another sequential 161*57443789SMauro Carvalho Chehabfile:: 162*57443789SMauro Carvalho Chehab 163*57443789SMauro Carvalho Chehab struct debugfs_reg32 { 164*57443789SMauro Carvalho Chehab char *name; 165*57443789SMauro Carvalho Chehab unsigned long offset; 166*57443789SMauro Carvalho Chehab }; 167*57443789SMauro Carvalho Chehab 168*57443789SMauro Carvalho Chehab struct debugfs_regset32 { 169*57443789SMauro Carvalho Chehab struct debugfs_reg32 *regs; 170*57443789SMauro Carvalho Chehab int nregs; 171*57443789SMauro Carvalho Chehab void __iomem *base; 172*57443789SMauro Carvalho Chehab }; 173*57443789SMauro Carvalho Chehab 174*57443789SMauro Carvalho Chehab struct dentry *debugfs_create_regset32(const char *name, umode_t mode, 175*57443789SMauro Carvalho Chehab struct dentry *parent, 176*57443789SMauro Carvalho Chehab struct debugfs_regset32 *regset); 177*57443789SMauro Carvalho Chehab 178*57443789SMauro Carvalho Chehab void debugfs_print_regs32(struct seq_file *s, struct debugfs_reg32 *regs, 179*57443789SMauro Carvalho Chehab int nregs, void __iomem *base, char *prefix); 180*57443789SMauro Carvalho Chehab 181*57443789SMauro Carvalho ChehabThe "base" argument may be 0, but you may want to build the reg32 array 182*57443789SMauro Carvalho Chehabusing __stringify, and a number of register names (macros) are actually 183*57443789SMauro Carvalho Chehabbyte offsets over a base for the register block. 184*57443789SMauro Carvalho Chehab 185*57443789SMauro Carvalho ChehabIf you want to dump an u32 array in debugfs, you can create file with:: 186*57443789SMauro Carvalho Chehab 187*57443789SMauro Carvalho Chehab void debugfs_create_u32_array(const char *name, umode_t mode, 188*57443789SMauro Carvalho Chehab struct dentry *parent, 189*57443789SMauro Carvalho Chehab u32 *array, u32 elements); 190*57443789SMauro Carvalho Chehab 191*57443789SMauro Carvalho ChehabThe "array" argument provides data, and the "elements" argument is 192*57443789SMauro Carvalho Chehabthe number of elements in the array. Note: Once array is created its 193*57443789SMauro Carvalho Chehabsize can not be changed. 194*57443789SMauro Carvalho Chehab 195*57443789SMauro Carvalho ChehabThere is a helper function to create device related seq_file:: 196*57443789SMauro Carvalho Chehab 197*57443789SMauro Carvalho Chehab struct dentry *debugfs_create_devm_seqfile(struct device *dev, 198*57443789SMauro Carvalho Chehab const char *name, 199*57443789SMauro Carvalho Chehab struct dentry *parent, 200*57443789SMauro Carvalho Chehab int (*read_fn)(struct seq_file *s, 201*57443789SMauro Carvalho Chehab void *data)); 202*57443789SMauro Carvalho Chehab 203*57443789SMauro Carvalho ChehabThe "dev" argument is the device related to this debugfs file, and 204*57443789SMauro Carvalho Chehabthe "read_fn" is a function pointer which to be called to print the 205*57443789SMauro Carvalho Chehabseq_file content. 206*57443789SMauro Carvalho Chehab 207*57443789SMauro Carvalho ChehabThere are a couple of other directory-oriented helper functions:: 208*57443789SMauro Carvalho Chehab 209*57443789SMauro Carvalho Chehab struct dentry *debugfs_rename(struct dentry *old_dir, 210*57443789SMauro Carvalho Chehab struct dentry *old_dentry, 211*57443789SMauro Carvalho Chehab struct dentry *new_dir, 212*57443789SMauro Carvalho Chehab const char *new_name); 213*57443789SMauro Carvalho Chehab 214*57443789SMauro Carvalho Chehab struct dentry *debugfs_create_symlink(const char *name, 215*57443789SMauro Carvalho Chehab struct dentry *parent, 216*57443789SMauro Carvalho Chehab const char *target); 217*57443789SMauro Carvalho Chehab 218*57443789SMauro Carvalho ChehabA call to debugfs_rename() will give a new name to an existing debugfs 219*57443789SMauro Carvalho Chehabfile, possibly in a different directory. The new_name must not exist prior 220*57443789SMauro Carvalho Chehabto the call; the return value is old_dentry with updated information. 221*57443789SMauro Carvalho ChehabSymbolic links can be created with debugfs_create_symlink(). 222*57443789SMauro Carvalho Chehab 223*57443789SMauro Carvalho ChehabThere is one important thing that all debugfs users must take into account: 224*57443789SMauro Carvalho Chehabthere is no automatic cleanup of any directories created in debugfs. If a 225*57443789SMauro Carvalho Chehabmodule is unloaded without explicitly removing debugfs entries, the result 226*57443789SMauro Carvalho Chehabwill be a lot of stale pointers and no end of highly antisocial behavior. 227*57443789SMauro Carvalho ChehabSo all debugfs users - at least those which can be built as modules - must 228*57443789SMauro Carvalho Chehabbe prepared to remove all files and directories they create there. A file 229*57443789SMauro Carvalho Chehabcan be removed with:: 230*57443789SMauro Carvalho Chehab 231*57443789SMauro Carvalho Chehab void debugfs_remove(struct dentry *dentry); 232*57443789SMauro Carvalho Chehab 233*57443789SMauro Carvalho ChehabThe dentry value can be NULL or an error value, in which case nothing will 234*57443789SMauro Carvalho Chehabbe removed. 235*57443789SMauro Carvalho Chehab 236*57443789SMauro Carvalho ChehabOnce upon a time, debugfs users were required to remember the dentry 237*57443789SMauro Carvalho Chehabpointer for every debugfs file they created so that all files could be 238*57443789SMauro Carvalho Chehabcleaned up. We live in more civilized times now, though, and debugfs users 239*57443789SMauro Carvalho Chehabcan call:: 240*57443789SMauro Carvalho Chehab 241*57443789SMauro Carvalho Chehab void debugfs_remove_recursive(struct dentry *dentry); 242*57443789SMauro Carvalho Chehab 243*57443789SMauro Carvalho ChehabIf this function is passed a pointer for the dentry corresponding to the 244*57443789SMauro Carvalho Chehabtop-level directory, the entire hierarchy below that directory will be 245*57443789SMauro Carvalho Chehabremoved. 246*57443789SMauro Carvalho Chehab 247*57443789SMauro Carvalho Chehab.. [1] http://lwn.net/Articles/309298/ 248