Even more documentation updates

git-svn-id: http://lm-sensors.org/svn/lm-sensors/trunk@409 7894878c-1315-0410-8ee3-d5d059ff63e0

doc/FAQ

@@ -43,6 +43,7 @@ sensor reading results. Why?
 4.13 I try to read the raw /proc files, but the values are strange?!?
 4.14 How do I set new limits?
 4.15 Some sensors are doubly detected?
+4.16 I ran sensors-detect, but now I get very strange readings?!?
 
 5 How to ask for help: 
 5.1 What to do if it won't insert? 
@@ -197,26 +198,14 @@ boot-time.
 
 3.2 How do I know which chips I own?
 
-	At the moment this is written (just before version 2.1.0 is released),
-the adapter (SMBus host) detection is quite good, but the chip detection
-is quite worthless (I wrote it myself, so I am allowed to say this :-)).
-	As always, the best way to do this is to read the documentation, in
-this case, your mainboard manual (I hope you ever got one; if not, go
-complain to your salesperson). Usually, it tells you what adapter and chips
-are present.
-	If you really have no idea what is supported on your mainboard, you
-will have to experiment. First, try to find out your adapter. First try
-the piix4.o module; if it does not load, try the bit-mb.o (VIA) module.
-You can type 'dmesg' to see what happened. Also, insert the isa.o module;
-it may be enough, even if no other module loads succesfully.
-	Now, the chips. Try the drivers one by one (lm78.o, lm80.o, lm75.o,
-gl518sm.o and w83781d.o at this moment). Type 'sensors' to determine whether
-the read values make any sense. Remove modules if you are convinced that
-the values are bogus. Also, see some of the driver-specific questions below.
-	There will be an automatic detection program in later versions of
-this package; it is only partially  implemented yet. Look for it in the
-prog/detect directory. For 2.2.0, it will only be able to detect the bus
-type, not the chip type.
+	By now, chip detection is fairly good. That means that it is 
+relatively harmless to insert more chip drivers than you need. This approach
+can still lead to problems, though.
+	In the past, you had to muddle your way through and just tried
+several drivers. But starting with 2.3.0, we have an excellent program
+that scans all your hardware. It is called 'sensors-detect' and is
+installed when you call 'make install'. Just execute this script, and
+it will tell you exactly what you want to know.
 
 
 3.3 Which modules should I insert?
@@ -409,10 +398,20 @@ but it is really tough. Double detections can be caused by two things:
 sensors can be detected to both the ISA and the SMBus (and if you have
 loaded the approprate adapter drivers, it will be detected on both), and
 some chips simulate other chips (the Winbond W83781D simulates LM75 chips
-on the SMBus, for example). Remove the offending adapter or chip driver,
-or live with it for now.
+on the SMBus, for example). Remove the offending adapter or chip driver, or
+run sensors-detect and add the insmod parameters it suggests.
 
 
+4.16 I ran sensors-detect, but now I get very strange readings?!?
+
+	Your SMBus (PIIX4?) is probably crashed. There are some mainboards
+which connect a clock chip to the SMBus. Unfortunately, this clock chip
+hangs the PIIX4 if it is read (it is an I2C device, but not SMBus compatible).
+We have found no way of solving this, except for rebooting your computer.
+Next time when you run sensors-detect, you may want to exclude addresses
+0x69 and/or 0x6a, by entering 's' when you are asked whether you want to
+scan the PIIX4.
+
 5 How to ask for help:
 
 	We are always willing to answer questions if things don't work out.

doc/modules

@@ -2,6 +2,9 @@ This is a list of modules, the modules they depend on, and the module
 parameters they define. First, some things about managing all these 
 modules.
 
+Managing Modules
+================
+
 The hardcore way is to insmod each of them by hand. This is not very
 practical, though. It is better to install them in a subdirectory that
 modprobe examines. /lib/modules/current/extra/misc comes to mind.
@@ -11,8 +14,10 @@ which file is used depends on your distribution):
     path[misc]=/lib/modules/current/extra/misc
   (modutils-2.1.x):
     path=/lib/modules/current/extra
-Do always a 'killall -HUP kerneld; depmod -a' after changing either your
-configuration file or changing a module in one of the module directories.
+Do always a 'depmod -a' after changing either your configuration file or 
+changing a module in one of the module directories; you also need to do
+a 'killall -HUP kerneld' if you still use kerneld (kernel 2.2.x usually
+uses kmod.
 
 Now you can do 'modprobe lm78', and all dependent modules are loaded
 automatically. You could, of course, add this statement (and related
@@ -41,6 +46,12 @@ With the above, the managing of all those modules is suddenly no problem
 at all!
 
 
+Available Modules
+=================
+
+This does not list the chip and bus drivers; please examine the directories
+doc/chips and doc/busses for more information about them.
+
 (i2c) i2c-core:
   The core i2c module (surprise!). Almost everything else depends on this one.
   Module parameters:
@@ -56,16 +67,6 @@ at all!
   SMBus emulation on i2c busses. Base algorithm, on which SMBus-only adapters
   rely.
 
-(src/busses) i2c-piix4: smbus i2c-core
-  PIIX4 SMBus access.
-
-(src/busses) i2c-via: algo-bit i2c-core
-  VIA VT82C586B bus access. This is often used instead of the PIIX4 as SMBus
-  host.
-
-(src/busses) i2c-ali15x3: smbus i2c-core
-  Acer Labs M1541 and M1543C bus access.
-
 (src/busses) i2c-isa: i2c-core
   Defines the ISA bus as being a I2C adapter. It isn't, of course; but this is
   often used by sensor client modules, to keep the code small and simple.
@@ -73,34 +74,6 @@ at all!
 (src) sensors: i2c-core
   General purpose routines for sensor client modules
 
-(src/chips) lm78: sensors smbus i2c-core
-  LM78, LM78-J and LM79 chip driver
-
-(src/chips) lm75: sensors smbus i2c-core
-  LM75 chip driver
-
-(src/chips) gl518sm: sensors smbus i2c-core
-  GL518SM revision 0x00 and 0x80 chip driver
-
-(src/chips) adm1021: sensors smbus i2c-core
-  ADM1021 and MAX1617 chip driver 
-
-(src/chips) adm9240: sensors smbus i2c-core
-  ADM9240 chip driver
-
-(src/chips) ltc1710: sensors smbus i2c-core
-  LTC1710 chip driver
-
-(src/chips) sis5595: sensors smbus i2c-core
-  SIS-5595 chipset hardware monitor driver
-
-(src/chips) w83781d: sensors smbus i2c-core
-  W83781D chip driver
-
-(src/chips) eeprom: sensors smbus i2c-core
-  Driver for DIMMs connected to the SMBus. You need prog/eeprom/decode-dimms.pl
-  to make sense of its output.
-
 (i2c) algo-bit: i2c-core
   The 'bit' algorithm, used by many i2c adapters
   Module parameters:
@@ -133,6 +106,7 @@ i2c/old-code.
 Usually, if you load the modules through modprobe, you need the following
 commands:
   modprobe i2c-proc
+  modprobe i2c-dev  # Often not needed; see above
   modprobe i2c-isa  # Unless you are certain no sensor chips live on the ISA bus
   modprobe i2c-piix4 # One such line for each adapter you own
   modprobe lm78     # One such line for each device you own

doc/progs

@@ -7,9 +7,11 @@ this package.
   file. It read /proc/bus/i2c (or the file specified on the command-line),
   and prints to stdout `bus' statements reflecting the currently detected
   adapters.
-* prog/detect/dectect.pl (written in Perl, not installed)
-  This program tries to detect the available SMBus adapters. In time, it will
-  also scan each adapter for supported devices (chips).
+* prog/detect/sensors-detect (written in Perl, installed by 'make install')
+  This program tries to detect the available SMBus adapters and the chips
+  connected to them and/or the ISA bus. It also generates modprobe lines
+  and module options. This program is interactive and will ask you about
+  all information it needs.
 * prog/detect/i2cdetect (written in C, not installed)
   This program scans your complete I2C or SMBus adapter for connected devices.
   Not all devices can be detected in this way, though; and it may hang your
@@ -17,8 +19,17 @@ this package.
     ./i2cdetect 0
   Here the '0' stands for i2c-0 (check /proc/bus/i2c to find out which bus
   you need).
-* prog/doc/doc-features (written in C, not installed)
-  This program is/will be used to help us generate chip driver documentation.
+* prog/doc/doc-features.pl (written in Perl, not installed)
+  This program is used to help us generate driver documentation; it scans
+  some C source programs to do this. Syntax:
+    ./doc-features.pl BASE [PREFIX...]
+  BASE is the path to the base directory of the lm_sensors tree
+  PREFIX is one of more prefixes of chips you want documented; if left out,
+  all chips are documented.
+* prog/doc/doc-insmod.pl (written in Perl, not installed)
+  This program is used to help us generate driver documentation; it reads
+  all module information and outputs insmod parameter information. Syntax:
+    ./doc-insmod.pl DRIVER
 * prog/dump/i2cdump (written in C, not installed)
   This program helps to dump the registers of a I2C device that understands
   the 'byte data' or 'word data' SMBus protocols. Usual syntax:

doc/version-2

@@ -18,3 +18,6 @@ package. Some of the more important ones:
   how all sensor readings are to be interpreted.
 * All code has been completely rewritten.
 * Many new drivers
+
+By now (version 2.3.0) so many things have changed that we do not even try
+to keep the above list up-to-date. Just don't use version 1 anymore.