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

[svn-commits at oss.oracle.com]

Author: jlbec
Signed-off-by: manish
Date: 2005-03-20 01:26:25 -0600 (Sun, 20 Mar 2005)
New Revision: 2017

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

o Put an example into the usysfs documentation.

Signed-off-by: manish



Modified: trunk/fs/usysfs/usysfs.txt
===================================================================
--- trunk/fs/usysfs/usysfs.txt	2005-03-19 22:08:54 UTC (rev 2016)
+++ trunk/fs/usysfs/usysfs.txt	2005-03-20 07:26:25 UTC (rev 2017)
@@ -5,7 +5,8 @@
 
 Updated: 15 March 2005
 
-Copyright (c) 2005 Oracle Corporation
+Copyright (c) 2005 Oracle Corporation,
+	Joel Becker <joel.becker at oracle.com>
 
 
 [What is usysfs?]
@@ -44,7 +45,8 @@
 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.
+one) under /usys.  Like sysfs, the usysfs tree is always there, whether
+mounted on /usys or not.
 
 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,
@@ -53,6 +55,49 @@
 with only one value per file.  The same efficiency caveats from sysfs
 apply.  Don't mix more than one attribute in one attribute file.
 
+Like sysfs, usysfs expects write(2) to store the entire buffer at once.
+When writing to usysfs attributes, userspace processes should first
+read the entire file, modify the portions they wish to change, and then
+write the entire buffer back.  Attribute files have a maximum size of
+one page (PAGE_SIZE, 4096 on i386).
+
 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).
+
+[Configuring FakeNBD: an Example]
+
+Imagine there's a Network Block Device (NBD) driver that allows you to
+access remote block devices.  Call it FakeNBD.  FakeNBD uses usysfs for
+its configuration.  Obviously, there will be a nice program that
+sysadmins use to configure FakeNBD, but somehow that program has to tell
+the driver about it.  Here's where usysfs comes in.
+
+When the FakeNBD driver is loaded, it registers itself with usysfs.
+readdir(3) sees this just fine:
+
+	# ls /usys
+	fakenbd
+
+A fakenbd connection can be created with mkdir(2).  The name is
+arbitrary, but likely the tool will make some use of the name.  Perhaps
+it is a uuid or a disk name:
+
+	# mkdir /usys/fakenbd/disk1
+	# ls /usys/fakenbd/disk1
+	target device rw
+
+The target attribute contains the IP address of the server FakeNBD will
+connect to.  The device attribute is the device on the server.
+Predictably, the rw attribute determines whether the connection is
+read-only or read-write.
+
+	# echo 10.0.0.1 > /usys/fakenbd/disk1/target
+	# echo /dev/sda1 > /usys/fakenbd/disk1/device
+	# echo 1 > /usys/fakenbd/disk1/rw
+
+That's it.  That's all there is.  Now the device is configured, via the
+shell no less.
+
+[Coding With usysfs]
+