Reviewed by:

Submitted by:	julian
oops rename doc file to README as agreed

1 files changed, 123 insertions, 0 deletions

diff --git a/sys/miscfs/devfs/README b/sys/miscfs/devfs/README
new file mode 100644
index 0000000..ca950e0
--- /dev/null
+++ b/sys/miscfs/devfs/README
@@ -0,0 +1,123 @@
+this file is: /sys/miscfs/devfs/README (or soon will be)
+
+to enable: add
+options	devfs
+
+to your config file..
+expect it to be highly useless for a while,
+as the only device that registers itself is the floppy.
+
+it works like this:
+
+There is a tree of nodes that describe the layout of the DEVFS as seen by
+the drivers.. they add nodes to this tree. This is called the 'back' layer
+for reasons that will become obvious in a second. Think of it as a
+BLUEPRINT of the DEVFS tree. Each back node has associated with it 
+a "devnode" struct, that holds information about the device
+(or directory) and a pointer to the vnode if one has been associated 
+with that node. The back node itself can be considered to be 
+a directory entry, and contains the default name of the device,
+and a link to the directory that holds it.
+
+When you mount the devfs somewhere (you can mount it multiple times in
+multiple places), a front layer is created that contains a tree of 'front'
+nodes.
+
+Think of this as a Transparency, layed over the top of the blueprint.
+(or possibly a photocopy).
+
+To start with there is a 1:1 relationship between the front nodes
+and the backing nodes, however once the front plane has been created
+the nodes can be moved around within that plane (or deleted).
+Think of this as the ability to revise a transparency...
+the blueprint is untouched.
+
+There is a "devnode" struct associated with each front note also.
+Front nodes that refer to devices, use the same "devnode" struct that is used 
+by their associated backing node, so that multiple front nodes that
+point to the same device will use the same "devnode" struct, and through
+that, the same vnode, ops, modification times, flags, owner and group.
+Front nodes representing directories and symlinks have their own
+"devnode" structs, and may therefore differ. (have different vnodes)
+i.e. if you have two devfs trees mounted, you can change the 
+directories in one without changing the other. 
+e.g. remove or rename nodes
+
+Multiple mountings are like multiple transparencies,
+each showing through to the original blueprint.
+
+The nodes on the 'front' plane representing the particular mounting of the
+DEVFS that you are interested in, each have a link back to the 'backing'
+node to which they refer to get information about the node (e.g.
+major/minor) etc.
+
+Information that is to be shared between these mounts is stored
+in the 'backing' node for that object.  Once you have erased 'front'
+object, there is no memory of where the backing object was, and
+except for the possibility of searching the entire backing tree
+for the node with the correct major/minor/type, I don't see that
+it is easily recovered.. Particularly as there will eventually be
+(I hope) devices that go direct from the backing node to the driver
+without going via the cdevsw table.. they may not even have
+major/minor numbers.
+
+I see 'mount -u' as a possible solution to recovering a broken dev tree.
+
+Because non device nodes (directories and symlinks) have their own
+"devnode" structs on each layer, these may have different
+flags, owners, and contents on each layer.
+e.g. if you have a chroot tree like erf.tfs.com has, you
+may want different permissions or owners on the chroot mount of the DEVFS
+than you want in the real one. You might also want to delete some sensitive
+devices from the chroot tree.
+
+Directories also have backing nodes but there is nothing to stop
+the user from removing a front node from the directory front node.
+(except permissions of course).  This is because the front directory
+nodes keep their own records as to which front nodes are members
+of that directory and do not refer to their original backing node
+for this information.
+
+The front nodes may be moved to other directories (including
+directories) however this does not break the linkage between the
+backing nodes and the front nodes. The backing node never moves. If
+a driver decides to remove a device from the backing tree, the FS
+code follows the links to all the front nodes linked to that backing
+node, and deletes them, no matter where they've been moved to.
+(active vnodes are redirected to point to the deadfs).
+
+If a directory has been moved, and a new backing node is inserted
+into it's own back node, the new front node will appear in that front
+directory, even though it's been moved, because the directory that
+gets the front node is found via the links and not by name.
+
+a mount -u might be considered to be a request to 'refresh' the
+plane that controls to the mount being updated.. that would have the
+effect of 're-propogating' through any backing nodes that find they
+have no front nodes in that plane.
+
+
+NOTES FOR RELEASE 1
+1/ this is very preliminary
+2/ Attempts to unmount a devfs structure while you are 'IN' in will
+result in a message "hanging vnode" and the system will panic.
+3/ 'find /devfs -print' will only find the directories, and the devices
+don't show up.. (?)... find /dev/fs -ls DOES show all the devices.
+4/ the dates of all nodes is '0' i.e. 00:00 1st Jan 1970 UTC.
+It appears 'time' in the kernel hasn't been started at the time that
+the devfs is started up. (when the first device registers itself).
+notably, the VFS hasn't been started yet either so the devfs has to be careful
+to not use VFS features during probe time.
+5/ many features are not present yet..
+e.g. symlinks, a comprehensive registration interface (only a crude one)
+ability to unlink and mv nodes.
+6/ I'm pretty sure my use of vnodes is bad and it may be 'losing'
+them, or alternatively, corrupting things.. I need a vnode specialist
+to look at this.
+7/ The back and front node structures have become very similar with time
+and I have decided to merge them to a single structure, 
+which will be called a "devname" struct, as they can be thought of
+as the analogue of a directory entry, except that they are linked
+together rather than in an array. The "devnode" struct can be considered
+analogous to the inodes of a UFS.
+