                         README file for
                      thinkpad device drivers

Last updated: 27 Nov 2002

Introduction
============

thinkpad.o, smapi.o, superio.o, rtcmosram.o and thinkpadpm.o are loadable
kernel modules that serve as interfaces to the IBM System Management
Application Program Interface (SMAPI) BIOS found in some IBM ThinkPad laptop
computers, and as drivers of certain ThinkPad hardware components.  Access
to the modules is via the ioctl() system call.  Each module adds an entry
under /proc/driver/thinkpad named like itself which contains some information
about the module.

These drivers were written to be used with the tpctl program.
Please see the README file for that program for more information.

Requirements
============

Hardware
--------

IBM ThinkPad laptop computer.  See the SUPPORTED-MODELS file for more
information.  If this file wasn't included in the thinkpad package, look
for it in the tpctl package.

Kernel
------

The 3.x releases of the drivers support Linux 2.4.0 or later.


Installation
============

If you are using Debian, install the thinkpad-base package, then 
install the thinkpad-source package and use make-kpkg to make a
thinkpad-modules-<your.kern.ver> package for your kernel and install
that.  You are finished.

On distributions that don't set things up for you automatically,
you can install from the source tarball.  First make sure that your
kernel source tree is at /lib/modules/`uname -r`/build and make
sure that the file include/linux/modversions.h is in that tree.
(It is generated by the "make dep" command in the kernel build
procedure.)  Then do:
	tar zxvf thinkpad_<ver.num>.src.tar.gz
	cd thinkpad-<ver.num>

If you are running Linux 2.5, do:
	make all

If you are running Linux 2.4, do:
	mkdir 2.5
	mv drivers include 2.5
	ln -s 2.4/drivers drivers
	ln -s 2.4/include include
	make all

If you are running Linux 2.2, do:
	mkdir 2.5
	mv drivers include 2.5
	ln -s 2.2/drivers drivers
	ln -s 2.2/include include
	make all

Once compilation has finished, to install the files do the following
(as root):
	make install
This installs the loadable kernel modules under the directory
/lib/modules/<running-kernel-version>/thinkpad .

You may want to follow this with:
	make clean
which deletes all compiled binaries from your source directory.

If you do _not_ use devfs then you must create a device node for the
thinkpad device driver.  As root do:
	mkdir --mode=755 /dev/thinkpad
	mknod --mode=664 /dev/thinkpad/thinkpad c 10 170

If you _do_ use devfs you don't need to make a node; the driver
modules will create nodes under /dev/thinkpad when they are loaded.

It might be useful to create a "thinkpad" group and add to it users
whom you want to allow to adjust settings.  Then the device node's
group should be changed to "thinkpad".  Without devfs do this as
root:
	chown root.thinkpad /dev/thinkpad/thinkpad
With devfs, to make this change permanent, add the following line to
/etc/devfsd.conf and restart devfsd:
	REGISTER ^thinkpad/.*$    PERMISSIONS root.thinkpad  0664

The package is now installed.


Uninstallation
==============

To remove all installed thinkpad device driver files:
	make uninstall

Note that this removes /lib/modules/<running.kernel.version>/thinkpad
and all its contents and subdirectories!


Usage -- modules
================

The modules are loaded automatically when they are needed.

thinkpad.o dispatches requests to the other modules.  It can be loaded with
the following parameters:
	enable_smapi=(0|1)       disable|enable use of smapi module
	enable_superio=(0|1)     disable|enable use of superio module
	enable_rtcmosram=(0|1)   disable|enable use of rtcmosram module
	enable_thinkpadpm=(0|1)  disable|enable use of thinkpadpm module
E.g.,
	insmod thinkpad enable_superio=0
loads the thinkpad module while preventing it from using the superio module.
tpctl commands that employ the superio module will then return an error
message.  The default value of each parameter is 1.  These parameters can be
added to the /etc/modules.conf or /etc/conf.modules file as follows so that
they are in effect whenever thinkpad.o loaded by modprobe.  E.g.,
	options thinkpad enable_smapi=0 enable_superio=0
These parameters were added so that thinkpad.o can be used "safely" on
ThinkPads which lack some of the supported hardware.

The file /proc/thinkpad/<module_name> contains information about each of
the drivers.


Security
========

The user requires write permission on the thinkpad device file (normally
/dev/thinkpad/thinkpad) in order to change settings or to "sedate"
the machine.  This means that it is safe to allow an untrusted user to
execute tpctl or ntpctl, so long as he or she doesn't have write
permission on the device file.


References
==========

In writing the code I found the following documentation helpful.
With the advent of kernel 2.4.0 much of their content is out of date.

------------------------------------------------------------------------

IBM.  _IBM ThinkPad 560Z Technical Reference_.  First ed (October 1998).
	_IBM ThinkPad 560 Technical Reference_.
	_IBM ThinkPad 600 Technical Reference_.
	_IBM ThinkPad 765 Technical Reference_.
	_IBM ThinkPad 770 Technical Reference_.

National Semiconductor.  _PC87338/PC97338 data sheet_.   November, 1998.

Pomerantz, Ori.  _Linux kernel module programming guide_.  Version 1.1.0
	26 April 1999.

Rubini, Alessandro.  _Linux device drivers_.  Cambridge: O'Reilly, 1998.

Rubini, Alessandro and Jonathan Corbet.  _Linux device drivers_.  2nd ed.
	Cambridge, O'Reilly, 2001.
	http://www.oreilly.com/catalog/linuxdrive2/chapter/book/index.html

------------------------------------------------------------------------

The first of the IBM Technical Reference manuals listed is the most
current and correct that I have found.  All are available in the
"support" section of IBM's website www.ibm.com.

I thank Ori Pomerantz for his contribution.

The O'Reilly book, now in its second edition, is superb.

--
Thomas Hood
