From b7bb64350cbcb3388ffa07c70f486be4bf68c1c4 Mon Sep 17 00:00:00 2001 From: Frodo Looijaard Date: Mon, 20 Sep 1999 15:12:11 +0000 Subject: Updated INSTALL and README files git-svn-id: http://lm-sensors.org/svn/lm-sensors/trunk@567 7894878c-1315-0410-8ee3-d5d059ff63e0 --- INSTALL | 466 +++++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 268 insertions(+), 198 deletions(-) (limited to 'INSTALL') diff --git a/INSTALL b/INSTALL index deabc991..99b007d2 100644 --- a/INSTALL +++ b/INSTALL @@ -1,198 +1,268 @@ -============================================================================= -INSTALLATION - SHORT INSTRUCTIONS - NON-KERNEL INSTALLATION -============================================================================= - - - Make sure you have a recent version of the i2c package compiled - and installed properly. - - make (ignore 'no such file or directory' warnings) - - (as root) make install - - (as root) prog/mkdev/mkdev.sh (makes the devices in /dev) - - (as root) prog/detect/sensors-detect (determines installed hardware) - - Place the 'modprobe' commands output by sensors-detect in a - boot file like /etc/rc.d/rc.multi. - Make sure it is after 'depmod -a -e' is run. - - After those commands, put the line 'sensors -s' in the boot file - to initialize the sensors at boot time - - Place the lines output by sensors-detect in the module - configuration file /etc/conf.modules or /etc/modules.conf - - Reboot - - Verify correct installation of modules at boot time - - Use the command 'sensors' to check sensor status. - - -============================================================================= -============================================================================= - -Please read this file thoroughly before you try to install and run things. It -will safe you many headaches. Installation is not really difficult, but there -are a few pitfalls. - -ALWAYS READ THE `BUGS' FILE! This file contains a list of known -incompatibilities with this package. Most are highly kernel-dependent and -usually not fatal, but still. - -COMPILATION AND INSTALLATION -============================ - -Basic installation is uncomplicated. Run `make all', followed by an optional -`make install'. Everything is compiled using the Makefile in the root of -this package. - -You need flex and bison (reportedly a version newer than 1.22). You must -also make sure you have all kernel headers installed properly, including -the ones created during the kernel compilation. Some of the additional -programs in the prog/ subdirectory need Perl and GAWK to run, but you -don't need them to use this package. And you need a fully working compilation -environment, of course; the program should compile against both libc5 -and glibc2. Like always, we recommend gcc-2.7.2.3 as the compiler for -kernel modules, but 2.8.1 and any non-buggy egcs version will very -probably work too. The modules in this package should work with any 2.0, -2.1 or 2.2 kernel. - -Some interesting Makefile variables: - -* SMP - This must be set to 1 if your kernel was compiled with SMP set to 1. There - is a sort of magic invocation which tries to check this; it will fail if - you do not have the correct kernel tree in /usr/src/linux. If you set it, - a `-D__SMP__' argument will be added to all module compiles. -* MODVER - This must be set to 1 if your kernel was compiled with CONFIG_MODVERSIONS - enabled. There is some magic which tries to retrieve this information - from /usr/include/linux/config.h and /usr/include/linux/autoconf.h. -* I2C - If you already have Simon Vogl's i2c package installed, you may not have - to compile the version included in this package. In that case, check - the file i2c/MODIFICATIONS in this package to see what versions are - safe. -* WARN, DEBUG - These options should only be needed if you are an active developer of - this package. -* PREFIX (/usr/local) - The prefix which is added to most directory locations below. -* MODDIR (/lib/modules/extra/misc) - The directory where `make install' installs your modules. -* ETCDIR (/etc) - The directory where `make install' installs the example configuration file - if none is found there. -* LIBDIR ($(PREFIX)/lib) - The directory where `make install' installs the shared and static libraries. -* BINDIR ($(PREFIX)/bin) - The directory where `make install' installs all executables. -* SBINDIR ($(PREFIX)/sbin) - The directory where `make install' installs all system programs (programs - which can only be run by root). -* INCLUDEDIR ($(PREFIX)/include) - The base directory where `make install' installs your include files. - Actually, SYSINCLUDEDIR ($(INCLUDEDIR)/linux) is used for kernel header - files, and LIBINCLUDEDIR ($(INCLUDEDIR)/sensors) is used for library - header files. -* MANDIR ($(PREFIX)/man) - The base directory where manual pages are installed. -* MANOWN, MANGRP (root, root) - Owner and group of installed manual pages - -Warning! In 2.2 and newer 2.1 kernels, there is support for I2C. This support -is NOT compatible with this module! Actually, Simon Vogl's modules package -(which IS compatible) is scheduled to replace the current support. If you -actually use these modules, you have a problem; they can not coexist -with Simon's modules. Theoretically, you should be able to replace -the old modules in the kernel tree with the new stuff in our i2c directory, -recompile the kernel, and then compile our modules with I2C=0. If you try -this, please share the results with us! There have also been some rumors -about the peaceful coexistence of both sets of modules, but others found -some problems with it. - -Please make sure that /usr/include/linux and /usr/include/asm are symlinks -into the kernel tree which corresponds with the kernel version you are using -now (or more exactly, the kernel which you will use the compiled modules -with). If the tree and the running kernel do not match, you will either -be unable to insert the modules at all, or you can expect strange -behaviour (probably leading to crashes). - -If you do a `make install', remember to do a `depmod -a' and a `ldconfig' -to make sure the new modules and shared libraries are recognized. If you -set PREFIX to anything different from `/' or `/usr' (it is `usr/local' -by default), check whether /etc/ld.so.conf contains the library directory -(like `/usr/local/lib') before you do the `ldconfig'. - -Do no worry about the `No such file or directory' warnings when you compile -the package the first time. They are harmless. - - -TESTING AND RUNNING -=================== - -When you have compiled this package, you will be left with a lot of modules. -It can be tricky to know which modules you need to insert. For this reason, -I suggest you go the `modprobe' way, as described within doc/modules. - -If you just want to run a test without installing them, try the following: - insmod i2c/i2c-core.o - insmod kernel/smbus.o - insmod kernel/i2c-proc.o - insmod kernel/i2c-dev.o - insmod kernel/sensors.o - insmod kernel/busses/i2c-isa.o - insmod kernel/busses/i2c-piix4.o # Or whatever SMBus controller you have - insmod kernel/chips/lm78.o # Or whatever hardware monitoring chip you have -Now you should have new directories under /proc/sys/dev/sensors and some files -beginning with i2c in /proc/bus. - -If you have installed the modules, as described within doc/modules, you can -do: - modprobe i2c-isa && modprobe i2c-piix4 && modprobe lm78 && modprobe i2c-proc -(the last is optional) from any directory to reach the same situation. - -But instead of doing any of the above things, please read doc/modules and -do a `make install'. After that, you can run `sensors-detect'. This Perl -program will detect all hardware available on your system, and tell you -what drivers you need to insert. First check whether you have /dev/i2c-* -files (at least 4 of them), and if not, create them by running `mkdev.sh' -in directory prog/mkdev. - -Do not panic if some (or all) of the values in the /proc/sys/dev/sensors/*/* -files do not seem to correspond to anything in earlier versions. Starting -with lm_sensors version 2.1.0, these files will reflect the real chip -measurements, without any scaling or adjusting. This is most obvious for -the voltage files. You can specify the conversion factors in a configuration -file. Use an application linked to libsensors to read these real values. - -This package contains a library of functions which can be used to -access sensor data in a more programmer-friendly way. It will be built as -both a shared and a static library, and installed in your LIB directory -(normally /usr/local/lib). It needs a configuration file, which is usually -called `sensors.conf', and can be placed in /etc, /usr/lib/sensors, -/usr/local/lib/sensors, /usr/lib, or /usr/local/lib. - -Note that if you already have a config file, it is NOT overwritten! You -may still want to do this by hand (`cp etc/sensors.conf.eg /etc/sensors.conf') -as the example config file may be updated. - -Where version 1 of this package had the human-readable /proc/sensors file, -this version includes a user-space program which gathers all data -and displays it in a comparable format. This program is called `sensors'. -Everybody can use it to read sensors values; only root can use it to -set minimum and maximum values (using the `-s' switch). - -If you want to run `sensors' without installing the package, you must -use the following command to make it able to find its shared library: - (bash) export LD_LIBRARY_PATH=/WHEREVER/lm_sensors-2.X.Y/lib:$LD_LIBRARY_PATH - (tcsh) setenv LD_LIBRARYPATH /WHEREVER/lm_sensors-2.X.Y/lib:$LD_LIBRARY_PATH -Replace /WHEREVER/lm_sensors-2.X.Y with the base directory of the package -source code. - -Please examine the files in the doc subdirectory for more information, -especially about individual drivers. You can always mail us at -. Alternatively, consider useing the (free) -support site at http://www.netroedge.com/~lm78/support.html. Good luck! - - -USEFUL PROGRAMS -=============== - -The prog subdirectory contains lots of useful programs, many of which are -not installed. doc/progs contains some documentation for each of them. -Most important are prog/mkdev/mkdev.sh, which creates /dev/i2c-* files, -and prog/detect/sensors-detect, which tries to detect what adapters are -present on your system. +These are the installation instruction for the lm_sensors package. + +There are two ways in which you can compile and install this package. Each +has its own strong points. They are: + 1. Complete separate from kernel compilation + This will generate a set of modules which can be inserted and removed + as needed; nothing will be written into the kernel tree; + 2. Patching of the kernel + This will patch your kernel source tree. You must recompile your kernel + to take advantage of this. But it makes it possible to compile drivers + into the kernel itself, instead of having to add them as modules. + YOU WILL STILL HAVE TO COMPILE THIS PACKAGE TO GET THE USERLAND UTILITIES! + +Each of these ways will be described below in detail. + +NOTE: OPTION 2 WILL CURRENTLY NOT WORK FOR 2.0 AND OLDER 2.1 KERNELS! + +NOTE: IN EACH CASE, YOU WILL HAVE TO GET AND INSTALL THE I2C PACKAGE FIRST! + + + +Installing the i2c package +========================== + +As of version 2.4.0 of lm_sensors, all i2c components are distributed in +a separate package. There are install instructions in that package. If +you want to use compilation option 2 (patching the kernel) for lm_sensors, +you will have to use compilation option 3 (patching the kernel) for i2c +too. If you want to use compilation option 1 (compiling as modules) for +lm_sensors, you may use either compilation option 1 or 2 (compiling as +modules) or compilation option 3 (patching the kernel for i2c). See the +table below. + + LM_SENSORS +I2C | option 1 (modules) option 2 (patch kernel) +option 1 (modules) | YES NO +option 2 (modules) | YES YES +option 3 (patch kernel) | YES YES + + +If you use compilation option 1 (compiling as modules) for lm_sensors, you +will have to make very sure the correct i2c header files are found. If you +get weird compilation errors, this is almost certainly going wrong. The +i2c header files are in a i2c subdirectory of either /usr/local/include +(i2c compilation option 1) or /usr/src/linux*/include (i2c compilation +options 2 and 3). Especially if you have in the past placed the header +files in /usr/local/include, this will probably go wrong. See below on +how to fix this. + + +Having a proper kernel tree (compilation option 1) +================================================== + +Usually, if you compile a user-space application, you can get away with +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 +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 +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 +do not have your original kernel tree anymore, recompile your kernel +first. + +Note that there is no need for a perfect match at compilation time, just +at run-time. This means you can cross-compile against a different kernel +version, and the Makefile does not check for this. + +Usually problems if the match is imperfect, is that either this package +won't compile at all (because it was a freshly unpacked tree without +some files generated by `make *config dep'), or that you can't insert +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. + + +Separate from kernel compilation (compilation option 1) +======================================================= + +This will compile and install the complete i2c package. Though nothing is +written to your kernel tree, a proper tree is still needed for this. See +earlier for what a proper kernel tree is. + +At the top of the Makefile are a couple of configuration variables that +you may want to change. As far as possible, the Makefile tries to figure +out by itself their settings, but it is possible to overrule them. A list +is found below. Most important are the variables that determine where +your kernel is located (LINUX=/usr/src/linux), where the i2c header files +are (I2C_HEADERS=/usr/local/include) and where you want to install +your modules (MODDIR=/lib/modules/KERNELVERSION/extra/misc) and +header files (LINUX_INCLUDE_DIR=/usr/local/include/linux). You can see +that the installation locations are choosen in such a way that they +are separate from the true kernel. + +Compilation is done by `make all'; `make install' installs the package. +You will get a lot of warnings about files which are not found, all +ending on `.*d'. You can safely ignore this; they contain dependency +information, which is regenerated on the spot. + +Please continue reading this file before you start compiling. + + +Makefile configuration variables (compilation option 1) +============================================================== + +SHELL (default: /bin/sh) + You may have to specify the full path to Bash here, if /bin/sh is some + other shell. There have been conflicting reports on whether this is + needed. +LINUX default: /usr/src/linux + The location of your kernel tree. +COMPILE_KERNEL + This determines whether only the user-space utilities are needed (0) + or also the kernel modules (1). This is usually determined by checking + whether the kernel was already patched to include the kernel modules, + but that is not really foolprool. +I2C_HEADERS default: /usr/local/include + This lists where the i2c headers are found. If you used compilation + option 1 for the i2c package, the default will be right. If you used + compilation options 2 or 3, it will not, and may actually cause + problems if you have the left-overs of a previous installation. + If you have weird compilation problems, try to change this to + $(LINUX_HEADERS). +SMP + This must be set to 1 for a SMP kernel. The magic invocation should + determine this automatically, so you should not have to bother with + this. +WARN default: 0 + Generate additional compilation warnings; mainly interesting for + developers. +MODVER + This must be set to 1 if CONFIG_MODVERSIONS is defined. The magic + invocation should determine this automatically, so you should not + have to bother with this. +DEBUG default: 0 + Some drivers will issue more debug information if you set this to + 1. Don't do it, unless you are a developer or are instructed to do + so by the lm_sensors team. +PREFIX default: /usr/local + Prefix for almost all installation directories +MODDIR default: /lib/modules/KERNELVERSION/extra/misc) + The location where the kernel modules will be installed. +ETCDIR default: /etc + Installation location of the sensors.conf configuration file +LIBDIR default: $(PREFIX)/lib + Installation location of all static and shared libraries. +BINDIR default: $(PREFIX)/bin + Installation directory of programs useful for users +SBINDIR default: $(PREFIX)/sbin + Installation directory of system administrator-only programs +INCLUDEDIR default: $(PREFIX)/include + Base installation directory for include files (see next two vars) +SYSINCLUDEDIR default: $(INCLUDEDIR)/linux + Installation directory for system include files +LIBINCLUDEDIR default: $(INCLUDEDIR)/sensors + Installation directory for libsensors include files. +MANDIR default: $(PREFIX)/man + Base installation directory for manual pages +MANOWN default: root + Owner of manual pages +MANGRP default: root + Group of manual pages + + + +Handling the modules (compilation option 1) +=========================================== + +Once you have installed the kernel modules, you will have to make sure +they are found. + +First, check whether your modutils will look in the right directory at +all. If you used build system 1, you will probably have to add lines +to /etc/conf.modules or /etc/modules.conf (use the one that exists, or +take your pick): + (modules-2.0.0): + path[misc]=/lib/modules/current/extra/misc + (modutils-2.1.x): + path=/lib/modules/current/extra +This assumes /lib/modules/current will always be linked to the correct +modules tree. If not, you will have to change it as appropriate for +your system. + +Next, you will have to run `depmod -a' to have them 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.0, 2.1, 2.2 and 2.3 kernel. 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. + +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 +i2c 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 +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: + 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. + +Once you have applied the patches, you can configure and compile your +kernel as usual. You will see the sensors configuration screen under the +`Character Devices' menu in menuconfig, but it will only be available +if you selected base I2C support. + + +Using the sensors package +========================= + +You can now load the modules by using `modprobe'. For example, +`modprobe i2c-piix4' will load the i2c-piix4 module, and all i2c modules +on which it depends. + +You can not use demand-loading; you will have to issue explicit modprobe +instructions. + +If you have an older installation, you will probably have to create the +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 +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 succesfully. + +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 +`sensors -s' will set the limits and other configuration settings +specified in /etc/sensors.conf. Again, read the manual pages for more +information. + + +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. -- cgit v1.2.1