TROUBLESHOOTING file for
                              tpctl

Last updated: 22 October 2001

Note that the exact wording of many of these messages has changed,
but the explanations and solutions still apply.


Error message:
	tpctl: module required for request is not enabled
Explanation:
	Perhaps the thinkpad module was loaded with one of the services
	disabled (e.g., "insmod thinkpad enable_superio=0").
Solution:
	Re-enable it.
Explanation:
	Since thinkpad.o requests that other modules be loaded as they
	are required, this message means either that the module cannot
	be found by modprobe, or that the module failed initialization.
	Try insmod'ing the service module manually, e.g., 
		cd /lib/modules/thinkpad
		insmod superio
	and if you get an error message then the problem is probably that
	your model of thinkpad is incompatible with that module.
Solution:
	Don't use that tpctl option.

Error message:
	Segmentation fault
Explanation:
	Segmentation faults can occur for a variety of reasons, but here
	is one scenario.  Sometimes, for obscure reasons, the loadable kernel
	module "thinkpad.o" is not automatically loaded by the kernel when it
	is needed.
Solution:
	modprobe thinkpad
	Then retry the tpctl command that caused the segfault.

Error message:
	tpctl: error in loading shared libraries: libsmapidev.so:
	cannot open shared object file: No such file or directory.
Solution:
	Make sure libsmapidev is in /usr/lib, or at least on your
	library search path as set in /etc/ld.so.conf.  Run "ldconfig".

Error message:
   /lib/modules/thinkpad/thinkpad.o: kernel-module version mismatch:
   /lib/modules/thinkpad/thinkpad.o was compiled for kernel version 2.2.10
   while this kernel is version 2.2.5.
Explanation:
	Even when compiled with MODVERSIONS, modules compiled for one
	kernel version are rarely compatible with other kernel versions.
Solution:
	Recompile the modules.

Error message:
	/lib/modules/thinkpad/thinkpad.o: unresolved symbol(s)
Solution #1:
	This may be nothing to worry about.  Try running tpctl anyway.
	If you get an error message, try the previous solution suggestion.
Solution #2:
	Make sure that the kernel source tree that is present at
	/lib/modules/`uname -r`/build when you build tpctl is the
	source for the kernel into which you want to load the modules.

Error message:
	tpctl: Can't open device file: /dev/thinkpad with flags 0x2
Explanation:
	You need write permission on /dev/thinkpad (or /dev/thinkpad/thinkpad
	if you're using devfs) in order to change the system configuration.
Solution:
	Use "chmod" to change the permissions.  If you are using devfs,
	configure devfsd to do this for you automatically.  See the
	README file.

Error message:
	insufficient permission for request
Explanation:
	You need to open /dev/thinkpad (or /dev/thinkpad/thinkpad if you are
	using devfs) with write flags in order to perform the action you are
	contemplating.  If you get this message in tpctl it means that there
	is a bug in the program, because tpctl should always try to open
	/dev/thinkpad for writing when it needs to.

Problem:
	The setting does not change when set, even though tpctl reports that
	it has been set
Explanation 1:
	tpctl reports error messages that are returned by the SMAPI
	BIOS.  For some requests the BIOS returns no error code, yet does
	not change the setting.  In most cases this is because the setting
	cannot be changed on one's particular model of ThinkPad.
Note:
	If a timer-initiated sedation event cannot be changed using --ps*,
	it may be {en|dis}ableable using --pt*.
Explanation 2:
	However, we cannot rule out the possibility that there is a bug in
	the program.  If you find one, please report it to the author.

Error message:
	Warning: value being converted from BCD format is not a valid BCD number
Explanation:
	This means that some ThinkPad memory address that is supposed to contain
	a binary-coded-decimal number happens to contain a value that is not BCD.
	If this warning appears when printing the resume appointment then simply
	set the appointment to some date.  Choose a date in the past if you don't
	really want to set an appointment.

Problem:
	"tpctl --suspend" doesn't work
	"tpctl --hibernate" doesn't work
	"tpctl --hibernate" results in "system is invalid" message
Explanation:
	tpctl sedation requests and those from the keyboard are treated
	by the system as "system suspends", unlike requests from the 
	apm program which are treated as "user suspends".  The BIOS
	sees system requests before Linux does, and so Linux doesn't
	have a chance to do things like eject PCMCIA cards before
	the BIOS looks to see whether or not the suspend can go ahead.
	The BIOS will reject the suspend or hibernate request under
	certain conditions, such as when there is a network card in a
	PCMCIA slot and the machine is on AC power.
Solution 1:
	Try "apm --suspend" instead.  apm --suspend calls the Linux apm
	driver, which calls callback functions and executes apmd proxy
	scripts before telling the BIOS about the request.  If your
	scripts are set up correctly, e.g., so that PCMCIA cards are
	ejected on suspend, then by the time the BIOS is called the
	machine should be cleared to suspend.  The apm program does not
	support hibernation at present.
Solution 2: Try "cardctl eject"ing the PCMCIA card
Solution 3: Try killing esd or kaudioserver if it is running.
Solution 4: Try disconnecting the power cord.

Problem:
	sedation (i.e., standbyifying, suspending or hibernating) doesn't
	work at all
Solution:
	Try recompiling your kernel with CONFIG_APM_ALLOW_INTS=y

Problem:
	I enable the serial port but "setserial" doesn't detect the UART.
Explanation:
	I don't know why, but the serial ports just aren't recognized at every
	possible io address.  If the port is not recognized at *any* address
	then it may be that the port is powered down.  If it is powered down
	then "enabling" it is not enough; it has to be switched on.  Use the
	ThinkPad Configuration for Windows or PS2.EXE ("PS2 SER ON") to do
	this.

Error message:
	When you attempt "tpctl --pdx" on a ThinkPad 570 you get:
		...
		tpctl: SMAPI BIOS error 0x81 ("invalid parameter") -- exiting.
Explanation:
	The TP570 has a buggy SMAPI BIOS that returns spurious
	error codes.
Solution:
	Go into the tpctl subdirectory and, in the Makefile, add
	"-DTP570_KLUDGE" to the CFLAGS.  Remake and reinstall.

Error message:
	tpctl: /dev/thinkpad is a directory, not a device file.
Explanation:
	You are using devfs and thinkpad device drivers version 3.0 or
	later, which are accessed through device files under _directory_
	/dev/thinkpad instead of through _device_file_ /dev/thinkpad.
	Versions of tpctl prior to 3.0 don't know about this.
Solution 1: Get tpctl version 3.0 or later.
Solution 2: Give the "--device=/dev/thinkpad/thinkpad" option to tpctl.

Error message:
	tpctl: System error message is: Permission denied
	tpctl: Can't open device file /dev/thinkpad with flags O_RDWR.  Exiting.
Explanation 1:
	Maybe the driver modules aren't loaded.  If your system is configured
	properly, they should be loaded automatically by the kernel or devfsd.
Solution 1: See the README for configuration instructions.
Explanation 2:
	Maybe /dev/thinkpad (or, if you're using devfs, the files under the
	directory of the same name) has its permission bits set such that
	you can't read or write to it.
Solution 2a: Change the permissions.
Solution 2b: Make sure that you are a member of the "thinkpad" group.
Solution 2c: If you are using devfs, configure devfsd to set the appropriate
	     permissions.
Explanation 3:
	Maybe you are using devfs and have configured devfsd as described in
	the README file, but you have forgotten to start devfsd.
Solution 3: Start devfsd.

--
Thomas Hood