The tpctl tool and the thinkpad modules

- obsolete -

If you own a new ThinkPad then you are looking for this other page.


Description | Download | Log | Background | GNOME configure-thinkpad | Authors | SF project page

Log:

Description

Most people will want to use tp_smapi. It exposes some SMAPI funtionality via a sysfs interface. See the ThinkWiki page for more information.

For old ThinkPad models with which tp_smapi does not work one could consider using tpctl and the thinkpad modules, but these have not been updated to work with the latest versions of Linux; so the following information is more of historical than of practical interest. (Updating the thinkpad modules to work with recent versions of Linux would be possible, but there is little motivation to do so.)

tpctl is a package of configuration tools for Linux. 

The centrepiece of the package is tpctl, a program that does some of what PS2.EXE does under DOS and the ThinkPad Configuration program does under Windows.  (See the README file for a comparison of tpctl's features with those of PS2.EXE.  You can consult this in combination with this compendium of all the PS2.EXE help outputs on my ThinkPad 600.) 

tpctl gives the user access to all the functions of the SMAPI BIOS that are documented in the various ThinkPad Technical Reference manuals.  It can also control the resources used by the parallel and serial ports.  The USAGE output and the README file should give a rough idea of what the program can do.

tpctl accesses SMAPI and hardware resources through the drivers provided in the thinkpad package.

Programs included in the most recent tpctl packages

Background: Resource configuration tools

"Easy Setup", i.e., the firmware setup program

A contributor to the linux-thinkpad mailing list says:

"The engineering group that designed the 755C/CS/CD was located in Japan. That was the first series that included Easy Setup. ... The bird in Easy Setup is a hummingbird. The best thing about Easy Setup is the self-test that you can run in it. You can get to some extended tests (like a very good floppy test) by doing a Cntl-A and Cntl-D while in the test screen. It will let the bios do loopback tests on the serial and parallel ports (if you have loopback connectors) and it will format a floppy disk to make sure the floppy drive can write correctly."

Function keys

Some ThinkPad function keys run firmware routines that control certain runtime aspects of the ThinkPad's behavior, without OS support.  On my ThinkPad 600X, for example, all of the following work as usual under Linux:
   F3 -- suspend
   F4 -- standby
   F7 -- toggle video output mode
   F11 -- toggle power expenditure mode (between "high", "auto" and "manual")
   F12 -- hibernate
(Additionally, the state of keys F2 ("battery monitor") and F8 (unlabelled) can be watched via the /dev/nvram device.  YMMV.) 

Microsoft-OS-based utilities

The ThinkPad configuration utility for Windows and the Windows Device Manager and the DOS program PS2.EXE use the PnP and SMAPI BIOSes to configure devices. 

PS2.EXE is the most capable of all the utilities, with one exception: it too narrowly restricts the resource assignments that you can make. 

I recommend keeping a DOS partition on your hard drive large enough to hold some version of DOS, your hibernation file and a copy of the ThinkPad utilities for DOS. 

I obtained the latest "ThinkPad Utilities for DOS" package (ver 4.30 as of this writing) via the IBM ThinkPad 600X (2646-8EU) support page at IBM's PC support website.  It comes as a file called 'uttpcdos.exe' which when run extracts itself onto a floppy.  The contents of the floppy can then be copied onto the hard drive. 

Here is a file containing all the PS2.EXE help outputs on my ThinkPad 600 (2645-51U).

Note that Windows remembers configuration settings by storing them in the registry.  Consequently, if you make changes to the hardware configuration, even using PS2.EXE or setpnp, even storing them in nonvolatile memory, and then boot Windows, Windows will sometimes change the settings back to what it remembers.  Another good reason not to boot Windows.

PnP BIOS

(Thanks to Till Straumann for cluing me in to the following information!)

The lspnp and setpnp programs can be used to interact with the PnP BIOS in order to query and set resource assignments. 

For this to work, PnP BIOS support has to be available in the kernel.  Alan Cox kernels from 2.4.3-ac9 to 2.4.13-ac8 included this support, but it wasn't until 2.4.10-ac5 that a number of bugs were fixed.  The driver made it into 2.5.3.  It is also available as a patch to current 2.4 kernels.  (Of course, you need to select PnP BIOS support when you configure the kernel sources for compilation.)  If you are using an earlier kernel, you can get (buggy) PnP BIOS support by selecting PnP BIOS support when you configure and compile the David Hinds PCMCIA drivers.

An example of how to use these tools: To enable the serial infrared interface at ioaddr 0x3e8 with IRQ4, do:
   setpnp -b 13 io 0x3e8 irq 4
   setpnp 13 on
and to disable it do:
   setpnp 13 off
Here, 13 is the number (in hexadecimal!) of the serial infrared device on my machine.  Use the '-b' option to tell the PnP BIOS to make the changes to the nonvolatile, "boot" values.  Without the '-b' option, setpnp changes the volatile "current" values.  Note, however, that all kernels prior to 2.4.9-ac15 contain bugs such that the boot and current values are swapped.  Therefore until you install a fixed kernel (best to get 2.4.10-ac10 or later) you must use '-b' to change the current values and the absence of '-b' to change the boot values, and avoid the "on" argument.  I recommend updating your kernel. 

Furthermore, at present the setpnp utility contains a bug such that the value 0 for irq or dma is interpreted as "disable".  This has been fixed in release 3.1.30 of pcmcia-cs.  Unfortunately, the release that is going into Debian woody is 3.1.29 . 

Here is the output of lspnp on my ThinkPad 600 and on my ThinkPad 600X, listing the devices whose resource usage can be controlled.

You can check that the changes have been made to hardware registers by running "tpctl --rx", which prints out the current configuration of the hardware.

isa-pnp driver

On my ThinkPad the PnP BIOS always configures ISA PnP devices at boot time, so the Linux isa-pnp driver (which was formerly distributed with the ALSA drivers but is now in the official kernel sources in the drivers/pnp/ directory) sees nothing to configure and reports "No Plug & Play device found" when it loads.  Therefore it's not of any use. 

isapnp utility

The isapnp utility in the isapnptools package does in user space what the isa-pnp driver does in kernel space.  It is of no use for the same reason that the isa-pnp driver is of no use.

lshw

The lshw command in the lshw package prints the machine's hardware component list on the console in tree form.

tpctl

tpctl uses the SMAPI and APM BIOSes and direct hardware accesses to control certain features of the ThinkPad.  There may be discrepancies between what tpctl and lspnp report as the resource usage of hardware devices.  This is because tpctl talks directly to device registers, so it reports the present configuration, while lspnp reports the configuration reported by the PnP BIOS, which may only be what the configuration will be once the machine is rebooted.  Note that tpctl's settings are volatile (lost on reboot) while those of PS2.EXE and the ThinkPad Configuration program are nonvolatile (retained across reboots).  This limitation of tpctl's can be overcome by inserting tpctl commands in one of the startup scripts, e.g., /etc/init.d/local

FYI, on my ThinkPad 600X:
tpctl --hibernate does exactly the same thing as Fn-F12. 
tpctl --suspend does exactly the same thing as Fn-F4. 
tpctl --standby does exactly the same thing as Fn-F3. 
tpctl --pm* changes the same settings as Fn-F11 does. 

Requirements

Hardware
Not all ThinkPad models have all the hardware and software required for all tpctl functions to work.  Most tpctl functions require that the machine have the SMAPI BIOS. 

Here is the list of "tpctl --ib" outputs that I have received so far.  Consult this list to see if your model is supported. 

Kernel
The current thinkpad package contains drivers for Linux 2.2 (all point releases) and Linux 2.4 (2.4.19 and up) plus experimental drivers for Linux 2.5.

Software
The ncurses-devel RPM or the libncurses[45]-dev DEB is required to compile tpctl.

Download

Sources:

The last thinkpad modules source tarball. The last tpctl source tarball. The last configure-thinkpad source tarball.

Release notes

   Consult the ChangeLog of the latest tpctl tarball. 
   Consult the ChangeLog of the latest thinkpad tarball. 
   Consult the CHANGES of the latest tp_smapi tarball. 

Configuration

If you use the tp_smapi module, you don't need to configure anything after installation.

If you use the thinkpad module, your modules.conf file should contain the following lines:
   keep
   path[thinkpad]=/lib/modules/`uname -r`/thinkpad
If you are not using devfs you also need the following line:
   alias char-major-10-170 thinkpad
whereas if you are using devfs, you also need the following line:
   alias /dev/thinkpad thinkpad
   alias /dev/thinkpad/thinkpad thinkpad
   alias /dev/thinkpad/smapi smapi
   alias /dev/thinkpad/superio superio
   alias /dev/thinkpad/rtcmosram rtcmosram
   alias /dev/thinkpad/thinkpadpm thinkpadpm
and you also should have a file /etc/devfs/conf.d/thinkpad containing something like the following:
   REGISTER ^thinkpad/.*$ PERMISSIONS root.thinkpad 0664
Here I assume that you have already created a "thinkpad" group which will comprise all the users who will be permitted to use tpctl to change laptop settings.  If you don't create such a group, then use the line:
   REGISTER ^thinkpad/.*$ PERMISSIONS root.root 0664

Development status

tpctl is considered by its author to be obsolete. 

thinkpad 4.999 includes drivers for Linux 2.6 but these must be considered beta quality at present. 

Feedback please!  Please tell me whether or not the program works for you!  Also, please send me your "tpctl --ib" outputs along with the exact model number of your machine.   This will allow me to figure out what each system ID corresponds to.

Links to tpctl-related programs

Links to other tools that may be useful to ThinkPad owners

The results of various rummagings in the ThinkPad hardware

Bochs, roughly speaking, emulates an x86 PC. 
DOSemu, roughly speaking, emulates a PC with DOS installed on it. 
Wine, roughly speaking, emulates a PC with (DOS and) some version of Windows installed on it. 

In December 1999 I tried running PS2.EXE under Bochs. I booted Windows 95 in "command prompt only" mode, executed "format a: /s" to create a boot floppy, and copied the following files to the floppy from my c:\thinkpad directory:
   PS2.EXE
   PS2MAIN.EXE
   PS2.MSG
I then booted this copy and found that PS2.EXE ran correctly.
I booted Linux and followed the installation instructions for Bochs. I copied the boot floppy to a file for bochs to use as its "floppya". I then started Bochs with the latter file as the boot device. When it said "Starting Windows 95" I pressed F8 and selected "command prompt only" mode and received the usual DOS prompt in the Bochs window. However when I executed "PS2" I received the message that "This program cannot be run on this system."

I had similar results when I tried to run PS2.EXE under the version of DOSemu that ships with RedHat Linux 6.1.

For its part, the ThinkPad Configuration program crashes Wine. I could tell by disassembing the code that at least *some* configuration actions are performed by relatively straightforward calls to Windows 95 (e.g. KERNEL32's "device IO control" function).  However the ThinkPad Configuration program as a whole doesn't run under Wine as yet because Wine has not yet implemented certain aspects of the ADVAPI, e.g., "OpenSCManager" and "OpenService".  I am told that these are not likely to be implemented anytime soon since they're hard (in more than one sense).
In order to run the TC program under Wine I cd'ed to /c/thinkpad (which is where C:\THINKPAD appears on my system) and did:
   wine tpw95.exe -debugmsg +dll,+relay -winver win95
(Without "-winver win95" the program exits immediately with a beep.)

I also played around with the lm_sensors stuff.  The ThinkPad Quick Reference guide mentions that the ThinkPad 600 has an "LM75 digital thermometer" and I thought it would be fun to use this to monitor the temperature of my ThinkPad CPU as I compile Wine during a Baltimore heatwave.  ;-)  However I couldn't get the code to recognize the device.
Update, March 2000: no success with the latest lm_sensors release (2.5.0).
Update, November 2000: Some people have reported that lm_sensors code corrupted the EEPROM on their ThinkPads.  Beware! See Bill Mair's site for more information.

The authors of the ThinkPad configuration tools for Linux

Thomas Hood, who has a Debian GNU/Linux on a ThinkPad 600 page.
Bill Mair, who has a cool ThinkPad 770X page.
Nathan Hand
Christian Lademann
Fabrice Bellet
Rob Radez <ibpn_AT_users.sourceforge.net>

This page maintained by Thomas Hood <jdthood_AT_yahoo.co.uk>.