bsd/miscfs/devfs/README

   1 Note: The following comments are from the original FreeBSD 3.1 README
   2
   3 this file is: /sys/miscfs/devfs/README
   4
   5 to enable: add
   6 options DEVFS
   7
   8 to your config file..
   9 expect it to be highly useless for a while,
  10 as the only devices that register themselves are the floppy,
  11 the pcaudio stuff, speaker, null,mem,zero,io,kmem.
  12
  13 it works like this:
  14
  15 There is a tree of nodes that describe the layout of the DEVFS as seen by
  16 the drivers.. they add nodes to this tree. This is called the 'back' layer
  17 for reasons that will become obvious in a second. Think of it as a
  18 BLUEPRINT of the DEVFS tree. Each back node has associated with it
  19 a "devnode" struct, that holds information about the device
  20 (or directory) and a pointer to the vnode if one has been associated
  21 with that node. The back node itself can be considered to be
  22 a directory entry, and contains the default name of the device,
  23 and a link to the directory that holds it. It is sometimes refered
  24 to in the code as the dev_name. The devnode can be considered the inode.
  25
  26 When you mount the devfs somewhere (you can mount it multiple times in
  27 multiple places), a front layer is created that contains a tree of 'front'
  28 nodes.
  29
  30 Think of this as a Transparency, layed over the top of the blueprint.
  31 (or possibly a photocopy).
  32
  33 The front and back nodes are identical in type, but the back nodes
  34 are reserved for kernel use only, and are protected from the user.
  35 The back plane has a mount structure and all that stuff, but it is in
  36 fact not really mounted. (and is thus not reachable via namei).
  37 Internal kernel routines can open devices in this plane
  38 even if the external devfs has not been mounted yet :)
  39 (e.g. to find the root device)
  40
  41 To start with there is a 1:1 relationship between the front nodes
  42 and the backing nodes, however once the front plane has been created
  43 the nodes can be moved around within that plane (or deleted).
  44 Think of this as the ability to revise a transparency...
  45 the blueprint is untouched.
  46
  47 There is a "devnode" struct associated with each front note also.
  48 Front nodes that refer to devices, use the same "devnode" struct that is used
  49 by their associated backing node, so that multiple front nodes that
  50 point to the same device will use the same "devnode" struct, and through
  51 that, the same vnode, ops, modification times, flags, owner and group.
  52 Front nodes representing directories and symlinks have their own
  53 "devnode" structs, and may therefore differ. (have different vnodes)
  54 i.e. if you have two devfs trees mounted, you can change the
  55 directories in one without changing the other.
  56 e.g. remove or rename nodes
  57
  58 Multiple mountings are like multiple transparencies,
  59 each showing through to the original blueprint.
  60
  61 Information that is to be shared between these mounts is stored
  62 in the 'backing' node for that object.  Once you have erased 'front'
  63 object, there is no memory of where the backing object was, and
  64 except for the possibility of searching the entire backing tree
  65 for the node with the correct major/minor/type, I don't see that
  66 it is easily recovered.. Particularly as there will eventually be
  67 (I hope) devices that go direct from the backing node to the driver
  68 without going via the cdevsw table.. they may not even have
  69 major/minor numbers.
  70
  71 I see 'mount -u' as a possible solution to recovering a broken dev tree.
  72 (though umount+mount would do the same)
  73
  74 Because non device nodes (directories and symlinks) have their own
  75 "devnode" structs on each layer, these may have different
  76 flags, owners, and contents on each layer.
  77 e.g. if you have a chroot tree like erf.tfs.com has, you
  78 may want different permissions or owners on the chroot mount of the DEVFS
  79 than you want in the real one. You might also want to delete some sensitive
  80 devices from the chroot tree.
  81
  82 Directories also have backing nodes but there is nothing to stop
  83 the user from removing a front node from the directory front node.
  84 (except permissions of course).  This is because the front directory
  85 nodes keep their own records as to which front nodes are members
  86 of that directory and do not refer to their original backing node
  87 for this information.
  88
  89 The front nodes may be moved to other directories (including
  90 directories) however this does not break the linkage between the
  91 backing nodes and the front nodes. The backing node never moves. If
  92 a driver decides to remove a device from the backing tree, the FS
  93 code follows the links to all the front nodes linked to that backing
  94 node, and deletes them, no matter where they've been moved to.
  95 (active vnodes are redirected to point to the deadfs).
  96
  97 If a directory has been moved, and a new backing node is inserted
  98 into its own back node, the new front node will appear in that front
  99 directory, even though it's been moved, because the directory that
 100 gets the front node is found via the links and not by name.
 101
 102 a mount -u might be considered to be a request to 'refresh' the
 103 plane that controls to the mount being updated.. that would have the
 104 effect of 're-propogating' through any backing nodes that find they
 105 have no front nodes in that plane.
 106
 107
 108 NOTES FOR RELEASE 1.2
 109 1/ this is very preliminary
 110 2/ the routines have greatly simplified since release 1.1
 111 (I guess the break did me good :)
 112 3/ many features are not present yet..
 113 e.g. symlinks, a comprehensive registration interface (only a crude one)
 114 ability to unlink and mv nodes.
 115 4/ I'm pretty sure my use of vnodes is bad and it may be 'losing'
 116 them, or alternatively, corrupting things.. I need a vnode specialist
 117 to look at this.
 118