09/20/99 17:12:11 (15 years ago)

Updated INSTALL and README files

1 modified


  • lm-sensors/trunk/INSTALL

    r546 r567  
    1 ============================================================================= 
    3 ============================================================================= 
    5         - Make sure you have a recent version of the i2c package compiled  
    6           and installed properly. 
    7         - make (ignore 'no such file or directory' warnings) 
    8         - (as root) make install 
    9         - (as root) prog/mkdev/        (makes the devices in /dev) 
    10         - (as root) prog/detect/sensors-detect (determines installed hardware) 
    11         - Place the 'modprobe' commands output by sensors-detect in a 
    12           boot file like /etc/rc.d/rc.multi. 
    13           Make sure it is after 'depmod -a -e' is run. 
    14         - After those commands, put the line 'sensors -s' in the boot file 
    15           to initialize the sensors at boot time 
    16         - Place the lines output by sensors-detect in the module 
    17           configuration file /etc/conf.modules or /etc/modules.conf 
    18         - Reboot 
    19         - Verify correct installation of modules at boot time 
    20         - Use the command 'sensors' to check sensor status. 
    23 ============================================================================= 
    24 ============================================================================= 
    26 Please read this file thoroughly before you try to install and run things. It 
    27 will safe you many headaches. Installation is not really difficult, but there 
    28 are a few pitfalls. 
    30 ALWAYS READ THE `BUGS' FILE! This file contains a list of known  
    31 incompatibilities with this package. Most are highly kernel-dependent and 
    32 usually not fatal, but still. 
    35 ============================ 
    37 Basic installation is uncomplicated. Run `make all', followed by an optional 
    38 `make install'. Everything is compiled using the Makefile in the root of 
    39 this package.  
    41 You need flex and bison (reportedly a version newer than 1.22). You must 
    42 also make sure you have all kernel headers installed properly, including 
    43 the ones created during the kernel compilation. Some of the additional 
    44 programs in the prog/ subdirectory need Perl and GAWK to run, but you 
    45 don't need them to use this package. And you need a fully working compilation 
    46 environment, of course; the program should compile against both libc5 
    47 and glibc2. Like always, we recommend gcc- as the compiler for 
    48 kernel modules, but 2.8.1 and any non-buggy egcs version will very 
    49 probably work too. The modules in this package should work with any 2.0, 
    50 2.1 or 2.2 kernel. 
    52 Some interesting Makefile variables: 
    54 * SMP 
    55   This must be set to 1 if your kernel was compiled with SMP set to 1. There 
    56   is a sort of magic invocation which tries to check this; it will fail if 
    57   you do not have the correct kernel tree in /usr/src/linux. If you set it, 
    58   a `-D__SMP__' argument will be added to all module compiles. 
    59 * MODVER 
    60   This must be set to 1 if your kernel was compiled with CONFIG_MODVERSIONS 
    61   enabled. There is some magic which tries to retrieve this information 
    62   from /usr/include/linux/config.h and /usr/include/linux/autoconf.h. 
    63 * I2C 
    64   If you already have Simon Vogl's i2c package installed, you may not have 
    65   to compile the version included in this package. In that case, check 
    66   the file i2c/MODIFICATIONS in this package to see what versions are 
    67   safe. 
    68 * WARN, DEBUG 
    69   These options should only be needed if you are an active developer of 
    70   this package. 
    71 * PREFIX (/usr/local) 
    72   The prefix which is added to most directory locations below. 
    73 * MODDIR (/lib/modules/extra/misc) 
    74   The directory where `make install' installs your modules. 
    75 * ETCDIR (/etc) 
    76   The directory where `make install' installs the example configuration file 
    77   if none is found there. 
    78 * LIBDIR ($(PREFIX)/lib) 
    79   The directory where `make install' installs the shared and static libraries. 
    80 * BINDIR ($(PREFIX)/bin) 
    81   The directory where `make install' installs all executables. 
    82 * SBINDIR ($(PREFIX)/sbin) 
    83   The directory where `make install' installs all system programs (programs 
    84   which can only be run by root). 
    85 * INCLUDEDIR ($(PREFIX)/include) 
    86   The base directory where `make install' installs your include files. 
    87   Actually, SYSINCLUDEDIR ($(INCLUDEDIR)/linux) is used for kernel header 
    88   files, and LIBINCLUDEDIR ($(INCLUDEDIR)/sensors) is used for library 
    89   header files. 
    90 * MANDIR ($(PREFIX)/man) 
    91   The base directory where manual pages are installed.  
    92 * MANOWN, MANGRP (root, root) 
    93   Owner and group of installed manual pages 
    95 Warning! In 2.2 and newer 2.1 kernels, there is support for I2C. This support  
    96 is NOT compatible with this module! Actually, Simon Vogl's modules package  
    97 (which IS compatible) is scheduled to replace the current support. If you 
    98 actually use these modules, you have a problem; they can not coexist 
    99 with Simon's modules. Theoretically, you should be able to replace 
    100 the old modules in the kernel tree with the new stuff in our i2c directory, 
    101 recompile the kernel, and then compile our modules with I2C=0. If you try 
    102 this, please share the results with us! There have also been some rumors 
    103 about the peaceful coexistence of both sets of modules, but others found 
    104 some problems with it. 
    106 Please make sure that /usr/include/linux and /usr/include/asm are symlinks  
    107 into the kernel tree which corresponds with the kernel version you are using 
    108 now (or more exactly, the kernel which you will use the compiled modules  
    109 with). If the tree and the running kernel do not match, you will either 
    110 be unable to insert the modules at all, or you can expect strange  
    111 behaviour (probably leading to crashes). 
    113 If you do a `make install', remember to do a `depmod -a' and a `ldconfig' 
    114 to make sure the new modules and shared libraries are recognized. If you 
    115 set PREFIX to anything different from `/' or `/usr' (it is `usr/local' 
    116 by default), check whether /etc/ contains the library directory 
    117 (like `/usr/local/lib') before you do the `ldconfig'. 
    119 Do no worry about the `No such file or directory' warnings when you compile 
    120 the package the first time. They are harmless. 
    124 =================== 
    126 When you have compiled this package, you will be left with a lot of modules. 
    127 It can be tricky to know which modules you need to insert. For this reason, 
    128 I suggest you go the `modprobe' way, as described within doc/modules. 
    130 If you just want to run a test without installing them, try the following: 
    131   insmod i2c/i2c-core.o 
    132   insmod kernel/smbus.o 
    133   insmod kernel/i2c-proc.o 
    134   insmod kernel/i2c-dev.o 
    135   insmod kernel/sensors.o 
    136   insmod kernel/busses/i2c-isa.o 
    137   insmod kernel/busses/i2c-piix4.o # Or whatever SMBus controller you have 
    138   insmod kernel/chips/lm78.o   # Or whatever hardware monitoring chip you have 
    139 Now you should have new directories under /proc/sys/dev/sensors and some files 
    140 beginning with i2c in /proc/bus. 
    142 If you have installed the modules, as described within doc/modules, you can 
    143 do: 
    144   modprobe i2c-isa && modprobe i2c-piix4 && modprobe lm78 && modprobe i2c-proc 
    145 (the last is optional) from any directory to reach the same situation. 
    147 But instead of doing any of the above things, please read doc/modules and 
    148 do a `make install'. After that, you can run `sensors-detect'. This Perl 
    149 program will detect all hardware available on your system, and tell you 
    150 what drivers you need to insert. First check whether you have /dev/i2c-* 
    151 files (at least 4 of them), and if not, create them by running `' 
    152 in directory prog/mkdev. 
    154 Do not panic if some (or all) of the values in the /proc/sys/dev/sensors/*/* 
    155 files do not seem to correspond to anything in earlier versions. Starting 
    156 with lm_sensors version 2.1.0, these files will reflect the real chip 
    157 measurements, without any scaling or adjusting. This is most obvious for 
    158 the voltage files. You can specify the conversion factors in a configuration 
    159 file.  Use an application linked to libsensors to read these real values. 
    161 This package contains a library of functions which can be used to 
    162 access sensor data in a more programmer-friendly way. It will be built as 
    163 both a shared and a static library, and installed in your LIB directory 
    164 (normally /usr/local/lib). It needs a configuration file, which is usually 
    165 called `sensors.conf', and can be placed in /etc, /usr/lib/sensors, 
    166 /usr/local/lib/sensors, /usr/lib, or /usr/local/lib. 
    168 Note that if you already have a config file, it is NOT overwritten! You 
    169 may still want to do this by hand (`cp etc/ /etc/sensors.conf') 
    170 as the example config file may be updated. 
    172 Where version 1 of this package had the human-readable /proc/sensors file, 
    173 this version includes a user-space program which gathers all data 
    174 and displays it in a comparable format. This program is called `sensors'. 
    175 Everybody can use it to read sensors values; only root can use it to 
    176 set minimum and maximum values (using the `-s' switch). 
    178 If you want to run `sensors' without installing the package, you must 
    179 use the following command to make it able to find its shared library: 
    180   (bash) export LD_LIBRARY_PATH=/WHEREVER/lm_sensors-2.X.Y/lib:$LD_LIBRARY_PATH 
    181   (tcsh) setenv LD_LIBRARYPATH /WHEREVER/lm_sensors-2.X.Y/lib:$LD_LIBRARY_PATH 
    182 Replace /WHEREVER/lm_sensors-2.X.Y with the base directory of the package 
    183 source code. 
    185 Please examine the files in the doc subdirectory for more information,  
    186 especially about individual drivers. You can always mail us at  
    187 <>. Alternatively, consider useing the (free) 
    188 support site at Good luck! 
    192 =============== 
    194 The prog subdirectory contains lots of useful programs, many of which are 
    195 not installed. doc/progs contains some documentation for each of them. 
    196 Most important are prog/mkdev/, which creates /dev/i2c-* files, 
    197 and prog/detect/sensors-detect, which tries to detect what adapters are 
    198 present on your system. 
     1These are the installation instruction for the lm_sensors package. 
     3There are two ways in which you can compile and install this package. Each 
     4has its own strong points. They are: 
     5 1. Complete separate from kernel compilation 
     6    This will generate a set of modules which can be inserted and removed 
     7    as needed; nothing will be written into the kernel tree; 
     8 2. Patching of the kernel 
     9    This will patch your kernel source tree. You must recompile your kernel 
     10    to take advantage of this. But it makes it possible to compile drivers 
     11    into the kernel itself, instead of having to add them as modules. 
     14Each of these ways will be described below in detail. 
     22Installing the i2c package 
     25As of version 2.4.0 of lm_sensors, all i2c components are distributed in 
     26a separate package. There are install instructions in that package. If 
     27you want to use compilation option 2 (patching the kernel) for lm_sensors, 
     28you will have to use compilation option 3 (patching the kernel) for i2c 
     29too. If you want to use compilation option 1 (compiling as modules) for 
     30lm_sensors, you may use either compilation option 1 or 2 (compiling as 
     31modules) or compilation option 3 (patching the kernel for i2c). See the 
     32table below. 
     34                                          LM_SENSORS 
     35I2C                      | option 1 (modules)      option 2 (patch kernel) 
     36option 1 (modules)       |      YES                      NO 
     37option 2 (modules)       |      YES                      YES 
     38option 3 (patch kernel)  |      YES                      YES 
     41If you use compilation option 1 (compiling as modules) for lm_sensors, you 
     42will have to make very sure the correct i2c header files are found. If you 
     43get weird compilation errors, this is almost certainly going wrong. The 
     44i2c header files are in a i2c subdirectory of either /usr/local/include  
     45(i2c compilation option 1) or /usr/src/linux*/include (i2c compilation 
     46options 2 and 3). Especially if you have in the past placed the header 
     47files in /usr/local/include, this will probably go wrong. See below on 
     48how to fix this. 
     51Having a proper kernel tree (compilation option 1) 
     54Usually, if you compile a user-space application, you can get away with 
     55having a different version of the kernel running than the version of the 
     56kernel header files against which you compiled it. But a perfect match 
     57is needed for the first two compilation options above. 
     59Let's say you want to use the lm_sensors modules with the kernel 2.1.12 you 
     60are running now. What you need, is the original tree in which you 
     61compiled that 2.1.12 kernel. A freshly unpacked 2.1.12 kernel will not 
     62cut it, because `make *config dep' creates some files that are needed. 
     63And even then, you will run into trouble, because you may not have 
     64selected the exact same configuration variables. Plain advise: if you 
     65do not have your original kernel tree anymore, recompile your kernel 
     68Note that there is no need for a perfect match at compilation time, just 
     69at run-time. This means you can cross-compile against a different kernel 
     70version, and the Makefile does not check for this. 
     72Usually problems if the match is imperfect, is that either this package 
     73won't compile at all (because it was a freshly unpacked tree without 
     74some files generated by `make *config dep'), or that you can't insert 
     75modules because of either a `kernel-module version mismatch' or because 
     76of `unresolved kernel symbols'. If you get either of these messages, 
     77check your kernel tree! 
     79Note that some distributions are notably bad at this. To offset this 
     80somewhat, not the files in /usr/include/{linux,asm} are used, but instead 
     81those in /usr/src/linux/include/{linux,asm}. It is also possible to 
     82tell the Makefile the kernel is somewhere else than at /usr/src/linux. 
     85Separate from kernel compilation (compilation option 1) 
     88This will compile and install the complete i2c package. Though nothing is 
     89written to your kernel tree, a proper tree is still needed for this. See 
     90earlier for what a proper kernel tree is. 
     92At the top of the Makefile are a couple of configuration variables that 
     93you may want to change. As far as possible, the Makefile tries to figure 
     94out by itself their settings, but it is possible to overrule them. A list 
     95is found below. Most important are the variables that determine where 
     96your kernel is located (LINUX=/usr/src/linux), where the i2c header files 
     97are (I2C_HEADERS=/usr/local/include) and where you want to install  
     98your modules (MODDIR=/lib/modules/KERNELVERSION/extra/misc) and 
     99header files (LINUX_INCLUDE_DIR=/usr/local/include/linux). You can see 
     100that the installation locations are choosen in such a way that they 
     101are separate from the true kernel. 
     103Compilation is done by `make all'; `make install' installs the package. 
     104You will get a lot of warnings about files which are not found, all  
     105ending on `.*d'. You can safely ignore this; they contain dependency 
     106information, which is regenerated on the spot. 
     108Please continue reading this file before you start compiling. 
     111Makefile configuration variables (compilation option 1) 
     114SHELL (default: /bin/sh) 
     115  You may have to specify the full path to Bash here, if /bin/sh is some 
     116  other shell. There have been conflicting reports on whether this is  
     117  needed. 
     118LINUX default: /usr/src/linux 
     119  The location of your kernel tree. 
     121  This determines whether only the user-space utilities are needed (0)  
     122  or also the kernel modules (1). This is usually determined by checking 
     123  whether the kernel was already patched to include the kernel modules,  
     124  but that is not really foolprool. 
     125I2C_HEADERS default: /usr/local/include 
     126  This lists where the i2c headers are found. If you used compilation 
     127  option 1 for the i2c package, the default will be right. If you used 
     128  compilation options 2 or 3, it will not, and may actually cause 
     129  problems if you have the left-overs of a previous installation. 
     130  If you have weird compilation problems, try to change this to 
     131  $(LINUX_HEADERS). 
     133  This must be set to 1 for a SMP kernel. The magic invocation should 
     134  determine this automatically, so you should not have to bother with  
     135  this. 
     136WARN default: 0 
     137  Generate additional compilation warnings; mainly interesting for 
     138  developers. 
     140  This must be set to 1 if CONFIG_MODVERSIONS is defined. The magic 
     141  invocation should determine this automatically, so you should not 
     142  have to bother with this. 
     143DEBUG default: 0 
     144  Some drivers will issue more debug information if you set this to 
     145  1. Don't do it, unless you are a developer or are instructed to do 
     146  so by the lm_sensors team. 
     147PREFIX default: /usr/local 
     148  Prefix for almost all installation directories 
     149MODDIR default: /lib/modules/KERNELVERSION/extra/misc) 
     150  The location where the kernel modules will be installed.  
     151ETCDIR default: /etc 
     152  Installation location of the sensors.conf configuration file 
     153LIBDIR default: $(PREFIX)/lib 
     154  Installation location of all static and shared libraries. 
     155BINDIR default: $(PREFIX)/bin 
     156  Installation directory of programs useful for users 
     157SBINDIR default: $(PREFIX)/sbin 
     158  Installation directory of system administrator-only programs 
     159INCLUDEDIR default: $(PREFIX)/include 
     160  Base installation directory for include files (see next two vars) 
     161SYSINCLUDEDIR default: $(INCLUDEDIR)/linux 
     162  Installation directory for system include files 
     163LIBINCLUDEDIR default: $(INCLUDEDIR)/sensors 
     164  Installation directory for libsensors include files. 
     165MANDIR default: $(PREFIX)/man 
     166  Base installation directory for manual pages 
     167MANOWN default: root 
     168  Owner of manual pages 
     169MANGRP default: root 
     170  Group of manual pages 
     174Handling the modules (compilation option 1) 
     177Once you have installed the kernel modules, you will have to make sure 
     178they are found. 
     180First, check whether your modutils will look in the right directory at 
     181all. If you used build system 1, you will probably have to add lines 
     182to /etc/conf.modules or /etc/modules.conf (use the one that exists, or 
     183take your pick): 
     184  (modules-2.0.0): 
     185    path[misc]=/lib/modules/current/extra/misc 
     186  (modutils-2.1.x): 
     187    path=/lib/modules/current/extra 
     188This assumes /lib/modules/current will always be linked to the correct 
     189modules tree. If not, you will have to change it as appropriate for 
     190your system. 
     192Next, you will have to run `depmod -a' to have them recognised. Most 
     193distributions run this command when you boot, so if you were cross- 
     194compiling, you can skip this step. 
     196See doc/modules for a more detailed treatment. 
     199Patching the kernel (compilation option 2) 
     202There is a special script which should be able to generate diffs against 
     203any 2.0, 2.1, 2.2 and 2.3 kernel. Please report any problems to our 
     204mailinglist. Note that it may fail, and probably silently, if you have 
     205applied other patches to your kernel tree, or for very new kernels. 
     206It *is* safe to run it if your kernel already has the lm_sensors drivers. 
     207It will only work if you applied the i2c patches first. 
     209The kernel diffs are generated by the program `' in the mkpatch 
     210subdirectory. It needs two arguments: the first one is the root of the 
     211i2c package, the second one is the root of the kernel tree against 
     212which the diffs will be generated. For example: 
     213  cd /tmp/lm_sensors-2.4.0 
     214  mkpatch/ . /usr/src/linux > /tmp/sensors-patch 
     215You can apply the diffs as usual: 
     216  cd /usr/src/linux 
     217  patch -p1 -E < /tmp/sensors-patch 
     218Genearation and application can easily be done in one step: 
     219  mkpatch/ . /usr/src/linux | patch -p1 -E -d /usr/src/linux 
     220The generated diffs are of course only valid for the kernel version  
     221against which was run. 
     223Once you have applied the patches, you can configure and compile your 
     224kernel as usual. You will see the sensors configuration screen under the 
     225`Character Devices' menu in menuconfig, but it will only be available 
     226if you selected base I2C support. 
     229Using the sensors package 
     232You can now load the modules by using `modprobe'. For example, 
     233`modprobe i2c-piix4' will load the i2c-piix4 module, and all i2c modules 
     234on which it depends. 
     236You can not use demand-loading; you will have to issue explicit modprobe 
     239If you have an older installation, you will probably have to create the 
     240i2c device files in the /dev directory. They are called /dev/i2c-%d, 
     241and are character devices with major device number 89 and minor device  
     242number %d. The script prog/mkdev/ will create the files for you. 
     244There is a special scanning program installed called sensors-detect. It 
     245will scan all available I2C and SMBus adapters for all known devices, 
     246and give you a list of what modules you need to insert. It is written in 
     247Perl, and you will need at least Perl 5.004 to run it succesfully. 
     249You can use the installed sensors program to get a report of all detected 
     250sensor devices. There is also a manual page for this program. Calling 
     251`sensors -s' will set the limits and other configuration settings  
     252specified in /etc/sensors.conf. Again, read the manual pages for more 
     256Old and new I2C drivers 
     259In the current 2.2 and 2.3 kernels, there are already I2C drivers, but 
     260they are not the same ones as in this package. They are much older, and 
     261have a very limited functionality compared with the drivers included 
     262here. Fortunately, they can co-exist peacefully, so you should not worry 
     263about it. Except for one thing: `#include <linux/i2c.h>' can cause the 
     264wrong header file to be included. If you patched the kernel (compilation 
     265option 3), you will have to use `#include <linux/i2c-old.h>' to include 
     266the old ones; in all other cases, including the old ones will probably 
     267be impossible without copying them explicitly to some place that will 
     268be checked first.