[PATCH] doc: add documentation for debugfs

[PATCH] doc: add documentation for debugfs

[Shen Feng]

debugfs is used as a virtual filesystem devoted to debugging
information. But it's not documented in Documentation/filesystems.
Add one for it. The content is mainly from
http://lwn.net/Articles/115405/

Signed-off-by: Shen Feng <shen@cn.fujitsu.com>
---
 Documentation/filesystems/debugfs.txt |   51 +++++++++++++++++++++++++++++++++
 1 files changed, 51 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/filesystems/debugfs.txt

diff --git a/Documentation/filesystems/debugfs.txt b/Documentation/filesystems/debugfs.txt
new file mode 100644
index 0000000..112cf0c
--- /dev/null
+++ b/Documentation/filesystems/debugfs.txt
@@ -0,0 +1,51 @@
+        Debugfs - a virtual filesystem devoted to debugging information
+
+Debugfs is a virtual filesystem devoted to debugging information. Debugfs is
+intended to be a relatively easy and lightweight subsystem which gracefully
+disappears when configured out of the kernel.
+
+Traditionally debugfs is supposed to be mounted at /sys/kernel/debug with the
+following command:
+
+ # mount -t debugfs none /sys/kernel/debug/
+
+A developer wishing to use debugfs starts by creating a directory within the
+filesystem:
+
+    struct dentry *debugfs_create_dir(const char *name,
+                                      struct dentry *parent);
+
+The parent argument will usually be NULL, causing the directory to be created
+in the debugfs root. If debugfs is not configured into the system, the return
+value is -ENODEV; a NULL return, instead, indicates some other sort of error.
+
+The general-purpose function for creating a file in debugfs is:
+
+    struct dentry *debugfs_create_file(const char *name, mode_t mode,
+                                       struct dentry *parent, void *data,
+                                       struct file_operations *fops);
+
+The structure pointed to by fops should, of course, contain pointers to the
+functions which implement the actual operations on the file. In many cases,
+most of those functions can be the helpers provided by seq_file, making the
+task of exporting a file easy.
+
+Some additional helpers have been provided to make exporting a single value as
+easy as possible:
+
+    struct dentry *debugfs_create_u8(const char *name, mode_t mode,
+                                     struct dentry *parent, u8 *value);
+    struct dentry *debugfs_create_u16(const char *name, mode_t mode,
+                                      struct dentry *parent, u16 *value);
+    struct dentry *debugfs_create_u32(const char *name, mode_t mode,
+                                      struct dentry *parent, u32 *value);
+    struct dentry *debugfs_create_bool(const char *name, mode_t mode,
+                                       struct dentry *parent, u32 *value);
+
+Debugfs does not automatically clean up files when a module shuts down, so,
+for every file or directory created with the above functions, there must be a
+call to:
+
+    void debugfs_remove(struct dentry *dentry);
+
+See Documentation/DocBook/filesystems for more details.
-- 
1.6.0.6

Re: [PATCH] doc: add documentation for debugfs

[Andrew Morton]

On Mon, 13 Apr 2009 15:12:13 +0800
Shen Feng <shen@cn.fujitsu.com> wrote:

> 
> debugfs is used as a virtual filesystem devoted to debugging
> information. But it's not documented in Documentation/filesystems.
> Add one for it. The content is mainly from
> http://lwn.net/Articles/115405/

We should ask for Jon's permission, please?

That document is from 2004(!).  Did anyone check that it's still correct?

Re: [PATCH] doc: add documentation for debugfs

[Jonathan Corbet]

On Wed, 15 Apr 2009 15:55:28 -0700
Andrew Morton <akpm@linux-foundation.org> wrote:

> We should ask for Jon's permission, please?

No worries.  Feel free to put my:

	Signed-off-by: Jonathan Corbet <corbet@lwn.net>

onto it.

> That document is from 2004(!).  Did anyone check that it's still correct?

Seems unlikely, doesn't it?  Even if it's correct, it may well not be
complete.  I'll try to take a look at it tomorrow.

jon

Re: [PATCH] doc: add documentation for debugfs

[Shen Feng]

on 04/16/2009 07:04 AM, Jonathan Corbet wrote:
> On Wed, 15 Apr 2009 15:55:28 -0700
> Andrew Morton <akpm@linux-foundation.org> wrote:
> 
>> We should ask for Jon's permission, please?
> 
> No worries.  Feel free to put my:
> 
> 	Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> 
> onto it.
> 
>> That document is from 2004(!).  Did anyone check that it's still correct?
> 
> Seems unlikely, doesn't it?  Even if it's correct, it may well not be
> complete.  I'll try to take a look at it tomorrow.

It's not complete.
A complete API can be found at Documentation/DocBook/filesystems which is
generated by kernel-doc. So I do not update it.

I also found another another virtual filesystem securityfs which is not
documented. A good candidate is from here.
http://lwn.net/Articles/153366/


> 
> jon
> 
>