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