Commit | Line | Data |
---|---|---|
57443789 MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | .. include:: <isonum.txt> | |
3 | ||
4 | ======= | |
5 | DebugFS | |
6 | ======= | |
7 | ||
8 | Copyright |copy| 2009 Jonathan Corbet <corbet@lwn.net> | |
f89d7eaf JC |
9 | |
10 | Debugfs exists as a simple way for kernel developers to make information | |
11 | available to user space. Unlike /proc, which is only meant for information | |
12 | about a process, or sysfs, which has strict one-value-per-file rules, | |
13 | debugfs has no rules at all. Developers can put any information they want | |
14 | there. The debugfs filesystem is also intended to not serve as a stable | |
15 | ABI to user space; in theory, there are no stability constraints placed on | |
57443789 | 16 | files exported there. The real world is not always so simple, though [1]_; |
f89d7eaf JC |
17 | even debugfs interfaces are best designed with the idea that they will need |
18 | to be maintained forever. | |
19 | ||
57443789 | 20 | Debugfs is typically mounted with a command like:: |
f89d7eaf JC |
21 | |
22 | mount -t debugfs none /sys/kernel/debug | |
23 | ||
d6e48686 | 24 | (Or an equivalent /etc/fstab line). |
82aceae4 KC |
25 | The debugfs root directory is accessible only to the root user by |
26 | default. To change access to the tree the "uid", "gid" and "mode" mount | |
d6e48686 | 27 | options can be used. |
f89d7eaf JC |
28 | |
29 | Note that the debugfs API is exported GPL-only to modules. | |
30 | ||
31 | Code using debugfs should include <linux/debugfs.h>. Then, the first order | |
32 | of business will be to create at least one directory to hold a set of | |
57443789 | 33 | debugfs files:: |
f89d7eaf JC |
34 | |
35 | struct dentry *debugfs_create_dir(const char *name, struct dentry *parent); | |
36 | ||
37 | This call, if successful, will make a directory called name underneath the | |
38 | indicated parent directory. If parent is NULL, the directory will be | |
39 | created in the debugfs root. On success, the return value is a struct | |
40 | dentry pointer which can be used to create files in the directory (and to | |
9abb2499 RT |
41 | clean it up at the end). An ERR_PTR(-ERROR) return value indicates that |
42 | something went wrong. If ERR_PTR(-ENODEV) is returned, that is an | |
43 | indication that the kernel has been built without debugfs support and none | |
44 | of the functions described below will work. | |
f89d7eaf | 45 | |
57443789 | 46 | The most general way to create a file within a debugfs directory is with:: |
f89d7eaf | 47 | |
f4ae40a6 | 48 | struct dentry *debugfs_create_file(const char *name, umode_t mode, |
f89d7eaf JC |
49 | struct dentry *parent, void *data, |
50 | const struct file_operations *fops); | |
51 | ||
52 | Here, name is the name of the file to create, mode describes the access | |
53 | permissions the file should have, parent indicates the directory which | |
54 | should hold the file, data will be stored in the i_private field of the | |
55 | resulting inode structure, and fops is a set of file operations which | |
56 | implement the file's behavior. At a minimum, the read() and/or write() | |
57 | operations should be provided; others can be included as needed. Again, | |
9abb2499 RT |
58 | the return value will be a dentry pointer to the created file, |
59 | ERR_PTR(-ERROR) on error, or ERR_PTR(-ENODEV) if debugfs support is | |
60 | missing. | |
f89d7eaf | 61 | |
9e1aa7c8 | 62 | Create a file with an initial size, the following function can be used |
57443789 | 63 | instead:: |
9e1aa7c8 | 64 | |
526ee72d GKH |
65 | 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); | |
9e1aa7c8 WL |
69 | |
70 | file_size is the initial file size. The other parameters are the same | |
71 | as the function debugfs_create_file. | |
72 | ||
f89d7eaf JC |
73 | In a number of cases, the creation of a set of file operations is not |
74 | actually necessary; the debugfs code provides a number of helper functions | |
75 | for simple situations. Files containing a single integer value can be | |
57443789 | 76 | created with any of:: |
f89d7eaf | 77 | |
9655ac4a GKH |
78 | void debugfs_create_u8(const char *name, umode_t mode, |
79 | struct dentry *parent, u8 *value); | |
313f5dbb GKH |
80 | void debugfs_create_u16(const char *name, umode_t mode, |
81 | struct dentry *parent, u16 *value); | |
2b07021a GKH |
82 | void debugfs_create_u32(const char *name, umode_t mode, |
83 | struct dentry *parent, u32 *value); | |
ad26221f GKH |
84 | void debugfs_create_u64(const char *name, umode_t mode, |
85 | struct dentry *parent, u64 *value); | |
f89d7eaf JC |
86 | |
87 | These files support both reading and writing the given value; if a specific | |
88 | file should not be written to, simply set the mode bits accordingly. The | |
89 | values in these files are in decimal; if hexadecimal is more appropriate, | |
57443789 | 90 | the following functions can be used instead:: |
f89d7eaf | 91 | |
c7c11689 GKH |
92 | void debugfs_create_x8(const char *name, umode_t mode, |
93 | struct dentry *parent, u8 *value); | |
e40d38f2 GKH |
94 | void debugfs_create_x16(const char *name, umode_t mode, |
95 | struct dentry *parent, u16 *value); | |
f5cb0a7e GKH |
96 | void debugfs_create_x32(const char *name, umode_t mode, |
97 | struct dentry *parent, u32 *value); | |
0864c408 GKH |
98 | void debugfs_create_x64(const char *name, umode_t mode, |
99 | struct dentry *parent, u64 *value); | |
f89d7eaf JC |
100 | |
101 | These functions are useful as long as the developer knows the size of the | |
102 | value to be exported. Some types can have different widths on different | |
726ce477 | 103 | architectures, though, complicating the situation somewhat. There are |
57443789 | 104 | functions meant to help out in such special cases:: |
f89d7eaf | 105 | |
8e580263 GKH |
106 | void debugfs_create_size_t(const char *name, umode_t mode, |
107 | struct dentry *parent, size_t *value); | |
f89d7eaf JC |
108 | |
109 | As might be expected, this function will create a debugfs file to represent | |
110 | a variable of type size_t. | |
111 | ||
d3504757 | 112 | Similarly, there are helpers for variables of type unsigned long, in decimal |
57443789 | 113 | and hexadecimal:: |
726ce477 GU |
114 | |
115 | struct dentry *debugfs_create_ulong(const char *name, umode_t mode, | |
116 | struct dentry *parent, | |
117 | unsigned long *value); | |
d3504757 GU |
118 | void debugfs_create_xul(const char *name, umode_t mode, |
119 | struct dentry *parent, unsigned long *value); | |
726ce477 | 120 | |
57443789 | 121 | Boolean values can be placed in debugfs with:: |
f89d7eaf | 122 | |
f4ae40a6 | 123 | struct dentry *debugfs_create_bool(const char *name, umode_t mode, |
621a5f7a | 124 | struct dentry *parent, bool *value); |
f89d7eaf JC |
125 | |
126 | A read on the resulting file will yield either Y (for non-zero values) or | |
127 | N, followed by a newline. If written to, it will accept either upper- or | |
128 | lower-case values, or 1 or 0. Any other input will be silently ignored. | |
129 | ||
57443789 | 130 | Also, atomic_t values can be placed in debugfs with:: |
9e1aa7c8 | 131 | |
9927c6fa GKH |
132 | void debugfs_create_atomic_t(const char *name, umode_t mode, |
133 | struct dentry *parent, atomic_t *value) | |
9e1aa7c8 WL |
134 | |
135 | A read of this file will get atomic_t values, and a write of this file | |
136 | will set atomic_t values. | |
137 | ||
1a087c6a | 138 | Another option is exporting a block of arbitrary binary data, with |
57443789 | 139 | this structure and function:: |
f89d7eaf JC |
140 | |
141 | struct debugfs_blob_wrapper { | |
142 | void *data; | |
143 | unsigned long size; | |
144 | }; | |
145 | ||
f4ae40a6 | 146 | struct dentry *debugfs_create_blob(const char *name, umode_t mode, |
f89d7eaf JC |
147 | struct dentry *parent, |
148 | struct debugfs_blob_wrapper *blob); | |
149 | ||
150 | A read of this file will return the data pointed to by the | |
151 | debugfs_blob_wrapper structure. Some drivers use "blobs" as a simple way | |
152 | to return several lines of (static) formatted text output. This function | |
153 | can be used to export binary information, but there does not appear to be | |
154 | any code which does so in the mainline. Note that all files created with | |
155 | debugfs_create_blob() are read-only. | |
156 | ||
1a087c6a AR |
157 | If you want to dump a block of registers (something that happens quite |
158 | often during development, even if little such code reaches mainline. | |
159 | Debugfs offers two functions: one to make a registers-only file, and | |
160 | another to insert a register block in the middle of another sequential | |
57443789 | 161 | file:: |
1a087c6a AR |
162 | |
163 | struct debugfs_reg32 { | |
164 | char *name; | |
165 | unsigned long offset; | |
166 | }; | |
167 | ||
168 | struct debugfs_regset32 { | |
fd79cfd7 | 169 | const struct debugfs_reg32 *regs; |
1a087c6a AR |
170 | int nregs; |
171 | void __iomem *base; | |
fd79cfd7 | 172 | struct device *dev; /* Optional device for Runtime PM */ |
1a087c6a AR |
173 | }; |
174 | ||
ae91c925 GKH |
175 | debugfs_create_regset32(const char *name, umode_t mode, |
176 | struct dentry *parent, | |
177 | struct debugfs_regset32 *regset); | |
1a087c6a | 178 | |
fd79cfd7 | 179 | void debugfs_print_regs32(struct seq_file *s, const struct debugfs_reg32 *regs, |
1a087c6a AR |
180 | int nregs, void __iomem *base, char *prefix); |
181 | ||
182 | The "base" argument may be 0, but you may want to build the reg32 array | |
183 | using __stringify, and a number of register names (macros) are actually | |
184 | byte offsets over a base for the register block. | |
185 | ||
57443789 | 186 | If you want to dump an u32 array in debugfs, you can create file with:: |
9e1aa7c8 | 187 | |
a2b992c8 JK |
188 | struct debugfs_u32_array { |
189 | u32 *array; | |
190 | u32 n_elements; | |
191 | }; | |
192 | ||
c9c2c27d | 193 | void debugfs_create_u32_array(const char *name, umode_t mode, |
9e1aa7c8 | 194 | struct dentry *parent, |
a2b992c8 | 195 | struct debugfs_u32_array *array); |
9e1aa7c8 | 196 | |
a2b992c8 JK |
197 | The "array" argument wraps a pointer to the array's data and the number |
198 | of its elements. Note: Once array is created its size can not be changed. | |
9e1aa7c8 | 199 | |
57443789 | 200 | There is a helper function to create device related seq_file:: |
9e1aa7c8 | 201 | |
0d519cbf | 202 | void debugfs_create_devm_seqfile(struct device *dev, |
9e1aa7c8 WL |
203 | const char *name, |
204 | struct dentry *parent, | |
205 | int (*read_fn)(struct seq_file *s, | |
206 | void *data)); | |
207 | ||
208 | The "dev" argument is the device related to this debugfs file, and | |
209 | the "read_fn" is a function pointer which to be called to print the | |
210 | seq_file content. | |
1a087c6a | 211 | |
57443789 | 212 | There are a couple of other directory-oriented helper functions:: |
f89d7eaf | 213 | |
57443789 | 214 | struct dentry *debugfs_rename(struct dentry *old_dir, |
f89d7eaf | 215 | struct dentry *old_dentry, |
57443789 | 216 | struct dentry *new_dir, |
f89d7eaf JC |
217 | const char *new_name); |
218 | ||
57443789 | 219 | struct dentry *debugfs_create_symlink(const char *name, |
f89d7eaf JC |
220 | struct dentry *parent, |
221 | const char *target); | |
222 | ||
223 | A call to debugfs_rename() will give a new name to an existing debugfs | |
224 | file, possibly in a different directory. The new_name must not exist prior | |
225 | to the call; the return value is old_dentry with updated information. | |
226 | Symbolic links can be created with debugfs_create_symlink(). | |
227 | ||
228 | There is one important thing that all debugfs users must take into account: | |
229 | there is no automatic cleanup of any directories created in debugfs. If a | |
230 | module is unloaded without explicitly removing debugfs entries, the result | |
231 | will be a lot of stale pointers and no end of highly antisocial behavior. | |
232 | So all debugfs users - at least those which can be built as modules - must | |
233 | be prepared to remove all files and directories they create there. A file | |
57443789 | 234 | can be removed with:: |
f89d7eaf JC |
235 | |
236 | void debugfs_remove(struct dentry *dentry); | |
237 | ||
9abb2499 RT |
238 | The dentry value can be NULL or an error value, in which case nothing will |
239 | be removed. | |
f89d7eaf JC |
240 | |
241 | Once upon a time, debugfs users were required to remember the dentry | |
242 | pointer for every debugfs file they created so that all files could be | |
243 | cleaned up. We live in more civilized times now, though, and debugfs users | |
57443789 | 244 | can call:: |
f89d7eaf JC |
245 | |
246 | void debugfs_remove_recursive(struct dentry *dentry); | |
247 | ||
248 | If this function is passed a pointer for the dentry corresponding to the | |
249 | top-level directory, the entire hierarchy below that directory will be | |
250 | removed. | |
251 | ||
57443789 | 252 | .. [1] http://lwn.net/Articles/309298/ |