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