1 .. SPDX-License-Identifier: GPL-2.0
2 .. include:: <isonum.txt>
3
4 =======
5 DebugFS
6 =======
7
8 Copyright |copy| 2009 Jonathan Corbet <corbet@l
9
10 Debugfs exists as a simple way for kernel deve
11 available to user space. Unlike /proc, which
12 about a process, or sysfs, which has strict on
13 debugfs has no rules at all. Developers can p
14 there. The debugfs filesystem is also intende
15 ABI to user space; in theory, there are no sta
16 files exported there. The real world is not a
17 even debugfs interfaces are best designed with
18 to be maintained forever.
19
20 Debugfs is typically mounted with a command li
21
22 mount -t debugfs none /sys/kernel/debug
23
24 (Or an equivalent /etc/fstab line).
25 The debugfs root directory is accessible only
26 default. To change access to the tree the "uid
27 options can be used.
28
29 Note that the debugfs API is exported GPL-only
30
31 Code using debugfs should include <linux/debug
32 of business will be to create at least one dir
33 debugfs files::
34
35 struct dentry *debugfs_create_dir(const ch
36
37 This call, if successful, will make a director
38 indicated parent directory. If parent is NULL
39 created in the debugfs root. On success, the
40 dentry pointer which can be used to create fil
41 clean it up at the end). An ERR_PTR(-ERROR) r
42 something went wrong. If ERR_PTR(-ENODEV) is
43 indication that the kernel has been built with
44 of the functions described below will work.
45
46 The most general way to create a file within a
47
48 struct dentry *debugfs_create_file(const c
49 struct
50 const s
51
52 Here, name is the name of the file to create,
53 permissions the file should have, parent indic
54 should hold the file, data will be stored in t
55 resulting inode structure, and fops is a set o
56 implement the file's behavior. At a minimum,
57 operations should be provided; others can be i
58 the return value will be a dentry pointer to t
59 ERR_PTR(-ERROR) on error, or ERR_PTR(-ENODEV)
60 missing.
61
62 Create a file with an initial size, the follow
63 instead::
64
65 void debugfs_create_file_size(const char *
66 struct dentr
67 const struct
68 loff_t file_
69
70 file_size is the initial file size. The other
71 as the function debugfs_create_file.
72
73 In a number of cases, the creation of a set of
74 actually necessary; the debugfs code provides
75 for simple situations. Files containing a sin
76 created with any of::
77
78 void debugfs_create_u8(const char *name, u
79 struct dentry *pare
80 void debugfs_create_u16(const char *name,
81 struct dentry *par
82 void debugfs_create_u32(const char *name,
83 struct dentry *par
84 void debugfs_create_u64(const char *name,
85 struct dentry *par
86
87 These files support both reading and writing t
88 file should not be written to, simply set the
89 values in these files are in decimal; if hexad
90 the following functions can be used instead::
91
92 void debugfs_create_x8(const char *name, u
93 struct dentry *pare
94 void debugfs_create_x16(const char *name,
95 struct dentry *par
96 void debugfs_create_x32(const char *name,
97 struct dentry *par
98 void debugfs_create_x64(const char *name,
99 struct dentry *par
100
101 These functions are useful as long as the deve
102 value to be exported. Some types can have dif
103 architectures, though, complicating the situat
104 functions meant to help out in such special ca
105
106 void debugfs_create_size_t(const char *nam
107 struct dentry *
108
109 As might be expected, this function will creat
110 a variable of type size_t.
111
112 Similarly, there are helpers for variables of
113 and hexadecimal::
114
115 struct dentry *debugfs_create_ulong(const
116 struct
117 unsign
118 void debugfs_create_xul(const char *name,
119 struct dentry *par
120
121 Boolean values can be placed in debugfs with::
122
123 void debugfs_create_bool(const char *name,
124 struct dentry *pa
125
126 A read on the resulting file will yield either
127 N, followed by a newline. If written to, it w
128 lower-case values, or 1 or 0. Any other input
129
130 Also, atomic_t values can be placed in debugfs
131
132 void debugfs_create_atomic_t(const char *n
133 struct dentry
134
135 A read of this file will get atomic_t values,
136 will set atomic_t values.
137
138 Another option is exporting a block of arbitra
139 this structure and function::
140
141 struct debugfs_blob_wrapper {
142 void *data;
143 unsigned long size;
144 };
145
146 struct dentry *debugfs_create_blob(const c
147 struct
148 struct
149
150 A read of this file will return the data point
151 debugfs_blob_wrapper structure. Some drivers
152 to return several lines of (static) formatted
153 can be used to export binary information, but
154 any code which does so in the mainline. Note
155 debugfs_create_blob() are read-only.
156
157 If you want to dump a block of registers (some
158 often during development, even if little such
159 debugfs offers two functions: one to make a re
160 another to insert a register block in the midd
161 file::
162
163 struct debugfs_reg32 {
164 char *name;
165 unsigned long offset;
166 };
167
168 struct debugfs_regset32 {
169 const struct debugfs_reg32 *regs;
170 int nregs;
171 void __iomem *base;
172 struct device *dev; /* Optional de
173 };
174
175 debugfs_create_regset32(const char *name,
176 struct dentry *par
177 struct debugfs_reg
178
179 void debugfs_print_regs32(struct seq_file
180 int nregs, void __iom
181
182 The "base" argument may be 0, but you may want
183 using __stringify, and a number of register na
184 byte offsets over a base for the register bloc
185
186 If you want to dump a u32 array in debugfs, yo
187
188 struct debugfs_u32_array {
189 u32 *array;
190 u32 n_elements;
191 };
192
193 void debugfs_create_u32_array(const char *
194 struct dentry *parent,
195 struct debugfs_u32_arr
196
197 The "array" argument wraps a pointer to the ar
198 of its elements. Note: Once array is created i
199
200 There is a helper function to create a device-
201
202 void debugfs_create_devm_seqfile(struct dev
203 const char *na
204 struct dentry
205 int (*read_fn)
206 void *
207
208 The "dev" argument is the device related to th
209 the "read_fn" is a function pointer which to b
210 seq_file content.
211
212 There are a couple of other directory-oriented
213
214 struct dentry *debugfs_rename(struct dentr
215 struct dentr
216 struct dentr
217 const char *
218
219 struct dentry *debugfs_create_symlink(cons
220 stru
221 cons
222
223 A call to debugfs_rename() will give a new nam
224 file, possibly in a different directory. The
225 to the call; the return value is old_dentry wi
226 Symbolic links can be created with debugfs_cre
227
228 There is one important thing that all debugfs
229 there is no automatic cleanup of any directori
230 module is unloaded without explicitly removing
231 will be a lot of stale pointers and no end of
232 So all debugfs users - at least those which ca
233 be prepared to remove all files and directorie
234 can be removed with::
235
236 void debugfs_remove(struct dentry *dentry)
237
238 The dentry value can be NULL or an error value
239 be removed.
240
241 Once upon a time, debugfs users were required
242 pointer for every debugfs file they created so
243 cleaned up. We live in more civilized times n
244 can call::
245
246 void debugfs_remove_recursive(struct dentr
247
248 If this function is passed a pointer for the d
249 top-level directory, the entire hierarchy belo
250 removed.
251
252 .. [1] http://lwn.net/Articles/309298/
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.