The Linux Trackpoint Utilities

brought to you by Till Straumann,

Last Modified: 1/11/2005

What's new:

Problems with tp4d under Linux 2.6.x

I do not use 2.6 yet but I have received problem reports and a solution for using tp4d under 2.6. The fact that tp4d has been running under 2.2, 2.4 and now 2.6 without modification convinces me that the approach of a user-level tool was good. Under 2.6, however, the /dev/psaux device does not provide direct access to the trackpoint anymore but merely provides a PS2 emulation layer to low-level kernel drivers. This emulation does not know of any special trackpoint commands, of course. Therefore, tp4d is unable to communicate with the hardware. Luckily, a suitable and simple low-level driver can be found here - it provides the hardware access needed by tp4d. No modification to tp4d itself is needed.The psctrl module/device which always has been optional should not be used under 2.6.

Problems with tp4d under Linux 2.4.x

Unfortunately, there are problems with 'tp4d' under linux 2.4.18 (and maybe other 2.4.x kernels - although earlier 2.4 kernels seemed to work). This has recently been brought to my attention and I started looking into it. The real-time scheduling seems to be broken with the consequence that tp4d no longer always wins when competing with the X server for psaux resulting in a communication chaos [:-(] Until I find the reason for this, it makes no sense to port psctrl to 2.4. As a workaround, I recommend the following steps:

Switch to a different virtual console (i.e. 'away from X')
Make sure no other mouse client is running (e.g. 'gpm') either by sending them KILL or STOP signals.
Use 'tp4d' in interactive mode (-i flag) to program the desired settings (there is no need for the psctrl device)
Restart or send CONT to 'gpm' (or other clients)
Switch back to vt7 (X).

Unfortunately, these steps have to be repeated after resuming from sleep mode. Check back the web-page for a new version of tp4d - unfortunately, I am currently quite loaded with work, but I try to fix this ASAP. Sorry for the inconvenience

1/11/2005: added remark about A30p under 2.6.8/SERIO_USERDEV patched under Supported Machines
7/30/2001: added a FAQ section explaining why tp4d can not be used to generate Button4/5 events.

7/30/2001: incorporated minor patches contributed by Soumen Chakrabarti (retry detection sometimes required on A20/A21 machines) and Shinichi Sakata (psctrl / modversions).

5/25/2001: Ported the "psctrl" driver to linux-2.4. It should now compile under 2.2 and 2.4.

3/29/2001: Finally, I had a minute to update this page. The new release 1.0 is finally available.
renamed most of the options to better match their functionality. I tried to adapt the parameter/option descriptions to the real meaning (as defined by the IBM document cited below). Unfortunately, this means that the new release in incompatible with the older ones. Make sure you properly uninstall any old release before using 1_0. (Do 'make uninstall' - note that the utilities do a client vs. server version check automatically at run-time.) The parameter descriptions in xtp4 are also more informative, now.
IMPORTANT: Upgrade any scripts to the new option names or improper settings may result!
tp4d is now capable of reading the hardware settings at startup. Only the settings you explicitely ask for to be changed (by setting command line options) are modified at startup. E.g. the trackpoint keyboard uses completely different modes (Y and Z inversion) than the thinkpads. The new feature makes sure that the default mode is not changed by accident.
7/28/2000: I got a nice email from Barton Smith / IBM telling me where to find information about the trackpoint internals - 1000 thanks. I'll upgrade tp4utils ASAP. Removed the `beta' from the current release. No more barfing against IBM...

7/15/2000: tp4d reported to work on a TP T20 (although a different `secondary firmware id' is reported: 0x0e-0x01).

5/12/2000: Release 0.3_beta is out and believed fairly stable (no new features, the new release fixes the bugs listed below here.

5/11/2000: I finally found the cause of spurious tp4d crashes (not really a crash - the watchdog timed out because it was never started :-). Is fixed in release 0.3.

4/22/2000: resolved the "`tp4d' didn't detach itself into the background" problem encountered with glibc-2.1. This will be fixed in release 0.3.

tp4d reported to work on TP770, TP770ED, TP380Z, TP390E, TP240 machines.

2/15/2000: Please don't use the `-Z' option with release 0_2_alpha. There's a bug reported by Oleg Bartunov which will crash tp4d. Because `-Z' is enabled by default anyway, I feel that it's ok to fix this in the next release. As a workaround, you may use the `-m' option instead. Will be fixed in release 0.3.

What's this about?

Many notebook computers have pointing devices that are attached to the pc_keyboard/ps2_auxiliary port. The generic LINUX driver for the PS2/aux (`psaux') only provides basic support to read/write byte streams from/to this device. Currently (AFAIK), all programs that use the pointing device, such as the XFree86 X-Server or gpm contain driver code that only knows about the features of a generic PS2 compatible 2/3 button mouse.

However, modern pointing devices, such as the IBM Trackpoint ^(R) contained in their ThinkPad computers exhibit more features than a basic PS2 mouse. (This also applies to touchpad devices, see e.g. here). The trackpoint hardware is capable to detect z-axis pressure and hence is inherently a three-dimensional device. Most popular software applications however are not able to deal with 3D mouse input data. On the other hand, the trackpoint hardware supports various ways of mappingz-axis activity to other, essentially mouse button press/release events. Also, the trackpoint hardware has more configurable parameters than the traditional mouse resolution and scale.

The purpose of the software presented here is to make (as many as possible of) these extra features available under the LINUX operating system. IBM has a web-page with very valuable information about the trackpoint internals / software protocols etc - unfortunately, the existence of this page got to my knowledge only relatively late. Nevertheless, thanks to Barton Smith who brought this to my attention.

Frequently Asked Questions

Can tp4d be used to generate Button4 / Button5 events for scrolling?

Many people (including myself) would like to be able to use the trackpoint for scrolling while holding down one of the buttons. Unfortunately, this is not possible, essentially because it's not implemented by the trackpoint hardware. Remember that tp4d was designed for making the trackpoint hardware features available and for saving/restoring hardware settings across suspend/resume cycles.

The trackpoint hardware itself (not the driver) converts z-axis pressure into button presses. However, although it is possible to map the z-axis activity to any combination of Btn1..Btn3 clicks, the hardware is not capable of performing any other kind of mapping (e.g. xy-motion to click conversion is not possible).

Note that what you want is mapping _motion_ events (while Btn2 is pressed) to repeated Btn4/Btn5 clicks (which subsequently are translated [by the Xt translation manager] to scrolling actions in the individual applications [such as xterm, netscape etc.]). Unfortunately, the trackpoint is not capable of doing this kind of mapping. The only way of achieving it would be running the trackpoint in so called "burst" mode, reporting raw x,y,z coordinates. However, this would require a driver implementing all of the z (_and_ x/y) axis handling (sensitivity, "click" detection etc.) that is currently done by the hardware. What you want can (unfortunately only) almost be done by Xt translation tables, i.e. if the translation manager could distinguish between UpwardMotion and DownwardMotion events, you could simply define resources similar to

<Btn2UpwardMotion>: scroll(up)\n\
<Btn2DownwardMotion>: scroll(down)

Alas, this is not possible. Hence, you would (as I already tried to say) need a driver which converts x(t)/y(t)/z(t) [t being the "time" coordinate] to appropriate Btn4/Btn5 events which could be translated by the Xt translation manager into the respective actions. Such a driver could be implemented in the XServer proper

You can also try to get the source code of your most important applications and do tiny modifications to the scrolling action code. You'd have to add two or three lines of code which evaluates the event and distinguishes upward vs. downward motion. Then you could define translations

<Btn2Motion>: scroll()\n

and the action code would know what to do.

Since most scrollbar widgets already do the right thing when you drag the scrollbar around, you also could install scrollbar accelerators to the scrolled window and use properly defined accelerator bindings.

Sorry for not having better advice in this case.

Current Status

Supported Machines

`tp4d' has been reported to work on TP770, TP770ED, TP380Z, TP390E, TP240, TP T20, T21 and A20m machines. The IBM trackpoint keyboard also works. The `reference-platform', i.e. my own computer, where `tp4d' is developed and maintained, is a TP600E (firmware secondary id: 0x0b-0x01)..
I got a report (1/6/05, thanks to Jens Hansen) from a A30p user (2.6.8 with SERIO_USERDEV patch applied) who had problems getting his trackpoint detected. He ended up hacking tp4d (hardcoding his trackpoint ID [0xe] and eliminating the detection step) which got him up and running. I have no access to this hardware and am therefore unable to analyze this further, sorry.

Software Status

The current release, 1.0_beta, is believed to be stable. The previous release 0.3 has been out for many months and I didn't get problem reports (it's still available). I've been running it myself flawlessly for a long time.

The software currently supports:

control trackpoint sensitivity in 2D (x-y directions).
enable / disable `z-axis activity' to `button press / release' mapping; control which buttons are activated by pressing the stick.
enable / disable `press-to-click' feature; when enabled, pressing the trackpoint maps to a button click (of configurable duration). When disabled, pressing the trackpoint maps to a button press, releasing it maps to a button release.
control various parameters that affect z-axis sensitivity (press/release velocity, pressure level).
mirroring / inverting x and y axes, e.g. pulling the trackpoint towards you will move the pointer left :-)

Not (yet) supported:

Burst mode, i.e. sucking `raw z-axis data' out of the device is not supported. It would be useful for dedicated applications - such applications should use /dev/psaux directly, however and there is no point in using 'tp4d'.

Prerequisites

What do you need in order to build / use the trackpoint support software?

a notebook computer with an IBM trackpoint (I own a ThinkPad 600E).
LINUX 2.2 or 2.4 (basic tests only); you should have APM support configured into the kernel.
libapm.a

For the `xtp4' configuration utility which allows for comfortable trackpoint configuration under X11 (as a client of tp4d) you additionally need

the XPM library, libXpm (optional)
the Xaw3d widgets, libXaw3d (required)
unless someone writes a X-server extension using tp4d or driving the trackpoint directly, xtp4 must run on the machine where the server is running [- grin -].

The tp4utils Software Package

tp4d

After discovering the basic commands needed to enable the trackpoint's extra features, I developed a daemon called `tp4d' which provides the following services:

manage a (tiny) database of all current settings. Because many settings can not be read back from the trackpoint device (at least, I dont know how [yet]), a centralized manager is desirable to maintain a cache of the current settings.
restore the cached settings after detection of an APM resume event because all settings are lost when suspending the machine.
listen on a pipe for client requests. Clients may send requests to modify and query the `extra' settings (as well as the plain PS2 mouse parameters).
synchronize access to the one and only psaux hardware device. Normally, the X-Server (or any other application like `gpm') is using the psaux device already. However, the X-Server does not know about driving the trackpoint's extra features (and although it would be possible, e.g. to write a `trackpoint extension' for the X server, it is maybe unwise: other apps like gpm or commercial X-Servers might not be able to use such an extension).

tp4d needs to access the psaux (trackpoint) hardware - possibly concurrently with the X-server. The synchronization problem is not exactly trivial (it would be much easier, if there was some support in the kernel for `hooking' into the psaux driver - ideally, this would be the way to go). I suppose that there are other pointing devices and there may appear more in the future. Therefore, IMHO, the LINUX psaux driver should provide the necessary hooks to add `enhanced-feature driver' modules.

Alas, because I didn't want to patch the kernel (maintaining such a patch would be a nuisance), I had to go all the way. Consult the manpage (and the source code) for more info about implementation issues.

xtp4

xtp4 is an X program that operates as a client to tp4d (which must be running, too). xtp4 offers tickmarks and scrollbars for comfortable manipulation of all configurable (as far as currently known) trackpoint settings as well as a test-area where button events are displayed (button events subsequently wipe out the tp4d logo). The test-area comes handy when you want to study the effect of the various settings.

Click here for a screen-dump.

tp4lib (optional)

is a tiny `library' (which actually consists of one single file) for people that want to write their own clients of tp4d. Note that it is strongly recommended to use this interface rather than communicating directly with tp4d as this makes it possible to hide protocol changes (at least until things settle a bit). Study the header tp4lib.h if you want to write your own client app.

psctrl (optional)

psctrl.o is a kernel module which may optionally be installed. The presence of this module enables tp4d to also do safe write-synchronization of the /dev/psaux device. Because the XFree86 X-Server seldomly writes the mouse device (on init, switching VT and maybe when using xset), this is perhaps not very critical. A typical scenario of a race condition that is avoided by using the psctrl device can be described as follows:

Just while an APM resume cycle is in progress, you switch to virtual console 7 (where the X-Server is running). In this case, it would be possible that the server's write commands get intermixed with tp4d's which could lead to incorrect settings and/or a `dead' mouse.

The use of the psctrl device is further discussed in the tp4d manpage and the README.

Note that tp4d automatically finds out if the psctrl device is present or not. There is no need for any compile- or run-time options.

Useful Hint

If you ever happen to completely mess up the trackpoint settings (even if you only tried out the x/y axis swapping it may be difficult to place the pointer to the `restore' button...), simply suspend and resume the machine. This will bring back the power-on (bare PS2 mouse) settings. However, make sure to switch to another virtual console and kill `tp4d' before suspending - remember that `tp4d' was designed to restore the settings after resuming.

Download

the source tarball.
(the old release 0_3).
view the online manpage of tp4d or xtp4.
view the installation README

Licensing

The tp4utils package is released under the terms of the GPL (for more information about GPL).

Feedback

Please, don't hesitate to contact me for any kind of feedback: new things that you figured out about the trackpoint and, of course, questions / problems / suggestions...

PLEASE GIVE ME FEEDBACK about tp4d (not) working on other machines (than the TP600E).

Other Useful Resources

Kenneth Harker's Linux Laptop Homepage.
Thomas Hood's TP600 and tpctl (ThinkPad configuration tool under linux) pages.