                         README file for
         tpctl -- ThinkPad configuration tools for Linux

Last updated: 14 Nov 2001

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

Execute
	man ./tpctl.1
to see the tpctl man page.

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.  Please
see the README file for the thinkpad device drivers for more information.

libsmapidev.o is a library of functions that can be used to access
(some of) the features of the SMAPI BIOS via the smapi.o module.

tpctl is a console interface to the modules.

ntpctl is an ncurses interface to the modules.

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.

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.


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.

Kernel
------

The 1.x releases of tpctl support Linux kernel 2.2.x .
The 2.x releases of tpctl support Linux kernel 2.4.x .


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
============

If you are using Debian the simplest thing to do is install the latest
tpctl deb.  Otherwise install from the tarball.

To install from the source tarball do the following.

First install the thinkpad drivers.  See the README file for that package
for installation instructions.

Do:
	tar zxvf tpctl-<ver>.src.tar.gz
	cd tpctl-<ver>
	make all

To install the files do the following.
	make install
tpctl and ntpctl are installed in /usr/bin.  The library libsmapidev.so.1
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.

Add the following to /etc/modules.conf (or for Debian, to a file
/etc/modutils/tpctl, or for RedHat, to the file /etc/conf.modules):
   keep
   path[thinkpad]=/lib/modules/`uname -r`/thinkpad
   options thinkpad enable_smapi=1 enable_superio=1 enable_rtcmosram=1 enable_thinkpadpm=1
   alias char-major-10-170 thinkpad
   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 then run the "depmod -a" command as root.  The "keep" line only needs
to be added if it does not already appear earlier in the file.

The package is now installed.


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

To remove all installed tpctl files:
	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.

<VGA-mode-#>
	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

<yy>-<mm>-<dd> <hh>:<mm>:<ss>
daily <hh>:<mm>:<ss>
d<hh>:<mm>:<ss>
	'<yy>' 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.

<port>
	A hardware I/O address, e.g., '0x3f8'


Usage -- ntpctl
===============

The key:	means:
        q 	- Quit

        LEFT	- previos 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
================================

If you boot with the internal pointing device in "auto-disable" mode then
the TrackPoint will not work when you start X.  However on my ThinkPad 600
I can "tpctl --spi=enable" prior to starting X windows and this allows use
of both external and internal pointing devices.  

You may want to stick with auto-disable mode if you have a wheel mouse,
however: the wheels on some wheel mice work with X windows, but only if
the TrackPoint is disabled.  Please let me know if you manage to get
a wheel-mouse wheel working simultaneously with the TrackPoint!


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.


Other issues with use
=====================

Please see the TROUBLESHOOTING file.


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 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.

Power expenditure control on the ThinkPad is complex.  The machine
switches expenditure modes when switched between AC and battery power 
sources.  For each power source, one can select "high", "auto" or
"manual" ("custom") power expenditure [e.g., "PS2.EXE PMODE high AC"
or "tpctl --pma=high"].  The current expenditure mode can itself be
customized, however, using the "PS2.EXE SPEED" command, which has no
tpctl equivalent as of this writing.

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

