Getting Started Linux Keyboard drivers

Please note: this description refers to the keyboard and mouse drivers for the TWIRP receiver, PS2Adapt and HD64465 PS/2 ports, which were introduced in the 0.4 release. These techniques will not work on the older drivers.

Currently we support three different keyboard types under Linux for the SuperH:

• Keyboards which use the TWIRP Infra Red protocol, using the TWIRP receiver dongle which plugs into a standard serial port. For more details see the TWIRP web site.
• PS/2 keyboards and mice plugged into the Semtech PS2adapt PS/2 to serial protocol interpreter (part number UR6HCPS2-SP40), connected to a standard serial port. An evaluation kit for this device is available with the part number EVK6-PS2-SP40-XXX. This chip was originally produced by a company called USAR, who were taken over by Semtech Corp. in 1999, and are now known as Semtech's Human Interface Device (HID) Division. For more details see the Semtech HID web site.
• A PS/2 keyboard and mouse driven using an Hitachi HD64465 peripheral support device. This is available on the STMicroelectronics ST40STB1 Overdrive and HARP platforms. Linux configuration option CONFIG_SH_HD64465_PS2.

Device drivers for the HD64465 PS/2 ports must be linked into the Linux kernel, and should be pre-configured in any LSP where the hardware supports it.

Device drivers for the TWIRP receiver and PS2Adapt keyboards/mice are provided in the form of loadable kernel modules, and so need to be loaded into the kernel, before they can be bound to the appropriate serial port using the inputattach command. For example, to use a TWIRP receiver attached to serial port /dev/ttySC1 simply execute:

insmod twirp
inputattach --twirp /dev/ttySC1

If using the PS2adapt simply replace twirp with ps2adapt in both commands.

You are now ready to test that the keyboard is working. The easiest way to do this is to use the command:

cat < /dev/tty0

Anything typed on the keyboard should be echoed to the screen. Note that by default the console will be in line mode, so nothing will appear until you hit the return key.

Similarly mice can be tested using the command:

od -x /dev/mouse

and you should see a stream of hex numbers when the mouse is moved or the buttons clicked a few times.

Kernel configuration

The support for the PS2adapt and TWIRP keyboards is built on top of the Linux Input Drivers support. This is gradually being integrated into the kernel, as the way in which all keyboards and mice will be supported in the future.

To add the support these drivers need into the kernel, a number of options have to be enabled. First enable "Input core support" (CONFIG_INPUT) and "Keyboard support" (CONFIG_INPUT_KEYBDEV) and "Mouse support" (CONFIG_INPUTMOUSEDEV) as required. Next (and bizarly) you need to go to the "Joysticks" menu in the "Character devices" section, and finally enable "Serial port device support" (CONFIG_INPUT_SERIO) and "Serial port input line discipline" (CONFIG_INPUT_SERPORT).

Other commands

There are a large number of other commands associated with keyboards, which accommodate different keyboards, languages, and user customisation. This gives a brief overview of what can be done, but assumes a reasonable understanding of how keyboards are driven by Linux. For more details check out this document I wrote when implementing the keyboard drivers on how keyboards work or The Linux keyboard and console HOWTO.

First a couple of useful tools for seeing what is going on:

• showkey displays the codes that a key generates when it is pressed or released:
  • showkey --scancodes shows the scancodes generated by the keyboard controller.
  • showkey --keycodes shows the keycodes generated by the Linux kernel from the scancodes, and which gives each key a unique number.
  • showkey --keymap shows the effects of the current keyboard translation table (also called the keymap). This handles modifier and compose keys, and other actions such as switching virtual consoles.
• xev is an X application which shows the X events sent by the Xserver to an application. When a key is pressed or released in the xev window, xev will show the key's keycode (the unique number X assigns to each key), and the state of any modifiers currently pressed. Together these allow the X library to display the keysym (the symbol which X thinks that key has engraved on it, taking into account the modifiers).

Most of these mappings are programmable, and utility programs are provided to change the mappings:

• For the low level keyboard mapping, from scancode to keycode the utility getkeycodes shows the current mapping, while setkeycodes can be used to modify this map.
• The keyboard translation table (or keymap) describes what the Linux console should do when a certain key in pressed in conjunction with any modifier keys (such as Shift or Alt). Actions are normally to generate one or more characters on the console's input, but can also be things like switching to a different virtual console. The keymap can be printed in various formats using the dumpkeys utility, and modified using loadkeys.
• Finally X programs map keycodes to keysyms using a mapping called the keymap. This mapping can be updated using the xmodmap program.

Most of the console utilities are provided in the package console-tools.

Note that the Linux kernel keycode and the X keycode will usually be different. Yes, there is yet another mapping going on within the X server from Linux kernel keysyms to X keysyms. This mapping is fixed, and fairly arbitrary.

One area which typically causes problems is non-standard keys which are provided on some keyboards. For example the TWIRP keyboard provides a top row of keys which are useful in audio/visual applications. However by default the keys won't do anything because they are not mapped correctly.

First we need to find out what scancode the key generates:

host% showkey --scancode
press any key (program terminates after 10s of last keypress)...
0xe0 0x32 0xe0 0xb2

Next we need to find what of any keycode is generated for this scancode:

host% getkeycodes
...
Escaped scancodes e0 xx (hex)
...
e0 30:    0   0   0   0   0  98   0  99
e0 38:  100   0   0   0   0 113 114 115

This shows that scancode e0 32 is currently bound to keycode 0, which actually means it is not bound at all. So the next thing to do is find a free keycode. Normally keycodes 89-95, 112-118 and 120-127 are used for `unusual' keys, although codes 125-127 are used for the three Windows keys, which can probably be regarded as normal now. So if we use pick code 89, this can be bound to the key using:

setkeycodes e032 89

Next if we want to use the key in a console application, the key has to be bound to an action. The easiest way to do this is to pretend the key is a function key, and get it to generate an escape sequence. First we need to get a copy of the current keymap:

host% dumpkeys > /tmp/keymap

Then modify the keymap so that the keycode is bound to a function key, and the function key generates a string:

keycode 89 = F100
string F100 = "Hello"

And finally load the keymap into the kernel:

host% loadkeys /tmp/keymap

If you want to use the key from inside an X application, the process is very similar. As before you need to use setkeycodes to map the scancode to a keycode, and then fire up X and use xev to find out what keycode X has assigned to the key. If you want to use this key from within an existing application, then the key will have to be entered into the keymap using xmodmap, however if it is only going to be used from within your own application, simply check for that keycode in XKeyPressedEvent and XKeyReleasedEvent type events.