From 57d2787b5e1f3137f29dd2ff5a04489a58fe2518 Mon Sep 17 00:00:00 2001 From: Jean Delvare Date: Sun, 24 Sep 2006 16:36:34 +0000 Subject: [PATCH] Documentation update. I tried to remove or update all outdated stuff, it looks better now, but that's still quite a mess which we'd need to cleanup. git-svn-id: http://lm-sensors.org/svn/lm-sensors/trunk@4173 7894878c-1315-0410-8ee3-d5d059ff63e0 --- BACKGROUND | 18 ++++++------ BUGS | 4 +-- CONTRIBUTORS | 5 ++-- INSTALL | 69 ++++++++++------------------------------------ QUICKSTART | 23 ++++------------ README | 52 +++++++++++----------------------- README.directories | 3 +- TODO | 47 +++++++++---------------------- 8 files changed, 65 insertions(+), 156 deletions(-) diff --git a/BACKGROUND b/BACKGROUND index bc157c00..a7b452c0 100644 --- a/BACKGROUND +++ b/BACKGROUND @@ -15,23 +15,23 @@ addition, there is one kernel module for each piece of hardware - whether this is an I2C bus adapter, an SMBus adapter or a sensors chip. The kernel modules communicate their information through both the /proc -and sysctl interfaces. To keep things uncomplicated, the sensor chips always -advert their measurements 'as is'. This means that the values they -report are not immediately relevant to you - they must first be scaled -and translated to correspond to the real world. +and sysctl interfaces (Linux 2.4) or the /sys interface (Linux 2.6). To +keep things uncomplicated, the sensor chips always advert their +measurements 'as is'. This means that the values they report are not +immediately relevant to you - they must first be scaled and translated +to correspond to the real world. It is also possible to communicate directly with chips on an I2C bus or SMBus. This is done through /dev files. This is useful if you quickly want to test how a certain chip behaves, without having to -write a kernel driver. It is also dangerous; several applications could -access the same chip at the same time. +write a kernel driver. Note that all other parts of this package function in so-called user-space. This is important, because bugs in kernel-space might crash your computer or do other bad things. And kernel memory can not be swapped out! Applications could (and can) directly read the sensor values through the -/proc or the sysctl interfaces. This is harder then it sounds; because +/proc, sysctl or /sys interfaces. This is harder than it sounds; because no two chips are the same, the information they communicate may also be very unlike. This would mean that every application would have to know about every type of chip. But there is a better solution. @@ -56,8 +56,8 @@ a new application is started, you can change configuration values without having to recompile anything. This package does not contain a nice graphical monitor. Look at the file -doc/useful_addresses for pointers to such programs. It does contain an -example console program that reports all current sensors values. This +doc/useful_addresses.html for pointers to such programs. It does contain +an example console program that reports all current sensors values. This program is called 'sensors'. You can use it as a reference implementation for more intricate programs. diff --git a/BUGS b/BUGS index 44a9deec..b584ba98 100644 --- a/BUGS +++ b/BUGS @@ -1,6 +1,6 @@ Except for many unimplemented things (listed in the TODO file), there may be -true bugs too. If you experience any problems not listed here, -do not hesitate to mail us (see http://www.lm-sensors.org/wiki/FeedbackAndSupport). +true bugs too. If you experience any problems not listed here, do not hesitate +to mail us (see http://www.lm-sensors.org/wiki/FeedbackAndSupport). But read this file and doc/FAQ first, please! ============================================================================ diff --git a/CONTRIBUTORS b/CONTRIBUTORS index 872f6c5c..985418e1 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -1,7 +1,8 @@ This package could not have been created without the help of many, many people. The most notable contributors are listed below. You are probably best off -to use the mailing list (see http://www.lm-sensors.org/wiki/AuthorsAndContributors) -if you have questions, suggestions or problems. +to use the mailing list (see +http://www.lm-sensors.org/wiki/AuthorsAndContributors) if you have questions, +suggestions or problems. * Alexander Larsson Wrote the original lm78 module; lm_sensors version 1 was no more than an diff --git a/INSTALL b/INSTALL index c7ea4e89..89a53585 100644 --- a/INSTALL +++ b/INSTALL @@ -40,8 +40,8 @@ Option 1 is much easier and is recommended. Each of these ways will be described below in detail. NOTE: MAKE SURE YOU HAVE THE I2C-ALGO-BIT DRIVER (PART OF THE I2C PACKAGE) - COMPILED INTO YOUR KERNEL OR AVAILABLE AS A MODULE; SOME SENSORS - DRIVERS DEPEND ON IT! + COMPILED INTO YOUR KERNEL OR AVAILABLE AS A MODULE; SOME I2C/SMBUS + MASTER DRIVERS DEPEND ON IT! NOTE: IN EACH CASE, YOU WILL HAVE TO GET AND INSTALL THE I2C PACKAGE FIRST! SET COMPILE_KERNEL TO 0 IN THE MAIN MAKEFILE FOR OPTION 2, UNLESS @@ -96,7 +96,7 @@ a very new kernel which already has limited or full i2c or lm_sensors support, but you want to use newer versions of the drivers. This is possible, but there are some pitfalls. -If had compiled all i2c and lm_sensors drivers as modules, you are +If you had compiled all i2c and lm_sensors drivers as modules, you are in luck. You can simply compile the newest versions of i2c and lm_sensors and install them. Just make sure the right modules are loaded (best bet: remove the old ones first). @@ -124,9 +124,9 @@ having a different version of the kernel running than the version of the kernel header files against which you compiled it. But a perfect match is needed for the first two compilation options above. -Let's say you want to use the lm_sensors modules with the kernel 2.1.12 you +Let's say you want to use the lm_sensors modules with the kernel 2.4.32 you are running now. What you need, is the original tree in which you -compiled that 2.1.12 kernel. A freshly unpacked 2.1.12 kernel will not +compiled that 2.4.32 kernel. A freshly unpacked 2.4.32 kernel will not cut it, because `make *config dep' creates some files that are needed. And even then, you will run into trouble, because you may not have selected the exact same configuration variables. Plain advise: if you @@ -144,11 +144,6 @@ modules because of either a `kernel-module version mismatch' or because of `unresolved kernel symbols'. If you get either of these messages, check your kernel tree! -Note that some distributions are notably bad at this. To offset this -somewhat, not the files in /usr/include/{linux,asm} are used, but instead -those in /usr/src/linux/include/{linux,asm}. It is also possible to -tell the Makefile the kernel is somewhere else than at /usr/src/linux. - To keep problems to a minimum, please use a 'vanilla' kernel tree, as distributed on ftp://ftp.kernel/org/pub/linux/kernel, and not one patched by your distribution. @@ -250,28 +245,13 @@ MANGRP (default: root) Group of manual pages. - -Handling the modules (compilation option 1) -=========================================== - -Run the command `depmod -a' to have the new modules recognised. Most -distributions run this command when you boot, so if you were cross- -compiling, you can skip this step. - -See doc/modules for a more detailed treatment. - - Patching the kernel (compilation option 2) ========================================== There is a special script which should be able to generate diffs against -any 2.2 or 2.4 kernel (2.4.0 or later). Note that 2.3 kernels are no -longer supported for this compilation option (choose option 1 instead). -Please report any problems to our mailinglist. Note that it may fail, -and probably silently, if you have applied other patches to your kernel \ -tree, or for very new kernels. It *is* safe to run it if your kernel -already has the lm_sensors drivers. It will only work if you applied the -i2c patches first. +any 2.4 kernel (2.4.10 or later). Please report any problems to our +mailing list. It *is* safe to run it if your kernel already has the +lm_sensors drivers. It will only work if you applied the i2c patches first. ** Only a subset of the modules in lm_sensors are patched into the ** ** kernel by the script. See the file mkpatch/FILES to see if the ** @@ -283,12 +263,12 @@ The kernel diffs are generated by the program `mkpatch.pl' in the mkpatch subdirectory. It needs two arguments: the first one is the root of the lm_sensors package, the second one is the root of the kernel tree against which the diffs will be generated. For example: - cd /tmp/lm_sensors-2.4.0 - mkpatch/mkpatch.pl . /usr/src/linux > /tmp/sensors-patch + cd /tmp/lm_sensors-2.10.0 + mkpatch/mkpatch.pl . /usr/src/linux > /tmp/sensors-2.10.0.patch You can apply the diffs as usual: cd /usr/src/linux - patch -p1 -E < /tmp/sensors-patch -Genearation and application can easily be done in one step: + patch -p1 -E < /tmp/sensors-2.10.0.patch +Generation and application can easily be done in one step: mkpatch/mkpatch.pl . /usr/src/linux | patch -p1 -E -d /usr/src/linux The generated diffs are of course only valid for the kernel version against which mkpatch.pl was run. @@ -314,14 +294,10 @@ i2c device files in the /dev directory. They are called /dev/i2c-%d, and are character devices with major device number 89 and minor device number %d. The script prog/mkdev/mkdev.sh will create the files for you. -There is a special scanning program installed called sensors-detect. It +There is a scanning program installed called sensors-detect. It will scan all available I2C and SMBus adapters for all known devices, -and give you a list of what modules you need to insert. It is written in -Perl, and you will need at least Perl 5.004 to run it successfully. - -If `sensors' returns some error message about not being able to load -libsensors, you have to add the directory in which it is installed -(by default /usr/local/lib) to /etc/ld.so.conf and run `ldconfig'. +and will also look for ISA, PCI and Super-I/O chips with sensors, +and give you a list of what modules you need to insert. You can use the installed sensors program to get a report of all detected sensor devices. There is also a manual page for this program. Calling @@ -331,18 +307,3 @@ information. There are many auxiliary programs not installed. You can find them under the prog subdirectory. A list can be found in doc/progs. - - -Old and new I2C drivers -======================= - -In the current 2.2 and 2.3 kernels, there are already I2C drivers, but -they are not the same ones as in this package. They are much older, and -have a very limited functionality compared with the drivers included -here. Fortunately, they can co-exist peacefully, so you should not worry -about it. Except for one thing: `#include ' can cause the -wrong header file to be included. If you patched the kernel (compilation -option 3), you will have to use `#include ' to include -the old ones; in all other cases, including the old ones will probably -be impossible without copying them explicitly to some place that will -be checked first. diff --git a/QUICKSTART b/QUICKSTART index 75621266..b2196aa9 100644 --- a/QUICKSTART +++ b/QUICKSTART @@ -16,7 +16,7 @@ Other methods are described in INSTALL. of these instructions. * Make sure you have the kernel tree corresponding to your current - kernel in /lib/modules/(uname -r)/build. + kernel in /lib/modules/$(uname -r)/build. Even if the source is there, it may not correspond to your running kernel. If so, you will have to recompile your kernel. @@ -30,33 +30,22 @@ Other methods are described in INSTALL. * Download, build, and install the latest i2c package, (i2c-2.9.0 or later). The i2c subsystem found in the Linux 2.4 kernel trees, even the latest ones, is outdated and won't work. - Quickstart for i2c: make; make install; depmod -a + Quickstart for i2c: make; (as root) make install * Go back to the lm_sensors directory. Do `make'. The warnings about .d files at the start are harmless. - If you have compile problems, you probably should not have skipped step 3. - Go back and install the latest i2c package. - If you still have compile problems, you probably should not - have skipped the i2c step above. * Do (as root) `make install'. - * Do (as root) `depmod -a'. - * Verify that /usr/local/lib is listed in /etc/ld.so.conf; - add it if it isn't. - - * Do (as root) `ldconfig'. + if it isn't, add it, then run (as root) `ldconfig'. * Run (as root) `prog/mkdev/mkdev.sh' to create the device files, - unless you already have them or are running devfs. + unless you already have them or are running devfs or udev. * Run (as root) `prog/detect/sensors-detect' to detect your hardware, - put the lines it suggests into /etc/modules.conf - and enter the modprobe lines sensors-detect suggests. - Add the line `sensors -s' after the modprobe lines. - - * Reboot, or else type in the modprobe lines and `sensors -s'. + put the lines it suggests into /etc/modules.conf, and run all + the commands it suggests (`modprobe X', `sensors -s'). * Run `sensors' to see your output. diff --git a/README b/README index 95dfaf06..ba7cf78e 100644 --- a/README +++ b/README @@ -8,12 +8,12 @@ OVERVIEW OF THE LM_SENSORS PACKAGE AND SUMMARY OF SUPPORTED DEVICES -!!! This package is ONLY for 2.6, 2.5, and 2.4 kernels (2.4.10 or later) !!! -!!! THIS PACKAGE REQUIRES i2c-2.9.0 or later!!! +!!! This package is ONLY for 2.6 and 2.4 kernels (2.4.10 or later). !!! +!!! For 2.4 kernels, this package requires i2c-2.9.0 or later. !!! -FOR 2.6/2.5 KERNELS, use only the userspace tools in this package! +FOR 2.6 KERNELS, use only the userspace tools in this package! Build and install them with 'make user' and 'make user_install'. -The kernel modules in this package will not compile for 2.6/2.5; +The kernel modules in this package will NOT compile for 2.6; use the drivers already in the 2.6 kernel. ============================================================================= @@ -25,31 +25,20 @@ Version 1 is now officially unsupported. WARNING! The drivers in this package will work on reasonably recent 2.4 kernels only (2.4.10 and later). Use lm_sensors-2.4.5 for 2.0 kernels. -Use lm_sensors-2.7.0 for 2.2, 2.3, and 2.4.0 - 2.4.9 kernels. -Use the drivers already in the kernel for 2.6/2.5 kernels; if you need +Use lm_sensors-2.7.0 for 2.2, and early 2.4 (up to 2.4.9) kernels. +Use the drivers already in the kernel for 2.6 kernels; if you need additional drivers in 2.6 please port and submit them to us. HOWEVER, the userspace tools in this package will work for -2.4, 2.5, and 2.6 kernels. - -WARNING! You must have at least i2c-2.9.0. -EVEN IF your kernel does contain i2c support! +both 2.4 and 2.6 kernels. The I2C[2] package in existing 2.4 kernels is NOT sufficient -for compilation of this package. - -ADDITIONALLY, i2c-2.9.0 is API compatible to i2c releases 2.7.0 and earlier, -but is not API compatible to i2c releases 2.8.0 - 2.8.8 -due to struct changes. Versions 2.8.x of i2c are considered deprecated. +for compilation of this package. You need i2c-2.9.0 or later. See the lm_sensors download page for further guidance: http://www.lm-sensors.org/wiki/Download -WARNING! If you downloaded this package through our SVN archive, you walk -the cutting edge. Things may not even compile! On the other hand, you will -be the first to profit from new drivers and other changes. Have fun! - ============================================================================= At least the following I2C/SMBus adapters are supported: @@ -59,7 +48,7 @@ At least the following I2C/SMBus adapters are supported: Apple Hydra (used on some PPC machines) ATI IXP200, IXP300, IXP400 DEC 21272/21274 (Tsunami/Typhoon - on Alpha boards) - Intel I801 ICH/ICH0/ICH2/ICH3/ICH4/ICH5/ICH6 (82801xx), 6300ESB, ICH7 + Intel I801 ICH/ICH0/ICH2/ICH3/ICH4/ICH5/ICH6/ICH7/ICH8 (82801xx), 6300ESB Intel PIIX4 (used in many Intel chipsets) Intel I810/I810E/I815/I845G GMCH Intel 82443MX (440MX) @@ -83,7 +72,7 @@ At least the following hardware sensor chips are supported: Fujitsu Siemens Poseidon, Scylla, Hermes Genesys Logic GL518SM, GL520SM, GL523SM Intel Xeon processor embedded sensors - ITE IT8705F, IT8712F embedded sensors + ITE IT8705F, IT8712F Maxim MAX1617, MAX1617A, MAX1619, MAX6650, MAX6651, MAX6633, MAX6634, MAX6635, MAX6657, MAX6658, MAX6659 Microchip TC1068, TCM1617, TCN75 @@ -120,8 +109,8 @@ You may also refer to doc/chips/SUMMARY for details on what each chip can monitor. -We always appreciate testers. If you own a specific monitoring chip listed -on our 'new drivers' page, and are willing to help us out, please contact +We always appreciate testers. If you own a specific monitoring chip we do +not yet (properly) support, and are willing to help us out, please contact us. Even if you have no programming knowledge, you could help us by running new modules and reporting on the results and output. If you want to offer more substantial help, this is very welcome too, of course. @@ -130,12 +119,7 @@ more substantial help, this is very welcome too, of course. Don't ask us whether we support a particular mainboard; we do not know. We *do* know what hardware we support, but usually, it is easier to install everything and run sensors-detect. It will tell you what hardware -you have (and incidentally, what corresponding drivers are needed). You -could also take a look at http://mbm.livewiredev.com/ -(this lists chips found on many mainboard, but regrettably not the adapters -on them) or http://web01.fureai.or.jp/~hirobo/project/reserch_project.html -(yes, it is Japanese; you want the ninth column, and it again lists only -chips, not adapters). +you have (and incidentally, what corresponding drivers are needed). SMBus, also known as System Management Bus, is a protocol for communicating @@ -161,10 +145,6 @@ one of these additional busses, they can be used too. Please read INSTALL before trying to compile and install these modules. There is a lot of additional documentation in the doc/ subdirectory. -Amnong these is a list of supported busses and chips. Regrettably, there -are too many mainboards to keep a list of busses and chips used on them. -On the other hand, we provide a program called 'sensors-detect' which -tries to figure out what hardware is available on your system. The developers of this package can be reached through a mailing-list (see http://www.lm-sensors.org/wiki/AuthorsAndContributors). Do not hesitate @@ -172,9 +152,9 @@ to mail us if you have questions, suggestions, problems, want to contribute, or just want to report it works for you. But please try to read the documentation and FAQ before you ask any questions! -The latest version of this package can always be found on our homepage: -http://www.lm-sensors.org. Pre-release versions can be retrieved -through anonymous SVN; see doc/svn for details. +The latest version of this package can always be found at: +http://www.lm-sensors.org/wiki/Download. Pre-release versions can be +retrieved through anonymous SVN; see doc/svn for details. This package may be distributed according to the GNU General Public License (GPL), as included in the file COPYING. diff --git a/README.directories b/README.directories index 8d1e5b3a..a2b996ec 100644 --- a/README.directories +++ b/README.directories @@ -5,8 +5,7 @@ The directories within this package: * etc A sample configuration file for the 'sensors' program. * kernel - The kernel modules: general SMBus drivers, and specific chip and adapter - drivers. + The kernel modules: I2C/SMBus master drivers, and sensor chip drivers. * lib The user-space sensors support library code. * mkpatch diff --git a/TODO b/TODO index cbc84131..0ef6e580 100644 --- a/TODO +++ b/TODO @@ -2,12 +2,6 @@ LM-Sensors TODO list Contact us if you have comments or wish to help. ------------------------------------------------ -I2C CODE CHANGES -================ - -See TODO in the i2c package. - - KERNEL MODULES ============== @@ -44,10 +38,6 @@ KERNEL MODULES * "uninstall" Makefile target. -* mkpatch. Trace back Configure changes from 2.5 tree and - have it make clean diffs. - Applies to both i2c and sensors. - * ACPI and SMBus host - ACPI subsystem may access SMBus host too. Locks? - On my ancient board using i2c-via, suspend and power switch status @@ -64,36 +54,37 @@ KERNEL MODULES /proc and libsensors; report errors through /proc 'alarms' or new 'fail' entry? See adm1021 for a partial example. -* Add string function in sensors.o * ALL: cleanup_module is void; check also that cleaning up is done properly, now we know that the module will be unloaded whatever we do. + * ALL chip drivers: add a readonly insmod option so we don't cause APM/ACPI to go insane. + * gl518sm: using iterate==2 causes a tread to be started. this thread remains even after setting iterate==1 and/or removing the gl518sm module + * LM78 detection: Tom Webster has proven that the reset bit in the id register can be one (strange!) + * maxilife.c: Introduce new insmod variables + * maxilife.c: Round REG_TO_VID correctly + * icspll.c: Rewrite. The current implementation simply can't work at all. It needs i2c-level access (too bad for SMBus-only adapters). -* w83781d: Some features are still unsupported for the W8378[23]. - Also, alarms seem to give strange results - sometimes, and there are some other minor problems, as indicated by - Jonathan Bradshaw + * Support 10-bit addresses. At this moment, they are supported nowhere, except in Simon Vogl's i2c modules. -* Better general locking, or at least a once-over to check no race-conditions - remain. This is part of the SMP-safeness, and can better be done at once. + * adm9240: check whether the current voltage computations are correct. Probably not, as they are different from the datasheet specifications. Also check for the supported dallas chip. + * lm80: Check how OS alarms work. At page 17 of the sheet, it tells something completely different from the description at page 25. -* gl518sm: Assume that new values are close to old values, so start with - trying to use a small range near the old values (already partially done) + * Add MTP006F chip: http://www.myson.com/Pcd/MTP006/Mtp006.pdf gfiala@s.netic.de (Guido Fiala) has one on his mainboard @@ -111,23 +102,11 @@ LIBRARY temp_over, temp_hyst } * reload does not work (Bison/Flex problem?). + * Some library routines are pretty inefficient right now. + * Library should be split in more separate files, for better linking behaviour. + * Some adm9240 labels start with a digit; change this, it leads to confusing syntax in the conf file (they have to be quoted) - - -PROGRAMS -======== - -* Sensors program needs to print a + before lm75 temperatures - - -OTHERS -====== - -* Examine watchdog-4.3 or later of meskes@debian.org (Michael Meskes) - tsx-11.mit.edu /pub/linux/sources/sbin or - sunsite.unc.edu /pub/linux/system/daemons/watchdog -