                         README file for
                              tpctl
              ThinkPad configuration tools for Linux


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

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

thinkpad.o, smapi.o, superio.o and rtcmosram.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/thinkpad
named like itself which contains some information about the module.

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

tpctl is a console interface to the modules.

ntpctl is an ncurses interface to the modules.

The "other_tools" directory contains some other tools that may be useful
to you depending on which ThinkPad you have.  Each one is compiled and
installed separately.  Just cd to the subdirectory, read the README
there and execute "make all ; make install" to install.


Requirements
============

Hardware
--------

Not all ThinkPad models have all the hardware and software required for
all tpctl functions to work.  So far, tpctl has been found to be fully
functional with:
	365XD, 380D, 380XD, 380Z, 560E, 560X, 570, 600, 600E, 600X
	760E, 760ED, 760XD, 770, 770E, 770ED, 770X, 770Z

The following ThinkPad models lack the SMAPI BIOS, but
the --ic and --r* options may still work:
	750P, all i-series models


Kernel
------
Kernel 2.2.0 or higher


Software
--------
The "ncurses-devel" package 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
============

To install from the source tarball:
	tar zxvf tpctl-<ver>.src.tar.gz
	cd tpctl-<ver>
	make all
	make install
You may want to follow this with:
	make clean
which deletes the binaries from the source directory.

To uninstall, see the section below.

tpctl and ntpctl are installed in /usr/local/bin, loadable kernel
modules thinkpad.o, smapi.o, superio.o and rtcmosram.o in
/lib/modules/<running.kernel.version>/thinkpad, and library
libsmapidev.so in /usr/local/lib.

The installation process:
*) adds a path statement and an alias to /etc/modules.conf or to
   /etc/conf.modules ;
*) adds the path "/usr/local/lib" to the linker configuration file
   /etc/ld.so.conf if it is not already there;
*) creates character device file /dev/thinkpad with major 10 minor 170;
*) deletes any previous versions of tpctl-related files that it finds.

The /etc/modules.conf or /etc/conf.modules file should contain the
following line so that the thinkpad module will be loaded when needed
by tpctl.
	alias char-major-10-170 thinkpad

The thinkpad module takes care of loading other modules when they are
required.


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

To remove all installed tpctl files:
	make uninstall

Note that this removes /lib/modules/<running.kernel.version>/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
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/<module_name> contains information about the status
of each of the modules.


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.

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

For a comparison of PS2.EXE and tpctl options, see the TODO file.

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>  or
daily:<HH>:<MM>:<SS>  or  d:<HH>:<MM>:<SS>
	'<SS>' etc. should be pairs of digits signifying the year, month,
	day, hour, minute and second of the appointment.

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

NOTE THAT THE --r** OPTIONS CAUSE TPCTL TO TALK DIRECTLY TO HARDWARE.
They do not change settings stored in nonvolatile RAM.  Therefore your
changes will be lost on power-off.

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 not
work on your machine.

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

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

	[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


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

Please see the TROUBLESHOOTING file.


Security
========

The user requires write permission on the thinkpad device file (normally
/dev/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.


Development
===========

I would like to enhance tpctl so that it can do everything that
PS2.EXE can do under DOS, and that the ThinkPad Configuration
Utility can do under Windows.  See the TODO file for what remains
to be done.


References
==========

In writing the code I found the following documentation helpful.

------------------------------------------------------------------------

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.

------------------------------------------------------------------------

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 is really superb.


Bugs and other issues
=====================

For the time being, please read the source for more information
or contact the author, Thomas Hood, at jdthood@mail.com .


--
Thomas Hood
31 December 1999
