freebsd-skq/sys/miscfs/devfs/README

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.