blob: db9ea085404033d7723ccd2ba02c4abdab8b0712 [file] [log] [blame]
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +01001.. SPDX-License-Identifier: GPL-2.0
2.. include:: <isonum.txt>
3
4=======
5DebugFS
6=======
7
8Copyright |copy| 2009 Jonathan Corbet <[email protected]>
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -06009
10Debugfs exists as a simple way for kernel developers to make information
11available to user space. Unlike /proc, which is only meant for information
12about a process, or sysfs, which has strict one-value-per-file rules,
13debugfs has no rules at all. Developers can put any information they want
14there. The debugfs filesystem is also intended to not serve as a stable
15ABI to user space; in theory, there are no stability constraints placed on
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +010016files exported there. The real world is not always so simple, though [1]_;
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060017even debugfs interfaces are best designed with the idea that they will need
18to be maintained forever.
19
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +010020Debugfs is typically mounted with a command like::
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060021
22 mount -t debugfs none /sys/kernel/debug
23
Ludwig Nusseld6e48682012-01-25 11:52:28 +010024(Or an equivalent /etc/fstab line).
Kees Cook82aceae42012-08-27 13:32:15 -070025The debugfs root directory is accessible only to the root user by
26default. To change access to the tree the "uid", "gid" and "mode" mount
Ludwig Nusseld6e48682012-01-25 11:52:28 +010027options can be used.
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060028
29Note that the debugfs API is exported GPL-only to modules.
30
31Code using debugfs should include <linux/debugfs.h>. Then, the first order
32of business will be to create at least one directory to hold a set of
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +010033debugfs files::
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060034
35 struct dentry *debugfs_create_dir(const char *name, struct dentry *parent);
36
37This call, if successful, will make a directory called name underneath the
38indicated parent directory. If parent is NULL, the directory will be
39created in the debugfs root. On success, the return value is a struct
40dentry pointer which can be used to create files in the directory (and to
Ronald Tschalär9abb2492019-04-15 01:25:05 -070041clean it up at the end). An ERR_PTR(-ERROR) return value indicates that
42something went wrong. If ERR_PTR(-ENODEV) is returned, that is an
43indication that the kernel has been built without debugfs support and none
44of the functions described below will work.
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060045
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +010046The most general way to create a file within a debugfs directory is with::
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060047
Al Virof4ae40a62011-07-24 04:33:43 -040048 struct dentry *debugfs_create_file(const char *name, umode_t mode,
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060049 struct dentry *parent, void *data,
50 const struct file_operations *fops);
51
52Here, name is the name of the file to create, mode describes the access
53permissions the file should have, parent indicates the directory which
54should hold the file, data will be stored in the i_private field of the
55resulting inode structure, and fops is a set of file operations which
56implement the file's behavior. At a minimum, the read() and/or write()
57operations should be provided; others can be included as needed. Again,
Ronald Tschalär9abb2492019-04-15 01:25:05 -070058the return value will be a dentry pointer to the created file,
59ERR_PTR(-ERROR) on error, or ERR_PTR(-ENODEV) if debugfs support is
60missing.
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060061
Wang Long9e1aa7c2015-07-16 06:31:16 +000062Create a file with an initial size, the following function can be used
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +010063instead::
Wang Long9e1aa7c2015-07-16 06:31:16 +000064
Greg Kroah-Hartman526ee722020-03-09 17:36:40 +010065 void debugfs_create_file_size(const char *name, umode_t mode,
66 struct dentry *parent, void *data,
67 const struct file_operations *fops,
68 loff_t file_size);
Wang Long9e1aa7c2015-07-16 06:31:16 +000069
70file_size is the initial file size. The other parameters are the same
71as the function debugfs_create_file.
72
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060073In a number of cases, the creation of a set of file operations is not
74actually necessary; the debugfs code provides a number of helper functions
75for simple situations. Files containing a single integer value can be
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +010076created with any of::
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060077
Greg Kroah-Hartman9655ac42019-10-11 15:29:24 +020078 void debugfs_create_u8(const char *name, umode_t mode,
79 struct dentry *parent, u8 *value);
Greg Kroah-Hartman313f5db2019-10-11 15:29:25 +020080 void debugfs_create_u16(const char *name, umode_t mode,
81 struct dentry *parent, u16 *value);
Al Virof4ae40a62011-07-24 04:33:43 -040082 struct dentry *debugfs_create_u32(const char *name, umode_t mode,
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060083 struct dentry *parent, u32 *value);
Greg Kroah-Hartmanad262212019-10-11 15:29:26 +020084 void debugfs_create_u64(const char *name, umode_t mode,
85 struct dentry *parent, u64 *value);
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060086
87These files support both reading and writing the given value; if a specific
88file should not be written to, simply set the mode bits accordingly. The
89values in these files are in decimal; if hexadecimal is more appropriate,
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +010090the following functions can be used instead::
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -060091
Greg Kroah-Hartmanc7c11682019-10-11 15:29:28 +020092 void debugfs_create_x8(const char *name, umode_t mode,
93 struct dentry *parent, u8 *value);
Greg Kroah-Hartmane40d38f2019-10-11 15:29:29 +020094 void debugfs_create_x16(const char *name, umode_t mode,
95 struct dentry *parent, u16 *value);
Greg Kroah-Hartmanf5cb0a72019-10-11 15:29:30 +020096 void debugfs_create_x32(const char *name, umode_t mode,
97 struct dentry *parent, u32 *value);
Greg Kroah-Hartman0864c402019-10-11 15:29:31 +020098 void debugfs_create_x64(const char *name, umode_t mode,
99 struct dentry *parent, u64 *value);
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600100
101These functions are useful as long as the developer knows the size of the
102value to be exported. Some types can have different widths on different
Geert Uytterhoeven726ce472019-10-21 17:06:45 +0200103architectures, though, complicating the situation somewhat. There are
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100104functions meant to help out in such special cases::
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600105
Greg Kroah-Hartman8e580262019-10-11 15:29:27 +0200106 void debugfs_create_size_t(const char *name, umode_t mode,
107 struct dentry *parent, size_t *value);
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600108
109As might be expected, this function will create a debugfs file to represent
110a variable of type size_t.
111
Geert Uytterhoevend3504752019-10-25 11:41:24 +0200112Similarly, there are helpers for variables of type unsigned long, in decimal
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100113and hexadecimal::
Geert Uytterhoeven726ce472019-10-21 17:06:45 +0200114
115 struct dentry *debugfs_create_ulong(const char *name, umode_t mode,
116 struct dentry *parent,
117 unsigned long *value);
Geert Uytterhoevend3504752019-10-25 11:41:24 +0200118 void debugfs_create_xul(const char *name, umode_t mode,
119 struct dentry *parent, unsigned long *value);
Geert Uytterhoeven726ce472019-10-21 17:06:45 +0200120
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100121Boolean values can be placed in debugfs with::
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600122
Al Virof4ae40a62011-07-24 04:33:43 -0400123 struct dentry *debugfs_create_bool(const char *name, umode_t mode,
Viresh Kumar621a5f72015-09-26 15:04:07 -0700124 struct dentry *parent, bool *value);
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600125
126A read on the resulting file will yield either Y (for non-zero values) or
127N, followed by a newline. If written to, it will accept either upper- or
128lower-case values, or 1 or 0. Any other input will be silently ignored.
129
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100130Also, atomic_t values can be placed in debugfs with::
Wang Long9e1aa7c2015-07-16 06:31:16 +0000131
Greg Kroah-Hartman9927c6f2019-10-16 06:03:32 -0700132 void debugfs_create_atomic_t(const char *name, umode_t mode,
133 struct dentry *parent, atomic_t *value)
Wang Long9e1aa7c2015-07-16 06:31:16 +0000134
135A read of this file will get atomic_t values, and a write of this file
136will set atomic_t values.
137
Alessandro Rubini1a087c62011-11-18 14:50:21 +0100138Another option is exporting a block of arbitrary binary data, with
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100139this structure and function::
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600140
141 struct debugfs_blob_wrapper {
142 void *data;
143 unsigned long size;
144 };
145
Al Virof4ae40a62011-07-24 04:33:43 -0400146 struct dentry *debugfs_create_blob(const char *name, umode_t mode,
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600147 struct dentry *parent,
148 struct debugfs_blob_wrapper *blob);
149
150A read of this file will return the data pointed to by the
151debugfs_blob_wrapper structure. Some drivers use "blobs" as a simple way
152to return several lines of (static) formatted text output. This function
153can be used to export binary information, but there does not appear to be
154any code which does so in the mainline. Note that all files created with
155debugfs_create_blob() are read-only.
156
Alessandro Rubini1a087c62011-11-18 14:50:21 +0100157If you want to dump a block of registers (something that happens quite
158often during development, even if little such code reaches mainline.
159Debugfs offers two functions: one to make a registers-only file, and
160another to insert a register block in the middle of another sequential
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100161file::
Alessandro Rubini1a087c62011-11-18 14:50:21 +0100162
163 struct debugfs_reg32 {
164 char *name;
165 unsigned long offset;
166 };
167
168 struct debugfs_regset32 {
169 struct debugfs_reg32 *regs;
170 int nregs;
171 void __iomem *base;
172 };
173
Greg Kroah-Hartmanae91c922019-11-22 11:44:53 +0100174 debugfs_create_regset32(const char *name, umode_t mode,
175 struct dentry *parent,
176 struct debugfs_regset32 *regset);
Alessandro Rubini1a087c62011-11-18 14:50:21 +0100177
Joe Perches97615362014-09-29 16:08:26 -0700178 void debugfs_print_regs32(struct seq_file *s, struct debugfs_reg32 *regs,
Alessandro Rubini1a087c62011-11-18 14:50:21 +0100179 int nregs, void __iomem *base, char *prefix);
180
181The "base" argument may be 0, but you may want to build the reg32 array
182using __stringify, and a number of register names (macros) are actually
183byte offsets over a base for the register block.
184
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100185If you want to dump an u32 array in debugfs, you can create file with::
Wang Long9e1aa7c2015-07-16 06:31:16 +0000186
Greg Kroah-Hartmanc9c2c272019-04-16 15:46:55 +0200187 void debugfs_create_u32_array(const char *name, umode_t mode,
Wang Long9e1aa7c2015-07-16 06:31:16 +0000188 struct dentry *parent,
189 u32 *array, u32 elements);
190
191The "array" argument provides data, and the "elements" argument is
192the number of elements in the array. Note: Once array is created its
193size can not be changed.
194
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100195There is a helper function to create device related seq_file::
Wang Long9e1aa7c2015-07-16 06:31:16 +0000196
197 struct dentry *debugfs_create_devm_seqfile(struct device *dev,
198 const char *name,
199 struct dentry *parent,
200 int (*read_fn)(struct seq_file *s,
201 void *data));
202
203The "dev" argument is the device related to this debugfs file, and
204the "read_fn" is a function pointer which to be called to print the
205seq_file content.
Alessandro Rubini1a087c62011-11-18 14:50:21 +0100206
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100207There are a couple of other directory-oriented helper functions::
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600208
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100209 struct dentry *debugfs_rename(struct dentry *old_dir,
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600210 struct dentry *old_dentry,
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100211 struct dentry *new_dir,
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600212 const char *new_name);
213
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100214 struct dentry *debugfs_create_symlink(const char *name,
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600215 struct dentry *parent,
216 const char *target);
217
218A call to debugfs_rename() will give a new name to an existing debugfs
219file, possibly in a different directory. The new_name must not exist prior
220to the call; the return value is old_dentry with updated information.
221Symbolic links can be created with debugfs_create_symlink().
222
223There is one important thing that all debugfs users must take into account:
224there is no automatic cleanup of any directories created in debugfs. If a
225module is unloaded without explicitly removing debugfs entries, the result
226will be a lot of stale pointers and no end of highly antisocial behavior.
227So all debugfs users - at least those which can be built as modules - must
228be prepared to remove all files and directories they create there. A file
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100229can be removed with::
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600230
231 void debugfs_remove(struct dentry *dentry);
232
Ronald Tschalär9abb2492019-04-15 01:25:05 -0700233The dentry value can be NULL or an error value, in which case nothing will
234be removed.
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600235
236Once upon a time, debugfs users were required to remember the dentry
237pointer for every debugfs file they created so that all files could be
238cleaned up. We live in more civilized times now, though, and debugfs users
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100239can call::
Jonathan Corbetf89d7ea2009-06-04 16:35:25 -0600240
241 void debugfs_remove_recursive(struct dentry *dentry);
242
243If this function is passed a pointer for the dentry corresponding to the
244top-level directory, the entire hierarchy below that directory will be
245removed.
246
Mauro Carvalho Chehab574437892020-02-17 17:11:57 +0100247.. [1] http://lwn.net/Articles/309298/