3 files changed, 170 insertions, 9 deletions
diff --git a/Documentation/filesystems/debugfs.txt b/Documentation/filesystems/debugfs.txt
new file mode 100644
index 000000000000..ed52af60c2d8
--- /dev/null
+++ b/Documentation/filesystems/debugfs.txt
@@ -0,0 +1,158 @@
+Copyright 2009 Jonathan Corbet <corbet@lwn.net>
+Debugfs exists as a simple way for kernel developers to make information
+available to user space.  Unlike /proc, which is only meant for information
+about a process, or sysfs, which has strict one-value-per-file rules,
+debugfs has no rules at all.  Developers can put any information they want
+there.  The debugfs filesystem is also intended to not serve as a stable
+ABI to user space; in theory, there are no stability constraints placed on
+files exported there.  The real world is not always so simple, though [1];
+even debugfs interfaces are best designed with the idea that they will need
+to be maintained forever.
+Debugfs is typically mounted with a command like:
+    mount -t debugfs none /sys/kernel/debug
+(Or an equivalent /etc/fstab line). 
+Note that the debugfs API is exported GPL-only to modules.
+Code using debugfs should include <linux/debugfs.h>.  Then, the first order
+of business will be to create at least one directory to hold a set of
+debugfs files:
+    struct dentry *debugfs_create_dir(const char *name, struct dentry *parent);
+This call, if successful, will make a directory called name underneath the
+indicated parent directory.  If parent is NULL, the directory will be
+created in the debugfs root.  On success, the return value is a struct
+dentry pointer which can be used to create files in the directory (and to
+clean it up at the end).  A NULL return value indicates that something went
+wrong.  If ERR_PTR(-ENODEV) is returned, that is an indication that the
+kernel has been built without debugfs support and none of the functions
+described below will work.
+The most general way to create a file within a debugfs directory is with:
+    struct dentry *debugfs_create_file(const char *name, mode_t mode,
+                                       struct dentry *parent, void *data,
+                                       const struct file_operations *fops);
+Here, name is the name of the file to create, mode describes the access
+permissions the file should have, parent indicates the directory which
+should hold the file, data will be stored in the i_private field of the
+resulting inode structure, and fops is a set of file operations which
+implement the file's behavior.  At a minimum, the read() and/or write()
+operations should be provided; others can be included as needed.  Again,
+the return value will be a dentry pointer to the created file, NULL for
+error, or ERR_PTR(-ENODEV) if debugfs support is missing.
+In a number of cases, the creation of a set of file operations is not
+actually necessary; the debugfs code provides a number of helper functions
+for simple situations.  Files containing a single integer value can be
+created with any of:
+    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_u64(const char *name, mode_t mode,
+                                      struct dentry *parent, u64 *value);
+These files support both reading and writing the given value; if a specific
+file should not be written to, simply set the mode bits accordingly.  The
+values in these files are in decimal; if hexadecimal is more appropriate,
+the following functions can be used instead:
+    struct dentry *debugfs_create_x8(const char *name, mode_t mode,
+                                     struct dentry *parent, u8 *value);
+    struct dentry *debugfs_create_x16(const char *name, mode_t mode,
+                                      struct dentry *parent, u16 *value);
+    struct dentry *debugfs_create_x32(const char *name, mode_t mode,
+                                      struct dentry *parent, u32 *value);
+Note that there is no debugfs_create_x64().
+These functions are useful as long as the developer knows the size of the
+value to be exported.  Some types can have different widths on different
+architectures, though, complicating the situation somewhat.  There is a
+function meant to help out in one special case:
+    struct dentry *debugfs_create_size_t(const char *name, mode_t mode,
+                                         struct dentry *parent, 
+                                         size_t *value);
+As might be expected, this function will create a debugfs file to represent
+a variable of type size_t.
+Boolean values can be placed in debugfs with:
+    struct dentry *debugfs_create_bool(const char *name, mode_t mode,
+                                       struct dentry *parent, u32 *value);
+A read on the resulting file will yield either Y (for non-zero values) or
+N, followed by a newline.  If written to, it will accept either upper- or
+lower-case values, or 1 or 0.  Any other input will be silently ignored.
+Finally, a block of arbitrary binary data can be exported with:
+    struct debugfs_blob_wrapper {
+        void *data;
+        unsigned long size;
+    };
+    struct dentry *debugfs_create_blob(const char *name, mode_t mode,
+                                       struct dentry *parent,
+                                       struct debugfs_blob_wrapper *blob);
+A read of this file will return the data pointed to by the
+debugfs_blob_wrapper structure.  Some drivers use "blobs" as a simple way
+to return several lines of (static) formatted text output.  This function
+can be used to export binary information, but there does not appear to be
+any code which does so in the mainline.  Note that all files created with
+debugfs_create_blob() are read-only.
+There are a couple of other directory-oriented helper functions:
+    struct dentry *debugfs_rename(struct dentry *old_dir, 
+                                  struct dentry *old_dentry,
+                                  struct dentry *new_dir, 
+                                  const char *new_name);
+    struct dentry *debugfs_create_symlink(const char *name, 
+                                          struct dentry *parent,
+                                          const char *target);
+A call to debugfs_rename() will give a new name to an existing debugfs
+file, possibly in a different directory.  The new_name must not exist prior
+to the call; the return value is old_dentry with updated information.
+Symbolic links can be created with debugfs_create_symlink().
+There is one important thing that all debugfs users must take into account:
+there is no automatic cleanup of any directories created in debugfs.  If a
+module is unloaded without explicitly removing debugfs entries, the result
+will be a lot of stale pointers and no end of highly antisocial behavior.
+So all debugfs users - at least those which can be built as modules - must
+be prepared to remove all files and directories they create there.  A file
+can be removed with:
+    void debugfs_remove(struct dentry *dentry);
+The dentry value can be NULL, in which case nothing will be removed.
+Once upon a time, debugfs users were required to remember the dentry
+pointer for every debugfs file they created so that all files could be
+cleaned up.  We live in more civilized times now, though, and debugfs users
+can call:
+    void debugfs_remove_recursive(struct dentry *dentry);
+If this function is passed a pointer for the dentry corresponding to the
+top-level directory, the entire hierarchy below that directory will be
+removed.
+Notes:
+        [1] http://lwn.net/Articles/309298/
diff --git a/Documentation/filesystems/gfs2-glocks.txt b/Documentation/filesystems/gfs2-glocks.txt
index 4dae9a3840bf..0494f78d87e4 100644
--- a/Documentation/filesystems/gfs2-glocks.txt
+++ b/Documentation/filesystems/gfs2-glocks.txt
@@ -60,7 +60,7 @@ go_lock          | Called for the first local holder of a lock
 go_unlock        | Called on the final local unlock of a lock
 go_dump          | Called to print content of object for debugfs file, or on
                 | error to dump glock to the log.
-go_type;         | The type of the glock, LM_TYPE_.....
+go_type          | The type of the glock, LM_TYPE_.....
 go_min_hold_time | The minimum hold time
 The minimum hold time for each lock is the time after a remote lock
diff --git a/Documentation/filesystems/gfs2.txt b/Documentation/filesystems/gfs2.txt
index 593004b6bbab..5e3ab8f3beff 100644
--- a/Documentation/filesystems/gfs2.txt
+++ b/Documentation/filesystems/gfs2.txt
@@ -11,18 +11,15 @@ their I/O so file system consistency is maintained.  One of the nifty
 features of GFS is perfect consistency -- changes made to the file system
 on one machine show up immediately on all other machines in the cluster.
-GFS uses interchangable inter-node locking mechanisms.  Different lock
+GFS uses interchangable inter-node locking mechanisms, the currently
-modules can plug into GFS and each file system selects the appropriate
+supported mechanisms are:
-lock module at mount time.  Lock modules include:
  lock_nolock -- allows gfs to be used as a local file system
  lock_dlm -- uses a distributed lock manager (dlm) for inter-node locking
  The dlm is found at linux/fs/dlm/
-In addition to interfacing with an external locking manager, a gfs lock
+Lock_dlm depends on user space cluster management systems found
-module is responsible for interacting with external cluster management
-systems.  Lock_dlm depends on user space cluster management systems found
 at the URL above.
 To use gfs as a local file system, no external clustering systems are
@@ -31,13 +28,19 @@ needed, simply:
  $ mkfs -t gfs2 -p lock_nolock -j 1 /dev/block_device
  $ mount -t gfs2 /dev/block_device /dir
-GFS2 is not on-disk compatible with previous versions of GFS.
+If you are using Fedora, you need to install the gfs2-utils package
+and, for lock_dlm, you will also need to install the cman package
+and write a cluster.conf as per the documentation.
+GFS2 is not on-disk compatible with previous versions of GFS, but it
+is pretty close.
 The following man pages can be found at the URL above:
-  gfs2_fsck     to repair a filesystem
+  fsck.gfs2     to repair a filesystem
  gfs2_grow     to expand a filesystem online
  gfs2_jadd     to add journals to a filesystem online
  gfs2_tool     to manipulate, examine and tune a filesystem
  gfs2_quota    to examine and change quota values in a filesystem
+  gfs2_convert  to convert a gfs filesystem to gfs2 in-place
  mount.gfs2    to help mount(8) mount a filesystem
  mkfs.gfs2     to make a filesystem

diff --git a/Documentation/filesystems/debugfs.txt b/Documentation/filesystems/debugfs.txt new file mode 100644 index 000000000000..ed52af60c2d8 --- /dev/null +++ b/Documentation/filesystems/debugfs.txt
@@ -0,0 +1,158 @@
		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/


diff --git a/Documentation/filesystems/gfs2-glocks.txt b/Documentation/filesystems/gfs2-glocks.txt index 4dae9a3840bf..0494f78d87e4 100644 --- a/Documentation/filesystems/gfs2-glocks.txt +++ b/Documentation/filesystems/gfs2-glocks.txt
@@ -60,7 +60,7 @@ go_lock \| Called for the first local holder of a lock
60	go_unlock \| Called on the final local unlock of a lock	60	go_unlock \| Called on the final local unlock of a lock
61	go_dump \| Called to print content of object for debugfs file, or on	61	go_dump \| Called to print content of object for debugfs file, or on
62	\| error to dump glock to the log.	62	\| error to dump glock to the log.
63	go_type; \| The type of the glock, LM_TYPE_.....	63	go_type \| The type of the glock, LM_TYPE_.....
64	go_min_hold_time \| The minimum hold time	64	go_min_hold_time \| The minimum hold time
65		65
66	The minimum hold time for each lock is the time after a remote lock	66	The minimum hold time for each lock is the time after a remote lock


diff --git a/Documentation/filesystems/gfs2.txt b/Documentation/filesystems/gfs2.txt index 593004b6bbab..5e3ab8f3beff 100644 --- a/Documentation/filesystems/gfs2.txt +++ b/Documentation/filesystems/gfs2.txt
@@ -11,18 +11,15 @@ their I/O so file system consistency is maintained. One of the nifty
11	features of GFS is perfect consistency -- changes made to the file system	11	features of GFS is perfect consistency -- changes made to the file system
12	on one machine show up immediately on all other machines in the cluster.	12	on one machine show up immediately on all other machines in the cluster.
13		13
14	GFS uses interchangable inter-node locking mechanisms. Different lock	14	GFS uses interchangable inter-node locking mechanisms, the currently
15	modules can plug into GFS and each file system selects the appropriate	15	supported mechanisms are:
16	lock module at mount time. Lock modules include:
17		16
18	lock_nolock -- allows gfs to be used as a local file system	17	lock_nolock -- allows gfs to be used as a local file system
19		18
20	lock_dlm -- uses a distributed lock manager (dlm) for inter-node locking	19	lock_dlm -- uses a distributed lock manager (dlm) for inter-node locking
21	The dlm is found at linux/fs/dlm/	20	The dlm is found at linux/fs/dlm/
22		21
23	In addition to interfacing with an external locking manager, a gfs lock	22	Lock_dlm depends on user space cluster management systems found
24	module is responsible for interacting with external cluster management
25	systems. Lock_dlm depends on user space cluster management systems found
26	at the URL above.	23	at the URL above.
27		24
28	To use gfs as a local file system, no external clustering systems are	25	To use gfs as a local file system, no external clustering systems are
@@ -31,13 +28,19 @@ needed, simply:
31	$ mkfs -t gfs2 -p lock_nolock -j 1 /dev/block_device	28	$ mkfs -t gfs2 -p lock_nolock -j 1 /dev/block_device
32	$ mount -t gfs2 /dev/block_device /dir	29	$ mount -t gfs2 /dev/block_device /dir
33		30
34	GFS2 is not on-disk compatible with previous versions of GFS.	31	If you are using Fedora, you need to install the gfs2-utils package
		32	and, for lock_dlm, you will also need to install the cman package
		33	and write a cluster.conf as per the documentation.
		34
		35	GFS2 is not on-disk compatible with previous versions of GFS, but it
		36	is pretty close.
35		37
36	The following man pages can be found at the URL above:	38	The following man pages can be found at the URL above:
37	gfs2_fsck to repair a filesystem	39	fsck.gfs2 to repair a filesystem
38	gfs2_grow to expand a filesystem online	40	gfs2_grow to expand a filesystem online
39	gfs2_jadd to add journals to a filesystem online	41	gfs2_jadd to add journals to a filesystem online
40	gfs2_tool to manipulate, examine and tune a filesystem	42	gfs2_tool to manipulate, examine and tune a filesystem
41	gfs2_quota to examine and change quota values in a filesystem	43	gfs2_quota to examine and change quota values in a filesystem
		44	gfs2_convert to convert a gfs filesystem to gfs2 in-place
42	mount.gfs2 to help mount(8) mount a filesystem	45	mount.gfs2 to help mount(8) mount a filesystem
43	mkfs.gfs2 to make a filesystem	46	mkfs.gfs2 to make a filesystem