README file for thinkpad device drivers Last updated: 13 April 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- 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 . Do: tar zxvf thinkpad-.src.tar.gz cd thinkpad- 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//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: mknod --mode=664 /dev/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 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//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/ contains information about each of the drivers. Security ======== The user requires write permission on the thinkpad device file (normally /dev/thinkpad or /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