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 | |
34 | clean it up at the end). A NULL return value indicates that something went | |
35 | wrong. If ERR_PTR(-ENODEV) is returned, that is an indication that the | |
36 | kernel has been built without debugfs support and none of the functions | |
37 | described below will work. | |
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, | |
51 | the return value will be a dentry pointer to the created file, NULL for | |
52 | error, or ERR_PTR(-ENODEV) if debugfs support is missing. | |
53 | ||
9e1aa7c8 WL |
54 | Create a file with an initial size, the following function can be used |
55 | instead: | |
56 | ||
57 | struct dentry *debugfs_create_file_size(const char *name, umode_t mode, | |
58 | struct dentry *parent, void *data, | |
59 | const struct file_operations *fops, | |
60 | loff_t file_size); | |
61 | ||
62 | file_size is the initial file size. The other parameters are the same | |
63 | as the function debugfs_create_file. | |
64 | ||
f89d7eaf JC |
65 | In a number of cases, the creation of a set of file operations is not |
66 | actually necessary; the debugfs code provides a number of helper functions | |
67 | for simple situations. Files containing a single integer value can be | |
68 | created with any of: | |
69 | ||
f4ae40a6 | 70 | struct dentry *debugfs_create_u8(const char *name, umode_t mode, |
f89d7eaf | 71 | struct dentry *parent, u8 *value); |
f4ae40a6 | 72 | struct dentry *debugfs_create_u16(const char *name, umode_t mode, |
f89d7eaf | 73 | struct dentry *parent, u16 *value); |
f4ae40a6 | 74 | struct dentry *debugfs_create_u32(const char *name, umode_t mode, |
f89d7eaf | 75 | struct dentry *parent, u32 *value); |
f4ae40a6 | 76 | struct dentry *debugfs_create_u64(const char *name, umode_t mode, |
f89d7eaf JC |
77 | struct dentry *parent, u64 *value); |
78 | ||
79 | These files support both reading and writing the given value; if a specific | |
80 | file should not be written to, simply set the mode bits accordingly. The | |
81 | values in these files are in decimal; if hexadecimal is more appropriate, | |
82 | the following functions can be used instead: | |
83 | ||
f4ae40a6 | 84 | struct dentry *debugfs_create_x8(const char *name, umode_t mode, |
f89d7eaf | 85 | struct dentry *parent, u8 *value); |
f4ae40a6 | 86 | struct dentry *debugfs_create_x16(const char *name, umode_t mode, |
f89d7eaf | 87 | struct dentry *parent, u16 *value); |
f4ae40a6 | 88 | struct dentry *debugfs_create_x32(const char *name, umode_t mode, |
f89d7eaf | 89 | struct dentry *parent, u32 *value); |
f4ae40a6 | 90 | struct dentry *debugfs_create_x64(const char *name, umode_t mode, |
d0a54263 | 91 | struct dentry *parent, u64 *value); |
f89d7eaf JC |
92 | |
93 | These functions are useful as long as the developer knows the size of the | |
94 | value to be exported. Some types can have different widths on different | |
95 | architectures, though, complicating the situation somewhat. There is a | |
96 | function meant to help out in one special case: | |
97 | ||
f4ae40a6 | 98 | struct dentry *debugfs_create_size_t(const char *name, umode_t mode, |
f89d7eaf JC |
99 | struct dentry *parent, |
100 | size_t *value); | |
101 | ||
102 | As might be expected, this function will create a debugfs file to represent | |
103 | a variable of type size_t. | |
104 | ||
105 | Boolean values can be placed in debugfs with: | |
106 | ||
f4ae40a6 | 107 | struct dentry *debugfs_create_bool(const char *name, umode_t mode, |
621a5f7a | 108 | struct dentry *parent, bool *value); |
f89d7eaf JC |
109 | |
110 | A read on the resulting file will yield either Y (for non-zero values) or | |
111 | N, followed by a newline. If written to, it will accept either upper- or | |
112 | lower-case values, or 1 or 0. Any other input will be silently ignored. | |
113 | ||
9e1aa7c8 WL |
114 | Also, atomic_t values can be placed in debugfs with: |
115 | ||
116 | struct dentry *debugfs_create_atomic_t(const char *name, umode_t mode, | |
117 | struct dentry *parent, atomic_t *value) | |
118 | ||
119 | A read of this file will get atomic_t values, and a write of this file | |
120 | will set atomic_t values. | |
121 | ||
1a087c6a AR |
122 | Another option is exporting a block of arbitrary binary data, with |
123 | this structure and function: | |
f89d7eaf JC |
124 | |
125 | struct debugfs_blob_wrapper { | |
126 | void *data; | |
127 | unsigned long size; | |
128 | }; | |
129 | ||
f4ae40a6 | 130 | struct dentry *debugfs_create_blob(const char *name, umode_t mode, |
f89d7eaf JC |
131 | struct dentry *parent, |
132 | struct debugfs_blob_wrapper *blob); | |
133 | ||
134 | A read of this file will return the data pointed to by the | |
135 | debugfs_blob_wrapper structure. Some drivers use "blobs" as a simple way | |
136 | to return several lines of (static) formatted text output. This function | |
137 | can be used to export binary information, but there does not appear to be | |
138 | any code which does so in the mainline. Note that all files created with | |
139 | debugfs_create_blob() are read-only. | |
140 | ||
1a087c6a AR |
141 | If you want to dump a block of registers (something that happens quite |
142 | often during development, even if little such code reaches mainline. | |
143 | Debugfs offers two functions: one to make a registers-only file, and | |
144 | another to insert a register block in the middle of another sequential | |
145 | file. | |
146 | ||
147 | struct debugfs_reg32 { | |
148 | char *name; | |
149 | unsigned long offset; | |
150 | }; | |
151 | ||
152 | struct debugfs_regset32 { | |
153 | struct debugfs_reg32 *regs; | |
154 | int nregs; | |
155 | void __iomem *base; | |
156 | }; | |
157 | ||
88187398 | 158 | struct dentry *debugfs_create_regset32(const char *name, umode_t mode, |
1a087c6a AR |
159 | struct dentry *parent, |
160 | struct debugfs_regset32 *regset); | |
161 | ||
9761536e | 162 | void debugfs_print_regs32(struct seq_file *s, struct debugfs_reg32 *regs, |
1a087c6a AR |
163 | int nregs, void __iomem *base, char *prefix); |
164 | ||
165 | The "base" argument may be 0, but you may want to build the reg32 array | |
166 | using __stringify, and a number of register names (macros) are actually | |
167 | byte offsets over a base for the register block. | |
168 | ||
9e1aa7c8 WL |
169 | If you want to dump an u32 array in debugfs, you can create file with: |
170 | ||
171 | struct dentry *debugfs_create_u32_array(const char *name, umode_t mode, | |
172 | struct dentry *parent, | |
173 | u32 *array, u32 elements); | |
174 | ||
175 | The "array" argument provides data, and the "elements" argument is | |
176 | the number of elements in the array. Note: Once array is created its | |
177 | size can not be changed. | |
178 | ||
179 | There is a helper function to create device related seq_file: | |
180 | ||
181 | struct dentry *debugfs_create_devm_seqfile(struct device *dev, | |
182 | const char *name, | |
183 | struct dentry *parent, | |
184 | int (*read_fn)(struct seq_file *s, | |
185 | void *data)); | |
186 | ||
187 | The "dev" argument is the device related to this debugfs file, and | |
188 | the "read_fn" is a function pointer which to be called to print the | |
189 | seq_file content. | |
1a087c6a | 190 | |
f89d7eaf JC |
191 | There are a couple of other directory-oriented helper functions: |
192 | ||
193 | struct dentry *debugfs_rename(struct dentry *old_dir, | |
194 | struct dentry *old_dentry, | |
195 | struct dentry *new_dir, | |
196 | const char *new_name); | |
197 | ||
198 | struct dentry *debugfs_create_symlink(const char *name, | |
199 | struct dentry *parent, | |
200 | const char *target); | |
201 | ||
202 | A call to debugfs_rename() will give a new name to an existing debugfs | |
203 | file, possibly in a different directory. The new_name must not exist prior | |
204 | to the call; the return value is old_dentry with updated information. | |
205 | Symbolic links can be created with debugfs_create_symlink(). | |
206 | ||
207 | There is one important thing that all debugfs users must take into account: | |
208 | there is no automatic cleanup of any directories created in debugfs. If a | |
209 | module is unloaded without explicitly removing debugfs entries, the result | |
210 | will be a lot of stale pointers and no end of highly antisocial behavior. | |
211 | So all debugfs users - at least those which can be built as modules - must | |
212 | be prepared to remove all files and directories they create there. A file | |
213 | can be removed with: | |
214 | ||
215 | void debugfs_remove(struct dentry *dentry); | |
216 | ||
217 | The dentry value can be NULL, in which case nothing will be removed. | |
218 | ||
219 | Once upon a time, debugfs users were required to remember the dentry | |
220 | pointer for every debugfs file they created so that all files could be | |
221 | cleaned up. We live in more civilized times now, though, and debugfs users | |
222 | can call: | |
223 | ||
224 | void debugfs_remove_recursive(struct dentry *dentry); | |
225 | ||
226 | If this function is passed a pointer for the dentry corresponding to the | |
227 | top-level directory, the entire hierarchy below that directory will be | |
228 | removed. | |
229 | ||
230 | Notes: | |
231 | [1] http://lwn.net/Articles/309298/ |