Eric Lee / linux-smarc-t335x-v3.2

Commit f89d7eaf6c34828070f407d0e04b73127f176ec5

Authored by Jonathan Corbet 2009-06-05 06:35:25 +0800

Exists in master and in 4 other branches

Document the debugfs API

This is an updated document covering the internal API for the debugfs
filesystem.  Thanks to Shen Feng for suggesting that I put this text here
and noting that the old LWN version was rather out of date.

Acked-by: Greg Kroah-Hartman <gregkh@suse.de>
Reported-by: Shen Feng <shen@cn.fujitsu.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Showing 1 changed file with 158 additions and 0 deletions Side-by-side Diff

Documentation/filesystems/debugfs.txt

Documentation/filesystems/debugfs.txt

Diff comments View file @ f89d7ea

	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/