[Ocfs2-commits] jlbec commits r1974 - trunk/fs/usysfs

[svn-commits at oss.oracle.com]

Author: jlbec
Signed-off-by: zab
Date: 2005-03-15 14:21:14 -0600 (Tue, 15 Mar 2005)
New Revision: 1974

Added:
   trunk/fs/usysfs/usysfs.txt
Log:

o Started usysfs.txt

Signed-off-by: zab



Added: trunk/fs/usysfs/usysfs.txt
===================================================================
--- trunk/fs/usysfs/usysfs.txt	2005-03-15 03:31:12 UTC (rev 1973)
+++ trunk/fs/usysfs/usysfs.txt	2005-03-15 20:21:14 UTC (rev 1974)
@@ -0,0 +1,58 @@
+
+usysfs - User-driven sysfs
+
+Joel Becker <joel.becker at oracle.com>
+
+Updated: 15 March 2005
+
+Copyright (c) 2005 Oracle Corporation
+
+
+[What is usysfs?]
+
+usysfs is a ram-based filesystem initially based on sysfs.  It provides
+the converse of sysfs's functionality.  Where sysfs is a
+filesystem-based view of kernel objects, usysfs is a filesystem-based
+manager of kernel objects.
+
+With sysfs, an object is created in kernel (for example, when a device
+is discovered) and it is registered with sysfs.  Its attributes then
+appear in sysfs, allowing userspace to read the attributes via
+readdir(3)/read(2).  It may allow some attributes to be modified via
+write(2).  The important point is that the object is created and
+destroyed in kernel, the kernel controls the lifecycle of the sysfs
+representation, and sysfs is merely a window on all this.
+
+A usysfs object is created via an explicit userspace operation:
+mkdir(2).  It is destroyed via rmdir(2).  The attributes appear at
+mkdir(2) time, and can be read or modified via read(2) and write(2).
+As with sysfs, readdir(3) queries the list of objects and/or attributes.
+symlink(2) can be used to group objects together.  Unlike sysfs, the
+lifetime of the representation is completely driven by userspace.  The
+kernel modules backing the objects must respond to this.
+
+Both sysfs and usysfs can and should exist together on the same system.
+One is not a replacement for the other.
+
+[Using usysfs]
+
+usysfs can be compiled as a module or into the kernel.  You can access
+it by doing
+
+	mount -t usysfs none /usys
+
+The usysfs tree will be empty unless client modules are also loaded.
+These are modules that register their object types with usysfs.  Once a
+client module is loaded, it will appear as a subdirectory (or more than
+one) under /usys.
+
+An object is created via mkdir(2).  The object's attributes will also
+appear at this time.  readdir(3) can determine what the attributes are,
+read(2) can query their default values, and write(2) can store new
+values.  Like sysfs, attributes should be ASCII text files, preferably
+with only one value per file.  The same efficiency caveats from sysfs
+apply.  Don't mix more than one attribute in one attribute file.
+
+When an object needs to be destroyed, remove it with rmdir(2).  An
+object cannot be destroyed if any other object has a link to it (via
+symlink(2)).  Links can be removed via unlink(2).