                         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_<ver>.src.tar.gz
	cd tpctl-<ver>
	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.

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

