]>
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 | ||
17 | (Or an equivalent /etc/fstab line). | |
18 | ||
19 | Note that the debugfs API is exported GPL-only to modules. | |
20 | ||
21 | Code using debugfs should include <linux/debugfs.h>. Then, the first order | |
22 | of business will be to create at least one directory to hold a set of | |
23 | debugfs files: | |
24 | ||
25 | struct dentry *debugfs_create_dir(const char *name, struct dentry *parent); | |
26 | ||
27 | This call, if successful, will make a directory called name underneath the | |
28 | indicated parent directory. If parent is NULL, the directory will be | |
29 | created in the debugfs root. On success, the return value is a struct | |
30 | dentry pointer which can be used to create files in the directory (and to | |
31 | clean it up at the end). A NULL return value indicates that something went | |
32 | wrong. If ERR_PTR(-ENODEV) is returned, that is an indication that the | |
33 | kernel has been built without debugfs support and none of the functions | |
34 | described below will work. | |
35 | ||
36 | The most general way to create a file within a debugfs directory is with: | |
37 | ||
38 | struct dentry *debugfs_create_file(const char *name, mode_t mode, | |
39 | struct dentry *parent, void *data, | |
40 | const struct file_operations *fops); | |
41 | ||
42 | Here, name is the name of the file to create, mode describes the access | |
43 | permissions the file should have, parent indicates the directory which | |
44 | should hold the file, data will be stored in the i_private field of the | |
45 | resulting inode structure, and fops is a set of file operations which | |
46 | implement the file's behavior. At a minimum, the read() and/or write() | |
47 | operations should be provided; others can be included as needed. Again, | |
48 | the return value will be a dentry pointer to the created file, NULL for | |
49 | error, or ERR_PTR(-ENODEV) if debugfs support is missing. | |
50 | ||
51 | In a number of cases, the creation of a set of file operations is not | |
52 | actually necessary; the debugfs code provides a number of helper functions | |
53 | for simple situations. Files containing a single integer value can be | |
54 | created with any of: | |
55 | ||
56 | struct dentry *debugfs_create_u8(const char *name, mode_t mode, | |
57 | struct dentry *parent, u8 *value); | |
58 | struct dentry *debugfs_create_u16(const char *name, mode_t mode, | |
59 | struct dentry *parent, u16 *value); | |
60 | struct dentry *debugfs_create_u32(const char *name, mode_t mode, | |
61 | struct dentry *parent, u32 *value); | |
62 | struct dentry *debugfs_create_u64(const char *name, mode_t mode, | |
63 | struct dentry *parent, u64 *value); | |
64 | ||
65 | These files support both reading and writing the given value; if a specific | |
66 | file should not be written to, simply set the mode bits accordingly. The | |
67 | values in these files are in decimal; if hexadecimal is more appropriate, | |
68 | the following functions can be used instead: | |
69 | ||
70 | struct dentry *debugfs_create_x8(const char *name, mode_t mode, | |
71 | struct dentry *parent, u8 *value); | |
72 | struct dentry *debugfs_create_x16(const char *name, mode_t mode, | |
73 | struct dentry *parent, u16 *value); | |
74 | struct dentry *debugfs_create_x32(const char *name, mode_t mode, | |
75 | struct dentry *parent, u32 *value); | |
76 | ||
77 | Note that there is no debugfs_create_x64(). | |
78 | ||
79 | These functions are useful as long as the developer knows the size of the | |
80 | value to be exported. Some types can have different widths on different | |
81 | architectures, though, complicating the situation somewhat. There is a | |
82 | function meant to help out in one special case: | |
83 | ||
84 | struct dentry *debugfs_create_size_t(const char *name, mode_t mode, | |
85 | struct dentry *parent, | |
86 | size_t *value); | |
87 | ||
88 | As might be expected, this function will create a debugfs file to represent | |
89 | a variable of type size_t. | |
90 | ||
91 | Boolean values can be placed in debugfs with: | |
92 | ||
93 | struct dentry *debugfs_create_bool(const char *name, mode_t mode, | |
94 | struct dentry *parent, u32 *value); | |
95 | ||
96 | A read on the resulting file will yield either Y (for non-zero values) or | |
97 | N, followed by a newline. If written to, it will accept either upper- or | |
98 | lower-case values, or 1 or 0. Any other input will be silently ignored. | |
99 | ||
100 | Finally, a block of arbitrary binary data can be exported with: | |
101 | ||
102 | struct debugfs_blob_wrapper { | |
103 | void *data; | |
104 | unsigned long size; | |
105 | }; | |
106 | ||
107 | struct dentry *debugfs_create_blob(const char *name, mode_t mode, | |
108 | struct dentry *parent, | |
109 | struct debugfs_blob_wrapper *blob); | |
110 | ||
111 | A read of this file will return the data pointed to by the | |
112 | debugfs_blob_wrapper structure. Some drivers use "blobs" as a simple way | |
113 | to return several lines of (static) formatted text output. This function | |
114 | can be used to export binary information, but there does not appear to be | |
115 | any code which does so in the mainline. Note that all files created with | |
116 | debugfs_create_blob() are read-only. | |
117 | ||
118 | There are a couple of other directory-oriented helper functions: | |
119 | ||
120 | struct dentry *debugfs_rename(struct dentry *old_dir, | |
121 | struct dentry *old_dentry, | |
122 | struct dentry *new_dir, | |
123 | const char *new_name); | |
124 | ||
125 | struct dentry *debugfs_create_symlink(const char *name, | |
126 | struct dentry *parent, | |
127 | const char *target); | |
128 | ||
129 | A call to debugfs_rename() will give a new name to an existing debugfs | |
130 | file, possibly in a different directory. The new_name must not exist prior | |
131 | to the call; the return value is old_dentry with updated information. | |
132 | Symbolic links can be created with debugfs_create_symlink(). | |
133 | ||
134 | There is one important thing that all debugfs users must take into account: | |
135 | there is no automatic cleanup of any directories created in debugfs. If a | |
136 | module is unloaded without explicitly removing debugfs entries, the result | |
137 | will be a lot of stale pointers and no end of highly antisocial behavior. | |
138 | So all debugfs users - at least those which can be built as modules - must | |
139 | be prepared to remove all files and directories they create there. A file | |
140 | can be removed with: | |
141 | ||
142 | void debugfs_remove(struct dentry *dentry); | |
143 | ||
144 | The dentry value can be NULL, in which case nothing will be removed. | |
145 | ||
146 | Once upon a time, debugfs users were required to remember the dentry | |
147 | pointer for every debugfs file they created so that all files could be | |
148 | cleaned up. We live in more civilized times now, though, and debugfs users | |
149 | can call: | |
150 | ||
151 | void debugfs_remove_recursive(struct dentry *dentry); | |
152 | ||
153 | If this function is passed a pointer for the dentry corresponding to the | |
154 | top-level directory, the entire hierarchy below that directory will be | |
155 | removed. | |
156 | ||
157 | Notes: | |
158 | [1] http://lwn.net/Articles/309298/ |