README file for tpctl ThinkPad configuration tools for Linux Last updated: 10 July 2003 Introduction ============ Execute man ./tpctl.1 to see the tpctl man page. libsmapidev.o is a library of functions that can be used to access (some of) the features of the SMAPI BIOS via the smapi driver. (See below for information about drivers.) tpctl is a console interface to the drivers. ntpctl is an ncurses interface to the drivers. apmiser is a daemon that uses tpctl to control the power expenditure mode dynamically according to CPU load. See the README file in the "apmiser" directory for more information. These programs require the "thinkpad drivers". The object files thinkpad.o, smapi.o, superio.o, rtcmosram.o and thinkpadpm.o are drivers in the form of loadable kernel modules which 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. Please see the README file in the thinkpad drivers tarball for more information. tpctlir will enable or disable the infrared port on ThinkPads with Programmable Option Select registers: e.g., the 760 and 765. Newer ThinkPads such as the ThinkPad 600 do not seem to have these registers. See the README file in the "tpctlir" directory for more information. Requirements ============ Hardware -------- The file "SUPPORTED-MODELS" lists supported models. If you have a ThinkPad 570 and you get an error message when you do "tpctl --pdx", see the TROUBLESHOOTING file for a solution. Software -------- The thinkpad device drivers are required for tpctl, ntpctl and apmiser to work. The "ncurses-devel" RPM or the "libncurses4-dev" DEB is required to compile tpctl. Compatibility ============= If you receive an error message saying that the module is incompatible with your kernel or that thinkpad.o can't be loaded, please read the TROUBLESHOOTING file. Installation ============ First install the thinkpad device drivers. See the thinkpad tarball or the thinkpad-base deb README for more information about how to do that. If you are using Debian then the simplest thing to do next is to install the latest tpctl deb. If you are using RedHat then there may be an rpm available: check the tpctl home page at tpctl.sourceforge.net for information about that. After installing one or the other package, you are done. Otherwise install from the tarball. To install from the source tarball do the following. Next install the tpctl programs. To build them do: tar zxvf tpctl_.src.tar.gz cd tpctl- make all Then to install them do: make install tpctl and ntpctl are installed in /usr/bin. The library libsmapidev.so.2 is installed in /usr/lib. If you want to use different locations then change the macros in Makefile-common, or simply perform the copies manually and set the appropriate permissions. You may want to follow this with: make clean which deletes the binaries from the source directory. The package is now installed. Uninstallation ============== Do: make uninstall Usage -- tpctl ============== The command: tpctl --help | more outputs a usage listing which is designed to be largely self-explanatory. The "--dull" option turns off highlighting in the printed output. The "--quiet" option makes tpctl a bit less verbose. If you want no output at all then pipe the output to /dev/null. Note that at the present time all the options can be given with a single dash. You can give as many different options as you like, including multiple instances of an option with different arguments: e.g., tpctl --rs1=enable --rs1=irq5 option arguments ---------------- Here is an explanation of some of the arguments taken by tpctl options. One of the VGA mode numbers (specifiable either in decimal, '1234', or in hex, '0x567') listed in the file VGA-MODES. (-|S|Z|R|H|O) -: disable S: standby Z: suspend R: safely suspend (RediSafe) H: hibernate O: power off --
:: daily :: d:: '' etc. should be pairs of digits signifying the year-offset (from year 0 of the century), month, day, hour, minute and second of the appointment. Periods can be used instead of hyphens, colons and spaces. A hardware I/O address, e.g., '0x3f8' Usage -- ntpctl =============== The key: means: q - Quit LEFT - previous value (in most cases) RIGHT - next value (in most cases) a - auto h - high (or hibernate) m - manual y - yes (in most cases the same as enable) n - no (in most cases the same as disable) e - enable (in most cases the same as yes) d - disable (in most cases the same as no) s - standby (or sticky) z - suspend r - redisave h - hibernate (or high) o - power off -/0 - nothing RETURN - change timer/value s - sticky (or standby) l - sticky and lock F1 - displays some information about the last SMAPI-BIOS call, which tried to change some configuration. Controlling the pointing devices ================================ The following script allows a Logitech PS/2 wheel mouse to be used together with the TrackPoint. This only works under Linux 2.6 and only works if the PS/2 mouse driver is built as a module (psmouse.ko). #!/bin/sh tpctl --spi=enable sudo rmmod psmouse sudo modprobe psmouse # This initializes the TrackPoint tpctl --spi=disable sudo rmmod psmouse sudo modprobe psmouse # This initializes the wheel mouse tpctl --spi=enable Controlling resources ===================== The best way to control resource configuration is using the lspnp and setpnp utilities in the pcmcia-cs package. tpctl can also report and change the resource assignments to the parallel interface and serial cable and infrared interfaces. NOTE, however, THAT THE --r** OPTIONS CAUSE TPCTL TO TALK DIRECTLY TO HARDWARE. They do not change settings stored in nonvolatile RAM as setpnp can do. Therefore your changes will be lost on reboot. These options have not been tried out on every model of ThinkPad; but at least they have worked fine on a 380Z, a 600 and a 770X. They may or may not work on your model. Some information about the current resource utilization on your ThinkPad can be had by executing: cat /proc/interrupts cat /proc/ioports On my system the interrupts and ioports used by the parallel port driver do not show up until the parallel port has been opened at least once. (I have configured parallel port support as a module.) The "superio" module uses two ioports but they do not appear in /proc/ioports. Example ------- Here is an example of a session in which I first moved my serial port 1 from 0x3e8 irq4 to 0x2f8 irq3, and then enabled serial port 2 at 0x3e8 irq4. Please read the man page for the "setserial" command for more information about that command. On my ThinkPad 600, serial port 1 is connected to the DB-9 on the back of the machine; serial port 2 is connected to the serial infrared interface. (Note that the output of tpctl has changed a bit since I recorded this session. Don't worry about that.) [root@myhost]# setserial /dev/ttyS1 auto_irq autoconfig ; setserial /dev/ttyS2 auto_irq autoconfig ; setserial /dev/ttyS1 ; setserial /dev/ttyS2 ttyS1, UART: unknown, Port: 0x02f8, IRQ: 3 ttyS2, UART: 16550A, Port: 0x03e8, IRQ: 4 [root@myhost]# tpctl --rs1=0x2f8 --rs1=irq3 tpctl: serial port 1 interrupt has been set to IRQ3 tpctl: serial port 1 base address has been set to 0x2f8 resource current state: serial port 1: enabled COM1 0x2f8 IRQ3 [root@myhost]# setserial /dev/ttyS1 auto_irq autoconfig ; setserial /dev/ttyS2 auto_irq autoconfig ; setserial /dev/ttyS1 ; setserial /dev/ttyS2 ttyS1, UART: 16550A, Port: 0x02f8, IRQ: 3 ttyS2, UART: unknown, Port: 0x03e8, IRQ: 4 [root@myhost]# tpctl --rs2=0x3e8 --rs2=irq4 --rs2=enable tpctl: serial port 2 has been enabled tpctl: serial port 2 interrupt has been set to IRQ4 tpctl: serial port 2 base address has been set to 0x3e8 resource current state: serial port 2: enabled COM2 0x3e8 IRQ4 [root@myhost]# setserial /dev/ttyS1 auto_irq autoconfig ; setserial /dev/ttyS2 auto_irq autoconfig ; setserial /dev/ttyS1 ; setserial /dev/ttyS2 ttyS1, UART: 16550A, Port: 0x02f8, IRQ: 3 ttyS2, UART: 16550A, Port: 0x03e8, IRQ: 4 Controlling serial port power ----------------------------- As of tpctl version 2.2, "tpctl --rs1=on" and "tpctl --rs1=off" power the first serial port on or off, respectively. Powering the serial port on or off is not the same thing as enabling or disabling it! To use the serial port it must be both enabled and powered on. (I assume that what one "powers on" is not the UART but the circuits that deliver current to the DB-9 connector.) On my ThinkPad 600, it seems that the serial port power can only be controlled if PS2.EXE or setpnp has previously been used to enable and power on the serial port. YMMV. Clock interference ================== Running tpctl with one of the options implemented by SMAPI can cause the system clock to lose a few milliseconds. As a result, running the apmiser program can cause the system clock to run slowly. The effect is not huge, but you may find it unacceptable for your purposes. Other issues with use ===================== Please see the TROUBLESHOOTING file. 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 a normal user to execute tpctl or ntpctl, so long as he or she doesn't have write permission on the device file. If you are using devfs, you may want to create a "thinkpad" group and set permissions on thinkpad device nodes using a line like the following in your /etc/devfsd.conf file (or for debian, in a /etc/devfs/conf.d/tpctl file): REGISTER thinkpad PERMISSIONS root.thinkpad 0664 Things to do ============ See the ChangeLog file Things done =========== tpctl is similar in function to PS2.EXE, the ThinkPad configuration tool that runs under DOS. One major difference between PS2.EXE and tpctl is that tpctl's changes to hardware configuration (using --r* options) are non-permanent: they revert to their previous settings on reboot. (In contrast, PS2.EXE does change the boot-up settings; and setpnp does so if the '-b' option is given.) This isn't much of a limitation because appropriate tpctl commands can be inserted in one of the initscripts (e.g., /etc/init.d/local in a Debian distro) to effect a quasi-permanent change. Another difference is in the option names. Here is a list of all the PS2.EXE options, plus their tpctl equivalent(s), if any. Also listed are lspnp/setpnp equivalents, if any. Power expenditure control on ThinkPads is complicated. The machine switches power expenditure mode when the power source is switched between line and battery. For each power source, one can select to expend power at a "high", "auto"matic or "manual"ly adjusted rate: PS2.EXE PMODE high AC tpctl --pma=high The _current_ expenditure "rate" can in turn be customized using the "PS2.EXE SPEED" command as follows. This has no tpctl equivalent as of this writing. PS2.EXE SPEED FIXED MAX PS2.EXE SPEED FIXED MEDIUM PS2.EXE SPEED FIXED SLOW PS2.EXE SPEED AUTO MEDIUM PS2.EXE SPEED AUTO SLOW PS2.EXE command or option tpctl option comments --------- ------------- -------- PMODE --pm* SERIAL --rs1=(on|off) but tpctl settings are volatile POWER --ptZ,--pdZ* LCD --ptB DISK --ptd,--pdZ* ON --pra COVER --psl DOCK would be nice SAFE --pmR RI --prs HTIMER --psh TIMER --psZ LBATTERY --psb S2H --psH,--pdH HSWITCH --psp CDSPEED ioctl()s on the cd driver CPUPOWER would be nice SPEED would be nice PCIBUSPOWER would be nice HFILE would be nice, but if you have a FAT (i.e., DOS) partition for the hib file then you also have a place to install PS2.EXE, which only needs to be run once with the "HFILE" option. SCREEN --sd* HVEXPANSION would be nice F8 would be nice BEEP would be nice IRQ lspnp,--rx but tpctl doesn't display *all* IRQs DMA lspnp,--rx but tpctl doesn't display *all* DMAs KRATE would be nice FNSTICKY --sf TPOINT --sp* JSTICK would be nice PARALLEL lspnp|setpnp|tpctl --rp but tpctl settings are volatile SERA lspnp|setpnp|tpctl --rs1 but tpctl settings are volatile IR lspnp|setpnp|tpctl --rs2 but tpctl settings are volatile and can't set dma STARTUP yawn PRESENTATION --pt* PCIIRQ would be nice AUDIO lspnp|setpnp MIDIPORT lspnp|setpnp AUDIOCTRL lspnp|setpnp IDE2 lspnp|setpnp IDE3 lspnp|setpnp IMODEM lspnp|setpnp BRIGHTNESS would be nice FDD would be nice SUSPEND --S actually does standby OFF --Z actually does suspend HIBERNATE --H TURN --O (disabled) actually does power-off