New file BACKGROUND

This file offers a small tour around all components of our package.


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

BACKGROUND

@@ -0,0 +1,69 @@
+This package consists of many parts. This document offers a small tour
+around the most important pieces. Not all aspects are discussed 
+exhaustively, but it should be enough to give you the feeling you
+understand what you are seeing happen.
+
+When you want to communicate with a piece of hardware, you need a kernel
+driver (well, that is not quite true, but it is in most cases the only
+way to do it safely). In the past, this meant you had to patch the kernel
+and recompile it. These days, you can use kernel modules.
+
+We have chooses for a very modular (no pun intended) setup. There are a
+few general-purpose base kernel modules, which you always need. In 
+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.
+
+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.
+
+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
+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.
+
+libsensors is a (shared or static) library of access functions. It
+knows about every type of chip supported by the kernel modules (or it
+should, if it is up-to-date). It offers a simple-to-use interface for
+applications to access the sensor chip readings, to set new limits,
+and all other commonly needed things. From the application's point of
+view, there is no need to know very much about a specific sensors chip. 
+Having some inside information can still be useful, but it is possible to
+write a generic fall-back function that takes care of newer, unknown
+chips, and to display all really important information.
+
+libsensors takes care of one other thing. The kernel modules report 
+so-called 'as is' values. They have to be scaled or translated to be 
+relevant in the real world. libsensors reads a configuration file 
+(usually /etc/sensors.conf) which specifies how this translation should
+be done (with some other things). Again, the application does not have
+to know about it. And because the configuration file is reread each time
+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
+program is called 'sensors'. You can use it as a reference implementation
+for more intricate programs.
+
+There are many, many kernel modules in this package, and there are lots
+of different sensor chips supported. Sometimes, it can be hard to 
+determine what chips and adapters you have, and which modules correspond
+to them. Fortunately, there is a user-space application 'sensors-detect'
+that should tell you exactly what is available, and what you need to
+do. This perl script uses the /dev interface, and you may use it as an
+example how you can do this.