docs: update some docs and delete outdated stuff

3 files changed, 6 insertions, 322 deletions

diff --git a/docs/README-gcov_for_udev b/docs/README-gcov_for_udev
index c223dc38e8..5acb53a27c 100644
--- a/docs/README-gcov_for_udev
+++ b/docs/README-gcov_for_udev
@@ -14,37 +14,19 @@ With that said, here is how to get code coverage analysis for udev files.
 Note that this was developed with udev version 024.
 
 - Make sure you've installed udev and that it is working properly.
-  If you are having problems, refer to the README and HOWTO-udev_for_dev
-  documents in udev tarball.
-
-- execute make_gcov.sh from udev top level directory
 
+- Build udev with:
     make gcov-all
-
-  This will compile udev with gcov support.  Basically make_gcov.sh will
-  run make but override the CFLAGS.  It strips any optimization from
-  CFLAGS in order for gcov to get correct code coverage analysis.  It will
-  also add the -fprofile-arcs and -ftest-coverage options which are the
-  necessary flags needed to use gcov.
-
-  If you look into your udev directory and see that it has been polluted with
-  a bunch of *.gcno, *.gcda and *.gcov files. gcov creates and uses these files
-  to extract the code coverage info.
-
-- After running make_gcov.sh you need to install udev again.  So basically,
-
-    su to root
-    make install
+  This will compile udev with gcov support. If you look into your udev directory
+  and see that it has been polluted with a bunch of *.gcno, *.gcda and *.gcov files.
+  gcov creates and uses these files to extract the code coverage info.
 
 - Then execute some udev tasks.  You can run some udev tests, reboot, or
   do anything your little udev heart desires.  Once you are satisfied, you
   can now see how much udev code was covered.  I personally recommend just
   running test/udev-test.pl for starters.
 
-- To get the udev code coverage analysis, execute run_gcov.sh from udev top
-  level directory.  You need to be root to do this.
-
-    su to root
+- To get the udev code coverage analysis:
     make udev_gcov.txt
 
 - This creates udev_gcov.txt in the udev top level directory which holds all
@@ -83,8 +65,4 @@ Note that this was developed with udev version 024.
 
 - Once you are done with using gcov for udev and want to return to your
   normal use of udev, run a regular 'make clean' on your udev directory.
-  Then just run a regular make and make install and you are back to normal:
-
-    make clean all
-    su to root
-    make install
+  Then just run a regular make and make install and you are back to normal.
diff --git a/docs/overview b/docs/overview
deleted file mode 100644
index 87c1d1df10..0000000000
--- a/docs/overview
+++ /dev/null
@@ -1,102 +0,0 @@
--------------------------------------------------------------------------
-    This is a proposal from the early days of udev. A lot of the things
-    mentioned here are implemented differently and most of the features
-    implemented in udev are not part of that document.
-    This document is only kept in the tree for sentimental reasons.
--------------------------------------------------------------------------
-
-We've got a couple of goals for udev:
-
-1) dynamic replacement for /dev
-2) device naming
-3) API to access info about current system devices
-
-Splitting these goals into separate subsystems:
-
-1) udev - dynamic replacement for /dev
-2) namedev - device naming
-3) libsysfs - a standard library for accessing device information on the
-              system.
-
-Udev
-------
-
-Udev will be responsible for responding to /sbin/hotplug on device
-events.  It will receive the device class information along with
-device's sysfs directory.  Udev will call the name_device function from
-the naming device subsystem with that information and receive a unique
-device name in return.  Udev will then query sysfs through the libsysfs
-for specific device information required for creating the /dev node like
-major and minor number.  Once it has the important information, udev
-will create a /dev entry for the device, add the device to the in memory
-table of current devices, and send notification of the successful event
-through a D-BUS message.  On a remove call, udev will remove the /dev
-entry, remove the device from the in memory table, and send
-notification.
-
-Udev will consist of a command udev - to be called from /sbin/hotplug.
-It will require the in memory dynamic database/table for keeping track
-of current system devices, and a library of routines for accessing that
-database/table.  Udev will not care about "how" devices are named, that
-will be separated into the device naming subsystem.  It's presented a
-common device naming API by the device naming subsystem to use for
-naming devices.
-
-
-
-namedev
-----------
-
-From comments people have made, the device naming part of udev has been
-pushed into its own "subsystem".  The reason is to make this as flexible
-and pluggable as possible.  The device naming subsystem, or namedev, will
-present a standard interface for udev to call for naming a particular
-device.  Under that interface, system administrators can plug in their
-own methods for device naming.
-
-We would provide a default naming scheme. The first prototype
-implementation could simply take the sysfs directory passed in with the
-device name function, query sysfs for the major and minor numbers, and
-then look up in a static device name mapping file the name of the
-device. The static device naming file could look just like devices.txt
-in the Linux kernel's Documentation directory.  Obviously, this isn't a
-great implementation because eventually we'd like major an minor numbers
-to be dynamic.
-
-The default naming scheme in the future would have a set of policies to
-go through in order to determine the name of the device.  The device
-naming subsystem would get the sysfs directory of the to be named device
-and would use the following information in order to map the device's
-name:
-
-1) Label info - like SCSI's UUID
-2) Bus Device Number
-3) Topology on Bus
-4) Kernel Name - DEFAULT
-
-System administrators could use the default naming system or enterprise
-computing environments could plug in their Universal Unique Identifier
-(UUID) policies.  The idea is to make the device naming as flexible and
-pluggable as possible.
-
-The device naming subsystem would require accessing sysfs for device
-information.  It will receive the device's sysfs directory in the call
-from udev and use it to get more information to determine naming.  The
-namedev subsystem will include a standard naming API for udev to use.
-The default naming scheme will include a set of functions and a static
-device naming file, which will reside in /etc or /var.
-
-
-
-libsysfs
---------
-
-There is a need for a common API to access device information in sysfs.
-The device naming subsystem and the udev subsystem need to take the
-sysfs directory path and query device information.  Instead of copying
-code so each one will have to readdir, etc., splitting this logic of
-sysfs calls into a separate library that will sit atop sysfs makes more
-sense.  Sysfs callbacks aren't standard across devices, so this is
-another reason for creating a common and standard library interface for
-querying device information. 
-
diff --git a/docs/udev_vs_devfs b/docs/udev_vs_devfs
deleted file mode 100644
index 9e803ca309..0000000000
--- a/docs/udev_vs_devfs
+++ /dev/null
@@ -1,192 +0,0 @@
-		udev and devfs - The final word
-
-			December 30, 2003
-			Greg Kroah-Hartman
-			<greg@kroah.com>
-
-
-Executive summary for those too lazy to read this whole thing:
-	I don't care about devfs, and I don't want to talk about it at
-	all anymore.  If you love devfs, fine, I'm not trying to tell
-	anyone what to do.  But you really should be looking into using
-	udev instead.  All further email messages sent to me about devfs
-	will be gladly ignored.
-
-
-First off, some background.  For a description of udev, and what its
-original design goals were, please see the OLS 2003 paper on udev,
-available at:
-	<http://www.kroah.com/linux/talks/ols_2003_udev_paper/Reprint-Kroah-Hartman-OLS2003.pdf>
-and the slides for the talk, available at:
-	<http://www.kroah.com/linux/talks/ols_2003_udev_talk/>
-The OLS paper can also be found in the docs/ directory of the udev
-tarball, available on kernel.org in the /pub/linux/utils/kernel/hotplug/
-directory.
-
-In that OLS paper, I described the current situation of a static /dev
-and the current problems that a number of people have with it.  I also
-detailed how devfs tries to solve a number of these problems.  In
-hindsight, I should have never mentioned the word "devfs" when talking
-about udev.  I did so only because it seemed like a good place to start
-with.  Most people understood what devfs is, and what it does.  To
-compare udev against it, showing how udev was more powerful, and a more
-complete solution to the problems people were having, seemed like a
-natural comparison to me.
-
-But no more.  I hereby never want to compare devfs and udev again.  With
-the exception of this message...
-
-The Problems:
- 1) A static /dev is unwieldy and big.  It would be nice to only show
-    the /dev entries for the devices we actually have running in the
-    system.
- 2) We are (well, were) running out of major and minor numbers for
-    devices.
- 3) Users want a way to name devices in a persistent fashion (i.e. "This
-    disk here, must _always_ be called "boot_disk" no matter where in
-    the scsi tree I put it", or "This USB camera must always be called
-    "camera" no matter if I have other USB scsi devices plugged in or
-    not.")
- 4) Userspace programs want to know when devices are created or removed,
-    and what /dev entry is associated with them.
-
-The constraints:
- 1) No policy in the kernel!
- 2) Follow standards (like the LSB)
- 3) must be small so embedded devices will use it.
-
-
-So, how does devfs stack up to the above problems and constraints:
-  Problems:
-    1) devfs only shows the dev entries for the devices in the system.
-    2) devfs does not handle the need for dynamic major/minor numbers
-    3) devfs does not provide a way to name devices in a persistent
-       fashion.
-    4) devfs does provide a deamon that userspace programs can hook into
-       to listen to see what devices are being created or removed.
-  Constraints:
-    1) devfs forces the devfs naming policy into the kernel.  If you
-       don't like this naming scheme, tough.
-    2) devfs does not follow the LSB device naming standard.
-    3) devfs is small, and embedded devices use it.  However it is
-       implemented in non-pagable memory.
-
-Oh yeah, and there are the insolvable race conditions with the devfs
-implementation in the kernel, but I'm not going to talk about them right
-now, sorry.  See the linux-kernel archives if you care about them (and
-if you use devfs, you should care...)
-
-So devfs is 2 for 7, ignoring the kernel races.
-
-And now for udev:
-  Problems:
-    1) using udev, the /dev tree only is populated for the devices that
-       are currently present in the system.
-    2) udev does not care about the major/minor number schemes.  If the
-       kernel tomorrow switches to randomly assign major and minor numbers
-       to different devices, it would work just fine (this is exactly
-       what I am proposing to do in 2.7...)
-    3) This is the main reason udev is around.  It provides the ability
-       to name devices in a persistent manner.  More on that below.
-    4) udev emits D-BUS messages so that any other userspace program
-       (like HAL) can listen to see what devices are created or removed.
-       It also allows userspace programs to query its database to see
-       what devices are present and what they are currently named as
-       (providing a pointer into the sysfs tree for that specific device
-       node.)
-  Constraints:
-    1) udev moves _all_ naming policies out of the kernel and into
-       userspace.
-    2) udev defaults to using the LSB device naming standard.  If users
-       want to deviate away from this standard (for example when naming
-       some devices in a persistent manner), it is easily possible to do
-       so.
-    3) udev is small and is entirely in userspace, which
-       is swapable, and doesn't have to be running at all times.
-
-Nice, 7 out of 7 for udev.  Makes you think the problems and constraints
-were picked by a udev developer, right?  No, the problems and
-constraints are ones I've seen over the years and so udev, along with
-the kernel driver model and sysfs, were created to solve these real
-problems.  I also have had the luxury to see the problems that the
-current devfs implementation has, and have taken the time to work out
-something that does not have those same problems.
-
-So by just looking at the above descriptions, everyone should instantly
-realize that udev is far better than devfs and start helping out udev
-development, right?  Oh, you want more info, ok...
-
-Back in May 2003 I released a very tiny version of udev that implemented
-everything that devfs currently does, in about 6Kb of userspace code:
-	http://marc.theaimsgroup.com/?l=linux-kernel&m=105003185331553
-
-Yes, that's right, 6Kb.  So, you are asking, why are you still working
-on udev if it did everything devfs did back in May 2003?  That's because
-just managing static device nodes based on what the kernel calls the
-devices is _not_ the primary goal of udev.  It's just a tiny side effect
-of its primary goal, the ability to never worry about major/minor
-number assignments and provide the ability to achieve persistent device
-names if wanted.
-
-All the people wanting to bring up the udev vs. devfs argument go back
-and read the previous paragraph.  Yes, all Gentoo users who keep filling
-up my inbox with smoking emails, I mean you.
-
-So, how well does udev solve its goals:
-  Prevent users from ever worrying about major/minor numbers
-    And here you were, not knowing you ever needed to worry about
-    major/minor numbers in the first place, right?  Ah, I see you
-    haven't plugged in 2 USB printers and tried to figure out which
-    printer was which /dev entry?  Or plugged in 4000 SCSI disks and
-    tried to figure out how to access that 3642nd disk and what it was
-    called in /dev.  Or plugged in a USB camera and a USB flash drive
-    and then tried to download the pictures off of the flash drive by
-    accident?
-
-    As the above scenarios show, both desktop users and big iron users
-    both need to not worry about which device is assigned to what
-    major/minor device.
-
-    udev doesn't care what major/minor number is assigned to a device.
-    It merely takes the numbers that the kernel says it assigned to the
-    device and creates a device node based on it, which the user can
-    then use (if you don't understand the whole major/minor to device
-    node issue, or even what a device node is, trust me, you don't
-    really want to, go install udev and don't worry about it...)  As
-    stated above, if the kernel decides to start randomly assigning
-    major numbers to all devices, then udev will still work just fine.
-
-  Provide a persistent device naming solution:
-    Lots of people want to assign a specific name that they can talk to
-    a device to, no matter where it is in the system, or what order they
-    plugged the device in.  USB printers, SCSI disks, PCI sound cards,
-    Firewire disks, USB mice, and lots of other devices all need to be
-    assigned a name in a consistent manner (udev doesn't handle network
-    devices, naming them is already a solved solution, using nameif).
-    udev allows users to create simple rules to describe what device to
-    name.  If users want to call a program running a large database
-    half-way around the world, asking it what to name this device, it
-    can.  We don't put the naming database into the kernel (like other
-    Unix variants have), everything is in userspace, and easily
-    accessible.  You can even run a perl script to name your device if
-    you are that crazy...
-
-    For more information on how to create udev rules to name devices,
-    please see the udev man page, and look at the example udev rules
-    that ship with the tarball.
-
-
-So, convinced already why you should use udev instead of devfs?  No.
-Ok, fine, I'm not forcing you to abandon your bloated, stifling policy,
-nonextensible, end of life feature if you don't want to.  But please
-don't bother me about it either, I don't care about devfs, only about
-udev.
-
-This is my last posting about this topic, all further emails sent to me
-about why devfs is wonderful, and why are you making fun of this
-wonderful, stable gift from the gods, will be gleefully ignored and
-possibly posted in a public place where others can see.
-
-thanks,
-
-greg k-h